Stdio

Service contract for command-line arguments and standard input, output, and error output. It lets programs depend on standard I/O through the Effect environment instead of reading from or writing to global process handles directly.

The service exposes arguments as an Effect, stdout and stderr as Sinks that accept strings or bytes, and stdin as a byte Stream. This module also provides a constructor for service values and a small test layer with overridable defaults.

6 exports Added in v4.0.0 Source

Constructors

make

Added in v4.0.0 Source

Creates a Stdio service implementation from the provided fields and attaches the Stdio type identifier.

When to use

Use when you need to assemble a concrete Stdio service from command-line arguments and standard I/O implementations.

Details

The returned service reuses the supplied fields unchanged and adds the Stdio type identifier. Omitted terminal-detection fields default to effects that succeed with false.

See

layerTest for a test layer with default fields that can be overridden

Signature

declare function make(options: Omit<Stdio, "~effect/Stdio" | "stdinIsTerminal" | "stdoutIsTerminal"> & Partial<Pick<Stdio, "stdinIsTerminal" | "stdoutIsTerminal">>): Stdio

Layers

layerTest

Added in v4.0.0 Source

Creates a test layer for Stdio.

When to use

Use to provide deterministic standard I/O in tests while overriding only the command-line arguments, input stream, or output sinks relevant to the case.

Details

Any provided fields override defaults. By default, arguments are empty, standard output and error are draining sinks, and standard input is an empty stream, and terminal-detection effects succeed with false.

See

make for constructing a Stdio service directly without a Layer or defaults

Signature

declare function layerTest(impl: Partial<Stdio>): Layer<Stdio>

Services

Stdio

Added in v4.0.0 Source

Service tag for process standard I/O.

When to use

Use when you need command-line arguments or standard I/O streams supplied by an effect's environment.

See

make for constructing a Stdio service directly
layerTest for a test layer with defaults and overrides

Signature

declare const Stdio: Service<Stdio, Stdio>

Stdio interface

Added in v4.0.0 Source

Defines the service interface for process standard I/O.

When to use

Use to depend on command-line arguments and standard I/O through the Effect environment.

Details

The service provides command-line arguments, sinks for standard output and standard error, and a stream of standard input bytes. I/O operations can fail with PlatformError.

Signature

interface Stdio {
  readonly "~effect/Stdio": "~effect/Stdio";
  readonly args: Effect<readonly Array<string>>;
  readonly stdin: Stream<Uint8Array<ArrayBufferLike>, PlatformError>;
  readonly stdinIsTerminal: Effect<boolean>;
  readonly stdoutIsTerminal: Effect<boolean>;
  stderr(options?: {
    readonly endOnDone?: boolean;
  }): Sink<void, string | Uint8Array<ArrayBufferLike>, never, PlatformError>;
  stdout(options?: {
    readonly endOnDone?: boolean;
  }): Sink<void, string | Uint8Array<ArrayBufferLike>, never, PlatformError>;
}

Type IDs

TypeId

Added in v4.0.0 Source

Runtime identifier stored on Stdio service implementations.

Details

This marker is part of the runtime representation of Stdio service implementations.

Signature

declare const TypeId: "~effect/Stdio"

TypeId type

Added in v4.0.0 Source

String literal type used as the unique brand for the Stdio service.

When to use

Use to type the runtime identifier stored on Stdio service implementations.

Signature

type TypeId = "~effect/Stdio"