07 - `Effect.gen`: Sequential Effects, Flat Syntax

Previous · Next

A chain of flatMap calls produces correct, type-safe sequential code, and unreadable indentation. Effect.gen is sugar over that chain: a generator function whose yield* plays the role of await.

Every yielded effect’s success value becomes a local variable in the same scope; every failure short-circuits the generator.

What you’ll work through

index.test.ts contains five beats: a basic yield* chain, a conditional failure with return yield* Effect.fail, a short-circuit demonstration, a side-by-side gen-vs-flatMap equivalence, and an async generator that mixes Effect.sync with Effect.tryPromise. Most beats have one or two stubs.

By the end you should be able to write a sequential workflow as a flat generator and know when to reach for pipe instead.

Mental Model

yield* unwraps the success channel and binds it. The error channel is propagated to the outer effect, the line after a failing yield* does not run.

1
Effect.gen(function* () {
2
  const a = yield* stepA   //  success: a = A,   continue
3
                           //  failure: generator stops, E propagates
4
  const b = yield* stepB   //  success: b = B,   continue
5
  return a + b             //  ─► Effect<number, E_A | E_B, R_A | R_B>
6
})

The flat scope is the point: every bound value is visible to every later step. The flatMap form keeps each variable trapped inside its callback.

1
// flatMap:                            // gen:
2
a.pipe(Effect.flatMap((a) =>           Effect.gen(function* () {
3
  b.pipe(Effect.flatMap((b) =>           const a = yield* a
4
    c.pipe(Effect.map((c) =>             const b = yield* b
5
      a + b + c                          const c = yield* c
6
    ))                                   return a + b + c
7
  ))                                   })
8
))

Unwrap with `yield*`

Creates an Effect from a generator. Each yield* consumes an effect and produces its success value.

The outer effect’s types are inferred from the return value and the union of every yielded effect.

1
import { Effect } from "effect"
2

3
//      ┌─── Effect<number, never, never>
4
//      ▼
5
const program = Effect.gen(function* () {
6
  const a = yield* Effect.succeed(1)
7
  const b = yield* Effect.succeed(2)
8
  const c = yield* Effect.succeed(3)
9
  return a + b + c
10
})

Details

The generator function does not take an adapter argument in Effect v4, yield* is applied directly to effects. The outer Effect’s E channel is the union of every yielded effect’s E; the R channel is the union of every yielded effect’s R.

The return value of the generator is the outer A.

A failure inside the generator behaves like an exception that the surrounding flatMap chain would have short-circuited on: subsequent statements do not execute, and the failure is the outer effect’s failure.

When to Use

For any sequential effect logic with more than one step, especially when later steps depend on earlier values. Reach for pipe(Effect.map, Effect.flatMap) for single-step transformations or when a single combinator (Effect.all, Effect.zip) is enough.

Your turn `yield*` each Effect so its success value lands in a plain local binding.

Variables in Scope

Every yield* result is a regular local binding.

1
//      ┌─── Effect<{ user: User; posts: ReadonlyArray<Post> }, never, never>
2
//      ▼
3
const program = Effect.gen(function* () {
4
  const user = yield* Effect.succeed({ id: "1", name: "Alice" })
5
  const posts = yield* Effect.succeed(["post1", "post2"])
6
  return { user, posts }
7
})

No closures, no callback nesting. Branches, loops, and try/finally work as in any other generator, the only special form is yield*.

Conditional Failure

A typed failure inside a generator is yield* Effect.fail(...). The generator stops at that point; the error widens the outer E.

1
import { Effect } from "effect"
2

3
//      ┌─── Effect<number, "Division by zero", never>
4
//      ▼
5
const divide = (a: number, b: number): Effect.Effect<number, "Division by zero"> =>
6
  Effect.gen(function* () {
7
    if (b === 0) {
8
      return yield* Effect.fail("Division by zero" as const)
9
    }
10
    return a / b
11
  })

The return yield* form is required because yield* Effect.fail(...) has type never, returning it satisfies the function signature without an unreachable branch.

> not its success channel. The binding becomes `Effect` rather than > `A`. The star is doing all the work — never drop it.

Your turn `return yield* Effect.fail(...)` on the `b === 0` branch so the divide function rejects. The success branch should return `a / b` directly.

Short-Circuit

Code placed after a failing yield* does not execute. There is no compiler warning for dead code, so the assumption must be explicit.

1
const program = Effect.gen(function* () {
2
  yield* Effect.fail("boom")
3
  // never runs
4
  return "done"
5
})

For cleanup that must always run, use Effect.ensuring or Effect.acquireRelease (introduced in step 46).

Your turn `yield* Effect.fail(...)` in the middle of a generator and confirm the lines after it never execute.

gen and flatMap have the same semantics

Effect.gen is sugar over a flatMap chain. The two forms produce the same description; the generator just keeps every variable in one flat scope.

Your turn read both forms and confirm they return the same value.

Mixing Sync, Async, and Errors

A generator can yield any effect, sync, async, failing, depending on a service, and the inferred types fold every channel together.

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

3
class FetchError extends Data.TaggedError("FetchError")<{ url: string }> {}
4

5
//      ┌─── Effect<{ user: unknown; posts: unknown }, FetchError, never>
6
//      ▼
7
const program = Effect.gen(function* () {
8
  const config = yield* Effect.sync(() => ({ baseUrl: "https://api.example.com" }))
9

10
  const user = yield* Effect.tryPromise({
11
    try: () => fetch(`${config.baseUrl}/users/1`).then((r) => r.json()),
12
    catch: () => new FetchError({ url: `${config.baseUrl}/users/1` }),
13
  })
14

15
  const posts = yield* Effect.tryPromise({
16
    try: () => fetch(`${config.baseUrl}/posts?userId=${(user as { id: string }).id}`).then((r) => r.json()),
17
    catch: () => new FetchError({ url: `${config.baseUrl}/posts` }),
18
  })
19

20
  return { user, posts }
21
})

Your turn `yield*` an `Effect.tryPromise` so the resolved value is bound locally and a rejection lands in E.

Rule: gen for sequencing, pipe for instrumentation

Effect.gen is the canonical way to sequence dependent steps. Reach for it whenever one step needs the result of the previous.

pipe is the canonical way to decorate a workflow — retry, timeout, log annotations, span attachment — without changing what the workflow does.

1
//  ✅ gen — each step depends on the previous
2
const order = Effect.gen(function* () {
3
  const user = yield* fetchUser(id)
4
  const cart = yield* loadCart(user.id)
5
  const total = yield* priceCart(cart)
6
  return { user, cart, total }
7
})
8

9
//  ✅ pipe — apply cross-cutting concerns at the edge
10
const robust = order.pipe(
11
  Effect.retry(Schedule.recurs(3)),
12
  Effect.timeout("5 seconds"),
13
  Effect.annotateLogs({ orderId: id }),
14
)

If you find yourself chaining flatMap more than two or three times inside a pipe, switch to gen. If you’re attaching retry/timeout/logging to a workflow, switch to pipe.

The split keeps both forms readable.

Rules of thumb

yield* for sequencing dependent steps; pipe for decoration. When a step needs the previous result, use gen. When you’re wrapping a workflow in retry/timeout/log, use pipe.
Never run inside a gen. Effect.runPromise inside a generator is almost always a bug — yield* the inner Effect instead.
gen is where local variables live. It’s the natural home for shared intermediate values, accumulators, and audit arrays.

Common Pitfalls

1, yield instead of yield*. yield produces the effect value itself, not its success channel. The local binding becomes Effect<A, E, R> instead of A.

Always yield*.

2, Forgetting that failure ends the generator. Lines after a failing yield* are dead code. Use Effect.ensuring or Effect.acquireRelease for guaranteed cleanup.

3, runSync on an async generator. If any yielded effect is async, Effect.runSync throws. Use Effect.runPromise.

4, Trying to await inside the generator. await is for async functions; Effect.gen uses yield*. Wrap promises with Effect.tryPromise and yield them.

derived value. - [ ] Complete `conditional-fail`: `return yield* Effect.fail(...)` for the divide-by-zero case. - [ ] Read `short-circuit` and confirm code after a failing `yield*` never runs. - [ ] Compare the `gen-vs-flatmap` pair and note that both forms produce the same description. - [ ] Complete `async-yield`: `yield*` an `Effect.tryPromise` so the resolved value binds locally and rejection lands in `E`. - [ ] Note the "gen for sequencing, pipe for instrumentation" rule — it reappears in nearly every step that follows.

The full test suite

The index.test.ts for this lesson, verbatim from steps/07-effect-gen/.

1
import { it, expect } from "vite-plus/test"
2
import { Effect, Exit } from "effect"
3

4
// =============================================================================
5
// 06 - Effect.gen: Sequential Effects, Flat Syntax
6
// =============================================================================
7
//
8
// yield* unwraps the success channel; failures short-circuit the generator.
9
// The outer Effect's E is the union of every yielded effect's E.
10

11
// @beat
12
//   id: yield-star
13
//   shape: multi-todo
14
//   title: Unwrap success with yield*
15
//   teaches: yield* applied to an Effect binds its success value as a local variable in the same scope.
16
//   hint: prefix each Effect with yield* to get its A value into a local binding
17
it("unwraps the success value", () => {
18
  //      ┌─── Effect<number, never, never>
19
  //      ▼
20
  const program = Effect.gen(function* () {
21
    const a = /* @stub */ yield* Effect.succeed(1) /* @end */
22
    const b = /* @stub */ yield* Effect.succeed(2) /* @end */
23
    return a + b
24
  })
25

26
  expect(Effect.runSync(program)).toBe(3)
27
})
28

29
it("keeps every bound value in the same scope", () => {
30
  const program = Effect.gen(function* () {
31
    const user = /* @stub */ yield* Effect.succeed({ id: "1", name: "Alice" }) /* @end */
32
    const posts = /* @stub */ yield* Effect.succeed(["post1", "post2"]) /* @end */
33
    return { user, posts }
34
  })
35

36
  const result = Effect.runSync(program)
37
  expect(result.user.name).toBe("Alice")
38
  expect(result.posts.length).toBe(2)
39
})
40
// @end-beat
41

42
// @beat
43
//   id: short-circuit
44
//   shape: multi-todo
45
//   title: Failure short-circuits the generator
46
//   teaches: A failing yield* stops the generator; every later statement is dead code and the failure propagates.
47
//   hint: yield* Effect.fail to short-circuit — the lines after it never run
48
it("stops at the first failing yield*", () => {
49
  let reached = false
50
  const program = Effect.gen(function* () {
51
    const a = yield* Effect.succeed(1)
52
    /* @stub */ yield* Effect.fail("boom") /* @end */
53
    reached = true
54
    return a
55
  })
56

57
  expect(Exit.isFailure(Effect.runSyncExit(program))).toBe(true)
58
  expect(reached).toBe(false)
59
})
60

61
it("skips every statement after the failure", () => {
62
  const log: string[] = []
63

64
  const program = Effect.gen(function* () {
65
    log.push("step 1 started")
66
    yield* Effect.succeed("ok")
67
    log.push("step 1 done")
68

69
    log.push("step 2 will fail")
70
    /* @stub */ yield* Effect.fail("error") /* @end */
71

72
    log.push("step 3 — never runs")
73
    log.push("step 4 — never runs")
74
    return "never"
75
  })
76

77
  Effect.runSyncExit(program)
78
  expect(log).toEqual(["step 1 started", "step 1 done", "step 2 will fail"])
79
})
80
// @end-beat
81

82
// @beat
83
//   id: conditional-fail
84
//   shape: one-todo
85
//   title: Fail conditionally inside a generator
86
//   teaches: `return yield* Effect.fail(...)` lets a generator reject on a branch while preserving the inferred E type.
87
//   hint: yield* Effect.fail has type never — return it to satisfy the function signature
88
it("conditionally fails on a branch", () => {
89
  //      ┌─── Effect<number, "Division by zero", never>
90
  //      ▼
91
  const divide = (a: number, b: number): Effect.Effect<number, "Division by zero"> =>
92
    Effect.gen(function* () {
93
      if (b === 0) {
94
        return /* @stub */ yield* Effect.fail("Division by zero" as const) /* @end */
95
      }
96
      return a / b
97
    })
98

99
  expect(Effect.runSync(divide(10, 2))).toBe(5)
100
  expect(Exit.isFailure(Effect.runSyncExit(divide(10, 0)))).toBe(true)
101
})
102
// @end-beat
103

104
// @beat
105
//   id: gen-vs-flatmap
106
//   shape: read-run
107
//   title: gen and flatMap have the same semantics
108
//   teaches: Effect.gen compiles to the same flatMap chain — the generator is sugar for nested callbacks.
109
//   hint: compare both forms and notice the inferred type and result are identical
110
it("nested flatMap produces the same result", () => {
111
  const program = Effect.succeed(1).pipe(
112
    Effect.flatMap((a) =>
113
      Effect.succeed(2).pipe(
114
        Effect.flatMap((b) => Effect.succeed(3).pipe(Effect.map((c) => a + b + c))),
115
      ),
116
    ),
117
  )
118

119
  expect(Effect.runSync(program)).toBe(6)
120
})
121

122
it("Effect.gen keeps the same logic flat", () => {
123
  const program = Effect.gen(function* () {
124
    const a = yield* Effect.succeed(1)
125
    const b = yield* Effect.succeed(2)
126
    const c = yield* Effect.succeed(3)
127
    return a + b + c
128
  })
129

130
  expect(Effect.runSync(program)).toBe(6)
131
})
132
// @end-beat
133

134
// @beat
135
//   id: async-yield
136
//   shape: multi-todo
137
//   title: Yield async effects inside a generator
138
//   teaches: Effect.tryPromise lifts a Promise into an Effect; yielding it inside Effect.gen unwraps the resolved value (or routes the catch to E).
139
//   hint: yield* the Effect.tryPromise result the same way as any other effect
140
it("yields a tryPromise result on success", async () => {
141
  const fetchUser = async (id: string) => {
142
    if (id === "0") throw new Error("User not found")
143
    return { id, name: "Alice" }
144
  }
145

146
  const program = Effect.gen(function* () {
147
    const user = /* @stub */ yield* Effect.tryPromise({
148
      try: () => fetchUser("123"),
149
      catch: (cause) => new Error(`Fetch failed: ${String(cause)}`),
150
    }) /* @end */
151
    return user.name
152
  })
153

154
  await expect(Effect.runPromise(program)).resolves.toBe("Alice")
155
})
156

157
it("places the catch result in E when the promise rejects", async () => {
158
  const fetchUser = async (id: string) => {
159
    if (id === "0") throw new Error("User not found")
160
    return { id, name: "Alice" }
161
  }
162

163
  const program = Effect.gen(function* () {
164
    const user = /* @stub */ yield* Effect.tryPromise({
165
      try: () => fetchUser("0"),
166
      catch: (cause) => new Error(`Fetch failed: ${String(cause)}`),
167
    }) /* @end */
168
    return user.name
169
  })
170

171
  const exit = await Effect.runPromiseExit(program)
172
  expect(Exit.isFailure(exit)).toBe(true)
173
})
174
// @end-beat

02·01Effect.gen

07 - `Effect.gen`: Sequential Effects, Flat Syntax

What you’ll work through

Mental Model

Unwrap with `yield*`

Variables in Scope

Conditional Failure

Short-Circuit

gen and flatMap have the same semantics

Mixing Sync, Async, and Errors

Rule: gen for sequencing, pipe for instrumentation

Rules of thumb

Common Pitfalls

See Also

The full test suite

02·01Effect.gen

07 - Effect.gen: Sequential Effects, Flat Syntax

What you’ll work through

Mental Model

Unwrap with yield*

Variables in Scope

Conditional Failure

Short-Circuit

gen and flatMap have the same semantics

Mixing Sync, Async, and Errors

Rule: gen for sequencing, pipe for instrumentation

Rules of thumb

Common Pitfalls

See Also

The full test suite

07 - `Effect.gen`: Sequential Effects, Flat Syntax

Unwrap with `yield*`