Skip to content

Runtime

Helpers for turning an Effect program into a host application's main entry point. This module is the low-level layer used by platform adapters to run a main effect, observe its fiber, report unhandled failures, and translate the resulting Exit into an application or process exit code. It provides makeRunMain, the default teardown behavior, and error markers for custom exit codes and already-reported failures. Application code usually calls the platform-provided runner instead of using this module directly.

9 exports Added in v4.0.0 Source

Getters

getErrorExitCode

Added in v4.0.0 Source

Reads the runtime exit-code marker from an unknown error value.

When to use

Use to read a custom failure exit code from an unknown error value, falling back to the default failure code.

Details

Returns the numeric [Runtime.errorExitCode] property when it is present on an object. Otherwise returns 1, the default failure exit code used by defaultTeardown.

Gotchas

Non-object values, missing markers, and non-number marker values all return 1.

See

Signature

declare function getErrorExitCode(u: unknown): number;

getErrorReported

Added in v4.0.0 Source

Reads the runtime error-reporting marker from an unknown error value.

When to use

Use to read whether an unknown error value should be treated as already reported by the default main runner.

Details

Returns a boolean [Runtime.errorReported] property when it is present on an object. Otherwise returns true, so failures are logged by default.

Gotchas

Non-object values, missing markers, and non-boolean marker values all return true.

See

Signature

declare function getErrorReported(u: unknown): boolean;

Models

Teardown interface

Added in v4.0.0 Source

Represents a teardown function that handles program completion and determines the exit code.

When to use

Use when integrating makeRunMain with a host platform that needs to translate an Effect Exit into a process, worker, or application exit code.

Details

A teardown function is called when an Effect program completes, either successfully or with a failure. It determines the appropriate exit code and can perform cleanup before invoking the supplied onExit callback.

Signature

interface Teardown {
  <E, A>(exit: Exit<E, A>, onExit: (code: number) => void): void;
}

Running

defaultTeardown

Added in v4.0.0 Source

The default teardown function that determines exit codes from an Effect exit.

When to use

Use as the standard teardown for main programs with conventional process exit codes and support for errorExitCode.

Details

This teardown follows these exit-code rules:

- 0 for successful completion. - 130 for interruption-only failures. - The squashed error's errorExitCode value for other failures when present. - 1 for other failures.

Gotchas

The 130 code is used only when the Cause contains interruptions and no other failure reasons. Mixed causes use the squashed error path instead.

See

Signature

declare const defaultTeardown: Teardown;

makeRunMain

Added in v4.0.0 Source

Creates a platform-specific main program runner that handles Effect execution lifecycle.

When to use

Use when building a runtime adapter for a host platform.

Details

The runner executes Effect programs as main entry points. The provided function receives a forked fiber and a teardown callback so it can install platform-specific signal handling, fiber observers, and final exit behavior.

Most applications should use a platform-provided runner, such as NodeRuntime.runMain, rather than constructing one directly.

disableErrorReporting disables the automatic log emitted for unreported non-interruption failures. It does not change exit-code calculation or the custom teardown callback.

Gotchas

The setup function is responsible for observing the fiber and eventually invoking teardown. makeRunMain also tries to keep the host process alive with a long interval while the main fiber is running; if the host blocks timers, the runner still starts but cannot use that keep-alive fallback.

Signature

declare function makeRunMain(
  f: <E, A>(options: { readonly fiber: Fiber<A, E>; readonly teardown: Teardown }) => void,
): {
  (options?: {
    readonly disableErrorReporting?: boolean;
    readonly teardown?: Teardown;
  }): <E, A>(effect: Effect<A, E>) => void;
  <E, A>(
    effect: Effect<A, E>,
    options?: {
      readonly disableErrorReporting?: boolean;
      readonly teardown?: Teardown;
    },
  ): void;
};

Symbols

errorExitCode

Added in v4.0.0 Source

Allows associating an exit code with an error for determining the process exit code on failure.

When to use

Use when error classes should map failures to a specific process exit code when handled by defaultTeardown.

Details

Attach this marker as a readonly property on an error object. When the main program fails, defaultTeardown squashes the Cause and reads the marker from the resulting error value.

Gotchas

The marker is read from the squashed failure value. If a Cause contains multiple failures, the selected squashed error determines the exit code.

See

Signature

declare const errorExitCode: "~effect/Runtime/errorExitCode";

errorExitCode type

Added in v4.0.0 Source

Type-level key for the Runtime.errorExitCode marker.

When to use

Use to type properties keyed by Runtime.errorExitCode on custom error values.

Signature

type errorExitCode = "~effect/Runtime/errorExitCode";

errorReported

Added in v4.0.0 Source

Defines the runtime marker that controls default runMain error logging for an error.

When to use

Use when you need error classes reported by application code to avoid being logged again by the default main runner.

Details

Set [Runtime.errorReported] to false on an error object to suppress the runtime log because the error has already been reported. Omitted or non-boolean values are treated as true, so failures are logged by default.

Gotchas

This marker controls only automatic error logging. It does not change the failure Cause or the process exit code. makeRunMain reads the marker from Cause.squash(cause), so for causes with multiple failures, the squashed error determines whether default logging is suppressed.

See

Signature

declare const errorReported: "~effect/Runtime/errorReported";

errorReported type

Added in v4.0.0 Source

Type-level key for the Runtime.errorReported marker.

When to use

Use to type properties keyed by Runtime.errorReported on custom error values.

Signature

type errorReported = "~effect/Runtime/errorReported";