ChildProcessSpawner unstable

Service boundary for starting and controlling child processes.

ChildProcessSpawner is the service used by ChildProcess commands to start operating-system processes. A spawner turns a command description into a handle that can write to stdin, read stdout and stderr, wait for exit, kill the process, and manage whether the process keeps its parent alive. Platform backends implement this service, while most application code uses the higher level ChildProcess module.

9 exports Since v4.0.0 Source

Constructors

ExitCode

unstable

Since v4.0.0

Constructs branded child process ExitCode values.

Signature

declare const ExitCode: Constructor<ExitCode>

make

unstable

Since v4.0.0

Creates a ChildProcessSpawner service from a spawn function, deriving helpers for exit codes and output collection from that implementation.

Signature

declare function make(spawn: (command: Command) => Effect<ChildProcessHandle, PlatformError, Scope>): {
  exitCode(command: Command): Effect<ExitCode, PlatformError>;
  lines(command: Command, options?: {
    readonly includeStderr?: boolean;
  }): Effect<Array<string>, PlatformError>;
  spawn(command: Command): Effect<ChildProcessHandle, PlatformError, Scope>;
  streamLines(command: Command, options?: {
    readonly includeStderr?: boolean;
  }): Stream<string, PlatformError>;
  streamString(command: Command, options?: {
    readonly includeStderr?: boolean;
  }): Stream<string, PlatformError>;
  string(command: Command, options?: {
    readonly includeStderr?: boolean;
  }): Effect<string, PlatformError>;
}

makeHandle

unstable

Since v4.0.0

Constructs a new ChildProcessHandle.

Signature

declare function makeHandle(params: Omit<ChildProcessHandle, typeof HandleTypeId>): ChildProcessHandle

ProcessId

unstable

Since v4.0.0

Constructs branded child process ProcessId values.

Signature

declare const ProcessId: Constructor<ProcessId>

Models

ChildProcessHandle

interface unstable

Since v4.0.0

A handle to a running child process.

Signature

interface ChildProcessHandle {
  readonly "~effect/process/ChildProcessSpawner/ChildProcessHandle": "~effect/process/ChildProcessSpawner/ChildProcessHandle";
  readonly all: Stream<Uint8Array<ArrayBufferLike>, PlatformError>;
  readonly exitCode: Effect<ExitCode, PlatformError>;
  readonly getInputFd: (fd: number) => Sink<void, Uint8Array<ArrayBufferLike>, never, PlatformError>;
  readonly getOutputFd: (fd: number) => Stream<Uint8Array<ArrayBufferLike>, PlatformError>;
  readonly isRunning: Effect<boolean, PlatformError>;
  readonly kill: (options?: KillOptions) => Effect<void, PlatformError>;
  readonly pid: ProcessId;
  readonly stderr: Stream<Uint8Array<ArrayBufferLike>, PlatformError>;
  readonly stdin: Sink<void, Uint8Array<ArrayBufferLike>, never, PlatformError>;
  readonly stdout: Stream<Uint8Array<ArrayBufferLike>, PlatformError>;
  readonly unref: Effect<Reref, PlatformError>;
}

ExitCode

type unstable

Since v4.0.0

Branded number representing the exit code reported by a child process.

Signature

type ExitCode = Brand.Branded<number, "ExitCode">

ProcessId

type unstable

Since v4.0.0

Branded number representing the operating system process identifier of a child process.

Signature

type ProcessId = Brand.Branded<number, "ProcessId">

Reref

type unstable

Since v4.0.0

An Effect that adds an unrefed child process back into the parent process's reference count.

Details

This value is returned by ChildProcessHandle.unref and can be run later to restore the default behavior where the child process keeps the parent process alive.

Signature

type Reref = Effect.Effect<void, PlatformError.PlatformError>

Services