Cause overview

The Effect<R, E, A> type is polymorphic in values of type E and we can work with any error type that we want. However, there is a lot of information that is not inside an arbitrary E value. So as a result, an Effect needs somewhere to store things like unexpected errors or defects, stack and execution traces, causes of fiber interruptions, and so forth.

Effect-TS is very strict about preserving the full information related to a failure. It captures all type of errors into the Cause data type. Effect uses the Cause<E> data type to store the full story of failure. So its error model is lossless. It doesn’t throw information related to the failure result. So we can figure out exactly what happened during the operation of our effects.

It is important to note that Cause is an underlying data type representing errors occuring within an Effect workflow. Thus, we don’t usually deal with Causes directly. Even though it is not a data type that we deal with very often, the Cause of a failing Effect workflow can be accessed at any time, which gives us total access to all parallel and sequential errors in occurring within our codebase.

Added in v1.0.0

Table of contents

• constructors
  • die
  • empty
  • fail
  • interrupt
  • parallel
  • sequential
• destructors
  • squash
  • squashWith
• elements
  • contains
  • find
• errors
  • IllegalArgumentException
  • InterruptedException
  • NoSuchElementException
  • RuntimeException
  • originalError
• filtering
  • filter
• folding
  • match
  • reduce
  • reduceWithContext
• getters
  • defects
  • dieOption
  • failureOption
  • failureOrCause
  • failures
  • flipCauseOption
  • interruptOption
  • interruptors
  • isDie
  • isEmpty
  • isFailure
  • isInterrupted
  • isInterruptedOnly
  • keepDefects
  • linearize
  • size
  • stripFailures
  • stripSomeDefects
• mapping
  • as
  • map
• models
  • Annotated (interface)
  • Cause (type alias)
  • CauseReducer (interface)
  • Die (interface)
  • Empty (interface)
  • Fail (interface)
  • IllegalArgumentException (interface)
  • Interrupt (interface)
  • InterruptedException (interface)
  • InvalidHubCapacityException (interface)
  • NoSuchElementException (interface)
  • Parallel (interface)
  • RuntimeException (interface)
  • Sequential (interface)
• refinements
  • isCause
  • isDieType
  • isEmptyType
  • isFailType
  • isIllegalArgumentException
  • isInterruptType
  • isInterruptedException
  • isNoSuchElementException
  • isParallelType
  • isRuntimeException
  • isSequentialType
• rendering
  • pretty
• sequencing
  • flatMap
  • flatten
• symbols
  • CauseTypeId
  • CauseTypeId (type alias)
  • IllegalArgumentExceptionTypeId
  • IllegalArgumentExceptionTypeId (type alias)
  • InterruptedExceptionTypeId
  • InterruptedExceptionTypeId (type alias)
  • InvalidHubCapacityExceptionTypeId
  • InvalidHubCapacityExceptionTypeId (type alias)
  • NoSuchElementExceptionTypeId
  • NoSuchElementExceptionTypeId (type alias)
  • RuntimeExceptionTypeId
  • RuntimeExceptionTypeId (type alias)
• utils
  • Cause (namespace)
    • Variance (interface)

constructors

die

Constructs a new Die cause from the specified defect.

Signature

export declare const die: (defect: unknown) => Cause<never>

Added in v1.0.0

empty

Constructs a new Empty cause.

Signature

export declare const empty: Cause<never>

Added in v1.0.0

fail

Constructs a new Fail cause from the specified error.

Signature

export declare const fail: <E>(error: E) => Cause<E>

Added in v1.0.0

interrupt

Constructs a new Interrupt cause from the specified fiberId.

Signature

export declare const interrupt: (fiberId: FiberId.FiberId) => Cause<never>

Added in v1.0.0

parallel

Constructs a new Parallel cause from the specified left and right causes.

Signature

export declare const parallel: <E, E2>(left: Cause<E>, right: Cause<E2>) => Cause<E | E2>

Added in v1.0.0

sequential

Constructs a new Sequential cause from the specified pecified left and right causes.

Signature

export declare const sequential: <E, E2>(left: Cause<E>, right: Cause<E2>) => Cause<E | E2>

Added in v1.0.0

destructors

squash

Squashes a Cause down to a single defect, chosen to be the “most important” defect.

Signature

export declare const squash: <E>(self: Cause<E>) => unknown

Added in v1.0.0

squashWith

Squashes a Cause down to a single defect, chosen to be the “most important” defect. If a recoverable error is found, the provided function will be used to map the error a defect, and the resulting value will be returned.

Signature

export declare const squashWith: {
  <E>(f: (error: E) => unknown): (self: Cause<E>) => unknown
  <E>(self: Cause<E>, f: (error: E) => unknown): unknown
}

Added in v1.0.0

elements

contains

Returns true if the self cause contains or is equal to that cause, false otherwise.

Signature

export declare const contains: {
  <E2>(that: Cause<E2>): <E>(self: Cause<E>) => boolean
  <E, E2>(self: Cause<E>, that: Cause<E2>): boolean
}

Added in v1.0.0

find

Uses the provided partial function to search the specified cause and attempt to extract information from it.

Signature

export declare const find: {
  <E, Z>(pf: (cause: Cause<E>) => Option.Option<Z>): (self: Cause<E>) => Option.Option<Z>
  <E, Z>(self: Cause<E>, pf: (cause: Cause<E>) => Option.Option<Z>): Option.Option<Z>
}

Added in v1.0.0

errors

IllegalArgumentException

Represents a checked exception which occurs when an invalid argument is provided to a method.

Signature

export declare const IllegalArgumentException: (message?: string | undefined) => IllegalArgumentException

Added in v1.0.0

InterruptedException

Represents a checked exception which occurs when a Fiber is interrupted.

Signature

export declare const InterruptedException: (message?: string | undefined) => InterruptedException

Added in v1.0.0

NoSuchElementException

Represents a checked exception which occurs when an expected element was unable to be found.

Signature

export declare const NoSuchElementException: (message?: string | undefined) => NoSuchElementException

Added in v1.0.0

RuntimeException

Represents a generic checked exception which occurs at runtime.

Signature

export declare const RuntimeException: (message?: string | undefined) => RuntimeException

Added in v1.0.0

originalError

Returns the original, unproxied, instance of a thrown error

Signature

export declare const originalError: <E>(obj: E) => E

Added in v1.0.0

filtering

filter

Filters causes which match the provided predicate out of the specified cause.

Signature

export declare const filter: {
  <E>(predicate: Predicate<Cause<E>>): (self: Cause<E>) => Cause<E>
  <E>(self: Cause<E>, predicate: Predicate<Cause<E>>): Cause<E>
}

Added in v1.0.0

folding

match

Folds the specified cause into a value of type Z.

Signature

export declare const match: {
  <Z, E>(options: {
    readonly onEmpty: Z
    readonly onFail: (error: E) => Z
    readonly onDie: (defect: unknown) => Z
    readonly onInterrupt: (fiberId: FiberId.FiberId) => Z
    readonly onAnnotated: (value: Z, annotation: unknown) => Z
    readonly onSequential: (left: Z, right: Z) => Z
    readonly onParallel: (left: Z, right: Z) => Z
  }): (self: Cause<E>) => Z
  <Z, E>(
    self: Cause<E>,
    options: {
      readonly onEmpty: Z
      readonly onFail: (error: E) => Z
      readonly onDie: (defect: unknown) => Z
      readonly onInterrupt: (fiberId: FiberId.FiberId) => Z
      readonly onAnnotated: (value: Z, annotation: unknown) => Z
      readonly onSequential: (left: Z, right: Z) => Z
      readonly onParallel: (left: Z, right: Z) => Z
    }
  ): Z
}

Added in v1.0.0

reduce

Reduces the specified cause into a value of type Z, beginning with the provided zero value.

Signature

export declare const reduce: {
  <Z, E>(zero: Z, pf: (accumulator: Z, cause: Cause<E>) => Option.Option<Z>): (self: Cause<E>) => Z
  <Z, E>(self: Cause<E>, zero: Z, pf: (accumulator: Z, cause: Cause<E>) => Option.Option<Z>): Z
}

Added in v1.0.0

reduceWithContext

Reduces the specified cause into a value of type Z using a Cause.Reducer. Also allows for accessing the provided context during reduction.

Signature

export declare const reduceWithContext: {
  <C, E, Z>(context: C, reducer: CauseReducer<C, E, Z>): (self: Cause<E>) => Z
  <C, E, Z>(self: Cause<E>, context: C, reducer: CauseReducer<C, E, Z>): Z
}

Added in v1.0.0

getters

defects

Returns a List of all unrecoverable defects in the specified cause.

Signature

export declare const defects: <E>(self: Cause<E>) => Chunk.Chunk<unknown>

Added in v1.0.0

dieOption

Returns the defect associated with the first Die in this Cause, if one exists.

Signature

export declare const dieOption: <E>(self: Cause<E>) => Option.Option<unknown>

Added in v1.0.0

failureOption

Returns the E associated with the first Fail in this Cause, if one exists.

Signature

export declare const failureOption: <E>(self: Cause<E>) => Option.Option<E>

Added in v1.0.0

failureOrCause

Returns the first checked error on the Left if available, if there are no checked errors return the rest of the Cause that is known to contain only Die or Interrupt causes.

Signature

export declare const failureOrCause: <E>(self: Cause<E>) => Either.Either<E, Cause<never>>

Added in v1.0.0

failures

Returns a List of all recoverable errors of type E in the specified cause.

Signature

export declare const failures: <E>(self: Cause<E>) => Chunk.Chunk<E>

Added in v1.0.0

flipCauseOption

Converts the specified Cause<Option<E>> to an Option<Cause<E>> by recursively stripping out any failures with the error None.

Signature

export declare const flipCauseOption: <E>(self: Cause<Option.Option<E>>) => Option.Option<Cause<E>>

Added in v1.0.0

interruptOption

Returns the FiberId associated with the first Interrupt in the specified cause, if one exists.

Signature

export declare const interruptOption: <E>(self: Cause<E>) => Option.Option<FiberId.FiberId>

Added in v1.0.0

interruptors

Returns a HashSet of FiberIds for all fibers that interrupted the fiber described by the specified cause.

Signature

export declare const interruptors: <E>(self: Cause<E>) => HashSet.HashSet<FiberId.FiberId>

Added in v1.0.0

isDie

Returns true if the specified cause contains a defect, false otherwise.

Signature

export declare const isDie: <E>(self: Cause<E>) => boolean

Added in v1.0.0

isEmpty

Returns true if the specified cause is empty, false otherwise.

Signature

export declare const isEmpty: <E>(self: Cause<E>) => boolean

Added in v1.0.0

isFailure

Returns true if the specified cause contains a failure, false otherwise.

Signature

export declare const isFailure: <E>(self: Cause<E>) => boolean

Added in v1.0.0

isInterrupted

Returns true if the specified cause contains an interruption, false otherwise.

Signature

export declare const isInterrupted: <E>(self: Cause<E>) => boolean

Added in v1.0.0

isInterruptedOnly

Returns true if the specified cause contains only interruptions (without any Die or Fail causes), false otherwise.

Signature

export declare const isInterruptedOnly: <E>(self: Cause<E>) => boolean

Added in v1.0.0

keepDefects

Remove all Fail and Interrupt nodes from the specified cause, and return a cause containing only Die cause/finalizer defects.

Signature

export declare const keepDefects: <E>(self: Cause<E>) => Option.Option<Cause<never>>

Added in v1.0.0

linearize

Linearizes the specified cause into a HashSet of parallel causes where each parallel cause contains a linear sequence of failures.

Signature

export declare const linearize: <E>(self: Cause<E>) => HashSet.HashSet<Cause<E>>

Added in v1.0.0

size

Returns the size of the cause, calculated as the number of individual Cause nodes found in the Cause semiring structure.

Signature

export declare const size: <E>(self: Cause<E>) => number

Added in v1.0.0

stripFailures

Remove all Fail and Interrupt nodes from the specified cause, and return a cause containing only Die cause/finalizer defects.

Signature

export declare const stripFailures: <E>(self: Cause<E>) => Cause<never>

Added in v1.0.0

stripSomeDefects

Remove all Die causes that the specified partial function is defined at, returning Some with the remaining causes or None if there are no remaining causes.

Signature

export declare const stripSomeDefects: {
  (pf: (defect: unknown) => Option.Option<unknown>): <E>(self: Cause<E>) => Option.Option<Cause<E>>
  <E>(self: Cause<E>, pf: (defect: unknown) => Option.Option<unknown>): Option.Option<Cause<E>>
}

Added in v1.0.0

mapping

as

Signature

export declare const as: {
  <E2>(error: E2): <E>(self: Cause<E>) => Cause<E2>
  <E, E2>(self: Cause<E>, error: E2): Cause<E2>
}

Added in v1.0.0

map

Signature

export declare const map: {
  <E, E2>(f: (e: E) => E2): (self: Cause<E>) => Cause<E2>
  <E, E2>(self: Cause<E>, f: (e: E) => E2): Cause<E2>
}

Added in v1.0.0

models

Annotated (interface)

The Annotated cause represents a Cause which is annotated with some arbitrary metadata.

For example, we can annotate a Cause with a trace to assist in debugging.

Signature

export interface Annotated<E> extends Cause.Variance<E>, Equal.Equal, Pipeable, Inspectable {
  readonly _tag: 'Annotated'
  readonly cause: Cause<E>
  readonly annotation: unknown
}

Added in v1.0.0

Cause (type alias)

A Cause represents the full history of a failure resulting from running an Effect workflow.

Effect-TS uses a data structure from functional programming called a semiring to represent the Cause data type. This allows us to take a base type E (which represents the error type of an Effect) and capture the sequential and parallel composition of errors in a fully lossless fashion.

Signature

export type Cause<E> = Empty | Fail<E> | Die | Interrupt | Sequential<E> | Parallel<E>

Added in v1.0.0

CauseReducer (interface)

Represents a set of methods that can be used to reduce a Cause<E> to a specified value of type Z with access to a context of type C.

Signature

export interface CauseReducer<C, E, Z> {
  readonly emptyCase: (context: C) => Z
  readonly failCase: (context: C, error: E) => Z
  readonly dieCase: (context: C, defect: unknown) => Z
  readonly interruptCase: (context: C, fiberId: FiberId.FiberId) => Z
  readonly sequentialCase: (context: C, left: Z, right: Z) => Z
  readonly parallelCase: (context: C, left: Z, right: Z) => Z
}

Added in v1.0.0

Die (interface)

The Die cause represents a Cause which failed as a result of a defect, or in other words, an unexpected error.

type E.

Signature

export interface Die extends Cause.Variance<never>, Equal.Equal, Pipeable, Inspectable {
  readonly _tag: 'Die'
  readonly defect: unknown
}

Added in v1.0.0

Empty (interface)

The Empty cause represents a lack of errors.

Signature

export interface Empty extends Cause.Variance<never>, Equal.Equal, Pipeable, Inspectable {
  readonly _tag: 'Empty'
}

Added in v1.0.0

Fail (interface)

The Fail cause represents a Cause which failed with an expected error of type E.

Signature

export interface Fail<E> extends Cause.Variance<E>, Equal.Equal, Pipeable, Inspectable {
  readonly _tag: 'Fail'
  readonly error: E
}

Added in v1.0.0

IllegalArgumentException (interface)

Represents a checked exception which occurs when an invalid argument is provided to a method.

Signature

export interface IllegalArgumentException {
  readonly _tag: 'IllegalArgumentException'
  readonly [IllegalArgumentExceptionTypeId]: IllegalArgumentExceptionTypeId
  readonly message?: string
}

Added in v1.0.0

Interrupt (interface)

The Interrupt cause represents failure due to Fiber interruption, which contains the FiberId of the interrupted Fiber.

Signature

export interface Interrupt extends Cause.Variance<never>, Equal.Equal, Pipeable, Inspectable {
  readonly _tag: 'Interrupt'
  readonly fiberId: FiberId.FiberId
}

Added in v1.0.0

InterruptedException (interface)

Represents a checked exception which occurs when a Fiber is interrupted.

Signature

export interface InterruptedException {
  readonly _tag: 'InterruptedException'
  readonly [InterruptedExceptionTypeId]: InterruptedExceptionTypeId
  readonly message?: string
}

Added in v1.0.0

InvalidHubCapacityException (interface)

Represents a checked exception which occurs when attempting to construct a Hub with an invalid capacity.

Signature

export interface InvalidHubCapacityException {
  readonly _tag: 'InvalidHubCapacityException'
  readonly [InvalidHubCapacityExceptionTypeId]: InvalidHubCapacityExceptionTypeId
  readonly message?: string
}

Added in v1.0.0

NoSuchElementException (interface)

Represents a checked exception which occurs when an expected element was unable to be found.

Signature

export interface NoSuchElementException {
  readonly _tag: 'NoSuchElementException'
  readonly [NoSuchElementExceptionTypeId]: NoSuchElementExceptionTypeId
  readonly message?: string
}

Added in v1.0.0

Parallel (interface)

The Parallel cause represents the composition of two causes which occurred in parallel.

In Effect-TS programs, it is possible that two operations may be performed in parallel. In these cases, the Effect workflow can fail for more than one reason. If both computations fail, then there are actually two errors which occurred in parallel. In these cases, the errors can be represented by the Parallel cause.

Signature

export interface Parallel<E> extends Cause.Variance<E>, Equal.Equal, Pipeable, Inspectable {
  readonly _tag: 'Parallel'
  readonly left: Cause<E>
  readonly right: Cause<E>
}

Added in v1.0.0

RuntimeException (interface)

Represents a generic checked exception which occurs at runtime.

Signature

export interface RuntimeException {
  readonly _tag: 'RuntimeException'
  readonly [RuntimeExceptionTypeId]: RuntimeExceptionTypeId
  readonly message?: string
}

Added in v1.0.0

Sequential (interface)

The Sequential cause represents the composition of two causes which occurred sequentially.

For example, if we perform Effect-TS’s analog of try-finally (i.e. Effect.ensuring), and both the try and finally blocks fail, we have two errors which occurred sequentially. In these cases, the errors can be represented by the Sequential cause.

Signature

export interface Sequential<E> extends Cause.Variance<E>, Equal.Equal, Pipeable, Inspectable {
  readonly _tag: 'Sequential'
  readonly left: Cause<E>
  readonly right: Cause<E>
}

Added in v1.0.0

refinements

isCause

Returns true if the specified value is a Cause, false otherwise.

Signature

export declare const isCause: (u: unknown) => u is Cause<never>

Added in v1.0.0

isDieType

Returns true if the specified Cause is a Die type, false otherwise.

Signature

export declare const isDieType: <E>(self: Cause<E>) => self is Die

Added in v1.0.0

isEmptyType

Returns true if the specified Cause is an Empty type, false otherwise.

Signature

export declare const isEmptyType: <E>(self: Cause<E>) => self is Empty

Added in v1.0.0

isFailType

Returns true if the specified Cause is a Fail type, false otherwise.

Signature

export declare const isFailType: <E>(self: Cause<E>) => self is Fail<E>

Added in v1.0.0

isIllegalArgumentException

Returns true if the specified value is an IllegalArgumentException, false otherwise.

Signature

export declare const isIllegalArgumentException: (u: unknown) => u is IllegalArgumentException

Added in v1.0.0

isInterruptType

Returns true if the specified Cause is an Interrupt type, false otherwise.

Signature

export declare const isInterruptType: <E>(self: Cause<E>) => self is Interrupt

Added in v1.0.0

isInterruptedException

Returns true if the specified value is an InterruptedException, false otherwise.

Signature

export declare const isInterruptedException: (u: unknown) => u is InterruptedException

Added in v1.0.0

isNoSuchElementException

Returns true if the specified value is an NoSuchElementException, false otherwise.

Signature

export declare const isNoSuchElementException: (u: unknown) => u is NoSuchElementException

Added in v1.0.0

isParallelType

Returns true if the specified Cause is a Parallel type, false otherwise.

Signature

export declare const isParallelType: <E>(self: Cause<E>) => self is Parallel<E>

Added in v1.0.0

isRuntimeException

Returns true if the specified value is an RuntimeException, false otherwise.

Signature

export declare const isRuntimeException: (u: unknown) => u is RuntimeException

Added in v1.0.0

isSequentialType

Returns true if the specified Cause is a Sequential type, false otherwise.

Signature

export declare const isSequentialType: <E>(self: Cause<E>) => self is Sequential<E>

Added in v1.0.0

rendering

pretty

Returns the specified Cause as a pretty-printed string.

Signature

export declare const pretty: <E>(cause: Cause<E>) => string

Added in v1.0.0

sequencing

flatMap

Signature

export declare const flatMap: {
  <E, E2>(f: (e: E) => Cause<E2>): (self: Cause<E>) => Cause<E2>
  <E, E2>(self: Cause<E>, f: (e: E) => Cause<E2>): Cause<E2>
}

Added in v1.0.0

flatten

Signature

export declare const flatten: <E>(self: Cause<Cause<E>>) => Cause<E>

Added in v1.0.0

symbols

CauseTypeId

Signature

export declare const CauseTypeId: typeof CauseTypeId

Added in v1.0.0

CauseTypeId (type alias)

Signature

export type CauseTypeId = typeof CauseTypeId

Added in v1.0.0

IllegalArgumentExceptionTypeId

Signature

export declare const IllegalArgumentExceptionTypeId: typeof IllegalArgumentExceptionTypeId

Added in v1.0.0

IllegalArgumentExceptionTypeId (type alias)

Signature

export type IllegalArgumentExceptionTypeId = typeof IllegalArgumentExceptionTypeId

Added in v1.0.0

InterruptedExceptionTypeId

Signature

export declare const InterruptedExceptionTypeId: typeof InterruptedExceptionTypeId

Added in v1.0.0

InterruptedExceptionTypeId (type alias)

Signature

export type InterruptedExceptionTypeId = typeof InterruptedExceptionTypeId

Added in v1.0.0

InvalidHubCapacityExceptionTypeId

Signature

export declare const InvalidHubCapacityExceptionTypeId: typeof InvalidHubCapacityExceptionTypeId

Added in v1.0.0

InvalidHubCapacityExceptionTypeId (type alias)

Signature

export type InvalidHubCapacityExceptionTypeId = typeof InvalidHubCapacityExceptionTypeId

Added in v1.0.0

NoSuchElementExceptionTypeId

Signature

export declare const NoSuchElementExceptionTypeId: typeof NoSuchElementExceptionTypeId

Added in v1.0.0

NoSuchElementExceptionTypeId (type alias)

Signature

export type NoSuchElementExceptionTypeId = typeof NoSuchElementExceptionTypeId

Added in v1.0.0

RuntimeExceptionTypeId

Signature

export declare const RuntimeExceptionTypeId: typeof RuntimeExceptionTypeId

Added in v1.0.0

RuntimeExceptionTypeId (type alias)

Signature

export type RuntimeExceptionTypeId = typeof RuntimeExceptionTypeId

Added in v1.0.0

utils

Cause (namespace)

Added in v1.0.0

Variance (interface)

Signature

export interface Variance<E> {
  readonly [CauseTypeId]: {
    readonly _E: (_: never) => E
  }
}

Added in v1.0.0