Type Argument Inference

## The two halves of a generic call A generic function declares one or more **type parameters** — placeholders in angle brackets that stand for a type the caller decides. `declare function first<T>(items: T[]): T | undefined` declares one, `T`, and then uses it twice: in the parameter type `T[]` and in the return type `T | undefined`. The declaration never says what `T` is. The caller decides, and in ordinary code the caller decides *implicitly*, just by passing an argument. Working out `T` from the arguments is called **type argument inference**. ## Inference sites An **inference site** is a place in the parameter list where a type parameter appears. When you write a call, the compiler: 1. Works out the type of each argument on its own, before looking at the signature. 2. Matches that type structurally against the declared parameter type. 3. Wherever a type parameter appears on the parameter side, whatever sits opposite it on the argument side becomes a **candidate** for that parameter. 4. Fixes the type parameter to a candidate, then substitutes it everywhere in the signature — including the return type. Walking `first([1, 2, 3])` through those steps: the array literal's own type is `number[]`; matching `number[]` against `T[]` lines `number` up opposite `T`; `number` is the only candidate, so `T` is `number`; the call's type is therefore `number | undefined`. ```ts declare function first<T>(items: T[]): T | undefined; const value = first([1, 2, 3]); // ^? number | undefined ``` Notice that the return type did no work. It consumed `T`; it did not supply it. A type parameter that appears **only** in the return type has no inference site at all, and the compiler has to fall back to something else. ## The argument's own type is decided first Inference never reaches inside the argument to redecide it. Whatever the argument's type already is, that is what gets matched: ```ts first(["x"]); // string | undefined first([1, "x"]); // string | number | undefined — the literal is (string | number)[] first([]); // undefined — an empty array literal is never[], so T is never ``` The empty-array case is the one that surprises people. `first([])` is not an error and does not produce `any`; the element type of `[]` is `never`, so `T` is `never` and `T | undefined` collapses to `undefined`. In real code this shows up when an accumulator starts empty. Annotate the variable — `const rows: Row[] = []` — and the call infers `Row` as intended. ## The call's context can also supply a candidate Arguments are the main source, but not the only one. If a call's result flows into a position with a known expected type, that expected type can supply a candidate too — with lower priority than arguments: ```ts declare function make<T>(): T; const name: string = make(); // T is string, taken from the annotation ``` Because argument candidates outrank the contextual one, an annotation cannot override what the arguments already decided. `const w: string | number = pick(1)` still infers `number` for a `pick<T>(v: T): T`. ## Writing the type argument yourself Explicit type arguments are always available as an escape hatch: `first<number>([1, 2, 3])`. Supplying them is all-or-nothing — you must give one for every type parameter unless the trailing ones have defaults, so a two-parameter generic called with a single type argument is rejected. In practice you reach for explicit type arguments only when the call has no usable inference site, or when inference lands somewhere you did not want. ## None of this exists at runtime Types are erased. `first<T>` compiles to an ordinary JavaScript function with no `T` anywhere; inference is a compile-time bookkeeping exercise that produces better editor types and better errors, and costs nothing when the program runs. A function cannot branch on `T`, and no `T` is available to inspect. ## Common misreadings Inference is not a runtime check, it is not driven by the variable name you assign to, and it does not fall back to `any` when it is unsure. It is a structural match between the argument types you actually passed and the parameter types the signature declares — and once you can narrate that match, most "why is this type weird?" questions answer themselves.