@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
md 113 lines 3.58 KB
Rendered Raw
1 # Layer Memoization
2
3 In v3, each call to `Effect.provide` created its own memoization scope. Layers
4 were memoized / deduplicated within a single `Effect.provide` call, but would
5 **not** be shared across separate calls — so two `Effect.provide` calls with
6 overlapping layers would silently build those layers twice.
7
8 In v4, a layer already built by an enclosing `Effect.provide` or runtime is
9 reused by nested `Effect.provide` calls. Each call forks the ambient `MemoMap`: it
10 can reuse parent entries, but newly built layers are not written back to the
11 parent. Sibling `Effect.provide` calls therefore build their own copies, just as
12 in v3. Use `{ local: true }` to build a fresh layer subtree without reusing the
13 enclosing memo map.
14
15 ## Example
16
17 ```ts
18 import { Console, Context, Effect, Layer } from "effect"
19
20 const MyService = Context.Service<{ readonly value: string }>("MyService")
21
22 const MyServiceLayer = Layer.effect(
23 MyService,
24 Effect.gen(function*() {
25 yield* Console.log("Building MyService")
26 return { value: "hello" }
27 })
28 )
29
30 const program = Effect.gen(function*() {
31 const a = yield* MyService
32 return a.value
33 })
34
35 // Same layer provided twice in nested provide calls
36 const main = program.pipe(
37 Effect.provide(MyServiceLayer),
38 Effect.provide(MyServiceLayer)
39 )
40
41 // Effect v3: "Building MyService" is logged TWICE
42 // Effect v4: "Building MyService" is logged ONCE
43 Effect.runPromise(main)
44 ```
45
46 The calls above are nested, not siblings. In contrast, the following builds
47 `MyServiceLayer` twice in v4 when no enclosing provide or runtime has already
48 built it:
49
50 ```ts
51 const siblings = Effect.gen(function*() {
52 yield* program.pipe(Effect.provide(MyServiceLayer))
53 yield* program.pipe(Effect.provide(MyServiceLayer))
54 })
55
56 Effect.runPromise(siblings) // "Building MyService" is logged TWICE
57 ```
58
59 ## Prefer Layer Composition Over Multiple Provides
60
61 Even though nested v4 `provide` calls reuse already-built layers, **composing
62 layers before providing is still the recommended pattern**. Layer composition makes your
63 dependency graph explicit and lets you see the full structure in one place:
64
65 ```ts
66 // Preferred — provide once
67 const main = program.pipe(Effect.provide(MyServiceLayer))
68 ```
69
70 Reusing enclosing layers is **not** a substitute for proper layer composition
71 and does not deduplicate independent sibling builds.
72
73 ## Opting Out of Shared Memoization
74
75 There are cases where you **want** a layer to be built fresh — for example,
76 test isolation or creating independent resource pools. v4 provides two
77 mechanisms:
78
79 ### `Layer.fresh`
80
81 Wraps a layer so it always builds with a fresh memo map, bypassing the shared
82 cache. This existed in v3 as well.
83
84 ```ts
85 import { Effect, Layer } from "effect"
86
87 const main = program.pipe(
88 Effect.provide(MyServiceLayer),
89 Effect.provide(Layer.fresh(MyServiceLayer))
90 )
91 // "Building MyService" is logged TWICE — fresh bypasses the shared cache
92 ```
93
94 ### `Effect.provide` with `{ local: true }`
95
96 New in v4. Builds the provided layer with a **local memo map** instead of the
97 fiber's ambient one. The layer and all its sublayers are built from scratch,
98 without reusing layers built by an enclosing `provide` or runtime. Nested
99 `provide` calls can still reuse layers built in this local map.
100
101 ```ts
102 import { Effect } from "effect"
103
104 const main = program.pipe(
105 Effect.provide(MyServiceLayer, { local: true }),
106 Effect.provide(MyServiceLayer)
107 )
108 // "Building MyService" is logged TWICE — local creates its own memo map
109 ```
110
111 Use `local: true` when you need an entire layer subtree to be isolated — for
112 example, when providing layers in a test harness where each test should get
113 independent resources.