@j-o-r/sh 1.1.28 → 1.1.31

package/types/SH.d.ts

@@ -1,198 +1,220 @@
+/**
+ * Parsed command-line arguments.
+ *
+ * Named options map to their string value, or `true` when no value is supplied.
+ * Bare positional arguments are collected in `_`.
+ */
 export type ArgsObject = {
-    [x: string]: string;
+    _: string[];
+} & {
+    [x: string]: string | true | string[];
 };
 export type RejectCallback = Function;
 export type ResolveCallback = Function;
+export type SHOptions = import("./SHDispatch.js").SHOptions;
+export type AbortableInput = {
+    /**
+     * - Promise that resolves to user input or void if aborted.
+     */
+    input: Promise<string | void>;
+    /**
+     * - Function to abort input collection.
+     */
+    abort: () => void;
+};
+/**
+ * Generator-like object that yields retry delay durations.
+ */
+export type ExpBackoffGenerator = Iterator<number | string>;
 /**
- * Creates a new SHDispatch object that represents a command to be executed.
+ * 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();
  */
-export type Shell = Function;
+export const SH: any;
 /**
- * A template-tag that returns an SHDispatch.
+ * Changes the current working directory.
+ *
+ * @param {string} dir - Path to new directory.
+ * @example
+ * cd('/tmp');
  */
-export type SHTag = (pieces: TemplateStringsArray, ...args: unknown[]) => SHDispatch;
+export function cd(dir: string): void;
 /**
-* A template-tag that returns an SHDispatch.
-* @typedef {(pieces: TemplateStringsArray, ...args: unknown[]) => SHDispatch} SHTag
-*/
+ * Sleeps for a specified duration.
+ *
+ * @param {string|number} duration - Duration as '5s', '100ms', or ms number.
+ * @returns {Promise<void>}
+ * @example
+ * await sleep('2s');
+ */
+export function sleep(duration: string | number): Promise<void>;
 /**
-* 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}
-*/
-export const SH: Shell & SHTag & import("./SHDispatch.js").SHOptions;
+ * 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());
+ */
+export function retry(count: number, delayOrCallback: string | number | ExpBackoffGenerator | Function, callback?: Function): Promise<any>;
 /**
-* Change working directory
-* @param {string} dir
-*/
-export function cd(dir: string): void;
+ * 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
+ */
+export function readIn(): Promise<string>;
 /**
-* 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');
-*/
-export function sleep(duration: string | number): Promise<any>;
-/**
-* 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`);
-*/
-export function retry(count: number, a: string | number | typeof expBackoff | Function, b?: Function): Promise<any>;
-/**
-* 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>}
- */
-export function readIn(): Promise<string | undefined>;
-/**
-* 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()
-*/
-export function userIn(prompt: string): {
-    input: Promise<string | void>;
-    abort: () => void;
-};
+ * 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
+ */
+export function userIn(prompt: string): AbortableInput;
+/**
+ * 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)]);
+ * });
+ */
+export function within(callback: () => Promise<any>): Promise<any>;
 /**
-* 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';
-* });
-*/
-export function within(callback: Function): Promise<any>;
-/**
- * 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);
  */
 export function expBackoff(max?: string, rand?: string): Generator<number, void, unknown>;
 /**
-* 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.
- *
- * 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.
- *
- * Not supported:
- * - --key=value syntax
- * - Grouped short flags like -abc
- *
- * @param {string[]} [args]
+ * 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.
+ *
+ * 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', _: [] }
  */
 export function parseArgs(args?: string[]): ArgsObject;
 /**
-* @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 {Function} RejectCallback
-* @param {Error} error - The error object passed to the callback.
-*/
-/**
-* @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();
-*/
-/**
-* Determine a javascript type
-*
-* @param {any} fn - Any let type
-* @returns {string} The "real" object / typeof name
-*/
+ * 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 {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.
+ */
+/**
+ * Generator-like object that yields retry delay durations.
+ *
+ * @typedef {Iterator<number|string>} ExpBackoffGenerator
+ */
+/**
+ * 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'
+ */
 export function jsType(fn: any): string;
 /**
-* '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.
+ */
 export function hasProp(o: any, p: string): boolean;
 import Test from './Test.js';
 import assert from 'node:assert';
 import AsyncTracker from './AsyncTracker.js';
 /**
-* bash escape a string suitable as an argument on the commandline
-* for javascript code
-* @param {string} x
-* @returns {string}
-*/
-export function bashEscape(x: string): string;
-import SHDispatch from './SHDispatch.js';
+ * 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();
+ */
+export function bashEscape(x: unknown): string;
 export { Test, assert, AsyncTracker };

package/types/SHDispatch.d.ts

@@ -1,113 +1,128 @@
 export default SHDispatch;
 export type SpawnSyncResponse = {
     /**
-     * - Exit code of the child process (null if terminated by signal).
+     * - Exit code (null if signal).
      */
     status: number | null;
     /**
-     * - Name of the terminating signal, if any.
+     * - Terminating signal.
      */
     signal: string | null;
     /**
-     * - [stdin, stdout, stderr] per Node's SpawnSyncReturns.
+     * - [stdin, stdout, stderr].
      */
     output: (string | Buffer | null)[];
     /**
-     * - PID of the spawned process.
+     * - Process ID.
      */
     pid: number;
     /**
-     * - Stdout collected (type depends on encoding option).
+     * - Captured stdout.
      */
     stdout: string | Buffer | null;
     /**
-     * - Stderr collected (type depends on encoding option).
+     * - Captured stderr.
      */
     stderr: string | Buffer | null;
 };
+export type StdioOption = ("pipe" | "ignore" | "inherit" | number);
+export type StdioOptions = Array<StdioOption> | StdioOption;
+/**
+ * Core options for SH/SHDispatch.
+ *
+ * Defaults (merged from global SH):
+ * - `cwd`: `process.cwd()`
+ * - `env`: `process.env`
+ * - `shell`: `'bash'` (string/true → shell; false → no-shell `/usr/bin/env -S`)
+ * - `stdio`: `['inherit', 'pipe', 'pipe']`
+ * - `timeout`: `0` (no timeout; rolling on data)
+ * - `maxBuffer`: `512000` (500 kb per stream in SHExecute)
+ *
+ * Prefix (`.options(undefined, prefix)`) only for shell mode.
+ */
 export type SHOptions = {
     /**
-     * - Current working directory of the child process.
+     * - Working directory for spawned commands.
      */
-    cwd?: string | undefined;
-    /**
-     * - Environment key-value pairs.
-     */
-    env?: Object | undefined;
-    /**
-     * - Explicitly set the value of `argv[0]` sent to the child process.
-     */
-    argv0?: string | undefined;
-    /**
-     * - If true, the child will be a process group leader.
-     */
-    detached?: boolean | undefined;
+    cwd: string;
     /**
-     * - Sets the user identity of the process.
+     * - Environment for spawned commands.
      */
-    uid?: number | undefined;
+    env: NodeJS.ProcessEnv;
     /**
-     * - Sets the group identity of the process.
+     * - Shell executable, true for bash, or false for no-shell mode.
      */
-    gid?: number | undefined;
+    shell: string | boolean;
     /**
-     * - Child's stdio configuration.
+     * - Stdio config passed to child_process.
      */
-    stdio?: number | "pipe" | "ignore" | "inherit" | StdioOption[] | undefined;
+    stdio: StdioOptions;
     /**
-     * - If string or true, runs the command via that shell ('bash' if true).
+     * - Rolling timeout in ms or duration string; 0 disables timeout.
      */
-    shell?: string | boolean | undefined;
+    timeout: number | string;
     /**
-     * - Milliseconds before sending SIGTERM (0 = no timeout).
+     * - Maximum buffered bytes per stdout/stderr stream.
      */
-    timeout?: number | undefined;
+    maxBuffer?: number | undefined;
     /**
-     * - Optional stdin payload for spawnSync. Use .run(payload) for async.
+     * - Run process detached and resolve early.
      */
-    input?: string | Uint8Array<ArrayBufferLike> | Buffer<ArrayBufferLike> | undefined;
+    detached?: boolean | undefined;
 };
-export type StdioOption = ("pipe" | "ignore" | "inherit" | number);
-export type StdioOptions = Array<StdioOption> | StdioOption;
 /**
- * SHOptions — effective defaults and semantics used by SHDispatch/SHExecute
+ * High-level command dispatcher.
  *
- * Defaults:
- * - cwd: process.cwd()
- * - env: process.env
- * - shell: 'bash' (string). If a string, that shell is used. If true, 'bash' is used. If false/undefined, no shell is used.
- * - stdio: ['inherit', 'pipe', 'pipe'] — inherit stdin, capture stdout/stderr
- * - timeout: 0 — no timeout
- * - maxBuffer?: number — optional (bytes per stream). Passed through to SHExecute.
+ * Created by {@link SH`cmd`}; chain `.options()` then `.run()`.
  *
- * Notes:
- * - The prefix (see options(prefix)) is only applied when a shell is used; it is ignored in no-shell mode.
- * - Each call to options() resets to the defaults and merges the provided options; it does not accumulate from prior calls.
+ * Delegates to {@link SHExecute} for exec/timeout/buffer/kill.
+ *
+ * @example
+ * const dispatch = SH`ls -la`.options({ timeout: '2s' });
+ * const out = await dispatch.run();
  */
 declare class SHDispatch {
     /**
-    * @param {string} cmd - cmd to execute
-    * @param {SHOptions} options
-    * @param {string} [prefix] - command prefix e.g (default) '/usr/bin/env'
-    */
-    constructor(cmd: string, options: SHOptions, prefix?: string);
-    /**
-    * @param {SHOptions} [options]
-    * @param {string} [prefix] - command prefix e.g (default) '/usr/bin/env'
-    * @returns {SHDispatch}
-    */
-    options(options?: SHOptions, prefix?: string): SHDispatch;
-    /**
-    * @param {string} [payload]
-    * @returns {Promise<string>}
-    */
+     * @param {string} cmd - Command string.
+     * @param {Partial<SHOptions>} [options] - Initial options.
+     * @param {string} [prefix] - Shell prefix (e.g., 'set -euo pipefail').
+     * @throws {Error} Invalid/empty cmd.
+     */
+    constructor(cmd: string, options?: Partial<SHOptions>, prefix?: string);
+    /**
+     * Updates options/prefix by merging into the dispatch instance's current options.
+     *
+     * This preserves global `SH.*` defaults captured when the command was created
+     * and only overrides options explicitly supplied for this command. Strings for
+     * `stdio` are expanded to `[value, value, value]`.
+     *
+     * @param {Partial<SHOptions>} [options] - New options.
+     * @param {string} [prefix] - New prefix.
+     * @returns {SHDispatch} Self for chaining.
+     */
+    options(options?: Partial<SHOptions>, prefix?: string): SHDispatch;
+    /**
+     * Async run: Captures stdout; rejects on error/timeout.
+     *
+     * @param {string} [payload] - Stdin payload.
+     * @returns {Promise<string>} Stdout.
+     */
     run(payload?: string): Promise<string>;
     /**
-    * Works for terminal screen takeovers like editors
-    * @param {string} [payload]
-    * @returns {import('child_process').SpawnSyncReturns}
-    */
-    runSync(payload?: string): import("child_process").SpawnSyncReturns<any>;
-    kill(signal?: string): Promise<number[]>;
+     * Sync run: Full Node SpawnSyncReturns.
+     *
+     * Good for TTY takeovers (e.g., vim).
+     *
+     * @param {string} [payload] - Stdin payload.
+     * @returns {import('child_process').SpawnSyncReturns<Buffer>}
+     */
+    runSync(payload?: string): import("child_process").SpawnSyncReturns<Buffer>;
+    /**
+     * Kills running process + children.
+     *
+     * @param {number | string} [signal='SIGTERM'] - Signal.
+     * @returns {Promise<number[]>} Killed PIDs.
+     */
+    kill(signal?: number | string): Promise<number[]>;
     #private;
 }