63 lines
2.3 KiB
TypeScript
63 lines
2.3 KiB
TypeScript
|
import { SpawnOptions } from "node:child_process";
|
||
|
|
|
||
|
|
//#region src/server/exec.d.ts
|
||
|
|
interface ExecOptions {
|
||
|
|
signal?: AbortSignal;
|
||
|
|
timeout?: number;
|
||
|
|
stdin?: string;
|
||
|
|
spawnOptions?: SpawnOptions;
|
||
|
|
throwOnNonZeroExitCode?: boolean;
|
||
|
|
}
|
||
|
|
interface ExecResult {
|
||
|
|
pid: number | undefined;
|
||
|
|
stderr: string;
|
||
|
|
stdout: string;
|
||
|
|
exitCode: number | null;
|
||
|
|
}
|
||
|
|
/**
|
||
|
|
* Executes a command and captures its output.
|
||
|
|
*
|
||
|
|
* This function spawns a child process, collects its stdout and stderr, and resolves with the
|
||
|
|
* process result when execution finishes. By default, it throws an {@link ExecError} when the
|
||
|
|
* process exits with a non-zero exit code.
|
||
|
|
*
|
||
|
|
* @param {string} _command - The command to execute.
|
||
|
|
* @param {string[]} args - The arguments passed to the command.
|
||
|
|
* @param {ExecOptions} options - The options object.
|
||
|
|
* @param {AbortSignal} options.signal - An optional AbortSignal used to abort the process.
|
||
|
|
* @param {number} options.timeout - An optional timeout in milliseconds. When provided, the
|
||
|
|
* process is aborted after the timeout expires.
|
||
|
|
* @param {string} options.stdin - An optional string written to the process stdin.
|
||
|
|
* @param {SpawnOptions} options.spawnOptions - Additional options forwarded to `child_process.spawn`.
|
||
|
|
* @param {boolean} options.throwOnNonZeroExitCode - Whether to throw an {@link ExecError} when the
|
||
|
|
* process exits with a non-zero exit code. Defaults to `true`.
|
||
|
|
* @returns {Promise<ExecResult>} A promise that resolves with the process result.
|
||
|
|
* @throws {ExecError} Throws when `throwOnNonZeroExitCode` is enabled and the process exits with a
|
||
|
|
* non-zero exit code.
|
||
|
|
*
|
||
|
|
* @example
|
||
|
|
* const result = await exec('echo', ['hello']);
|
||
|
|
*
|
||
|
|
* console.log(result.stdout.trim());
|
||
|
|
* // => 'hello'
|
||
|
|
*
|
||
|
|
* @example
|
||
|
|
* const result = await exec('git', ['diff', '--quiet'], {
|
||
|
|
* throwOnNonZeroExitCode: false,
|
||
|
|
* });
|
||
|
|
*
|
||
|
|
* console.log(result.exitCode);
|
||
|
|
* // => 1 when there are changes
|
||
|
|
*/
|
||
|
|
declare function exec(_command: string, args?: string[], options?: ExecOptions): Promise<ExecResult>;
|
||
|
|
/**
|
||
|
|
* Represents an error thrown when a process exits with a non-zero exit code.
|
||
|
|
*
|
||
|
|
* @param {ExecResult} result - The captured process result.
|
||
|
|
*/
|
||
|
|
declare class ExecError extends Error {
|
||
|
|
readonly result: ExecResult;
|
||
|
|
constructor(result: ExecResult);
|
||
|
|
}
|
||
|
|
//#endregion
|
||
|
|
export { ExecError, exec };
|