Error Channel Operations

In Effect you can perform various operations on the error channel of effects. These operations allow you to transform, inspect, and handle errors in different ways. Let’s explore some of these operations.

Map Operations

mapError

The Effect.mapError function is used when you need to transform or modify an error produced by an effect, without affecting the success value. This can be helpful when you want to add extra information to the error or change its type.

Example (Mapping an Error)

Here, the error type changes from string to Error.

1
import { Effect } from "effect"
2

3
//      ┌─── Effect<number, string, never>
4
//      ▼
5
const simulatedTask = Effect.fail("Oh no!").pipe(Effect.as(1))
6

7
//      ┌─── Effect<number, Error, never>
8
//      ▼
9
const mapped = Effect.mapError(simulatedTask, (message) => new Error(message))

mapBoth

The Effect.mapBoth function allows you to apply transformations to both channels: the error channel and the success channel of an effect. It takes two map functions as arguments: one for the error channel and the other for the success channel.

Example (Mapping Both Success and Error)

1
import { Effect } from "effect"
2

3
//      ┌─── Effect<number, string, never>
4
//      ▼
5
const simulatedTask = Effect.fail("Oh no!").pipe(Effect.as(1))
6

7
//      ┌─── Effect<boolean, Error, never>
8
//      ▼
9
const modified = Effect.mapBoth(simulatedTask, {
10
  onFailure: (message) => new Error(message),
11
  onSuccess: (n) => n > 0,
12
})

Filtering the Success Channel

The Effect library provides several operators to filter values on the success channel based on a given predicate.

These operators offer different strategies for handling cases where the predicate fails:

API	Description
`filterOrFail`	This operator filters the values on the success channel based on a predicate. If the predicate fails for any value, the original effect fails with an error.
`filterOrDie` / `filterOrDieMessage`	These operators also filter the values on the success channel based on a predicate. If the predicate fails for any value, the original effect terminates abruptly. The `filterOrDieMessage` variant allows you to provide a custom error message.
`filterOrElse`	This operator filters the values on the success channel based on a predicate. If the predicate fails for any value, an alternative effect is executed instead.

Example (Filtering Success Values)

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

3
// Fail with a custom error if predicate is false
4
const task1 = Effect.filterOrFail(
5
  Random.nextRange(-1, 1),
6
  (n) => n >= 0,
7
  () => "random number is negative",
8
)
9

10
// Die with a custom exception if predicate is false
11
const task2 = Effect.filterOrDie(
12
  Random.nextRange(-1, 1),
13
  (n) => n >= 0,
14
  () => new Cause.IllegalArgumentException("random number is negative"),
15
)
16

17
// Die with a custom error message if predicate is false
18
const task3 = Effect.filterOrDieMessage(
19
  Random.nextRange(-1, 1),
20
  (n) => n >= 0,
21
  "random number is negative",
22
)
23

24
// Run an alternative effect if predicate is false
25
const task4 = Effect.filterOrElse(
26
  Random.nextRange(-1, 1),
27
  (n) => n >= 0,
28
  () => task3,
29
)

It’s important to note that depending on the specific filtering operator used, the effect can either fail, terminate abruptly, or execute an alternative effect when the predicate fails. Choose the appropriate operator based on your desired error handling strategy and program logic.

The filtering APIs can also be combined with user-defined type guards to improve type safety and code clarity. This ensures that only valid types pass through.

Example (Using a Type Guard)

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

3
// Define a user interface
4
interface User {
5
  readonly name: string
6
}
7

8
// Simulate an asynchronous authentication function
9
declare const auth: () => Promise<User | null>
10

11
const program = pipe(
12
  Effect.promise(() => auth()),
13
  // Use filterOrFail with a custom type guard to ensure user is not null
14
  Effect.filterOrFail(
15
    (user): user is User => user !== null, // Type guard
16
    () => new Error("Unauthorized"),
17
  ),
18
  // 'user' now has the type `User` (not `User | null`)
19
  Effect.andThen((user) => user.name),
20
)

In the example above, a guard is used within the filterOrFail API to ensure that the user is of type User rather than User | null.

If you prefer, you can utilize a pre-made guard like Predicate.isNotNull for simplicity and consistency.

Inspecting Errors

Similar to tapping for success values, Effect provides several operators for inspecting error values. These operators allow developers to observe failures or underlying issues without modifying the outcome.

tapError

Executes an effectful operation to inspect the failure of an effect without altering it.

Example (Inspecting Errors)

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

3
// Simulate a task that fails with an error
4
const task: Effect.Effect<number, string> = Effect.fail("NetworkError")
5

6
// Use tapError to log the error message when the task fails
7
const tapping = Effect.tapError(task, (error) => Console.log(`expected error: ${error}`))
8

9
Effect.runFork(tapping)
10
/*
11
Output:
12
expected error: NetworkError
13
*/

tapErrorTag

This function allows you to inspect errors that match a specific tag, helping you handle different error types more precisely.

Example (Inspecting Tagged Errors)

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

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

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

11
// Create a task that fails with a NetworkError
12
const task: Effect.Effect<number, NetworkError | ValidationError> = Effect.fail(
13
  new NetworkError({ statusCode: 504 }),
14
)
15

16
// Use tapErrorTag to inspect only NetworkError types
17
// and log the status code
18
const tapping = Effect.tapErrorTag(task, "NetworkError", (error) =>
19
  Console.log(`expected error: ${error.statusCode}`),
20
)
21

22
Effect.runFork(tapping)
23
/*
24
Output:
25
expected error: 504
26
*/

tapErrorCause

This function inspects the complete cause of an error, including failures and defects.

Example (Inspecting Error Causes)

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

3
// Create a task that fails with a NetworkError
4
const task1: Effect.Effect<number, string> = Effect.fail("NetworkError")
5

6
const tapping1 = Effect.tapErrorCause(task1, (cause) => Console.log(`error cause: ${cause}`))
7

8
Effect.runFork(tapping1)
9
/*
10
Output:
11
error cause: Error: NetworkError
12
*/
13

14
// Simulate a severe failure in the system
15
const task2: Effect.Effect<number, string> = Effect.dieMessage("Something went wrong")
16

17
const tapping2 = Effect.tapErrorCause(task2, (cause) => Console.log(`error cause: ${cause}`))
18

19
Effect.runFork(tapping2)
20
/*
21
Output:
22
error cause: RuntimeException: Something went wrong
23
  ... stack trace ...
24
*/

tapDefect

Specifically inspects non-recoverable failures or defects in an effect (i.e., one or more Die causes).

Example (Inspecting Defects)

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

3
// Simulate a task that fails with a recoverable error
4
const task1: Effect.Effect<number, string> = Effect.fail("NetworkError")
5

6
// tapDefect won't log anything because NetworkError is not a defect
7
const tapping1 = Effect.tapDefect(task1, (cause) => Console.log(`defect: ${cause}`))
8

9
Effect.runFork(tapping1)
10
/*
11
No Output
12
*/
13

14
// Simulate a severe failure in the system
15
const task2: Effect.Effect<number, string> = Effect.dieMessage("Something went wrong")
16

17
// Log the defect using tapDefect
18
const tapping2 = Effect.tapDefect(task2, (cause) => Console.log(`defect: ${cause}`))
19

20
Effect.runFork(tapping2)
21
/*
22
Output:
23
defect: RuntimeException: Something went wrong
24
  ... stack trace ...
25
*/

tapBoth

Inspects both success and failure outcomes of an effect, performing different actions based on the result.

Example (Inspecting Both Success and Failure)

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

3
// Simulate a task that might fail
4
const task = Effect.filterOrFail(
5
  Random.nextRange(-1, 1),
6
  (n) => n >= 0,
7
  () => "random number is negative",
8
)
9

10
// Use tapBoth to log both success and failure outcomes
11
const tapping = Effect.tapBoth(task, {
12
  onFailure: (error) => Console.log(`failure: ${error}`),
13
  onSuccess: (randomNumber) => Console.log(`random number: ${randomNumber}`),
14
})
15

16
Effect.runFork(tapping)
17
/*
18
Example Output:
19
failure: random number is negative
20
*/

Exposing Errors in The Success Channel

The Effect.either function transforms an Effect<A, E, R> into an effect that encapsulates both potential failure and success within an Either data type:

Effect<A, E, R> -> Effect<Either<A, E>, never, R>

This means if you have an effect with the following type:

Effect<string, HttpError, never>

and you call Effect.either on it, the type becomes:

Effect<Either<string, HttpError>, never, never>

The resulting effect cannot fail because the potential failure is now represented within the Either’s Left type. The error type of the returned Effect is specified as never, confirming that the effect is structured to not fail.

This function becomes especially useful when recovering from effects that may fail when using Effect.gen:

Example (Using Effect.either to Handle Errors)

1
import { Effect, Either, Console } from "effect"
2

3
// Simulate a task that fails
4
//
5
//      ┌─── Either<number, string, never>
6
//      ▼
7
const program = Effect.fail("Oh uh!").pipe(Effect.as(2))
8

9
//      ┌─── Either<number, never, never>
10
//      ▼
11
const recovered = Effect.gen(function* () {
12
  //      ┌─── Either<number, string>
13
  //      ▼
14
  const failureOrSuccess = yield* Effect.either(program)
15
  if (Either.isLeft(failureOrSuccess)) {
16
    const error = failureOrSuccess.left
17
    yield* Console.log(`failure: ${error}`)
18
    return 0
19
  } else {
20
    const value = failureOrSuccess.right
21
    yield* Console.log(`success: ${value}`)
22
    return value
23
  }
24
})
25

26
Effect.runPromise(recovered).then(console.log)
27
/*
28
Output:
29
failure: Oh uh!
30
0
31
*/

Exposing the Cause in The Success Channel

You can use the Effect.cause function to expose the cause of an effect, which is a more detailed representation of failures, including error messages and defects.

Example (Logging the Cause of Failure)

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

3
//      ┌─── Effect<number, string, never>
4
//      ▼
5
const program = Effect.fail("Oh uh!").pipe(Effect.as(2))
6

7
//      ┌─── Effect<void, never, never>
8
//      ▼
9
const recovered = Effect.gen(function* () {
10
  const cause = yield* Effect.cause(program)
11
  yield* Console.log(cause)
12
})

Merging the Error Channel into the Success Channel

The Effect.merge function allows you to combine the error channel with the success channel. This results in an effect that never fails; instead, both successes and errors are handled as values in the success channel.

Example (Combining Error and Success Channels)

1
import { Effect } from "effect"
2

3
//      ┌─── Effect<number, string, never>
4
//      ▼
5
const program = Effect.fail("Oh uh!").pipe(Effect.as(2))
6

7
//      ┌─── Effect<number | string, never, never>
8
//      ▼
9
const recovered = Effect.merge(program)

Flipping Error and Success Channels

The Effect.flip function allows you to switch the error and success channels of an effect. This means that what was previously a success becomes the error, and vice versa.

Example (Swapping Error and Success Channels)

1
import { Effect } from "effect"
2

3
//      ┌─── Effect<number, string, never>
4
//      ▼
5
const program = Effect.fail("Oh uh!").pipe(Effect.as(2))
6

7
//      ┌─── Effect<string, number, never>
8
//      ▼
9
const flipped = Effect.flip(program)