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 { Effect } from "effect"
2

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

5
const applyDiscount = (
6
  total: number,
7
  discountRate: number,
8
): Effect.Effect<number, Error> =>
9
  discountRate === 0
10
    ? Effect.fail(new Error("Discount rate cannot be zero"))
11
    : Effect.succeed(total - (total * discountRate) / 100)
12

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

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

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

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

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

8
const fetchTransactionAmount = Promise.resolve(100)
9

10
const fetchDiscountRate = Promise.resolve(5)
11

12
export const program = async function () {
13
  const transactionAmount = await fetchTransactionAmount
14
  const discountRate = await fetchDiscountRate
15
  const discountedAmount = await applyDiscount(transactionAmount, discountRate)
16
  const finalAmount = addServiceCharge(discountedAmount)