@j-o-r/sh 1.0.2 → 1.0.3

package/lib/SH.js

@@ -0,0 +1,254 @@
+// 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
+import assert from 'node:assert';
+import SHDispatch from './SHDispatch.js';
+
+
+/**
+ * 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;
+	let attempt = 0;
+	while (count-- > 0) {
+		attempt++;
+		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,
+	sleep,
+	retry,
+	readIn,
+	within,
+	expBackoff,
+}

package/lib/SHDispatch.js

@@ -0,0 +1,151 @@
+import SHExec from './SHExecute.js';
+/**
+ * @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. e.g: prefix: 'set -euo pipefail;/usr/bin/env',
+ * @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: '/usr/bin/env',
+	stdio: ['inherit', 'pipe', 'pipe'],
+	timeout: 10000 // when 0 there is no timeout
+};
+
+
+
+class SHDispatch {
+	#cmd = '';
+	#options = {};
+	/** 
+	* @type {SHExec} 
+	*/
+	#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 SHExec(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 SHExec(this.#cmd, this.#options).runSync(payload);
+	}
+	async kill() {
+		try {
+			await this.#proc.kill();
+		} catch (_e) { }
+		this.#proc = undefined;
+	}
+}
+
+export default SHDispatch

package/lib/SHExecute.js

@@ -0,0 +1,154 @@
+import { spawnSync, spawn, exec } from 'node:child_process';
+
+/**
+* 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 {
+	/**
+	* @type {import('child_process').ChildProcess}
+	*/
+	#proc;
+	#command = '';
+	#options = {};
+	#stdout = '';
+	#stderr = '';
+	/**
+	* @param {string} command - linux command to be executed
+	* @param {import('./SHDispatch').SHOptions} [options] - ChildProcess options
+	*/
+	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 () => {
+					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);
+	}
+}
+
+export default SHExecute;
+

package/package.json

@@ -2,19 +2,19 @@
   "name": "@j-o-r/sh",
   "author": "Jorrit Duin <j-o-r@duin.work>",
   "type": "module",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Execute shell commands on Linux-based systems from javascript",
-  "main": "lib/sh.js",
+  "main": "lib/SH.js",
+  "types": "types/SH.d.ts",
   "engines": {
     "node": ">=20.0.0"
   },
   "scripts": {
     "test": "test/sh.js",
-    "compile": "npx rollup src/sh.js --generatedCode es2015 --file lib/sh.js --format es --name SH && npm run types",
     "publish": "npm run release && npm publish --access public",
     "release": "npm pack --pack-destination=release",
-    "types": "tsc lib/*.js --module nodenext --moduleResolution nodenext --declaration --allowJs --emitDeclarationOnly --outDir lib/",
-    "clear:types": "rm lib/*.d.ts"
+    "types": "tsc lib/*.js --module nodenext --moduleResolution nodenext --declaration --allowJs --emitDeclarationOnly --outDir types/",
+    "clear:types": "rm types/*.d.ts"
   },
   "repository": {
     "type": "git",

package/{lib/sh.d.ts → types/SH.d.ts}

@@ -1,60 +1,3 @@
-export type SpawnSyncResponse = {
-    /**
-     * - The exit code of the child process. A value of `0` indicates success.
-     */
-    status: number;
-    /**
-     * - The signal used to terminate the process, if any.
-     */
-    signal: Buffer | null;
-    /**
-     * - An array containing the standard output and standard error of the child process.
-     */
-    output: Array<string | null>;
-    /**
-     * - The process ID of the child process.
-     */
-    pid: number;
-    /**
-     * - The standard output of the child process.
-     */
-    stdout: Buffer | null;
-    /**
-     * - The standard error of the child process.
-     */
-    stderr: Buffer | null;
-};
-/**
- * Default options for the execution environment.
- */
-export type SHOptions = {
-    /**
-     * - The current working directory.
-     */
-    cwd?: string;
-    /**
-     * - The environment variables.
-     */
-    env?: NodeJS.ProcessEnv;
-    /**
-     * - The shell to use for execution.
-     */
-    shell?: string;
-    /**
-     * - The prefix commands to ensure a safe execution environment.
-     */
-    prefix?: string;
-    /**
-     * - The stdio configuration.
-     */
-    stdio?: StdioOptions | StdioOption;
-    /**
-     * - default 20000: a timeout error is triggerd when a process execution time is exceeded, 0 is no timeout
-     */
-    timeout?: number;
-};
-export type StdioOption = ('pipe' | 'ignore' | 'inherit' | number);
-export type StdioOptions = Array<StdioOption> | StdioOption;
 /**
  * Creates a new SHDispatch object that represents a command to be executed.
  */
@@ -69,20 +12,14 @@ export const SH: Shell & {
 */
 export function cd(dir: string): void;
 /**
- * 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.
- */
-export function expBackoff(max?: string, rand?: string): Generator<number, void, unknown>;
-/**
-* This function reads the standard input (stdin) from the current process.
+* 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 content = await stdin();
+*
+* const res = await sleep('5s');
 */
-export function readIn(): Promise<string>;
+export function sleep(duration: string | number): Promise<any>;
 /**
 * Retries a given asynchronous function a specified number of times with optional delays between attempts.
 *
@@ -104,14 +41,11 @@ export function readIn(): Promise<string>;
 */
 export function retry(count: number, a: string | typeof expBackoff | Function, b?: Function): Promise<any>;
 /**
-* 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'.
-*
+* This function reads the standard input (stdin) from the current process.
 * @example
-*
-* const res = await sleep('5s');
+* const content = await stdin();
 */
-export function sleep(duration: string | number): Promise<any>;
+export function readIn(): Promise<string>;
 /**
 * Create a async context in an sync block
 * @param {function} callback - async function
@@ -125,28 +59,13 @@ export function sleep(duration: string | number): Promise<any>;
 *		]);
 */
 export function within(callback: Function): void;
-declare class SHDispatch {
-    /**
-    * @param {string} cmd - cmd to execute
-    */
-    constructor(cmd: string);
-    /**
-    * @param {SHOptions} options
-    * @returns {SHDispatch}
-    */
-    options(options: SHOptions): SHDispatch;
-    /**
-    * @param {string} [payload]
-    * @returns {Promise<string>}
-    */
-    run(payload?: string): Promise<string>;
-    /**
-    * Works for screen takeovers like editors
-    * @param {string} [payload]
-    * @returns {SpawnSyncResponse}
-    */
-    runSync(payload?: string): SpawnSyncResponse;
-    kill(): Promise<void>;
-    #private;
-}
-export {};
+/**
+ * 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.
+ */
+export function expBackoff(max?: string, rand?: string): Generator<number, void, unknown>;
+import SHDispatch from './SHDispatch.js';

package/types/SHDispatch.d.ts

@@ -0,0 +1,82 @@
+export default SHDispatch;
+export type SpawnSyncResponse = {
+    /**
+     * - The exit code of the child process. A value of `0` indicates success.
+     */
+    status: number;
+    /**
+     * - The signal used to terminate the process, if any.
+     */
+    signal: Buffer | null;
+    /**
+     * - An array containing the standard output and standard error of the child process.
+     */
+    output: Array<string | null>;
+    /**
+     * - The process ID of the child process.
+     */
+    pid: number;
+    /**
+     * - The standard output of the child process.
+     */
+    stdout: Buffer | null;
+    /**
+     * - The standard error of the child process.
+     */
+    stderr: Buffer | null;
+};
+/**
+ * Default options for the execution environment.
+ */
+export type SHOptions = {
+    /**
+     * - The current working directory.
+     */
+    cwd?: string;
+    /**
+     * - The environment variables.
+     */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * - The shell to use for execution.
+     */
+    shell?: string;
+    /**
+     * - The prefix commands to ensure a safe execution environment. e.g: prefix: 'set -euo pipefail;/usr/bin/env',
+     */
+    prefix?: string;
+    /**
+     * - The stdio configuration.
+     */
+    stdio?: StdioOptions | StdioOption;
+    /**
+     * - default 20000: a timeout error is triggerd when a process execution time is exceeded, 0 is no timeout
+     */
+    timeout?: number;
+};
+export type StdioOption = ('pipe' | 'ignore' | 'inherit' | number);
+export type StdioOptions = Array<StdioOption> | StdioOption;
+declare class SHDispatch {
+    /**
+    * @param {string} cmd - cmd to execute
+    */
+    constructor(cmd: string);
+    /**
+    * @param {SHOptions} options
+    * @returns {SHDispatch}
+    */
+    options(options: SHOptions): SHDispatch;
+    /**
+    * @param {string} [payload]
+    * @returns {Promise<string>}
+    */
+    run(payload?: string): Promise<string>;
+    /**
+    * Works for screen takeovers like editors
+    * @param {string} [payload]
+    * @returns {SpawnSyncResponse}
+    */
+    runSync(payload?: string): SpawnSyncResponse;
+    kill(): Promise<void>;
+    #private;
+}

package/types/SHExecute.d.ts

@@ -0,0 +1,24 @@
+/// <reference types="node" resolution-mode="require"/>
+export default SHExecute;
+declare class SHExecute {
+    /**
+    * @param {string} command - linux command to be executed
+    * @param {import('./SHDispatch').SHOptions} [options] - ChildProcess options
+    */
+    constructor(command: string, options?: any);
+    /**
+    * @param {string} [payload] - data to write
+    * @retuns {Promise<object>}
+    */
+    runSync(payload?: string): import("child_process").SpawnSyncReturns<Buffer>;
+    /**
+    * @param {string} [payload] - data to write
+    * @retuns {Promise<string>}
+    */
+    run(payload?: string): Promise<any>;
+    /**
+    * @returns {Promise<number[]>}
+    */
+    kill(signal?: string): Promise<number[]>;
+    #private;
+}

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 };