Overload Signatures

## The rule When a function has an overload list, the compiler tries the signatures **in the order they are written** and commits to the **first** one the call's arguments are assignable to. It does not gather all viable candidates and pick the most specific; there is no specificity ranking and no ambiguity error. First match wins. That single rule turns the order of an overload list into part of the function's meaning. Reordering two headers can silently change the type of every call site. ## The ordering bug ```ts function getSetting(key: string): unknown; function getSetting(key: "retries"): number; function getSetting(key: string): unknown { return key === "retries" ? 3 : undefined; } const retries = getSetting("retries"); // unknown, not number ``` The literal `"retries"` is assignable to `string`, so the first header matches and resolution stops there. The result is `unknown`, and any arithmetic on it fails to compile with an error that looks like it is about the wrong thing. The second header is unreachable — dead code the compiler does not flag. Swap the two headers and `getSetting("retries")` is `number` while other keys still fall through to the general form. The same shadowing appears with arity and optionality: ```ts function on(event: string, handler: (...args: unknown[]) => void): void; function on(event: "click", handler: (x: number, y: number) => void): void; ``` Every call matches the first header, so the precise `"click"` handler typing never applies. ## Ordering heuristics that work - **Literal types before the primitive they belong to** — `"retries"` above `string`, `0` above `number`. - **Fixed arities before variadic or optional forms** — a two-parameter header above one ending in a rest parameter. - **Concrete object shapes before wide ones** — a header taking a specific interface above one taking `Record<string, unknown>`. - **Anything taking `any` or `unknown` goes last**, because such a header matches almost every call and will swallow the list. A useful mental check: read the list top to bottom and ask, for each header, "is there a call this header accepts that a header above it also accepts, but which should have gone to mine?" If yes, move it up. ## When nothing matches If no signature accepts the call, the compiler reports `No overload matches this call.` It then elaborates by explaining why one particular candidate failed — usually the last one — which is why the message often complains about a signature you never intended to use. Read the whole diagnostic, not the last line: the elaboration is a report about one candidate, not a claim that the others were closer. Ordering also interacts with the fact that only the headers participate in resolution. The implementation signature is never a candidate, however permissive it looks, so a call that "obviously should work" because the implementation accepts it will still be rejected. ## Why the compiler works this way First-match resolution is simple, predictable and cheap: the checker never has to define what "most specific" means across unions, optionality, generics and structural subtyping — a relation that is not even a total order in a structural type system. The cost is pushed onto the author, who must express intent through ordering. That is a deliberate trade, and it is why every review of an overload list should look at the order first. ## Consequences for API design Because order is meaning, an overload list is fragile in ways a single signature is not. Adding a convenience header at the top of an existing list can silently retype every call site in a codebase and produce no error at the definition. Prefer appending new, narrower headers **above** the general catch-all and below any narrower ones, and treat the list's order as covered by tests: a type-level check per advertised form — assign each call's result to a variable of the expected type — catches a shadowed header immediately, which is the only thing that will. ## What to say in an interview State the rule, then demonstrate the shadowing bug with a literal-versus-`string` pair and show the fix by reordering. Adding that the compiler performs no specificity ranking, and that a shadowed overload is never reported as dead, is what separates a memorised answer from an understood one.