TypeScript Function Overloads
debt(d3/e3/b3/t5)
Closest to 'default linter catches the common case' (d3). Common mistakes like putting the implementation signature before overload signatures or making the implementation narrower than the overloads are caught by the TypeScript compiler itself at compile time — essentially the default toolchain. No specialist tools are listed in detection_hints.tools (empty), but the TypeScript compiler as a standard part of the ecosystem catches ordering and compatibility errors immediately.
Closest to 'simple parameterised fix' (e3). The quick_fix describes replacing a union return type with overload signatures, or correcting overload ordering/narrowing issues. This is a localised refactor within one function's declaration — more than a single-line swap but contained to the function signature and implementation block, not spread across multiple files.
Closest to 'localised tax' (b3). Overloads apply to individual functions and their callers. The misconception and common_mistakes indicate the cognitive tax is felt at the function definition site and by direct callers, but the rest of the codebase is generally unaffected. The applies_to field is unspecified, suggesting no system-wide reach.
Closest to 'notable trap' (t5). The canonical misconception — that the implementation signature is visible to callers — is a documented gotcha that many developers encounter when first using TypeScript overloads. The 'obvious' assumption that what you write in the implementation is what callers see contradicts TypeScript's actual behaviour, but it's a learnable and well-documented surprise rather than a catastrophic or architecturally dangerous one.
Also Known As
TL;DR
Explanation
A function overload consists of two or more overload signatures (no body) followed by one implementation signature (with body). TypeScript uses the overload signatures for type checking and IDE autocomplete — the implementation signature is hidden from callers. Overloads are useful when the return type depends on the input type (e.g. createElement('div') returns HTMLDivElement, createElement('canvas') returns HTMLCanvasElement), or when a function accepts fundamentally different argument shapes. The implementation must be compatible with all overload signatures. Method overloads work the same way in classes.
Watch Out
Common Misconception
Why It Matters
Common Mistakes
- Putting the implementation signature before the overload signatures — TypeScript requires all overload signatures first, then the implementation.
- Making the implementation signature narrower than the overloads — the implementation must accept the union of all overload parameters.
- Using overloads when conditional types or generics would be cleaner — overloads are best for a small number of distinct cases; for many cases use generics with conditional return types.
- Exposing too many overloads — each overload adds cognitive load; prefer 2–4 well-chosen overloads over exhaustive enumeration.
Avoid When
- When a union type or optional parameters can express the same behavior more simply — overloads add maintenance burden if the type relationship is straightforward.
- When the function logic is identical regardless of input type — use a generic or a single signature with wider types instead.
- When you have more than 3–4 overload signatures — the implementation becomes hard to reason about; consider splitting into separate functions or using discriminated unions.
- When overload signatures don't genuinely constrain the caller's input or clarify the return type — this creates false precision and confuses rather than helps.
When To Use
- When a function's return type must change based on a specific input parameter value or type, and a union return type would be too broad for callers to safely use without type guards.
- When a function accepts fundamentally different argument shapes (e.g. accepting either a string filename or a Buffer object) and treating them as a single union would obscure the valid combinations from callers.
- When wrapping or reimplementing a DOM or library API (like createElement or fetch) that has well-defined type relationships between arguments and return values that you want to preserve exactly.
- When you have optional parameters where omitting them changes the return type—overloads can express 'no arguments → one return type' and 'with argument → different return type' more clearly than optional parameter unions.
Code Examples
// ❌ Union return type — caller must narrow every time
function parseInput(input: string | number): string | number {
if (typeof input === 'string') return input.toUpperCase();
return input * 2;
}
const result = parseInput('hello');
// result: string | number — TypeScript doesn't know it's string
result.toUpperCase(); // Error: Property 'toUpperCase' does not exist on type 'string | number'// ✅ Overloads — return type matches input type
function parseInput(input: string): string;
function parseInput(input: number): number;
function parseInput(input: string | number): string | number {
if (typeof input === 'string') return input.toUpperCase();
return input * 2;
}
const s = parseInput('hello'); // TypeScript knows: string
s.toUpperCase(); // ✓ No error
const n = parseInput(42); // TypeScript knows: number
n.toFixed(2); // ✓ No error
// Class method overload
class EventEmitter {
on(event: 'data', listener: (data: Buffer) => void): this;
on(event: 'error', listener: (err: Error) => void): this;
on(event: string, listener: Function): this {
// implementation
return this;
}
}