@j-o-r/sh 1.1.28 → 1.1.29

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,47 @@ 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.
-*/
+ * @typedef {Object.<string, string>} ArgsObject
+ * @property {string[]} _ - Array of strings, unnamed parameters
+ * @property {string} [key: string] - Any string key maps to a string value
+ * @description Parsed parameters result.
+ */
+
 /**
-* @typedef {Function} RejectCallback
-* @param {Error} error - The error object passed to the callback.
-*/
+ * @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} ResolveCallback
+ * @param {any} [param] - Optional callback any value
+ */
+
 /**
-* 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();
-*/
+ * @typedef {import('./SHDispatch.js').SHOptions} SHOptions
+ */
+
+/**
+ * @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.
+ */
+
+/**
+ * @typedef {Object} ExpBackoffGenerator
+ * @generator
+ * @yields {number} Backoff time in ms.
+ */
 
 /**
-* 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,21 +81,26 @@ 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: '5s' (5000ms), '100ms' (100ms), plain numbers (ms).
+ *
+ * @param {number|string} d - Duration as number (ms) or string ('5s', '100ms').
+ * @returns {number} Duration in milliseconds.
+ * @throws {Error} If invalid duration format.
+ */
 const parseDuration = (d) => {
 	if (typeof d == 'number') {
 		if (isNaN(d) || d < 0)
@@ -103,12 +115,15 @@ const parseDuration = (d) => {
 	}
 	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}
-*/
+ * Escapes a string for safe use as a bash command-line argument.
+ *
+ * Handles quotes, backticks, $, newlines, etc.
+ *
+ * @param {string} x - Input string to escape.
+ * @returns {string} Bash-escaped string.
+ */
 const bashEscape = (x) => {
 	let str = String(x).trim();
 	// the trick is to double escape escape vars first
@@ -125,8 +140,7 @@ const bashEscape = (x) => {
 	return str;
 }
 
-
-/** @type {import('./SHDispatch.js').SHOptions} */
+/** Default options applied to all SH commands unless overridden. */
 const defaultOptions = {
 	cwd: process.cwd(),
 	env: process.env,
@@ -135,30 +149,36 @@ const defaultOptions = {
 	timeout: 0, // when 0 there is no timeout
 };
 
+/** Proxy set trap for dynamically updating defaultOptions via SH.prop = value */
 const setHandler = {
   set(target, prop, value) {
-    defaultOptions[prop] = value;  // Allow setting on target
-    // console.log(`Set ${String(prop)} = ${value}`);
-    // console.log(defaultOptions);
+    defaultOptions[prop] = value;
     return true;
   }
 }
 
 /**
-* A template-tag that returns an SHDispatch.
-* @typedef {(pieces: TemplateStringsArray, ...args: unknown[]) => SHDispatch} SHTag
-*/
-/**
-* 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:
+ * - Arrays: Elements trimmed, newlines/tabs escaped, shell-special chars single-quoted with '\'' escape.
+ * - Other values: String(value) inserted as-is (NOT auto-escaped; use {@link bashEscape} for safety).
+ *
+ * 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
+ * SH`ls ${['-la', '/']}`.run(); // ls '-la' '/'
+ */
 const SH = new Proxy(function(pieces, ...args) {
 	if (pieces.some((p) => p == undefined)) {
 		throw new Error(`Malformed command ${pieces}`);
@@ -188,37 +208,31 @@ const SH = new Proxy(function(pieces, ...args) {
 	return new SHDispatch(cmd, defaultOptions);
 }, setHandler);
 
-
 /**
-* 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|undefined>} Stdin content or undefined 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 +241,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,27 +300,22 @@ 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`);
-*/
+ * Retries an async function up to N times with optional delays.
+ *
+ * Delay can be fixed ('1s'), generator (expBackoff()), or none.
+ *
+ * @param {number} count - Number of attempts.
+ * @param {string|number|ExpBackoffGenerator|Function} delayOrFn - Delay or callback if no separate fn.
+ * @param {Function} [fn] - Callback to retry (if delayOrFn not function).
+ * @returns {Promise<any>} Successful result.
+ * @throws {Error} Last error if all attempts fail.
+ * @example
+ * await retry(3, '1s', () => SH`curl http://unreliable`.run());
+ * await retry(3, expBackoff(), () => flakyOp());
+ */
 const retry = async (count, a, b) => {
-	// const total = count;
 	let callback;
 	let delayStatic = 0;
 	let delayGen;
@@ -345,34 +355,43 @@ 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
-* 
-* 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,35 +402,20 @@ 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.
-*/
-/**
- * Parse command-line args into an object.
+ * Parses CLI arguments into an object.
  *
- * 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.
+ * Supports --key value, -k value (no shorts grouped).
+ * Bares go to _[]. Duplicates error. No = syntax.
  *
- * Not supported:
- * - --key=value syntax
- * - Grouped short flags like -abc
+ * Defaults to process.argv.slice(2).
  *
- * @param {string[]} [args]
+ * @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'] }
  */
 const parseArgs = (args) => {
 	if (!args) args = process.argv.slice(2);