Library generics: APIs that infer beautifully (and the ones that don't)

The goal: the caller writes values, the compiler writes types

The north star of generic API design: a caller should pass ordinary values and get back precise types without writing a single type argument. Every <T> the caller is forced to type is a design failure — it’s a type the API should have inferred. Inference happens at inference sites: positions in the signature where a type parameter appears in a parameter’s type, letting the compiler read it off the argument.

// forces the caller to specify K — bad
function getBad<T, K extends keyof T>(obj: T, key: K): T[K] { return obj[key]; }
getBad<{ a: number }, "a">({ a: 1 }, "a"); // ugh

// infers both from the arguments — good
function get<T, K extends keyof T>(obj: T, key: K): T[K] { return obj[key]; }
get({ a: 1, b: "x" }, "b"); // ^? string  — T and K both inferred, no type args

Same signature, but the second call site supplies values at both inference sites (obj fixes T, key fixes K), so nothing must be written by hand. The return T[K] is then precise — string, not the constraint keyof-something.

Return the precise type, never the constraint

A classic leak: constraining a parameter and then returning the constraint instead of the inferred type. The caller loses all the specificity they passed in.

// returns the constraint — caller gets the wide type back
function firstWide<T extends unknown[]>(arr: T): unknown { return arr[0]; }
const a = firstWide([1, 2, 3]); // ^? unknown  — specificity thrown away

// returns the precise element type via inference
function first<T>(arr: readonly T[]): T | undefined { return arr[0]; }
const b = first([1, 2, 3]); // ^? number | undefined

The fix is to make T the element type (so it’s inferred precisely) rather than constraining T to be the whole array and returning a widened piece. Returning the constraint is the single most common way a library “loses types.”

Constraints + defaults for ergonomics

What if you want a generic that infers its primary type parameter from the argument but still lets advanced callers override a secondary one? That is exactly the gap constraints and defaults fill.

Constraints (T extends ...) keep callers honest and unlock member access inside the body; defaults (T = ...) make a parameter optional when inference can’t supply it (e.g. a config object never passed). Used together they let one signature serve the common case with zero ceremony and the advanced case with an explicit override:

function createStore<State, Action = { type: string }>(initial: State) {
  return { state: initial } as { state: State; dispatch: (a: Action) => void };
}
const s = createStore({ count: 0 }); // State inferred {count:number}, Action defaulted

NoInfer: block an unwanted inference site

Sometimes a type parameter appears in two positions and you only want one of them to drive inference. Pre-5.4 you needed an intersection hack; TS 5.4 added the built-in NoInfer<T>:

// without NoInfer: TS widens C from BOTH the array and the default,
// so a typo'd default still "works" by widening the union
function pick<C extends string>(choices: C[], fallback: C): C { /* ... */ return fallback; }
pick(["a", "b"], "c"); // C inferred as "a" | "b" | "c" — the bug "c" is accepted!

// with NoInfer: only `choices` is an inference site; fallback must match it
function pickSafe<C extends string>(choices: C[], fallback: NoInfer<C>): C { return fallback; }
pickSafe(["a", "b"], "c"); // Error: "c" is not assignable to "a" | "b"

NoInfer<C> tells the compiler “don’t read C off this argument” — so C is fixed by choices alone, and fallback is checked against it rather than widening it. This is the precise tool for “this parameter must conform to a type already determined elsewhere.”

Builders that accumulate types

Fluent builders (the pattern behind zod, the tRPC router, query builders) thread an evolving type through each chained call by returning a new generic instance:

class Query<Cols extends string = never> {
  select<C extends string>(col: C): Query<Cols | C> { return this as any; }
  build(): Cols[] { return [] as Cols[]; }
}
const cols = new Query().select("id").select("name").build();
// ^? ("id" | "name")[]  — each .select widened the accumulated Cols union

Each select returns Query<Cols | C>, so the type grows along the chain and build() reports exactly the columns selected. This is how a query builder knows its result row shape, and how the tRPC router (lesson 3) accumulates its procedure map — each .procedure(...) call adds to the router’s type.