Implementation Signature Compatibility
You'll learn: How to write an implementation signature that TypeScript accepts for all your overload signatures and correctly handles every possible call case internally.
The Compatibility Rule
When you write function overloads, TypeScript requires that your implementation signature be compatible with every overload signature you declare. Think of it like making a promise: each overload is a specific promise you're making to callers, and your implementation must be capable of keeping all those promises.
The implementation signature must:
- Accept all possible parameter combinations from the overloads
- Return a type that satisfies all overload return types
- Handle every case internally with proper logic
Why This Matters
TypeScript doesn't let you write an implementation that can't possibly fulfill what the overloads promise. If an overload says "you can call this with a number," but your implementation only accepts strings, the compiler catches this mismatch.
The implementation signature itself is invisible to callers—they only see the overload signatures. This means you often make it more permissive (using unions) to accommodate all overloads.
Making It Compatible
To satisfy all overloads, you typically:
- Use union types for parameters that vary across overloads
- Use union return types or a broad return type that covers all cases
- Add type guards inside the function body to route logic correctly
- Make parameters optional if some overloads don't require them
The implementation signature acts as the "catch-all" that must work no matter which overload the caller matched.
Common Pitfall
If your implementation signature is too narrow (accepts fewer cases than the overloads promise), TypeScript will reject it at compile time. The overloads create the contract; the implementation must honor it.
Key Takeaway: The implementation signature must be a superset of all overload signatures—accepting every parameter combination they allow and returning compatible types—while internally routing logic to fulfill each specific case.