48 — Cause and the complete failure model

In v4, Cause<E> contains a flat reasons array. Each reason is a typed Fail, a defect (Die), or an Interrupt. Use Cause.findErrorOption, Cause.hasFails, Cause.hasDies, and Cause.hasInterruptsOnly rather than matching a recursive tree.

Most feature code handles typed errors with Effect.catch or catchTag. Use Effect.catchCause at an operational boundary that genuinely needs defects and interruption too.

The full test suite

The index.test.ts for this lesson, verbatim from steps/48-cause-and-sandbox/.

1
import { describe, expect, it } from "vite-plus/test"
2
import { Cause, Effect, Exit, Option } from "effect"
3

4
describe("Cause", () => {
5
  it("stores typed failures, defects, and interruption as flat reasons", () => {
6
    const exit = Effect.runSyncExit(Effect.fail("typed"))
7
    expect(Exit.isFailure(exit)).toBe(true)
8
    if (Exit.isFailure(exit)) {
9
      expect(Cause.hasFails(exit.cause)).toBe(true)
10
      expect(Option.getOrThrow(Cause.findErrorOption(exit.cause))).toBe("typed")
11
      expect(exit.cause.reasons).toHaveLength(1)
12
    }
13
  })
14

15
  it("uses catchCause only at a boundary that needs the full failure model", () => {
16
    const label = Effect.die("defect").pipe(
17
      Effect.catchCause((cause) => Effect.succeed(Cause.hasDies(cause) ? "defect" : "failure")),
18
    )
19
    expect(Effect.runSync(label)).toBe("defect")
20
  })
21
})

08·01Cause & Sandbox

48 — Cause and the complete failure model

The full test suite