使用生成器

Effect 提供了一种便捷的语法，类似于 async/await，用于使用生成器编写有效果的代码。

可选特性

在 Effect 中使用生成器是一个可选特性。如果您对生成器不熟悉或偏好不同的编码风格，可以 探索 Effect 中关于构建管道的文档。

理解 Effect.gen

Effect.gen 工具通过利用 JavaScript 的生成器函数简化了编写有效果代码的任务。这种方法帮助您的代码看起来和表现得更像传统的同步代码，从而增强了可读性和错误管理。

示例（执行带折扣的交易）

让我们探索一个实用的程序，它执行应用程序逻辑中常见的一系列数据转换：

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.gen(function* () {
  // 获取交易金额
  const transactionAmount = yield* fetchTransactionAmount

  // 获取折扣率
  const discountRate = yield* fetchDiscountRate

  // 计算折扣后金额
  const discountedAmount = yield* applyDiscount(
    transactionAmount,
    discountRate
  )

  // 应用服务费
  const finalAmount = addServiceCharge(discountedAmount)

  // 返回应用费用后的总金额
  return `Final amount to charge: ${finalAmount}`
})

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

使用 Effect.gen 时要遵循的关键步骤：

• 将您的逻辑包装在 Effect.gen 中
• 使用 yield* 处理效果
• 返回最终结果

必需的 TypeScript 配置

生成器 API 仅在使用 downlevelIteration 标志或在 tsconfig.json 文件中 将 target 设置为 "es2015" 或更高版本时可用。

比较 Effect.gen 与 async/await

如果您熟悉 async/await，您可能会注意到编写代码的流程是相似的。

让我们比较这两种方法：

Using Effect.gen

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))

export const program = Effect.gen(function* () {
  const transactionAmount = yield* fetchTransactionAmount
  const discountRate = yield* fetchDiscountRate
  const discountedAmount = yield* applyDiscount(
    transactionAmount,
    discountRate
  )
  const finalAmount = addServiceCharge(discountedAmount)
  return `Final amount to charge: ${finalAmount}`
})

Using Async / Await

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

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

const fetchTransactionAmount = Promise.resolve(100)

const fetchDiscountRate = Promise.resolve(5)

export const program = async function () {
  const transactionAmount = await fetchTransactionAmount
  const discountRate = await fetchDiscountRate
  const discountedAmount = await applyDiscount(
    transactionAmount,
    discountRate
  )
  const finalAmount = addServiceCharge(discountedAmount)
  return `Final amount to charge: ${finalAmount}`
}

需要注意的是，尽管代码看起来相似，但这两个程序并不相同。并排比较它们的目的只是为了突出它们在编写方式上的相似性。

拥抱控制流

使用 Effect.gen 结合生成器的一个重要优势是它能够在生成器函数内使用标准的控制流结构。这些结构包括 if/else、for、while 和其他分支和循环机制，增强了您在代码中表达复杂控制流逻辑的能力。

示例（使用控制流）

import { Effect } from "effect"

const calculateTax = (
  amount: number,
  taxRate: number
): Effect.Effect<number, Error> =>
  taxRate > 0
    ? Effect.succeed((amount * taxRate) / 100)
    : Effect.fail(new Error("Invalid tax rate"))

const program = Effect.gen(function* () {
  let i = 1

  while (true) {
    if (i === 10) {
      break // 当计数器达到 10 时跳出循环
    } else {
      if (i % 2 === 0) {
        // 为偶数计算税费
        console.log(yield* calculateTax(100, i))
      }
      i++
      continue
    }
  }
})

Effect.runPromise(program)
/*
Output:
2
4
6
8
*/

How to Raise Errors

The Effect.gen API lets you integrate error handling directly into your workflow by yielding failed effects. You can introduce errors with Effect.fail, as shown in the example below.

Example (Introducing an Error into the Flow)

import { Effect, Console } from "effect"

const task1 = Console.log("task1...")
const task2 = Console.log("task2...")

const program = Effect.gen(function* () {
  // Perform some tasks
  yield* task1
  yield* task2
  // Introduce an error
  yield* Effect.fail("Something went wrong!")
})

Effect.runPromise(program).then(console.log, console.error)
/*
Output:
task1...
task2...
(FiberFailure) Error: Something went wrong!
*/

The Role of Short-Circuiting

When working with Effect.gen, it is important to understand how it handles errors. This API will stop execution at the first error it encounters and return that error.

How does this affect your code? If you have several operations in sequence, once any one of them fails, the remaining operations will not run, and the error will be returned.

In simpler terms, if something fails at any point, the program will stop right there and deliver the error to you.

Example (Halting Execution at the First Error)

import { Effect, Console } from "effect"

const task1 = Console.log("task1...")
const task2 = Console.log("task2...")
const failure = Effect.fail("Something went wrong!")
const task4 = Console.log("task4...")

const program = Effect.gen(function* () {
  yield* task1
  yield* task2
  // The program stops here due to the error
  yield* failure
  // The following lines never run
  yield* task4
  return "some result"
})

Effect.runPromise(program).then(console.log, console.error)
/*
Output:
task1...
task2...
(FiberFailure) Error: Something went wrong!
*/

Even though execution never reaches code after a failure, TypeScript may still assume that the code below the error is reachable unless you explicitly return after the failure.

For example, consider the following scenario where you want to narrow the type of a variable:

Example (Type Narrowing without Explicit Return)

import { Effect } from "effect"

type User = {
  readonly name: string
}

// Imagine this function checks a database or an external service
declare function getUserById(id: string): Effect.Effect<User | undefined>

function greetUser(id: string) {
  return Effect.gen(function* () {
    const user = yield* getUserById(id)

    if (user === undefined) {
      // Even though we fail here, TypeScript still thinks
      // 'user' might be undefined later
      yield* Effect.fail(`User with id ${id} not found`)
    }

    return `Hello, ${user.name}!`
Error ts(18048)  ― 'user' is possibly 'undefined'.
  })
}

In this example, TypeScript still considers user possibly undefined because there is no explicit return after the failure.

To fix this, explicitly return right after calling Effect.fail:

Example (Type Narrowing with Explicit Return)

import { Effect } from "effect"

type User = {
  readonly name: string
}

declare function getUserById(id: string): Effect.Effect<User | undefined>

function greetUser(id: string) {
  return Effect.gen(function* () {
    const user = yield* getUserById(id)

    if (user === undefined) {
      // Explicitly return after failing
      return yield* Effect.fail(`User with id ${id} not found`)
    }

    // Now TypeScript knows that 'user' is not undefined
    return `Hello, ${user.name}!`
  })
}

Further Learning

To learn more about error handling in Effect, refer to the Error Management section.

Passing this

In some cases, you might need to pass a reference to the current object (this) into the body of your generator function. You can achieve this by utilizing an overload that accepts the reference as the first argument:

Example (Passing this to Generator)

import { Effect } from "effect"

class MyClass {
  readonly local = 1
  compute = Effect.gen(this, function* () {
    const n = this.local + 1

    yield* Effect.log(`Computed value: ${n}`)

    return n
  })
}

Effect.runPromise(new MyClass().compute).then(console.log)
/*
Output:
timestamp=... level=INFO fiber=#0 message="Computed value: 2"
2
*/

Adapter Deprecated

You may still come across some code snippets that use an adapter, typically indicated by _ or $ symbols.

In earlier versions of TypeScript, the generator “adapter” function was necessary to ensure correct type inference within generators. This adapter was used to facilitate the interaction between TypeScript’s type system and generator functions.

Example (Adapter in Older Code)

import { Effect } from "effect"

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

// Older usage with an adapter for proper type inference
const programWithAdapter = Effect.gen(function* ($) {
  const transactionAmount = yield* $(fetchTransactionAmount)
})

// Current usage without an adapter
const program = Effect.gen(function* () {
  const transactionAmount = yield* fetchTransactionAmount
})

With advances in TypeScript (v5.5+), the adapter is no longer necessary for type inference. While it remains in the codebase for backward compatibility, it is anticipated to be removed in the upcoming major release of Effect.