Here is the signature of the function at the heart of Cartwheel’s checkout:
\nasync function placeOrder(cart: Cart, payment: PaymentMethod): Promise<Order> { /* … */ }It can fail in at least five ways the business expects every day: the card is declined, an item is out of stock, the coupon expired, the address is undeliverable, the payment provider asks for 3-D Secure. The signature mentions none of them. They are exceptions, thrown from somewhere inside, and TypeScript has no throws clause. A caller who forgets a try/catch compiles fine, and the customer sees a blank screen.
The fix is to return expected failures instead of throwing them, using a discriminated union you already know how to write:
\ntype Result<T, E> = { ok: true; value: T } | { ok: false; error: E };\n\nconst ok = <T>(value: T): { ok: true; value: T } => ({ ok: true, value });\nconst err = <E>(error: E): { ok: false; error: E } => ({ ok: false, error });ok is the discriminant. A caller cannot read value without first proving the call succeeded, because value only exists on one member:
const result = await placeOrder(cart, payment);\nshowConfirmation(result.value);\n// Error: Property 'value' does not exist on type 'Result<Order, CheckoutError>'.\n// Property 'value' does not exist on type '{ ok: false; error: CheckoutError; }'.\n\nif (result.ok) showConfirmation(result.value); // fineE could be a string, but a string is the error equivalent of status: string. Model failures as a discriminated union, each with the data needed to handle it:
type CheckoutError =\n | { type: 'card-declined'; declineCode: string }\n | { type: 'out-of-stock'; sku: string; available: number }\n | { type: 'coupon-expired'; code: string; expiredOn: string };\n\nfunction errorMessage(e: CheckoutError): string {\n switch (e.type) {\n case 'card-declined': return `Your card was declined (${e.declineCode}).`;\n case 'out-of-stock': return `Only ${e.available} of ${e.sku} left.`;\n case 'coupon-expired': return `${e.code} expired on ${e.expiredOn}.`;\n }\n}The : string return type makes this exhaustive, as you saw in section 1. When the payments team adds 'requires-3ds' to the union, every message function and every UI branch that switches on type is flagged.
Checkout is a sequence: validate the cart, apply the coupon, charge the card. Each step can fail with its own errors. Early returns compose them without nesting:
\ntype CartError = { type: 'out-of-stock'; sku: string; available: number };\ntype CouponError = { type: 'coupon-expired'; code: string; expiredOn: string };\n\nasync function checkout(input: CheckoutInput): Promise<Result<Order, CartError | CouponError | PaymentError>> {\n const cart = validateCart(input.lines);\n if (!cart.ok) return cart;\n\n const priced = applyCoupon(cart.value, input.coupon);\n if (!priced.ok) return priced;\n\n const charge = await chargeCard(priced.value.total, input.payment);\n if (!charge.ok) return charge;\n\n return ok(createOrder(priced.value, charge.value));\n}After if (!cart.ok), cart is narrowed to { ok: false; error: CartError }, which is assignable to the function’s wider failure type, so it can be returned as is. The success path reads top to bottom, and the return type documents every failure the caller must handle. If someone later adds a fourth step with a new error type and forgets to widen the return type, the return of that step’s failure is a compile error, so the list of failures cannot silently fall out of date.
You will see libraries that offer map and andThen methods to chain results instead. They are fine, but in TypeScript the early-return style is usually easier to read and needs no library: narrowing does the work.
Most of the failures in a checkout start life as exceptions in someone else’s code: the payment SDK throws a CardError, fetch rejects when the network drops. Convert them once, at the edge, into the Result your own code speaks:
type PaymentError = { type: 'card-declined'; declineCode: string };\n\nasync function chargeCard(amount: Money, payment: PaymentMethod): Promise<Result<Receipt, PaymentError>> {\n try {\n return ok(await paymentSdk.charge(amount, payment));\n } catch (e: unknown) {\n if (e instanceof CardError) return err({ type: 'card-declined', declineCode: e.code });\n throw e; // not a failure we understand: let it propagate\n }\n}Three things are worth copying. The catch variable is unknown, as it always is under strict, so you narrow it with instanceof before reading code. Only the one failure the business expects becomes a value; everything else is rethrown untouched, stack trace and all. And the function’s return type is now an honest list of what can go wrong, which every caller sees in a tooltip.
Asynchronous results nest the obvious way, Promise<Result<T, E>>. A rejected promise still means “something unexpected happened”, and a resolved { ok: false } means “the business said no”. Keeping those two channels separate is the whole point.
Result is for failures the business expects and the caller can act on. It is not a replacement for every throw:
null where the types say there cannot be one, an unhandled union member reaching assertNever) should throw. There is nothing sensible for the caller to do, and you want a stack trace.err(…) and rethrowing the rest.In the exercise you will build Cartwheel’s coupon step with Result, compose it into a checkout function, and write the exhaustive error messages. Next lesson deals with the data those steps start from: untrusted input.
type Result<T, E> = { ok: true; value: T } | { ok: false; error: E } is a discriminated union, so callers must check ok before they can read value.","Model errors as a discriminated union too, so each failure carries its own data and the UI can handle every case exhaustively.","Compose results with early returns (if (!r.ok) return r;); the narrowed failure is assignable to the caller’s wider error union.","Use Result for failures the business expects; keep throw for bugs, broken invariants and infrastructure failures you cannot handle locally."],"further":[{"title":"Discriminated unions (Narrowing)","url":"https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"},{"title":"Control flow and error handling (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Control_flow_and_error_handling"}],"quiz":[{"q":"placeOrder(cart): Promise<Order> can fail with a declined card. What does its signature tell a caller about that?
throws clause in TypeScript, which is why expected failures belong in the return type."},{"text":"That it rejects with an Error, because every promise can reject.","why":"Any promise can reject with any value. The signature does not say which failures are expected or what data they carry."},{"text":"That the caller must wrap it in try/catch, enforced by strict.","why":"No compiler option forces a try/catch; forgetting one compiles fine."},{"text":"That it can throw a CardDeclinedError, inferred from the implementation.","why":"Thrown types are never inferred or tracked, even with all strict flags on."}],"answer":0},{"q":"Why does the last line fail to compile?
\ntype Result<T, E> = { ok: true; value: T } | { ok: false; error: E };\ndeclare const r: Result<Order, CheckoutError>;\nconsole.log(r.value.id);value is optional in Result.","why":"value is required on the success member. The issue is that it does not exist on the failure member at all."},{"text":"Because Result must be awaited first.","why":"r is not a promise in this snippet; nothing needs awaiting."},{"text":"Because value only exists on the ok: true member, and r has not been narrowed.","why":"Correct. Checking if (r.ok) narrows r to the success member, where value is available."}],"answer":2},{"q":"Which failure is a good fit for a Result rather than an exception?
null reaching a function whose types say it cannot be null.","why":"That is a broken invariant, a bug. Throw, and fix the code that let it happen."},{"text":"The database connection pool is exhausted.","why":"Infrastructure failure that the checkout cannot handle locally; let it propagate to the error boundary or retry layer."},{"text":"The coupon code the customer typed has expired.","why":"Correct. It is expected, the caller can do something useful (show a message), and it carries data (the code and its expiry)."}],"answer":2},{"q":"validateCart returns Result<Cart, CartError> and checkout returns Result<Order, CartError | PaymentError>. Does this compile?
const cart = validateCart(input);\nif (!cart.ok) return cart;Result<Cart, CartError> is not Result<Order, …>.","why":"After the check, cart is only the failure member, { ok: false; error: CartError }, which has no Cart in it."},{"text":"No, you must rebuild the failure with err(cart.error).","why":"Rebuilding works, but it is unnecessary; the narrowed failure already fits."},{"text":"Only with an as cast.","why":"No cast is needed; assignability handles it."},{"text":"Yes, because the narrowed { ok: false; error: CartError } is assignable to the wider failure member.","why":"Correct. CartError is part of CartError | PaymentError, so the failure can be returned as is."}],"answer":3}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"type Coupon = { code: string; percentOff: number; expiresOn: string };\ntype Cart = { lines: { sku: string; quantity: number; unitPriceCents: number }[] };\ntype PricedCart = Cart & { totalCents: number };\n\nconst COUPONS: Coupon[] = [\n { code: 'WELCOME10', percentOff: 10, expiresOn: '2099-12-31' },\n { code: 'SPRING15', percentOff: 15, expiresOn: '2025-05-31' },\n];\nconst STOCK: RecordTurn Cartwheel’s coupon step into typed, expected failures:
\nResult<T, E> as a discriminated union on ok, with ok(value) and err(error) helpers.findCoupon return Result<Coupon, CouponError>: coupon-unknown when the code does not exist, coupon-expired (with expiredOn) when expiresOn is before today.checkout return Result<PricedCart, CheckoutError>: check stock first, then the coupon (when couponCode is not null), then return the cart with totalCents (subtotal minus the coupon’s percentage, rounded).errorMessage return a message for each error type that includes its data (the code, the expiry date, or the SKU).type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }; and const ok = <T>(value: T): { ok: true; value: T } => ({ ok: true, value });.","In checkout, use early returns: const stocked = checkStock(cart); if (!stocked.ok) return stocked;. The narrowed failure fits the wider CheckoutError union.","Annotate checkout’s return type explicitly, and switch on e.type in errorMessage with a : string return type so a missed case is a compile error."],"explanation":"With Result as a discriminated union, value simply does not exist until a caller checks ok, which is what the @ts-expect-error line proves. findCoupon now declares both of its expected failures in its signature instead of hiding them in throw. Early returns keep checkout flat: each narrowed failure is assignable to CheckoutError, so it is returned unchanged. Because errors are a union with a type discriminant, errorMessage can use each failure’s own data, and adding a new error type later flags this function automatically.
coupon-expired failure with its expiry date","stock-first":"Stock is checked before the coupon","messages":"errorMessage includes each failure’s data"}},"words":712,"readMinutes":3}