spawn-rx/lib/index.d.ts

An Rx-version of child_process.spawn

import { type SpawnOptions } from "node:child_process";
import * as sfs from "node:fs";
import { Observable } from "rxjs";
/**
 * Custom error class for spawn operations with additional metadata
 */
export declare class SpawnError extends Error {
    readonly exitCode: number;
    readonly code: number;
    readonly stdout?: string;
    readonly stderr?: string;
    readonly command: string;
    readonly args: string[];
    constructor(message: string, exitCode: number, command: string, args: string[], stdout?: string, stderr?: string);
}
/**
 * Process metadata tracked during execution
 */
export interface ProcessMetadata {
    pid: number;
    startTime: number;
    command: string;
    args: string[];
}
/**
 * stat a file but don't throw if it doesn't exist
 *
 * @param  {string} file The path to a file
 * @return {Stats}       The stats structure
 *
 * @private
 */
export declare function statSyncNoException(file: string): sfs.Stats | null;
/**
 * stat a file but don't throw if it doesn't exist
 *
 * @param  {string} file The path to a file
 * @return {Stats}       The stats structure
 *
 * @private
 */
export declare function statNoException(file: string): Promise<sfs.Stats | null>;
export type CmdWithArgs = {
    cmd: string;
    args: string[];
};
/**
 * Finds the actual executable and parameters to run on Windows. This method
 * mimics the POSIX behavior of being able to run scripts as executables by
 * replacing the passed-in executable with the script runner, for PowerShell,
 * CMD, and node scripts.
 *
 * This method also does the work of running down PATH, which spawn on Windows
 * also doesn't do, unlike on POSIX.
 *
 * @param  {string} exe           The executable to run
 * @param  {string[]} args   The arguments to run
 *
 * @return {Object}               The cmd and args to run
 * @property {string} cmd         The command to pass to spawn
 * @property {string[]} args The arguments to pass to spawn
 */
export declare function findActualExecutable(exe: string, args: string[]): CmdWithArgs;
export type SpawnRxExtras = {
    stdin?: Observable<string>;
    echoOutput?: boolean;
    split?: boolean;
    encoding?: BufferEncoding;
    /**
     * Timeout in milliseconds. If the process doesn't complete within this time,
     * it will be killed and the observable will error with a TimeoutError.
     */
    timeout?: number;
    /**
     * Number of retry attempts if the process fails (non-zero exit code).
     * Defaults to 0 (no retries).
     */
    retries?: number;
    /**
     * Delay in milliseconds between retry attempts. Defaults to 1000ms.
     */
    retryDelay?: number;
};
export type OutputLine = {
    source: "stdout" | "stderr";
    text: string;
};
/**
 * Utility type to extract the return type based on split option
 */
export type SpawnResult<T extends SpawnRxExtras> = T extends {
    split: true;
} ? Observable<OutputLine> : Observable<string>;
/**
 * Utility type to extract the promise return type based on split option
 */
export type SpawnPromiseResult<T extends SpawnRxExtras> = T extends {
    split: true;
} ? Promise<[string, string]> : Promise<string>;
/**
 * Spawns a process attached as a child of the current process.
 *
 * @param  {string} exe               The executable to run
 * @param  {string[]} params     The parameters to pass to the child
 * @param  {SpawnOptions & SpawnRxExtras} opts              Options to pass to spawn.
 *
 * @return {Observable<OutputLine>}       Returns an Observable that when subscribed
 *                                    to, will create a child process. The
 *                                    process output will be streamed to this
 *                                    Observable, and if unsubscribed from, the
 *                                    process will be terminated early. If the
 *                                    process terminates with a non-zero value,
 *                                    the Observable will terminate with onError.
 */
export declare function spawn(exe: string, params: string[], opts: SpawnOptions & SpawnRxExtras & {
    split: true;
}): Observable<OutputLine>;
/**
 * Spawns a process attached as a child of the current process.
 *
 * @param  {string} exe               The executable to run
 * @param  {string[]} params     The parameters to pass to the child
 * @param  {SpawnOptions & SpawnRxExtras} opts              Options to pass to spawn.
 *
 * @return {Observable<string>}       Returns an Observable that when subscribed
 *                                    to, will create a child process. The
 *                                    process output will be streamed to this
 *                                    Observable, and if unsubscribed from, the
 *                                    process will be terminated early. If the
 *                                    process terminates with a non-zero value,
 *                                    the Observable will terminate with onError.
 */
export declare function spawn(exe: string, params: string[], opts?: SpawnOptions & SpawnRxExtras & {
    split: false | undefined;
}): Observable<string>;
/**
 * Spawns a process as a child process.
 *
 * @param  {string} exe               The executable to run
 * @param  {string[]} params     The parameters to pass to the child
 * @param  {SpawnOptions & SpawnRxExtras} opts              Options to pass to spawn.
 *
 * @return {Promise<[string, string]>}       Returns an Promise that represents a child
 *                                 process. The value returned is the process
 *                                 output. If the process terminates with a
 *                                 non-zero value, the Promise will resolve with
 *                                 an Error.
 */
export declare function spawnPromise(exe: string, params: string[], opts: SpawnOptions & SpawnRxExtras & {
    split: true;
}): Promise<[string, string]>;
/**
 * Spawns a process as a child process.
 *
 * @param  {string} exe               The executable to run
 * @param  {string[]} params     The parameters to pass to the child
 * @param  {SpawnOptions & SpawnRxExtras} opts              Options to pass to spawn.
 *
 * @return {Promise<string>}       Returns an Promise that represents a child
 *                                 process. The value returned is the process
 *                                 output. If the process terminates with a
 *                                 non-zero value, the Promise will resolve with
 *                                 an Error.
 */
export declare function spawnPromise(exe: string, params: string[], opts?: SpawnOptions & SpawnRxExtras): Promise<string>;