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.