ChildProcess
Describes child processes before they are started.
A Command stores the executable, arguments, environment, standard streams, working directory, and other process options. Commands can also be piped together. A command is an Effect; running it asks the ChildProcessSpawner service to start the process and returns a ChildProcessHandle.
Combinators
Signature
declare const pipeTo: { (that: Command, options?: PipeOptions): (self: Command) => PipedCommand; (self: Command, that: Command, options?: PipeOptions): PipedCommand;};Prepends another command to a command.
Details
For pipelines, only the leftmost command is prefixed.
Signature
declare const prefix: { (command: string, args?: readonly Array<string>): (self: Command) => Command; (templates: TemplateStringsArray, ...expressions: readonly Array<TemplateExpression>): (self: Command) => Command; (self: Command, command: string, args?: readonly Array<string>): Command;}Sets the current working directory for a command.
Details
For pipelines, applies to each command in the pipeline.
Signature
declare const setCwd: { (cwd: string): (self: Command) => Command; (self: Command, cwd: string): Command;};Adds environment variables to a command, merging them with any existing command environment and overriding duplicate keys.
Details
For pipelines, applies to each command in the pipeline.
Signature
declare const setEnv: { (env: Record<string, string>): (self: Command) => Command; (self: Command, env: Record<string, string>): Command;};Constructors
Create a command from a template literal, options + template, or array form.
Details
This function supports three calling conventions: 1. Template literal: make\npm run build\` 2. Options + template literal: make({ cwd: "/app" })\npm run build\ 3. Array form: make("npm", ["run", "build"], options?)`
Template literals are not parsed until execution time, allowing parsing errors to flow through Effect's error channel.
Signature
declare const make: { (command: string, options?: CommandOptions): StandardCommand; (command: string, args: readonly Array<string>, options?: CommandOptions): StandardCommand; (options: CommandOptions): (templates: TemplateStringsArray, ...expressions: readonly Array<TemplateExpression>) => StandardCommand; (templates: TemplateStringsArray, ...expressions: readonly Array<TemplateExpression>): StandardCommand;}Converting
Create an fd name from its numeric index.
Signature
declare function fdName(fd: number): string;parseFdName
Parses an fd name like "fd3" to its numeric index. Returns undefined if the name is invalid.
Signature
declare function parseFdName(name: string): number | undefined;Guards
Checks whether a value is a Command.
Signature
declare function isCommand(u: unknown): u is Command;isPipedCommand
Checks whether a command is a PipedCommand.
Signature
declare function isPipedCommand(command: Command): command is PipedCommand;isStandardCommand
Checks whether a command is a StandardCommand.
Signature
declare function isStandardCommand(command: Command): command is StandardCommand;Models
AdditionalFdConfig type
Configuration for additional file descriptors to expose to the child process.
Signature
type AdditionalFdConfig = | { readonly stream?: Stream.Stream<Uint8Array, PlatformError.PlatformError>; readonly type: "input"; } | { readonly sink?: Sink.Sink<Uint8Array, Uint8Array, never, PlatformError.PlatformError>; readonly type: "output"; };A command that can be built using make, combined using pipeTo, and executed using exec or spawn.
Signature
type Command = StandardCommand | PipedCommand;CommandInput type
Input type for child process stdin.
Signature
type CommandInput = | "pipe" | "inherit" | "ignore" | "overlapped" | Stream.Stream<Uint8Array, PlatformError.PlatformError>;CommandOutput type
Output type for child process stdout/stderr.
Signature
type CommandOutput = | "pipe" | "inherit" | "ignore" | "overlapped" | Sink.Sink<Uint8Array, Uint8Array, never, PlatformError.PlatformError>;The encoding format to use for binary data.
Signature
type Encoding = | "ascii" | "utf8" | "utf-8" | "utf16le" | "utf-16le" | "ucs2" | "ucs-2" | "base64" | "base64url" | "latin1" | "binary" | "hex";PipedCommand interface
A pipeline of commands where the output of one is piped to the input of the next.
Signature
interface PipedCommand extends Effect< ChildProcessHandle, PlatformError.PlatformError, ChildProcessSpawner | Scope.Scope> { readonly _tag: "PipedCommand"; readonly left: Command; readonly options: PipeOptions; readonly right: Command;}PipeFromOption type
Specifies which stream to pipe from the source subprocess.
Details
- "stdout": Pipe stdout from the source (default) - "stderr": Pipe stderr from the source - "all": Pipe both stdout and stderr interleaved - ` fd${number} : Pipe from a custom file descriptor (e.g., "fd3"`)
Signature
type PipeFromOption = "stdout" | "stderr" | "all" | `fd${number}`;PipeToOption type
Specifies which input to pipe to on the destination subprocess.
Details
- "stdin": Pipe to stdin of the destination (default) - ` fd${number} : Pipe to a custom file descriptor (e.g., "fd3"`)
Signature
type PipeToOption = "stdin" | `fd${number}`;A signal that can be sent to a child process.
Signature
type Signal = | "SIGABRT" | "SIGALRM" | "SIGBUS" | "SIGCHLD" | "SIGCONT" | "SIGFPE" | "SIGHUP" | "SIGILL" | "SIGINT" | "SIGIO" | "SIGIOT" | "SIGKILL" | "SIGPIPE" | "SIGPOLL" | "SIGPROF" | "SIGPWR" | "SIGQUIT" | "SIGSEGV" | "SIGSTKFLT" | "SIGSTOP" | "SIGSYS" | "SIGTERM" | "SIGTRAP" | "SIGTSTP" | "SIGTTIN" | "SIGTTOU" | "SIGUNUSED" | "SIGURG" | "SIGUSR1" | "SIGUSR2" | "SIGVTALRM" | "SIGWINCH" | "SIGXCPU" | "SIGXFSZ" | "SIGBREAK" | "SIGLOST" | "SIGINFO";StandardCommand interface
A standard command with pre-parsed command and arguments.
Signature
interface StandardCommand extends Effect<ChildProcessHandle, PlatformError.PlatformError, ChildProcessSpawner | Scope.Scope> { readonly _tag: "StandardCommand"; readonly args: readonly Array<string>; readonly command: string; readonly options: CommandOptions;}StderrConfig interface
Configuration for the child process standard error stream.
Signature
interface StderrConfig { readonly stream?: CommandOutput;}StdinConfig interface
Configuration for the child process standard input stream.
Signature
interface StdinConfig { readonly encoding?: Encoding; readonly endOnDone?: boolean; readonly stream: CommandInput;}StdoutConfig interface
Configuration for the child process standard output stream.
Signature
interface StdoutConfig { readonly stream?: CommandOutput;}TemplateExpression type
Template expression type for interpolated values.
Signature
type TemplateExpression = TemplateExpressionItem | ReadonlyArray<TemplateExpressionItem>;TemplateExpressionItem type
Valid template expression item types.
Signature
type TemplateExpressionItem = string | number | boolean;Options
CommandOptions interface
Options for command execution.
Signature
interface CommandOptions extends KillOptions { readonly additionalFds?: Record<`fd${number}`, AdditionalFdConfig>; readonly cwd?: string; readonly detached?: boolean; readonly env?: Record<string, string | undefined>; readonly extendEnv?: boolean; readonly shell?: string | boolean; readonly stderr?: CommandOutput | StderrConfig; readonly stdin?: StdinConfig | CommandInput; readonly stdout?: StdoutConfig | CommandOutput;}KillOptions interface
Options that can be used to control how a child process is terminated.
Signature
interface KillOptions { readonly forceKillAfter?: Input; readonly killSignal?: Signal;}PipeOptions interface
Options for controlling how commands are piped together.
Signature
interface PipeOptions { readonly from?: PipeFromOption; readonly to?: PipeToOption;}
Pipes the output of one command to the input of another.
Details
By default, pipes
stdoutfrom the source tostdinof the destination. Use theoptionsparameter to customize which streams are connected.