refactor: rename stopOnError to onError and change to a literal union

so we can expand the possible values later

Author: apaleslimghost

plugins/parallel/readme.md

@@ -51,9 +51,18 @@ commands:
               watch: true
 ~~~
 
-##### `stopOnError`
+##### `onError`
 
-An optional `boolean`, defaulting to `false`. If `true`, when one of the parallel tasks throws an error, `Parallel` will stop the other tasks. This is useful for long-running tasks, e.g. a Node server and Webpack in `watch` mode, where one task erroring means you don't have everything running that you'd expect. If you're using `Parallel` to run shorter tasks in parallel as an optimisation, keep this as the default `false` so every task runs to completion and Tool Kit can show the final results of all the tasks.
+_optional_
+
+| Value | Description |
+|-|-|
+| `'wait-for-others'` (default) | If any task errors, wait for the other tasks to complete, and print all the errors at the end. |
+| `'stop-all'` | If any task errors, immediately stop the other tasks, and print the error. |
+
+For long-running tasks, e.g. a Node server and Webpack in `watch` mode, it's possible for one task to error, but its error logging to be buried by the other tasks' output, meaning you might have missed an error and aren't aware that not everything you expect to be running is still running. In these cases, set `onError: stop-all`; Tool Kit will exit every `Parallel` task if one of them errors, so you're always in a consistent state and don't miss any errors.
+
+If you're using `Parallel` to run shorter tasks in parallel as an optimisation, keep this as the default `wait-for-others` so every task runs to completion and Tool Kit can show the final results of all the tasks.
 
 <!-- hide autogenerated schema docs -->
 

plugins/parallel/src/tasks/parallel.ts

@@ -4,10 +4,11 @@ import { z } from 'zod'
 import { type ErrorSummary, handleTaskErrors, loadTasks } from 'dotcom-tool-kit/lib/tasks'
 import { ValidConfig } from '@dotcom-tool-kit/config'
 import type { WritableDeep } from 'type-fest'
+import { ToolKitError } from '@dotcom-tool-kit/error'
 
 const ParallelSchema = z.object({
   tasks: z.array(z.record(z.record(z.unknown()))),
-  stopOnError: z.boolean().default(false)
+  onError: z.union([z.literal('stop-all'), z.literal('wait-for-others')]).default('wait-for-others')
 }).describe(`Run Tool Kit tasks in parallel
 
 ### Task options
@@ -29,9 +30,18 @@ commands:
               watch: true
 ~~~
 
-#### \`stopOnError\`
+#### \`onError\`
 
-An optional \`boolean\`, defaulting to \`false\`. If \`true\`, when one of the parallel tasks throws an error, \`Parallel\` will stop the other tasks. This is useful for long-running tasks, e.g. a Node server and Webpack in \`watch\` mode, where one task erroring means you don't have everything running that you'd expect. If you're using \`Parallel\` to run shorter tasks in parallel as an optimisation, keep this as the default \`false\` so every task runs to completion and Tool Kit can show the final results of all the tasks.
+_optional_
+
+| Value | Description |
+|-|-|
+| \`'wait-for-others'\` (default) | If any task errors, wait for the other tasks to complete, and print all the errors at the end. |
+| \`'stop-all'\` | If any task errors, immediately stop the other tasks, and print the error. |
+
+For long-running tasks, e.g. a Node server and Webpack in \`watch\` mode, it's possible for one task to error, but its error logging to be buried by the other tasks' output, meaning you might have missed an error and aren't aware that not everything you expect to be running is still running. In these cases, set \`onError: stop-all\`; Tool Kit will exit every \`Parallel\` task if one of them errors, so you're always in a consistent state and don't miss any errors.
+
+If you're using \`Parallel\` to run shorter tasks in parallel as an optimisation, keep this as the default \`wait-for-others\` so every task runs to completion and Tool Kit can show the final results of all the tasks.
 
 <!-- hide autogenerated schema docs -->
 `)
@@ -62,30 +72,38 @@ ${tasks
       await loadTasks(this.logger, tasks, context.config as WritableDeep<ValidConfig>)
     ).unwrap('tasks are invalid!')
 
-    if (this.options.stopOnError) {
-      try {
-        await Promise.all(this.taskInstances.map((task) => task.run(context)))
-      } catch (error) {
-        this.stop()
-
-        throw error
+    switch (this.options.onError) {
+      case 'stop-all': {
+        try {
+          await Promise.all(this.taskInstances.map((task) => task.run(context)))
+        } catch (error) {
+          this.stop()
+          throw error
+        }
+        break
       }
-    } else {
-      const errors: ErrorSummary[] = []
-
-      await Promise.all(
-        this.taskInstances.map((task) =>
-          task.run(context).catch((error: Error) => {
-            errors.push({
-              task: task.id,
-              error
+      case 'wait-for-others': {
+        const errors: ErrorSummary[] = []
+
+        await Promise.all(
+          this.taskInstances.map((task) =>
+            task.run(context).catch((error: Error) => {
+              errors.push({
+                task: task.id,
+                error
+              })
             })
-          })
+          )
         )
-      )
 
-      if (errors.length > 0) {
-        handleTaskErrors(errors, context.command)
+        if (errors.length > 0) {
+          handleTaskErrors(errors, context.command)
+        }
+
+        break
+      }
+      default: {
+        this.assertUnreachable('Parallel.options.onError', this.options.onError)
       }
     }
   }
@@ -100,4 +118,10 @@ ${error.message}`)
       )
     )
   }
+
+  assertUnreachable(label: string, value: never): asserts value is never {
+    const error = new ToolKitError(`Unexpected value for ${label}, received ${value}`)
+    error.details = 'This should never happen! Talk to #cp-platforms-team, something weird af is going on'
+    throw error
+  }
 }