@j-o-r/sh 1.1.28 → 1.1.29

package/types/SH.d.ts

@@ -3,196 +3,189 @@ export type ArgsObject = {
 };
 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;
+};
+export type ExpBackoffGenerator = Object;
 /**
- * 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:
+ * - 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' '/'
  */
-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;
-/**
-* A template-tag that returns an SHDispatch.
-* @typedef {(pieces: TemplateStringsArray, ...args: unknown[]) => SHDispatch} SHTag
-*/
+export function cd(dir: string): 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;
+ * 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>;
 /**
-* Change working directory
-* @param {string} dir
-*/
-export function cd(dir: string): void;
+ * 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());
+ */
+export function retry(count: number, a: any, b: any): Promise<any>;
 /**
-* 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>}
+ * 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
  */
 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;
 /**
-* 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.
+ * 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>;
+/**
+ * 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.
+ *
+ * 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'] }
  */
 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
-*/
+ * @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} 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.
+ */
+/**
+ * @typedef {Object} ExpBackoffGenerator
+ * @generator
+ * @yields {number} Backoff time in ms.
+ */
+/**
+ * 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}
-*/
+ * 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.
+ */
 export function bashEscape(x: string): string;
-import SHDispatch from './SHDispatch.js';
 export { Test, assert, AsyncTracker };

package/types/SHDispatch.d.ts

@@ -1,113 +1,90 @@
 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 SHOptions = {
-    /**
-     * - Current working directory of the child process.
-     */
-    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;
-    /**
-     * - Sets the user identity of the process.
-     */
-    uid?: number | undefined;
-    /**
-     * - Sets the group identity of the process.
-     */
-    gid?: number | undefined;
-    /**
-     * - Child's stdio configuration.
-     */
-    stdio?: number | "pipe" | "ignore" | "inherit" | StdioOption[] | undefined;
-    /**
-     * - If string or true, runs the command via that shell ('bash' if true).
-     */
-    shell?: string | boolean | undefined;
-    /**
-     * - Milliseconds before sending SIGTERM (0 = no timeout).
-     */
-    timeout?: number | undefined;
-    /**
-     * - Optional stdin payload for spawnSync. Use .run(payload) for async.
-     */
-    input?: string | Uint8Array<ArrayBufferLike> | Buffer<ArrayBufferLike> | 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.
+ *
+ * Created by {@link SH`cmd`}; chain `.options()` then `.run()`.
  *
- * 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.
+ * Delegates to {@link SHExecute} for exec/timeout/buffer/kill.
  *
- * 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.
+ * @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 {string} cmd - Command string.
+     * @param {Partial<typeof SHOptions>} [options] - Initial options.
+     * @param {string} [prefix] - Shell prefix (e.g., 'set -euo pipefail').
+     * @throws {Error} Invalid/empty cmd.
+     */
+    constructor(cmd: string, options?: Partial<typeof 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;
+     * Updates options/prefix; resets to defaults + user overrides (non-cumulative).
+     *
+     * Strings for `stdio` → array fill.
+     *
+     * @param {Partial<typeof SHOptions>} [options] - New options.
+     * @param {string} [prefix] - New prefix.
+     * @returns {SHDispatch} Self for chaining.
+     */
+    options(options?: Partial<typeof SHOptions>, prefix?: string): SHDispatch;
     /**
-    * @param {string} [payload]
-    * @returns {Promise<string>}
-    */
+     * 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;
 }
+declare namespace SHOptions {
+    let cwd: string;
+    let env: NodeJS.ProcessEnv;
+    let shell: string;
+    let stdio: string[];
+    let timeout: number;
+}

package/types/SHExecute.d.ts

@@ -1,39 +1,60 @@
 export default SHExecute;
+export type SHExecuteOptions = any & {
+    maxBuffer?: number;
+};
 /**
- * SHExecute
- * Low-level process runner used by SHDispatch.
+ * @typedef {import('../SH.js').SHOptions & { maxBuffer?: number }} SHExecuteOptions
+ * @description Extended options for SHExecute: adds `maxBuffer` (bytes per stream, default 1MB).
+ */
+/**
+ * Low-level process executor for shell commands.
+ *
+ * Used internally by {@link SHDispatch}.
+ *
+ * Key features:
+ * - **Shell mode**: If `options.shell` is string/true, runs `${prefix}; ${command}` via shell ('bash' default).
+ * - **No-shell mode**: Uses `/usr/bin/env -S ${command}` for direct exec (ignores prefix).
+ * - **Rolling timeout**: `options.timeout` (ms/'2s'); resets on stdout/stderr data. SIGTERM on expiry.
+ * - **Buffering**: Captures stdout/stderr up to `maxBuffer` (1MB default); appends truncation markers.
+ * - **Payload**: `run(payload)` writes string to stdin (forces pipe).
+ * - **Detached**: If `options.detached`, resolves early (~1s) and unrefs.
+ * - **Kill**: Terminates process + children via pgrep.
  *
- * Features:
- * - Optional shell execution: if options.shell is a string (e.g., 'bash') or true, runs `${prefix}; ${command}` via that shell; otherwise runs without a shell using `/usr/bin/env -S`.
- * - Timeout: options.timeout may be a number (ms) or string like '1500ms' or '2s'. On timeout, run() rejects with a descriptive error.
- * - Buffering: Captures stdout/stderr up to maxBuffer bytes per stream (default 40 MiB). Appends "[stdout truncated]" / "[stderr truncated]" markers if exceeded.
- * - Payload: Passing a payload writes it to stdin and forces stdin to be a pipe.
- * - Detached mode: If options.detached is true, run() resolves to '' after ~1s and unrefs the process.
- * - Kill support: kill(signal) attempts to terminate the process (and some children) and causes run() to reject with "Process killed (forced).".
+ * @example
+ * const exec = new SHExecute('ls', 'set -euo pipefail', { timeout: '5s' });
+ * const out = await exec.run();
  */
 declare class SHExecute {
     /**
-     * @param {string} command - linux command to be executed
-     * @param {string} prefix  - command prefix (shell prelude, e.g. 'set -euo pipefail')
-     * @param {import('child_process').SpawnOptions & { maxBuffer?: number }} options
+     * @param {string} command - Command to execute.
+     * @param {string} prefix - Shell prelude (e.g., 'set -euo pipefail'); ignored in no-shell.
+     * @param {SHExecuteOptions} [options] - Spawn options + maxBuffer/timeout.
      */
-    constructor(command: string, prefix: string, options?: import("child_process").SpawnOptions & {
-        maxBuffer?: number;
-    });
+    constructor(command: string, prefix: string, options?: SHExecuteOptions);
     /**
-     * @param {string} [payload] - data to write
-     * @returns {import('child_process').SpawnSyncReturns}
+     * Synchronous execution.
+     *
+     * @param {string} [payload] - Stdin data (forces pipe).
+     * @returns {import('child_process').SpawnSyncReturns<Buffer>}
+     * @throws {Error} Invalid payload type.
      */
-    runSync(payload?: string): import("child_process").SpawnSyncReturns<any>;
+    runSync(payload?: string): import("child_process").SpawnSyncReturns<Buffer>;
     /**
-     * @param {string} [payload] - data to write
-     * @returns {Promise<string>}
+     * Asynchronous execution with buffering/timeout/kill.
+     *
+     * Resolves stdout (trimmed) on success; rejects on error/timeout/kill.
+     *
+     * @param {string} [payload] - Stdin data (forces pipe).
+     * @returns {Promise<string>} Trimmed UTF-8 stdout (+ truncation marker if exceeded).
+     * @throws {Error} Command failure (incl. code, stderr), timeout, kill, spawn error.
      */
     run(payload?: string): Promise<string>;
     /**
-     * Kill this process and possible child processes
-     * @param {number | string} signal - kill signal
-     * @returns {Promise<number[]>}
+     * Terminates process and its children (via pgrep).
+     *
+     * @param {number | string} [signal='SIGTERM'] - Signal to send.
+     * @returns {Promise<number[]>} Killed PIDs.
+     * @throws {Error} No process/PID.
      */
     kill(signal?: number | string): Promise<number[]>;
     #private;