@j-o-r/sh 1.0.2 → 1.0.4

package/README.md

@@ -59,7 +59,7 @@ The `SH` method accepts a template literal string enclosed in backticks as its a
 ### Additional Utilities
 
 The module also provides additional utilities for common tasks:
-
+- `args(command)`: Parsing a command from a string into an arguments array 
 - `cd(dir)`: Change the working directory.
 - `sleep(duration)`: Pause execution for a specified duration.
 - `retry(count, interval, callback)`: Retry a command a specified number of times with an optional interval.
@@ -92,6 +92,13 @@ This class is returned by the `SH` function. Here's a summary of its methods and
   console.log(res);
   ```
 
+- Create a command from a string
+  ```javascript
+	const command = args("uname -r");
+	const content = await SH`${command}`.run();
+	console.log(content);
+  ```
+
 - Async context with multiple commands and sleep:
   ```javascript
   within(async () => {

package/lib/SH.js

@@ -0,0 +1,296 @@
+// 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);
+}, {});
+/**
+ * Splits a command string into an array of arguments, handling quoted strings.
+ * This fixes a problem when a command is like this: SH`${command}` 
+ * 
+ * @param {string} command - The command string to split.
+ * @returns {string[]} - The array of command arguments.
+ */
+const args = (command) => {
+	const args = [];
+	let currentArg = '';
+	let insideQuotes = false;
+	let quoteChar = null;
+
+	for (let i = 0; i < command.length; i++) {
+		const char = command[i];
+
+		if (char === '"' || char === "'") {
+			if (insideQuotes && quoteChar === char && command[i - 1] !== '\\') {
+				insideQuotes = false;
+				quoteChar = null;
+			} else if (!insideQuotes) {
+				insideQuotes = true;
+				quoteChar = char;
+			} else {
+				currentArg += char;
+			}
+		} else if (char === ' ' && !insideQuotes) {
+			if (currentArg.length > 0) {
+				args.push(currentArg);
+				currentArg = '';
+			}
+		} else {
+			currentArg += char;
+		}
+	}
+
+	if (currentArg.length > 0) {
+		args.push(currentArg);
+	}
+
+	return args.map(arg => arg.replace(/\\(['"])/g, '$1'));
+}
+/**
+* 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,
+	args,
+	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.4",
   "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",
+    "clear:types": "rm types/*.d.ts"
   },
   "repository": {
     "type": "git",
@@ -22,10 +22,7 @@
   },
   "license": "Apache License, Version 2.0",
   "dependencies": {},
-  "devDependencies": {
-    "@types/node": "^20.8.10",
-    "uvu": "^0.5.6"
-  },
+  "devDependencies": {},
   "bugs": {
     "url": "https://codeberg.org/duin/sh/issues"
   },
@@ -49,4 +46,4 @@
     "process-promise",
     "process-output"
   ]
-}
+}