55 - The `use` Pattern: Wrapping Wide Clients

Previous · Next

Some clients (pg, fs, s3) expose dozens of methods. Wrapping each one in a service method is tedious and rigid.

The use pattern exposes a single entry point, service.use, that accepts a callback over the raw client. The service still owns the resource, error mapping, timeouts, and cancellation; callers borrow the client for one operation at a time.

What you’ll work through

index.test.ts contains three beats: declaring a service Tag whose only method is use, implementing the Layer that wires in the underlying client, and consuming service.use(client => …) from business code.

By the end you should reach for use whenever the underlying client has more methods than your service interface should expose — every Postgres, filesystem, or S3 wrapper is a candidate.

The Pattern

1
Explicit wrapping (every method enumerated):
2
  UserService
3
    ├── findById, findByName, create, update, delete, ...
4

5
use pattern (one entry point):
6
  FileClient
7
    └── use(fn): Effect<A, FileClientError>
8
                  │
9
                  └── service injects the raw client and an AbortSignal
10
                      service maps thrown errors into FileClientError

The raw client never leaves the service. Errors converge on a single tagged type.

Adding a timeout or a logger means changing one place.

Defining a `use`-style Service

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

3
class FileClientError extends Data.TaggedError("FileClientError")<{
4
  readonly cause: unknown
5
}> {}
6

7
type FileModule = {
8
  readonly readFile: (path: string, signal: AbortSignal) => Promise<string>
9
  readonly writeFile: (path: string, contents: string, signal: AbortSignal) => Promise<void>
10
}
11

12
//      ┌─── Context.Service for the service
13
//      ▼
14
class FileClient extends Context.Service<FileClient, {
15
    readonly use: <A>(
16
      fn: (fileModule: FileModule, signal: AbortSignal) => Promise<A>,
17
    ) => Effect.Effect<A, FileClientError>
18
  }>()("FileClient") {}

Details

The signature is the contract. use takes a function that receives the raw module and an AbortSignal, returns a Promise<A>, and surfaces failures through FileClientError.

Implementing `use`

1
const makeFileClient = (fileModule: FileModule) =>
2
  Layer.succeed(FileClient, {
3
    use: <A>(fn: (fileModule: FileModule, signal: AbortSignal) => Promise<A>) =>
4
      Effect.tryPromise({
5
        try: (signal) => fn(fileModule, signal),
6
        catch: (cause) => new FileClientError({ cause }),
7
      }),
8
  })

Details

Effect.tryPromise provides the AbortSignal linked to fiber interruption. When the fiber is interrupted, the signal aborts, and the underlying client (any client that respects AbortSignal) cancels its work.

When to Use

When the client has 10+ methods you might reach for, or when the surface evolves over time. For narrow services with two or three methods, prefer explicit wrappers.

Consuming `use`

1
//      ┌─── Effect<number, FileClientError, FileClient>
2
//      ▼
3
const copyFile = (from: string, to: string) =>
4
  Effect.gen(function* () {
5
    const fileClient = yield* FileClient
6
    const contents = yield* fileClient.use((fs, signal) => fs.readFile(from, signal))
7
    yield* fileClient.use((fs, signal) => fs.writeFile(to, contents, signal))
8
    return contents.length
9
  })

Callers never see the raw FileModule. They see only FileClient, and every error converges on FileClientError.

Adding Cross-Cutting Concerns

1
const makeFileClient = (fileModule: FileModule) =>
2
  Layer.succeed(FileClient, {
3
    use: <A>(fn: (fileModule: FileModule, signal: AbortSignal) => Promise<A>) =>
4
      Effect.tryPromise({
5
        try: (signal) => fn(fileModule, signal),
6
        catch: (cause) => new FileClientError({ cause }),
7
      }).pipe(
8
        Effect.timeout("5 seconds"),
9
        Effect.mapError((cause) => new FileClientError({ cause })),
10
      ),
11
  })

Every call gets the timeout. Add logging, retries, or rate limits the same way.

Common Pitfalls

1, Using use for a tiny surface. If you have three methods, write them. The use pattern earns its keep on broad clients, not narrow ones.

2, Mapping errors inside the callback. Let the service do it. The callback returns the raw Promise; the service catches and tags.

Duplicating that work in every callback defeats the point.

3, Ignoring the AbortSignal. Many client libraries respect { signal }. Pass it through, or interruption stops at the Effect boundary and the underlying request keeps running.

4, Constructing the client inside the layer body without acquireRelease. If the client owns a connection, attach a finalizer (step 46) so it closes on shutdown.

the lifecycle. - [ ] Consume `service.use(client => …)` from business code; the callback is the per-operation borrow.

The full test suite

The index.test.ts for this lesson, verbatim from steps/55-use-pattern/.

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

4
// =============================================================================
5
// 34 - The `use` Pattern
6
// =============================================================================
7
//
8
// A service exposes a single `use(fn)` entry point. The callback receives the
9
// raw client + an AbortSignal; the service owns error mapping and lifetime.
10

11
class FileClientError extends Data.TaggedError("FileClientError")<{
12
  readonly cause: unknown
13
}> {}
14

15
type FileModule = {
16
  readonly readFile: (path: string, signal: AbortSignal) => Promise<string>
17
  readonly writeFile: (path: string, contents: string, signal: AbortSignal) => Promise<void>
18
}
19

20
// @beat
21
//   id: declare-tag
22
//   shape: one-todo
23
//   title: Declare a use-style service Tag
24
//   teaches: A use-style service exposes a single use(fn) method that borrows the raw client and an AbortSignal.
25
//   hint: use Context.Service with a single `use` method whose callback receives (fileModule, signal) and returns a Promise<A>
26
class FileClient extends /* @stub */ Context.Service<
27
  FileClient,
28
  {
29
    readonly use: <A>(
30
      fn: (fileModule: FileModule, signal: AbortSignal) => Promise<A>,
31
    ) => Effect.Effect<A, FileClientError>
32
  }
33
>()("FileClient") /* @end */ {}
34
// @end-beat
35

36
// @beat
37
//   id: implement-layer
38
//   shape: one-todo
39
//   title: Implement use with tryPromise
40
//   teaches: Effect.tryPromise supplies an AbortSignal and maps thrown errors into a tagged service error.
41
//   hint: Layer.succeed with use: (fn) => Effect.tryPromise({ try: (signal) => fn(fileModule, signal), catch: ... })
42
const makeFileClient = (fileModule: FileModule) =>
43
  /* @stub */ Layer.succeed(FileClient, {
44
    use: <A>(fn: (fileModule: FileModule, signal: AbortSignal) => Promise<A>) =>
45
      Effect.tryPromise({
46
        try: (signal) => fn(fileModule, signal),
47
        catch: (cause) => new FileClientError({ cause }),
48
      }),
49
  }) /* @end */
50
// @end-beat
51

52
// @beat
53
//   id: consume-use
54
//   shape: one-todo
55
//   title: Consume the borrowed client
56
//   teaches: Callers borrow the raw client for one operation at a time through fileClient.use.
57
//   hint: yield* FileClient then call fileClient.use((fs, signal) => fs.readFile(from, signal))
58
const copyFile = (from: string, to: string) =>
59
  /* @stub */ Effect.gen(function* () {
60
    const fileClient = yield* FileClient
61
    const contents = yield* fileClient.use((fs, signal) => fs.readFile(from, signal))
62
    yield* fileClient.use((fs, signal) => fs.writeFile(to, contents, signal))
63
    return contents.length
64
  }) /* @end */
65
// @end-beat
66

67
describe("34 - use pattern", () => {
68
  describe("FileClient.use", () => {
69
    it("borrows the underlying client without exposing it", async () => {
70
      const writes: Record<string, string> = {}
71
      const fileModule: FileModule = {
72
        readFile: async () => "hello",
73
        writeFile: async (path, contents) => {
74
          writes[path] = contents
75
        },
76
      }
77

78
      const bytes = await Effect.runPromise(
79
        copyFile("a.txt", "b.txt").pipe(Effect.provide(makeFileClient(fileModule))),
80
      )
81

82
      expect(bytes).toBe(5)
83
      expect(writes["b.txt"]).toBe("hello")
84
    })
85

86
    it("maps thrown Promise errors into the tagged service error", async () => {
87
      const fileModule: FileModule = {
88
        readFile: async () => {
89
          throw new Error("permission denied")
90
        },
91
        writeFile: async () => undefined,
92
      }
93

94
      const exit = await Effect.runPromiseExit(
95
        copyFile("a.txt", "b.txt").pipe(Effect.provide(makeFileClient(fileModule))),
96
      )
97

98
      expect(exit._tag).toBe("Failure")
99
      if (exit._tag === "Failure" && exit.cause.reasons[0]?._tag === "Fail") {
100
        expect(exit.cause.reasons[0].error._tag).toBe("FileClientError")
101
      }
102
    })
103
  })
104
})

10·05Use Pattern

55 - The `use` Pattern: Wrapping Wide Clients

What you’ll work through

The Pattern

Defining a `use`-style Service

Implementing `use`

Consuming `use`

Adding Cross-Cutting Concerns

Common Pitfalls

See Also

The full test suite

10·05Use Pattern

55 - The use Pattern: Wrapping Wide Clients

What you’ll work through

The Pattern

Defining a use-style Service

Implementing use

Consuming use

Adding Cross-Cutting Concerns

Common Pitfalls

See Also

The full test suite

55 - The `use` Pattern: Wrapping Wide Clients

Defining a `use`-style Service

Implementing `use`

Consuming `use`