Yieldable Errors

Errors created with Data.Error and Data.TaggedError are yieldable. Inside Effect.gen, yielding one is equivalent to passing it to Effect.fail.

Data.Error

Use Data.Error when the error does not need a discriminant tag.

Example (Yielding a Custom Error)

1
import { Data, Effect, Exit } from "effect"
2

3
class InvalidInput extends Data.Error<{
4
  readonly message: string
5
}> {}
6

7
const program = Effect.gen(function* () {
8
  return yield* new InvalidInput({ message: "Name is required" })
9
})
10

11
Effect.runSyncExit(program) // => Exit.fail(new InvalidInput({ message: "Name is required" }))

Data.TaggedError

Data.TaggedError adds a readonly _tag field. Tagged errors form discriminated unions that can be handled precisely with Effect.catchTag and Effect.catchTags.

Example (Handling Tagged Errors)

1
import { Data, Effect } from "effect"
2

3
class NotFound extends Data.TaggedError("NotFound")<{
4
  readonly id: string
5
}> {}
6

7
class PermissionDenied extends Data.TaggedError("PermissionDenied")<{
8
  readonly id: string
9
}> {}
10

11
const loadUser = (
12
  id: string,
13
): Effect.Effect<string, NotFound | PermissionDenied> =>
14
  Effect.gen(function* () {
15
    if (id === "missing") {
16
      return yield* new NotFound({ id })
17
    }
18
    return `user:${id}`
19
  })
20

21
const program = loadUser("missing").pipe(
22
  Effect.catchTag("NotFound", (error) => Effect.succeed(`No user ${error.id}`)),
23
)
24

25
Effect.runSync(program) // => "No user missing"

Use tagged errors for domain errors that callers may need to distinguish. The class is both the error’s constructor and its TypeScript type.