@j-o-r/sh 0.0.3 → 1.0.0

package/lib/sh.js

@@ -1,3 +1,262 @@
+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 {
+   #proc;
+   #command = '';
+   #options = {};
+   #stdout = '';
+   #stderr = '';
+	constructor(command, options = {}) {
+		this.#command = command;
+		this.#options = options;
+		this.#proc = null;
+		this.#stdout = '';
+		this.#stderr = '';
+	}
+	runSync () {
+    let { cwd, shell, env, stdio } = this.#options;
+		return spawnSync(this.#options.prefix, [this.#command], {
+			cwd,
+			shell,
+			stdio,
+			windowsHide: true,
+			env,
+		});
+	}
+  /**
+  * @param {string} [payload] - data to write
+  * @retuns {Promise<string>}
+  */
+	run(payload) {
+		if (payload && typeof payload !== 'string') {
+			throw new Error('Argument is not a string');
+		} 
+		let { cwd, shell, env, stdio } = this.#options;
+		if (payload) stdio = ['pipe', 'pipe', '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.write(payload);
+      this.#proc.stdin.end();
+    }
+		return new Promise((resolve, reject) => {
+			this.#proc.on('close', (code) => {
+				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 {StdioOption|StdioOptions} [stdio] - The stdio configuration.
+ */
+/**
+ * @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 {object} predefined - original object
+* @param {object} options - object with new values
+* @retuns {object}
+*/
+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']
+};
+
+
+
+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) {
+		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
+  * @returns {SpawnSyncResponse}
+  */ 
+	runSync() {
+		// @ts-ignore
+		return new SHExecute(this.#cmd, this.#options).runSync();
+	}
+	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");
@@ -19,64 +278,85 @@
 // 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 to enhance usability.
+// - 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 { AsyncLocalStorage } from 'node:async_hooks';
-import { log, parseDuration, quote, quotePowerShell, } from './utils.js';
-import ProcessPromise from './ProcessPromise.js';
-const storage = new AsyncLocalStorage();
 
-const defaults = {
-	processCwd: '',
-	verbose: false,
-	env: {},
-	shell: 'bash',
-	prefix: '',
-};
-defaults.prefix = 'set -euo pipefail;/usr/bin/env';
-
-/**
-* Escape CLI arguments
-* @param {string[]} arg
-* @retruns {string}
-*/
-const sanitizeArg = (arg) => {
-	const s = `${arg}`;
-	if (process.platform == 'win32') {
-		return quotePowerShell(s)
-	}
-	return quote(s);
-}
 
-const getStore = () => {
-	return storage.getStore() || defaults;
-}
 /**
- * Creates a new ProcessPromise object that represents a command to be executed.
+ * 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.
- * @property {boolean} verbose - A property to control verbosity.
  *
  * @param {Array} pieces - An array of string literals from a template literal.
  * @param {...*} args - The values to be interpolated into the string literals.
- * @returns {ProcessPromise} A ProcessPromise object that represents the command.
+ * @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!'`;
+ * const command = await SH`echo 'Hello, world!'`.run();
  */
-/** @type {Shell & { (pieces: TemplateStringsArray, ...args: any[]): ProcessPromise }} */
-// @ts-ignore
+
+/**
+* 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) {
-	const from = new Error().stack.split(/^\s*at\s/m)[2].trim();
 	if (pieces.some((p) => p == undefined)) {
-		throw new Error(`Malformed command at ${from}`);
+		throw new Error(`Malformed command ${pieces}`);
 	}
 	let cmd = pieces[0], i = 0;
 	while (i < args.length) {
@@ -89,29 +369,8 @@ const SH = new Proxy(function(pieces, ...args) {
 		}
 		cmd += s + pieces[++i];
 	}
-	let resolve, reject;
-
-	const promise = new ProcessPromise((...args) => ([resolve, reject] = args));
-	// re-add the environment
-	defaults.processCwd = process.cwd();
-	defaults.env = process.env,
-		promise._bind(cmd, from, resolve, reject, getStore());
-	// Postpone run to allow promise configuration.
-	setImmediate(() => promise.isHalted || promise.run());
-	return promise;
-}, {
-	// this will get and set from:
-	// defaults OR storage (@see within());
-	set(_, key, value) {
-		const target = key in Function.prototype ? _ : getStore();
-		Reflect.set(target, key, value);
-		return true;
-	},
-	get(_, key) {
-		const target = key in Function.prototype ? _ : getStore();
-		return Reflect.get(target, key);
-	},
-});
+	return new SHDispatch(cmd);
+}, {});
 
 /**
 * Create a async context in an sync block
@@ -119,32 +378,40 @@ const SH = new Proxy(function(pieces, ...args) {
 * @example
 * const p = within(async () => {
 *		const res = await Promise.all([
-*			SH`sleep 1; echo 1`,
-*			SH`sleep 2; echo 2`,
+*			SH`sleep 1; echo 1`.run(),
+*			SH`sleep 2; echo 2`.run(),
 *			sleep(2),
-*			SH`sleep 3; echo 3`
+*			SH`sleep 3; echo 3`.run()
 *		]);
 */
 const within = (callback) => {
-	// @ts-ignore
-	return storage.run({ ...getStore() }, callback);
-}
+	(async () => {
+		return await callback()
+	})();
+};
 /**
-* This function reads the standard input (stdin) for the current process.
-* It is used to get piped content into a script.
+* This function reads the standard input (stdin) from the current process.
 * @example 
 * const content = await stdin();
 */
-const stdin = async () => {
+const readIn = async () => {
 	let buf = '';
 	process.stdin.setEncoding('utf8');
 	for await (const chunk of process.stdin) {
 		buf += chunk;
 	}
 	return buf;
-}
+};
+
 /**
-* This function retries a command a specified number of times.
+* 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`);
@@ -156,12 +423,11 @@ const stdin = async () => {
 * const p = await retry(3, expBackoff(), () => SH`curl -s https://flipwrsi`);
 */
 const retry = async (count, a, b) => {
-	const total = count;
+	// const total = count;
 	let callback;
 	let delayStatic = 0;
 	let delayGen;
 	// @ts-ignore
-	const verbose = SH.verbose;
 	if (typeof a == 'function') {
 		callback = a;
 	}
@@ -176,9 +442,7 @@ const retry = async (count, a, b) => {
 		callback = b;
 	}
 	let lastErr;
-	let attempt = 0;
 	while (count-- > 0) {
-		attempt++;
 		try {
 			return await callback();
 		}
@@ -187,13 +451,6 @@ const retry = async (count, a, b) => {
 			if (delayStatic > 0)
 				delay = delayStatic;
 			if (delayGen) delay = delayGen.next().value;
-			log({
-				verbose,
-				kind: 'retry',
-				error: ' FAIL ' +
-					` Attempt: ${attempt}${total == Infinity ? '' : `/${total}`}` +
-					(delay > 0 ? `; next in ${delay}ms` : ''),
-			});
 			lastErr = err;
 			if (count == 0)
 				break;
@@ -202,34 +459,36 @@ const retry = async (count, a, b) => {
 		}
 	}
 	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 Promise.all([
-* 	SH`sleep 2; echo 2`,  // Sleep for 2 seconds
-* 	sleep(2),             // Sleep for 2 seconds
-* 	SH`sleep 3; echo 3`   // Sleep for 3 seconds
-* ]);
+* 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
-	const verbose = SH.verbose;
-	log({ kind: 'cd', dir, verbose });
 	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);
@@ -239,16 +498,5 @@ function* expBackoff(max = '60s', rand = '100ms') {
 		yield Math.min(2 ** n++, maxMs) + ms;
 	}
 }
-// const syncCwd = () => {
-// 	if (SH['processCwd'] != process.cwd())
-// 		process.chdir(SH['processCwd']);
-// }
-export {
-	SH,
-	cd,
-	sleep,
-	retry,
-	stdin,
-	within,
-	expBackoff,
-}
+
+export { SH, cd, expBackoff, readIn, retry, sleep, within };

package/package.json

@@ -2,7 +2,7 @@
   "name": "@j-o-r/sh",
   "author": "Jorrit Duin <j-o-r@duin.work>",
   "type": "module",
-  "version": "0.0.3",
+  "version": "1.0.0",
   "description": "Execute shell commands on Linux-based systems from javascript",
   "main": "lib/sh.js",
   "engines": {
@@ -10,10 +10,11 @@
   },
   "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",
-    "clear:types": "rm lib/*.d.ts",
-    "types": "tsc lib/*.js --declaration --allowJs --emitDeclarationOnly"
+    "types": "tsc lib/*.js --module nodenext --moduleResolution nodenext --declaration --allowJs --emitDeclarationOnly --outDir lib/",
+    "clear:types": "rm lib/*.d.ts"
   },
   "repository": {
     "type": "git",

package/lib/ProcessOutput.d.ts

@@ -1,44 +0,0 @@
-/// <reference types="node" />
-export default ProcessOutput;
-/**
-* The ProcessPromise returns a ProcessOutput even when it fails, by rejecting it.
-* The extension of the Error class is implemented to ensure compatibility when an Error is expected upon rejection.
-*/
-declare class ProcessOutput extends Error {
-    /**
-    * @param {number} code - exit code
-    * @param {string} signal - SIGTERM ...
-    * @param {string} stdout - std reponse string
-    * @param {string} stderr - error reponse string
-    * @param {string} combined - stderr + stdout
-    * @param {string} message - Error message
-    */
-    constructor(code: number, signal: string, stdout?: string, stderr?: string, combined?: string, message?: string);
-    /**
-    * This string represents the standard output (stdout) from the child process.
-    * @returns {string}
-    */
-    get stdout(): string;
-    /**
-    * This string represents the error output (stderr) from the child process.
-    * @returns {string}
-    */
-    get stderr(): string;
-    /**
-    * This represents the exit code returned by the external process.
-    * @returns {number} The exit
-    */
-    get exitCode(): number;
-    /**
-    * This represents the exit signal, for example, "SIGTERM", received from the child process.
-    * @returns {string} The exit signal from the child
-    */
-    get signal(): string;
-    /**
-    * This method is used for debugging purposes. It displays the current state of the object
-    * when passed to the console.log function.
-    */
-    [inspect.custom](): string;
-    #private;
-}
-import { inspect } from 'node:util';