50 - Capstone: E-Commerce Checkout

Previous · Next

A checkout flow orchestrates four independent services, inventory, pricing, payment, order, each with its own failure mode. The useful question is not “did it work?” but “what happens when one of them does not?” This capstone composes the services with Effect.gen, runs the independent checks in parallel with Effect.all, and exposes every failure in the return type.

The final exercise turns this into a service-shaped boundary slice. A Schema acts as the typed transport contract, unknown input is decoded at the HTTP-style edge, SQL stays behind an OrdersRepository, the repository owns the transaction, and publication runs only after commit. Live adapters can provide real HTTP, SQL, and telemetry integrations; tests replace them with Layers without changing the application program.

The resulting artifacts are the contract Schema, tagged boundary errors, service interfaces, live and fake Layers, transaction test, and the observed begin → insert → commit → publish ordering. Together they make the architecture reviewable without coupling the domain program to a particular HTTP or SQL package.

What you’ll work through

The second capstone scales the single-service shape of 49-payment-system up to four collaborating services. index.test.ts covers the happy path: a non-empty cart flowing through parallel inventory and pricing checks, sequential reserve / charge / create, and a returned Order.

The interesting territory here is structural rather than algorithmic — every service comes from an earlier step, and the new content is how they compose under Effect.all and Layer.mergeAll.

By the end you should be able to take any multi-service workflow and decide three things from its signature alone: which steps run in parallel, which failures are recoverable, and where the dangerous partial-failure windows are.

The Pipeline

1
checkout(cart)
2
  ├── validate          cart not empty                         (CartError)
3
  ├── parallel
4
  │     ├── inventory.check(item) for each item                (InventoryError)
5
  │     └── pricing.getPrice(item) for each item               (PricingError)
6
  ├── total             sum(price * quantity)
7
  ├── reserve           inventory.reserve(item) for each item  (InventoryError)
8
  ├── charge            payment.charge(userId, total)          (PaymentError)
9
  └── create            orders.create(...)                     (OrderError)

Effect.all short-circuits on first failure by default. If prod-1 is out of stock, the pricing branch is interrupted before its requests finish.

The Signature

1
//      ┌─── Effect<Order, CheckoutError,
2
//      │         InventoryService | PricingService | PaymentService | OrderService>
3
//      ▼
4
declare function checkout(
5
  cart: Cart,
6
): Effect.Effect<
7
  Order,
8
  CheckoutError,
9
  InventoryService | PricingService | PaymentService | OrderService
10
>
11

12
type CheckoutError =
13
  | CartError
14
  | InventoryError
15
  | PricingError
16
  | PaymentError
17
  | OrderError

Four dependencies, five failure modes. Every one of them is visible to the caller.

Validate before any service is resolved

Validation runs at the top of the pipeline, before any Tag is yielded. Bad input never reaches the parallel branch, the payment gateway, or the order-creation service — it short-circuits with a typed ValidationError in E.

The orchestration code is unchanged whether validation lives in a service or as a pure helper; what matters is that it runs first.

1
import { Effect } from "effect"
2

3
const checkout = (cart: Cart) =>
4
  Effect.gen(function* () {
5
    // 1. Pure validation — no service required.
6
    yield* validateCart(cart) // Effect<void, ValidationError>
7

8
    // 2. Only now do we touch services.
9
    const inventory = yield* InventoryService
10
    const pricing = yield* PricingService
11
    // ...
12
  })

Validation in front means downstream branches never need to defend against malformed shapes — they can trust their inputs. The cost of running it eagerly is tiny; the cost of letting bad input through is a debugging session in production.

Your turn add a `validateCart` step at the top of the pipeline and assert that an invalid cart fails *before* any service mock is called.

Parallel Checks with `Effect.all`

1
//      ┌─── Effect<[Inventory[], Price[]], InventoryError | PricingError, ...>
2
//      ▼
3
const [, prices] = yield* Effect.all(
4
  [
5
    Effect.all(
6
      cart.items.map((item) => inventory.check(item.productId, item.quantity)),
7
      { concurrency: "unbounded" },
8
    ),
9
    Effect.all(
10
      cart.items.map((item) => pricing.getPrice(item.productId)),
11
      { concurrency: "unbounded" },
12
    ),
13
  ],
14
  { concurrency: "unbounded" },
15
)

Details

{ concurrency: "unbounded" } runs every effect at once. The default is sequential.

The default failure mode short-circuits on the first error and interrupts the rest; { mode: "validate" } collects all failures, { mode: "either" } wraps each result in Result.

Notice. Without concurrency, Effect.all runs sequentially. A 50-item cart that spends 100ms per pricing call costs five seconds in sequence and a hundred milliseconds in parallel — same code, same errors, different option.

Composing Layers

1
import { Layer } from "effect"
2

3
const testLayers = Layer.mergeAll(
4
  Layer.succeed(InventoryService, { check, reserve }),
5
  Layer.succeed(PricingService, { getPrice }),
6
  Layer.succeed(PaymentService, { charge }),
7
  Layer.succeed(OrderService, { create }),
8
)

Layer.mergeAll combines independent layers, no two may depend on each other. When layers do form a dependency chain, use Layer.provide to wire the dependency before merge.

Swapping one layer is a one-line change:

1
const failingPayment = Layer.succeed(PaymentService, {
2
  charge: () => Effect.fail(new PaymentError({ reason: "card_declined" })),
3
})

Partial Failure

The dangerous window is between payment.charge and orders.create. The card is debited but no order exists.

Effect does not roll back automatically, compensation is a domain decision. The type forces the question by exposing OrderError.

1
const order = yield* orders
2
  .create({ userId, items, total, txId: charge.txId })
3
  .pipe(
4
    Effect.catchTag("OrderError", (e) =>
5
      payment.refund(charge.txId).pipe(Effect.flatMap(() => Effect.fail(e))),
6
    ),
7
  )

The compensating refund itself returns an Effect, so its failure (a refund that did not go through) joins the error channel and surfaces to the caller for alerting.

The Full Function

1
import { Effect } from "effect"
2

3
//      ┌─── Effect<Order, CheckoutError, ...services>
4
//      ▼
5
const checkout = (cart: Cart) =>
6
  Effect.gen(function* () {
7
    if (cart.items.length === 0) {
8
      return yield* Effect.fail(new CartError({ reason: "Cart is empty" }))
9
    }
10

11
    const inventory = yield* InventoryService
12
    const pricing = yield* PricingService
13
    const payment = yield* PaymentService
14
    const orders = yield* OrderService
15

16
    const [, prices] = yield* Effect.all(
17
      [
18
        Effect.all(
19
          cart.items.map((i) => inventory.check(i.productId, i.quantity)),
20
          { concurrency: "unbounded" },
21
        ),
22
        Effect.all(
23
          cart.items.map((i) => pricing.getPrice(i.productId)),
24
          { concurrency: "unbounded" },
25
        ),
26
      ],
27
      { concurrency: "unbounded" },
28
    )
29

30
    const total = prices.reduce(
31
      (sum, price, i) => sum + price.amount * cart.items[i].quantity,
32
      0,
33
    )
34

35
    yield* Effect.all(
36
      cart.items.map((i) => inventory.reserve(i.productId, i.quantity)),
37
      { concurrency: "unbounded" },
38
    )
39

40
    const charge = yield* payment.charge(cart.userId, total)
41

42
    return yield* orders.create({
43
      userId: cart.userId,
44
      items: cart.items,
45
      total,
46
      txId: charge.txId,
47
    })
48
  })

Common Pitfalls

1, Sequential when you mean parallel. A bare for loop with yield* runs items one after another. Use Effect.all with { concurrency: "unbounded" } (or a number) when the items are independent.

2, Ignoring the partial-failure window. Charge succeeded, order failed: money out, order missing. Add compensation with catchTag("OrderError", ...) or a saga/outbox.

3, Circular Layer.mergeAll order. mergeAll requires that no layer depends on another in the set. Chain dependencies with Layer.provide before merging.

4, Forgetting to short-circuit validation. Validate the cart first, before resolving services. Failing fast on bad input keeps the I/O surface clean.

The full test suite

The index.test.ts for this lesson, verbatim from steps/50-ecommerce-checkout/.

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

4
// =============================================================================
5
// 22 - Capstone: E-Commerce Checkout
6
// =============================================================================
7
//
8
// Orchestrates four services. Inventory + pricing run in parallel; reserve →
9
// charge → create run sequentially. Five failure modes; all visible in the type.
10

11
// ---------- Errors ----------
12

13
class CartError extends Data.TaggedError("CartError")<{ readonly reason: string }> {}
14
class InventoryError extends Data.TaggedError("InventoryError")<{
15
  readonly productId: string
16
}> {}
17
class PricingError extends Data.TaggedError("PricingError")<{
18
  readonly productId: string
19
}> {}
20
class PaymentError extends Data.TaggedError("PaymentError")<{ readonly reason: string }> {}
21
class OrderError extends Data.TaggedError("OrderError")<{ readonly reason: string }> {}
22

23
type CheckoutError =
24
  | CartError
25
  | InventoryError
26
  | PricingError
27
  | PaymentError
28
  | OrderError
29

30
// ---------- Domain ----------
31

32
type Cart = {
33
  userId: string
34
  items: Array<{ productId: string; quantity: number }>
35
}
36
type Inventory = { productId: string; available: number }
37
type Price = { productId: string; amount: number }
38
type Order = { orderId: string; total: number; status: string }
39

40
// ---------- Services ----------
41

42
class InventoryService extends Context.Service<InventoryService, {
43
    readonly check: (
44
      productId: string,
45
      quantity: number,
46
    ) => Effect.Effect<Inventory, InventoryError>
47
    readonly reserve: (
48
      productId: string,
49
      quantity: number,
50
    ) => Effect.Effect<void, InventoryError>
51
  }>()("InventoryService") {}
52

53
class PricingService extends Context.Service<PricingService, {
54
    readonly getPrice: (productId: string) => Effect.Effect<Price, PricingError>
55
  }>()("PricingService") {}
56

57
class PaymentService extends Context.Service<PaymentService, {
58
    readonly charge: (
59
      userId: string,
60
      amount: number,
61
    ) => Effect.Effect<{ txId: string }, PaymentError>
62
  }>()("PaymentService") {}
63

64
class OrderService extends Context.Service<OrderService, {
65
    readonly create: (data: {
66
      userId: string
67
      items: Cart["items"]
68
      total: number
69
      txId: string
70
    }) => Effect.Effect<Order, OrderError>
71
  }>()("OrderService") {}
72

73
// ---------- The function ----------
74

75
//      ┌─── Effect<Order, CheckoutError, ...services>
76
//      ▼
77
function checkout(cart: Cart): Effect.Effect<
78
  Order,
79
  CheckoutError,
80
  InventoryService | PricingService | PaymentService | OrderService
81
> {
82
  return Effect.gen(function* () {
83
    if (cart.items.length === 0) {
84
      return yield* Effect.fail(new CartError({ reason: "Cart is empty" }))
85
    }
86

87
    const inventory = yield* InventoryService
88
    const pricing = yield* PricingService
89
    const payment = yield* PaymentService
90
    const orders = yield* OrderService
91

92
    const [, prices] = yield* Effect.all(
93
      [
94
        Effect.all(
95
          cart.items.map((i) => inventory.check(i.productId, i.quantity)),
96
          { concurrency: "unbounded" },
97
        ),
98
        Effect.all(
99
          cart.items.map((i) => pricing.getPrice(i.productId)),
100
          { concurrency: "unbounded" },
101
        ),
102
      ],
103
      { concurrency: "unbounded" },
104
    )
105

106
    const total = prices.reduce(
107
      (sum, price, i) => sum + price.amount * cart.items[i].quantity,
108
      0,
109
    )
110

111
    yield* Effect.all(
112
      cart.items.map((i) => inventory.reserve(i.productId, i.quantity)),
113
      { concurrency: "unbounded" },
114
    )
115

116
    const charge = yield* payment.charge(cart.userId, total)
117

118
    return yield* orders.create({
119
      userId: cart.userId,
120
      items: cart.items,
121
      total,
122
      txId: charge.txId,
123
    })
124
  })
125
}
126

127
// ---------- Tests ----------
128

129
const testLayers = Layer.mergeAll(
130
  Layer.succeed(InventoryService, {
131
    check: (productId, _quantity) =>
132
      productId === "out-of-stock"
133
        ? Effect.fail(new InventoryError({ productId }))
134
        : Effect.succeed({ productId, available: 100 }),
135
    reserve: () => Effect.void,
136
  }),
137
  Layer.succeed(PricingService, {
138
    getPrice: (productId) => Effect.succeed({ productId, amount: 29.99 }),
139
  }),
140
  Layer.succeed(PaymentService, {
141
    charge: (userId, amount) =>
142
      Effect.succeed({ txId: `tx_${userId}_${amount}` }),
143
  }),
144
  Layer.succeed(OrderService, {
145
    create: (data) =>
146
      Effect.succeed({
147
        orderId: `order_${data.txId}`,
148
        total: data.total,
149
        status: "confirmed",
150
      }),
151
  }),
152
)
153

154
describe("22 - E-Commerce Checkout", () => {
155
  // @beat
156
  //   id: orchestrate-services
157
  //   shape: worked-then-your-turn
158
  //   title: Orchestrate four services
159
  //   teaches: Effect.gen sequences validation, parallel checks, reserve, charge, and create across four service tags.
160
  //   hint: Effect.provide a Layer.mergeAll of every service before runPromise
161
  describe("happy path", () => {
162
    it("completes a checkout with the merged test layers", async () => {
163
      const order = await Effect.runPromise(
164
        checkout({
165
          userId: "user-1",
166
          items: [
167
            { productId: "prod-1", quantity: 2 },
168
            { productId: "prod-2", quantity: 1 },
169
          ],
170
        }).pipe(Effect.provide(testLayers)),
171
      )
172

173
      expect(order.status).toBe("confirmed")
174
      expect(order.orderId).toBeTruthy()
175
      expect(order.total).toBeCloseTo(89.97)
176
    })
177
  })
178
  // @end-beat
179

180
  // @beat
181
  //   id: validate-cart
182
  //   shape: one-todo
183
  //   title: Short-circuit an empty cart
184
  //   teaches: Validation runs before any service is resolved so bad input never reaches the parallel branch.
185
  //   hint: yield* Effect.fail(new CartError({ reason: "Cart is empty" })) when items.length === 0
186
  it("an empty cart fails with CartError before any I/O", async () => {
187
    const exit = await Effect.runPromiseExit(
188
      checkout({ userId: "user-1", items: [] }).pipe(
189
        Effect.provide(testLayers),
190
      ),
191
    )
192

193
    expect(exit._tag).toBe("Failure")
194
    if (exit._tag === "Failure" && exit.cause.reasons[0]?._tag === "Fail") {
195
      expect(exit.cause.reasons[0].error._tag).toBe("CartError")
196
    }
197
  })
198
  // @end-beat
199

200
  // @beat
201
  //   id: parallel-checks
202
  //   shape: multi-todo
203
  //   title: Run inventory and pricing in parallel
204
  //   teaches: Effect.all with { concurrency: "unbounded" } fans out independent checks and short-circuits on the first failure.
205
  //   hint: nest Effect.all — outer pairs the two branches, inner maps each branch over cart.items
206
  it("an out-of-stock item short-circuits the parallel branch", async () => {
207
    const exit = await Effect.runPromiseExit(
208
      checkout({
209
        userId: "user-1",
210
        items: [{ productId: "out-of-stock", quantity: 1 }],
211
      }).pipe(Effect.provide(testLayers)),
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("InventoryError")
217
    }
218
  })
219
  // @end-beat
220

221
  // @beat
222
  //   id: swap-layer
223
  //   shape: from-scratch
224
  //   title: Swap one layer to inject a failure
225
  //   teaches: Layer.mergeAll combines independent services; swap one Layer.succeed to test downstream propagation.
226
  //   hint: rebuild the merged layer with a PaymentService whose charge returns Effect.fail(new PaymentError(...))
227
  it("a payment failure propagates through the pipeline", async () => {
228
    const failingPayment = Layer.mergeAll(
229
      Layer.succeed(InventoryService, {
230
        check: () => Effect.succeed({ productId: "p1", available: 100 }),
231
        reserve: () => Effect.void,
232
      }),
233
      Layer.succeed(PricingService, {
234
        getPrice: (pid) => Effect.succeed({ productId: pid, amount: 10 }),
235
      }),
236
      Layer.succeed(PaymentService, {
237
        charge: () =>
238
          Effect.fail(new PaymentError({ reason: "Card declined" })),
239
      }),
240
      Layer.succeed(OrderService, {
241
        create: () =>
242
          Effect.succeed({ orderId: "x", total: 0, status: "x" }),
243
      }),
244
    )
245

246
    const exit = await Effect.runPromiseExit(
247
      checkout({
248
        userId: "user-1",
249
        items: [{ productId: "prod-1", quantity: 1 }],
250
      }).pipe(Effect.provide(failingPayment)),
251
    )
252

253
    expect(exit._tag).toBe("Failure")
254
    if (exit._tag === "Failure" && exit.cause.reasons[0]?._tag === "Fail") {
255
      expect(exit.cause.reasons[0].error._tag).toBe("PaymentError")
256
    }
257
  })
258
  // @end-beat
259

260
  // @beat
261
  //   id: partial-failure
262
  //   shape: from-scratch
263
  //   title: Surface the partial-failure window
264
  //   teaches: OrderError after a successful charge is the compensation seam — the type forces the caller to acknowledge it.
265
  //   hint: at the call site, Effect.catchTag("OrderError", e => payment.refund(charge.txId).pipe(Effect.flatMap(() => Effect.fail(e))))
266
  it("an order failure after a successful charge is the partial-failure window", async () => {
267
    // Card debited, order missing. OrderError in the type forces the caller
268
    // to consider compensation (refund, alert, dead-letter queue).
269
    const partialFail = Layer.mergeAll(
270
      Layer.succeed(InventoryService, {
271
        check: () => Effect.succeed({ productId: "p1", available: 100 }),
272
        reserve: () => Effect.void,
273
      }),
274
      Layer.succeed(PricingService, {
275
        getPrice: (pid) => Effect.succeed({ productId: pid, amount: 10 }),
276
      }),
277
      Layer.succeed(PaymentService, {
278
        charge: (userId, amount) =>
279
          Effect.succeed({ txId: `tx_${userId}_${amount}` }),
280
      }),
281
      Layer.succeed(OrderService, {
282
        create: () =>
283
          Effect.fail(new OrderError({ reason: "DB unavailable" })),
284
      }),
285
    )
286

287
    const exit = await Effect.runPromiseExit(
288
      checkout({
289
        userId: "user-1",
290
        items: [{ productId: "prod-1", quantity: 1 }],
291
      }).pipe(Effect.provide(partialFail)),
292
    )
293

294
    expect(exit._tag).toBe("Failure")
295
    if (exit._tag === "Failure" && exit.cause.reasons[0]?._tag === "Fail") {
296
      expect(exit.cause.reasons[0].error._tag).toBe("OrderError")
297
    }
298
  })
299
  // @end-beat
300
})
301

302
// @beat
303
//   id: transactional-repository-boundary
304
//   shape: read-run
305
//   title: Keep contracts, SQL, transactions, and post-commit work at explicit seams
306
//   teaches: Decode at the boundary, hide SQL behind a repository, commit the transaction before publishing follow-up effects, and replace every edge with a Layer in tests.
307
//   hint: The audit order should be begin, insert, commit, publish; publishing inside transaction would make the boundary incorrect.
308
describe("service-shaped boundary slice", () => {
309
  const CreateOrder = Schema.Struct({ customerId: Schema.String, total: Schema.Number })
310

311
  class OrdersRepository extends Context.Service<OrdersRepository, {
312
    readonly transaction: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
313
    readonly insert: (order: typeof CreateOrder.Type) => Effect.Effect<string>
314
  }>()("app/OrdersRepository") {}
315

316
  class OrderEvents extends Context.Service<OrderEvents, {
317
    readonly created: (id: string) => Effect.Effect<void>
318
  }>()("app/OrderEvents") {}
319

320
  const createOrder = (input: unknown) => Effect.gen(function*() {
321
    const order = yield* Schema.decodeUnknownEffect(CreateOrder)(input)
322
    const repository = yield* OrdersRepository
323
    const events = yield* OrderEvents
324
    const id = yield* repository.transaction(repository.insert(order))
325
    yield* events.created(id)
326
    return { id }
327
  })
328

329
  it("keeps SQL behind a repository transaction and effects after commit", async () => {
330
    const audit: Array<string> = []
331
    const layer = Layer.mergeAll(
332
      Layer.succeed(OrdersRepository, {
333
        transaction: (effect) => Effect.sync(() => audit.push("begin")).pipe(
334
          Effect.andThen(effect),
335
          Effect.tap(() => Effect.sync(() => audit.push("commit"))),
336
        ),
337
        insert: () => Effect.sync(() => (audit.push("insert"), "o-1")),
338
      }),
339
      Layer.succeed(OrderEvents, {
340
        created: () => Effect.sync(() => { audit.push("publish") }),
341
      }),
342
    )
343

344
    const result = await Effect.runPromise(
345
      createOrder({ customerId: "c-1", total: 42 }).pipe(Effect.provide(layer)),
346
    )
347
    expect(result).toEqual({ id: "o-1" })
348
    expect(audit).toEqual(["begin", "insert", "commit", "publish"])
349
  })
350
})
351
// @end-beat

09·02E-commerce Checkout

50 - Capstone: E-Commerce Checkout

What you’ll work through

The Pipeline

The Signature

Validate before any service is resolved

Parallel Checks with `Effect.all`

Composing Layers

Partial Failure

The Full Function

Common Pitfalls

See Also

The full test suite

09·02E-commerce Checkout

50 - Capstone: E-Commerce Checkout

What you’ll work through

The Pipeline

The Signature

Validate before any service is resolved

Parallel Checks with Effect.all

Composing Layers

Partial Failure

The Full Function

Common Pitfalls

See Also

The full test suite

Parallel Checks with `Effect.all`