@dotcom-tool-kit/parallel 1.0.0

package/.toolkitrc.yml

@@ -0,0 +1,4 @@
+version: 2
+
+tasks:
+  Parallel: './lib/tasks/parallel'

package/lib/tasks/parallel.d.ts

@@ -0,0 +1,22 @@
+import { Task, TaskRunContext } from '@dotcom-tool-kit/base';
+import { z } from 'zod';
+declare const ParallelSchema: z.ZodObject<{
+    tasks: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>, "many">;
+    onError: z.ZodDefault<z.ZodUnion<[z.ZodLiteral<"stop-all">, z.ZodLiteral<"wait-for-others">]>>;
+}, "strip", z.ZodTypeAny, {
+    tasks: Record<string, Record<string, unknown>>[];
+    onError: "stop-all" | "wait-for-others";
+}, {
+    tasks: Record<string, Record<string, unknown>>[];
+    onError?: "stop-all" | "wait-for-others" | undefined;
+}>;
+export { ParallelSchema as schema };
+export default class Parallel extends Task<{
+    task: typeof ParallelSchema;
+}> {
+    taskInstances: Task<any>[];
+    run(context: TaskRunContext): Promise<void>;
+    stop(): Promise<void>;
+    assertUnreachable(label: string, value: never): asserts value is never;
+}
+//# sourceMappingURL=parallel.d.ts.map

package/lib/tasks/parallel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel.d.ts","sourceRoot":"","sources":["../../src/tasks/parallel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAE5D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,QAAA,MAAM,cAAc;;;;;;;;;EAsClB,CAAA;AAEF,OAAO,EAAE,cAAc,IAAI,MAAM,EAAE,CAAA;AAEnC,MAAM,CAAC,OAAO,OAAO,QAAS,SAAQ,IAAI,CAAC;IAAE,IAAI,EAAE,OAAO,cAAc,CAAA;CAAE,CAAC;IACzE,aAAa,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,CAAK;IAEzB,GAAG,CAAC,OAAO,EAAE,cAAc;IAsD3B,IAAI;IAWV,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,KAAK;CAKvE"}

package/lib/tasks/parallel.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.schema = void 0;
+const base_1 = require("@dotcom-tool-kit/base");
+const logger_1 = require("@dotcom-tool-kit/logger");
+const zod_1 = require("zod");
+const tasks_1 = require("dotcom-tool-kit/lib/tasks");
+const error_1 = require("@dotcom-tool-kit/error");
+const ParallelSchema = zod_1.z.object({
+    tasks: zod_1.z.array(zod_1.z.record(zod_1.z.record(zod_1.z.unknown()))),
+    onError: zod_1.z.union([zod_1.z.literal('stop-all'), zod_1.z.literal('wait-for-others')]).default('wait-for-others')
+}).describe(`Run Tool Kit tasks in parallel
+
+### Task options
+
+#### \`tasks\`
+
+An array listing the tasks to run in parallel, and the options to run each task with. Each element in the array is an object with a single key and value; the key is the name of the task to run, and the value is the options object for that task. Other tasks' options are documented in their plugin's readme.
+
+##### Example
+
+~~~yaml
+commands:
+  run:local:
+    - Parallel:
+        tasks:
+          - Node:
+              entry: server/index.js
+          - Webpack:
+              watch: true
+~~~
+
+#### \`onError\`
+
+_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 -->
+`);
+exports.schema = ParallelSchema;
+class Parallel extends base_1.Task {
+    taskInstances = [];
+    async run(context) {
+        const tasks = this.options.tasks.flatMap((entry) => Object.entries(entry).map(([task, options]) => ({ task, options, plugin: this.plugin })));
+        this.logger.info(`running tasks in parallel:
+${tasks
+            .map((task) => `  - ${logger_1.styles.task(task.task)} ${logger_1.styles.dim(`(with options ${logger_1.styles.code(JSON.stringify(task.options))})`)}`)
+            .join('\n')}
+`);
+        this.taskInstances = (await (0, tasks_1.loadTasks)(this.logger, tasks, context.config)).unwrap('tasks are invalid!');
+        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;
+            }
+            case 'wait-for-others': {
+                const errors = [];
+                await Promise.all(this.taskInstances.map((task) => task.run(context).catch((error) => {
+                    errors.push({
+                        task: task.id,
+                        error
+                    });
+                })));
+                if (errors.length > 0) {
+                    (0, tasks_1.handleTaskErrors)(errors, context.command);
+                }
+                break;
+            }
+            default: {
+                this.assertUnreachable('Parallel.options.onError', this.options.onError);
+            }
+        }
+    }
+    async stop() {
+        await Promise.all(this.taskInstances.map((task) => task.stop().catch((error) => {
+            this.logger.warn(`error stopping ${logger_1.styles.task(task.id)}:
+${error.message}`);
+        })));
+    }
+    assertUnreachable(label, value) {
+        const error = new error_1.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;
+    }
+}
+exports.default = Parallel;

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@dotcom-tool-kit/parallel",
+  "version": "1.0.0",
+  "description": "",
+  "main": "lib",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "FT.com Platforms Team <platforms-team.customer-products@ft.com>",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/financial-times/dotcom-tool-kit.git",
+    "directory": "plugins/parallel"
+  },
+  "bugs": "https://github.com/financial-times/dotcom-tool-kit/issues",
+  "homepage": "https://github.com/financial-times/dotcom-tool-kit/tree/main/plugins/parallel",
+  "files": [
+    "/lib",
+    ".toolkitrc.yml"
+  ],
+  "engines": {
+    "node": "20.x || 22.x"
+  },
+  "volta": {
+    "extends": "../../package.json"
+  },
+  "peerDependencies": {
+    "dotcom-tool-kit": "^4.8.1"
+  },
+  "dependencies": {
+    "@dotcom-tool-kit/base": "^1.3.0",
+    "zod": "^3.25.67"
+  }
+}

package/readme.md

@@ -0,0 +1,65 @@
+# @dotcom-tool-kit/parallel
+
+This plugin allows you to run Tool Kit tasks in parallel. By default, Tool Kit tasks run sequentially in the order they are specified in a command.
+
+## Installation
+
+Install `@dotcom-tool-kit/parallel` as a `devDependency` in your app:
+
+```sh
+npm install --save-dev @dotcom-tool-kit/parallel
+```
+
+Add the plugin to your [Tool Kit configuration](https://github.com/financial-times/dotcom-tool-kit/blob/main/readme.md#configuration):
+
+```yaml
+plugins:
+	- '@dotcom-tool-kit/parallel'
+```
+
+## Usage
+
+To run tasks in parallel, pass them in as the `tasks` option to the [`Parallel` task](#parallel).
+
+<!-- begin autogenerated docs -->
+## Tasks
+
+### `Parallel`
+
+Run Tool Kit tasks in parallel
+
+#### Task options
+
+##### `tasks`
+
+An array listing the tasks to run in parallel, and the options to run each task with. Each element in the array is an object with a single key and value; the key is the name of the task to run, and the value is the options object for that task. Other tasks' options are documented in their plugin's readme.
+
+###### Example
+
+~~~yaml
+commands:
+  run:local:
+    - Parallel:
+        tasks:
+          - Node:
+              entry: server/index.js
+          - Webpack:
+              watch: true
+~~~
+
+##### `onError`
+
+_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 -->
+
+<!-- end autogenerated docs -->