Skip to content

Terminal

Service definition for interactive terminal capabilities. Programs can query terminal dimensions, read a line of input, receive low-level key events, and display text without depending directly on a specific platform implementation.

This module defines the Terminal service, input event shapes, key metadata, the QuitError used when a user cancels input, a guard for that error, and a constructor for custom terminal service implementations.

7 exports Added in v4.0.0 Source

Constructors

make

Added in v4.0.0 Source

Creates a Terminal service implementation.

When to use

Use to construct a custom Terminal service implementation from concrete terminal capabilities when writing a platform adapter, test implementation, or custom runtime service.

Details

The implementation object supplies columns, rows, readInput, readLine, and display; make attaches the Terminal service marker so the result can be provided through the Terminal context service.

Signature

declare function make(impl: Omit<Terminal, typeof TypeId>): Terminal;

Errors

QuitError

Added in v4.0.0 Source

Represents an error that occurs when a user attempts to quit out of a Terminal prompt for input (usually by entering ctrl+c).

When to use

Use when implementing terminal input or prompts that need to signal user-requested cancellation through the typed error channel.

See

  • isQuitError for checking unknown errors when handling terminal cancellation

Signature

declare class QuitError extends {
  readonly _tag: "QuitError";
} & YieldableError<this> {
  constructor(...args: [props?: {
    readonly _tag?: "QuitError";
  }, options?: MakeOptions]);
  readonly "effect/platform/Terminal/QuitError": "effect/platform/Terminal/QuitError";
}

Guards

isQuitError

Added in v4.0.0 Source

Returns true if the provided value is a Terminal.QuitError.

When to use

Use to narrow unknown failures to QuitError when handling terminal input cancellation.

Details

Returns true when the value carries the QuitError runtime marker and narrows it to QuitError.

See

  • QuitError for the error value produced when terminal input is quit

Signature

declare function isQuitError(u: unknown): u is QuitError;

Models

Key interface

Added in v4.0.0 Source

Keyboard key metadata for terminal input, including the key name and modifier state.

Signature

interface Key {
  readonly ctrl: boolean;
  readonly meta: boolean;
  readonly name: string;
  readonly shift: boolean;
}

UserInput interface

Added in v4.0.0 Source

A terminal input event containing an optional raw character and the parsed key that was pressed.

When to use

Use when consuming low-level terminal input events from Terminal.readInput and you need both raw character input and parsed key metadata.

See

  • Key for the parsed key metadata stored on each input event

Signature

interface UserInput {
  readonly input: Option<string>;
  readonly key: Key;
}

Services

Terminal

Added in v4.0.0 Source

Service tag for command-line input and output services.

When to use

Use to access or provide platform terminal capabilities such as reading input, writing output, and inspecting terminal dimensions.

Signature

declare const Terminal: Service<Terminal, Terminal>;

Terminal interface

Added in v4.0.0 Source

A Terminal represents a command-line interface which can read input from a user and display messages to a user.

Signature

interface Terminal {
  readonly "~effect/platform/Terminal": "~effect/platform/Terminal";
  readonly columns: Effect<number>;
  readonly display: (text: string) => Effect<void, PlatformError>;
  readonly readInput: Effect<Dequeue<UserInput, Done<void>>, never, Scope>;
  readonly readLine: Effect<string, QuitError>;
  readonly rows: Effect<number>;
}