@j-o-r/sh 1.0.2 → 1.0.4

package/lib/sh.js

@@ -1,538 +0,0 @@
-import assert from 'node:assert';
-import { spawnSync, spawn, exec } from 'node:child_process';
-
-// timeout when a process becomes inresponsive
-
-/**
-* Kills a process and all child processes of a given process ID in Linux/Posix.
-* @param {number} processPid - The process ID.
-* @param {string} signal - Signal to send.
-* @retruns {Promise<number[]>} array with killed pid numbers
-*/
-const killProcesses = (processPid, signal) => {
-	const killed = [];
-	return new Promise((resolve, reject) => {
-		// Command to get child PIDs of the given process
-		const cmd = `pgrep -P ${processPid}`;
-		exec(cmd, (error, stdout, stderr) => {
-			if (error) {
-				reject(error);
-				return;
-			}
-			if (stderr) {
-				reject(new Error(stderr));
-				return;
-			}
-			const pids = stdout.split(/\r?\n/).filter(pid => pid);
-			// Kill each child process
-			try {
-				for (const pid of pids) {
-					process.kill(parseInt(pid), signal);
-					killed.push(parseInt(pid));
-				}
-			} catch (err) {
-				reject(err);
-				return;
-			}
-			// Kill the parent process after all child processes have been killed
-			try {
-				process.kill(processPid, signal);
-				killed.push(processPid);
-			} catch (err) {
-				reject(err);
-				return;
-			}
-			resolve(killed);
-		});
-	});
-};
-
-class SHExecute {
-	#proc;
-	#command = '';
-	#options = {};
-	#stdout = '';
-	#stderr = '';
-	constructor(command, options = {}) {
-		this.#command = command;
-		this.#options = options;
-		this.#proc = null;
-		this.#stdout = '';
-		this.#stderr = '';
-	}
-	/**
-	* @param {string} [payload] - data to write
-	* @retuns {Promise<object>}
-	*/
-	runSync(payload) {
-		if (payload && typeof payload !== 'string') {
-			throw new Error('Argument is not a string');
-		}
-		let { cwd, shell, env, stdio } = this.#options;
-		// pipe need to be set on stdin when posting a payload
-		if (payload) stdio[0] = 'pipe';
-		const input = payload || undefined;
-		return spawnSync(this.#options.prefix, [this.#command], {
-			cwd,
-			shell,
-			stdio,
-			windowsHide: true,
-			env,
-			input
-		});
-	}
-	/**
-	* @param {string} [payload] - data to write
-	* @retuns {Promise<string>}
-	*/
-	run(payload) {
-		let to = 0;
-		if (payload && typeof payload !== 'string') {
-			throw new Error('Argument is not a string');
-		}
-		if (this.#options.timeout) {
-			to = this.#options.timeout;
-		}
-		let { cwd, shell, env, stdio } = this.#options;
-		// pipe need to be set on stdin when posting a payload
-		if (payload) stdio[0] = 'pipe';
-		this.#proc = spawn(this.#options.prefix, [this.#command], {
-			cwd,
-			shell,
-			stdio,
-			windowsHide: true,
-			env,
-		});
-
-		this.#proc.stdout?.on('data', (data) => {
-			this.#stdout += data;
-		});
-
-		this.#proc.stderr?.on('data', (data) => {
-			this.#stderr += data;
-		});
-		if (payload) {
-			this.#proc.stdin.end(payload);
-		}
-		return new Promise((resolve, reject) => {
-			let timeout;
-			if (to > 0) {
-				timeout = setTimeout(async () => {
-					await this.#proc.kill();
-					reject(new Error(`Process timed out: ${this.#command}`));
-				}, to); // options.timeout
-			}
-			this.#proc.on('close', (code) => {
-				if (timeout) clearTimeout(timeout);
-				if (code === 0) {
-					resolve(this.#stdout.trim());
-				} else {
-					reject(new Error(`${code}: ${this.#command} "${this.#stderr.trim()}"`));
-				}
-			});
-
-			this.#proc.on('error', (err) => {
-				reject(err);
-			});
-		});
-	}
-	/**
-	* @returns {Promise<number[]>}
-	*/
-	async kill(signal = 'SIGTERM') {
-		if (!this.#proc) throw new Error('Trying to kill a process without creating one.');
-		if (!this.#proc.pid) throw new Error('The process pid is undefined.');
-
-		return killProcesses(this.#proc.pid, signal);
-	}
-}
-
-/**
- * @typedef {Object} SpawnSyncResponse
- * @property {number} status - The exit code of the child process. A value of `0` indicates success.
- * @property {Buffer|null} signal - The signal used to terminate the process, if any.
- * @property {Array<string|null>} output - An array containing the standard output and standard error of the child process.
- * @property {number} pid - The process ID of the child process.
- * @property {Buffer|null} stdout - The standard output of the child process.
- * @property {Buffer|null} stderr - The standard error of the child process.
- */
-/**
- * Default options for the execution environment.
- *
- * @typedef {Object} SHOptions
- * @property {string} [cwd] - The current working directory.
- * @property {NodeJS.ProcessEnv} [env] - The environment variables.
- * @property {string} [shell] - The shell to use for execution.
- * @property {string} [prefix] - The prefix commands to ensure a safe execution environment.
- * @property {StdioOptions|StdioOption} [stdio] - The stdio configuration.
- * @property {number} [timeout] - default 20000: a timeout error is triggerd when a process execution time is exceeded, 0 is no timeout
- */
-/**
- * @typedef {('pipe' | 'ignore' | 'inherit' | number)} StdioOption
- * @description Defines the stdio configuration for each of the standard streams.
- * 
- * - 'pipe' creates a pipe between the child process and the parent process. 
- *   The parent end of the pipe is exposed as a property on the `ChildProcess` object.
- * - 'ignore' indicates that the child process's corresponding stdio file descriptor will be ignored.
- * - 'inherit' passes the corresponding stdio stream to/from the child process.
- * - Stream object to be used for the stdio stream.
- * - Positive integer representing a file descriptor to be used for the stdio stream.
- */
-/**
- * @typedef {Array<StdioOption>|StdioOption} StdioOptions
- * @description 
- * Configures the stdio streams for the child process. This can be an array or a single StdioOption.
- * 
- * Array Form: Specify the configuration for [stdin, stdout, stderr].
- *   - If array length is more than 3, additional positions correspond to extra streams.
- * Single Value: This value will be applied to stdin, stdout, and stderr.
- * 
- * Examples:
- * - ['pipe', 'pipe', 'ignore']: Pipe stdin and stdout, ignore stderr.
- * - 'inherit': Inherit all stdio streams from the parent.
- */
-/**
- * 'Code Safe' has own prop
- *
- * @param {any} o - object to examine
- * @param {string} p - property to look for
- * @returns {boolean}
- */
-const hasProp = (o, p) => {
-	if (typeof o === 'undefined') {
-		return false;
-	}
-	return Object.prototype.hasOwnProperty.call(o, p);
-};
-
-/**
-* Merge property values while maintaining the fixed set of props in the original object
-* @param {SHOptions} predefined - original object
-* @param {SHOptions} options - object with new values
-* @returns {SHOptions}
-*/
-const mergeOptions = (predefined, options) => {
-	// Extract the keys from the predefined object
-	const keys = Object.keys(predefined);
-
-	// Use reduce to accumulate only the predefined properties from sourceObj
-	const mergedObj = keys.reduce((acc, key) => {
-		if (hasProp(options, key)) {
-			acc[key] = options[key];
-		} else {
-			acc[key] = predefined[key];
-		}
-		return acc;
-	}, {});
-
-	return mergedObj;
-};
-
-
-/** @type {SHOptions} */
-const defaultOptions = {
-	cwd: process.cwd(),
-	env: process.env,
-	shell: 'bash',
-	prefix: 'set -euo pipefail;/usr/bin/env',
-	stdio: ['inherit', 'pipe', 'pipe'],
-	timeout: 10000 // when 0 there is no timeout
-};
-
-
-
-class SHDispatch {
-	#cmd = '';
-	#options = {};
-	#proc;
-	/**
-	* @param {string} cmd - cmd to execute
-	*/
-	constructor(cmd) {
-		this.#cmd = cmd;
-		this.#options = defaultOptions;
-	}
-  /**
-  * @param {SHOptions} options
-  * @returns {SHDispatch}
-  */
-	options(options) {
-		if (options.stdio && typeof options.stdio === 'string') {
-			// convert stdio to array
-			// This sets the default io values
-			// but can be overwritten when having a payload
-			const io = options.stdio;
-			options.stdio = Array(3).fill(io);
-		}
-		this.#options = mergeOptions(defaultOptions, options);
-		return this;
-	}
-  /** 
-  * @param {string} [payload]
-  * @returns {Promise<string>}
-  */ 
-	run(payload) {
-		this.#proc = new SHExecute(this.#cmd, this.#options);
-		return this.#proc.run(payload);
-	}
-
-  /** 
-  * Works for screen takeovers like editors
-  * @param {string} [payload]
-  * @returns {SpawnSyncResponse}
-  */ 
-	runSync(payload) {
-		// @ts-ignore
-		return new SHExecute(this.#cmd, this.#options).runSync(payload);
-	}
-	async kill() {
-		try {
-		  await this.#proc.kill();
-		} catch (_e) {}
-		this.#proc = undefined;
-	}
-}
-
-// Copyright 2021 Google LLC
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     https://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-// 
-//
-// Original Source: zx
-// Link to Original Source: https://github.com/google/zx
-// Reason for Using This Code: 
-// The core functionality of this code is highly beneficial. However, certain parts of the original code 
-// were overwriting the global namespace with core libraries and variables. This was causing conflicts with 
-// other packages (for instance, fetch) and introducing unexpected elements into my code base.
-// The main $/SH method is all there is left, with barebone Promises and readable code.
-// Changes Made: 
-// - The code has been or is being reformatted to comply with ES2020 standards.
-// - Some methods were added and existing ones were modified or deleted to enhance usability.
-// - Most methods were deleted, 
-// - The namespace has been changed from '$' to 'SH'.
-// Modified by: jorrit.duin+sh[AT]gmail.com
-
-
-/**
- * Creates a new SHDispatch object that represents a command to be executed.
- *
- * @typedef {Function} Shell
- * @property {function(Array, ...*): ProcessPromise} execute - The function to execute the command.
- *
- * @param {Array} pieces - An array of string literals from a template literal.
- * @param {...*} args - The values to be interpolated into the string literals.
- * @returns {SHDispatch} Trigger for the command.
- * @throws {Error} Throws an error if any of the string literals in `pieces` is undefined.
- *
- * @example
- * const command = await SH`echo 'Hello, world!'`.run();
- */
-
-/**
-* escape paramater commands
-* @param {string} arg
-* @returns {string}
-*/
-const quote = (arg) => {
-	if (/^[a-z0-9/_.\-@:=]+$/i.test(arg) || arg === '') {
-		return arg;
-	}
-	return (`'` +
-		arg
-			.replace(/\\/g, '\\\\')
-			.replace(/'/g, "\\'")
-			.replace(/\f/g, '\\f')
-			.replace(/\n/g, '\\n')
-			.replace(/\r/g, '\\r')
-			.replace(/\t/g, '\\t')
-			.replace(/\v/g, '\\v')
-			.replace(/\0/g, '\\0') +
-		`'`);
-};
-/**
-* Escape CLI arguments
-* @param {string[]} arg
-* @retruns {string}
-*/
-const sanitizeArg = (arg) => {
-	const s = `${arg}`;
-	return quote(s);
-};
-
-/**
-* 4ms, 5s || 5
-* @param {number|string} d 
-* @returns {number}
-*/
-const parseDuration = (d) => {
-	if (typeof d == 'number') {
-		if (isNaN(d) || d < 0)
-			throw new Error(`Invalid duration: "${d}".`);
-		return d;
-	}
-	else if (/\d+s/.test(d)) {
-		return +d.slice(0, -1) * 1000;
-	}
-	else if (/\d+ms/.test(d)) {
-		return +d.slice(0, -2);
-	}
-	throw new Error(`Unknown duration: "${d}".`);
-};
-/** @type {Shell & { (pieces: TemplateStringsArray, ...args: *): SHDispatch }} */
-const SH = new Proxy(function(pieces, ...args) {
-	if (pieces.some((p) => p == undefined)) {
-		throw new Error(`Malformed command ${pieces}`);
-	}
-	let cmd = pieces[0], i = 0;
-	while (i < args.length) {
-		let s;
-		if (Array.isArray(args[i])) {
-			s = args[i].map((x) => sanitizeArg(x)).join(' ');
-		}
-		else {
-			s = sanitizeArg(args[i]);
-		}
-		cmd += s + pieces[++i];
-	}
-	return new SHDispatch(cmd);
-}, {});
-
-/**
-* Create a async context in an sync block
-* @param {function} callback - async function
-* @example
-* const p = within(async () => {
-*		const res = await Promise.all([
-*			SH`sleep 1; echo 1`.run(),
-*			SH`sleep 2; echo 2`.run(),
-*			sleep(2),
-*			SH`sleep 3; echo 3`.run()
-*		]);
-*/
-const within = (callback) => {
-	(async () => {
-		return await callback()
-	})();
-};
-/**
-* This function reads the standard input (stdin) from the current process.
-* @example 
-* const content = await stdin();
-*/
-const readIn = async () => {
-	let buf = '';
-	process.stdin.setEncoding('utf8');
-	for await (const chunk of process.stdin) {
-		buf += chunk;
-	}
-	return buf;
-};
-
-/**
-* Retries a given asynchronous function a specified number of times with optional delays between attempts.
-*
-* @param {number} count - The number of retry attempts.
-* @param {string|expBackoff|Function} a - Either a delay duration as a string, a delay generator object, or the callback function.
-* @param {Function} [b] - The callback function to retry, required if `a` is not a function.
-* @returns {Promise<*>} - The result of the callback function if it succeeds within the retry attempts.
-* @throws {Error} - The last error encountered if all retry attempts fail.
-* 
-* @example 
-* // Retry a command 3 times
-* const p = await retry(3, () => SH`curl -s https://flipwrsi`);
-* 
-* // Retry a command 3 times with an interval of 1 second between each try
-* const p = await retry(3, '1s', () => SH`curl -s https://flipwrsi`);
-* 
-* // Retry a command 3 times with irregular intervals using exponential backoff
-* const p = await retry(3, expBackoff(), () => SH`curl -s https://flipwrsi`);
-*/
-const retry = async (count, a, b) => {
-	// const total = count;
-	let callback;
-	let delayStatic = 0;
-	let delayGen;
-	// @ts-ignore
-	if (typeof a == 'function') {
-		callback = a;
-	}
-	else {
-		if (typeof a == 'object') {
-			delayGen = a;
-		}
-		else {
-			delayStatic = parseDuration(a);
-		}
-		assert(b);
-		callback = b;
-	}
-	let lastErr;
-	while (count-- > 0) {
-		try {
-			return await callback();
-		}
-		catch (err) {
-			let delay = 0;
-			if (delayStatic > 0)
-				delay = delayStatic;
-				// @ts-ignore
-			if (delayGen) delay = delayGen.next().value;
-			lastErr = err;
-			if (count == 0)
-				break;
-			if (delay)
-				await sleep(delay);
-		}
-	}
-	throw lastErr;
-};
-/**
-* This function pauses or "sleeps" code execution for a specified duration.
-* @param {string|number} duration - The duration to pause execution for, e.g., '100ms' or '3s'.
-* 
-* @example
-* 
-* const res = await sleep('5s');
-*/
-const sleep = (duration) => {
-	return new Promise((resolve) => {
-		setTimeout(resolve, parseDuration(duration));
-	});
-};
-/**
-* Change working directory
-* @param {string} dir
-*/
-const cd = (dir) => {
-	// @ts-ignore
-	process.chdir(dir);
-};
-/**
- * Generates an exponential backoff time with a random jitter.
- *
- * @generator
- * @param {string} [max='60s'] - The maximum backoff time in a human-readable format (e.g., '60s' for 60 seconds).
- * @param {string} [rand='100ms'] - The maximum random jitter time in a human-readable format (e.g., '100ms' for 100 milliseconds).
- * @yields {number} The backoff time in milliseconds.
- */
-function* expBackoff(max = '60s', rand = '100ms') {
-	const maxMs = parseDuration(max);
-	const randMs = parseDuration(rand);
-	let n = 1;
-	while (true) {
-		const ms = Math.floor(Math.random() * randMs);
-		yield Math.min(2 ** n++, maxMs) + ms;
-	}
-}
-
-export { SH, cd, expBackoff, readIn, retry, sleep, within };