24 - Advanced DI: Composing the Dependency Graph

Previous · Next

Layers form a directed acyclic graph. Effect resolves the graph at startup and constructs each service exactly once, sharing the instance with every dependent.

This step covers the patterns that scale: wiring chains, merging many independent services, exposing intermediate services with provideMerge, and guaranteeing shared instances.

What you’ll work through

index.test.ts contains three beats: composing a multi-layer DAG via Layer.provide / Layer.provideMerge, combining many independents with Layer.mergeAll, and asserting that a shared dependency is constructed exactly once across the graph.

By the end you should be able to lay out an application’s service graph as a single AppLayer value and reason about construction order from the shape of the wiring.

Layers as a DAG

1
   ConfigLive ─────────────────┐
2
        │                       │
3
        ▼                       ▼
4
   DatabaseLive ──────┐    LoggerLive
5
        │             │         │
6
        ▼             ▼         ▼
7
   ApiLive       ReportLive   AuditLive
8
        │             │         │
9
        └─────────────┴─────────┘
10
                      ▼
11
                  AppLayer
12
                      │
13
                      ▼
14
            Effect.provide(AppLayer)
15

16
   Arrow = "this layer's input"
17
   ConfigLive is constructed ONCE. Both Database and Logger
18
   share the same instance.

The shared-instance guarantee is what makes Layer composition tractable. A connection pool, a config object, a logger, declare it once, wire it through, and Effect never constructs it twice.

`Layer.provide`: Wire a Dependency

1
import { Layer } from "effect"
2

3
//      ┌─── Layer<Database, never, never>
4
//      ▼
5
const DatabaseWithConfig = DatabaseLive.pipe(Layer.provide(ConfigLive))

Layer.provide(dependency) plugs dependency into the receiving layer’s RIn, removing it from the result’s RIn. The dependency is no longer visible to callers of the resulting layer, it has been satisfied internally.

`Layer.provideMerge`: Wire and Expose

1
import { Layer } from "effect"
2

3
//      ┌─── Layer<UserService | Database | Config, ..., never>
4
//      ▼
5
const AppLayer = UserServiceLive.pipe(
6
  Layer.provideMerge(DatabaseLive),
7
  Layer.provideMerge(ConfigLive)
8
)

Layer.provideMerge does the same wiring as Layer.provide but keeps the wired-in services available in the output. Use it when downstream code also needs direct access to those services, for example, a request handler that calls UserService but also needs raw Database queries elsewhere.

Your turn chain `Layer.provide` so `ApiLive` is satisfied by `DatabaseLive`, which itself is satisfied by `ConfigLive`.

`Layer.mergeAll`: Combine Independents

1
import { Layer } from "effect"
2

3
//      ┌─── Layer<Logger | Cache | Metrics, never, ConfigService>
4
//      ▼
5
const AppLayer = Layer.mergeAll(LoggerLive, CacheLive, MetricsLive)

Layer.mergeAll combines layers that do not depend on each other into a single layer that provides every service. Their RIn channels are unioned (so any shared input appears exactly once in the result), their errors are unioned, and the output ROut exposes every service from every layer.

This is the typical top-level shape of a production AppLayer: a flat bundle of horizontal capabilities sitting on top of whatever the vertical Layer.provide chain produced.

> needs `Logger` to be present, do not merge them — use `Layer.provide` > (previous beat) so the dependency is wired, then `mergeAll` whatever is > left.

Rule of thumb. Reach for mergeAll once your tree has more than two “siblings”. For one or two, a single Layer.merge(a, b) reads fine; past that, the variadic form is much easier to keep tidy.

Your turn call `Layer.mergeAll(ConfigLive, DatabaseLive, CacheLive)` so the resulting `AppLayer` provides all three services to the program in one shot. The test reads `Config`, `Database`, and `Cache` and asserts each came from its expected `Live` implementation.

Shared Instances

When a layer value is referenced more than once in the graph, Effect constructs the service once. The contract is per-Layer-value, not per-reference: two separate Layer.sync calls with the same factory produce two different services.

1
import { Layer } from "effect"
2

3
// One named layer, used in two places, one Database instance.
4
const DatabaseShared = Layer.sync(Database, makeDatabase)
5

6
const AppLayer = Layer.mergeAll(
7
  ApiLive.pipe(Layer.provide(DatabaseShared)),
8
  ReportLive.pipe(Layer.provide(DatabaseShared)),
9
  DatabaseShared // exposed directly for code that does raw queries
10
)

If you call Layer.sync(Database, makeDatabase) twice, even with the same factory, the result is two distinct layers and two distinct instances. Name the layer once and reuse the value.

Your turn bind the shared layer to a `const` and pass that same value to every consumer; the construction counter must stay at one.

Wiring three services into one `AppLayer`

Layer.provide chains a dependency into a layer; Layer.mergeAll bundles independent layers into one. The standard application shape combines both — provide the wiring you need, then merge the independent results.

1
import { Layer } from "effect"
2

3
// Config is leaf. Database needs Config. Logger is independent.
4
const DatabaseWithConfig = DatabaseLive.pipe(Layer.provide(ConfigLive))
5

6
//      ┌─── Layer<Logger | Database, never, never>
7
//      ▼
8
const AppLayer = Layer.mergeAll(LoggerLive, DatabaseWithConfig)
9

10
await Effect.runPromise(program.pipe(Effect.provide(AppLayer)))

The runner sees a single AppLayer value. Internally that value is a DAG of layers — Layer.provide writes edges, Layer.mergeAll collects roots.

Your turn wire `Database` with `Config` via `Layer.provide`, then merge it with `Logger` into a single `AppLayer` and run a program that depends on all three.

A Full Example

A four-service graph: Config is shared, Database depends on Config, both Api and Report depend on Database, and the top-level program needs all four.

1
import { Effect, Context, Layer } from "effect"
2

3
class Config extends Context.Service<Config, { readonly dbUrl: string }>()("app/Config") {}
4

5
class Database extends Context.Service<Database, { readonly query: (sql: string) => Effect.Effect<ReadonlyArray<string>> }>()("app/Database") {}
6

7
class Api extends Context.Service<Api, { readonly getUser: (id: string) => Effect.Effect<ReadonlyArray<string>> }>()("app/Api") {}
8

9
class Report extends Context.Service<Report, { readonly generate: (sql: string) => Effect.Effect<string> }>()("app/Report") {}
10

11
const ConfigLive = Layer.succeed(Config, { dbUrl: "postgres://prod" })
12

13
const DatabaseLive = Layer.effect(
14
  Database,
15
  Effect.gen(function* () {
16
    const { dbUrl } = yield* Config
17
    return {
18
      query: (sql) => Effect.succeed([`${dbUrl}: ${sql}`]),
19
    }
20
  })
21
)
22

23
const ApiLive = Layer.effect(
24
  Api,
25
  Effect.gen(function* () {
26
    const db = yield* Database
27
    return {
28
      getUser: (id) => db.query(`SELECT * FROM users WHERE id='${id}'`),
29
    }
30
  })
31
)
32

33
const ReportLive = Layer.effect(
34
  Report,
35
  Effect.gen(function* () {
36
    const db = yield* Database
37
    return {
38
      generate: (sql) =>
39
        Effect.gen(function* () {
40
          const rows = yield* db.query(sql)
41
          return rows.join(", ")
42
        }),
43
    }
44
  })
45
)
46

47
const DatabaseWithConfig = DatabaseLive.pipe(Layer.provide(ConfigLive))
48

49
//      ┌─── Layer<Api | Report | Database, never, never>
50
//      ▼
51
const AppLayer = Layer.mergeAll(
52
  ApiLive.pipe(Layer.provide(DatabaseWithConfig)),
53
  ReportLive.pipe(Layer.provide(DatabaseWithConfig)),
54
  DatabaseWithConfig
55
)

Config and Database are each constructed exactly once. Api, Report, and any code that yields Database directly all share the same Database instance, which itself shares the same Config.

Common Pitfalls

1, Confusing Layer.merge with Layer.provide. merge combines independents. provide satisfies a dependency.

If A needs B, Layer.merge(A, B) leaves B in A’s RIn, you must use A.pipe(Layer.provide(B)).

2, Duplicating a “shared” layer. Two Layer.sync(Tag, factory) calls produce two separate services. Bind the layer to a const and reuse the value.

3, Wrong order for Layer.provide. The receiver pipes into Layer.provide with its dependency: UserServiceLive.pipe(Layer.provide(DatabaseLive)). Reversing the relationship is a common source of confusing type errors.

4, Providing layers inside business logic. Wire once at the application boundary. Helpers should accept whatever R they need; the entry point provides every layer.

the assertion counts constructions.

The full test suite

The index.test.ts for this lesson, verbatim from steps/24-advanced-di/.

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

4
// =============================================================================
5
// 14 - Advanced DI: Composing the Dependency Graph
6
// =============================================================================
7
//
8
// Layer.provide      — wire a dependency into a layer that needs it
9
// Layer.provideMerge — wire and also expose the dependency downstream
10
// Layer.mergeAll     — combine many independent layers
11
//
12
// A Layer value referenced multiple times is constructed exactly once. Two
13
// separate Layer.sync calls with the same factory produce two services.
14

15
class Config extends Context.Service<Config, { readonly port: number; readonly dbUrl: string }>()("app/Config") {}
16

17
class Database extends Context.Service<Database, { readonly query: (sql: string) => Effect.Effect<ReadonlyArray<string>> }>()("app/Database") {}
18

19
class Cache extends Context.Service<Cache, { readonly get: (key: string) => Effect.Effect<string | null> }>()("app/Cache") {}
20

21
class Api extends Context.Service<Api, { readonly getUser: (id: string) => Effect.Effect<ReadonlyArray<string>> }>()("app/Api") {}
22

23
class Report extends Context.Service<Report, { readonly generate: (sql: string) => Effect.Effect<string> }>()("app/Report") {}
24

25
describe("14 - Advanced DI", () => {
26
  // @beat
27
  //   id: dag-composition
28
  //   shape: multi-todo
29
  //   title: Compose a multi-level dependency graph
30
  //   teaches: Layer.provide chains across layers; the receiver pipes the dependency it needs.
31
  //   hint: ApiLive.pipe(Layer.provide(DatabaseLive.pipe(Layer.provide(ConfigLive))))
32
  describe("Layer.provide", () => {
33
    it("satisfies a layer's RIn by piping in the dependency", async () => {
34
      const ConfigLive = Layer.succeed(Config, {
35
        port: 3000,
36
        dbUrl: "postgres://localhost",
37
      })
38

39
      const DatabaseLive = Layer.effect(
40
        Database,
41
        Effect.gen(function* () {
42
          const { dbUrl } = yield* Config
43
          return {
44
            query: (sql: string) => Effect.succeed([`${dbUrl}: ${sql}`]),
45
          }
46
        })
47
      )
48

49
      //      ┌─── Layer<Database, never, never>
50
      //      ▼
51
      const AppLayer = DatabaseLive.pipe(/* @stub */ Layer.provide(ConfigLive) /* @end */)
52

53
      const program = Effect.gen(function* () {
54
        const db = yield* Database
55
        return yield* db.query("SELECT 1")
56
      })
57

58
      const result = await Effect.runPromise(program.pipe(Effect.provide(AppLayer)))
59
      expect(result[0]).toContain("postgres://localhost")
60
    })
61

62
    it("chains across a multi-level dependency graph", async () => {
63
      const ConfigLive = Layer.succeed(Config, { port: 5432, dbUrl: "postgres://prod" })
64

65
      const DatabaseLive = Layer.effect(
66
        Database,
67
        Effect.gen(function* () {
68
          const { dbUrl } = yield* Config
69
          return {
70
            query: (sql: string) => Effect.succeed([`${dbUrl}: ${sql}`]),
71
          }
72
        })
73
      )
74

75
      const ApiLive = Layer.effect(
76
        Api,
77
        Effect.gen(function* () {
78
          const db = yield* Database
79
          return {
80
            getUser: (id: string) => db.query(`SELECT * FROM users WHERE id='${id}'`),
81
          }
82
        })
83
      )
84

85
      const AppLayer = ApiLive.pipe(
86
        /* @stub */ Layer.provide(DatabaseLive.pipe(Layer.provide(ConfigLive))) /* @end */
87
      )
88

89
      const program = Effect.gen(function* () {
90
        const api = yield* Api
91
        return yield* api.getUser("99")
92
      })
93

94
      const result = await Effect.runPromise(program.pipe(Effect.provide(AppLayer)))
95
      expect(result[0]).toContain("postgres://prod")
96
    })
97
  })
98
  // @end-beat
99

100
  // @beat
101
  //   id: merge-all
102
  //   shape: one-todo
103
  //   title: Bundle independents with Layer.mergeAll
104
  //   teaches: Layer.mergeAll combines many independent layers into a single AppLayer.
105
  //   hint: Layer.mergeAll(ConfigLive, DatabaseLive, CacheLive)
106
  describe("Layer.mergeAll", () => {
107
    it("combines independent layers into a single AppLayer", async () => {
108
      const ConfigLive = Layer.succeed(Config, { port: 3000, dbUrl: "test" })
109
      const DatabaseLive = Layer.succeed(Database, {
110
        query: (sql) => Effect.succeed([`db: ${sql}`]),
111
      })
112
      const CacheLive = Layer.succeed(Cache, {
113
        get: (key) => Effect.succeed(`cached: ${key}`),
114
      })
115

116
      const AppLayer = /* @stub */ Layer.mergeAll(ConfigLive, DatabaseLive, CacheLive) /* @end */
117

118
      const program = Effect.gen(function* () {
119
        const config = yield* Config
120
        const db = yield* Database
121
        const cache = yield* Cache
122

123
        const cached = yield* cache.get("u:1")
124
        const rows = yield* db.query("SELECT 1")
125

126
        return { port: config.port, cached, rows }
127
      })
128

129
      const result = await Effect.runPromise(program.pipe(Effect.provide(AppLayer)))
130
      expect(result.port).toBe(3000)
131
      expect(result.cached).toBe("cached: u:1")
132
      expect(result.rows).toEqual(["db: SELECT 1"])
133
    })
134
  })
135
  // @end-beat
136

137
  // @beat
138
  //   id: shared-instances
139
  //   shape: multi-todo
140
  //   title: Share a single construction across consumers
141
  //   teaches: A Layer value referenced multiple times is constructed exactly once; bind to a const and reuse.
142
  //   hint: name the layer once and pass the same value to every consumer
143
  describe("shared instances", () => {
144
    it("a Layer value referenced multiple times is constructed once", async () => {
145
      let constructions = 0
146

147
      const ConfigShared = /* @stub */ Layer.sync(Config, () => {
148
        constructions += 1
149
        return { port: 5432, dbUrl: "postgres://shared" }
150
      }) /* @end */
151

152
      const DatabaseLive = Layer.effect(
153
        Database,
154
        Effect.gen(function* () {
155
          const { dbUrl } = yield* Config
156
          return {
157
            query: (sql: string) => Effect.succeed([`${dbUrl}: ${sql}`]),
158
          }
159
        })
160
      )
161

162
      const ApiLive = Layer.effect(
163
        Api,
164
        Effect.gen(function* () {
165
          const db = yield* Database
166
          return {
167
            getUser: (id: string) => db.query(`u=${id}`),
168
          }
169
        })
170
      )
171

172
      const AppLayer = ApiLive.pipe(
173
        Layer.provide(DatabaseLive.pipe(Layer.provide(ConfigShared)))
174
      )
175

176
      const program = Effect.gen(function* () {
177
        const api = yield* Api
178
        return yield* api.getUser("5")
179
      })
180

181
      await Effect.runPromise(program.pipe(Effect.provide(AppLayer)))
182
      expect(constructions).toBe(1)
183
    })
184

185
    it("two consumers of one Database layer share the same instance", async () => {
186
      let dbConstructions = 0
187

188
      const DatabaseShared = Layer.sync(Database, () => {
189
        dbConstructions += 1
190
        return {
191
          query: (sql: string) => Effect.succeed([`row: ${sql}`]),
192
        }
193
      })
194

195
      const ApiLive = Layer.effect(
196
        Api,
197
        Effect.gen(function* () {
198
          const db = yield* Database
199
          return { getUser: (id: string) => db.query(`u=${id}`) }
200
        })
201
      )
202

203
      const ReportLive = Layer.effect(
204
        Report,
205
        Effect.gen(function* () {
206
          const db = yield* Database
207
          return {
208
            generate: (sql: string) =>
209
              Effect.gen(function* () {
210
                const rows = yield* db.query(sql)
211
                return rows.join(", ")
212
              }),
213
          }
214
        })
215
      )
216

217
      const AppLayer = /* @stub */ Layer.mergeAll(
218
        ApiLive.pipe(Layer.provide(DatabaseShared)),
219
        ReportLive.pipe(Layer.provide(DatabaseShared)),
220
        DatabaseShared
221
      ) /* @end */
222

223
      const program = Effect.gen(function* () {
224
        const api = yield* Api
225
        const report = yield* Report
226
        const db = yield* Database
227

228
        yield* api.getUser("1")
229
        yield* report.generate("SELECT 1")
230
        yield* db.query("SELECT 2")
231
      })
232

233
      await Effect.runPromise(program.pipe(Effect.provide(AppLayer)))
234
      expect(dbConstructions).toBe(1)
235
    })
236
  })
237
  // @end-beat
238

239
  // @beat
240
  //   id: wire-three-services
241
  //   shape: from-scratch
242
  //   title: Wire a three-service application from scratch
243
  //   teaches: Layer.provide chains dependencies across layers; Layer.mergeAll bundles independent layers; combining both produces an AppLayer the runner can use directly.
244
  //   hint: DatabaseTest needs ConfigTest wired via Layer.provide; ApiTest needs DatabaseTest; then bundle with Layer.mergeAll or a final Layer.provide chain
245

246
  describe("capstone: three-service graph", () => {
247
    it("builds an AppLayer that satisfies Api, Database, and Config from scratch", async () => {
248
      const ConfigTest = Layer.succeed(Config, { port: 3000, dbUrl: "postgres://test" })
249

250
      const DatabaseTest = Layer.effect(
251
        Database,
252
        Effect.gen(function* () {
253
          const { dbUrl } = yield* Config
254
          return {
255
            query: (sql: string) => Effect.succeed([`${dbUrl}: ${sql}`]),
256
          }
257
        }),
258
      )
259

260
      const ApiTest = Layer.effect(
261
        Api,
262
        Effect.gen(function* () {
263
          const db = yield* Database
264
          return {
265
            getUser: (id: string) => db.query(`SELECT * FROM users WHERE id='${id}'`),
266
          }
267
        }),
268
      )
269

270
      // Your turn: build AppLayer so the program below runs without providing anything else.
271
      // DatabaseTest requires Config; ApiTest requires Database.
272
      //
273
      //      ┌─── Layer<Api, never, never>
274
      //      ▼
275
      const AppLayer = /* @stub */ ApiTest.pipe(
276
        Layer.provide(DatabaseTest.pipe(Layer.provide(ConfigTest))),
277
      ) /* @end */
278

279
      const program = Effect.gen(function* () {
280
        const api = yield* Api
281
        return yield* api.getUser("42")
282
      })
283

284
      const result = await Effect.runPromise(program.pipe(Effect.provide(AppLayer)))
285
      expect(result[0]).toContain("postgres://test")
286
      expect(result[0]).toContain("42")
287
    })
288
  })
289
  // @end-beat
290
})

04·02Advanced DI

24 - Advanced DI: Composing the Dependency Graph

What you’ll work through

Layers as a DAG

`Layer.provide`: Wire a Dependency

`Layer.provideMerge`: Wire and Expose

`Layer.mergeAll`: Combine Independents

Shared Instances

Wiring three services into one `AppLayer`

A Full Example

Common Pitfalls

See Also

The full test suite

04·02Advanced DI

24 - Advanced DI: Composing the Dependency Graph

What you’ll work through

Layers as a DAG

Layer.provide: Wire a Dependency

Layer.provideMerge: Wire and Expose

Layer.mergeAll: Combine Independents

Shared Instances

Wiring three services into one AppLayer

A Full Example

Common Pitfalls

See Also

The full test suite

`Layer.provide`: Wire a Dependency

`Layer.provideMerge`: Wire and Expose

`Layer.mergeAll`: Combine Independents

Wiring three services into one `AppLayer`