46 - Scope: Resource Lifecycles That Cannot Leak

Previous · Next

A Scope is a lifetime. Finalizers attached to a scope run when the scope closes, on success, on failure, or on interruption.

The two operators that matter day-to-day are Effect.acquireRelease (pair a resource with its cleanup) and Effect.scoped (open and close a scope at a precise point). Get those two right and resources cannot leak.

What you’ll work through

index.test.ts contains four beats: pairing a resource with its cleanup via Effect.acquireRelease, attaching a free-standing finalizer with Effect.addFinalizer, opening and closing a scope explicitly with Effect.scoped, and asserting that finalizers run in LIFO order.

By the end you should treat Scope as the resource model underneath Layers, queues, files, sockets, and any other thing that owns external state.

Concept

1
Effect.scoped                       ──▶ open scope ┐
2
  Effect.acquireRelease(get, close) ──▶ run get    │
3
  ...                                              │
4
  Effect.acquireRelease(open, end)  ──▶ run open   │
5
  ...                                              │
6
                                    ◀── close scope (run finalizers in LIFO order)
7

8
If acquire fails        ──▶ no release runs (nothing was acquired).
9
If body fails           ──▶ every release still runs, then failure propagates.
10
If fiber is interrupted ──▶ every release still runs, then interruption propagates.

Finalizers run in LIFO order, the reverse of registration, closer cleans up before farther.

`Effect.acquireRelease`

Creates a scoped resource: pair a value-producing Effect (acquire) with a cleanup function (release). The resulting Effect has Scope in its requirements until you provide one.

1
import { Effect } from "effect"
2

3
interface Connection {
4
  readonly id: number
5
  readonly close: () => void
6
}
7

8
const open: Effect.Effect<Connection> = Effect.sync(() => ({
9
  id: 1,
10
  close: () => {},
11
}))
12

13
//      ┌─── Effect<Connection, never, Scope>
14
//      ▼
15
const managed = Effect.acquireRelease(
16
  open,
17
  (conn) => Effect.sync(() => conn.close()),
18
)

Details

The release callback receives the resource and the Exit describing how the scope is closing. Inspect the Exit if cleanup differs between success and failure.

When to Use

For anything with a paired open/close: connections, files, locks, subscriptions, child processes.

`Effect.addFinalizer`

Attaches a finalizer to the current scope without producing a resource. Useful when cleanup is logical rather than tied to a value.

1
//      ┌─── Effect<void, never, Scope>
2
//      ▼
3
const logShutdown = Effect.addFinalizer((exit) =>
4
  Effect.sync(() => console.log(`closing, exit: ${exit._tag}`)),
5
)

`Effect.scoped`

Provides a fresh Scope, runs the inner Effect, and closes the scope when the Effect ends. This is the boundary that removes Scope from R.

1
//      ┌─── Effect<Connection, never, never>
2
//      ▼
3
const program = Effect.scoped(managed)

When to Use

At the boundary where the resource’s lifetime should end. For services owned by the application, that boundary is the layer (Layer.effect), the scope closes on shutdown.

For short-lived resources, scope the smallest block that needs them.

Composite Example: Acquire / Use / Cleanup

1
//      ┌─── Effect<number, never, never>
2
//      ▼
3
const program = Effect.scoped(
4
  Effect.gen(function* () {
5
    const conn = yield* Effect.acquireRelease(
6
      Effect.sync(() => ({ id: 42, close: () => {} })),
7
      (c) => Effect.sync(() => c.close()),
8
    )
9
    yield* Effect.addFinalizer(() => Effect.sync(() => {/* flush metrics */}))
10
    return conn.id
11
  }),
12
)

When the inner block ends, finalizers run in reverse order: the metric flush first, then the connection close.

Use-after-scope is a bug

Effect.scoped closes the scope when its body finishes — every resource acquired inside is finalized at that boundary. Capturing a reference to the resource and using it outside Effect.scoped is a use-after-close bug.

With trivial in-memory values the bug is silent; with real resources (file handles, DB connections, sockets) the call throws.

1
import { Effect } from "effect"
2

3
// ✗ Bug: connection escapes the scope that owns its lifetime.
4
const broken = Effect.gen(function* () {
5
  let captured: Connection | undefined
6
  yield* Effect.scoped(
7
    Effect.gen(function* () {
8
      const conn = yield* openConnection
9
      captured = conn        // hold onto it past the scope
10
      return conn.query("SELECT 1")
11
    }),
12
  )
13
  // captured is closed here — using it throws.
14
  return captured!.query("SELECT 2")
15
})

The fix is to keep the resource use inside Effect.scoped, or to hoist the scope outward so it spans the entire lifetime the resource is used.

Your turn read the test that captures a resource and tries to use it after the scope ends — confirm the failure exit. Then complete the correct version where the use stays inside `Effect.scoped`.

Common Pitfalls

1, Forgetting Effect.scoped. An effect with Scope in its requirements is unrunnable until a scope is provided. The type system catches this; trust the error.

2, Closing the scope too early. Wrapping a service constructor in Effect.scoped closes the scope before the service is returned, so the resource is released immediately. Hoist Effect.scoped to the consumer, or use Layer.effect so the scope is the layer’s lifetime.

3, Throwing inside release. A throw in the release function is a defect, it cannot be recovered from with catch. Keep release functions infallible; if cleanup can fail, use Effect.catch inside the release to swallow or log.

4, Confusing Scope with try/finally. try/finally only fires on synchronous return. Scopes fire on success, failure, and interruption, the third case is what makes resources leak under cancellation.

confirm it runs on success, failure, and interruption. - [ ] Open a scope explicitly with `Effect.scoped` to control when finalizers fire. - [ ] Confirm finalizers run in LIFO order — the test asserts the order.

The full test suite

The index.test.ts for this lesson, verbatim from steps/46-scope/.

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

4
// =============================================================================
5
// 37 - Scope: Resource Lifecycles That Cannot Leak
6
// =============================================================================
7
//
8
// Effect.acquireRelease  pair a resource with its cleanup     — Effect<A, E, Scope>
9
// Effect.addFinalizer    attach a finalizer to the scope       — Effect<void, never, Scope>
10
// Effect.scoped          provide a fresh Scope, then close it  — removes Scope from R
11

12
describe("37 - Scope", () => {
13
  // @beat
14
  //   id: acquire-release
15
  //   shape: one-todo
16
  //   title: Pair acquire with release
17
  //   teaches: Effect.acquireRelease pairs a resource-producing Effect with a cleanup function; the resulting Effect requires a Scope.
18
  //   hint: Effect.acquireRelease(acquireEffect, (resource) => releaseEffect)
19
  describe("Effect.acquireRelease", () => {
20
    it("releases the resource when the scope closes", async () => {
21
      const events: Array<string> = []
22

23
      //      ┌─── Effect<{ readonly id: number }, never, Scope>
24
      //      ▼
25
      const managed = /* @stub */ Effect.acquireRelease(
26
        Effect.sync(() => {
27
          events.push("acquired")
28
          return { id: 42 }
29
        }),
30
        (resource) =>
31
          Effect.sync(() => {
32
            events.push(`released ${resource.id}`)
33
          }),
34
      ) /* @end */
35

36
      const result = await Effect.runPromise(
37
        Effect.scoped(
38
          Effect.gen(function* () {
39
            const resource = yield* managed
40
            return resource.id
41
          }),
42
        ),
43
      )
44

45
      expect(result).toBe(42)
46
      expect(events).toEqual(["acquired", "released 42"])
47
    })
48

49
    it("releases even when the body fails", async () => {
50
      const released: Array<boolean> = []
51

52
      const exit = await Effect.runPromiseExit(
53
        Effect.scoped(
54
          Effect.gen(function* () {
55
            yield* Effect.acquireRelease(
56
              Effect.succeed("connection"),
57
              () => Effect.sync(() => released.push(true)),
58
            )
59
            return yield* Effect.fail("db error")
60
          }),
61
        ),
62
      )
63

64
      expect(Exit.isFailure(exit)).toBe(true)
65
      expect(released).toEqual([true])
66
    })
67
  })
68
  // @end-beat
69

70
  // @beat
71
  //   id: scoped-boundary
72
  //   shape: one-todo
73
  //   title: Close the scope with Effect.scoped
74
  //   teaches: Effect.scoped opens a fresh Scope, runs the body, and closes the scope — removing Scope from R.
75
  //   hint: wrap the inner Effect.gen with Effect.scoped(...)
76
  describe("Effect.scoped", () => {
77
    it("removes Scope from the requirements", async () => {
78
      //      ┌─── Effect<number, never, never>
79
      //      ▼
80
      const program = /* @stub */ Effect.scoped(
81
        Effect.gen(function* () {
82
          yield* Effect.addFinalizer(() => Effect.void)
83
          return 1
84
        }),
85
      ) /* @end */
86

87
      expect(await Effect.runPromise(program)).toBe(1)
88
    })
89
  })
90
  // @end-beat
91

92
  // @beat
93
  //   id: add-finalizer
94
  //   shape: read-run
95
  //   title: Attach cleanup with addFinalizer
96
  //   teaches: Effect.addFinalizer attaches cleanup to the current scope; the finalizer runs on success and on failure.
97
  //   hint: read both tests — the finalizer fires whether the body succeeds or fails
98
  describe("Effect.addFinalizer", () => {
99
    it("runs on success", async () => {
100
      const program = Effect.gen(function* () {
101
        const log = yield* Ref.make<ReadonlyArray<string>>([])
102
        const body = Effect.gen(function* () {
103
          yield* Effect.addFinalizer(() => Ref.update(log, (arr) => [...arr, "cleanup"]))
104
          return "result"
105
        })
106
        const result = yield* Effect.scoped(body)
107
        const events = yield* Ref.get(log)
108
        return { result, events }
109
      })
110

111
      const out = await Effect.runPromise(program)
112
      expect(out.result).toBe("result")
113
      expect(out.events).toEqual(["cleanup"])
114
    })
115

116
    it("runs on failure", async () => {
117
      const log: Array<string> = []
118

119
      const exit = await Effect.runPromiseExit(
120
        Effect.scoped(
121
          Effect.gen(function* () {
122
            yield* Effect.addFinalizer(() => Effect.sync(() => log.push("cleanup")))
123
            return yield* Effect.fail("oops")
124
          }),
125
        ),
126
      )
127

128
      expect(Exit.isFailure(exit)).toBe(true)
129
      expect(log).toEqual(["cleanup"])
130
    })
131
  })
132
  // @end-beat
133

134
  // @beat
135
  //   id: lifo-finalizers
136
  //   shape: one-todo
137
  //   title: Finalizers run in LIFO order
138
  //   teaches: Finalizers fire in reverse registration order — closer cleans up before farther.
139
  //   hint: register "first" then "second"; the close order is ["second", "first"]
140
  it("runs finalizers in LIFO order", async () => {
141
    const log: Array<string> = []
142

143
    await Effect.runPromise(
144
      Effect.scoped(
145
        /* @stub */ Effect.gen(function* () {
146
          yield* Effect.addFinalizer(() => Effect.sync(() => log.push("first")))
147
          yield* Effect.addFinalizer(() => Effect.sync(() => log.push("second")))
148
        }) /* @end */,
149
      ),
150
    )
151

152
    expect(log).toEqual(["second", "first"])
153
  })
154
  // @end-beat
155

156
  // @beat
157
  //   id: use-after-scope
158
  //   shape: multi-todo
159
  //   title: Use a resource inside its scope — not outside
160
  //   teaches: Effect.scoped closes the scope when the body finishes; any resource obtained inside is finalized. Capturing a reference and using it outside is a bug — in real resources (file handles, DB connections) it throws.
161
  //   hint: move the resource use inside the Effect.scoped block — the scope guarantees the resource is live for the duration
162

163
  describe("Effect.scoped boundary", () => {
164
    it("a resource finalized outside its scope cannot be used safely (read this)", async () => {
165
      const log: Array<string> = []
166
      let capturedQuery: (() => string) | null = null
167

168
      const dbResource = Effect.acquireRelease(
169
        Effect.sync(() => ({
170
          query: () => {
171
            if (log.includes("released")) throw new Error("connection closed")
172
            return "result"
173
          },
174
        })),
175
        () => Effect.sync(() => log.push("released")),
176
      )
177

178
      // Scope closes at the end of Effect.scoped — capturedQuery is now "dead"
179
      await Effect.runPromise(
180
        Effect.scoped(
181
          Effect.gen(function* () {
182
            const db = yield* dbResource
183
            capturedQuery = db.query // captured but will be finalized
184
          }),
185
        ),
186
      )
187

188
      expect(log).toContain("released")
189
      // Using the captured reference outside the scope throws
190
      expect(() => capturedQuery!()).toThrow("connection closed")
191
    })
192

193
    it("use the resource inside Effect.scoped — guaranteed live", async () => {
194
      const log: Array<string> = []
195

196
      const dbResource = Effect.acquireRelease(
197
        Effect.sync(() => ({ query: () => "result" })),
198
        () => Effect.sync(() => log.push("released")),
199
      )
200

201
      const result = await Effect.runPromise(
202
        /* @stub */ Effect.scoped(
203
          Effect.gen(function* () {
204
            const db = yield* dbResource
205
            return db.query() // use inside — resource is live here
206
          }),
207
        ) /* @end */,
208
      )
209

210
      expect(result).toBe("result")
211
      expect(log).toContain("released")
212
    })
213
  })
214
  // @end-beat
215

216
})

07·01Scope

46 - Scope: Resource Lifecycles That Cannot Leak

What you’ll work through

Concept

`Effect.acquireRelease`

`Effect.addFinalizer`

`Effect.scoped`

Composite Example: Acquire / Use / Cleanup

Use-after-scope is a bug

Common Pitfalls

See Also

The full test suite