控制流操作符

尽管 JavaScript 提供了内置的控制流结构，但 Effect 提供了在 Effect 应用程序中有用的额外控制流函数。在本节中，我们将介绍控制执行流程的不同方法。

if 表达式

在处理 Effect 值时，我们可以使用标准的 JavaScript if-then-else 语句：

示例（为无效重量返回 None）

这里我们使用 Option 数据类型来表示有效值的缺失。

import { Effect, Option } from "effect"

// 验证重量并返回 Option 的函数
const validateWeightOption = (
  weight: number
): Effect.Effect<Option.Option<number>> => {
  if (weight >= 0) {
    // 如果重量有效则返回 Some
    return Effect.succeed(Option.some(weight))
  } else {
    // 如果重量无效则返回 None
    return Effect.succeed(Option.none())
  }
}

示例（为无效重量返回错误）

您也可以通过使用错误通道来处理无效输入，这允许您在输入无效时返回错误：

import { Effect } from "effect"

// 验证重量或失败并返回错误的函数
const validateWeightOrFail = (
  weight: number
): Effect.Effect<number, string> => {
  if (weight >= 0) {
    // 如果有效则返回重量
    return Effect.succeed(weight)
  } else {
    // 如果无效则失败并返回错误
    return Effect.fail(`negative input: ${weight}`)
  }
}

条件操作符

if

基于由有效谓词评估的条件执行两个 effect 中的一个。

使用 Effect.if 根据谓词 effect 是否评估为 true 或 false 来运行两个 effect 中的一个。如果谓词为 true，则执行 onTrue effect。如果为 false，则执行 onFalse effect。

示例（模拟抛硬币）

在这个例子中，我们使用 Random.nextBoolean 生成随机布尔值来模拟虚拟抛硬币。如果值为 true，onTrue effect 记录”Head”。如果值为 false，onFalse effect 记录”Tail”。

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

const flipTheCoin = Effect.if(Random.nextBoolean, {
  onTrue: () => Console.log("Head"), // 如果谓词为 true 则运行
  onFalse: () => Console.log("Tail") // 如果谓词为 false 则运行
})

Effect.runFork(flipTheCoin)

when

基于布尔条件有条件地执行 effect。

Effect.when 允许您有条件地执行 effect，类似于使用 if (condition) 表达式，但具有处理 effect 的额外好处。如果条件为 true，则执行 effect；否则，什么也不做。

effect 的结果被包装在 Option<A> 中以指示是否执行了 effect。如果条件为 true，effect 的结果被包装在 Some 中。如果条件为 false，结果为 None，表示 effect 被跳过。

示例（条件 Effect 执行）

import { Effect, Option } from "effect"

const validateWeightOption = (
  weight: number
): Effect.Effect<Option.Option<number>> =>
  // 如果重量非负则有条件地执行 effect
  Effect.succeed(weight).pipe(Effect.when(() => weight >= 0))

// 使用有效重量运行
Effect.runPromise(validateWeightOption(100)).then(console.log)
/*
输出：
{
  _id: "Option",
  _tag: "Some",
  value: 100
}
*/

// 使用无效重量运行
Effect.runPromise(validateWeightOption(-5)).then(console.log)
/*
输出：
{
  _id: "Option",
  _tag: "None"
}
*/

在这个例子中，Option 数据类型用于表示有效值的存在或缺失。如果条件评估为 true（在这种情况下，如果重量非负），则执行 effect 并包装在 Some 中。否则，结果为 None。

whenEffect

基于另一个 effect 的结果有条件地执行 effect。

当确定是否执行 effect 的条件取决于产生布尔值的另一个 effect 的结果时，使用 Effect.whenEffect。如果条件 effect 评估为 true，则执行指定的 effect。如果评估为 false，则不执行任何 effect。

effect 的结果被包装在 Option<A> 中以指示是否执行了 effect。如果条件为 true，effect 的结果被包装在 Some 中。如果条件为 false，结果为 None，表示 effect 被跳过。

示例（使用 Effect 作为条件）

以下函数创建一个随机整数，但仅当随机生成的布尔值为 true 时。

import { Effect, Random } from "effect"

const randomIntOption = Random.nextInt.pipe(
  Effect.whenEffect(Random.nextBoolean)
)

console.log(Effect.runSync(randomIntOption))
/*
示例输出：
{ _id: 'Option', _tag: 'Some', value: 8609104974198840 }
*/

unless / unlessEffect

Effect.unless 和 Effect.unlessEffect 函数类似于 when* 函数，但它们等同于 if (!condition) expression 构造。

压缩

zip

将两个 effect 组合为单个 effect，产生包含两个 effect 结果的元组。

Effect.zip 函数执行第一个 effect（左侧），然后执行第二个 effect（右侧）。一旦两个 effect 都成功，它们的结果就会组合成一个元组。

示例（顺序组合两个 Effect）

import { Effect } from "effect"

const task1 = Effect.succeed(1).pipe(
  Effect.delay("200 millis"),
  Effect.tap(Effect.log("task1 done"))
)

const task2 = Effect.succeed("hello").pipe(
  Effect.delay("100 millis"),
  Effect.tap(Effect.log("task2 done"))
)

// 将两个 effect 组合在一起
//
//      ┌─── Effect<[number, string], never, never>
//      ▼
const program = Effect.zip(task1, task2)

Effect.runPromise(program).then(console.log)
/*
输出：
timestamp=... level=INFO fiber=#0 message="task1 done"
timestamp=... level=INFO fiber=#0 message="task2 done"
[ 1, 'hello' ]
*/

默认情况下，effect 按顺序运行。要并发运行它们，请使用 { concurrent: true } 选项。

示例（并发组合两个 Effect）

import { Effect } from "effect"

const task1 = Effect.succeed(1).pipe(
  Effect.delay("200 millis"),
  Effect.tap(Effect.log("task1 done"))
)

const task2 = Effect.succeed("hello").pipe(
  Effect.delay("100 millis"),
  Effect.tap(Effect.log("task2 done"))
)

// 使用并发选项并发运行两个 effect
const program = Effect.zip(task1, task2, { concurrent: true })

Effect.runPromise(program).then(console.log)
/*
输出：
timestamp=... level=INFO fiber=#3 message="task2 done"
timestamp=... level=INFO fiber=#2 message="task1 done"
[ 1, 'hello' ]
*/

在这个并发版本中，两个 effect 并行运行。task2 首先完成，但两个任务都可以在完成后立即记录和处理。

zipWith

顺序组合两个 effect 并对它们的结果应用函数以产生单个值。

Effect.zipWith 函数类似于 Effect.zip，但不是返回结果元组，而是对两个 effect 的结果应用提供的函数，将它们组合为单个值。

默认情况下，effect 按顺序运行。要并发运行它们，请使用 { concurrent: true } 选项。

示例（使用自定义函数组合 Effect）

import { Effect } from "effect"

const task1 = Effect.succeed(1).pipe(
  Effect.delay("200 millis"),
  Effect.tap(Effect.log("task1 done"))
)
const task2 = Effect.succeed("hello").pipe(
  Effect.delay("100 millis"),
  Effect.tap(Effect.log("task2 done"))
)

//      ┌─── Effect<number, never, never>
//      ▼
const task3 = Effect.zipWith(
  task1,
  task2,
  // 将结果组合为单个值
  (number, string) => number + string.length
)

Effect.runPromise(task3).then(console.log)
/*
输出：
timestamp=... level=INFO fiber=#3 message="task1 done"
timestamp=... level=INFO fiber=#2 message="task2 done"
6
*/

循环

loop

Effect.loop 函数允许您使用 step 函数重复更新状态，直到 while 函数定义的条件变为 false。它将中间状态收集在数组中并将它们作为最终结果返回。

语法

Effect.loop(initial, {
  while: (state) => boolean,
  step: (state) => state,
  body: (state) => Effect
})

这个函数类似于 JavaScript 中的 while 循环，但增加了有效计算：

let state = initial
const result = []

while (options.while(state)) {
  result.push(options.body(state)) // 执行有效操作
  state = options.step(state) // 更新状态
}

return result

示例（收集结果的循环）

import { Effect } from "effect"

// 运行 5 次的循环，收集每次迭代的结果
const result = Effect.loop(
  // 初始状态
  1,
  {
    // 继续循环的条件
    while: (state) => state <= 5,
    // 状态更新函数
    step: (state) => state + 1,
    // 每次迭代要执行的 effect
    body: (state) => Effect.succeed(state)
  }
)

Effect.runPromise(result).then(console.log)
// 输出：[1, 2, 3, 4, 5]

在这个例子中，循环从状态 1 开始，继续直到状态超过 5。每个状态递增 1 并收集到数组中，成为最终结果。

丢弃中间结果

discard 选项设置为 true 时，将丢弃每个有效操作的结果，返回 void 而不是数组。

示例（丢弃结果的循环）

import { Effect, Console } from "effect"

const result = Effect.loop(
  // 初始状态
  1,
  {
    // 继续循环的条件
    while: (state) => state <= 5,
    // 状态更新函数
    step: (state) => state + 1,
    // 每次迭代要执行的 effect
    body: (state) => Console.log(`Currently at state ${state}`),
    // 丢弃中间结果
    discard: true
  }
)

Effect.runPromise(result).then(console.log)
/*
输出：
Currently at state 1
Currently at state 2
Currently at state 3
Currently at state 4
Currently at state 5
undefined
*/

在这个例子中，循环在每次迭代时执行记录当前索引的副作用，但它丢弃所有中间结果。最终结果是 undefined。

iterate

Effect.iterate 函数让您通过有效操作重复更新状态。它运行 body effect 在每次迭代中更新状态，并在 while 条件评估为 true 时继续。

语法

Effect.iterate(initial, {
  while: (result) => boolean,
  body: (result) => Effect
})

这个函数类似于 JavaScript 中的 while 循环，但增加了有效计算：

let result = initial

while (options.while(result)) {
  result = options.body(result)
}

return result

示例（有效迭代）

import { Effect } from "effect"

const result = Effect.iterate(
  // 初始结果
  1,
  {
    // 继续迭代的条件
    while: (result) => result <= 5,
    // 改变结果的操作
    body: (result) => Effect.succeed(result + 1)
  }
)

Effect.runPromise(result).then(console.log)
// 输出：6

forEach

对 Iterable 中的每个元素执行有效操作。

Effect.forEach 函数对可迭代对象中的每个元素应用提供的操作，产生返回结果数组的新 effect。如果任何 effect 失败，迭代立即停止（短路），错误被传播。

concurrency 选项控制并发执行多少操作。默认情况下，操作按顺序执行。

示例（对可迭代元素应用 Effect）

import { Effect, Console } from "effect"

const result = Effect.forEach([1, 2, 3, 4, 5], (n, index) =>
  Console.log(`Currently at index ${index}`).pipe(Effect.as(n * 2))
)

Effect.runPromise(result).then(console.log)
/*
输出：
Currently at index 0
Currently at index 1
Currently at index 2
Currently at index 3
Currently at index 4
[ 2, 4, 6, 8, 10 ]
*/

在这个例子中，我们遍历数组 [1, 2, 3, 4, 5]，应用记录当前索引的 effect。Effect.as(n * 2) 操作转换每个值，结果为数组 [2, 4, 6, 8, 10]。最终输出是收集所有转换值的结果。

丢弃结果

discard 选项设置为 true 时，将丢弃每个有效操作的结果，返回 void 而不是数组。

示例（使用 discard 忽略结果）

import { Effect, Console } from "effect"

// 应用 effect 但丢弃结果
const result = Effect.forEach(
  [1, 2, 3, 4, 5],
  (n, index) =>
    Console.log(`Currently at index ${index}`).pipe(Effect.as(n * 2)),
  { discard: true }
)

Effect.runPromise(result).then(console.log)
/*
输出：
Currently at index 0
Currently at index 1
Currently at index 2
Currently at index 3
Currently at index 4
undefined
*/

在这种情况下，effect 仍然为每个元素运行，但结果被丢弃，所以最终输出是 undefined。

收集

all

将多个 effect 组合为一个，根据输入结构返回结果。

当您需要运行多个 effect 并将它们的结果组合为单个输出时，使用 Effect.all。它支持元组、可迭代对象、结构和记录，使其对不同的输入类型具有灵活性。

如果任何 effect 失败，它会停止执行（短路）并传播错误。要改变这种行为，您可以使用 mode 选项，它允许所有 effect 运行并将结果收集为 Either 或 Option。

您可以使用并发选项控制执行顺序（例如，顺序与并发）。

例如，如果输入是元组：

//         ┌─── effect 的元组
//         ▼
Effect.all([effect1, effect2, ...])

effect 按顺序执行，结果是包含结果作为元组的新 effect。元组中的结果与传递给 Effect.all 的 effect 的顺序匹配。

让我们探索不同类型结构的示例：元组、可迭代对象、对象和记录。

示例（在元组中组合 Effect）

import { Effect, Console } from "effect"

const tupleOfEffects = [
  Effect.succeed(42).pipe(Effect.tap(Console.log)),
  Effect.succeed("Hello").pipe(Effect.tap(Console.log))
] as const

//      ┌─── Effect<[number, string], never, never>
//      ▼
const resultsAsTuple = Effect.all(tupleOfEffects)

Effect.runPromise(resultsAsTuple).then(console.log)
/*
输出：
42
Hello
[ 42, 'Hello' ]
*/

示例（在可迭代对象中组合 Effect）

import { Effect, Console } from "effect"

const iterableOfEffects: Iterable<Effect.Effect<number>> = [1, 2, 3].map(
  (n) => Effect.succeed(n).pipe(Effect.tap(Console.log))
)

//      ┌─── Effect<number[], never, never>
//      ▼
const resultsAsArray = Effect.all(iterableOfEffects)

Effect.runPromise(resultsAsArray).then(console.log)
/*
输出：
1
2
3
[ 1, 2, 3 ]
*/

示例（在结构中组合 Effect）

import { Effect, Console } from "effect"

const structOfEffects = {
  a: Effect.succeed(42).pipe(Effect.tap(Console.log)),
  b: Effect.succeed("Hello").pipe(Effect.tap(Console.log))
}

//      ┌─── Effect<{ a: number; b: string; }, never, never>
//      ▼
const resultsAsStruct = Effect.all(structOfEffects)

Effect.runPromise(resultsAsStruct).then(console.log)
/*
输出：
42
Hello
{ a: 42, b: 'Hello' }
*/

示例（在记录中组合 Effect）

import { Effect, Console } from "effect"

const recordOfEffects: Record<string, Effect.Effect<number>> = {
  key1: Effect.succeed(1).pipe(Effect.tap(Console.log)),
  key2: Effect.succeed(2).pipe(Effect.tap(Console.log))
}

//      ┌─── Effect<{ [x: string]: number; }, never, never>
//      ▼
const resultsAsRecord = Effect.all(recordOfEffects)

Effect.runPromise(resultsAsRecord).then(console.log)
/*
输出：
1
2
{ key1: 1, key2: 2 }
*/

短路行为

Effect.all 函数在遇到第一个错误时停止执行，这称为”短路”。如果集合中的任何 effect 失败，剩余的 effect 将不会运行，错误将被传播。

示例（在第一次失败时退出）

import { Effect, Console } from "effect"

const program = Effect.all([
  Effect.succeed("Task1").pipe(Effect.tap(Console.log)),
  Effect.fail("Task2: Oh no!").pipe(Effect.tap(Console.log)),
  // 由于之前的失败不会执行
  Effect.succeed("Task3").pipe(Effect.tap(Console.log))
])

Effect.runPromiseExit(program).then(console.log)
/*
输出：
Task1
{
  _id: 'Exit',
  _tag: 'Failure',
  cause: { _id: 'Cause', _tag: 'Fail', failure: 'Task2: Oh no!' }
}
*/

您可以通过使用 mode 选项来覆盖此行为。

mode 选项

{ mode: "either" } 选项改变 Effect.all 的行为，确保所有 effect 都运行，即使有些失败。这种模式不是在第一次失败时停止，而是收集成功和失败，返回 Either 实例数组，其中每个结果要么是 Right（成功）要么是 Left（失败）。

示例（使用 mode: "either" 收集结果）

import { Effect, Console } from "effect"

const effects = [
  Effect.succeed("Task1").pipe(Effect.tap(Console.log)),
  Effect.fail("Task2: Oh no!").pipe(Effect.tap(Console.log)),
  Effect.succeed("Task3").pipe(Effect.tap(Console.log))
]

const program = Effect.all(effects, { mode: "either" })

Effect.runPromiseExit(program).then(console.log)
/*
输出：
Task1
Task3
{
  _id: 'Exit',
  _tag: 'Success',
  value: [
    { _id: 'Either', _tag: 'Right', right: 'Task1' },
    { _id: 'Either', _tag: 'Left', left: 'Task2: Oh no!' },
    { _id: 'Either', _tag: 'Right', right: 'Task3' }
  ]
}
*/

类似地，{ mode: "validate" } 选项使用 Option 来指示成功或失败。每个 effect 成功时返回 None，失败时返回包含错误的 Some。

示例（使用 mode: "validate" 收集结果）

import { Effect, Console } from "effect"

const effects = [
  Effect.succeed("Task1").pipe(Effect.tap(Console.log)),
  Effect.fail("Task2: Oh no!").pipe(Effect.tap(Console.log)),
  Effect.succeed("Task3").pipe(Effect.tap(Console.log))
]

const program = Effect.all(effects, { mode: "validate" })

Effect.runPromiseExit(program).then((result) => console.log("%o", result))
/*
输出：
Task1
Task3
{
  _id: 'Exit',
  _tag: 'Failure',
  cause: {
    _id: 'Cause',
    _tag: 'Fail',
    failure: [
      { _id: 'Option', _tag: 'None' },
      { _id: 'Option', _tag: 'Some', value: 'Task2: Oh no!' },
      { _id: 'Option', _tag: 'None' }
    ]
  }
}
*/