spawn

Spawn a process with advanced ways to configure and control it.

Usage

import {spawn} from 'dollar-shell';

Docs

The TypeScript declaration:

type SpawnStreamState = 'pipe' | 'ignore' | 'inherit' | 'piped' | null;

interface SpawnOptions {
  cwd?: string;
  env?: {[key: string]: string | undefined};
  stdin?: SpawnStreamState;
  stdout?: SpawnStreamState;
  stderr?: SpawnStreamState;
}

interface Subprocess<R = string> {
  readonly command: string[];
  readonly options: SpawnOptions | undefined;
  readonly exited: Promise<number>;
  readonly finished: boolean;
  readonly killed: boolean;
  readonly exitCode: number | null;
  readonly signalCode: string | null;
  readonly stdin: WritableStream<R> | null;
  readonly stdout: ReadableStream<R> | null;
  readonly stderr: ReadableStream<R> | null;
  readonly asDuplex: DuplexPair<R>;
  kill(): void;
}

declare function spawn(command: string[], options?: SpawnOptions): Subprocess;

DuplexPair is defined in $.

Arguments:

• command — an array of strings. The first element is the command to run. The rest are its arguments.
• options — an optional object with options to configure the process:
  • cwd — the optional current working directory as a string. Defaults to process.cwd().
  • env — the optional environment variables as an object (key-value pairs). Defaults to process.env.
  • stdin — the optional source stream state. Defaults to null.
  • stdout — the optional destination stream state. Defaults to null.
  • stderr — the optional destination stream state. Defaults to null.

stdin, stdout and stderr can be a string (one of 'inherit', 'ignore', 'pipe' or 'piped') or null. The latter is equivalent to 'ignore'. 'piped' is an alias of 'pipe':

• 'inherit' — inherit streams from the parent process. For output steams (stdout and stderr), it means that they will be piped to the same target, e.g., the console.
• 'ignore' — the stream is ignored.
• 'pipe' — the stream is available for reading or writing.

Returns a sub-process object with the following properties:

• command — the command that was run as an array of strings.
• options — the options that were passed to spawn().
• exited — a promise that resolves to the exit code of the process. It is used to wait for the process to exit.
• finished — a boolean. It is true when the process has finished and false otherwise.
• killed — a boolean. It is true when the process has been killed and false otherwise.
• exitCode — the exit code of the process as a number. It is null if the process hasn't exited yet.
• signalCode — the signal code of the process as a string. It is null if the process hasn't exited yet.
• stdin — the source stream of the process if options.stdin was 'pipe'. It is null otherwise.
• stdout — the destination stream of the process if options.stdout was 'pipe'. It is null otherwise.
• stderr — the destination stream of the process if options.stderr was 'pipe'. It is null otherwise.
• asDuplex — returns a duplex stream that can be used to pipe the input and output. It is defined as {readable: this.stdout, writable: this.stdin}.
• kill() — kills the process. killed will be true as soon as the process has been killed. It can be used to pipe the input and output. See spawn()'s stdin and stdout above for more details.

Important: all streams are exposed as web streams.

Examples

import {spawn} from 'dollar-shell';

const sp = spawn(['sleep', '5'])
await new Promise(resolve => setTimeout(resolve, 1000));
sp.kill();
await sp.exited;

sp.finished === true;
sp.killed === true;