Yieldable Errors

Yieldable Errors are special types of errors that can be yielded directly within a generator function using Effect.gen. These errors allow you to handle them intuitively, without needing to explicitly invoke Effect.fail. This simplifies how you manage custom errors in your code.

Data.Error

The Data.Error constructor provides a way to define a base class for yieldable errors.

Example (Creating and Yielding a Custom Error)

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

3
// Define a custom error class extending Data.Error
4
class MyError extends Data.Error<{ message: string }> {}
5

6
export const program = Effect.gen(function* () {
7
  // Yield a custom error (equivalent to failing with MyError)
8
  yield* new MyError({ message: "Oh no!" })
9
})
10

11
Effect.runPromiseExit(program).then(console.log)
12
/*
13
Output:
14
{
15
  _id: 'Exit',
16
  _tag: 'Failure',
17
  cause: { _id: 'Cause', _tag: 'Fail', failure: { message: 'Oh no!' } }
18
}
19
*/

Data.TaggedError

The Data.TaggedError constructor lets you define custom yieldable errors with unique tags. Each error has a _tag property, allowing you to easily distinguish between different error types. This makes it convenient to handle specific tagged errors using functions like Effect.catchTag or Effect.catchTags.

Example (Handling Multiple Tagged Errors)

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

3
// An error with _tag: "Foo"
4
class FooError extends Data.TaggedError("Foo")<{
5
  message: string
6
}> {}
7

8
// An error with _tag: "Bar"
9
class BarError extends Data.TaggedError("Bar")<{
10
  randomNumber: number
11
}> {}
12

13
const program = Effect.gen(function* () {
14
  const n = yield* Random.next
15
  return n > 0.5
16
    ? "yay!"
17
    : n < 0.2
18
      ? yield* new FooError({ message: "Oh no!" })
19
      : yield* new BarError({ randomNumber: n })
20
}).pipe(
21
  // Handle different tagged errors using catchTags
22
  Effect.catchTags({
23
    Foo: (error) => Effect.succeed(`Foo error: ${error.message}`),
24
    Bar: (error) => Effect.succeed(`Bar error: ${error.randomNumber}`),
25
  }),
26
)
27

28
Effect.runPromise(program).then(console.log, console.error)
29
/*
30
Example Output (n < 0.2):
31
Foo error: Oh no!
32
*/