Here is a bug that shipped in a checkout I worked on. A refund function took an amount and the payment provider expected cents. One caller passed dollars. Customers got refunded 1% of what they were owed, and nobody noticed for two weeks, because every line of that code was “typed”: amount: number.
The types were there. They just did not earn their keep. number described the code and prevented nothing. This course is about the other kind of type, the kind that makes the bug impossible to write.
Cartwheel, the store you will work with throughout this course, has five order statuses: processing, shipped, delivered, cancelled and returned. Here is the decorative version:
type Order = { id: number; status: string };\n\nfunction canCancel(order: Order): boolean {\n return order.status === 'procesing'; // typo: always false\n}That compiles. status is string, so comparing it with any string is legal. Now the version that earns its keep:
type OrderStatus = 'processing' | 'shipped' | 'delivered' | 'cancelled' | 'returned';\ntype Order = { id: number; status: OrderStatus };\n\nfunction canCancel(order: Order): boolean {\n return order.status === 'procesing';\n // Error: This comparison appears to be unintentional because the types\n // 'OrderStatus' and '\"procesing\"' have no overlap.\n}Same runtime code, one changed line of types, and a whole class of bug is gone. You will see this move again and again: replace a wide type (string, number, object) with a narrow one that says what is actually allowed.
Lesson by lesson you will build the type layer of Cartwheel’s checkout API client: orders and their statuses, money that refuses to mix currencies, coupons, a fetch client whose responses are typed from a route map, events the checkout emits, and parsers that turn untrusted JSON into trusted types. The runtime code stays small on purpose. The interesting part is what the compiler refuses to accept.
\nThe course runs in five steps. First you use types as a design tool: structural typing, narrowing, discriminated unions and satisfies. Then generics, with a focus on inference. Then type-level programming, with honest advice on when to stop. Then patterns that real codebases need: branded types, Result types, parsing at the boundary, typed events. Finally, shipping: compiler flags, declaration files, decorators and migrating JavaScript.
Most exercises are type-level. The playground runs TypeScript 5.9 in strict mode and gives you two helpers:
\ntype T1 = Expect<Equal<OrderStatus, 'processing' | 'shipped' | 'delivered' | 'cancelled' | 'returned'>>;Equal<A, B> is true only when the two types are identical, and Expect only accepts true. So that line is a unit test: it compiles when you got the type right and fails when you did not.
The second tool is built into TypeScript. A // @ts-expect-error comment says “the next line must be an error”:
// @ts-expect-error: 'canceled' is not a status\ncanCancel({ id: 1001, status: 'canceled' });If the line below it compiles, TypeScript reports an unused directive. That turns “this bad call is rejected” into a test, which matters as much as “this good call is accepted”. A type that accepts everything passes every positive test.
\n\nIn the exercise below, the statuses are typed as string. Narrow the type and watch the compiler find the missing label for you. The next lesson looks at what “assignable” actually means in TypeScript, because it is not what most people coming from Java or C# expect.
string where only five values are valid is a missed chance; a union of literals lets the compiler check every use.","Expect<Equal<A, B>> fails to compile unless the two types are identical, so it works as a unit test for types.","A // @ts-expect-error line asserts that the next line is rejected, and it becomes an error itself if that line compiles."],"further":[{"title":"TypeScript for JavaScript Programmers","url":"https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html"},{"title":"Everyday Types","url":"https://www.typescriptlang.org/docs/handbook/2/everyday-types.html"}],"quiz":[{"q":"Which of these types catches the most real bugs for an order’s status field that can only be processing, shipped, delivered, cancelled or returned?
string, documented with a comment listing the five values","why":"A comment is not checked. 'canceled' with one L compiles fine and fails silently at runtime."},{"text":"'processing' | 'shipped' | 'delivered' | 'cancelled' | 'returned'","why":"Correct. Every assignment and comparison is checked against the five values, and the compiler can tell when a switch misses one."},{"text":"any, because the value comes from the database anyway","why":"any switches checking off for every use of the value, so a typo anywhere downstream goes unnoticed."},{"text":"String, the boxed object type, because it is stricter than string","why":"String is the wrapper object type and is no stricter; it accepts any string and is almost never what you want."}],"answer":1},{"q":"What does this type test do when Total is number | undefined?
type T1 = Expect<Equal<Total, number>>;number is part of the union.","why":"Equal checks that the two types are identical, not that one overlaps the other. A union with undefined is a different type."},{"text":"It compiles, but logs a warning at runtime.","why":"Types are erased before the code runs, so a type test can only fail at compile time; there is nothing left to log."},{"text":"It fails to compile, because Equal resolves to false and Expect only accepts true.","why":"Correct. Expect<T extends true> rejects false, so the mismatch shows up as a type error on that line."}],"answer":2},{"q":"You add // @ts-expect-error above pay(order, 'EUR'), but pay accepts any string as the currency. What happens?
// @ts-ignore behaves. @ts-expect-error is stricter and complains when it has nothing to suppress."},{"text":"TypeScript reports “Unused ‘@ts-expect-error’ directive”, so the test fails.","why":"Correct. An unused @ts-expect-error is itself an error, which is exactly why it works as a test that a bad call is rejected."},{"text":"The call is removed from the compiled JavaScript.","why":"Comments never change emitted code. The call still runs; only type checking is affected."}],"answer":1}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"// Cartwheel's five order statuses come from the orders table.\n// Right now the type accepts any string at all.\ntype OrderStatus = string;\n\nconst statusLabels: RecordCartwheel orders have exactly five statuses: processing, shipped, delivered, cancelled and returned. Replace string in OrderStatus with a union of those five literals so the type tests pass. Once the type is narrow, the compiler points at a gap in statusLabels: fill it so statusLabel('returned') returns 'Returned'.
'a' | 'b' | 'c'.","After you change OrderStatus, read the new error on statusLabels: Record<OrderStatus, string> now requires one key per status.","Add returned: 'Returned' to the object."],"explanation":"With OrderStatus as string, Record<OrderStatus, string> means “any string keys”, so a missing status is invisible and the typo 'canceled' is a valid argument. As a union of five literals, the record must have exactly those five keys, and canCancel('canceled') is rejected, which is what the @ts-expect-error line asserts. Nothing changed at runtime except the added label: the types alone found both problems.
statusLabel('returned') returns 'Returned'","can-cancel":"canCancel still allows only processing orders to be cancelled"}},"words":596,"readMinutes":3}