构建管道

Effect 管道允许对值进行操作的组合和排序，以简洁和模块化的方式实现数据的转换和操作。

为什么管道有利于构建应用程序

管道是构建应用程序和以简洁模块化方式处理数据转换的绝佳方法。它们提供了几个好处：

1. 可读性：管道允许您以可读和顺序的方式组合函数。您可以清楚地看到数据流和应用于数据的操作，使代码更容易理解和维护。

2. 代码组织：使用管道，您可以将复杂操作分解为更小、可管理的函数。每个函数执行特定任务，使您的代码更加模块化，更容易推理。

3. 可重用性：管道促进函数的重用。通过将操作分解为更小的函数，您可以在不同的管道或上下文中重用它们，提高代码重用性并减少重复。

4. 类型安全：通过利用类型系统，管道有助于在编译时捕获错误。管道中的函数具有明确定义的输入和输出类型，确保数据正确流经管道并最小化运行时错误。

函数 vs 方法

在 Effect 生态系统库中使用函数对于实现树摇优化和确保可扩展性非常重要。 函数通过消除未使用的代码实现高效打包，并提供灵活和模块化的方法来扩展库的功能。

树摇优化

树摇优化是指构建系统在打包过程中消除未使用代码的能力。函数是可树摇的，而方法则不是。

当在 Effect 生态系统中使用函数时，只有实际导入和在应用程序中使用的函数才会包含在最终打包的代码中。未使用的函数会自动移除，从而减小包大小并提高性能。

另一方面，方法附加到对象或原型上，它们不能轻易地被树摇。即使您只使用方法的子集，与对象或原型关联的所有方法都会包含在包中，导致不必要的代码膨胀。

可扩展性

在 Effect 生态系统中使用函数的另一个重要优势是易于扩展。使用方法时，扩展现有 API 的功能通常需要修改对象的原型，这可能很复杂且容易出错。

相比之下，使用函数扩展功能要简单得多。您可以将自己的”扩展方法”定义为普通函数，而无需修改对象的原型。这促进了更清洁和更模块化的代码，也允许与其他库和模块更好的兼容性。

pipe

pipe 函数是一个实用工具，允许我们以可读和顺序的方式组合函数。它将一个函数的输出作为管道中下一个函数的输入。这使我们能够通过链接多个函数来构建复杂的转换。

语法

import { pipe } from "effect"

const result = pipe(input, func1, func2, ..., funcN)

在这个语法中，input 是初始值，func1、func2、…、funcN 是要按顺序应用的函数。每个函数的结果成为下一个函数的输入，最终返回最终结果。

以下是 pipe 工作原理的图解：

┌───────┐    ┌───────┐    ┌───────┐    ┌───────┐    ┌───────┐    ┌────────┐
│ input │───►│ func1 │───►│ func2 │───►│  ...  │───►│ funcN │───►│ result │
└───────┘    └───────┘    └───────┘    └───────┘    └───────┘    └────────┘

需要注意的是，传递给 pipe 的函数必须有单个参数，因为它们只会用单个参数调用。

让我们看一个例子来更好地理解 pipe 的工作原理：

示例（链接算术操作）

import { pipe } from "effect"

// 定义简单的算术操作
const increment = (x: number) => x + 1
const double = (x: number) => x * 2
const subtractTen = (x: number) => x - 10

// 使用 `pipe` 顺序应用这些操作
const result = pipe(5, increment, double, subtractTen)

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

在上面的例子中，我们从输入值 5 开始。increment 函数将初始值加 1，结果为 6。然后，double 函数将值翻倍，得到 12。最后，subtractTen 函数从 12 中减去 10，最终输出为 2。

结果等同于 subtractTen(double(increment(5)))，但使用 pipe 使代码更具可读性，因为操作是从左到右排序的，而不是从内到外嵌套。

map

通过对 effect 内部的值应用函数来转换它。

语法

const mappedEffect = pipe(myEffect, Effect.map(transformation))
// 或
const mappedEffect = Effect.map(myEffect, transformation)
// 或
const mappedEffect = myEffect.pipe(Effect.map(transformation))

Effect.map 接受一个函数并将其应用于 effect 中包含的值，创建一个具有转换值的新 effect。

Effect 是不可变的

需要注意的是，effect 是不可变的，这意味着原始 effect 不会被修改。相反，会返回一个具有更新值的新 effect。

示例（添加服务费）

这是一个实际例子，我们对交易金额应用服务费：

import { pipe, Effect } from "effect"

// 为交易金额添加小额服务费的函数
const addServiceCharge = (amount: number) => amount + 1

// 模拟从数据库获取交易金额的异步任务
const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

// 对交易金额应用服务费
const finalAmount = pipe(
  fetchTransactionAmount,
  Effect.map(addServiceCharge)
)

Effect.runPromise(finalAmount).then(console.log) // 输出：101

as

用常量值替换 effect 内部的值。

Effect.as 允许您忽略 effect 内部的原始值并用新的常量值替换它。

Effect 是不可变的

需要注意的是，effect 是不可变的，这意味着原始 effect 不会被修改。相反，会返回一个具有更新值的新 effect。

示例（替换值）

import { pipe, Effect } from "effect"

// 将值 5 替换为常量 "new value"
const program = pipe(Effect.succeed(5), Effect.as("new value"))

Effect.runPromise(program).then(console.log) // 输出："new value"

flatMap

链接 effect 以产生新的 Effect 实例，对于组合依赖于先前结果的操作很有用。

语法

const flatMappedEffect = pipe(myEffect, Effect.flatMap(transformation))
// 或
const flatMappedEffect = Effect.flatMap(myEffect, transformation)
// 或
const flatMappedEffect = myEffect.pipe(Effect.flatMap(transformation))

在上面的代码中，transformation 是接受一个值并返回 Effect 的函数，myEffect 是被转换的初始 Effect。

当您需要链接多个 effect 时使用 Effect.flatMap，确保每个步骤产生新的 Effect，同时扁平化可能发生的任何嵌套 effect。

它类似于数组使用的 flatMap，但专门与 Effect 实例一起工作，允许您避免深度嵌套的 effect 结构。

Effect 是不可变的

需要注意的是，effect 是不可变的，这意味着原始 effect 不会被修改。相反，会返回一个具有更新值的新 effect。

示例（应用折扣）

import { pipe, Effect } from "effect"

// 安全地对交易金额应用折扣的函数
const applyDiscount = (
  total: number,
  discountRate: number
): Effect.Effect<number, Error> =>
  discountRate === 0
    ? Effect.fail(new Error("Discount rate cannot be zero"))
    : Effect.succeed(total - (total * discountRate) / 100)

// 模拟从数据库获取交易金额的异步任务
const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

// 使用 `flatMap` 链接获取和折扣应用
const finalAmount = pipe(
  fetchTransactionAmount,
  Effect.flatMap((amount) => applyDiscount(amount, 5))
)

Effect.runPromise(finalAmount).then(console.log)
// 输出：95

确保所有 Effect 都被考虑

确保 Effect.flatMap 中的所有 effect 都对最终计算有贡献。如果您忽略一个 effect，可能会导致意外行为：

Effect.flatMap((amount) => {
  // 这个 effect 将被忽略
  Effect.sync(() => console.log(`Apply a discount to: ${amount}`))
  return applyDiscount(amount, 5)
})

在这种情况下，Effect.sync 调用被忽略，不会影响 applyDiscount(amount, 5) 的结果。要正确处理 effect，请确保使用 Effect.map、Effect.flatMap、Effect.andThen 或 Effect.tap 等函数显式链接它们。

andThen

链接两个动作，其中第二个动作可以依赖于第一个动作的结果。

语法

const transformedEffect = pipe(myEffect, Effect.andThen(anotherEffect))
// 或
const transformedEffect = Effect.andThen(myEffect, anotherEffect)
// 或
const transformedEffect = myEffect.pipe(Effect.andThen(anotherEffect))

当您需要按顺序运行多个动作，第二个动作依赖于第一个动作的结果时，使用 andThen。这对于组合 effect 或处理必须按顺序发生的计算很有用。

第二个动作可以是：

1. 一个值（类似于 Effect.as）
2. 返回值的函数（类似于 Effect.map）
3. 一个 Promise
4. 返回 Promise 的函数
5. 一个 Effect
6. 返回 Effect 的函数（类似于 Effect.flatMap）

示例（基于获取金额应用折扣）

让我们看一个比较 Effect.andThen 与 Effect.map 和 Effect.flatMap 的例子：

import { pipe, Effect } from "effect"

// 安全地对交易金额应用折扣的函数
const applyDiscount = (
  total: number,
  discountRate: number
): Effect.Effect<number, Error> =>
  discountRate === 0
    ? Effect.fail(new Error("Discount rate cannot be zero"))
    : Effect.succeed(total - (total * discountRate) / 100)

// 模拟从数据库获取交易金额的异步任务
const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

// 使用 Effect.map 和 Effect.flatMap
const result1 = pipe(
  fetchTransactionAmount,
  Effect.map((amount) => amount * 2),
  Effect.flatMap((amount) => applyDiscount(amount, 5))
)

Effect.runPromise(result1).then(console.log) // 输出：190

// 使用 Effect.andThen
const result2 = pipe(
  fetchTransactionAmount,
  Effect.andThen((amount) => amount * 2),
  Effect.andThen((amount) => applyDiscount(amount, 5))
)

Effect.runPromise(result2).then(console.log) // 输出：190

Option 和 Either 与 andThen

Option 和 Either 都常用于处理可选值或缺失值或简单错误情况。这些类型与 Effect.andThen 很好地集成。当与 Effect.andThen 一起使用时，操作被归类为场景 5 和 6（如前所述），因为在这种情况下 Option 和 Either 都被视为 effect。

示例（使用 Option）

import { pipe, Effect, Option } from "effect"

// 模拟从数据库获取数字的异步任务
const fetchNumberValue = Effect.tryPromise(() => Promise.resolve(42))

//      ┌─── Effect<number, UnknownException | NoSuchElementException, never>
//      ▼
const program = pipe(
  fetchNumberValue,
  Effect.andThen((x) => (x > 0 ? Option.some(x) : Option.none()))
)

您可能期望 program 的类型是 Effect<Option<number>, UnknownException, never>，但实际上是 Effect<number, UnknownException | NoSuchElementException, never>。

这是因为 Option<A> 被视为类型为 Effect<A, NoSuchElementException> 的 effect，因此可能的错误被合并为联合类型。

Option 作为 Effect

类型为 Option<A> 的值被解释为类型为 Effect<A, NoSuchElementException> 的 effect。

示例（使用 Either）

import { pipe, Effect, Either } from "effect"

// 从字符串解析整数的函数，可能失败
const parseInteger = (input: string): Either.Either<number, string> =>
  isNaN(parseInt(input))
    ? Either.left("Invalid integer")
    : Either.right(parseInt(input))

// 模拟从数据库获取字符串的异步任务
const fetchStringValue = Effect.tryPromise(() => Promise.resolve("42"))

//      ┌─── Effect<number, string | UnknownException, never>
//      ▼
const program = pipe(
  fetchStringValue,
  Effect.andThen((str) => parseInteger(str))
)

虽然人们可能期望 program 的类型是 Effect<Either<number, string>, UnknownException, never>，但实际上是 Effect<number, string | UnknownException, never>。

这是因为 Either<A, E> 被视为类型为 Effect<A, E> 的 effect，这意味着错误被合并为联合类型。

Either 作为 Effect

类型为 Either<A, E> 的值被解释为类型为 Effect<A, E> 的 effect。

tap

使用 effect 的结果运行副作用，而不改变原始值。

当您想要执行副作用（如日志记录或跟踪）而不修改主值时，使用 Effect.tap。当您需要观察或记录动作但希望原始值传递到下一步时，这很有用。

Effect.tap 的工作方式类似于 Effect.flatMap，但它忽略传递给它的函数的结果。来自前一个 effect 的值仍然可用于链的下一部分。请注意，如果副作用失败，整个链也会失败。

示例（在管道中记录步骤）

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

// 安全地对交易金额应用折扣的函数
const applyDiscount = (
  total: number,
  discountRate: number
): Effect.Effect<number, Error> =>
  discountRate === 0
    ? Effect.fail(new Error("Discount rate cannot be zero"))
    : Effect.succeed(total - (total * discountRate) / 100)

// 模拟从数据库获取交易金额的异步任务
const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

const finalAmount = pipe(
  fetchTransactionAmount,
  // 记录获取的交易金额
  Effect.tap((amount) => Console.log(`Apply a discount to: ${amount}`)),
  // `amount` 仍然可用！
  Effect.flatMap((amount) => applyDiscount(amount, 5))
)

Effect.runPromise(finalAmount).then(console.log)
/*
输出：
Apply a discount to: 100
95
*/

在这个例子中，Effect.tap 用于在应用折扣之前记录交易金额，而不修改值本身。原始值（amount）仍然可用于下一个操作（applyDiscount）。

使用 Effect.tap 允许我们在计算过程中执行副作用而不改变结果。这对于日志记录、执行额外动作或观察中间值而不干扰主计算流程很有用。

all

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

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

例如，如果输入是元组：

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

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

默认情况下，Effect.all 顺序运行 effect 并产生包含结果的元组或对象。如果任何 effect 失败，它会停止执行（短路）并传播错误。

有关如何使用 Effect.all 的更多信息，请参阅收集。

示例（组合配置和数据库检查）

import { Effect } from "effect"

// 模拟从文件读取配置的函数
const webConfig = Effect.promise(() =>
  Promise.resolve({ dbConnection: "localhost", port: 8080 })
)

// 模拟测试数据库连接的函数
const checkDatabaseConnectivity = Effect.promise(() =>
  Promise.resolve("Connected to Database")
)

// 组合两个 effect 以执行启动检查
const startupChecks = Effect.all([webConfig, checkDatabaseConnectivity])

Effect.runPromise(startupChecks).then(([config, dbStatus]) => {
  console.log(
    `Configuration: ${JSON.stringify(config)}\nDB Status: ${dbStatus}`
  )
})
/*
输出：
Configuration: {"dbConnection":"localhost","port":8080}
DB Status: Connected to Database
*/

构建您的第一个管道

现在让我们结合 pipe 函数、Effect.all 和 Effect.andThen 来创建一个执行一系列转换的管道。

示例（构建交易管道）

import { Effect, pipe } from "effect"

// 为交易金额添加小额服务费的函数
const addServiceCharge = (amount: number) => amount + 1

// 安全地对交易金额应用折扣的函数
const applyDiscount = (
  total: number,
  discountRate: number
): Effect.Effect<number, Error> =>
  discountRate === 0
    ? Effect.fail(new Error("Discount rate cannot be zero"))
    : Effect.succeed(total - (total * discountRate) / 100)

// 模拟从数据库获取交易金额的异步任务
const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

// 模拟从配置文件获取折扣率的异步任务
const fetchDiscountRate = Effect.promise(() => Promise.resolve(5))

// 使用 effect 管道组装程序
const program = pipe(
  // 组合两个获取 effect 以获得交易金额和折扣率
  Effect.all([fetchTransactionAmount, fetchDiscountRate]),

  // 对交易金额应用折扣
  Effect.andThen(([transactionAmount, discountRate]) =>
    applyDiscount(transactionAmount, discountRate)
  ),

  // 向折扣金额添加服务费
  Effect.andThen(addServiceCharge),

  // 格式化最终结果以供显示
  Effect.andThen(
    (finalAmount) => `Final amount to charge: ${finalAmount}`
  )
)

// 执行程序并记录结果
Effect.runPromise(program).then(console.log)
// 输出："Final amount to charge: 96"

这个管道演示了如何通过将不同的 effect 组合成清晰、可读的流程来构建代码。

pipe 方法

Effect 提供了一个 pipe 方法，其工作方式类似于 rxjs 中的 pipe 方法。这个方法允许您将多个操作链接在一起，使您的代码更简洁和可读。

语法

const result = effect.pipe(func1, func2, ..., funcN)

这等同于使用 pipe 函数：

const result = pipe(effect, func1, func2, ..., funcN)

pipe 方法在所有 effect 和许多其他数据类型上都可用，无需导入 pipe 函数，为您节省一些按键。

示例（使用 pipe 方法）

让我们重写一个之前的例子，这次使用 pipe 方法。

import { Effect } from "effect"

const addServiceCharge = (amount: number) => amount + 1

const applyDiscount = (
  total: number,
  discountRate: number
): Effect.Effect<number, Error> =>
  discountRate === 0
    ? Effect.fail(new Error("Discount rate cannot be zero"))
    : Effect.succeed(total - (total * discountRate) / 100)

const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

const fetchDiscountRate = Effect.promise(() => Promise.resolve(5))

const program = Effect.all([
  fetchTransactionAmount,
  fetchDiscountRate
]).pipe(
  Effect.andThen(([transactionAmount, discountRate]) =>
    applyDiscount(transactionAmount, discountRate)
  ),
  Effect.andThen(addServiceCharge),
  Effect.andThen(
    (finalAmount) => `Final amount to charge: ${finalAmount}`
  )
)

备忘单

让我们总结一下到目前为止看到的转换函数：

API	输入	输出
map	Effect<A, E, R>, A => B	Effect<B, E, R>
flatMap	Effect<A, E, R>, A => Effect<B, E, R>	Effect<B, E, R>
andThen	Effect<A, E, R>, *	Effect<B, E, R>
tap	Effect<A, E, R>, A => Effect<B, E, R>	Effect<A, E, R>
all	[Effect<A, E, R>, Effect<B, E, R>, ...]	Effect<[A, B, ...], E, R>