Parallel and Sequential Errors

When working with Effect, if an error occurs, the default behavior is to fail with the first error encountered.

Example (Failing on the First Error)

Here, the program fails with the first error it encounters, "Oh uh!".

1
import { Effect } from "effect"
2

3
const fail = Effect.fail("Oh uh!")
4
const die = Effect.dieMessage("Boom!")
5

6
// Run both effects sequentially
7
const program = Effect.all([fail, die])
8

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

Parallel Errors

In some cases, you might encounter multiple errors, especially during concurrent computations. When tasks are run concurrently, multiple errors can happen at the same time.

Example (Handling Multiple Errors in Concurrent Computations)

In this example, both the fail and die effects are executed concurrently. Since both fail, the program will report multiple errors in the output.

1
import { Effect } from "effect"
2

3
const fail = Effect.fail("Oh uh!")
4
const die = Effect.dieMessage("Boom!")
5

6
// Run both effects concurrently
7
const program = Effect.all([fail, die], {
8
  concurrency: "unbounded",
9
}).pipe(Effect.asVoid)
10

11
Effect.runPromiseExit(program).then(console.log)
12
/*
13
Output:
14
{
15
  _id: 'Exit',
16
  _tag: 'Failure',
17
  cause: {
18
    _id: 'Cause',
19
    _tag: 'Parallel',
20
    left: { _id: 'Cause', _tag: 'Fail', failure: 'Oh uh!' },
21
    right: { _id: 'Cause', _tag: 'Die', defect: [Object] }
22
  }
23
}
24
*/

parallelErrors

Effect provides a function called Effect.parallelErrors that captures all failure errors from concurrent operations in the error channel.

Example (Capturing Multiple Concurrent Failures)

In this example, Effect.parallelErrors combines the errors from fail1 and fail2 into a single error.

1
import { Effect } from "effect"
2

3
const fail1 = Effect.fail("Oh uh!")
4
const fail2 = Effect.fail("Oh no!")
5
const die = Effect.dieMessage("Boom!")
6

7
// Run all effects concurrently and capture all errors
8
const program = Effect.all([fail1, fail2, die], {
9
  concurrency: "unbounded",
10
}).pipe(Effect.asVoid, Effect.parallelErrors)
11

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

Sequential Errors

When working with resource-safety operators like Effect.ensuring, you may encounter multiple sequential errors. This happens because regardless of whether the original effect has any errors or not, the finalizer is uninterruptible and will always run.

Example (Handling Multiple Sequential Errors)

In this example, both fail and the finalizer die result in sequential errors, and both are captured.

1
import { Effect } from "effect"
2

3
// Simulate an effect that fails
4
const fail = Effect.fail("Oh uh!")
5

6
// Simulate a finalizer that causes a defect
7
const die = Effect.dieMessage("Boom!")
8

9
// The finalizer 'die' will always run, even if 'fail' fails
10
const program = fail.pipe(Effect.ensuring(die))
11

12
Effect.runPromiseExit(program).then(console.log)
13
/*
14
Output:
15
{
16
  _id: 'Exit',
17
  _tag: 'Failure',
18
  cause: {
19
    _id: 'Cause',
20
    _tag: 'Sequential',
21
    left: { _id: 'Cause', _tag: 'Fail', failure: 'Oh uh!' },
22
    right: { _id: 'Cause', _tag: 'Die', defect: [Object] }
23
  }
24
}
25
*/