22 - Layers: Building Services

Previous · Next

A Layer<ROut, E, RIn> is a recipe for constructing one or more services. It declares what it provides (ROut), what it requires (RIn), and how construction can fail (E).

Layers compose: you wire dependencies, merge independent services, and provide one top-level AppLayer at the application boundary.

What you’ll work through

index.test.ts walks through the three Layer constructors (succeed, sync, effect), then the two composition operators (merge, provide), and finishes with mergeAll for three-or-more services. Each beat builds a small service graph and runs a program against it.

By the end you should be able to look at any Effect<A, E, R> and answer: which Layers do I need to satisfy R, and in what order do they compose?

What a Layer Is

1
                 Layer<ROut, E, RIn>
2
                       │   │   │
3
                       │   │   └── Services consumed during construction
4
                       │   └────── Errors construction can produce
5
                       └────────── Services produced by this layer

Three constructors cover almost every case: Layer.succeed for a static value, Layer.sync for a lazy synchronous factory, and Layer.effect for a constructor that itself runs as an Effect (async, fallible, may use other services).

1
  ConfigLive ────────────┐
2
                         ▼
3
                  DatabaseLive (needs Config)
4
                         │
5
                         ▼
6
             UserServiceLive (needs Database)
7
                         │
8
                         ▼
9
                     AppLayer  (RIn = never)
10
                         │
11
                         ▼
12
              Effect.provide(AppLayer)

Effect resolves the graph at startup, constructing each service exactly once and sharing the instance with every dependent.

`Layer.succeed`

Creates a Layer from a pre-built implementation. No construction effect, no dependencies.

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

3
declare const Logger: Context.Service<Logger, { log: (msg: string) => Effect.Effect<void> }>
4

5
//      ┌─── Layer<Logger, never, never>
6
//      ▼
7
const LoggerLive = Layer.succeed(Logger, {
8
  log: (msg) => Effect.sync(() => console.log(msg)),
9
})

When to Use

When the implementation is a value you already have, a constant object, a closure captured from the surrounding scope, a test double.

Your turn wrap a pre-built `Logger` value with `Layer.succeed` and provide it to the program.

`Layer.sync`

Creates a Layer from a lazy synchronous factory. The factory runs once on first construction.

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

3
//      ┌─── Layer<Logger, never, never>
4
//      ▼
5
const InMemoryLogger = Layer.sync(Logger, () => {
6
  const buffer: Array<string> = []
7
  return {
8
    log: (msg) => Effect.sync(() => buffer.push(msg)),
9
  }
10
})

Details

Layer.sync differs from Layer.succeed in laziness: the factory is invoked at construction time, allowing per-construction state (a fresh buffer, a counter). The service itself is still synchronously built, no Effect runs.

When to Use

When the service captures fresh mutable state that must be created per layer instantiation, not shared at module load time.

Your turn use `Layer.sync` so the factory body runs exactly once and the construction counter advances by one.

`Layer.effect`

Creates a Layer from an Effect. Construction can await Promises, fail with typed errors, and consume other services.

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

3
//      ┌─── Layer<Database, ConnectionError, Config>
4
//      ▼
5
const DatabaseLive = Layer.effect(
6
  Database,
7
  Effect.gen(function* () {
8
    const config = yield* Config
9
    const connection = yield* openConnection(config.url)
10
    return {
11
      query: (sql: string) => runQuery(connection, sql),
12
    }
13
  })
14
)

Details

yield* Config inside the constructor adds Config to the Layer’s RIn. Any error the constructor can fail with appears in E.

This is the only constructor that can produce non-trivial RIn or E.

When to Use

Any service whose construction itself is effectful, opening a connection pool, reading configuration, registering finalizers (use Layer.effect for the last case, see step 37).

Your turn build `UserService` with `Layer.effect`, yielding `Logger` during construction, then wire it with `Layer.provide`.

Composing Layers

`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 layer’s RIn, removing it from the result’s RIn.

`Layer.provideMerge`: wire and expose

1
import { Layer } from "effect"
2

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

Layer.provideMerge keeps the wired-in services in the output, so callers can use them directly.

`Layer.merge` and `Layer.mergeAll`: combine independents

1
import { Layer } from "effect"
2

3
const AppLayer = Layer.mergeAll(LoggerLive, DatabaseWithConfig, CacheLive)

merge and mergeAll combine services that do not depend on each other. For services with dependencies between them, use Layer.provide first.

Your turn use `Layer.merge` to combine independent `Logger`/`Database` test layers, then `Layer.provide` to wire `Config` into `DatabaseLive`.

`Layer.mergeAll` for three or more independent layers

Layer.merge takes two layers. Once you have three or more independent services to combine into an application layer, reach for Layer.mergeAll — it’s the variadic form and reads better than a chain of merges.

1
import { Layer } from "effect"
2

3
//      ┌─── Layer<Logger | Database | Config, never, never>
4
//      ▼
5
const AppLayer = Layer.mergeAll(LoggerTest, DatabaseTest, ConfigLive)
6

7
const program = Effect.gen(function* () {
8
  const logger = yield* Logger
9
  const db = yield* Database
10
  const config = yield* Config
11
  yield* logger.log(config.dbUrl)
12
  return yield* db.query("SELECT 1")
13
})
14

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

The arguments to mergeAll must be independent — none of them should depend on services produced by another in the list. For services that do have dependencies on each other, wire them with Layer.provide first, then hand the resulting layer to mergeAll.

Your turn combine three independent layers (`LoggerTest`, `DatabaseTest`, `ConfigLive`) into a single `AppLayer` and provide it once to the program.

A Full Example

A UserService that depends on a Logger and a Database, with Database itself depending on Config.

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

3
class Config extends Context.Service<Config, { dbUrl: string }>()("app/Config") {}
4
class Logger extends Context.Service<Logger, { log: (msg: string) => Effect.Effect<void> }>()("app/Logger") {}
5
class Database extends Context.Service<Database, { query: (sql: string) => Effect.Effect<Array<string>> }>()("app/Database") {}
6
class UserService extends Context.Service<UserService, { getUser: (id: string) => Effect.Effect<{ id: string; name: string }> }>()("app/UserService") {}
7

8
const ConfigLive = Layer.succeed(Config, { dbUrl: "postgres://localhost" })
9
const LoggerLive = Layer.succeed(Logger, {
10
  log: (msg) => Effect.sync(() => console.log(msg)),
11
})
12

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

23
const UserServiceLive = Layer.effect(
24
  UserService,
25
  Effect.gen(function* () {
26
    const logger = yield* Logger
27
    const db = yield* Database
28
    return {
29
      getUser: (id) =>
30
        Effect.gen(function* () {
31
          yield* logger.log(`fetch ${id}`)
32
          const rows = yield* db.query(`SELECT * FROM users WHERE id = '${id}'`)
33
          return { id, name: rows[0] ?? "unknown" }
34
        }),
35
    }
36
  })
37
)
38

39
//      ┌─── Layer<UserService, never, never>
40
//      ▼
41
const AppLayer = UserServiceLive.pipe(
42
  Layer.provide(
43
    Layer.mergeAll(
44
      LoggerLive,
45
      DatabaseLive.pipe(Layer.provide(ConfigLive))
46
    )
47
  )
48
)

Effect.provide(AppLayer) at the entry point satisfies every requirement in one call.

Rules of thumb

Layers are values. Compose with Layer.merge (parallel) and Layer.provide / Layer.provideMerge (dependency); pass them around like any other value.
Effects depend on services; services depend on Layers. Don’t conflate the two. The R channel asks for services, and Effect.provide(layer) satisfies the ask.
Build the runtime once at the program edge. Inside business logic, effects should require services, not assemble them.

Common Pitfalls

1, Providing layers inside business logic. Layers should be wired at the application boundary, not inside helpers. Otherwise each call site rebuilds the graph.

2, Confusing Layer.succeed with Layer.sync. succeed takes a value; sync takes a factory. Passing a factory to succeed stores the function as the service.

3, Using Layer.merge to satisfy dependencies. merge only combines independent layers. If A needs B, use A.pipe(Layer.provide(B)).

4, Re-declaring shared layers. Defining Layer.sync(Database, makeDb) twice produces two separate Database instances. Name the layer once and reuse the value.

in each beat. - [ ] Work through the three constructors first: `Layer.succeed` (eager value), `Layer.sync` (lazy factory — note the construction-count assertion), `Layer.effect` (constructor that uses other services). - [ ] Then the two composition operators: `Layer.merge` for siblings, `Layer.provide` for "A depends on B". Watch the `RIn` parameter in the type comment collapse to `never` after `Layer.provide`. - [ ] Finish with `Layer.mergeAll` for three-or-more independents — that's the form an `AppLayer` usually takes.

The full test suite

The index.test.ts for this lesson, verbatim from steps/22-layers/.

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

4
// =============================================================================
5
// 12 - Layers
6
// =============================================================================
7
//
8
// A Layer is a recipe for constructing services. Layer.succeed wraps a value,
9
// Layer.sync wraps a lazy synchronous factory, Layer.effect wraps an effectful
10
// constructor. Layer.provide wires dependencies; Layer.merge/mergeAll combines
11
// independent layers.
12

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

15
class Logger extends Context.Service<Logger, {
16
    readonly log: (message: string) => Effect.Effect<void>
17
    readonly getMessages: () => Effect.Effect<ReadonlyArray<string>>
18
  }>()("app/Logger") {}
19

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

24
class UserService extends Context.Service<UserService, {
25
    readonly getUser: (id: string) => Effect.Effect<{ id: string; name: string }>
26
  }>()("app/UserService") {}
27

28
describe("12 - Layers", () => {
29
  // @beat
30
  //   id: layer-succeed
31
  //   shape: one-todo
32
  //   title: Wrap a pre-built implementation with Layer.succeed
33
  //   teaches: Layer.succeed lifts an existing service value into a Layer with no construction effect.
34
  //   hint: Layer.succeed(Tag, implementation)
35
  describe("Layer.succeed", () => {
36
    it("wraps a pre-built implementation", async () => {
37
      const messages: Array<string> = []
38

39
      const LoggerLive = /* @stub */ Layer.succeed(Logger, {
40
        log: (msg) =>
41
          Effect.sync(() => {
42
            messages.push(msg)
43
          }),
44
        getMessages: () => Effect.succeed(messages),
45
      }) /* @end */
46

47
      const program = Effect.gen(function* () {
48
        const logger = yield* Logger
49
        yield* logger.log("hello")
50
        yield* logger.log("world")
51
        return yield* logger.getMessages()
52
      })
53

54
      const result = await Effect.runPromise(program.pipe(Effect.provide(LoggerLive)))
55
      expect(result).toEqual(["hello", "world"])
56
    })
57
  })
58
  // @end-beat
59

60
  // @beat
61
  //   id: layer-sync
62
  //   shape: one-todo
63
  //   title: Build per-construction state with Layer.sync
64
  //   teaches: Layer.sync runs a lazy factory once per construction; fresh state is captured at startup.
65
  //   hint: Layer.sync(Tag, factory) — the factory returns the service
66
  describe("Layer.sync", () => {
67
    it("calls the factory lazily, once, with fresh per-construction state", async () => {
68
      let constructions = 0
69

70
      const DatabaseTest = /* @stub */ Layer.sync(Database, () => {
71
        constructions += 1
72
        return {
73
          query: (sql: string) => Effect.succeed([`row for ${sql}`]),
74
        }
75
      }) /* @end */
76

77
      const program = Effect.gen(function* () {
78
        const db = yield* Database
79
        const a = yield* db.query("a")
80
        const b = yield* db.query("b")
81
        return [a, b]
82
      })
83

84
      await Effect.runPromise(program.pipe(Effect.provide(DatabaseTest)))
85
      expect(constructions).toBe(1)
86
    })
87
  })
88
  // @end-beat
89

90
  // @beat
91
  //   id: layer-effect
92
  //   shape: multi-todo
93
  //   title: Build a service that needs another service with Layer.effect
94
  //   teaches: Layer.effect lets the constructor yield* other services; Layer.provide wires the dependency.
95
  //   hint: Layer.effect(Tag, Effect.gen(...)) and then pipe Layer.provide(dependency)
96
  describe("Layer.effect", () => {
97
    it("constructs a service that depends on another service", async () => {
98
      const captured: Array<string> = []
99

100
      const LoggerTest = Layer.succeed(Logger, {
101
        log: (msg) =>
102
          Effect.sync(() => {
103
            captured.push(msg)
104
          }),
105
        getMessages: () => Effect.succeed(captured),
106
      })
107

108
      //      ┌─── Layer<UserService, never, Logger>
109
      //      ▼
110
      const UserServiceTest = /* @stub */ Layer.effect(
111
        UserService,
112
        Effect.gen(function* () {
113
          const logger = yield* Logger
114
          return {
115
            getUser: (id) =>
116
              Effect.gen(function* () {
117
                yield* logger.log(`build ${id}`)
118
                return { id, name: "Alice" }
119
              }),
120
          }
121
        })
122
      ) /* @end */
123

124
      const AppLayer = UserServiceTest.pipe(/* @stub */ Layer.provide(LoggerTest) /* @end */)
125

126
      const program = Effect.gen(function* () {
127
        const users = yield* UserService
128
        return yield* users.getUser("42")
129
      })
130

131
      const result = await Effect.runPromise(program.pipe(Effect.provide(AppLayer)))
132
      expect(result).toEqual({ id: "42", name: "Alice" })
133
      expect(captured).toEqual(["build 42"])
134
    })
135
  })
136
  // @end-beat
137

138
  // @beat
139
  //   id: merge-vs-provide
140
  //   shape: multi-todo
141
  //   title: Merge independents, provide dependencies
142
  //   teaches: Layer.merge combines unrelated services; Layer.provide satisfies a dependency.
143
  //   hint: use Layer.merge for siblings; pipe Layer.provide to wire a child's input
144
  describe("composing layers", () => {
145
    it("Layer.merge combines independent services", async () => {
146
      const messages: Array<string> = []
147

148
      const LoggerTest = Layer.succeed(Logger, {
149
        log: (msg) =>
150
          Effect.sync(() => {
151
            messages.push(msg)
152
          }),
153
        getMessages: () => Effect.succeed(messages),
154
      })
155

156
      const DatabaseTest = Layer.sync(Database, () => ({
157
        query: () => Effect.succeed(["user1", "user2"]),
158
      }))
159

160
      const AppLayer = /* @stub */ Layer.merge(LoggerTest, DatabaseTest) /* @end */
161

162
      const program = Effect.gen(function* () {
163
        const logger = yield* Logger
164
        const db = yield* Database
165
        yield* logger.log("query")
166
        return yield* db.query("SELECT *")
167
      })
168

169
      const result = await Effect.runPromise(program.pipe(Effect.provide(AppLayer)))
170
      expect(result).toEqual(["user1", "user2"])
171
      expect(messages).toEqual(["query"])
172
    })
173

174
    it("Layer.provide wires a dependency into a layer that requires it", async () => {
175
      const ConfigLive = Layer.succeed(Config, { dbUrl: "postgres://test" })
176

177
      const DatabaseLive = Layer.effect(
178
        Database,
179
        Effect.gen(function* () {
180
          const { dbUrl } = yield* Config
181
          return {
182
            query: (sql: string) => Effect.succeed([`${dbUrl}: ${sql}`]),
183
          }
184
        })
185
      )
186

187
      //      ┌─── Layer<Database, never, never>
188
      //      ▼
189
      const DatabaseWithConfig = DatabaseLive.pipe(/* @stub */ Layer.provide(ConfigLive) /* @end */)
190

191
      const program = Effect.gen(function* () {
192
        const db = yield* Database
193
        return yield* db.query("SELECT 1")
194
      })
195

196
      const result = await Effect.runPromise(
197
        program.pipe(Effect.provide(DatabaseWithConfig))
198
      )
199

200
      expect(result[0]).toContain("postgres://test")
201
    })
202
  })
203
  // @end-beat
204

205
  // @beat
206
  //   id: merge-all
207
  //   shape: one-todo
208
  //   title: Combine N independent layers with Layer.mergeAll
209
  //   teaches: Layer.mergeAll is the variadic form of Layer.merge — use it when composing three or more independent services into one application layer.
210
  //   hint: Layer.mergeAll(LoggerTest, DatabaseTest, ConfigLive)
211
  describe("Layer.mergeAll", () => {
212
    it("combines three independent layers into one", async () => {
213
      const messages: Array<string> = []
214

215
      const LoggerTest = Layer.succeed(Logger, {
216
        log: (msg) => Effect.sync(() => { messages.push(msg) }),
217
        getMessages: () => Effect.succeed(messages),
218
      })
219

220
      const DatabaseTest = Layer.sync(Database, () => ({
221
        query: () => Effect.succeed(["row"]),
222
      }))
223

224
      const ConfigLive = Layer.succeed(Config, { dbUrl: "postgres://test" })
225

226
      //      ┌─── Layer<Logger | Database | Config, never, never>
227
      //      ▼
228
      const AppLayer = /* @stub */ Layer.mergeAll(LoggerTest, DatabaseTest, ConfigLive) /* @end */
229

230
      const program = Effect.gen(function* () {
231
        const logger = yield* Logger
232
        const db = yield* Database
233
        const config = yield* Config
234
        yield* logger.log(config.dbUrl)
235
        return yield* db.query("SELECT 1")
236
      })
237

238
      const result = await Effect.runPromise(program.pipe(Effect.provide(AppLayer)))
239
      expect(result).toEqual(["row"])
240
      expect(messages).toEqual(["postgres://test"])
241
    })
242
  })
243
  // @end-beat
244
})

04·02Layers

22 - Layers: Building Services

What you’ll work through

What a Layer Is

`Layer.succeed`

`Layer.sync`

`Layer.effect`

Composing Layers

`Layer.provide`: wire a dependency

`Layer.provideMerge`: wire and expose

`Layer.merge` and `Layer.mergeAll`: combine independents

`Layer.mergeAll` for three or more independent layers

A Full Example

Rules of thumb

Common Pitfalls

See Also

The full test suite

04·02Layers

22 - Layers: Building Services

What you’ll work through

What a Layer Is

Layer.succeed

Layer.sync

Layer.effect

Composing Layers

Layer.provide: wire a dependency

Layer.provideMerge: wire and expose

Layer.merge and Layer.mergeAll: combine independents

Layer.mergeAll for three or more independent layers

A Full Example

Rules of thumb

Common Pitfalls

See Also

The full test suite

`Layer.succeed`

`Layer.sync`

`Layer.effect`

`Layer.provide`: wire a dependency

`Layer.provideMerge`: wire and expose

`Layer.merge` and `Layer.mergeAll`: combine independents

`Layer.mergeAll` for three or more independent layers