Skip to content

ChildProcessSpawner

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 Added in v4.0.0 Source

Constructors

ExitCode

Added in v4.0.0 Source

Constructs branded child process ExitCode values.

Signature

declare const ExitCode: Constructor<ExitCode>;

make

Added in v4.0.0 Source

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

Added in v4.0.0 Source

Constructs a new ChildProcessHandle.

Signature

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

ProcessId

Added in v4.0.0 Source

Constructs branded child process ProcessId values.

Signature

declare const ProcessId: Constructor<ProcessId>;

Models

ChildProcessHandle interface

Added in v4.0.0 Source

A handle to a running child process.

Signature

interface ChildProcessHandle {
  readonly "~effect/ChildProcessSpawner/ChildProcessHandle": "~effect/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

Added in v4.0.0 Source

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

Signature

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

ProcessId type

Added in v4.0.0 Source

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

Signature

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

Reref type

Added in v4.0.0 Source

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

ChildProcessSpawner

Added in v4.0.0 Source

Service tag for child process spawning.

Signature

declare class ChildProcessSpawner extends Shape<
  "effect/process/ChildProcessSpawner",
  {
    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>;
  },
  this
> {
  constructor(_: never);
}