Generic functions

A function over types

A normal function abstracts over values: you pass 3 or "x" and the body runs the same way. A generic function abstracts over types: you pass a type (explicitly or, far more often, implicitly) and the signature specialises to it.

function identity<T>(x: T): T {
  return x;
}

const a = identity("hello");
//    ^? const a: "hello"
const b = identity(42);
//    ^? const b: number

The <T> declares a type parameter — a placeholder in type space, exactly like a value parameter is a placeholder in value space. At each call site the checker picks a concrete type for T and the return type follows.

Inference: the checker solves for T

You almost never write identity<string>("hello"). Instead the checker performs type argument inference: it matches each argument’s type against the parameter that uses the type variable and solves for it.

function wrap<T>(value: T): { value: T } {
  return { value };
}

const w = wrap([1, 2, 3]);
//    ^? const w: { value: number[] }

Here value: T is matched against the argument [1, 2, 3] (inferred as number[]), so T = number[], and the return type is computed as { value: number[] }. The inference flows from the argument position into T, then back out through the return position.

Explicit vs inferred type arguments

You can supply the type argument by hand, and sometimes you must — when there are no arguments to infer from, or when you want a wider type than inference would pick.

function make<T>(): T[] {
  return [];
}

const xs = make();
//    ^? const xs: unknown[]   — nothing to infer from, T falls to unknown
const ys = make<string>();
//    ^? const ys: string[]    — explicit type argument

When you write nothing and there is nothing to infer, an unconstrained T resolves to unknown (not any) under modern defaults. Explicit type arguments are also useful to narrow inference: wrap<readonly number[]>([1, 2, 3]) forces a readonly element type that inference alone would not pick.

Multiple type parameters, and pluck

Real signatures often carry several type variables that the checker solves independently:

function pair<A, B>(a: A, b: B): [A, B] {
  return [a, b];
}

const p = pair("id", 7);
//    ^? const p: [string, number]

The single most useful generic shape in application code is pluck / prop — read a key off an object and get back exactly that property’s type. (The K extends keyof T machinery is the next lesson; here, just see why two parameters are needed.)

function prop<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

const user = { id: 1, name: "Ada" };
const n = prop(user, "name");
//    ^? const n: string
const id = prop(user, "id");
//    ^? const id: number

T is solved from obj, K from key, and the return type T[K] (an indexed access — that was last lesson) gives back the precise property type. Two parameters, each appearing twice.

The “appears at least twice” rule

Here is the rule that separates real generics from cargo-cult ones: a type parameter that appears only once in the signature is almost always a mistake. A type variable earns its keep by relating two positions — an argument to a return, or two arguments to each other. If it appears once, it relates nothing, and it is silently equivalent to any at that spot.

// SMELL: T appears only in the parameter, never related to anything.
function logAndDrop<T>(x: T): void {
  console.log(x);
}
// Identical in behaviour and safety to:
function logAndDrop2(x: unknown): void {
  console.log(x);
}

// WORSE: T appears only in the return — the caller invents T from nothing.
function parse<T>(text: string): T {
  return JSON.parse(text);
}
const cfg = parse<{ port: number }>("{}");
//    ^? const cfg: { port: number }   — a LIE; runtime value is {}

In parse<T>, T is unconstrained by any argument, so the caller’s annotation is an unchecked assertion. That single-use return-position T is one of the most common sources of “the types said it was fine, production said otherwise.”

What over-generic code costs the compiler

A <T> that earns its keep is nearly free; a <T> sprinkled everywhere is not. The number to watch is type instantiations, which tsc --extendedDiagnostics reports. A leaf utility module that types its data plainly might show on the order of tens of thousands of instantiations; rewrite the same helpers so every signature is generic and chained (each call re-solving T and substituting it through several more generic callees) and the count climbs into the hundreds of thousands — Instantiations: 412,300 against a former 38,900 is a realistic delta for one over-abstracted utilities file, and it shows up directly as a few hundred extra milliseconds of Check time on each incremental rebuild. Generics are a compile-time loop the checker runs per call site; cheap per instantiation, but you can write a lot of them.

The runaway case is recursive generics. The checker caps how deeply it will instantiate a generic alias before giving up: hit roughly 50 levels of nesting and you get Type instantiation is excessively deep and possibly infinite (TS error 2589) — the same depth ceiling that bounds recursive conditional types. A single fluent builder typed as Builder<readonly [A]> → Builder<readonly [A, B]> → … walks straight into this wall once a chain gets long, and the only fixes are to break the recursion or fall back to a non-generic shape.