意外错误

有些情况下您可能会遇到意外错误，需要决定如何处理它们。Effect 提供函数来帮助您处理这种情况，允许您在 Effect 执行期间发生错误时采取适当的行动。

创建不可恢复的错误

就像可以利用 Effect.fail 等组合子来创建 Effect<never, E, never> 类型的值一样，Effect 库提供了创建缺陷的工具。

当处理从业务逻辑角度无法恢复的错误时，创建缺陷是常见的需求，例如尝试建立在多次重试后被拒绝的连接。

在这些情况下，终止 Effect 的执行并转向报告（通过 stdout 或某些外部监控服务等输出）可能是最佳解决方案。

以下函数和组合子允许终止 Effect，通常用于将 Effect<A, E, R> 类型的值转换为 Effect<A, never, R> 类型的值，为程序员提供一个逃生舱口，无需处理和恢复没有合理恢复方式的错误。

die

创建一个使用指定错误终止纤程的 Effect。

当在代码中遇到不应作为常规错误处理，而是代表不可恢复缺陷的意外情况时，使用 Effect.die。

Effect.die 函数用于发出缺陷信号，它代表代码中的关键和意外错误。调用时，它产生一个不处理错误而是终止纤程的 Effect。

结果 Effect 的错误通道类型为 never，表明它无法从此失败中恢复。

示例（使用指定错误在除零时终止）

import { Effect } from "effect"

const divide = (a: number, b: number) =>
  b === 0
    ? Effect.die(new Error("Cannot divide by zero"))
    : Effect.succeed(a / b)

//      ┌─── Effect<number, never, never>
//      ▼
const program = divide(1, 0)

Effect.runPromise(program).catch(console.error)
/*
Output:
(FiberFailure) Error: Cannot divide by zero
  ...stack trace...
*/

dieMessage

创建一个使用包含指定消息的 RuntimeException 终止纤程的 Effect。

当您想要由于不可恢复的缺陷而终止纤程并在消息中包含清晰解释时，使用 Effect.dieMessage。

Effect.dieMessage 函数用于发出缺陷信号，代表代码中的关键和意外错误。调用时，它产生一个使用携带给定消息的 RuntimeException 终止纤程的 Effect。

结果 Effect 的错误通道类型为 never，表明它不处理或从错误中恢复。

示例（使用指定消息在除零时终止）

import { Effect } from "effect"

const divide = (a: number, b: number) =>
  b === 0
    ? Effect.dieMessage("Cannot divide by zero")
    : Effect.succeed(a / b)

//      ┌─── Effect<number, never, never>
//      ▼
const program = divide(1, 0)

Effect.runPromise(program).catch(console.error)
/*
Output:
(FiberFailure) RuntimeException: Cannot divide by zero
  ...stack trace...
*/

将失败转换为缺陷

orDie

将 Effect 的失败转换为纤程终止，从 Effect 的类型中移除错误。

当失败应被视为不可恢复的缺陷且不需要错误处理时，使用 Effect.orDie。

Effect.orDie 函数用于当您遇到不想处理或恢复的错误时。 它从 Effect 中移除错误类型，并确保任何失败都会终止纤程。 这对于将失败作为缺陷传播很有用，表明它们不应在 Effect 内处理。

示例（将错误作为缺陷传播）

import { Effect } from "effect"

const divide = (a: number, b: number) =>
  b === 0
    ? Effect.fail(new Error("Cannot divide by zero"))
    : Effect.succeed(a / b)

//      ┌─── Effect<number, never, never>
//      ▼
const program = Effect.orDie(divide(1, 0))

Effect.runPromise(program).catch(console.error)
/*
Output:
(FiberFailure) Error: Cannot divide by zero
  ...stack trace...
*/

orDieWith

将 Effect 的失败转换为使用自定义错误的纤程终止。

当失败应作为缺陷终止纤程，并且您想要为了清晰或调试目的自定义错误时，使用 Effect.orDieWith。

Effect.orDieWith 函数的行为类似于 Effect.orDie，但它允许您提供一个映射函数在终止纤程之前转换错误。这对于当您想要在失败作为缺陷传播时包含更详细或用户友好的错误的情况很有用。

示例（自定义缺陷）

import { Effect } from "effect"

const divide = (a: number, b: number) =>
  b === 0
    ? Effect.fail(new Error("Cannot divide by zero"))
    : Effect.succeed(a / b)

//      ┌─── Effect<number, never, never>
//      ▼
const program = Effect.orDieWith(
  divide(1, 0),
  (error) => new Error(`defect: ${error.message}`)
)

Effect.runPromise(program).catch(console.error)
/*
Output:
(FiberFailure) Error: defect: Cannot divide by zero
  ...stack trace...
*/

捕获所有缺陷

没有合理的方法从缺陷中恢复。我们即将讨论的函数应该只在 Effect 和外部系统之间的边界使用，用于传输缺陷信息以进行诊断或解释目的。

exit

Effect.exit 函数将 Effect<A, E, R> 转换为一个在 Exit 数据类型中封装潜在失败和成功的 Effect：

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

这意味着如果您有一个具有以下类型的 Effect：

Effect<string, HttpError, never>

并且您对其调用 Effect.exit，类型变为：

Effect<Exit<string, HttpError>, never, never>

结果 Effect 不能失败，因为潜在的失败现在在 Exit 的 Failure 类型中表示。 返回的 Effect 的错误类型被指定为 never，确认该 Effect 被构造为不会失败。

通过产生一个 Exit，我们获得了在生成器函数中对此类型进行”模式匹配”以处理失败和成功情况的能力。

示例（使用 Effect.exit 捕获缺陷）

import { Effect, Cause, Console, Exit } from "effect"

// Simulating a runtime error
const task = Effect.dieMessage("Boom!")

const program = Effect.gen(function* () {
  const exit = yield* Effect.exit(task)
  if (Exit.isFailure(exit)) {
    const cause = exit.cause
    if (
      Cause.isDieType(cause) &&
      Cause.isRuntimeException(cause.defect)
    ) {
      yield* Console.log(
        `RuntimeException defect caught: ${cause.defect.message}`
      )
    } else {
      yield* Console.log("Unknown failure caught.")
    }
  }
})

// We get an Exit.Success because we caught all failures
Effect.runPromiseExit(program).then(console.log)
/*
Output:
RuntimeException defect caught: Boom!
{
  _id: "Exit",
  _tag: "Success",
  value: undefined
}
*/

catchAllDefect

Recovers from all defects using a provided recovery function.

Effect.catchAllDefect allows you to handle defects, which are unexpected errors that usually cause the program to terminate. This function lets you recover from these defects by providing a function that handles the error.

However, it does not handle expected errors (like those from Effect.fail) or execution interruptions (like those from Effect.interrupt).

Example (Handling All Defects)

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

// Simulating a runtime error
const task = Effect.dieMessage("Boom!")

const program = Effect.catchAllDefect(task, (defect) => {
  if (Cause.isRuntimeException(defect)) {
    return Console.log(
      `RuntimeException defect caught: ${defect.message}`
    )
  }
  return Console.log("Unknown defect caught.")
})

// We get an Exit.Success because we caught all defects
Effect.runPromiseExit(program).then(console.log)
/*
Output:
RuntimeException defect caught: Boom!
{
  _id: "Exit",
  _tag: "Success",
  value: undefined
}
*/

When to Recover from Defects

Defects are unexpected errors that typically shouldn’t be recovered from, as they often indicate serious issues. However, in some cases, such as dynamically loaded plugins, controlled recovery might be needed.

Catching Some Defects

catchSomeDefect

Recovers from specific defects using a provided partial function.

Effect.catchSomeDefect allows you to handle specific defects, which are unexpected errors that can cause the program to stop. It uses a partial function to catch only certain defects and ignores others.

However, it does not handle expected errors (like those from Effect.fail) or execution interruptions (like those from Effect.interrupt).

The function provided to Effect.catchSomeDefect acts as a filter and a handler for defects:

• It receives the defect as an input.
• If the defect matches a specific condition (e.g., a certain error type), the function returns an Option.some containing the recovery logic.
• If the defect does not match, the function returns Option.none, allowing the defect to propagate.

Example (Handling Specific Defects)

import { Effect, Cause, Option, Console } from "effect"

// Simulating a runtime error
const task = Effect.dieMessage("Boom!")

const program = Effect.catchSomeDefect(task, (defect) => {
  if (Cause.isIllegalArgumentException(defect)) {
    return Option.some(
      Console.log(
        `Caught an IllegalArgumentException defect: ${defect.message}`
      )
    )
  }
  return Option.none()
})

// Since we are only catching IllegalArgumentException
// we will get an Exit.Failure because we simulated a runtime error.
Effect.runPromiseExit(program).then(console.log)
/*
Output:
{
  _id: 'Exit',
  _tag: 'Failure',
  cause: {
    _id: 'Cause',
    _tag: 'Die',
    defect: { _tag: 'RuntimeException' }
  }
}
*/

When to Recover from Defects

Defects are unexpected errors that typically shouldn’t be recovered from, as they often indicate serious issues. However, in some cases, such as dynamically loaded plugins, controlled recovery might be needed.