in-parallel-lit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Joel Voss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# in-parallel-lit
+
+A CLI tool to run multiple processes in parallel.
+
+## Requirements
+
+- [Node v16+][install-node]
+
+## Installation
+
+```bash
+$ npm i -g in-parallel-lit
+# or
+$ yarn global add in-parallel-lit
+```
+
+## Usage
+
+```bash
+$ npx in-parallel "ping google.com -c 3" "ping 127.0.0.1 -c 3"
+
+# Prints:
+# -------
+# [ping 127.0.0.1 -c 3] PING 127.0.0.1 (127.0.0.1): 56 data bytes
+# [ping 127.0.0.1 -c 3] 64 bytes from 127.0.0.1: icmp_seq=0 ttl=64 time=0.044 ms
+# [ping google.com -c 3] PING google.com (142.250.181.238): 56 data bytes
+# [ping google.com -c 3] 64 bytes from 142.250.181.238: icmp_seq=0 ttl=56 time=30.401 ms
+# [ping 127.0.0.1 -c 3] 64 bytes from 127.0.0.1: icmp_seq=1 ttl=64 time=0.037 ms
+# [ping google.com -c 3] 64 bytes from 142.250.181.238: icmp_seq=1 ttl=56 time=50.207 ms
+# [ping 127.0.0.1 -c 3] 64 bytes from 127.0.0.1: icmp_seq=2 ttl=64 time=0.188 ms
+# [ping 127.0.0.1 -c 3] 
+# [ping 127.0.0.1 -c 3] --- 127.0.0.1 ping statistics ---
+# [ping 127.0.0.1 -c 3] 3 packets transmitted, 3 packets received, 0.0% packet loss
+# [ping 127.0.0.1 -c 3] round-trip min/avg/max/stddev = 0.037/0.090/0.188/0.070 ms
+# [ping google.com -c 3] 64 bytes from 142.250.181.238: icmp_seq=2 ttl=56 time=29.115 ms
+# [ping google.com -c 3] 
+# [ping google.com -c 3] --- google.com ping statistics ---
+# [ping google.com -c 3] 3 packets transmitted, 3 packets received, 0.0% packet loss
+# [ping google.com -c 3] round-trip min/avg/max/stddev = 29.115/36.574/50.207/9.654 ms
+```
+
+## Development
+
+(1) Install dependencies
+
+```bash
+$ npm i
+# or
+$ yarn
+```
+
+(2) Run initial validation
+
+```bash
+$ ./Taskfile.sh validate
+```
+
+(3) Start developing. See [`./Taskfile.sh`](./Taskfile.sh) for more tasks to
+    help you develop.
+
+---
+
+_This project was set up by @jvdx/core_
+
+[install-node]: https://github.com/nvm-sh/nvm

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "in-parallel-lit",
+  "description": "Run multiple processes in parallel",
+  "version": "0.1.0",
+  "author": "Joel Voss <mail@joelvoss.com>",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">= 14"
+  },
+  "main": "src/index.js",
+  "bin": {
+    "in-parallel": "src/bin.js"
+  },
+  "files": [
+    "src",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "./Taskfile.sh start",
+    "test": "./Taskfile.sh test"
+  },
+  "dependencies": {
+    "cross-spawn": "^7.0.3",
+    "mri": "^1.2.0",
+    "sade": "^1.8.1"
+  },
+  "devDependencies": {
+    "@jvdx/core": "^2.16.0"
+  },
+  "prettier": "@jvdx/prettier-config",
+  "prettierIgnore": [
+    "tests/",
+    "dist/"
+  ],
+  "eslintConfig": {
+    "extends": "@jvdx/eslint-config"
+  },
+  "eslintIgnore": [
+    "tests/",
+    "dist/"
+  ]
+}

package/src/bin.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+import sade from 'sade';
+import { readPackageUp } from 'readpkg-lit';
+import { prog } from './index.js';
+
+async function run(argv) {
+	const { packageJson } = await readPackageUp();
+
+	// NOTE(joel): Avoid `MaxListenersExceededWarnings`.
+	process.stdout.setMaxListeners(0);
+	process.stderr.setMaxListeners(0);
+	process.stdin.setMaxListeners(0);
+
+	sade('in-parallel', true)
+		.version(packageJson.version)
+		.describe(packageJson.description)
+		.option(
+			'-c, --continue-on-error',
+			`Set the flag to continue executing other/subsequent tasks even if a task threw an error. 'in-parallel' itself will exit with non-zero code if one or more tasks threw error(s).`,
+		)
+		.option(
+			'--max-parallel',
+			`Set the maximum number of parallelism. Default is unlimited.`,
+			0,
+		)
+		.option(
+			'--aggregate-output',
+			`Avoid interleaving output by delaying printing of each command's output until it has finished.`,
+			false,
+		)
+		.action(opts => prog(opts, process))
+		.parse(argv);
+}
+
+run(process.argv);

package/src/index.js

@@ -0,0 +1,195 @@
+import { InParallelError } from './lib/in-parallel-error.js';
+import { spawn } from './lib/spawn.js';
+import { MemoryWritable } from './lib/memory-writable.js';
+import { getSignalNumber } from './lib/get-signal-num.js';
+import { removeFromArr } from './lib/remove-from-arr.js';
+import { wrapStreamWithLabel } from './lib/wrap-stream-with-label.js';
+import { getStreamKind } from './lib/get-stream-kind.js';
+
+/**
+ * prog represents the main program logic.
+ * @param {{[key: string]: any, _: string[]}} opts
+ * @param {NodeJS.process} proc
+ * @returns {Promise<void>}
+ */
+export function prog(opts, proc) {
+	const { _: tasks, ...options } = opts;
+
+	return new Promise((resolve, reject) => {
+		let results = [];
+		let queue = [];
+		let promises = [];
+		let error = null;
+		let aborted = false;
+
+		// NOTE(joel): Resolve if no tasks are passed.
+		if (tasks.length === 0) return done();
+
+		// NOTE(joel): Pre-build result and queue arays.
+		for (let i = 0; i < tasks.length; i++) {
+			results.push({ name: tasks[i], code: undefined });
+			queue.push({ name: tasks[i], index: i });
+		}
+
+		function done() {
+			if (error == null) return resolve(results);
+			return reject(error);
+		}
+
+		function abort() {
+			if (aborted) return;
+
+			aborted = true;
+			if (promises.length === 0) return done();
+			for (const p of promises) {
+				p.abort();
+			}
+			return Promise.all(promises).then(done, reject);
+		}
+
+		function next() {
+			if (aborted) return;
+
+			// NOTE(joel): Return without resolving if the queue is empty.
+			if (queue.length === 0) {
+				if (promises.length === 0) return done();
+				return;
+			}
+
+			const originalOutputStream = proc.stdout;
+			const optionsClone = {
+				...Object.assign({}, options),
+				stdout: proc.stdout,
+				stderr: proc.stderr,
+				stdin: proc.stdin,
+			};
+			const writer = new MemoryWritable();
+
+			if (options['aggregate-output']) {
+				optionsClone.stdout = writer;
+			}
+
+			const task = queue.shift();
+			const promise = runTask(task.name, optionsClone);
+
+			promises.push(promise);
+			promise.then(
+				result => {
+					removeFromArr(promises, promise);
+
+					if (aborted) return;
+
+					if (options['aggregate-output']) {
+						originalOutputStream.write(writer.toString());
+					}
+
+					// NOTE(joel): Check if the task failed as a result of a signal, and
+					// amend the exit code as a result.
+					if (result.code === null && result.signal !== null) {
+						// NOTE(joel): An exit caused by a signal must return a status code
+						// of 128 plus the value of the signal code.
+						// @see https://nodejs.org/api/process.html#process_exit_codes
+						result.code = 128 + getSignalNumber(result.signal);
+					}
+
+					// NOTE(joel): Save the result.
+					results[task.index].code = result.code;
+
+					// NOTE(joel): Aborts all tasks if it's an error.
+					if (result.code) {
+						error = new InParallelError(result, results);
+						if (!options['continue-on-error']) {
+							return abort();
+						}
+					}
+
+					next();
+				},
+				err => {
+					removeFromArr(promises, promise);
+					if (!options['continue-on-error']) {
+						error = err;
+						return abort();
+					}
+					next();
+				},
+			);
+		}
+
+		let end = tasks.length;
+		if (
+			typeof options['max-parallel'] === 'number' &&
+			options['max-parallel'] > 0
+		) {
+			end = Math.min(tasks.length, options['max-parallel']);
+		}
+
+		for (let i = 0; i < end; ++i) {
+			next();
+		}
+	});
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * @typedef {Object} RunTaskOptions
+ * @prop {stream.Readable} stdin
+ * @prop {stream.Writable} stdout
+ * @prop {stream.Writable} stderr
+ */
+
+/**
+ * runTask executes a single task as a child process.
+ * @param {string} name
+ * @param {RunTaskOptions} opts
+ * @returns {Promise<{name: string, code: number, signal: string}>}
+ */
+function runTask(name, opts) {
+	let proc = null;
+
+	const task = new Promise((resolve, reject) => {
+		const stdin = opts.stdin;
+		const stdout = wrapStreamWithLabel(opts.stdout, name);
+		const stderr = wrapStreamWithLabel(opts.stderr, name);
+
+		const stdinKind = getStreamKind(stdin, process.stdin);
+		const stdoutKind = getStreamKind(stdout, process.stdout);
+		const stderrKind = getStreamKind(stderr, process.stderr);
+
+		const [spawnName, ...spawnArgs] = name.split(' ');
+
+		proc = spawn(spawnName, spawnArgs, {
+			stdio: [stdinKind, stdoutKind, stderrKind],
+		});
+
+		// Piping stdio.
+		if (stdinKind === 'pipe') {
+			stdin.pipe(proc.stdin);
+		}
+		if (stdoutKind === 'pipe') {
+			proc.stdout.pipe(stdout, { end: false });
+		}
+		if (stderrKind === 'pipe') {
+			proc.stderr.pipe(stderr, { end: false });
+		}
+
+		// Register
+		proc.on('error', err => {
+			proc = null;
+			return reject(err);
+		});
+		proc.on('close', (code, signal) => {
+			proc = null;
+			return resolve({ name, code, signal });
+		});
+	});
+
+	task.abort = () => {
+		if (proc == null) return;
+		proc.kill();
+		proc = null;
+	};
+
+	return task;
+}

package/src/lib/get-signal-num.js

@@ -0,0 +1,32 @@
+const signals = {
+	SIGABRT: 6,
+	SIGALRM: 14,
+	SIGBUS: 10,
+	SIGCHLD: 20,
+	SIGCONT: 19,
+	SIGFPE: 8,
+	SIGHUP: 1,
+	SIGILL: 4,
+	SIGINT: 2,
+	SIGKILL: 9,
+	SIGPIPE: 13,
+	SIGQUIT: 3,
+	SIGSEGV: 11,
+	SIGSTOP: 17,
+	SIGTERM: 15,
+	SIGTRAP: 5,
+	SIGTSTP: 18,
+	SIGTTIN: 21,
+	SIGTTOU: 22,
+	SIGUSR1: 30,
+	SIGUSR2: 31,
+};
+
+/**
+ * Converts a signal name to a number.
+ * @param {string} signal
+ * @returns {number}
+ */
+export function getSignalNumber(signal) {
+	return signals[signal] || 0;
+}

package/src/lib/get-stream-kind.js

@@ -0,0 +1,13 @@
+/**
+ * Converts a given stream to an option for `child_process.spawn`.
+ * @param {stream.Readable|stream.Writable|null} stream
+ * @param {process.stdin|process.stdout|process.stderr} std
+ * @returns {string|stream.Readable|stream.Writable}
+ */
+export function getStreamKind(stream, std) {
+	if (stream == null) return 'ignore';
+	// NOTE(joel): `|| !std.isTTY` is needed for the workaround of
+	// https://github.com/nodejs/node/issues/5620
+	if (stream !== std || !std.isTTY) return 'pipe';
+	return stream;
+}

package/src/lib/in-parallel-error.js

@@ -0,0 +1,8 @@
+export class InParallelError extends Error {
+	constructor(causeResult, allResults) {
+		super(`"${causeResult.name}" exited with ${causeResult.code}.`);
+		this.name = causeResult.name;
+		this.code = causeResult.code;
+		this.results = allResults;
+	}
+}

package/src/lib/kill-pids.js

@@ -0,0 +1,110 @@
+import os from 'os';
+import crossSpawn from 'cross-spawn';
+
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Wrap crossSpawn in a Promise.
+ * @param {string} cmd
+ * @param {Array<string|number>} args
+ * @param {any} options
+ */
+function crossSpawnPromise(cmd, args, options) {
+	return new Promise((resolve, reject) => {
+		let stdout = '';
+		let stderr = '';
+		const ch = crossSpawn(cmd, args, options);
+
+		ch.stdout.on('data', d => {
+			stdout += d.toString();
+		});
+
+		ch.stderr.on('data', d => {
+			stderr += d.toString();
+		});
+
+		ch.on('error', err => reject(err));
+
+		ch.on('close', code => {
+			if (stderr) return reject(stderr);
+			if (code !== 0) return reject(`${cmd} exited with code ${code}`);
+			return resolve(stdout);
+		});
+	});
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Kills a process by ID and all its subprocesses.
+ * @param {number} pid
+ */
+export async function killPids(pid, platform = process.platform) {
+	if (platform === 'win32') {
+		crossSpawn('taskkill', ['/F', '/T', '/PID', pid]);
+		return;
+	}
+
+	try {
+		// NOTE(joel): Example of stdout:
+		//   PPID   PID
+		//      1   430
+		//    430   432
+		//      1   727
+		//      1  7166
+		let stdout = await crossSpawnPromise('ps', ['-A', '-o', 'ppid,pid']);
+		stdout = stdout.split(os.EOL);
+
+		let pidExists = false;
+		const pidTree = {};
+		for (let i = 1; i < stdout.length; i++) {
+			stdout[i] = stdout[i].trim();
+			if (!stdout[i]) continue;
+
+			stdout[i] = stdout[i].split(/\s+/);
+			stdout[i][0] = parseInt(stdout[i][0], 10); // PPID
+			stdout[i][1] = parseInt(stdout[i][1], 10); // PID
+
+			// NOTE(joel): Make sure our pid is part of the `ps` output.
+			if (
+				(!pidExists && stdout[i][1] === pid) ||
+				(!pidExists && stdout[i][0] === pid)
+			) {
+				pidExists = true;
+			}
+
+			// NOTE(joel): Build the adiacency Hash Map (pid -> [children of pid])
+			if (pidTree[stdout[i][0]]) {
+				pidTree[stdout[i][0]].push(stdout[i][1]);
+			} else {
+				pidTree[stdout[i][0]] = [stdout[i][1]];
+			}
+		}
+
+		// NOTE(joel): No matching pid found.
+		if (!pidExists) return;
+
+		// NOTE(joel): Starting by the `pid` provided, traverse the tree using
+		// the adiacency Hash Map until the whole subtree is visited. Each pid
+		// encountered while visiting is added to the pids array.
+		let idx = 0;
+		const pids = [pid];
+		while (idx < pids.length) {
+			let curpid = pids[idx++];
+			if (!pidTree[curpid]) continue;
+
+			for (let j = 0; j < pidTree[curpid].length; j++) {
+				pids.push(pidTree[curpid][j]);
+			}
+
+			delete pidTree[curpid];
+		}
+
+		// NOTE(joel): Finally, kill all pids.
+		for (const pid of pids) {
+			process.kill(pid);
+		}
+	} catch (err) {
+		/* Silence is golden */
+	}
+}

package/src/lib/memory-writable.js

@@ -0,0 +1,69 @@
+import { Writable } from 'node:stream';
+import { StringDecoder } from 'node:string_decoder';
+
+const noop = () => {};
+
+/**
+ * Writable stream that can hold written chunks.
+ */
+export class MemoryWritable extends Writable {
+	queue = [];
+	data = [];
+
+	constructor(data = null) {
+		super();
+
+		// NOTE(joel): Ensure `data` is an array.
+		this.data = Array.isArray(data) ? data : [data];
+
+		this.queue = [];
+		for (let chunk of this.data) {
+			if (chunk == null) continue;
+
+			// NOTE(joel): Ensure each chunk is a Buffer.
+			if (!(chunk instanceof Buffer)) {
+				chunk = Buffer.from(chunk);
+			}
+			this.queue.push(chunk);
+		}
+	}
+
+	_write(chunk, enc, cb = noop) {
+		let decoder = null;
+		try {
+			decoder = enc && enc !== 'buffer' ? new StringDecoder(enc) : null;
+		} catch (err) {
+			return cb(err);
+		}
+
+		let decodedChunk = decoder != null ? decoder.write(chunk) : chunk;
+		this.queue.push(decodedChunk);
+		cb();
+	}
+
+	_getQueueSize() {
+		let size = 0;
+		for (let i = 0; i < this.queue.length; i++) {
+			size += this.queue[i].length;
+		}
+		return size;
+	}
+
+	toString() {
+		let str = '';
+		for (const chunk of this.queue) {
+			str += chunk;
+		}
+		return str;
+	}
+
+	toBuffer() {
+		const buffer = Buffer.alloc(this._getQueueSize());
+		let currentOffset = 0;
+		for (const chunk of this.queue) {
+			chunk.copy(buffer, currentOffset);
+			currentOffset += chunk.length;
+		}
+		return buffer;
+	}
+}

package/src/lib/prefix-transform.js

@@ -0,0 +1,33 @@
+import { Transform } from 'node:stream';
+
+const ALL_BR = /\n/g;
+
+export class PrefixTransform extends Transform {
+	constructor(prefix) {
+		super();
+		this.prefix = prefix;
+		this.lastPrefix = null;
+		this.lastIsLinebreak = true;
+	}
+
+	_transform(chunk, _enc, cb) {
+		const firstPrefix = this.lastIsLinebreak
+			? this.prefix
+			: this.lastPrefix !== this.prefix
+			? '\n'
+			: '';
+		const prefixed = `${firstPrefix}${chunk}`.replace(
+			ALL_BR,
+			`\n${this.prefix}`,
+		);
+		const index = prefixed.indexOf(
+			this.prefix,
+			Math.max(0, prefixed.length - this.prefix.length),
+		);
+
+		this.lastPrefix = this.prefix;
+		this.lastIsLinebreak = index !== -1;
+
+		cb(null, index !== -1 ? prefixed.slice(0, index) : prefixed);
+	}
+}

package/src/lib/remove-from-arr.js

@@ -0,0 +1,11 @@
+/**
+ * removeFromArr removes an `item` from `arr`.
+ * @param {any[]} arr
+ * @param {any} item
+ */
+export function removeFromArr(arr, item) {
+	const index = arr.indexOf(item);
+	if (index !== -1) {
+		arr.splice(index, 1);
+	}
+}

package/src/lib/select-color.js

@@ -0,0 +1,67 @@
+let FORCE_COLOR;
+let NODE_DISABLE_COLORS;
+let NO_COLOR;
+let TERM;
+let isTTY = true;
+
+if (typeof process !== 'undefined') {
+	({ FORCE_COLOR, NODE_DISABLE_COLORS, NO_COLOR, TERM } = process.env);
+	isTTY = process.stdout && process.stdout.isTTY;
+}
+
+const enabled =
+	!NODE_DISABLE_COLORS &&
+	NO_COLOR == null &&
+	TERM !== 'dumb' &&
+	((FORCE_COLOR != null && FORCE_COLOR !== '0') || isTTY);
+
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Returns functions that wrap a given string with color char codes.
+ * @param {number} x
+ * @param {number} y
+ * @returns {(txt: string) => string}
+ */
+function createColor(x, y) {
+	const rgx = new RegExp(`\\x1b\\[${y}m`, 'g');
+	const open = `\x1b[${x}m`;
+	const close = `\x1b[${y}m`;
+
+	return function (txt) {
+		if (!enabled || txt == null) return txt;
+		return (
+			open +
+			(~('' + txt).indexOf(close) ? txt.replace(rgx, close + open) : txt) +
+			close
+		);
+	};
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+const colors = [
+	createColor(36, 39), // cyan
+	createColor(32, 39), // green
+	createColor(35, 39), // magenta
+	createColor(33, 39), // yellow
+	createColor(31, 39), // red
+];
+
+let colorIndex = 0;
+const taskNamesToColors = new Map();
+
+/**
+ * Select a color from given task name.
+ * @param {string} taskName
+ * @returns {(txt: string) => string}
+ */
+export function selectColor(taskName) {
+	let color = taskNamesToColors.get(taskName);
+	if (color == null) {
+		color = colors[colorIndex];
+		colorIndex = (colorIndex + 1) % colors.length;
+		taskNamesToColors.set(taskName, color);
+	}
+	return color;
+}

package/src/lib/spawn.js

@@ -0,0 +1,20 @@
+import crossSpawn from 'cross-spawn';
+import { killPids } from './kill-pids.js';
+
+/**
+ * Launches a new process with the given command.
+ * This is almost same as `child_process.spawn`, but it adds a `kill` method
+ * that kills the instance process and its sub processes.
+ * @param {string} command
+ * @param {string[]} args
+ * @param {object} options
+ * @returns {ChildProcess}
+ */
+export function spawn(command, args, options) {
+	const child = crossSpawn(command, args, options);
+	child.kill = function kill() {
+		killPids(this.pid);
+	};
+
+	return child;
+}

package/src/lib/wrap-stream-with-label.js

@@ -0,0 +1,20 @@
+import { selectColor } from './select-color.js';
+import { PrefixTransform } from './prefix-transform.js';
+
+/**
+ * Wraps stdout/stderr with a transform stream to add the task name as prefix.
+ * @param {stream.Writable} source
+ * @param {string} label
+ * @returns {stream.Writable}
+ */
+export function wrapStreamWithLabel(source, label) {
+	if (source == null) return source;
+
+	const color = source.isTTY ? selectColor(label) : x => x;
+	const prefix = color(`[${label}] `);
+	const target = new PrefixTransform(prefix);
+
+	target.pipe(source);
+
+	return target;
+}