Skip to content

Exit

Represents the result of an Effect computation as a plain value.

An Exit<A, E> is either a success with an A or a failure with a Cause<E>. The failure cause preserves typed errors, defects, and interruptions after a workflow has finished. Use this module when completed Effect results need to be inspected, transformed, filtered, or matched synchronously as data.

31 exports Added in v2.0.0 Source

Combinators

asVoid

Added in v2.0.0 Source

Discards the success value of an Exit, replacing it with void.

When to use

Use when you need to discard a successful Exit value while preserving whether the Exit succeeded or failed.

Details

Failures pass through unchanged.

Allocates a new Exit if successful.

See

  • void for a pre-allocated void success
  • asVoidAll to combine multiple exits into a single void Exit

Signature

declare const asVoid: <A, E>(self: Exit<A, E>) => Exit<void, E>;

asVoidAll

Added in v4.0.0 Source

Combines multiple Exit values into a single Exit<void, E>.

When to use

Use to validate that all exits in a collection succeeded

Details

If all exits are successful, this returns a void success. If any exit is a failure, this returns a single failure with all error causes combined.

Iterates over the entire collection. Collects all failure causes, not just the first.

See

  • asVoid to discard the value of a single Exit

Signature

declare const asVoidAll: <I extends Iterable<Exit<any, any>>>(
  exits: I,
) => Exit<void, I extends Iterable<Exit<infer _A, infer _E>> ? _E : never>;

map

Added in v2.0.0 Source

Transforms the success value of an Exit using the given function.

When to use

Use to apply a transformation to the value inside a successful Exit

Details

Failures pass through unchanged.

Allocates a new Exit if successful.

See

Signature

declare const map: {
  <A, B>(f: (a: A) => B): <E>(self: Exit<A, E>) => Exit<B, E>;
  <A, E, B>(self: Exit<A, E>, f: (a: A) => B): Exit<B, E>;
};

mapBoth

Added in v2.0.0 Source

Transforms both the success value and typed error of an Exit.

When to use

Use when you need to remap both channels in one step.

Details

onSuccess transforms the value if the Exit is a Success. onFailure transforms the typed error if the Exit is a Failure with a Fail reason. Allocates a new Exit.

Gotchas

If the Cause contains only defects or interruptions, the failure passes through unchanged.

See

  • map to transform only the success value
  • mapError to transform only the error

Signature

declare const mapBoth: {
  <E, E2, A, A2>(options: {
    readonly onFailure: (e: E) => E2;
    readonly onSuccess: (a: A) => A2;
  }): (self: Exit<A, E>) => Exit<A2, E2>;
  <A, E, E2, A2>(
    self: Exit<A, E>,
    options: {
      readonly onFailure: (e: E) => E2;
      readonly onSuccess: (a: A) => A2;
    },
  ): Exit<A2, E2>;
};

mapError

Added in v2.0.0 Source

Transforms the typed error of a failed Exit using the given function.

When to use

Use to remap typed errors while preserving the Exit structure

Details

Successes pass through unchanged.

Allocates a new Exit if the error is transformed.

Gotchas

Only transforms typed errors (Fail reasons). If the Cause contains only defects or interruptions, the failure passes through unchanged.

See

  • map to transform the success value
  • mapBoth to transform both success and error

Signature

declare const mapError: {
  <E, E2>(f: (a: NoInfer<E>) => E2): <A>(self: Exit<A, E>) => Exit<A, E2>;
  <A, E, E2>(self: Exit<A, E>, f: (a: NoInfer<E>) => E2): Exit<A, E2>;
};

Constructors

die

Added in v2.0.0 Source

Creates a failed Exit from a defect (unexpected error).

When to use

Use when you need unexpected, unrecoverable errors that should not appear in the typed error channel.

Details

The defect is wrapped in a Cause.Die internally.

Returns a Failure<never> with E = never, since defects do not appear in the typed error channel.

See

  • fail to create a Failure from a typed error
  • hasDies to check whether an Exit contains defects

Signature

declare const die: (defect: unknown) => Exit<never>;

fail

Added in v2.0.0 Source

Creates a failed Exit from a typed error value.

When to use

Use when you need to represent an expected typed failure as an Exit.

Details

The error is wrapped in a Cause.Fail internally.

Returns a Failure<never, E>.

See

  • succeed to create a successful Exit
  • die to create a Failure from an unexpected defect
  • failCause to create a Failure from a full Cause

Signature

declare const fail: <E>(e: E) => Exit<never, E>;

failCause

Added in v2.0.0 Source

Creates a failed Exit from a Cause.

When to use

Use when you already have a Cause<E> and want to wrap it in an Exit for advanced error handling where you need full control over the Cause structure.

Details

Returns a Failure<never, E>. If you only have an error value, use fail instead.

See

  • fail to create a Failure from a plain error value
  • die to create a Failure from a defect

Signature

declare const failCause: <E>(cause: Cause.Cause<E>) => Exit<never, E>;

interrupt

Added in v2.0.0 Source

Creates a failed Exit representing fiber interruption.

When to use

Use to signal that a fiber was interrupted.

Details

Optionally pass a fiber ID to identify which fiber was interrupted. Returns a Failure<never> with an Interrupt cause.

See

Signature

declare const interrupt: (fiberId?: number) => Exit<never>;

succeed

Added in v2.0.0 Source

Creates a successful Exit containing the given value.

When to use

Use when you need an Exit that contains a known success value.

Details

Returns a Success<A> with the provided value. Does not perform any computation.

See

  • fail to create a failed Exit
  • void for a pre-allocated success with no value

Signature

declare const succeed: <A>(a: A) => Exit<A>;

Filtering

filterCause

Added in v4.0.0 Source

Extracts the Cause from a failed Exit as a Result.

When to use

Use when composing Exit checks with Filter or other Result-based filtering APIs and you want the raw Cause rather than the Failure wrapper.

Details

Returns Result.succeed(cause) when the Exit is a Failure, or Result.fail(success) with the original Success otherwise.

Gotchas

This is not an Option accessor or an Effect failure. A failed extraction is represented as data in the Result failure channel.

See

Signature

declare const filterCause: <A, E>(self: Exit<A, E>) => Result.Result<Cause.Cause<E>, Success<A>>;

filterFailure

Added in v4.0.0 Source

Extracts the Failure variant from an Exit as a Result.

When to use

Use when composing Exit checks with Filter or other Result-based filtering APIs and you want the full Failure wrapper.

Details

Returns Result.succeed(failure) when the Exit is a Failure, or Result.fail(success) with the original Success otherwise.

Gotchas

This is not an Option accessor or an Effect failure. A failed extraction is represented as data in the Result failure channel.

See

Signature

declare const filterFailure: <A, E>(
  self: Exit<A, E>,
) => Result.Result<Failure<never, E>, Success<A>>;

filterSuccess

Added in v4.0.0 Source

Extracts the Success variant from an Exit as a Result.

When to use

Use when composing Exit checks with Filter or other Result-based filtering APIs and you want the full Success wrapper.

Details

Returns Result.succeed(success) when the Exit is a Success, or Result.fail(failure) with the original Failure otherwise.

Gotchas

This is not an Option accessor or an Effect failure. A failed extraction is represented as data in the Result failure channel.

See

Signature

declare const filterSuccess: <A, E>(
  self: Exit<A, E>,
) => Result.Result<Success<A>, Failure<never, E>>;

filterValue

Added in v4.0.0 Source

Extracts the success value from an Exit as a Result.

When to use

Use when composing Exit checks with Filter or other Result-based filtering APIs and you want the raw success value rather than the Success wrapper.

Details

Returns Result.succeed(value) when the Exit is a Success, or Result.fail(failure) with the original Failure otherwise.

Gotchas

This is not an Option accessor or an Effect failure. A failed extraction is represented as data in the Result failure channel.

See

Signature

declare const filterValue: <A, E>(self: Exit<A, E>) => Result.Result<A, Failure<never, E>>;

findDefect

Added in v4.0.0 Source

Extracts the first defect from a failed Exit as a Result.

When to use

Use when you need the first defect from an Exit as a Result for Filter or other Result-based filtering APIs.

Details

Returns Result.succeed(defect) when the Cause contains a Die reason, or Result.fail(exit) with the original Exit otherwise.

Gotchas

Only finds the first Die reason. If the Cause has multiple defects, the rest are ignored.

See

  • findError to find typed errors instead
  • hasDies to check for defects without extracting them

Signature

declare const findDefect: <A, E>(input: Exit<A, E>) => Result.Result<unknown, Exit<A, E>>;

findError

Added in v4.0.0 Source

Extracts the first typed error value from a failed Exit as a Result.

When to use

Use when you need the first typed error from an Exit as a Result for Filter or other Result-based filtering APIs.

Details

Returns Result.succeed(error) when the Cause contains a Fail reason, or Result.fail(exit) with the original Exit otherwise.

Gotchas

Only finds the first Fail reason. If the Cause has multiple errors, the rest are ignored.

See

Signature

declare const findError: <A, E>(input: Exit<A, E>) => Result.Result<E, Exit<A, E>>;

Getters

findErrorOption

Added in v4.0.0 Source

Returns the first typed error from a failed Exit as an Option.

When to use

Use when you need the first typed error from an Exit as an Option, ignoring successes and non-typed failures.

Details

Returns Option.some(error) if the Cause contains a Fail reason. Successes, defect-only failures, and interrupt-only failures return Option.none().

Gotchas

Only finds the first Fail reason. If the Cause has multiple typed errors, the rest are ignored.

See

Signature

declare const findErrorOption: <A, E>(self: Exit<A, E>) => Option<E>;

getCause

Added in v4.0.0 Source

Returns the Cause of a failed Exit as an Option.

When to use

Use when you need the failure Cause from an Exit as an Option instead of pattern matching.

Details

Returns Option.some(cause) for a Failure and Option.none() for a Success.

See

Signature

declare const getCause: <A, E>(self: Exit<A, E>) => Option<Cause.Cause<E>>;

getSuccess

Added in v4.0.0 Source

Returns the success value of an Exit as an Option.

When to use

Use when you need the success value from an Exit as an Option instead of pattern matching.

Details

Returns Option.some(value) for a Success and Option.none() for a Failure.

See

Signature

declare const getSuccess: <A, E>(self: Exit<A, E>) => Option<A>;

Guards

hasDies

Added in v4.0.0 Source

Checks whether a failed Exit contains defects (Die reasons).

When to use

Use to check whether an Exit failure cause contains unexpected errors.

Details

Returns false for successful exits. Only checks for Die reasons in the Cause. A Cause with only Fail or Interrupt reasons returns false.

See

Signature

declare const hasDies: <A, E>(self: Exit<A, E>) => self is Failure<A, E>;

hasFails

Added in v4.0.0 Source

Checks whether a failed Exit contains typed errors (Fail reasons).

When to use

Use to distinguish typed failures from defects or interruptions.

Details

Returns false for successful exits. Only checks for Fail reasons in the Cause. A Cause with only Die or Interrupt reasons returns false.

See

Signature

declare const hasFails: <A, E>(self: Exit<A, E>) => self is Failure<A, E>;

hasInterrupts

Added in v4.0.0 Source

Checks whether a failed Exit contains interruptions (Interrupt reasons).

When to use

Use to check whether an Exit contains fiber interruption.

Details

Returns false for successful exits. Only checks for Interrupt reasons in the Cause. A Cause with only Fail or Die reasons returns false.

See

Signature

declare const hasInterrupts: <A, E>(self: Exit<A, E>) => self is Failure<A, E>;

isExit

Added in v2.0.0 Source

Checks whether an unknown value is an Exit.

When to use

Use to validate unknown values at system boundaries and narrow them to Exit<unknown, unknown>.

Details

Does not inspect the contents of the Exit. Returns true for both Success and Failure exits.

See

Signature

declare const isExit: (u: unknown) => u is Exit<unknown, unknown>;

isFailure

Added in v2.0.0 Source

Checks whether an Exit is a Failure.

When to use

Use as a type guard to narrow Exit<A, E> to Failure<A, E> and access the cause property.

See

Signature

declare const isFailure: <A, E>(self: Exit<A, E>) => self is Failure<A, E>;

isSuccess

Added in v2.0.0 Source

Checks whether an Exit is a Success.

When to use

Use as a type guard to narrow Exit<A, E> to Success<A, E> and access the value property.

See

Signature

declare const isSuccess: <A, E>(self: Exit<A, E>) => self is Success<A, E>;

Models

Exit type

Added in v2.0.0 Source

Represents the result of an Effect computation.

When to use

Use when you need to synchronously inspect whether an Effect computation succeeded or failed.

Details

An Exit<A, E> is either Success<A, E> containing a value of type A, or Failure<A, E> containing a Cause<E> describing why the computation failed.

Since Exit is also an Effect, you can yield it inside Effect.gen.

See

Signature

type Exit<A, E = never> = Success<A, E> | Failure<A, E>;

Failure interface

Added in v2.0.0 Source

A failed Exit containing a Cause.

When to use

Use when working with the failed branch of an Exit after narrowing with isFailure. Access the cause via the cause property after narrowing.

Details

The Cause<E> may contain typed errors, defects, or interruptions.

See

Signature

interface Failure<out A, out E> extends Proto<A, E> {
  readonly _tag: "Failure";
  readonly cause: Cause<E>;
}

Success interface

Added in v2.0.0 Source

A successful Exit containing a value.

When to use

Use when working with the successful branch of an Exit after narrowing with isSuccess. Access the value via the value property after narrowing.

See

Signature

interface Success<out A, out E = never> extends Proto<A, E> {
  readonly _tag: "Success";
  readonly value: A;
}

Other

Exit

Added in v2.0.0 Source

Namespace containing helper types shared by Exit values.

When to use

Use to reference helper types that describe the shared structure of Exit values.

void

Source

Signature

declare const void: Exit<void>

Pattern Matching

match

Added in v2.0.0 Source

Pattern matches on an Exit, handling both success and failure cases.

When to use

Use when you need exhaustive handling of both Exit success and failure outcomes.

Details

Calls onSuccess with the value if the Exit is a Success, and calls onFailure with the Cause if the Exit is a Failure.

See

  • isSuccess and isFailure for simple boolean checks

Signature

declare const match: {
  <A, E, X1, X2>(options: {
    readonly onFailure: (cause: Cause.Cause<NoInfer<E>>) => X2;
    readonly onSuccess: (a: NoInfer<A>) => X1;
  }): (self: Exit<A, E>) => X1 | X2;
  <A, E, X1, X2>(
    self: Exit<A, E>,
    options: {
      readonly onFailure: (cause: Cause.Cause<E>) => X2;
      readonly onSuccess: (a: A) => X1;
    },
  ): X1 | X2;
};