创建 Effect

Effect 提供了不同的方式来创建 effect，它们是封装副作用的计算单元。 在本指南中，我们将介绍一些您可以用来创建 effect 的常见方法。

为什么不抛出错误？

在传统编程中，当发生错误时，通常通过抛出异常来处理：

// 类型签名不显示可能的异常
const divide = (a: number, b: number): number => {
  if (b === 0) {
    throw new Error("Cannot divide by zero")
  }
  return a / b
}

然而，抛出错误可能会有问题。函数的类型签名不会指示它们可能抛出异常，这使得推理潜在错误变得困难。

为了解决这个问题，Effect 引入了专用的构造函数来创建表示成功和失败的 effect：Effect.succeed 和 Effect.fail。这些构造函数允许您显式处理成功和失败情况，同时利用类型系统来跟踪错误。

succeed

创建一个总是成功并返回给定值的 Effect。

当您需要一个成功完成并返回特定值的 effect 时使用此函数， 无需任何错误或外部依赖。

示例（创建成功的 Effect）

import { Effect } from "effect"

//      ┌─── Effect<number, never, never>
//      ▼
const success = Effect.succeed(42)

success 的类型是 Effect<number, never, never>，这意味着：

• 它产生一个 number 类型的值。
• 它不产生任何错误（never 表示没有错误）。
• 它不需要任何额外的数据或依赖（never 表示没有需求）。

         ┌─── 产生 number 类型的值
         │       ┌─── 不产生任何错误
         │       │      ┌─── 不需要依赖
         ▼       ▼      ▼
Effect<number, never, never>

fail

创建一个表示可以恢复的错误的 Effect。

使用此函数在 Effect 中显式发出错误信号。错误 将继续传播，除非被处理。您可以使用 Effect.catchAll 或 Effect.catchTag 等函数来处理错误。

示例（创建失败的 Effect）

import { Effect } from "effect"

//      ┌─── Effect<never, Error, never>
//      ▼
const failure = Effect.fail(
  new Error("Operation failed due to network error")
)

failure 的类型是 Effect<never, Error, never>，这意味着：

• 它永远不会产生值（never 表示不会产生成功结果）。
• 它失败并产生错误，特别是 Error。
• 它不需要任何额外的数据或依赖（never 表示没有需求）。

         ┌─── 永远不产生值
         │      ┌─── 失败并产生 Error
         │      │      ┌─── 不需要依赖
         ▼      ▼      ▼
Effect<never, Error, never>

虽然您可以在 Effect.fail 中使用 Error 对象，但您也可以根据错误管理策略传递字符串、数字或更复杂的对象。

使用”标记”错误（具有 _tag 字段的对象）可以帮助识别错误类型，并与标准 Effect 函数（如 Effect.catchTag）配合良好。

示例（使用标记错误）

import { Effect, Data } from "effect"

class HttpError extends Data.TaggedError("HttpError")<{}> {}

//      ┌─── Effect<never, HttpError, never>
//      ▼
const program = Effect.fail(new HttpError())

错误跟踪

使用 Effect.succeed 和 Effect.fail，您可以显式处理成功和失败情况，类型系统将确保错误被跟踪和考虑。

示例（重写除法函数）

以下是如何使用 Effect 重写 divide 函数，使错误处理变得显式。

import { Effect } from "effect"

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

在此示例中，divide 函数在其返回类型 Effect<number, Error> 中指示操作可以成功返回 number 或失败返回 Error。

         ┌─── 产生 number 类型的值
         │       ┌─── 失败并产生 Error
         ▼       ▼
Effect<number, Error>

这个清晰的类型签名有助于确保错误得到正确处理，并且调用函数的任何人都知道可能的结果。

示例（模拟用户检索操作）

让我们想象另一个场景，我们使用 Effect.succeed 和 Effect.fail 来建模一个简单的用户检索操作，其中用户数据是硬编码的，这在测试场景或模拟数据时可能很有用：

import { Effect } from "effect"

// 定义 User 类型
interface User {
  readonly id: number
  readonly name: string
}

// 模拟从数据库获取用户的函数
const getUser = (userId: number): Effect.Effect<User, Error> => {
  // 通常，您会在这里访问数据库或 API，但我们将模拟它
  const userDatabase: Record<number, User> = {
    1: { id: 1, name: "John Doe" },
    2: { id: 2, name: "Jane Smith" }
  }

  // 检查用户是否存在于我们的"数据库"中并适当返回
  const user = userDatabase[userId]
  if (user) {
    return Effect.succeed(user)
  } else {
    return Effect.fail(new Error("User not found"))
  }
}

// 执行时，这将成功返回 id 为 1 的用户
const exampleUserEffect = getUser(1)

在此示例中，exampleUserEffect 的类型为 Effect<User, Error>，将根据用户是否存在于模拟数据库中产生 User 对象或 Error。

要深入了解应用程序中的错误管理，请参阅错误管理指南。

建模同步 Effect

在 JavaScript 中，您可以使用”thunk”来延迟同步计算的执行。

Thunk

“thunk” 是一个不接受参数并可能返回某个值的函数。

Thunk 对于延迟值的计算直到需要时才执行很有用。

为了建模同步副作用，Effect 提供了 Effect.sync 和 Effect.try 构造函数，它们接受一个 thunk。

sync

创建一个表示同步副作用计算的 Effect。

当您确定操作不会失败时使用 Effect.sync。

提供的函数（thunk）不得抛出错误；如果抛出，错误将被视为”缺陷”。

这种缺陷不是标准错误，而是表示预期无错误的逻辑中的缺陷。 您可以将其视为程序中的意外崩溃，可以使用 Effect.catchAllDefect 等工具进一步管理或记录。 此功能确保应用程序中的意外失败不会丢失，并且可以得到适当处理。

示例（记录消息）

在下面的示例中，Effect.sync 用于延迟写入控制台的副作用。

import { Effect } from "effect"

const log = (message: string) =>
  Effect.sync(() => {
    console.log(message) // 副作用
  })

//      ┌─── Effect<void, never, never>
//      ▼
const program = log("Hello, World!")

封装在 program 中的副作用（记录到控制台）直到 effect 被显式运行才会发生（有关更多详细信息，请参阅运行 Effect 部分）。这允许您在代码的一个点定义副作用，并控制何时激活它们，从而提高大型应用程序中副作用的可管理性和可预测性。

try

创建一个表示可能失败的同步计算的 Effect。

在需要执行可能失败的同步操作（如解析 JSON）的情况下，您可以使用 Effect.try 构造函数。 此构造函数旨在通过捕获可能抛出异常的操作并将其转换为可管理的错误来处理这些操作。

示例（安全的 JSON 解析）

假设您有一个尝试解析 JSON 字符串的函数。如果输入字符串格式不正确，此操作可能失败并抛出错误：

import { Effect } from "effect"

const parse = (input: string) =>
  // 如果输入不是有效的 JSON，这可能会抛出错误
  Effect.try(() => JSON.parse(input))

//      ┌─── Effect<any, UnknownException, never>
//      ▼
const program = parse("")

在此示例中：

• parse 是一个创建封装 JSON 解析操作的 effect 的函数。
• 如果 JSON.parse(input) 由于无效输入而抛出错误，Effect.try 会捕获此错误，program 表示的 effect 将失败并产生 UnknownException。这确保错误不会被静默忽略，而是在 effect 的结构化流程中处理。

自定义错误处理

您可能希望将捕获的异常转换为更具体的错误，或在捕获错误时执行其他操作。Effect.try 支持一个重载，允许您指定如何转换捕获的异常：

示例（自定义错误处理）

import { Effect } from "effect"

const parse = (input: string) =>
  Effect.try({
    // JSON.parse 可能因错误输入而抛出异常
    try: () => JSON.parse(input),
    // 重新映射错误
    catch: (unknown) => new Error(`something went wrong ${unknown}`)
  })

//      ┌─── Effect<any, Error, never>
//      ▼
const program = parse("")

您可以将此视为与 JavaScript 中传统 try-catch 块类似的模式：

try {
  return JSON.parse(input)
} catch (unknown) {
  throw new Error(`something went wrong ${unknown}`)
}

建模异步 Effect

在传统编程中，我们经常使用 Promise 来处理异步计算。然而，在 promise 中处理错误可能会有问题。默认情况下，Promise<Value> 只为解析值提供类型 Value，这意味着错误不会反映在类型系统中。这限制了表达能力，并使有效处理和跟踪错误变得困难。

为了克服这些限制，Effect 引入了专用的构造函数来创建在异步上下文中表示成功和失败的 effect：Effect.promise 和 Effect.tryPromise。这些构造函数允许您显式处理成功和失败情况，同时利用类型系统来跟踪错误。

promise

创建一个表示保证成功的异步计算的 Effect。

当您确定操作不会被拒绝时使用 Effect.promise。

提供的函数（thunk）返回一个永远不应该被拒绝的 Promise；如果被拒绝，错误将被视为”缺陷”。

这种缺陷不是标准错误，而是表示预期无错误的逻辑中的缺陷。 您可以将其视为程序中的意外崩溃，可以使用 Effect.catchAllDefect 等工具进一步管理或记录。 此功能确保应用程序中的意外失败不会丢失，并且可以得到适当处理。

示例（延迟消息）

import { Effect } from "effect"

const delay = (message: string) =>
  Effect.promise<string>(
    () =>
      new Promise((resolve) => {
        setTimeout(() => {
          resolve(message)
        }, 2000)
      })
  )

//      ┌─── Effect<string, never, never>
//      ▼
const program = delay("Async operation completed successfully!")

program 值的类型为 Effect<string, never, never>，可以解释为一个 effect：

• 成功返回 string 类型的值
• 不产生任何预期错误（never）
• 不需要任何上下文（never）

tryPromise

创建一个表示可能失败的异步计算的 Effect。

与 Effect.promise 不同，当底层 Promise 可能被拒绝时，此构造函数是合适的。 它提供了一种捕获错误并适当处理它们的方法。 默认情况下，如果发生错误，它将被捕获并作为 UnknownException 传播到错误通道。

示例（获取 TODO 项目）

import { Effect } from "effect"

const getTodo = (id: number) =>
  // 将捕获任何错误并将其作为 UnknownException 传播
  Effect.tryPromise(() =>
    fetch(`https://jsonplaceholder.typicode.com/todos/${id}`)
  )

//      ┌─── Effect<Response, UnknownException, never>
//      ▼
const program = getTodo(1)

program 值的类型为 Effect<Response, UnknownException, never>，可以解释为一个 effect：

• 成功返回 Response 类型的值
• 可能产生错误（UnknownException）
• 不需要任何上下文（never）

自定义错误处理

如果您想更好地控制传播到错误通道的内容，可以使用接受重新映射函数的 Effect.tryPromise 重载：

示例（自定义错误处理）

import { Effect } from "effect"

const getTodo = (id: number) =>
  Effect.tryPromise({
    try: () => fetch(`https://jsonplaceholder.typicode.com/todos/${id}`),
    // 重新映射错误
    catch: (unknown) => new Error(`something went wrong ${unknown}`)
  })

//      ┌─── Effect<Response, Error, never>
//      ▼
const program = getTodo(1)

从回调创建

从基于回调的异步函数创建 Effect。

有时您必须使用不支持 async/await 或 Promise 而使用回调风格的 API。 为了处理基于回调的 API，Effect 提供了 Effect.async 构造函数。

示例（包装回调 API）

让我们将 Node.js 的 fs 模块中的 readFile 函数包装成基于 Effect 的 API（确保安装了 @types/node）：

import { Effect } from "effect"
import * as NodeFS from "node:fs"

const readFile = (filename: string) =>
  Effect.async<Buffer, Error>((resume) => {
    NodeFS.readFile(filename, (error, data) => {
      if (error) {
        // 如果发生错误，使用失败的 Effect 恢复
        resume(Effect.fail(error))
      } else {
        // 如果成功，使用成功的 Effect 恢复
        resume(Effect.succeed(data))
      }
    })
  })

//      ┌─── Effect<Buffer, Error, never>
//      ▼
const program = readFile("example.txt")

在上面的示例中，我们在调用 Effect.async 时手动注释类型：

Effect.async<Buffer, Error>((resume) => {
  // ...
})

因为 TypeScript 无法基于回调体内的返回值推断回调的类型参数。注释类型确保提供给 resume 的值与预期类型匹配。

Effect.async 内的 resume 函数应该被调用恰好一次。多次调用将导致额外的调用被忽略。

示例（忽略后续的 resume 调用）

import { Effect } from "effect"

const program = Effect.async<number>((resume) => {
  resume(Effect.succeed(1))
  resume(Effect.succeed(2)) // 这一行将被忽略
})

// 运行程序
Effect.runPromise(program).then(console.log) // 输出：1

高级用法

对于更高级的用例，resume 可以选择性地返回一个 Effect，如果运行此 effect 的纤程被中断，该 Effect 将被执行。这在需要处理操作被中断时的资源清理的场景中很有用。

示例（使用清理处理中断）

在此示例中：

• writeFileWithCleanup 函数将数据写入文件。
• 如果运行此 effect 的纤程被中断，清理 effect（删除文件）将被执行。
• 这确保在操作被取消时，像打开的文件句柄这样的资源得到正确清理。

import { Effect, Fiber } from "effect"
import * as NodeFS from "node:fs"

// 模拟写入文件的长时间运行操作
const writeFileWithCleanup = (filename: string, data: string) =>
  Effect.async<void, Error>((resume) => {
    const writeStream = NodeFS.createWriteStream(filename)

    // 开始将数据写入文件
    writeStream.write(data)

    // 当流完成时，使用成功恢复
    writeStream.on("finish", () => resume(Effect.void))

    // 如果写入过程中发生错误，使用失败恢复
    writeStream.on("error", (err) => resume(Effect.fail(err)))

    // 通过返回清理 effect 处理中断
    return Effect.sync(() => {
      console.log(`Cleaning up ${filename}`)
      NodeFS.unlinkSync(filename)
    })
  })

const program = Effect.gen(function* () {
  const fiber = yield* Effect.fork(
    writeFileWithCleanup("example.txt", "Some long data...")
  )
  // 模拟在 1 秒后中断纤程
  yield* Effect.sleep("1 second")
  yield* Fiber.interrupt(fiber) // 这将触发清理
})

// 运行程序
Effect.runPromise(program)
/*
输出：
Cleaning up example.txt
*/

如果您包装的操作支持中断，resume 函数可以接收 AbortSignal 来直接处理中断请求。

示例（使用 AbortSignal 处理中断）

import { Effect, Fiber } from "effect"

// 支持使用 AbortSignal 中断的任务
const interruptibleTask = Effect.async<void, Error>((resume, signal) => {
  // 处理中断
  signal.addEventListener("abort", () => {
    console.log("Abort signal received")
    clearTimeout(timeoutId)
  })

  // 模拟长时间运行的任务
  const timeoutId = setTimeout(() => {
    console.log("Operation completed")
    resume(Effect.void)
  }, 2000)
})

const program = Effect.gen(function* () {
  const fiber = yield* Effect.fork(interruptibleTask)
  // 模拟在 1 秒后中断纤程
  yield* Effect.sleep("1 second")
  yield* Fiber.interrupt(fiber)
})

// 运行程序
Effect.runPromise(program)
/*
输出：
Abort signal received
*/

悬挂 Effect

Effect.suspend 用于延迟 effect 的创建。 它允许您延迟 effect 的评估，直到实际需要时才执行。 Effect.suspend 函数接受一个表示 effect 的 thunk，并将其包装在悬挂的 effect 中。

语法

const suspendedEffect = Effect.suspend(() => effect)

让我们探索一些 Effect.suspend 证明有用的常见场景。

惰性求值

当您想要延迟 effect 的评估直到需要时。这对于优化 effect 的执行很有用，特别是当它们并不总是需要或计算成本很高时。

此外，当创建具有副作用或作用域捕获的 effect 时，使用 Effect.suspend 在每次调用时重新执行。

示例（具有副作用的惰性求值）

import { Effect } from "effect"

let i = 0

const bad = Effect.succeed(i++)

const good = Effect.suspend(() => Effect.succeed(i++))

console.log(Effect.runSync(bad)) // 输出：0
console.log(Effect.runSync(bad)) // 输出：0

console.log(Effect.runSync(good)) // 输出：1
console.log(Effect.runSync(good)) // 输出：2

运行 Effect

此示例使用 Effect.runSync 来执行 effect 并显示其结果（有关更多详细信息，请参阅运行 Effect）。

在此示例中，bad 是调用 Effect.succeed(i++) 一次的结果，它递增作用域变量但返回其原始值。Effect.runSync(bad) 不会导致任何新的计算，因为 Effect.succeed(i++) 已经被调用过了。另一方面，每次调用 Effect.runSync(good) 时，传递给 Effect.suspend() 的 thunk 都会被执行，输出作用域变量的最新值。

处理循环依赖

Effect.suspend 在管理 effect 之间的循环依赖时很有帮助，其中一个 effect 依赖于另一个，反之亦然。 例如，在递归函数中使用 Effect.suspend 来避免急切调用是相当常见的。

示例（递归斐波那契）

import { Effect } from "effect"

const blowsUp = (n: number): Effect.Effect<number> =>
  n < 2
    ? Effect.succeed(1)
    : Effect.zipWith(blowsUp(n - 1), blowsUp(n - 2), (a, b) => a + b)

// console.log(Effect.runSync(blowsUp(32)))
// 崩溃：JavaScript 堆内存不足

const allGood = (n: number): Effect.Effect<number> =>
  n < 2
    ? Effect.succeed(1)
    : Effect.zipWith(
        Effect.suspend(() => allGood(n - 1)),
        Effect.suspend(() => allGood(n - 2)),
        (a, b) => a + b
      )

console.log(Effect.runSync(allGood(32))) // 输出：3524578

运行 Effect

此示例使用 Effect.zipWith 来组合两个 effect 的结果（有关更多详细信息，请参阅组合文档）。

blowsUp 函数创建递归斐波那契序列而不延迟执行。每次调用 blowsUp 都会触发进一步的立即递归调用，迅速增加 JavaScript 调用栈大小。

相反，allGood 通过使用 Effect.suspend 延迟递归调用来避免栈溢出。这种机制不会立即执行递归 effect，而是安排它们稍后运行，从而保持调用栈浅层并防止崩溃。

统一返回类型

在 TypeScript 难以统一返回的 effect 类型的情况下，可以使用 Effect.suspend 来解决这个问题。

示例（使用 Effect.suspend 帮助 TypeScript 推断类型）

import { Effect } from "effect"

/*
  没有 suspend，TypeScript 可能在类型推断上有困难。

  推断类型：
    (a: number, b: number) =>
      Effect<never, Error, never> | Effect<number, never, never>
*/
const withoutSuspend = (a: number, b: number) =>
  b === 0
    ? Effect.fail(new Error("Cannot divide by zero"))
    : Effect.succeed(a / b)

/*
  使用 suspend 来统一返回类型。

  推断类型：
    (a: number, b: number) => Effect<number, Error, never>
*/
const withSuspend = (a: number, b: number) =>
  Effect.suspend(() =>
    b === 0
      ? Effect.fail(new Error("Cannot divide by zero"))
      : Effect.succeed(a / b)
  )

备忘单

该表提供了可用构造函数的摘要，以及它们的输入和输出类型，允许您根据需要选择适当的函数。

API	给定	结果
succeed	A	Effect<A>
fail	E	Effect<never, E>
sync	() => A	Effect<A>
try	() => A	Effect<A, UnknownException>
try（重载）	() => A, unknown => E	Effect<A, E>
promise	() => Promise<A>	Effect<A>
tryPromise	() => Promise<A>	Effect<A, UnknownException>
tryPromise（重载）	() => Promise<A>, unknown => E	Effect<A, E>
async	(Effect<A, E> => void) => void	Effect<A, E>
suspend	() => Effect<A, E, R>	Effect<A, E, R>

有关构造函数的完整列表，请访问 Effect 构造函数文档。