Generics Fundamentals

"Every piece of knowledge must have a single, unambiguous, authoritative representation within a system." — Andrew Hunt & David Thomas, The Pragmatic Programmer

So far you have learned to describe concrete shapes: a User, a Course[], a Result with a kind tag. Give TypeScript enough shapes and it can model anything your program touches. But a nagging pattern keeps appearing — the same logic, written again and again, differing only in the type it carries. A function that returns the first element of an array of numbers is identical to the one for strings, and to the one for users, except for one word. Copy it per type and you drown in duplication; erase the type with any and you throw away the very safety you came to TypeScript for. Generics are the third way: write the logic once, over a type you don't name yet, and let the compiler fill it in — differently — at every call. This is the feature that separates a codebase that scales from one that rots, and it is where TypeScript stops feeling like "JavaScript with labels" and starts feeling like a type system.

Core Concepts

The problem: duplicate, or lose safety

Say you want the first element of an array. Without generics you have two bad options. The first is to write the function once per type — pure duplication that drifts out of sync the moment one copy changes:

function firstNumber(arr: number[]): number | undefined { return arr[0]; }
function firstString(arr: string[]): string | undefined { return arr[0]; }
function firstUser(arr: User[]): User | undefined { return arr[0]; }
// …one more for every type you ever hold. This does not scale.

The second is to write it once with any — and watch the return type evaporate. The function compiles for every input, but it hands back a value the compiler no longer understands:

That second console.log is the tragedy. any returned a hole: calling a string method on a number sails past the compiler and blows up in production. You wrote one function, but you paid for it with the entire point of TypeScript.

Type parameters: a placeholder for a type

A generic adds a type parameter — a placeholder for a type, written in angle brackets — that the caller (or the compiler) fills in. The canonical example is the identity function, which returns its argument unchanged. Its type isn't "takes anything, returns anything"; it's the far stronger claim "whatever type goes in, that exact type comes out":

T is not a real type — it's a variable that ranges over types, bound fresh at each call. Two things make this powerful. First, inference: you rarely write the angle brackets, because TypeScript reads T off the argument — identity("hi") infers T = string on its own. Second, explicit supply: when inference can't see enough (an empty array, a wider type than the literal), you name it — identity<number>(1) — and the compiler holds you to it. Either way, first(numbers) gives back number | undefined, first(strings) gives back string | undefined. One function, and the element type rides all the way through.

Generic over containers

The same placeholder works on types, not just functions. A Box<T> is a container whose contents you name at the point of use — the type parameter threads from the declaration into every field:

Box<number> and Box<string> are two distinct, fully-checked types minted from one declaration. That is the whole promise of generics scaled up from functions to data structures — and it's exactly how the standard library is built.

Generics vs any vs unknown

These three are the usual suspects when a type isn't fixed up front, and interviewers love the distinction because it exposes whether you actually understand the type system. The one-word summary: any forgets, unknown withholds, a generic remembers and relates.

any and a generic can look interchangeable at the boundary — both accept anything — but they behave like opposites downstream. Here is the generic version of the earlier failure. Same one function, but this time the type is remembered, so the bug is caught before it ships:

The any version compiled this and detonated at runtime; the generic version paints it red in your editor. Reach for unknown when a value's type is genuinely unknowable at that point (a JSON.parse result, a caught error) and you'll narrow it later. Reach for a generic when the type is known — to the caller — and you want to carry it through your code intact.

The mental model: a type-level function

Here is the idea that makes everything else click: a generic is a function that runs at the type level. An ordinary function takes values and returns a value. A generic takes types and returns a type. identity<T> is a machine you feed the type string and it hands you back the type (x: string) => string. Box<T> is a machine you feed number and it hands you back the object type { value: number }. You already think in functions — value in, value out. Generics are the same reflex one level up: type in, type out. Once you see them that way, the syntax stops being decoration and becomes what it is — parameters, for types.

Conventions, and built-ins you already use

The single-letter names are a decades-old convention, not a rule: T for the primary Type, U for a second, K for a Key, V for a Value, E for an Element or Error. They're fine for small, obvious generics like identity<T>. When a type has several parameters or the meaning isn't self-evident, a descriptive name reads far better — Map<TKey, TValue> or ApiResponse<TData> tells the next reader what belongs where. Clarity beats tradition.

And here's the reassuring part: you've been using generics since Volume 1 without the name. Array<T> (that's what number[] desugars to), Promise<T> (an async function returns Promise<string>), Map<K, V>, Set<T>, Record<K, V> — every one is generic. When you wrote new Map<string, User>(), you supplied two type arguments explicitly. Generics aren't a new dialect; they're the grammar the standard library was already written in.

Common Mistakes

• Reaching for any when you meant a generic. If the type is known to the caller, a generic carries it through safely. any throws that knowledge away and hands you a runtime crash instead of a compile error.
• Writing the type argument the compiler would infer. identity<string>("hi") is noise — TS infers T = string from the argument. Supply it explicitly only when inference genuinely can't.
• A type parameter used exactly once. function log<T>(x: T): void relates nothing — T appears once and vanishes. That's just unknown (or any) with extra ceremony. A generic earns its keep by connecting two or more positions.
• Confusing the declaration with the use. In Box<T>, T is the parameter (declared); in Box<number>, number is the argument (supplied). Mixing them up — writing Box<T> where you meant Box<number> — leaves you with an unbound T.
• Assuming a generic constrains anything. Bare <T> accepts every type, so inside the function you can't assume T has a .length or an .id. Narrowing that is the job of constraints — a later chapter — not of the plain type parameter.

Interview Corner

Chapter Summary

• Generics let you write one reusable, type-safe thing that works over many types — the alternative to duplicating code per type or erasing it with any.
• A type parameter (<T>) is a placeholder for a type, bound fresh at each call; identity<T>(x: T): T captures the relationship "input type = output type."
• TypeScript usually infers the type argument from the arguments; supply it explicitly (identity<number>(1)) only when inference can't see enough.
• The same placeholder types data, not just functions: Box<T> and first<T> thread the element type all the way through.
• any forgets a type, unknown withholds it until you narrow, a generic remembers and relates it — full safety with no re-checking.
• The mental model is a type-level function: types go in, a type comes out. Conventions (T, U, K, V, E) are habit; descriptive names like TData win when clarity matters.
• You've used generics all along — Array<T>, Promise<T>, Map<K, V> are the standard library written in this exact grammar.

Editorial reflection — generics are the first idea in this Volume that asks you to think one level up — not "what type is this value?" but "what is the relationship between these types?" That shift feels abstract for about a day, and then it becomes the way you see code. The engineers who never make the jump keep reaching for any at every boundary and calling it pragmatism; the ones who do write a single small abstraction that a whole team leans on safely for years. The syntax is five characters of angle brackets. The mindset is the entire craft.