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

import { Effect } from "effect"

const simulatedTask = Effect.fail("Oh no!").pipe(Effect.as(1))

const mapped = Effect.mapError(
  simulatedTask,
  (message) => new Error(message)
)

We can observe that the type in the error channel of our program has changed from string to Error.

Note

It’s important to note that using the Effect.mapError function does not change the overall success or failure of the effect. If the mapped effect is successful, then the mapping function is ignored. In other words, the Effect.mapError operation only applies the transformation to the error channel of the effect, while leaving the success channel unchanged.

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

import { Effect } from "effect"

const simulatedTask = Effect.fail("Oh no!").pipe(Effect.as(1))

const modified = Effect.mapBoth(simulatedTask, {
  onFailure: (message) => new Error(message),
  onSuccess: (n) => n > 0
})

After using mapBoth, we can observe that the type of our program has changed from Effect<number, string> to Effect<boolean, Error>.

Note

It’s important to note that using the mapBoth function does not change the overall success or failure of the effect. It only transforms the values in the error and success channels while preserving the effect’s original success or failure status.

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

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

const task1 = Effect.filterOrFail(
  Random.nextRange(-1, 1),
  (n) => n >= 0,
  () => "random number is negative"
)

const task2 = Effect.filterOrDie(
  Random.nextRange(-1, 1),
  (n) => n >= 0,
  () => new Cause.IllegalArgumentException("random number is negative")
)

const task3 = Effect.filterOrDieMessage(
  Random.nextRange(-1, 1),
  (n) => n >= 0,
  "random number is negative"
)

const task4 = Effect.filterOrElse(
  Random.nextRange(-1, 1),
  (n) => n >= 0,
  () => task3
)

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.

In addition to the filtering capabilities discussed earlier, you have the option to further refine and narrow down the type of the success channel by providing a user-defined type guard to the filterOr* APIs. This not only enhances type safety but also improves code clarity.

Example (Using a Type Guard)

import { Effect, pipe } from "effect"

// Define a user interface
interface User {
  readonly name: string
}

// Assume an asynchronous authentication function
declare const auth: () => Promise<User | null>

const program = pipe(
  Effect.promise(() => auth()),
  Effect.filterOrFail(
    // Define a guard to narrow down the type
    (user): user is User => user !== null,
    () => new Error("Unauthorized")
  ),
  // The 'user' here has type `User`, not `User | null`
  Effect.andThen((user) => user.name)
)

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. This refined type information improves the reliability of your code and makes it more understandable.

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.

API	Description
tapError	Executes an effectful operation to inspect the failure of an effect without altering it.
tapErrorTag	Specifically inspects a failure with a particular tag, allowing focused error handling.
tapErrorCause	Inspects the underlying cause of an effect’s failure.
tapDefect	Specifically inspects non-recoverable failures or defects in an effect (i.e., one or more Die causes).
tapBoth	Inspects both success and failure outcomes of an effect, performing different actions based on the result.

Note

Utilizing these error inspection tools does not alter the outcome or type of the effect.

tapError

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

Example

import { Effect, Console } from "effect"

// Create an effect that is designed to fail, simulating an occurrence
// of a network error
const task: Effect.Effect<number, string> = Effect.fail("NetworkError")

// Log the error message if the task fails. This function only executes
// if there is an error, providing a method to handle or inspect errors
// without altering the outcome of the original effect.
const tapping = Effect.tapError(task, (error) =>
  Console.log(`expected error: ${error}`)
)

Effect.runFork(tapping)
/*
Output:
expected error: NetworkError
*/

tapErrorTag

Specifically inspects a failure with a particular tag, allowing focused error handling.

Example

import { Effect, Console } from "effect"

class NetworkError {
  readonly _tag = "NetworkError"
  constructor(readonly statusCode: number) {}
}

class ValidationError {
  readonly _tag = "ValidationError"
  constructor(readonly field: string) {}
}

// Create an effect that is designed to fail, simulating an
// occurrence of a network error
const task: Effect.Effect<number, NetworkError | ValidationError> =
  Effect.fail(new NetworkError(504))

// Apply an error handling function only to errors tagged as
// "NetworkError", and log the corresponding status code of the error.
const tapping = Effect.tapErrorTag(task, "NetworkError", (error) =>
  Console.log(`expected error: ${error.statusCode}`)
)

Effect.runFork(tapping)
/*
Output:
expected error: 504
*/

tapErrorCause

Inspects the underlying cause of an effect’s failure.

Example

import { Effect, Console } from "effect"

// Create an effect that is designed to fail, simulating an occurrence of a
// network error
const task1: Effect.Effect<number, string> = Effect.fail("NetworkError")

// This will log the cause of any expected error or defect
const tapping1 = Effect.tapErrorCause(task1, (cause) =>
  Console.log(`error cause: ${cause}`)
)

Effect.runFork(tapping1)
/*
Output:
error cause: Error: NetworkError
*/

// Simulate a severe failure in the system by causing a defect with
// a specific message.
const task2: Effect.Effect<number, string> = Effect.dieMessage(
  "Something went wrong"
)

// This will log the cause of any expected error or defect
const tapping2 = Effect.tapErrorCause(task2, (cause) =>
  Console.log(`error cause: ${cause}`)
)

Effect.runFork(tapping2)
/*
Output:
error cause: RuntimeException: Something went wrong
  ... stack trace ...
*/

tapDefect

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

Example

import { Effect, Console } from "effect"

// Create an effect that is designed to fail, simulating an occurrence of a
// network error
const task1: Effect.Effect<number, string> = Effect.fail("NetworkError")

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

Effect.runFork(tapping1)
/*
No Output
*/

// Simulate a severe failure in the system by causing a defect with
// a specific message.
const task2: Effect.Effect<number, string> = Effect.dieMessage(
  "Something went wrong"
)

// This will only log defects, not errors
const tapping2 = Effect.tapDefect(task2, (cause) =>
  Console.log(`defect: ${cause}`)
)

Effect.runFork(tapping2)
/*
Output:
defect: RuntimeException: Something went wrong
  ... stack trace ...
*/

tapBoth

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

Example

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

// Simulate an effect that might fail
const task = Effect.filterOrFail(
  Random.nextRange(-1, 1),
  (n) => n >= 0,
  () => "random number is negative"
)

// Define an effect that logs both success and failure outcomes
// of the task
const tapping = Effect.tapBoth(task, {
  onFailure: (error) => Console.log(`failure: ${error}`),
  onSuccess: (randomNumber) =>
    Console.log(`random number: ${randomNumber}`)
})

Effect.runFork(tapping)
/*
Example Output:
failure: random number is negative
*/

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>

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:

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

const simulatedTask = Effect.fail("Oh uh!").pipe(Effect.as(2))

const program = Effect.gen(function* () {
  const failureOrSuccess = yield* Effect.either(simulatedTask)
  if (Either.isLeft(failureOrSuccess)) {
    const error = failureOrSuccess.left
    yield* Console.log(`failure: ${error}`)
    return 0
  } else {
    const value = failureOrSuccess.right
    yield* Console.log(`success: ${value}`)
    return value
  }
})

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

import { Effect, Console } from "effect"

const simulatedTask = Effect.fail("Oh uh!").pipe(Effect.as(2))

const program = Effect.gen(function* () {
  const cause = yield* Effect.cause(simulatedTask)
  yield* Console.log(cause)
})

Merging the Error Channel into the Success Channel

Using the Effect.merge function, you can merge the error channel into the success channel, creating an effect that always succeeds with the merged value.

Example

import { Effect } from "effect"

const simulatedTask = Effect.fail("Oh uh!").pipe(Effect.as(2))

const merged = Effect.merge(simulatedTask)

Flipping Error and Success Channels

Using the Effect.flip function, you can flip the error and success channels of an effect, effectively swapping their roles.

Example

import { Effect } from "effect"

const simulatedTask = Effect.fail("Oh uh!").pipe(Effect.as(2))

const flipped = Effect.flip(simulatedTask)