@j-o-r/sh 1.1.28 → 1.1.31

package/lib/SH.js

@@ -25,7 +25,7 @@
 // - Some methods were added and existing ones were modified or deleted to enhance usability.
 // - The namespace has been changed from '$' to 'SH'.
 // Modified by: jorrit.duin+sh[AT]gmail.com
-/** @type {assert} */
+
 import assert from 'node:assert';
 import readline from 'node:readline/promises';
 import SHDispatch from './SHDispatch.js';
@@ -33,40 +33,49 @@ import Test from './Test.js'
 import AsyncTracker from './AsyncTracker.js'
 
 /**
-* @typedef {Object.<string, string>} ArgsObject
-* @property {string} [key: string] - Any string key maps to a string value
-* @property {string[]} _ - Array of strings, unnamed parameters
-* @description Parsed parameters result.
-*/
+ * Parsed command-line arguments.
+ *
+ * Named options map to their string value, or `true` when no value is supplied.
+ * Bare positional arguments are collected in `_`.
+ *
+ * @typedef {{_: string[]} & Object.<string, string|true|string[]>} ArgsObject
+ */
+
+/**
+ * @typedef {Function} RejectCallback
+ * @param {Error} error - The error object passed to the callback.
+ */
+
+/**
+ * @typedef {Function} ResolveCallback
+ * @param {any} [param] - Optional callback any value
+ */
+
 /**
-* @typedef {Function} RejectCallback
-* @param {Error} error - The error object passed to the callback.
-*/
+ * @typedef {import('./SHDispatch.js').SHOptions} SHOptions
+ */
+
 /**
-* @typedef {Function} ResolveCallback
-* @param {any} [param] - Optional callback any value
-*/
+ * @typedef {Object} AbortableInput
+ * @property {Promise<string|void>} input - Promise that resolves to user input or void if aborted.
+ * @property {() => void} abort - Function to abort input collection.
+ */
+
 /**
-* 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();
-*/
+ * Generator-like object that yields retry delay durations.
+ *
+ * @typedef {Iterator<number|string>} ExpBackoffGenerator
+ */
 
 /**
-* Determine a javascript type
-*
-* @param {any} fn - Any let type
-* @returns {string} The "real" object / typeof name
-*/
+ * Utility to determine the JavaScript type of a value.
+ *
+ * @param {any} fn - Any value to inspect.
+ * @returns {string} The "real" object type name (e.g., 'Array', 'Promise') or primitive typeof.
+ * @example
+ * jsType([]); // 'Array'
+ * jsType(Promise.resolve()); // 'Promise'
+ */
 const jsType = (fn) => {
 	if (fn === undefined) return 'undefined';
 	const type = Object.prototype.toString.call(fn).slice(8, -1);
@@ -74,59 +83,60 @@ const jsType = (fn) => {
 };
 
 /**
-* 'Code Safe' has own prop
-*
-* @param {any} o - object to examine
-* @param {string} p - property to look for
-* @returns {boolean}
-*/
+ * Checks if an object has a specific own property (code-safe).
+ *
+ * @param {any} o - Object to examine.
+ * @param {string} p - Property name to check.
+ * @returns {boolean} True if the object has the own property.
+ */
 const hasProp = (o, p) => {
   if (o == null) return false;
   return Object.prototype.hasOwnProperty.call(o, p);
 };
+
 /**
-* 4ms, 5s || 5
-* @param {number|string} d 
-* @returns {number}
-*/
+ * Parses a human-readable duration string or number into milliseconds.
+ *
+ * Supports finite non-negative numbers as milliseconds, plus exact string forms
+ * with units: '5s' (5000ms) and '100ms' (100ms).
+ *
+ * @param {number|string} d - Duration as number (ms) or string ('5s', '100ms').
+ * @returns {number} Duration in milliseconds.
+ * @throws {Error} If the duration type or format is invalid.
+ */
 const parseDuration = (d) => {
 	if (typeof d == 'number') {
-		if (isNaN(d) || d < 0)
+		if (!Number.isFinite(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);
+	if (typeof d == 'string') {
+		const match = d.match(/^(\d+)(ms|s)$/);
+		if (!match)
+			throw new Error(`Unknown duration: "${d}".`);
+		const amount = Number(match[1]);
+		return match[2] == 's' ? amount * 1000 : amount;
 	}
-	throw new Error(`Unknown duration: "${d}".`);
-}
-/**
-* bash escape a string suitable as an argument on the commandline
-* for javascript code
-* @param {string} x
-* @returns {string}
-*/
-const bashEscape = (x) => {
-	let str = String(x).trim();
-	// the trick is to double escape escape vars first
-	str = str.replace(/\\/g, '\\\\');
-	// then add escaping for oddities
-	// Replace literal escape sequences like \n, \t, \r in quoted strings
-	str = str.replace(/(['"])\\(.)\1/g, '$1\\\\$2$1');
-	// escape $ (is a BASH var)
-	str = str.replace(/\$/g, '\\$');
-	// Escape backticks
-	str = str.replace(/`/g, '\\`');
-	// Escape quotes
-	str = str.replace(/"/g, '\\"');
-	return str;
+	throw new Error(`Invalid duration type: "${jsType(d)}".`);
 }
 
+/**
+ * Quotes a value as one POSIX shell argument.
+ *
+ * The `SH` template tag interpolates values as raw shell source by default. Use
+ * this helper when a JavaScript value must be passed as data instead of shell
+ * syntax. The returned string is single-quoted and preserves the exact string
+ * value, including leading/trailing whitespace, empty strings, quotes,
+ * semicolons, glob characters, tabs, and newlines.
+ *
+ * @param {unknown} x - Value to quote as a single shell argument.
+ * @returns {string} POSIX-shell-quoted argument string.
+ * @example
+ * await SH`printf '%s\n' ${bashEscape(userInput)}`.run();
+ */
+const bashEscape = (x) => `'${String(x).replace(/'/g, `'\\''`)}'`;
 
-/** @type {import('./SHDispatch.js').SHOptions} */
+/** Default options applied to all SH commands unless overridden. */
 const defaultOptions = {
 	cwd: process.cwd(),
 	env: process.env,
@@ -135,30 +145,66 @@ const defaultOptions = {
 	timeout: 0, // when 0 there is no timeout
 };
 
-const setHandler = {
-  set(target, prop, value) {
-    defaultOptions[prop] = value;  // Allow setting on target
-    // console.log(`Set ${String(prop)} = ${value}`);
-    // console.log(defaultOptions);
-    return true;
-  }
-}
+/** Known global option properties exposed for `SH.option` readback. */
+const defaultOptionKeys = new Set([
+	'cwd',
+	'env',
+	'shell',
+	'stdio',
+	'timeout',
+	'maxBuffer',
+	'detached',
+]);
 
 /**
-* A template-tag that returns an SHDispatch.
-* @typedef {(pieces: TemplateStringsArray, ...args: unknown[]) => SHDispatch} SHTag
-*/
+ * Proxy traps for the SH template tag and global option defaults.
+ *
+ * Assignments keep the existing compatibility behavior by storing every property
+ * in defaultOptions. Reads only expose known default option keys, so unknown
+ * property access continues to behave like a normal function proxy read.
+ */
+const defaultOptionHandler = {
+	get(target, prop, receiver) {
+		if (defaultOptionKeys.has(prop)) {
+			return defaultOptions[prop];
+		}
+		return Reflect.get(target, prop, receiver);
+	},
+	set(target, prop, value) {
+		defaultOptions[prop] = value;
+		return true;
+	}
+}
+
 /**
-* SH template tag
-*
-* Interpolation rules:
-* - Arrays: each element is String(x).trim(), with newlines/carriage returns/tabs escaped; if an element contains shell metacharacters or spaces, it is wrapped in single-quotes and internal single-quotes are escaped as '\''.
-* - Non-array values: currently coerced with String(value) and inserted as-is (NOT shell-escaped). Be careful when interpolating untrusted input.
-*
-* @type {Shell & SHTag & defaultOptions}
-* Returns an SHDispatch that can be configured via .options() and executed with .run() / .runSync().
-* @returns {SHDispatch}
-*/
+ * Template tag for building and executing shell commands.
+ *
+ * Returns an {@link SHDispatch} instance for configuration (.options()) and execution (.run(), .runSync()).
+ *
+ * Interpolation rules are raw-by-default:
+ * - Arrays: Each element is converted with `String(value)` and joined with one space.
+ * - Other values: `String(value)` is inserted directly into the shell source.
+ *
+ * Raw interpolation allows trusted shell fragments such as pipes, redirects, and
+ * command separators. It is not safe for untrusted input. Wrap untrusted values
+ * with {@link bashEscape} before interpolating them.
+ *
+ * SH acts as both template tag and options setter: `SH.timeout = 5000; SH`cmd``
+ *
+ * @param {TemplateStringsArray} pieces - String literals from template.
+ * @param {...unknown[]} args - Values to interpolate.
+ * @returns {SHDispatch} Command dispatcher.
+ * @throws {Error} If pieces contain undefined.
+ * @example
+ * const cmd = SH`echo ${'Hello'}`;
+ * await cmd.run(); // Executes: echo Hello
+ *
+ * // Array interpolation is raw and joins with spaces
+ * SH`ls ${['-la', '/']}`.run(); // Executes: ls -la /
+ *
+ * // Quote untrusted values explicitly
+ * SH`printf '%s\n' ${bashEscape('semi; colon')}`.run();
+ */
 const SH = new Proxy(function(pieces, ...args) {
 	if (pieces.some((p) => p == undefined)) {
 		throw new Error(`Malformed command ${pieces}`);
@@ -168,57 +214,40 @@ const SH = new Proxy(function(pieces, ...args) {
 		let s;
 		
 		if (Array.isArray(args[i])) {
-			// @ts-ignore
-			s = args[i].map(/** @param {string} x */(x) => {
-				// Trim every element
-				let str = String(x).trim();
-        str = str.replace(/\n/g, '\\n').replace(/\r/g, '\\r').replace(/\t/g, '\\t');
-				// If the string contains special characters, wrap in single quotes
-				if (str.match(/[ "'$`(){}[\]]/)) {
-					// Escape single quotes within the string
-					return `'${str.replace(/'/g, `'\\''`)}'`;
-				}
-				return str;
-			}).join(' ');
+			s = args[i].map((x) => String(x)).join(' ');
 		} else {
 			s = String(args[i]);
 		}
 		cmd += s + pieces[++i];
 	}
 	return new SHDispatch(cmd, defaultOptions);
-}, setHandler);
-
+}, defaultOptionHandler);
 
 /**
-* Create a async/sync context in new execution callstack
-* @param {function} callback - async/sync 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()
-*		]);
-*   return 'res';
-* });
-*/
+ * Executes a callback in a new async context (fresh callstack).
+ *
+ * Useful for parallel operations without nesting.
+ *
+ * @param {() => Promise<any>} callback - Async function to execute.
+ * @returns {Promise<any>} Result of callback.
+ * @example
+ * const results = await within(async () => {
+ *   return Promise.all([SH`sleep 1; echo 1`.run(), sleep(2)]);
+ * });
+ */
 const within = async (callback) => {
 	return await callback();
 }
 
 /**
-* This function reads the standard input (stdin) from the current process.
-* @returns {Promise<string>}
-* @example 
-* const content = await readIn();
-*/
-/**
- * Read entire stdin as UTF-8. If stdin is a TTY, resolves to an empty string.
- * @returns {Promise<string|undefined>}
+ * Reads entire stdin as UTF-8 string. Resolves to empty string if TTY (no pipe).
+ *
+ * @returns {Promise<string>} Stdin content, or an empty string if TTY.
+ * @example
+ * const input = await readIn(); // Use in piped scripts
  */
 const readIn = async () => {
-	if (process.stdin.isTTY) return;   // nothing was piped
+	if (process.stdin.isTTY) return '';
 	let buf = '';
 	process.stdin.setEncoding('utf8');
 	for await (const chunk of process.stdin) {
@@ -227,17 +256,18 @@ const readIn = async () => {
 	return buf;
 }
 
-
 /**
-* Get user input from the command line (stdin)
-* void when input has been aborted
-* @param {string} prompt - prompt or question
-* @returns {{input: Promise<string|void>, abort: function(): void}}
-* @example 
-* const user = userIn('Question: ');
-* const content = await user.input
-* // user.abort() 
-*/
+ * Prompts user for input on stdin with custom prompt.
+ *
+ * Supports aborting input collection.
+ *
+ * @param {string} prompt - Prompt text to display.
+ * @returns {AbortableInput} Object with input Promise and abort function.
+ * @example
+ * const {input, abort} = userIn('Enter name: ');
+ * const name = await input;
+ * // abort(); // Cancel anytime
+ */
 const userIn = (prompt) => {
   let resolvePromise;
   const input = new Promise((resolve) => { resolvePromise = resolve; });
@@ -285,94 +315,110 @@ const userIn = (prompt) => {
     }
   };
 };
+
 /**
-* 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|number|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;
+ * Checks whether a value is a generator-like retry delay source.
+ *
+ * @param {unknown} value - Value to inspect.
+ * @returns {boolean} True when value has a callable `next()` method.
+ */
+const isDelayGenerator = (value) => value != null && typeof value == 'object' && typeof value.next == 'function';
+
+/**
+ * Retries an async function up to N times with optional delays.
+ *
+ * Delay can be fixed ('1s'), generator-like (expBackoff()), or none.
+ *
+ * @param {number} count - Positive integer number of attempts.
+ * @param {string|number|ExpBackoffGenerator|Function} delayOrCallback - Delay, delay generator, or callback if no separate callback is supplied.
+ * @param {Function} [callback] - Callback to retry when a delay is supplied.
+ * @returns {Promise<any>} Successful result.
+ * @throws {Error} If arguments are invalid, or the last callback error if all attempts fail.
+ * @example
+ * await retry(3, '1s', () => SH`curl http://unreliable`.run());
+ * await retry(3, expBackoff(), () => flakyOp());
+ */
+const retry = async (count, delayOrCallback, callback) => {
+	if (!Number.isInteger(count) || count < 1) {
+		throw new Error(`Invalid retry count: "${count}". Expected a positive integer.`);
+	}
+
+	let retryCallback;
 	let delayStatic = 0;
 	let delayGen;
-	// @ts-ignore
-	if (typeof a == 'function') {
-		callback = a;
+
+	if (typeof delayOrCallback == 'function') {
+		retryCallback = delayOrCallback;
 	}
 	else {
-		if (typeof a == 'object') {
-			delayGen = a;
+		if (typeof callback != 'function') {
+			throw new Error(`Invalid retry callback: expected a function.`);
+		}
+		retryCallback = callback;
+
+		if (isDelayGenerator(delayOrCallback)) {
+			delayGen = delayOrCallback;
+		}
+		else if (delayOrCallback != null && typeof delayOrCallback == 'object') {
+			throw new Error(`Invalid retry delay generator: expected an object with next().`);
 		}
 		else {
-			delayStatic = parseDuration(a);
+			delayStatic = parseDuration(delayOrCallback);
 		}
-		assert(b);
-		callback = b;
 	}
-	let lastErr;
-	let attempt = 0;
-	while (count-- > 0) {
-		attempt++;
+
+	for (let attempt = 1; attempt <= count; attempt++) {
 		try {
-			return await callback();
+			return await retryCallback();
 		}
 		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)
+			if (attempt == count) {
+				throw err;
+			}
+			const delay = delayGen ? delayGen.next().value : delayStatic;
+			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
-* 
-* await sleep('5s');
-*/
+ * Sleeps for a specified duration.
+ *
+ * @param {string|number} duration - Duration as '5s', '100ms', or ms number.
+ * @returns {Promise<void>}
+ * @example
+ * await sleep('2s');
+ */
 const sleep = (duration) => {
 	return new Promise((resolve) => {
 		setTimeout(resolve, parseDuration(duration));
 	});
 }
+
 /**
-* Change working directory
-* @param {string} dir
-*/
+ * Changes the current working directory.
+ *
+ * @param {string} dir - Path to new directory.
+ * @example
+ * cd('/tmp');
+ */
 const cd = (dir) => {
 	// @ts-ignore
 	process.chdir(dir);
 }
+
 /**
- * Generates an exponential backoff time with a random jitter.
+ * Generator for exponential backoff delays with 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.
+ * @param {string} [max='60s'] - Max backoff duration.
+ * @param {string} [rand='100ms'] - Max jitter.
+ * @yields {number} Next backoff ms.
+ * @example
+ * const backoff = expBackoff();
+ * await sleep(backoff.next().value);
  */
 function* expBackoff(max = '60s', rand = '100ms') {
 	const maxMs = parseDuration(max);
@@ -383,52 +429,63 @@ function* expBackoff(max = '60s', rand = '100ms') {
 		yield Math.min(2 ** n++, maxMs) + ms;
 	}
 }
+
 /**
-* Parses command-line arguments into an object.
-*
-* The function recognizes arguments that start with two dashes (`--`) or one dash (`-`) as keys,
-* and the subsequent value (if not another key) as the corresponding value.
-* If a key does not have a value, it defaults to `true`.
-* All unrecognized arguments are collected in an array under the `_` property.
-*
-* @param {string[]} [args] -  An array of command-line arguments (process.argv.slice(2)).
-* @returns {ArgsObject} An object where:
-*   - If args is not passed, process.argv.slice(2) will be the default
-*   - Each key corresponds to an argument that starts with `--` or `-`,
-*   - The value is either the next argument or `true` if no value is provided,
-*   - The `_` property contains an array of unbound arguments.
-*/
+ * Matches negative number tokens that should be parsed as values, not options.
+ *
+ * Supports decimal and exponent forms such as `-1`, `-0.5`, `-.5`, and `-1e3`.
+ *
+ * @param {string} arg - CLI argument token.
+ * @returns {boolean} True when the token is a negative numeric value.
+ */
+const isNegativeNumberArg = (arg) => /^-(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i.test(arg);
+
 /**
- * Parse command-line args into an object.
+ * Checks whether a token should be parsed as an option.
  *
- * Supported:
- * - --key value, -k value (no grouped short flags)
- * - Bare values collected under `_.`
- * - Duplicate keys throw an error; keys without a following value become true.
+ * Negative numeric values are intentionally excluded so calls like
+ * `parseArgs(['--n', '-1'])` parse `-1` as the value for `--n`.
  *
- * Not supported:
- * - --key=value syntax
- * - Grouped short flags like -abc
+ * @param {string} arg - CLI argument token.
+ * @returns {boolean} True when the token should be parsed as an option.
+ */
+const isOptionArg = (arg) => arg.startsWith('-') && !isNegativeNumberArg(arg);
+
+/**
+ * Parses CLI arguments into an object.
+ *
+ * Supports --key value, -k value (no shorts grouped).
+ * Bares go to _[]. Duplicates error. No = syntax.
+ * Negative number tokens such as -1, -0.5, and -1e3 are parsed as values or
+ * positionals, not options.
  *
- * @param {string[]} [args]
+ * Defaults to process.argv.slice(2).
+ *
+ * @param {string[]} [args=process.argv.slice(2)] - Args array.
  * @returns {ArgsObject}
+ * @throws {Error} On invalid/dupe args.
+ * @example
+ * parseArgs(['--port', '8080', 'file.txt']); // { port: '8080', _: ['file.txt'] }
+ * parseArgs(['--n', '-1']); // { n: '-1', _: [] }
  */
 const parseArgs = (args) => {
 	if (!args) args = process.argv.slice(2);
 	const result = { _: [] };
 	const seenKeys = new Set();
 	for (let i = 0; i < args.length; i++) {
-		if (args[i].startsWith('--') || args[i].startsWith('-')) {
-			if (args[i].startsWith('-') && !args[i].startsWith('--') && args[i].length > 2) {
-				throw new Error(`Invalid argument: ${args[i]}. Use '--' for long options.`);
+		const arg = args[i];
+
+		if (isOptionArg(arg)) {
+			if (arg.startsWith('-') && !arg.startsWith('--') && arg.length > 2) {
+				throw new Error(`Invalid argument: ${arg}. Use '--' for long options.`);
 			}
-			const key = args[i].startsWith('--') ? args[i].substring(2) : args[i].substring(1);
+			const key = arg.startsWith('--') ? arg.substring(2) : arg.substring(1);
 			if (seenKeys.has(key)) {
-				throw new Error(`Duplicate argument: ${args[i]}`);
+				throw new Error(`Duplicate argument: ${arg}`);
 			}
 			seenKeys.add(key);
 			let value;
-			if (args[i + 1] && !args[i + 1].startsWith('-')) {
+			if (i + 1 < args.length && !isOptionArg(args[i + 1])) {
 				value = args[i + 1];
 				i++; // Skip next element as it is a value
 			} else {
@@ -436,7 +493,7 @@ const parseArgs = (args) => {
 			}
 			result[key] = value;
 		} else {
-			result._.push(args[i]);
+			result._.push(arg);
 		}
 	}
 	// @ts-ignore