50a - Capstone: SWAPI API Client

Previous · Next

A real API call lights up every piece of Effect you’ve learned so far. This capstone wires Config (25), Schema (18-20), Context.Service (23), typed errors (04, 09), Layer composition (22, 24), ConfigProvider.fromUnknown for tests (25, 29), and ManagedRuntime (60) into one client — pointed at SWAPI (the Star Wars API).

What you’ll work through

index.test.ts builds a SwapiClient service one beat at a time:

A HttpClient service abstracts fetch so tests can swap it without touching the network.
BuildSwapiUrl reads the base URL from Config — production gets it from process.env, tests inject it via ConfigProvider.fromUnknown.
SwapiClient.getPerson(id) returns Effect<Person, FetchError | JsonError | DecodeError | NotFoundError, …>. The return type is the spec.
Each error gets its own Data.TaggedError so Effect.catchTags({...}) is exhaustive — the compiler refuses to let you ignore a branch.
A ManagedRuntime composes SwapiClient.layer (which pulls in BuildSwapiUrl.layer via dependencies) so the test harness boots the whole graph once and reuses it across every it(...).

By the end you should be able to read SwapiClient.getPerson("1") and predict the four ways it can fail, the one service it needs (HttpClient), and the one config key it reads (SWAPI_BASE_URL).

Context.Service with `dependencies`

1
import { Effect } from "effect"
2

3
class SwapiClient extends Context.Service<SwapiClient>()("SwapiClient", {
4
  effect: Effect.gen(function* () {
5
    const url = yield* BuildSwapiUrl
6
    const http = yield* HttpClient
7
    return {
8
      getPerson: (id: string) => /* … */,
9
    }
10
  }),
11
  dependencies: [BuildSwapiUrl.layer, HttpClient.layer],
12
}) {}

Context.Service bakes the dependency graph into the service declaration. SwapiClient.layer is a Layer that automatically pulls in BuildSwapiUrl.layer and HttpClient.layer. The call site provides one layer; the rest is wired by tags.

Config from a map (no env vars in tests)

1
import { Config, ConfigProvider, Layer } from "effect"
2

3
const TestConfig = Layer.setConfigProvider(
4
  ConfigProvider.fromUnknown(new Map([["SWAPI_BASE_URL", "https://swapi.info/api"]])),
5
)

Tests inject configuration through a ConfigProvider, not through process.env. The BuildSwapiUrl service reads Config.string("SWAPI_BASE_URL") and doesn’t care whether the value came from a map or the environment — that’s the whole point of dependency injection at the config layer.

Four typed failure modes

1
import { Data } from "effect"
2

3
class FetchError extends Data.TaggedError("FetchError")<{ cause: unknown }> {}
4
class JsonError extends Data.TaggedError("JsonError")<{ cause: unknown }> {}
5
class NotFoundError extends Data.TaggedError("NotFoundError")<{ id: string }> {}
6
class DecodeError extends Data.TaggedError("DecodeError")<{ cause: unknown }> {}

fetch collapses every failure into a thrown promise. Effect makes them four distinct tagged classes:

FetchError — network or 5xx
NotFoundError — server responded 404
JsonError — body wasn’t valid JSON
DecodeError — JSON didn’t match Schema.Struct

The return type lists every one of them. There’s nothing else this function can do.

Schema as the wire contract

1
import { Schema } from "effect"
2

3
const Person = Schema.Struct({
4
  name: Schema.String,
5
  height: Schema.String,
6
  mass: Schema.String,
7
  birth_year: Schema.String,
8
})
9
type Person = typeof Person.Type

Schema.Struct parses untrusted JSON into a typed value. Effect.gen yields Schema.decodeUnknownEffect(Person)(json) directly; if the shape drifts on the server (Lucasfilm, please don’t), it’s a DecodeError in the return type, not a TypeError at runtime.

Exhaustive `catchTags`

1
const program = SwapiClient.getPerson("1").pipe(
2
  Effect.catchTags({
3
    FetchError:    (e) => Effect.succeed(`Network: ${e.cause}`),
4
    NotFoundError: (e) => Effect.succeed(`No such person: ${e.id}`),
5
    JsonError:     (e) => Effect.succeed(`Bad JSON: ${e.cause}`),
6
    DecodeError:   (e) => Effect.succeed(`Schema drift: ${e.cause}`),
7
  }),
8
)

Remove any one branch and the compiler tells you the unhandled tag remains in E. Add a branch that doesn’t exist and the compiler tells you it never fires. This is the payoff for typing errors: the call site is forced to enumerate them.

`ManagedRuntime` for the test harness

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

3
const TestLayer = Layer.mergeAll(SwapiClient.layer).pipe(
4
  Layer.provide(HttpClientTest),
5
  Layer.provide(TestConfig),
6
)
7

8
const runtime = ManagedRuntime.make(TestLayer)
9
const result = await runtime.runPromise(SwapiClient.getPerson("1"))

ManagedRuntime.make boots the layer graph once. Every runPromise reuses the same resolved services. In production, TestLayer becomes LiveLayer and HttpClientTest becomes HttpClientLive — the program in the middle doesn’t change.

Why SWAPI (and not Pokemon)

The TypeOnce course famously walks through this same construction with the Pokemon API. We use SWAPI deliberately — different domain, same shape of problem, so you can see the pattern rather than memorise the example. If you’ve done that course, this is the same machinery you already know; if you haven’t, you’ll find the Pokemon version a useful second reading.

The full test suite

The index.test.ts for this lesson, verbatim from steps/50a-swapi-api-client/.

1
import { describe, it, expect } from "vite-plus/test"
2
import {
3
  Config,
4
  ConfigProvider,
5
  Context,
6
  Data,
7
  Effect,
8
  Exit,
9
  Layer,
10
  ManagedRuntime,
11
  Schema,
12
} from "effect"
13

14
const providerFromMap = (entries: Map<string, string>) =>
15
  ConfigProvider.fromUnknown(Object.fromEntries(entries))
16

17
// =============================================================================
18
// 50a - Capstone: SWAPI API Client
19
// =============================================================================
20
//
21
// Composes: Context.Service with dependencies (23), Config + ConfigProvider (25),
22
//           Data.TaggedError (04), Schema.Struct (18), Layer composition (22),
23
//           ManagedRuntime (60), exhaustive catchTags (09).
24
//
25
// The function signature names every failure and every dependency:
26
//
27
//   SwapiClient.getPerson: (id: string) =>
28
//     Effect<Person, FetchError | NotFoundError | JsonError | DecodeError, SwapiClient>
29

30
// ---------- Errors ----------
31

32
class FetchError extends Data.TaggedError("FetchError")<{ readonly cause: unknown }> {}
33
class JsonError extends Data.TaggedError("JsonError")<{ readonly cause: unknown }> {}
34
class NotFoundError extends Data.TaggedError("NotFoundError")<{ readonly id: string }> {}
35
class DecodeError extends Data.TaggedError("DecodeError")<{ readonly cause: unknown }> {}
36

37
type SwapiError = FetchError | NotFoundError | JsonError | DecodeError
38

39
// ---------- Schema ----------
40

41
const Person = Schema.Struct({
42
  name: Schema.String,
43
  height: Schema.String,
44
  mass: Schema.String,
45
  birth_year: Schema.String,
46
})
47
type Person = typeof Person.Type
48

49
// ---------- HttpClient port (so tests don't hit the network) ----------
50

51
interface HttpResponse {
52
  readonly status: number
53
  readonly text: () => Promise<string>
54
}
55

56
class HttpClient extends Context.Service<HttpClient, { readonly get: (url: string) => Effect.Effect<HttpResponse, FetchError> }>()("HttpClient") {}
57

58
// ---------- Config service: reads SWAPI_BASE_URL ----------
59

60
class BuildSwapiUrl extends Context.Service<BuildSwapiUrl>()("BuildSwapiUrl", {
61
  make: Effect.gen(function* () {
62
    const base = yield* Config.string("SWAPI_BASE_URL")
63
    return (path: string) => `${base.replace(/\/$/, "")}${path}`
64
  }),
65
}) {
66
  static readonly layer = Layer.effect(this, this.make)
67
}
68

69
// ---------- The client ----------
70

71
class SwapiClient extends Context.Service<SwapiClient>()("SwapiClient", {
72
  make: Effect.gen(function* () {
73
    const buildUrl = yield* BuildSwapiUrl
74
    const http = yield* HttpClient
75

76
    const getPerson = (id: string): Effect.Effect<Person, SwapiError> =>
77
      Effect.gen(function* () {
78
        const response = yield* http.get(buildUrl(`/people/${id}`))
79
        if (response.status === 404) return yield* new NotFoundError({ id })
80
        if (response.status >= 400)
81
          return yield* new FetchError({ cause: `status ${response.status}` })
82

83
        const body = yield* Effect.tryPromise({
84
          try: () => response.text(),
85
          catch: (cause) => new FetchError({ cause }),
86
        })
87

88
        const parsed = yield* Effect.try({
89
          try: () => JSON.parse(body) as unknown,
90
          catch: (cause) => new JsonError({ cause }),
91
        })
92

93
        return yield* Schema.decodeUnknownEffect(Person)(parsed).pipe(
94
          Effect.mapError((cause) => new DecodeError({ cause })),
95
        )
96
      })
97

98
    return { getPerson } as const
99
  }),
100
}) {
101
  static readonly layer = Layer.effect(this, this.make).pipe(Layer.provide(BuildSwapiUrl.layer))
102
}
103

104
// ---------- Test layers ----------
105

106
const TestConfig = ConfigProvider.layer(
107
  providerFromMap(new Map([["SWAPI_BASE_URL", "https://swapi.info/api"]])),
108
)
109

110
const luke = {
111
  name: "Luke Skywalker",
112
  height: "172",
113
  mass: "77",
114
  birth_year: "19BBY",
115
}
116

117
function makeHttpStub(responses: Record<string, { status: number; body: string }>) {
118
  return Layer.succeed(HttpClient, {
119
    get: (url: string) =>
120
      Effect.gen(function* () {
121
        const r = responses[url]
122
        if (!r) return yield* new FetchError({ cause: `no stub for ${url}` })
123
        return { status: r.status, text: () => Promise.resolve(r.body) }
124
      }),
125
  })
126
}
127

128
const HappyHttp = makeHttpStub({
129
  "https://swapi.info/api/people/1": { status: 200, body: JSON.stringify(luke) },
130
  "https://swapi.info/api/people/999": { status: 404, body: "" },
131
  "https://swapi.info/api/people/garbage": { status: 200, body: "not json {" },
132
  "https://swapi.info/api/people/wrong-shape": {
133
    status: 200,
134
    body: JSON.stringify({ name: "Anakin" }),
135
  },
136
  "https://swapi.info/api/people/dead": { status: 502, body: "" },
137
})
138

139
// Merge BuildSwapiUrl.layer so beats that exercise it directly can resolve
140
// the service; SwapiClient.layer would otherwise hide it behind its own
141
// dependency graph.
142
const TestLayer = Layer.mergeAll(SwapiClient.layer, BuildSwapiUrl.layer).pipe(
143
  Layer.provide(HappyHttp),
144
  Layer.provide(TestConfig),
145
)
146

147
describe("50a - swapi api client", () => {
148
  // @beat
149
  //   id: service-shape
150
  //   shape: read-run
151
  //   title: A service that owns its dependency graph
152
  //   teaches: Context.Service with `dependencies: [...]` auto-provides every required layer when you supply only SwapiClient.layer.
153
  //   hint: SwapiClient.layer already pulls in BuildSwapiUrl.layer
154
  describe("service shape", () => {
155
    it("getPerson returns the parsed Person on a 200", async () => {
156
      const runtime = ManagedRuntime.make(TestLayer)
157
      const program = Effect.gen(function* () {
158
        const client = yield* SwapiClient
159
        return yield* client.getPerson("1")
160
      })
161
      const person = await runtime.runPromise(program)
162
      expect(person.name).toBe("Luke Skywalker")
163
      expect(person.birth_year).toBe("19BBY")
164
      await runtime.dispose()
165
    })
166
  })
167
  // @end-beat
168

169
  // @beat
170
  //   id: config-injection
171
  //   shape: read-run
172
  //   title: providerFromMap replaces process.env in tests
173
  //   teaches: BuildSwapiUrl reads Config.string("SWAPI_BASE_URL") which is injected through ConfigProvider, not the environment.
174
  //   hint: ConfigProvider.layer(providerFromMap(...))
175
  describe("config injection", () => {
176
    it("uses the SWAPI_BASE_URL provided by the test ConfigProvider", async () => {
177
      const runtime = ManagedRuntime.make(TestLayer)
178
      const program = Effect.gen(function* () {
179
        const buildUrl = yield* BuildSwapiUrl
180
        return buildUrl("/people/1")
181
      })
182
      const url = await runtime.runPromise(program)
183
      expect(url).toBe("https://swapi.info/api/people/1")
184
      await runtime.dispose()
185
    })
186
  })
187
  // @end-beat
188

189
  // @beat
190
  //   id: typed-errors
191
  //   shape: read-run
192
  //   title: Each failure mode is its own tagged class
193
  //   teaches: FetchError, NotFoundError, JsonError, DecodeError make every branch nameable in the type signature.
194
  //   hint: Exit.isFailure + Cause.findErrorOption
195
  describe("typed errors", () => {
196
    it("404 → NotFoundError", async () => {
197
      const runtime = ManagedRuntime.make(TestLayer)
198
      const exit = await runtime.runPromiseExit(
199
        Effect.gen(function* () {
200
          const client = yield* SwapiClient
201
          return yield* client.getPerson("999")
202
        }),
203
      )
204
      expect(Exit.isFailure(exit)).toBe(true)
205
      if (Exit.isFailure(exit)) {
206
        const err = exit.cause.reasons[0]?._tag === "Fail" ? exit.cause.reasons[0].error : null
207
        expect(err?._tag).toBe("NotFoundError")
208
        expect(err && "id" in err ? err.id : null).toBe("999")
209
      }
210
      await runtime.dispose()
211
    })
212

213
    it("502 → FetchError", async () => {
214
      const runtime = ManagedRuntime.make(TestLayer)
215
      const exit = await runtime.runPromiseExit(
216
        Effect.gen(function* () {
217
          const client = yield* SwapiClient
218
          return yield* client.getPerson("dead")
219
        }),
220
      )
221
      expect(Exit.isFailure(exit)).toBe(true)
222
      if (Exit.isFailure(exit) && exit.cause.reasons[0]?._tag === "Fail") {
223
        expect((exit.cause.reasons[0].error as { _tag: string })._tag).toBe("FetchError")
224
      }
225
      await runtime.dispose()
226
    })
227
  })
228
  // @end-beat
229

230
  // @beat
231
  //   id: schema-decode
232
  //   shape: read-run
233
  //   title: Schema.Struct is the wire contract
234
  //   teaches: A response missing required fields is a DecodeError, not a runtime TypeError elsewhere in the app.
235
  //   hint: Schema.decodeUnknownEffect returns Effect with a ParseError that we map to DecodeError
236
  describe("schema decode", () => {
237
    it("wrong shape → DecodeError", async () => {
238
      const runtime = ManagedRuntime.make(TestLayer)
239
      const exit = await runtime.runPromiseExit(
240
        Effect.gen(function* () {
241
          const client = yield* SwapiClient
242
          return yield* client.getPerson("wrong-shape")
243
        }),
244
      )
245
      expect(Exit.isFailure(exit)).toBe(true)
246
      if (Exit.isFailure(exit) && exit.cause.reasons[0]?._tag === "Fail") {
247
        expect((exit.cause.reasons[0].error as { _tag: string })._tag).toBe("DecodeError")
248
      }
249
      await runtime.dispose()
250
    })
251

252
    it("non-JSON body → JsonError", async () => {
253
      const runtime = ManagedRuntime.make(TestLayer)
254
      const exit = await runtime.runPromiseExit(
255
        Effect.gen(function* () {
256
          const client = yield* SwapiClient
257
          return yield* client.getPerson("garbage")
258
        }),
259
      )
260
      expect(Exit.isFailure(exit)).toBe(true)
261
      if (Exit.isFailure(exit) && exit.cause.reasons[0]?._tag === "Fail") {
262
        expect((exit.cause.reasons[0].error as { _tag: string })._tag).toBe("JsonError")
263
      }
264
      await runtime.dispose()
265
    })
266
  })
267
  // @end-beat
268

269
  // @beat
270
  //   id: catch-tags-exhaustive
271
  //   shape: read-run
272
  //   title: catchTags forces you to handle every failure
273
  //   teaches: Removing any branch leaves that tag in E; adding an impossible branch is a compile error.
274
  //   hint: Effect.catchTags({ FetchError, NotFoundError, JsonError, DecodeError })
275
  describe("catchTags exhaustive", () => {
276
    it("recovers every failure mode into a human-readable string", async () => {
277
      const runtime = ManagedRuntime.make(TestLayer)
278
      const describe1 = (id: string) =>
279
        Effect.gen(function* () {
280
          const client = yield* SwapiClient
281
          return yield* client.getPerson(id)
282
        }).pipe(
283
          Effect.map(() => "ok"),
284
          Effect.catchTags({
285
            FetchError: (e) => Effect.succeed(`network: ${String(e.cause)}`),
286
            NotFoundError: (e) => Effect.succeed(`missing: ${e.id}`),
287
            JsonError: () => Effect.succeed("bad json"),
288
            DecodeError: () => Effect.succeed("schema drift"),
289
          }),
290
        )
291

292
      const [ok, missing, bad, drift, net] = await Promise.all([
293
        runtime.runPromise(describe1("1")),
294
        runtime.runPromise(describe1("999")),
295
        runtime.runPromise(describe1("garbage")),
296
        runtime.runPromise(describe1("wrong-shape")),
297
        runtime.runPromise(describe1("dead")),
298
      ])
299
      expect(ok).toBe("ok")
300
      expect(missing).toBe("missing: 999")
301
      expect(bad).toBe("bad json")
302
      expect(drift).toBe("schema drift")
303
      expect(net.startsWith("network:")).toBe(true)
304
      await runtime.dispose()
305
    })
306
  })
307
  // @end-beat
308

309
  // @beat
310
  //   id: managed-runtime
311
  //   shape: read-run
312
  //   title: ManagedRuntime amortises the layer graph
313
  //   teaches: A single ManagedRuntime.make resolves SwapiClient once and reuses it across every runPromise — production wiring looks identical, just with a Live HttpClient.
314
  //   hint: ManagedRuntime.make(TestLayer); runtime.runPromise(...); runtime.dispose()
315
  describe("managed runtime", () => {
316
    it("reuses the same runtime across many calls", async () => {
317
      const runtime = ManagedRuntime.make(TestLayer)
318
      const calls = await Promise.all(
319
        Array.from({ length: 5 }, () =>
320
          runtime.runPromise(
321
            Effect.gen(function* () {
322
              const client = yield* SwapiClient
323
              return yield* client.getPerson("1")
324
            }),
325
          ),
326
        ),
327
      )
328
      expect(calls.every((p) => p.name === "Luke Skywalker")).toBe(true)
329
      await runtime.dispose()
330
    })
331
  })
332
  // @end-beat
333
})

09·03SWAPI API Client