The Cause module provides a lossless error model that captures all information about failures in Effect workflows, including parallel errors, sequential errors, defects, and interruptions.
Type
type Cause<E> =
| Empty
| Fail<E>
| Die
| Interrupt
| Sequential<E>
| Parallel<E>
Effect.
The error type contained in the cause
A data structure capturing all failure information
Cause Variants
Empty
Represents a lack of errors.
interface Empty extends Cause.Variance<never>
Fail
Represents an expected error.
interface Fail<out E> extends Cause.Variance<E> {
readonly _tag: "Fail"
readonly error: E
}
Die
Represents an unexpected defect.
interface Die extends Cause.Variance<never> {
readonly _tag: "Die"
readonly defect: unknown
}
The defect (unrecoverable error)
Interrupt
Represents fiber interruption.
interface Interrupt extends Cause.Variance<never> {
readonly _tag: "Interrupt"
readonly fiberId: FiberId.FiberId
}
The ID of the interrupted fiber
Sequential
Represents sequential composition of two causes.
interface Sequential<out E> extends Cause.Variance<E> {
readonly _tag: "Sequential"
readonly left: Cause<E>
readonly right: Cause<E>
}
Parallel
Represents parallel composition of two causes.
interface Parallel<out E> extends Cause.Variance<E> {
readonly _tag: "Parallel"
readonly left: Cause<E>
readonly right: Cause<E>
}
Constructors
empty
Creates an Empty cause.
const empty: Cause<never>
A cause representing no error
import { Cause } from "effect"
const noCause = Cause.empty
fail
Creates a Fail cause from an expected error.
const fail: <E>(error: E) => Cause<E>
A cause representing a typed error
import { Cause } from "effect"
const cause = Cause.fail("Something went wrong")
die
Creates a Die cause from an unexpected error.
const die: (defect: unknown) => Cause<never>
A cause representing an unrecoverable defect
import { Cause } from "effect"
const cause = Cause.die(new Error("Unexpected crash"))
interrupt
Creates an Interrupt cause from a FiberId.
const interrupt: (fiberId: FiberId.FiberId) => Cause<never>
The fiber ID that was interrupted
A cause representing an interruption
parallel
Combines two causes in parallel.
const parallel: <E, E2>(left: Cause<E>, right: Cause<E2>) => Cause<E | E2>
A cause combining both errors in parallel
import { Cause } from "effect"
const cause = Cause.parallel(
Cause.fail("error1"),
Cause.fail("error2")
)
sequential
Combines two causes sequentially.
const sequential: <E, E2>(left: Cause<E>, right: Cause<E2>) => Cause<E | E2>
A cause combining both errors sequentially
Guards
isCause
Checks if a value is a Cause.
const isCause: (u: unknown) => u is Cause<unknown>
isEmptyType
Checks if a Cause is an Empty type.
const isEmptyType: <E>(self: Cause<E>) => self is Empty
isFailType
Checks if a Cause is a Fail type.
const isFailType: <E>(self: Cause<E>) => self is Fail<E>
isDieType
Checks if a Cause is a Die type.
const isDieType: <E>(self: Cause<E>) => self is Die
isInterruptType
Checks if a Cause is an Interrupt type.
const isInterruptType: <E>(self: Cause<E>) => self is Interrupt
Getters
isEmpty
Checks if a Cause is entirely empty.
const isEmpty: <E>(self: Cause<E>) => boolean
true if the cause contains no errors
isFailure
Checks if a Cause contains a failure.
const isFailure: <E>(self: Cause<E>) => boolean
true if the cause includes any Fail error
isDie
Checks if a Cause contains a defect.
const isDie: <E>(self: Cause<E>) => boolean
isInterrupted
Checks if a Cause contains an interruption.
const isInterrupted: <E>(self: Cause<E>) => boolean
failures
Extracts all recoverable errors from a Cause.
const failures: <E>(self: Cause<E>) => Chunk.Chunk<E>
The cause to extract from
A collection of all Fail values
import { Cause } from "effect"
const cause = Cause.parallel(
Cause.fail("error1"),
Cause.fail("error2")
)
const errors = Cause.failures(cause)
// Chunk.Chunk<string>
defects
Extracts all unrecoverable defects from a Cause.
const defects: <E>(self: Cause<E>) => Chunk.Chunk<unknown>
interruptors
Collects all FiberIds responsible for interrupting a fiber.
const interruptors: <E>(self: Cause<E>) => HashSet.HashSet<FiberId.FiberId>
Mapping
map
Transforms the errors in a Cause.
const map: {
<E, E2>(f: (e: E) => E2): (self: Cause<E>) => Cause<E2>
<E, E2>(self: Cause<E>, f: (e: E) => E2): Cause<E2>
}
The transformation function
A cause with transformed errors
import { Cause } from "effect"
const cause = Cause.fail("error")
const mapped = Cause.map(cause, (e) => e.toUpperCase())
flatMap
Transforms errors in a Cause into new causes.
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>
}
Matching
match
Transforms a Cause into a single value using custom handlers.
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 onSequential: (left: Z, right: Z) => Z
readonly onParallel: (left: Z, right: Z) => Z
}): (self: Cause<E>) => Z
...
}
Handlers for each cause type
The result of applying the appropriate handler
import { Cause } from "effect"
const cause = Cause.fail("error")
const result = Cause.match(cause, {
onEmpty: 0,
onFail: (error) => 1,
onDie: (defect) => 2,
onInterrupt: (fiberId) => 3,
onSequential: (left, right) => left + right,
onParallel: (left, right) => left + right
})
// result: 1
Error Types
RuntimeException
An error representing a runtime error.
const RuntimeException: new(message?: string) => RuntimeException
InterruptedException
An error representing fiber interruption.
const InterruptedException: new(message?: string) => InterruptedException
IllegalArgumentException
An error representing an invalid argument.
const IllegalArgumentException: new(message?: string) => IllegalArgumentException
NoSuchElementException
An error that occurs when an expected element is missing.
const NoSuchElementException: new(message?: string) => NoSuchElementException
TimeoutException
An error representing a computation that timed out.
const TimeoutException: new(message?: string) => TimeoutException
UnknownException
A checked exception for handling unknown errors.
const UnknownException: new(error: unknown, message?: string) => UnknownException
The unknown error to wrap
The error argument is stored in the error property and passed as the cause to preserve stack traces.
pretty
Converts a Cause into a human-readable string.
const pretty: <E>(cause: Cause<E>, options?: {
readonly renderErrorCause?: boolean
}) => string
Whether to render the error cause
A formatted string representation
import { Cause } from "effect"
const cause = Cause.fail("Something went wrong")
console.log(Cause.pretty(cause))