49 - Capstone: Payment System

Previous · Next

Payments concentrate every difficulty Effect was built for: typed failures, idempotency, retries that distinguish transient from permanent errors, injected infrastructure, and a return type that names the full failure surface. This capstone wires the earlier lessons into one function whose signature tells you everything that can happen.

What you’ll work through

This is the first of two capstones: where the primitives from earlier steps — tagged errors (04, 15), Effect.gen (07), services and layers (21, 22), and retry schedules (31, 32) — combine into a single function. index.test.ts runs read-only beats over a createPayment function: happy path, validation rejection before any I/O, idempotency (cached hit, lock contention), provider error discrimination (hard vs soft fail with retry), and a check that PaymentError covers exactly five tags.

By the end you should be able to read the return type Effect<PaymentResult, PaymentError, DbService | ProviderService> and predict, without opening the body, every branch of the test file.

The Pipeline

1
createPayment(input)
2
  ├── validate          amount > 0, idemKey length ≥ 8        (ValidationError)
3
  ├── db.findByKey      already processed? return cached       (IdempotencyConflict)
4
  ├── db.acquireLock    concurrent request? reject             (IdempotencyConflict)
5
  ├── provider.charge   external API                          (ProviderHardFail | ProviderSoftFail)
6
  │     ├── timeout     5 seconds
7
  │     └── retry       exponential, soft fails only
8
  └── db.save           persist                                (PersistError)

Each branch corresponds to a typed error in E. Nothing else can fail.

The Signature

1
//      ┌─── Effect<PaymentResult, PaymentError, DbService | ProviderService>
2
//      ▼
3
declare function createPayment(input: {
4
  readonly amount: number
5
  readonly currency: string
6
  readonly idemKey: string
7
}): Effect.Effect<PaymentResult, PaymentError, DbService | ProviderService>
8

9
type PaymentError =
10
  | ValidationError
11
  | IdempotencyConflict
12
  | ProviderHardFail
13
  | ProviderSoftFail
14
  | PersistError

A is what succeeds. E is the union of every recoverable failure.

R lists every dependency the call site must provide. Missing one is a compile error.

Errors as Data

1
import { Data } from "effect"
2

3
class ValidationError extends Data.TaggedError("ValidationError")<{
4
  readonly field: string
5
  readonly message: string
6
}> {}
7

8
class ProviderSoftFail extends Data.TaggedError("ProviderSoftFail")<{
9
  readonly reason: string
10
}> {}

Data.TaggedError gives each error a _tag discriminator. catchTag narrows on that tag; the compiler removes the case from the remaining union.

Services as Ports

1
import { Context } from "effect"
2

3
class DbService extends Context.Service<DbService, DbPort>()("DbService") {}
4
class ProviderService extends Context.Service<ProviderService, ProviderPort>()("ProviderService") {}

Business logic depends on the tag, not on a concrete adapter. Tests supply a fake; production supplies the real adapter via Layer.succeed or Layer.effect.

Retry That Discriminates

The provider distinguishes 4xx (ProviderHardFail) from 5xx and timeouts (ProviderSoftFail). Only the latter is retried.

1
//      ┌─── Effect<ChargeResult, ProviderHardFail | ProviderSoftFail, ProviderService>
2
//      ▼
3
const charge = provider.charge(input).pipe(
4
  Effect.timeout("5 seconds"),
5
  Effect.catchTag("TimeoutError", () =>
6
    Effect.fail(new ProviderSoftFail({ reason: "Timeout" })),
7
  ),
8
  Effect.retry(Schedule.recurs(2)),
9
)

Schedule.while is the load-bearing piece. Without it, retry attempts a hard failure two more times, wasting calls and risking rate limits.

Why this matters. A naive retry(Schedule.recurs(2)) will hammer a dead 4xx three times before giving up, racking up provider fees and tripping rate limiters. Schedule.while reads the failure’s _tag on every attempt — the retry policy is part of the error model, not separate from it.

Idempotency

A payment is idempotent when repeating it with the same idemKey is safe. The function performs three checks in sequence:

1
Request 1 → findByKey null → acquireLock true  → charge → save → CONFIRMED
2
Request 2 → findByKey { id } → return cached
3
Request 3 → findByKey null → acquireLock false → IdempotencyConflict

The first two prevent double charges on retries. The third prevents double charges on concurrent retries arriving before the first request has committed.

> means *safe to repeat*. Without the find-then-lock sequence, a network > timeout that triggers an outer retry will charge the customer twice.

The Full Function

1
import { Effect } from "effect"
2

3
//      ┌─── Effect<PaymentResult, PaymentError, DbService | ProviderService>
4
//      ▼
5
const createPayment = (input: {
6
  readonly amount: number
7
  readonly currency: string
8
  readonly idemKey: string
9
}) =>
10
  Effect.gen(function* () {
11
    if (input.amount <= 0) {
12
      return yield* Effect.fail(
13
        new ValidationError({ field: "amount", message: "Must be positive" }),
14
      )
15
    }
16
    if (input.idemKey.length < 8) {
17
      return yield* Effect.fail(
18
        new ValidationError({ field: "idemKey", message: "Too short" }),
19
      )
20
    }
21

22
    const db = yield* DbService
23
    const provider = yield* ProviderService
24

25
    const existing = yield* db.findByKey(input.idemKey)
26
    if (existing) {
27
      return { paymentId: existing.id, status: "CONFIRMED" as const }
28
    }
29

30
    const locked = yield* db.acquireLock(input.idemKey)
31
    if (!locked) {
32
      return yield* Effect.fail(new IdempotencyConflict({ idemKey: input.idemKey }))
33
    }
34

35
    const charged = yield* provider
36
      .charge({ amount: input.amount, currency: input.currency })
37
      .pipe(
38
        Effect.timeout("5 seconds"),
39
        Effect.catchTag("TimeoutError", () =>
40
          Effect.fail(new ProviderSoftFail({ reason: "Timeout" })),
41
        ),
42
        Effect.retry(Schedule.recurs(2)),
43
      )
44

45
    const result: PaymentResult = {
46
      paymentId: charged.id,
47
      status: charged.status === "CONFIRMED" ? "CONFIRMED" : "FAILED",
48
    }
49

50
    yield* db
51
      .save({ ...result, idemKey: input.idemKey })
52
      .pipe(Effect.mapError((cause) => new PersistError({ cause })))
53

54
    return result
55
  })

Handling Errors at the Call Site

1
const handled = createPayment(input).pipe(
2
  Effect.provide(layers),
3
  Effect.catchTag("ValidationError", (e) =>
4
    Effect.succeed({ error: `Bad input: ${e.field}` }),
5
  ),
6
  Effect.catchTag("ProviderHardFail", (e) =>
7
    Effect.succeed({ error: `Provider rejected: ${e.status}` }),
8
  ),
9
)

Each catchTag removes one variant from E. Once every variant is handled, E is never.

Common Pitfalls

1, Retrying hard failures. A 4xx response will not become a 2xx response on the next attempt. Restrict retries with Schedule.while.

2, Forgetting to provide layers. Effect.runPromise(createPayment(...)) is a compile error when R is not never. That is the type system protecting you from a missing dependency.

3, Reading config inside business logic. Retry counts, timeouts, and URLs belong in the layer, not in createPayment. Tuning resilience should not require touching domain code.

4, Charging twice on retry. Without the find/lock/charge sequence, a network-timeout retry can charge the customer twice. Idempotency is not optional.

Every beat in this capstone is read-run; confirm the suite passes. - [ ] Read the `happy path` test and follow each `yield*` in `createPayment` back to its earlier step (gen → 07, services → 21, retry → 32). - [ ] In the `idempotency` group, run the three scenarios and confirm `findByKey` short-circuits before `acquireLock` is even called. - [ ] In the `provider errors` group, observe that `ProviderHardFail` runs the charge exactly once while `ProviderSoftFail` triggers the retry schedule. - [ ] Read the final `error union` assertion. The number `5` corresponds to every recoverable failure visible in `E` — name each one.

The full test suite

The index.test.ts for this lesson, verbatim from steps/49-payment-system/.

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

4
// =============================================================================
5
// 21 - Capstone: Payment System
6
// =============================================================================
7
//
8
// Combines: Data.TaggedError (05), Effect.gen (06), catchTag (07),
9
//           Context.Service + Layer (11-12), retry + timeout (17), test layers (16).
10
//
11
// The function signature names every failure and every dependency:
12
//   Effect<PaymentResult, PaymentError, DbService | ProviderService>
13

14
// ---------- Errors ----------
15

16
class ValidationError extends Data.TaggedError("ValidationError")<{
17
  readonly field: string
18
  readonly message: string
19
}> {}
20

21
class IdempotencyConflict extends Data.TaggedError("IdempotencyConflict")<{
22
  readonly idemKey: string
23
}> {}
24

25
class ProviderHardFail extends Data.TaggedError("ProviderHardFail")<{
26
  readonly status: number
27
  readonly body: unknown
28
}> {}
29

30
class ProviderSoftFail extends Data.TaggedError("ProviderSoftFail")<{
31
  readonly reason: string
32
}> {}
33

34
class PersistError extends Data.TaggedError("PersistError")<{
35
  readonly cause: unknown
36
}> {}
37

38
type PaymentError =
39
  | ValidationError
40
  | IdempotencyConflict
41
  | ProviderHardFail
42
  | ProviderSoftFail
43
  | PersistError
44

45
// ---------- Services ----------
46

47
type PaymentResult = { paymentId: string; status: "CONFIRMED" | "FAILED" }
48

49
interface DbPort {
50
  readonly findByKey: (key: string) => Effect.Effect<{ id: string } | null>
51
  readonly acquireLock: (key: string) => Effect.Effect<boolean>
52
  readonly save: (
53
    payment: PaymentResult & { idemKey: string },
54
  ) => Effect.Effect<void>
55
}
56

57
interface ProviderPort {
58
  readonly charge: (input: {
59
    amount: number
60
    currency: string
61
  }) => Effect.Effect<
62
    { id: string; status: string },
63
    ProviderHardFail | ProviderSoftFail
64
  >
65
}
66

67
class DbService extends Context.Service<DbService, DbPort>()("DbService") {}
68
class ProviderService extends Context.Service<ProviderService, ProviderPort>()("ProviderService") {}
69

70
// ---------- The function ----------
71

72
//      ┌─── Effect<PaymentResult, PaymentError, DbService | ProviderService>
73
//      ▼
74
function createPayment(input: {
75
  amount: number
76
  currency: string
77
  idemKey: string
78
}): Effect.Effect<PaymentResult, PaymentError, DbService | ProviderService> {
79
  return Effect.gen(function* () {
80
    if (input.amount <= 0) {
81
      return yield* Effect.fail(
82
        new ValidationError({ field: "amount", message: "Must be positive" }),
83
      )
84
    }
85
    if (input.idemKey.length < 8) {
86
      return yield* Effect.fail(
87
        new ValidationError({ field: "idemKey", message: "Too short" }),
88
      )
89
    }
90

91
    const db = yield* DbService
92
    const provider = yield* ProviderService
93

94
    const existing = yield* db.findByKey(input.idemKey)
95
    if (existing) {
96
      return { paymentId: existing.id, status: "CONFIRMED" as const }
97
    }
98

99
    const locked = yield* db.acquireLock(input.idemKey)
100
    if (!locked) {
101
      return yield* Effect.fail(
102
        new IdempotencyConflict({ idemKey: input.idemKey }),
103
      )
104
    }
105

106
    const charged = yield* provider
107
      .charge({ amount: input.amount, currency: input.currency })
108
      .pipe(
109
        Effect.timeout("5 seconds"),
110
        Effect.catchTag("TimeoutError", () =>
111
          Effect.fail(new ProviderSoftFail({ reason: "Timeout" })),
112
        ),
113
        Effect.retry(
114
          Schedule.recurs(2),
115
        ),
116
      )
117

118
    const result: PaymentResult = {
119
      paymentId: charged.id,
120
      status: charged.status === "CONFIRMED" ? "CONFIRMED" : "FAILED",
121
    }
122

123
    yield* db
124
      .save({ ...result, idemKey: input.idemKey })
125
      .pipe(Effect.mapError((cause) => new PersistError({ cause })))
126

127
    return result
128
  })
129
}
130

131
// ---------- Tests ----------
132

133
const makeTestDb = (options?: {
134
  existing?: { id: string } | null
135
  lockSuccess?: boolean
136
}): DbPort => ({
137
  findByKey: () => Effect.succeed(options?.existing ?? null),
138
  acquireLock: () => Effect.succeed(options?.lockSuccess ?? true),
139
  save: () => Effect.void,
140
})
141

142
const makeTestProvider = (options?: {
143
  hardFail?: boolean
144
  softFailAttempts?: number
145
}): ProviderPort => {
146
  let attempts = 0
147
  return {
148
    charge: () => {
149
      attempts++
150
      if (options?.hardFail) {
151
        return Effect.fail(
152
          new ProviderHardFail({ status: 400, body: { error: "bad" } }),
153
        )
154
      }
155
      if (
156
        options?.softFailAttempts &&
157
        attempts <= options.softFailAttempts
158
      ) {
159
        return Effect.fail(new ProviderSoftFail({ reason: "Rate limited" }))
160
      }
161
      return Effect.succeed({
162
        id: `pay_${Date.now()}`,
163
        status: "CONFIRMED",
164
      })
165
    },
166
  }
167
}
168

169
const makeLayer = (db: DbPort, provider: ProviderPort) =>
170
  Layer.merge(
171
    Layer.succeed(DbService, db),
172
    Layer.succeed(ProviderService, provider),
173
  )
174

175
describe("21 - Payment System", () => {
176
  // @beat
177
  //   id: happy-path
178
  //   shape: worked-then-your-turn
179
  //   title: Wire the happy path
180
  //   teaches: createPayment returns Effect<PaymentResult, PaymentError, DbService | ProviderService> and runs when both layers are provided.
181
  //   hint: Effect.provide a Layer.merge of DbService and ProviderService before runPromise
182
  describe("happy path", () => {
183
    it("creates a payment when all checks pass", async () => {
184
      const result = await Effect.runPromise(
185
        createPayment({
186
          amount: 100,
187
          currency: "USD",
188
          idemKey: "test-key-12345",
189
        }).pipe(Effect.provide(makeLayer(makeTestDb(), makeTestProvider()))),
190
      )
191

192
      expect(result.status).toBe("CONFIRMED")
193
      expect(result.paymentId).toBeTruthy()
194
    })
195
  })
196
  // @end-beat
197

198
  // @beat
199
  //   id: validate-first
200
  //   shape: multi-todo
201
  //   title: Validate inputs before any I/O
202
  //   teaches: Fail fast with Data.TaggedError variants so bad inputs never reach the database or provider.
203
  //   hint: yield* Effect.fail(new ValidationError(...)) before resolving DbService or ProviderService
204
  describe("validation rejects bad input before any I/O", () => {
205
    it("rejects non-positive amount", async () => {
206
      const exit = await Effect.runPromiseExit(
207
        createPayment({
208
          amount: -1,
209
          currency: "USD",
210
          idemKey: "test-key-12345",
211
        }).pipe(Effect.provide(makeLayer(makeTestDb(), makeTestProvider()))),
212
      )
213

214
      expect(exit._tag).toBe("Failure")
215
      if (exit._tag === "Failure" && exit.cause.reasons[0]?._tag === "Fail") {
216
        expect(exit.cause.reasons[0].error._tag).toBe("ValidationError")
217
      }
218
    })
219

220
    it("rejects an idempotency key shorter than 8 characters", async () => {
221
      const exit = await Effect.runPromiseExit(
222
        createPayment({
223
          amount: 100,
224
          currency: "USD",
225
          idemKey: "short",
226
        }).pipe(Effect.provide(makeLayer(makeTestDb(), makeTestProvider()))),
227
      )
228

229
      expect(exit._tag).toBe("Failure")
230
      if (exit._tag === "Failure" && exit.cause.reasons[0]?._tag === "Fail") {
231
        expect(exit.cause.reasons[0].error._tag).toBe("ValidationError")
232
      }
233
    })
234
  })
235
  // @end-beat
236

237
  // @beat
238
  //   id: idempotency
239
  //   shape: multi-todo
240
  //   title: Cache hits and lock contention
241
  //   teaches: findByKey returns a cached PaymentResult; a contended acquireLock raises IdempotencyConflict.
242
  //   hint: branch on findByKey first, then acquireLock; fail with new IdempotencyConflict when the lock is taken
243
  describe("idempotency", () => {
244
    it("returns the existing payment when the key has been seen", async () => {
245
      const result = await Effect.runPromise(
246
        createPayment({
247
          amount: 100,
248
          currency: "USD",
249
          idemKey: "existing-key-12345",
250
        }).pipe(
251
          Effect.provide(
252
            makeLayer(
253
              makeTestDb({ existing: { id: "existing-pay-123" } }),
254
              makeTestProvider(),
255
            ),
256
          ),
257
        ),
258
      )
259

260
      expect(result.paymentId).toBe("existing-pay-123")
261
      expect(result.status).toBe("CONFIRMED")
262
    })
263

264
    it("fails with IdempotencyConflict when the lock is contended", async () => {
265
      const exit = await Effect.runPromiseExit(
266
        createPayment({
267
          amount: 100,
268
          currency: "USD",
269
          idemKey: "test-key-12345",
270
        }).pipe(
271
          Effect.provide(
272
            makeLayer(
273
              makeTestDb({ lockSuccess: false }),
274
              makeTestProvider(),
275
            ),
276
          ),
277
        ),
278
      )
279

280
      expect(exit._tag).toBe("Failure")
281
      if (exit._tag === "Failure" && exit.cause.reasons[0]?._tag === "Fail") {
282
        expect(exit.cause.reasons[0].error._tag).toBe("IdempotencyConflict")
283
      }
284
    })
285
  })
286
  // @end-beat
287

288
  // @beat
289
  //   id: retry-discriminates
290
  //   shape: from-scratch
291
  //   title: Retry soft fails, surface hard fails
292
  //   teaches: Schedule.while narrows retries to ProviderSoftFail so 4xx hard failures fail immediately.
293
  //   hint: use a bounded Schedule.recurs policy for transient provider failures
294
  describe("provider errors", () => {
295
    it("does not retry a hard failure", async () => {
296
      const exit = await Effect.runPromiseExit(
297
        createPayment({
298
          amount: 100,
299
          currency: "USD",
300
          idemKey: "test-key-12345",
301
        }).pipe(
302
          Effect.provide(
303
            makeLayer(makeTestDb(), makeTestProvider({ hardFail: true })),
304
          ),
305
        ),
306
      )
307

308
      expect(exit._tag).toBe("Failure")
309
      if (exit._tag === "Failure" && exit.cause.reasons[0]?._tag === "Fail") {
310
        expect(exit.cause.reasons[0].error._tag).toBe("ProviderHardFail")
311
      }
312
    })
313

314
    it("only retries ProviderSoftFail via Schedule.while", () => {
315
      // whileInput discriminates on _tag.
316
      const isRetryable = (e: PaymentError | Error) =>
317
        "_tag" in e && e._tag === "ProviderSoftFail"
318

319
      expect(isRetryable(new ProviderSoftFail({ reason: "rate" }))).toBe(true)
320
      expect(isRetryable(new ProviderHardFail({ status: 400, body: null }))).toBe(
321
        false,
322
      )
323
    })
324
  })
325
  // @end-beat
326

327
  // @beat
328
  //   id: error-union
329
  //   shape: read-run
330
  //   title: PaymentError names every failure
331
  //   teaches: The E channel is a closed union of five tagged errors; nothing else can leak out of createPayment.
332
  //   hint: each Data.TaggedError class contributes one _tag to the union
333
  describe("error union", () => {
334
    it("PaymentError covers exactly five tags", () => {
335
      const errors: PaymentError[] = [
336
        new ValidationError({ field: "amount", message: "bad" }),
337
        new IdempotencyConflict({ idemKey: "key-12345" }),
338
        new ProviderHardFail({ status: 400, body: null }),
339
        new ProviderSoftFail({ reason: "rate limit" }),
340
        new PersistError({ cause: new Error("db down") }),
341
      ]
342

343
      expect(errors.map((e) => e._tag)).toEqual([
344
        "ValidationError",
345
        "IdempotencyConflict",
346
        "ProviderHardFail",
347
        "ProviderSoftFail",
348
        "PersistError",
349
      ])
350
    })
351
  })
352
  // @end-beat
353
})

09·01Payment System

49 - Capstone: Payment System

What you’ll work through

The Pipeline

The Signature

Errors as Data

Services as Ports

Retry That Discriminates

Idempotency

The Full Function

Handling Errors at the Call Site

Common Pitfalls

See Also

The full test suite