Here is a helper from Cartwheel’s order history page. It is typed, it compiles, and it quietly throws information away:
\ntype DetailedOrder = { id: number; totalCents: number; customer: string };\n\nfunction sortByTotal(orders: { totalCents: number }[]): { totalCents: number }[] {\n return [...orders].sort((a, b) => a.totalCents - b.totalCents);\n}\n\ndeclare const orders: DetailedOrder[];\nconst sorted = sortByTotal(orders);\nsorted[0].customer;\n// Error: Property 'customer' does not exist on type '{ totalCents: number; }'.The objects in sorted are still full orders at runtime. But the function’s signature can only describe its output in terms of its input annotation, and that annotation only mentions totalCents. The fix is not a wider annotation. It is a relationship: “whatever kind of object you give me, you get the same kind back”.
That relationship is what a generic says:
\nfunction sortByTotal<T extends { totalCents: number }>(orders: T[]): T[] {\n return [...orders].sort((a, b) => a.totalCents - b.totalCents);\n}\n\nconst sorted = sortByTotal(orders); // DetailedOrder[]\nsorted[0].customer; // stringRead the signature aloud: “for some type T that has a numeric totalCents, take an array of T and return an array of T”. The caller does not write <DetailedOrder>; TypeScript infers T from the argument (the next lesson is about exactly how).
Two parts are doing the work. T appears in the parameter and in the return type, which links them. And extends { totalCents: number } is a constraint: it limits which types T can be, which is what makes a.totalCents legal inside the function. Without it, T could be anything, and TypeScript would reject the property access.
The most useful test for a generic, and the one I apply in every code review: each type parameter should appear at least twice. Once to capture a type, once to use it somewhere else.
\nfunction lastItem<T>(items: T[]): T | undefined { // input → output\n return items[items.length - 1];\n}\n\nfunction indexById<T extends { id: number }>(items: T[]): Map<number, T> {\n return new Map(items.map((item) => [item.id, item]));\n}\n\nfunction merge<A, B>(a: A, b: B): A & B { // two inputs → output\n return { ...a, ...b };\n}A parameter that appears once links nothing. function log<T>(value: T): void is just function log(value: unknown): void with extra syntax, and function count<T>(items: T[]): number is items: unknown[]. Remove those type parameters; the signatures get easier to read and nothing is lost.
This error confuses almost everyone the first time:
\ntype Shippable = { weightGrams: number };\n\nfunction withDefaultWeight<T extends Shippable>(): T {\n return { weightGrams: 500 };\n // Error: Type '{ weightGrams: number; }' is not assignable to type 'T'.\n // '{ weightGrams: number; }' is assignable to the constraint of type 'T', but 'T'\n // could be instantiated with a different subtype of constraint 'Shippable'.\n}The constraint says T is at least Shippable. The caller might ask for withDefaultWeight<{ weightGrams: number; sku: string }>(), and your literal has no sku. Inside a generic function, T is a type you do not get to choose; you can only produce a T from values that already are one, such as the arguments. If your function builds the value itself, its return type is the constraint (Shippable), and no generic is needed.
A constraint can refer to another type parameter. The classic case picks a property by name:
\nfunction pluck<T, K extends keyof T>(items: T[], key: K): T[K][] {\n return items.map((item) => item[key]);\n}\n\nconst customers = pluck(orders, 'customer'); // string[]\npluck(orders, 'email');\n// Error: Argument of type '\"email\"' is not assignable to parameter of type 'keyof DetailedOrder'.keyof T is the union of T’s property names, and T[K] is the type of the property K. You will take both apart in section 3; for now, notice the pattern. K appears in the parameter and in the return type, and its constraint ties it to T. Each parameter appears at least twice, and each one earns its place.
Not every function that accepts several types needs a type parameter. Ask one question: does the output type depend on which input type the caller passed?
\n// Output is always a number, whatever came in: a union is enough.\nfunction toCents(amount: number | string): number {\n return Math.round(Number(amount) * 100);\n}\n\n// Output depends on the input: a generic says so.\nfunction firstOrThrow<T>(items: T[]): T {\n if (items.length === 0) throw new Error('Expected at least one item');\n return items[0];\n}toCents returns number no matter what, so making it toCents<T extends number | string>(amount: T): number would add a parameter that appears once and links nothing. firstOrThrow is the opposite: a list of orders must give back an order, and a list of products a product. A union signature (items: unknown[]): unknown) would force every caller to cast.
When you are unsure, start without the generic. If callers start writing as on the result, that is the signal the output depends on the input, and a type parameter will remove those casts.
In the exercise you will turn four lossy helpers into generic ones that keep the caller’s types. Next lesson looks at how TypeScript decides what T is when the caller does not say.
T extends { totalCents: number } lets the function use totalCents while still returning the caller’s full, more specific type.","A generic that appears only in the return type, like parse<T>(text): T, is an unchecked cast with nicer syntax.","The caller chooses T, not the function, which is why you cannot return a literal object where T is expected."],"further":[{"title":"Generics","url":"https://www.typescriptlang.org/docs/handbook/2/generics.html"},{"title":"More on Functions (generic functions and constraints)","url":"https://www.typescriptlang.org/docs/handbook/2/functions.html#generic-functions"}],"quiz":[{"q":"What is the type of sorted?
type DetailedOrder = { id: number; totalCents: number; customer: string };\ndeclare const orders: DetailedOrder[];\nfunction sortByTotal(xs: { totalCents: number }[]) { return [...xs].sort((a, b) => a.totalCents - b.totalCents); }\nconst sorted = sortByTotal(orders);DetailedOrder[], because the array holds DetailedOrder values","why":"The values are still full orders at runtime, but the return type is computed from the parameter type, which only knows totalCents."},{"text":"{ totalCents: number }[], so sorted[0].customer is an error","why":"Correct. Without a type parameter, the function has no way to say “I return the same kind of thing you gave me”."},{"text":"any[], because sort returns any","why":"sort returns the array’s own element type. The loss of information comes from the parameter annotation."}],"answer":1},{"q":"Which of these signatures uses its type parameter in a way that adds real type safety?
","options":[{"text":"function log<T>(value: T): void","why":"T appears once, so it links nothing. value: unknown says the same thing more honestly."},{"text":"function parse<T>(json: string): T","why":"T only appears in the return type, so the caller picks any type and nothing checks it. It is a cast in disguise."},{"text":"function lastItem<T>(items: T[]): T | undefined","why":"Correct. T appears in the input and the output, linking them, so the caller gets back exactly the element type they passed in."},{"text":"function count<T>(items: T[]): number","why":"T appears only once in a position that matters; items: unknown[] works identically."}],"answer":2},{"q":"Why is this an error?
\nfunction emptyCart<T extends { items: string[] }>(): T {\n return { items: [] };\n}[] is inferred as never[].","why":"never[] is assignable to string[]. The problem is the relationship between the literal and T."},{"text":"Because generic functions cannot return object literals.","why":"They can, when the literal’s type is what the return type says. Here the return type is the caller’s T, which you do not know."},{"text":"Because the caller chooses T, which might be { items: string[]; owner: string }, and your literal has no owner.","why":"Correct. The error says T could be instantiated with a different subtype of the constraint. Return the constraint type instead."}],"answer":2}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"function sortByTotal(orders: { totalCents: number }[]): { totalCents: number }[] {\n return [...orders].sort((a, b) => a.totalCents - b.totalCents);\n}\n\nfunction indexById(items: { id: number }[]): MapThese four helpers from Cartwheel’s order history page work at runtime but lose type information. Make each one generic so the type tests pass:
\nsortByTotal returns a sorted copy typed as the caller’s element type, and still rejects objects without totalCents.indexById returns a Map from id to the caller’s element type.pluck(items, key) only accepts real property names and returns an array of that property’s type.lastItem returns the last element, typed as the element type or undefined.Keep the runtime behaviour the same, and do not use any or as.
extends: <T extends { totalCents: number }> lets you read totalCents while returning T[].","For pluck, use two type parameters: <T, K extends keyof T>(items: T[], key: K): T[K][]."],"explanation":"Each type parameter now appears at least twice, linking the input to the output, so the caller gets back exactly the element type they passed in. The constraints (extends { totalCents: number }, extends { id: number }) are what make the property reads legal inside the functions, and they are also what rejects [{ sku: 'TENT-2P' }]. In pluck, K extends keyof T ties the key to the items, and T[K] looks up that property’s type, so 'customer' gives string[] and 'email' is refused.
sortByTotal sorts ascending without mutating its input","indexes":"indexById maps each id to its item","plucks":"pluck and lastItem still work at runtime"}},"words":749,"readMinutes":4}