@j-o-r/sh/types/SHExecute.d.ts

Execute shell commands on Linux-based systems from javascript

export default SHExecute;
export type SHExecuteOptions = any & {
    maxBuffer?: number;
};
/**
 * @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.
 *
 * @example
 * const exec = new SHExecute('ls', 'set -euo pipefail', { timeout: '5s' });
 * const out = await exec.run();
 */
declare class SHExecute {
    /**
     * @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?: SHExecuteOptions);
    /**
     * 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<Buffer>;
    /**
     * 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>;
    /**
     * 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;
}