Cause

Effect<A, E, R> 类型在错误类型 E 上是多态的，允许灵活处理任何所需的错误类型。然而，关于失败的信息往往比错误类型 E 单独能捕获的更多。

为了解决这个问题，Effect 使用 Cause<E> 数据类型来存储各种详细信息，例如：

• 意外错误或缺陷
• 堆栈和执行跟踪
• fiber 中断的原因

Effect 严格保留所有与失败相关的信息，在 Cause 类型中存储错误上下文的完整图片。这种全面的方法能够精确分析和处理失败，确保不会丢失任何数据。

虽然 Cause 值通常不会直接操作，但它们是 Effect 工作流中错误的基础，提供对并发和顺序错误详细信息的访问。这允许在需要时进行彻底的错误分析。

创建 Causes

您可以使用 Effect.failCause 有意创建具有特定原因的 effect。

示例（定义具有不同 Causes 的 Effects）

import { Effect, Cause } from "effect"

// 定义一个因意外错误而死亡的 effect
//
//      ┌─── Effect<never, never, never>
//      ▼
const die = Effect.failCause(Cause.die("Boom!"))

// 定义一个因预期错误而失败的 effect
//
//      ┌─── Effect<never, string, never>
//      ▼
const fail = Effect.failCause(Cause.fail("Oh no!"))

某些原因不会影响 effect 的错误类型，导致错误通道中出现 never：

                ┌─── 无错误信息
                ▼
Effect<never, never, never>

例如，Cause.die 不为 effect 指定错误类型，而 Cause.fail 会指定，相应地设置错误通道类型。

Cause 变体

有几种不同错误的原因，在本节中，我们将描述每种原因。

Empty

Empty 原因表示没有任何错误。

Fail

Fail<E> 原因表示由于类型为 E 的预期错误而导致的失败。

Die

Die 原因表示由缺陷导致的失败，这是一个意外或非预期的错误。

Interrupt

Interrupt 原因表示由于 Fiber 中断而导致的失败，并包含被中断 Fiber 的 FiberId。

Sequential

Sequential 原因组合了两个依次发生的原因。

例如，在 Effect.ensuring 操作中（类似于 try-finally），如果 try 和 finally 部分都失败，这两个错误会通过 Sequential 原因按顺序表示。

示例（使用 Sequential Cause 捕获顺序失败）

import { Effect, Cause } from "effect"

const program = Effect.failCause(Cause.fail("Oh no!")).pipe(
  Effect.ensuring(Effect.failCause(Cause.die("Boom!")))
)

Effect.runPromiseExit(program).then(console.log)
/*
输出:
{
  _id: 'Exit',
  _tag: 'Failure',
  cause: {
    _id: 'Cause',
    _tag: 'Sequential',
    left: { _id: 'Cause', _tag: 'Fail', failure: 'Oh no!' },
    right: { _id: 'Cause', _tag: 'Die', defect: 'Boom!' }
  }
}
*/

Parallel

Parallel 原因组合了两个并发发生的原因。

在 Effect 程序中，两个操作可能并行运行，可能导致多个失败。当两个计算同时失败时，Parallel 原因表示 effect 工作流中的并发错误。

示例（使用 Parallel Cause 捕获并发失败）

import { Effect, Cause } from "effect"

const program = Effect.all(
  [
    Effect.failCause(Cause.fail("Oh no!")),
    Effect.failCause(Cause.die("Boom!"))
  ],
  { concurrency: 2 }
)

Effect.runPromiseExit(program).then(console.log)
/*
输出:
{
  _id: 'Exit',
  _tag: 'Failure',
  cause: {
    _id: 'Cause',
    _tag: 'Parallel',
    left: { _id: 'Cause', _tag: 'Fail', failure: 'Oh no!' },
    right: { _id: 'Cause', _tag: 'Die', defect: 'Boom!' }
  }
}
*/

获取 Effect 的 Cause

要获取失败 effect 的原因，请使用 Effect.cause。这允许您检查或处理失败背后的确切原因。

示例（获取和检查失败原因）

import { Effect } from "effect"

const program = Effect.gen(function* () {
  const cause = yield* Effect.cause(Effect.fail("Oh no!"))
  console.log(cause)
})

Effect.runPromise(program)
/*
输出:
{ _id: 'Cause', _tag: 'Fail', failure: 'Oh no!' }
*/

守卫

要确定 Cause 的特定类型，请使用 Cause 模块中提供的守卫：

• Cause.isEmpty：检查原因是否为空，表示没有错误。
• Cause.isFailType：识别表示预期失败的原因。
• Cause.isDie：识别表示意外缺陷的原因。
• Cause.isInterruptType：识别与 fiber 中断相关的原因。
• Cause.isSequentialType：检查原因是否由顺序错误组成。
• Cause.isParallelType：检查原因是否包含并行错误。

示例（使用守卫识别 Cause 类型）

import { Cause } from "effect"

const cause = Cause.fail(new Error("my message"))

if (Cause.isFailType(cause)) {
  console.log(cause.error.message) // 输出: my message
}

这些守卫允许您准确识别 Cause 的类型，使在代码中处理各种错误情况变得更容易。无论是处理预期失败、意外缺陷、中断还是复合错误，这些守卫都提供了评估和管理错误场景的清晰方法。

模式匹配

Cause.match 函数提供了一种直接的方式来处理 Cause 的每种情况。通过为每种可能的原因类型定义回调，您可以用自定义行为响应特定的错误场景。

示例（对不同 Causes 进行模式匹配）

import { Cause } from "effect"

const cause = Cause.parallel(
  Cause.fail(new Error("my fail message")),
  Cause.die("my die message")
)

console.log(
  Cause.match(cause, {
    onEmpty: "(empty)",
    onFail: (error) => `(error: ${error.message})`,
    onDie: (defect) => `(defect: ${defect})`,
    onInterrupt: (fiberId) => `(fiberId: ${fiberId})`,
    onSequential: (left, right) =>
      `(onSequential (left: ${left}) (right: ${right}))`,
    onParallel: (left, right) =>
      `(onParallel (left: ${left}) (right: ${right})`
  })
)
/*
输出:
(onParallel (left: (error: my fail message)) (right: (defect: my die message))
*/

美化打印

清晰可读的错误消息是有效调试的关键。Cause.pretty 函数通过以结构化方式格式化错误消息来提供帮助，使理解失败详细信息变得更容易。

示例（使用 Cause.pretty 获得可读的错误消息）

import { Cause, FiberId } from "effect"

console.log(Cause.pretty(Cause.empty))
/*
输出:
All fibers interrupted without errors.
*/

console.log(Cause.pretty(Cause.fail(new Error("my fail message"))))
/*
输出:
Error: my fail message
    ...stack trace...
*/

console.log(Cause.pretty(Cause.die("my die message")))
/*
输出:
Error: my die message
*/

console.log(Cause.pretty(Cause.interrupt(FiberId.make(1, 0))))
/*
输出:
All fibers interrupted without errors.
*/

console.log(
  Cause.pretty(Cause.sequential(Cause.fail("fail1"), Cause.fail("fail2")))
)
/*
输出:
Error: fail1
Error: fail2
*/

获取失败和缺陷

要从 Cause 中专门收集失败或缺陷，您可以使用 Cause.failures 和 Cause.defects。这些函数允许您仅检查发生的错误或意外缺陷。

示例（从 Cause 中提取失败和缺陷）

import { Effect, Cause } from "effect"

const program = Effect.gen(function* () {
  const cause = yield* Effect.cause(
    Effect.all([
      Effect.fail("error 1"),
      Effect.die("defect"),
      Effect.fail("error 2")
    ])
  )
  console.log(Cause.failures(cause))
  console.log(Cause.defects(cause))
})

Effect.runPromise(program)
/*
输出:
{ _id: 'Chunk', values: [ 'error 1' ] }
{ _id: 'Chunk', values: [] }
*/