Cartwheel’s checkout emits events: order.shipped, payment.failed, checkout.opened. Analytics, the email service and the order page all listen. The first version used a plain emitter typed with string names and any payloads, and it produced the two classic bugs: a listener for 'order.shiped' that never fired, and a handler reading payload.trackingNo on an event that sends trackingNumber. Both were invisible until someone noticed missing emails.
Everything from this section and the last comes together to fix it.
\nDescribe every event once, in a map from name to payload type:
\ntype CheckoutEvents = {\n 'checkout.opened': undefined;\n 'order.shipped': { orderId: number; carrier: string; trackingNumber: string };\n 'payment.failed': { orderId: number; reason: string };\n};You could also generate part of this map with the template-literal mapped type from Template Literal Types. Either way, the map is the single source of truth: names are its keys, payloads are its values.
\ntype EventArgs<P> = [P] extends [undefined] ? [] : [payload: P];\ntype Handler = (payload: never) => void;\n\nclass Emitter<Events extends Record<string, unknown>> {\n #handlers = new Map<keyof Events, Set<Handler>>();\n\n on<K extends keyof Events>(event: K, handler: (payload: Events[K]) => void): () => void {\n let set = this.#handlers.get(event);\n if (!set) {\n set = new Set();\n this.#handlers.set(event, set);\n }\n set.add(handler);\n return () => set.delete(handler);\n }\n\n emit<K extends keyof Events>(event: K, ...args: EventArgs<Events[K]>): void {\n for (const handler of this.#handlers.get(event) ?? []) {\n // Handlers for K were registered with a matching payload type in on().\n (handler as (payload: unknown) => void)(args[0]);\n }\n }\n}The pattern is the API client’s, applied to events. K is inferred from the event name and has one job: look up the payload in Events[K]. In on, that type flows into the handler’s parameter, so the callback is contextually typed. In emit, it checks the payload you pass.
const bus = new Emitter<CheckoutEvents>();\n\nconst off = bus.on('order.shipped', (e) => sendEmail(`Tracking: ${e.trackingNumber}`));\nbus.emit('order.shipped', { orderId: 1042, carrier: 'DHL', trackingNumber: '1Z-999' });\nbus.emit('checkout.opened'); // no payload needed\nbus.on('order.shiped', () => {});\n// Error: Argument of type '\"order.shiped\"' is not assignable to parameter of type 'keyof CheckoutEvents'.\nbus.emit('payment.failed', { orderId: 1042 });\n// Error: … Property 'reason' is missing …\noff(); // unsubscribeEventArgs is the conditional rest-parameter trick from Conditional Types, Distribution and infer: payload-less events take zero extra arguments, the rest take exactly one. The brackets in [P] extends [undefined] stop distribution, so a payload type like string | undefined is still required rather than split.
Notice where the loose types live. Inside the class, handlers are stored as Set<Handler> and called through one commented cast, because a Map cannot express “the value type depends on the key”. Outside, every method is precise. That split, untyped storage behind a typed surface, is how most well-typed libraries are built. The private #handlers field is a real JavaScript private field, so nothing outside can reach in and break the invariant.
Once the core is typed, new methods inherit the precision almost for free. A once that resolves a promise with the next payload is four lines, and its result is typed per event with no extra annotations:
once<K extends keyof Events>(event: K): Promise<Events[K]> {\n return new Promise((resolve) => {\n const off = this.on(event, (payload) => { off(); resolve(payload); });\n });\n}\n\nconst shipped = await bus.once('order.shipped'); // { orderId; carrier; trackingNumber }This is the payoff of putting the types in one map and threading K through: each method you add is checked against the same source of truth, and none of them repeats a payload type.
A builder chains method calls to assemble something step by step. The type-level trick is to carry what has been built so far in a type parameter, and return a new, wider type from each call. Here is a small query builder for Cartwheel’s order history:
\ntype Order = { id: number; status: OrderStatus; totalCents: number; customer: string };\n\nclass OrderQuery<Selected extends keyof Order = never> {\n readonly #fields: readonly (keyof Order)[];\n\n constructor(fields: readonly (keyof Order)[] = []) {\n this.#fields = fields;\n }\n\n select<K extends keyof Order>(...fields: K[]): OrderQuery<Selected | K> {\n return new OrderQuery<Selected | K>([...this.#fields, ...fields]);\n }\n\n run(rows: Order[]): Pick<Order, Selected>[] {\n // #fields holds exactly the keys in Selected.\n return rows.map((row) => Object.fromEntries(this.#fields.map((f) => [f, row[f]])) as Pick<Order, Selected>);\n }\n}\n\nconst rows = new OrderQuery().select('id').select('totalCents').run(allOrders);\nrows[0].totalCents; // number\nrows[0].customer; // Error: Property 'customer' does not exist on type 'Pick<Order, \"id\" | \"totalCents\">'.Selected starts as never (nothing selected) and each select returns OrderQuery<Selected | K>. A method cannot change the type of the object it is called on, so each step returns a new instance. That is also good runtime design: builders that never mutate can be shared and reused safely. This is the same technique query builders such as Kysely and Drizzle use at much larger scale.
In the exercise you will build Cartwheel’s typed event bus and a small selecting builder. That completes the patterns section; section 5 turns to shipping all of this, starting with the compiler flags that make these types trustworthy.
\n","toc":[{"id":"sec-1","text":"One map, every type","level":2},{"id":"sec-2","text":"The typed emitter","level":2},{"id":"sec-3","text":"Builders whose type grows","level":2}],"takeaways":["An event map type ({ 'order.shipped': { orderId: number } }) is the single source of truth for both event names and payload types.","on<K extends keyof Events>(event: K, handler: (payload: Events[K]) => void) ties the handler’s parameter to the event name the caller passes.","A conditional rest parameter lets events with no payload be emitted without a dummy argument.","A builder can carry state in a type parameter, returning a new, wider type from each call, so the final result type reflects every step.","Keep the untyped storage inside the class and the precise types on its public methods, so the one cast lives in one place."],"further":[{"title":"Generic Classes","url":"https://www.typescriptlang.org/docs/handbook/2/generics.html#generic-classes"},{"title":"Classes (this-based types and parameter properties)","url":"https://www.typescriptlang.org/docs/handbook/2/classes.html"},{"title":"Rest parameters with tuple types (TypeScript 3.0 release notes)","url":"https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-0.html"}],"quiz":[{"q":"With bus = new Emitter<CheckoutEvents>(), what is the type of p?
type CheckoutEvents = {\n 'order.shipped': { orderId: number; carrier: string };\n 'payment.failed': { orderId: number; reason: string };\n};\nbus.on('payment.failed', (p) => console.log(p.reason));CheckoutEvents[keyof CheckoutEvents], the union of both payloads","why":"That would happen if the event name were typed as keyof Events without a type parameter. K captures the specific name."},{"text":"unknown, because handlers are stored in an untyped map","why":"How handlers are stored is an implementation detail; the public signature decides what callers see."},{"text":"any, because callbacks are contextually typed","why":"Contextual typing gives p the parameter type from the signature, which is precise here."},{"text":"{ orderId: number; reason: string }","why":"Correct. K is inferred as 'payment.failed', and the handler’s parameter is CheckoutEvents[K]."}],"answer":3},{"q":"Why type emit with ...args: EventArgs<Events[K]> instead of payload: Events[K]?
undefined can be emitted as emit('checkout.opened') with no second argument.","why":"Correct. The conditional produces an empty tuple for payload-less events and a one-element tuple otherwise."},{"text":"Because rest parameters are faster at runtime.","why":"The choice is about the type signature; at runtime the difference is negligible."},{"text":"Because Events[K] cannot be used as a parameter type.","why":"It can; on uses it for the handler parameter. The rest form only solves the missing-payload case."}],"answer":0},{"q":"What is the type of rows?
const rows = new OrderQuery().select('id').select('totalCents').run(allOrders);Order[], because run always returns full orders","why":"In this builder run returns Pick<Order, Selected>[], and Selected has grown with each call."},{"text":"Pick<Order, 'id' | 'totalCents'>[]","why":"Correct. Each select returns OrderQuery<Selected | K>, so the type parameter accumulates both fields."},{"text":"Pick<Order, 'totalCents'>[], because the second call replaces the first","why":"The second call widens Selected with a union; it does not replace it."}],"answer":1},{"q":"Why does each select call return a new OrderQuery instead of mutating this and returning it?
this from methods.","why":"They can; fluent APIs often do. The issue is what the type of this can express."},{"text":"Because a method cannot change the type of the object it is called on, so the wider type needs a new value.","why":"Correct. this keeps its type for its whole life; returning a new instance with a new type parameter is how the type grows."},{"text":"Because mutation is not allowed in TypeScript classes.","why":"TypeScript allows mutation freely; this is a typing constraint, not a language rule."}],"answer":1}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"type OrderStatus = 'processing' | 'shipped' | 'delivered' | 'cancelled' | 'returned';\ntype Order = { id: number; status: OrderStatus; totalCents: number; customer: string };\n\nconst ORDERS: Order[] = [\n { id: 1042, status: 'shipped', totalCents: 18900, customer: 'Mona' },\n { id: 1043, status: 'processing', totalCents: 4500, customer: 'Karim' },\n];\n\nclass Emitter = [P] extends [undefined] ? [] : [payload: P];\ntype Handler = (payload: never) => void;\n\nclass Emitter Make Cartwheel’s two utilities fully typed without changing their runtime behaviour: Keep any cast inside the classes, in one commented place each. The event map is the only place payload types are written; \n
\nEmitter<Events>: on(event, handler) must only accept event names from Events and give the handler that event’s payload type; emit(event, payload) must check the payload, and events whose payload is undefined must be emitted with no payload argument.OrderQuery: each select(...fields) call adds to the selected fields, and run(rows) returns Pick<Order, …>[] of exactly the selected fields.on and emit a type parameter K extends keyof Events and look the payload up with Events[K]. Constrain the class: Emitter<Events extends Record<string, unknown>>.","For payload-less events, use a conditional rest parameter: type EventArgs<P> = [P] extends [undefined] ? [] : [payload: P]; and emit<K …>(event: K, ...args: EventArgs<Events[K]>).","Give OrderQuery a type parameter Selected extends keyof Order = never; select<K extends keyof Order>(...fields: K[]) returns new OrderQuery<Selected | K>(…), and run returns Pick<Order, Selected>[] with one cast."],"explanation":"K is inferred from the event name and links it to Events[K] for both the handler and the payload. The conditional rest parameter yields zero arguments for undefined payloads, and the brackets stop it from distributing over unions. Inside, a Map cannot relate keys to value types, so handlers are stored loosely and called through one cast. The builder carries the selected keys in its type parameter: each select returns a new instance with a wider union, and run turns that union into a Pick.emit calls only the handlers for that event, with the payload","unsubscribes":"The function returned by on removes the handler","selects":"run returns only the selected fields, across several select calls"}},"words":665,"readMinutes":3}