In TypeScript a function is overloaded as `(x: string): string` and `(x: number): number`. A caller holds a value typed `string | number` and passes it — why is that a compile error, and what are the options?

## Why the union argument fails Overload resolution picks **one** signature. The compiler tries each header in order and asks whether the arguments are assignable to it; it never merges two headers into a combined signature that would accept a union. A value typed `string | number` is assignable to neither `(x: string)` nor `(x: number)`, so nothing matches and you get `No overload matches this call.` ```ts function format(value: string): string; function format(value: number): number; function format(value: string | number): string | number { return typeof value === "string" ? value.trim() : Math.round(value); } declare const raw: string | number; // format(raw); // No overload matches this call. ``` This is not an oversight. If the compiler did split the union across headers, it would have to produce `string | number` as the result — which is exactly the correlation the overloads existed to preserve. Refusing the call keeps the promise honest and pushes the decision back to the caller. ## Option one: narrow at the call site ```ts if (typeof raw === "string") { const s = format(raw); // string } else { const n = format(raw); // number } ``` Inside each branch the argument has a single type, so resolution succeeds and the caller gets the precise result type. This is usually the right answer, because the caller in the union case genuinely does not know which result type it will receive — the compile error is telling the truth about the caller's own uncertainty, not obstructing it. ## Option two: add a union header Append a header covering the union, below the precise ones: ```ts function format(value: string): string; function format(value: number): number; function format(value: string | number): string | number; ``` Now the union call compiles, but the result is `string | number` and the caller must re-narrow it. That is honest, and it keeps precise calls precise because ordering puts the narrow headers first. The cost is a third unverified promise about the same body and a wider public surface. ## Option three: drop overloads for one signature If you find yourself adding the union header for every combination, that is a signal the overload list is not earning its place: ```ts function format(value: string | number): string | number { /* ... */ } ``` One signature, no ordering hazard, nothing unchecked. Callers narrow the result, which they were going to do anyway. ## The choosing rule Ask one question: **does the return type depend on which argument form was used?** - **It does, and the forms are a small fixed set.** Overloads are the right tool. Different arities that mean different things belong here too. - **It does not — every form returns the same type.** Use a single signature with a union or optional parameters. Overloads buy nothing and cost order-dependence plus an unproven per-form promise. - **The result type is a function of the argument's own type, not of a fixed list of forms.** That is a generic's job — a type parameter carries the caller's type through to the result, and unlike an overload list it scales to types you have never enumerated. Overloads cannot express "whatever came in comes back" for open-ended input, and a growing overload list that keeps repeating the same shape is the symptom. ## Practical differences that decide close calls **Call sites.** Overloads give the cleanest error messages and the cleanest editor hints for a small set of forms: the tooltip lists the legal shapes. A generic with an involved constraint often shows the caller a signature that is harder to read. **Combinatorics.** Overloads multiply. Two independent optional dimensions become four headers, and each header is a separate promise about the same body. A generic or a single union signature stays flat. **Union arguments.** As above, overloads reject them by design. If your callers routinely hold union-typed values — data coming out of a parser, a config lookup, a message queue — an overload list will fight them at every call, and a single signature that returns a union they narrow is friendlier. **Verification.** A union-parameter signature is checked normally against the body. An overload header is not: nothing proves the branch serving it returns what it promised. That asymmetry alone should make overloads the exception rather than the default. ## What to say in an interview Lead with the mechanism — one signature is chosen, unions are never split across headers — then give the three options and the choosing rule in the same breath. The mark of experience is not knowing that overloads exist but saying out loud when you would *not* use them: same return type across forms, open-ended input types, or callers who mostly hold unions.