Error Channel Operations

Error-channel operators change or observe an Effect’s failure behavior without requiring an immediate recovery.

Transforming Channels

mapError

Effect.mapError transforms a typed error while leaving the success value unchanged.

Example (Mapping an Error)

1
import { Effect } from "effect"
2

3
const program = Effect.fail("unavailable").pipe(
4
  Effect.mapError((message) => new Error(message)),
5
)
6

7
const error = Effect.runSync(Effect.flip(program))
8

9
error.message // => "unavailable"

mapBoth

Effect.mapBoth transforms the success and error channels in one operation.

1
import { Effect } from "effect"
2

3
const program = Effect.succeed(2).pipe(
4
  Effect.mapBoth({
5
    onFailure: (message: string) => new Error(message),
6
    onSuccess: (value) => value * 2,
7
  }),
8
)
9

10
Effect.runSync(program) // => 4

The eager variants mapErrorEager and mapBothEager are optimizations for mappings that can be evaluated immediately.

Filtering the Success Channel

Effect.filterOrFail keeps a success value when it satisfies a predicate and otherwise creates a typed failure.

Example (Validating a Success Value)

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

3
const program = Effect.succeed(-1).pipe(
4
  Effect.filterOrFail(
5
    (value) => value >= 0,
6
    (value) => `Expected a non-negative number, got ${value}`,
7
  ),
8
)
9

10
Effect.runSyncExit(program) // => Exit.fail("Expected a non-negative number, got -1")

A user-defined type guard narrows the success type.

1
import { Effect } from "effect"
2

3
interface User {
4
  readonly name: string
5
}
6

7
const user: Effect.Effect<User | null> = Effect.succeed({ name: "Alice" })
8

9
const name = user.pipe(
10
  Effect.filterOrFail(
11
    (value): value is User => value !== null,
12
    () => new Error("Unauthorized"),
13
  ),
14
  Effect.map((value) => value.name),
15
)
16

17
Effect.runSync(name) // => "Alice"

Use Effect.filterOrElse when a failed predicate should run another Effect instead of producing a value directly.

Inspecting Failures

Tap operators run an observation Effect and preserve the original outcome. If the observation itself fails, that new failure is composed with the original outcome.

tapError

Effect.tapError observes every typed error.

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

3
const observed: Array<string> = []
4
const program = Effect.fail("NetworkError").pipe(
5
  Effect.tapError((error) =>
6
    Effect.sync(() => {
7
      observed.push(error)
8
    }),
9
  ),
10
)
11

12
Effect.runSyncExit(program) // => Exit.fail("NetworkError")
13
observed // => ["NetworkError"]

tapErrorTag

Effect.tapErrorTag observes only one member of a tagged error union without handling it.

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

3
class NetworkError extends Data.TaggedError("NetworkError")<{
4
  readonly status: number
5
}> {}
6

7
const observed: Array<number> = []
8
const error = new NetworkError({ status: 503 })
9
const program = Effect.fail(error).pipe(
10
  Effect.tapErrorTag("NetworkError", (error) =>
11
    Effect.sync(() => {
12
      observed.push(error.status)
13
    }),
14
  ),
15
)
16

17
Effect.runSyncExit(program) // => Exit.fail(error)
18
observed // => [503]

tapCause

Effect.tapCause observes the complete Cause, including typed failures, defects, interruptions, and multiple reasons.

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

3
const observed: Array<ReadonlyArray<string>> = []
4
const program = Effect.die("boom").pipe(
5
  Effect.tapCause((cause) =>
6
    Effect.sync(() => {
7
      observed.push(cause.reasons.map((reason) => reason._tag))
8
    }),
9
  ),
10
)
11

12
Effect.runSyncExit(program) // => Exit.die("boom")
13
observed // => [["Die"]]

tapDefect

Effect.tapDefect observes defects only. It does not run for ordinary typed failures.

1
import { Effect } from "effect"
2

3
const observed: Array<unknown> = []
4
const program = Effect.die("boom").pipe(
5
  Effect.tapDefect((defect) =>
6
    Effect.sync(() => {
7
      observed.push(defect)
8
    }),
9
  ),
10
  Effect.ignoreCause,
11
)
12

13
Effect.runSync(program) // => undefined
14
observed // => ["boom"]

Use an ordinary Effect.tap after tapError when both successful values and typed failures need separate observations.

Moving Failures into the Success Channel

Effect.result exposes typed failures as Result.Failure values and Effect.exit exposes the complete outcome, including the full Cause.

Effect<A, E, R> -> Effect<Result<A, E>, never, R>
Effect<A, E, R> -> Effect<Exit<A, E>, never, R>

See Expected Errors for Effect.result and Unexpected Errors for Effect.exit.

When both a typed error and success should become the same success type, recover with Effect.catch:

1
import { Effect } from "effect"
2

3
const program: Effect.Effect<number, number> = Effect.fail(1)
4
const merged = program.pipe(Effect.catch(Effect.succeed))
5

6
Effect.runSync(merged) // => 1

Flipping the Channels

Effect.flip swaps the typed error and success channels.

1
import { Effect } from "effect"
2

3
const program = Effect.fail("unavailable").pipe(Effect.as(42))
4
const flipped = Effect.flip(program)
5

6
Effect.runSync(flipped) // => "unavailable"

flip is useful for focused transformations of an error channel, but mapError or a catch operator usually communicates the intent more directly.