运行 Effect

要执行 effect，您可以使用 Effect 模块提供的众多 run 函数之一。

在程序边缘运行 Effect

推荐的方法是设计您的程序，使其大部分逻辑都是 Effect。建议在程序的”边缘”附近使用 run* 函数。这种方法允许在执行程序和构建复杂 effect 时具有更大的灵活性。

runSync

同步执行 effect，立即运行并返回结果。

示例（同步日志记录）

import { Effect } from "effect"

const program = Effect.sync(() => {
  console.log("Hello, World!")
  return 1
})

const result = Effect.runSync(program)
// 输出：Hello, World!

console.log(result)
// 输出：1

使用 Effect.runSync 运行不会失败且不包含任何异步操作的 effect。如果 effect 失败或涉及异步工作，它将抛出错误，执行将在失败或异步操作发生的地方停止。

示例（失败或异步 Effect 的错误用法）

import { Effect } from "effect"

try {
  // 尝试运行失败的 effect
  Effect.runSync(Effect.fail("my error"))
} catch (e) {
  console.error(e)
}
/*
输出：
(FiberFailure) Error: my error
*/

try {
  // 尝试运行涉及异步工作的 effect
  Effect.runSync(Effect.promise(() => Promise.resolve(1)))
} catch (e) {
  console.error(e)
}
/*
输出：
(FiberFailure) AsyncFiberException: Fiber #0 cannot be resolved synchronously. This is caused by using runSync on an effect that performs async work
*/

runSyncExit

同步运行 effect 并将结果作为 Exit 类型返回，该类型表示 effect 的结果（成功或失败）。

使用 Effect.runSyncExit 来了解 effect 是否成功或失败， 包括任何缺陷，而无需处理异步操作。

Exit 类型表示 effect 的结果：

• 如果 effect 成功，结果被包装在 Success 中。
• 如果失败，失败信息作为包含 Cause 类型的 Failure 提供。

示例（将结果作为 Exit 处理）

import { Effect } from "effect"

console.log(Effect.runSyncExit(Effect.succeed(1)))
/*
输出：
{
  _id: "Exit",
  _tag: "Success",
  value: 1
}
*/

console.log(Effect.runSyncExit(Effect.fail("my error")))
/*
输出：
{
  _id: "Exit",
  _tag: "Failure",
  cause: {
    _id: "Cause",
    _tag: "Fail",
    failure: "my error"
  }
}
*/

如果 effect 包含异步操作，Effect.runSyncExit 将 返回带有 Die 原因的 Failure，表示 effect 无法 同步解析。

示例（导致 Die 的异步操作）

import { Effect } from "effect"

console.log(Effect.runSyncExit(Effect.promise(() => Promise.resolve(1))))
/*
输出：
{
  _id: 'Exit',
  _tag: 'Failure',
  cause: {
    _id: 'Cause',
    _tag: 'Die',
    defect: [Fiber #0 cannot be resolved synchronously. This is caused by using runSync on an effect that performs async work] {
      fiber: [FiberRuntime],
      _tag: 'AsyncFiberException',
      name: 'AsyncFiberException'
    }
  }
}
*/

runPromise

执行 effect 并将结果作为 Promise 返回。

当您需要执行 effect 并使用 Promise 语法处理结果时， 通常为了与其他基于 promise 的代码兼容，请使用 Effect.runPromise。

示例（将成功的 Effect 作为 Promise 运行）

import { Effect } from "effect"

Effect.runPromise(Effect.succeed(1)).then(console.log)
// 输出：1

如果 effect 成功，promise 将解析为结果。如果 effect 失败，promise 将拒绝并返回错误。

示例（将失败的 Effect 处理为被拒绝的 Promise）

import { Effect } from "effect"

Effect.runPromise(Effect.fail("my error")).catch(console.error)
/*
输出：
(FiberFailure) Error: my error
*/

runPromiseExit

运行 effect 并返回一个解析为 Exit 的 Promise， 它表示 effect 的结果（成功或失败）。

当您需要确定 effect 是否成功或失败（包括任何缺陷） 并且您想要使用 Promise 时，请使用 Effect.runPromiseExit。

Exit 类型表示 effect 的结果：

• 如果 effect 成功，结果被包装在 Success 中。
• 如果失败，失败信息作为包含 Cause 类型的 Failure 提供。

示例（将结果作为 Exit 处理）

import { Effect } from "effect"

Effect.runPromiseExit(Effect.succeed(1)).then(console.log)
/*
输出：
{
  _id: "Exit",
  _tag: "Success",
  value: 1
}
*/

Effect.runPromiseExit(Effect.fail("my error")).then(console.log)
/*
输出：
{
  _id: "Exit",
  _tag: "Failure",
  cause: {
    _id: "Cause",
    _tag: "Fail",
    failure: "my error"
  }
}
*/

runFork

运行 effect 的基础函数，返回一个可以被观察或中断的”fiber”。

Effect.runFork 用于通过创建 fiber 在后台运行 effect。它是 所有其他运行函数的基础函数。它启动一个可以被观察或中断的 fiber。

Effect 执行的默认选择

除非您特别需要 Promise 或同步操作， 否则 Effect.runFork 是一个很好的默认选择。

示例（在后台运行 Effect）

import { Effect, Console, Schedule, Fiber } from "effect"

//      ┌─── Effect<number, never, never>
//      ▼
const program = Effect.repeat(
  Console.log("running..."),
  Schedule.spaced("200 millis")
)

//      ┌─── RuntimeFiber<number, never>
//      ▼
const fiber = Effect.runFork(program)

setTimeout(() => {
  Effect.runFork(Fiber.interrupt(fiber))
}, 500)

In this example, the program continuously logs “running…” with each repetition spaced 200 milliseconds apart. You can learn more about repetitions and scheduling in our Introduction to Scheduling guide.

To stop the execution of the program, we use Fiber.interrupt on the fiber returned by Effect.runFork. This allows you to control the execution flow and terminate it when necessary.

For a deeper understanding of how fibers work and how to handle interruptions, check out our guides on Fibers and Interruptions.

Synchronous vs. Asynchronous Effects

在 Effect 库中，没有内置的方法来提前确定 effect 是否会同步或异步执行。虽然在 Effect 的早期版本中考虑过这个想法，但最终由于几个重要原因没有实现：

1. 复杂性： 在类型系统中引入跟踪同步/异步行为的功能会使 Effect 更复杂，并限制其可组合性。

2. 安全性考虑： 我们尝试了不同的方法来跟踪异步 Effect，但它们都导致了更糟糕的开发者体验，而没有显著提高安全性。即使使用完全同步的类型，我们也需要支持 fromCallback 组合器来处理使用延续传递风格 (CPS) 的 API。然而，在类型级别，无法保证这样的函数总是立即调用而不是延迟调用。

运行 Effect 的最佳实践

在大多数情况下，effect 在应用程序的最外层运行。通常，围绕 Effect 构建的应用程序将涉及对主 effect 的单次调用。以下是您应该如何处理 effect 执行：

• 使用 runPromise 或 runFork：对于大多数情况，异步执行应该是默认选择。这些方法提供了处理基于 Effect 的工作流的最佳方式。

• 仅在必要时使用 runSync：同步执行应该被视为边缘情况，仅在异步执行不可行的场景中使用。例如，当您确定 effect 是纯同步的并且需要立即结果时。

备忘单

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

API	给定	结果
runSync	Effect<A, E>	A
runSyncExit	Effect<A, E>	Exit<A, E>
runPromise	Effect<A, E>	Promise<A>
runPromiseExit	Effect<A, E>	Promise<Exit<A, E>>
runFork	Effect<A, E>	RuntimeFiber<A, E>

您可以在这里找到完整的 run* 函数列表。