Using Generators

Effect offers a convenient syntax, similar to async/await, to write effectful code using generators.

Understanding Effect.gen

The Effect.gen utility simplifies the task of writing effectful code by utilizing JavaScript’s generator functions. This method helps your code appear and behave more like traditional synchronous code, which enhances both readability and error management.

Example (Performing Transactions with Discounts)

Let’s explore a practical program that performs a series of data transformations commonly found in application logic:

1
import { Effect } from "effect"
2

3
// Function to add a small service charge to a transaction amount
4
const addServiceCharge = (amount: number) => amount + 1
5

6
// Function to apply a discount safely to a transaction amount
7
const applyDiscount = (
8
  total: number,
9
  discountRate: number,
10
): Effect.Effect<number, Error> =>
11
  discountRate === 0
12
    ? Effect.fail(new Error("Discount rate cannot be zero"))
13
    : Effect.succeed(total - (total * discountRate) / 100)
14

15
// Simulated asynchronous task to fetch a transaction amount from a
16
// database
17
const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))
18

19
// Simulated asynchronous task to fetch a discount rate from a
20
// configuration file
21
const fetchDiscountRate = Effect.promise(() => Promise.resolve(5))
22

23
// Assembling the program using a generator function
24
const program = Effect.gen(function* () {
25
  // Retrieve the transaction amount
26
  const transactionAmount = yield* fetchTransactionAmount
27

28
  // Retrieve the discount rate
29
  const discountRate = yield* fetchDiscountRate
30

31
  // Calculate discounted amount
32
  const discountedAmount = yield* applyDiscount(transactionAmount, discountRate)
33

34
  // Apply service charge
35
  const finalAmount = addServiceCharge(discountedAmount)
36

37
  // Return the total amount after applying the charge
38
  return `Final amount to charge: ${finalAmount}`
39
})
40

41
// Execute the program and log the result
42
Effect.runPromise(program).then(console.log)
43
// Output: Final amount to charge: 96

Key steps to follow when using Effect.gen:

Wrap your logic in Effect.gen
Use yield* to handle effects
Return the final result

If any of the effects that you handle inside of the generator with yield* fail, then the generator will stop and exit with that failure.

Comparing Effect.gen with async/await

If you are familiar with async/await, you may notice that the flow of writing code is similar.

Let’s compare the two approaches:

1
import { 
import Effect
Effect } from "effect"
2

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

5
const 
const applyDiscount: (total: number, discountRate: number) => Effect.Effect<number, Error>
applyDiscount = (
6
  
total: number
total: number,
7
  
discountRate: number
discountRate: number,
8
): 
import Effect
Effect.
interface Effect<out A, out E = never, out R = never>
Effect<number, 
interface Error
Error> =>
9
  
discountRate: number
discountRate === 0
10
    ? 
import Effect
Effect.
const fail: <Error>(error: Error) => Effect.Effect<never, Error, never>
fail(new 
var Error: ErrorConstructor
new (message?: string, options?: ErrorOptions) => Error (+1 overload)
Error("Discount rate cannot be zero"))
11
    : 
import Effect
Effect.
const succeed: <number>(value: number) => Effect.Effect<number, never, never>
succeed(
total: number
total - (
total: number
total * 
discountRate: number
discountRate) / 100)
12

13
const 
const fetchTransactionAmount: Effect.Effect<number, never, never>
fetchTransactionAmount = 
import Effect
Effect.
const promise: <number>(evaluate: (signal: AbortSignal) => PromiseLike<number>) => Effect.Effect<number, never, never>
promise(() => 
var Promise: PromiseConstructor
Promise.
PromiseConstructor.resolve<number>(value: number): Promise<number> (+2 overloads)
resolve(100))
14

15
const 
const fetchDiscountRate: Effect.Effect<number, never, never>
fetchDiscountRate = 
import Effect
Effect.
const promise: <number>(evaluate: (signal: AbortSignal) => PromiseLike<number>) => Effect.Effect<number, never, never>
promise(() => 
var Promise: PromiseConstructor
Promise.
PromiseConstructor.resolve<number>(value: number): Promise<number> (+2 overloads)
resolve(5))
16

17
export const 
const program: Effect.Effect<string, Error, never>
program = 
import Effect
Effect.
const gen: <Effect.Effect<number, Error, never>, string>(f: () => Generator<Effect.Effect<number, Error, never>, string, never>) => Effect.Effect<string, Error, never> (+1 overload)
gen(function* () {
18
  const 
const transactionAmount: number
transactionAmount = yield* 
const fetchTransactionAmount: Effect.Effect<number, never, never>
fetchTransactionAmount
19
  const 
const discountRate: number
discountRate = yield* 
const fetchDiscountRate: Effect.Effect<number, never, never>
fetchDiscountRate
20
  const 
const discountedAmount: number
discountedAmount = yield* 
const applyDiscount: (total: number, discountRate: number) => Effect.Effect<number, Error>
applyDiscount(
const transactionAmount: number
transactionAmount, 
const discountRate: number
discountRate)
21
  const 
const finalAmount: number
finalAmount = 
const addServiceCharge: (amount: number) => number
addServiceCharge(
const discountedAmount: number
discountedAmount)
22
  return `Final amount to charge: ${
const finalAmount: number
finalAmount}`
23
})

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

3
const 
const applyDiscount: (total: number, discountRate: number) => Promise<number>
applyDiscount = (
total: number
total: number, 
discountRate: number
discountRate: number): 
interface Promise<T>
Promise<number> =>
4
  
discountRate: number
discountRate === 0
5
    ? 
var Promise: PromiseConstructor
Promise.
PromiseConstructor.reject<number>(reason?: any): Promise<number>
reject(new 
var Error: ErrorConstructor
new (message?: string, options?: ErrorOptions) => Error (+1 overload)
Error("Discount rate cannot be zero"))
6
    : 
var Promise: PromiseConstructor
Promise.
PromiseConstructor.resolve<number>(value: number): Promise<number> (+2 overloads)
resolve(
total: number
total - (
total: number
total * 
discountRate: number
discountRate) / 100)
7

8
const 
const fetchTransactionAmount: Promise<number>
fetchTransactionAmount = 
var Promise: PromiseConstructor
Promise.
PromiseConstructor.resolve<number>(value: number): Promise<number> (+2 overloads)
resolve(100)
9

10
const 
const fetchDiscountRate: Promise<number>
fetchDiscountRate = 
var Promise: PromiseConstructor
Promise.
PromiseConstructor.resolve<number>(value: number): Promise<number> (+2 overloads)
resolve(5)
11

12
export const 
const program: () => Promise<string>
program = async function () {
13
  const 
const transactionAmount: number
transactionAmount = await 
const fetchTransactionAmount: Promise<number>
fetchTransactionAmount
14
  const 
const discountRate: number
discountRate = await 
const fetchDiscountRate: Promise<number>
fetchDiscountRate
15
  const 
const discountedAmount: number
discountedAmount = await 
const applyDiscount: (total: number, discountRate: number) => Promise<number>
applyDiscount(
const transactionAmount: number
transactionAmount, 
const discountRate: number
discountRate)
16
  const 
const finalAmount: number
finalAmount = 
const addServiceCharge: (amount: number) => number
addServiceCharge(
const discountedAmount: number
discountedAmount)
17
  return `Final amount to charge: ${
const finalAmount: number
finalAmount}`
18
}

It’s important to note that although the code appears similar, the two programs are not identical. The purpose of comparing them side by side is just to highlight the resemblance in how they are written.

Embracing Control Flow

One significant advantage of using Effect.gen in conjunction with generators is its capability to employ standard control flow constructs within the generator function. These constructs include if/else, for, while, and other branching and looping mechanisms, enhancing your ability to express complex control flow logic in your code.

Example (Using Control Flow)

1
import { Effect } from "effect"
2

3
const calculateTax = (
4
  amount: number,
5
  taxRate: number,
6
): Effect.Effect<number, Error> =>
7
  taxRate > 0
8
    ? Effect.succeed((amount * taxRate) / 100)
9
    : Effect.fail(new Error("Invalid tax rate"))
10

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

14
  while (true) {
15
    if (i === 10) {
16
      break // Break the loop when counter reaches 10
17
    } else {
18
      if (i % 2 === 0) {
19
        // Calculate tax for even numbers
20
        console.log(yield* calculateTax(100, i))
21
      }
22
      i++
23
      continue
24
    }
25
  }
26
})
27

28
Effect.runPromise(program)
29
/*
30
Output:
31
2
32
4
33
6
34
8
35
*/

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)

1
import { Effect, Console } from "effect"
2

3
const task1 = Console.log("task1...")
4
const task2 = Console.log("task2...")
5

6
const program = Effect.gen(function* () {
7
  // Perform some tasks
8
  yield* task1
9
  yield* task2
10
  // Introduce an error
11
  yield* Effect.fail("Something went wrong!")
12
})
13

14
Effect.runPromise(program).then(console.log, console.error)
15
/*
16
Output:
17
task1...
18
task2...
19
(FiberFailure) Error: Something went wrong!
20
*/

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.

If you don’t want to stop on an error, you can use the Effect.either method to encapsulate the error in the Either data type: see the examples of managing expected errors.

Example (Halting Execution at the First Error)

1
import { Effect, Console } from "effect"
2

3
const task1 = Console.log("task1...")
4
const task2 = Console.log("task2...")
5
const failure = Effect.fail("Something went wrong!")
6
const task4 = Console.log("task4...")
7

8
const program = Effect.gen(function* () {
9
  yield* task1
10
  yield* task2
11
  // The program stops here due to the error
12
  yield* failure
13
  // The following lines never run
14
  yield* task4
15
  return "some result"
16
})
17

18
Effect.runPromise(program).then(console.log, console.error)
19
/*
20
Output:
21
task1...
22
task2...
23
(FiberFailure) Error: Something went wrong!
24
*/

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)

1
import { Effect } from "effect"
2

3
type User = {
4
  readonly name: string
5
}
6

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

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

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

20
    // @errors: 18048
21
    return `Hello, ${user.name}!`
22
  })
23
}

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)

1
import { Effect } from "effect"
2

3
type User = {
4
  readonly name: string
5
}
6

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

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

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

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

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)

1
import { Effect } from "effect"
2

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

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

10
    return n
11
  })
12
}
13

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

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)

1
import { Effect } from "effect"
2

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

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

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

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.

Using Generators

Understanding Effect.gen

Comparing Effect.gen with async/await

Embracing Control Flow

How to Raise Errors

The Role of Short-Circuiting

Passing this

Adapter Deprecated

Passing `this`