@j-o-r/sh 1.1.28 → 1.1.31

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;

package/types/Test.d.ts

@@ -1,68 +1,104 @@
 export default Test;
-export type AsyncFunction = (() => Promise<any>);
-export type testDefinition = {
+export type AsyncFunction = () => Promise<any>;
+export type TestDefinition = {
+    /**
+     * - Test name/description.
+     */
     description: string;
     /**
-     * - syc/ async function
+     * - Sync/async test function.
      */
     callback: Function | AsyncFunction;
 };
-export type testReport = {
+export type TestReport = {
+    /**
+     * - Test description.
+     */
     description: string;
     /**
-     * - start time in MS
+     * - Execution duration (ms).
      */
     duration: number;
     /**
-     * - Has it been called?
+     * - Whether the test ran.
      */
     executed: boolean;
 };
-export type Report = {
+export type TestReportSummary = {
+    /**
+     * - Total tests defined.
+     */
     tests: number;
     /**
-     * - start time in MS
+     * - Total execution time (ms).
      */
     duration: number;
     /**
-     * - number of errors
+     * - Number of failures.
      */
     errors: number;
     /**
-     * - number of tests executed
+     * - Number of tests run.
      */
     executed: number;
 };
 declare class Test {
     /**
-    * @param {boolean} [quiet] - does not output a report when true, default `false`
-    */
+     * Creates a test runner instance.
+     *
+     * Tracks tests, errors, unresolved promises via {@link AsyncTracker}.
+     * Supports sync/async callbacks; detects global errors.
+     *
+     * @param {boolean} [quiet=false] - Suppress console reports.
+     * @example
+     * const t = new Test();
+     * t.add('basic', () => { throw new Error('fail'); });
+     * const report = await t.run();
+     */
     constructor(quiet?: boolean);
     /**
-    * Set the timeout when a synced function is called.
-    * This settles async code used in a sync function
-    * and give some time to catch errors (#HACK)
-    * @param {number} timeout - in MS, default 50
-    */
+     * Sets timeout for settling async in sync tests (hack for late errors).
+     *
+     * @param {number} timeout - Timeout (ms); default 50.
+     * @example
+     * t.syncTimeout(100);
+     */
     syncTimeout(timeout: number): void;
     /**
-    *
-    * @param {string} description
-    * @param {Function|AsyncFunction} callback - sync / async function
-    * @throws Error when conditions are not met
-    * @returns {Test}
-    */
+     * Adds a test case.
+     *
+     * @param {string} description - Test name.
+     * @param {Function | AsyncFunction} callback - Test function.
+     * @returns {Test} Self for chaining.
+     * @throws {Error} Invalid description (non-string) or callback (not function).
+     * @example
+     * t.add('check 1+1', () => expect(1+1).toBe(2));
+     */
     add(description: string, callback: Function | AsyncFunction): Test;
     /**
-    * Execute tests
-    * @param {number[]} [execute] - limit the execution tests
-    * @returns {Promise<Report>}
-    */
-    run(execute?: number[]): Promise<Report>;
+     * Runs tests (all or selected); returns summary.
+     *
+     * Prints progress/errors; checks unresolved promises post-run.
+     *
+     * @param {number[]} [execute] - Indices of tests to run (default: all).
+     * @returns {Promise<TestReportSummary>} Summary stats.
+     * @example
+     * await t.run([0, 2]); // Run tests 0 and 2
+     */
+    run(execute?: number[]): Promise<TestReportSummary>;
+    /**
+     * Prints unresolved promises report (if any).
+     *
+     * @example
+     * t.unresolved();
+     */
     unresolved(): void;
     /**
-    * Empty tests
-    */
+     * Resets all tests, reports, errors, tracker.
+     *
+     * @example
+     * t.reset();
+     */
     reset(): void;
     #private;
 }