Function overloads

One function, two kinds of answer

Some JavaScript functions give back a different kind of value depending on what you pass. This one reads prices typed into a form. Give it one price as text, and it gives back a number. Give it a list of prices, and it gives back a list of numbers:

function parsePrice(input) {
  return Array.isArray(input) ? input.map(Number) : Number(input);
}

console.log(parsePrice("4"));
console.log(parsePrice(["3", "4"]).join(", "));

Line 2 checks whether input is a list with Array.isArray. If it is, it turns every item into a number with map; if not, it turns the one text into a number. Line 5 prints 4, and line 6 prints 3, 4.

How would you type it? The Union types lesson suggests string | string[] for the parameter. That works for the input, but look at what comes back:

1function parsePrice(input: string | string[]) {2  return Array.isArray(input) ? input.map(Number) : Number(input);3}4 5const price = parsePrice("4");6//    ^?7console.log(price.toFixed(2));

Line 1 takes a string or a list of strings. Line 5 passes "4", a string, so you know the answer is a number. But the query on line 6 shows const price: number | number[]: TypeScript only knows the function returns one or the other. So line 7 gets an error, on purpose here: Property 'toFixed' does not exist on type 'number | number[]'. It means "this might be a list, and lists don't have toFixed". The code runs fine and prints 4.00; the type is just too vague.

Overloads fix this. You list each way the function can be called, with the type it gives back for that way:

1function parsePrice(input: string): number;2function parsePrice(input: string[]): number[];3function parsePrice(input: string | string[]) {4  return Array.isArray(input) ? input.map(Number) : Number(input);5}6 7const price = parsePrice("4");8//    ^?9const prices = parsePrice(["3", "4"]);10//    ^?11console.log(price.toFixed(2));12console.log(prices.length);

Lines 1 and 2 are the two ways to call it: with a string, you get a number; with a list of strings, a list of numbers. Lines 3 to 5 are the function itself. Now the query on line 8 shows const price: number, and the query on line 10 shows const prices: number[]. Line 11 prints 4.00 with no error, and line 12 prints 2.

Overload signatures

A signature is a function's parameters and return type, without its body, like (input: string): number. An overloaded function is written in two parts:

• Overload signatures: usually two or more lines that start like a function but have no body. Each ends with a ;, and you write its return type.
• The implementation: the function with a body, written right after them, with the same name. Its own signature has to cover every overload.

When you call the function, TypeScript tries the overload signatures from the top and uses the first one that fits. Type a different argument on line 7 and watch which signature it picks:

1function parsePrice(input: string): number;2function parsePrice(input: string[]): number[];3function parsePrice(input: string | string[]) {4  return Array.isArray(input) ? input.map(Number) : Number(input);5}6 7const result = parsePrice("4");8//    ^?9console.log(JSON.stringify(result));

"4" fits the first signature, so result is a number. ["3", "4"] and [] fit the second, so it's a number[]. For 4 or [3, 4], TypeScript says No overload matches this call. Read the lines under it in the list: Overload 1 of 2, '(input: string): number', gave the following error, then the reason, and the same for overload 2. It shows how each signature turned the argument down. For two arguments, it says Expected 1 arguments, but got 2.

Overload signatures are types, so they disappear when the types are removed. Here is what the browser gets for the example above:

function parsePrice(input) {
  return Array.isArray(input) ? input.map(Number) : Number(input);
}

const price = parsePrice("4");
const prices = parsePrice(["3", "4"]);
console.log(price.toFixed(2));
console.log(prices.length);

Lines 1 and 2 of the TypeScript are gone, and so are the types. There is one function, and its own code, the Array.isArray check on line 2, decides what to do. JavaScript doesn't pick between bodies when it runs; overloads only tell TypeScript what each call gives back.

The implementation signature

The signature on the function with the body is called the implementation signature. It has three rules that surprise people. First, callers can't see it:

1function welcome(name: string): string;2function welcome(name?: string) {3  return "Hello, " + (name ?? "guest");4}5 6console.log(welcome("Asha"));7console.log(welcome());

Line 1 is the only overload: welcome takes a name. Line 2's implementation makes the name optional with name?, and line 3 uses "guest" when it's missing. Line 6 prints Hello, Asha. Line 7 calls welcome() with no name, and TypeScript says Expected 1 arguments, but got 0, on purpose here. Callers only see line 1. If you want a call with no name, write an overload for it. Run it anyway, and line 7 prints Hello, guest.

Second, the implementation signature must cover every overload:

1function parsePrice(input: string): number;2function parsePrice(input: string[]): number[];3function parsePrice(input: string) {4  return Number(input);5}

Line 2 promises callers they can pass a list of strings, but line 3's implementation only takes a string. TypeScript marks line 2: This overload signature is not compatible with its implementation signature. It means "the function below can't take what this line promises". Fix it by widening line 3 to input: string | string[], as in the overview.

Third, TypeScript checks the body only against the implementation signature, not against each overload:

1function parsePrice(input: string): number;2function parsePrice(input: string[]): number[];3function parsePrice(input: string | string[]) {4  return Array.isArray(input) ? Number(input[0]) : [Number(input)];5}6 7const price = parsePrice("4");8//    ^?9console.log(price.toFixed(2));

Line 4 has the two branches swapped: a list gives back one number, and a string gives back a list. Both are allowed by the implementation's return type, number | number[], so there are no errors. The query on line 8 still trusts line 1 and says const price: number. When it runs, price is really [4], and line 9 throws a TypeError. Overloads are promises you make; keep the body honest, and test it.

Overloads vs unions

TypeScript matches a call with one overload. That matters when the argument itself is a union, like a search that may hold one word or several:

1function countItems(items: string): number;2function countItems(items: string[]): number;3function countItems(items: string | string[]) {4  return items.length;5}6 7function countSearch(query: string | string[]) {8  return countItems(query);9}10console.log(countSearch(["tea", "cake"]));

Lines 1 and 2 take a string or a list, and both give back a number. Line 7's query may be either, so on line 8 neither overload fits the whole thing, and TypeScript says No overload matches this call. When it runs, line 10 prints 2, because the body handles both. The overloads add nothing here: the return type is the same either way. One union parameter is all you need:

1function countItems(items: string | string[]) {2  return items.length;3}4 5function countSearch(query: string | string[]) {6  return countItems(query);7}8console.log(countSearch(["tea", "cake"]));

Line 1 takes string | string[] and returns a number. Line 6 passes query with no error, and line 8 prints 2.

parsePrice is different: its return type does depend on the argument, so you keep the overloads. To let a union through as well, add a third signature that takes the union. Where you put it matters. Try the three choices:

1function parsePrice(input: string): number;2function parsePrice(input: string[]): number[];3// no overload for string | string[] yet4function parsePrice(input: string | string[]) {5  return Array.isArray(input) ? input.map(Number) : Number(input);6}7 8function readSearch(query: string | string[]) {9  return parsePrice(query);10}11 12const price = parsePrice("4");13//    ^?14console.log(JSON.stringify(readSearch(["3", "4"])));

With Two overloads, line 9 gets an error. Union overload last fixes it and keeps price a number. Union overload first also has no errors, but every string now matches line 1, so price becomes number | number[] again, as if you had no overloads at all.

The table below compares the two tools. Read each row as a question, then the answer for each.

When not to overload

Overloads are worth it when the return type depends on the arguments. Otherwise a plain signature is shorter and easier to call. Here are two overloads that differ only by a last parameter:

1function padding(all: number): string;2function padding(vertical: number, horizontal: number): string;3function padding(vertical: number, horizontal?: number) {4  return horizontal === undefined ? vertical + "px" : vertical + "px " + horizontal + "px";5}6 7function cardPadding(gap?: number) {8  return padding(8, gap);9}

Line 1 makes CSS padding from one size, and line 2 from two. Line 7's cardPadding has an optional gap, so gap is number | undefined. Line 8 passes two arguments, so only line 2 can match, and it needs a number: Argument of type 'number | undefined' is not assignable to parameter of type 'number'. Both overloads return a string, so an optional parameter says the same thing in one line:

1function padding(vertical: number, horizontal?: number) {2  return horizontal === undefined ? vertical + "px" : vertical + "px " + horizontal + "px";3}4 5function cardPadding(gap?: number) {6  return padding(8, gap);7}8console.log(cardPadding());9console.log(cardPadding(16));

Line 1 makes horizontal optional, and line 6 passes gap with no error. Line 8 prints 8px and line 9 prints 8px 16px.

And when you do overload, order matters, because TypeScript stops at the first signature that fits. Put general signatures, like one that takes a union, after the precise ones:

The table below sums up the choices. Read each row as: when your overloads look like this, write this instead.

Overloads you already use: createElement

You've used overloaded functions already. The browser's types give document.createElement three signatures. The first takes any tag name the browser knows, like "input", and returns that exact kind of element. The second does the same for a few old tag names. The last, general one takes any other name:

1const input = document.createElement("input");2//    ^?3const banner = document.createElement("div");4//    ^?5const widget = document.createElement("cart-widget");6//    ^?7input.value = "2";8console.log(input.value, banner.tagName, widget.tagName);

The query on line 2 shows const input: HTMLInputElement, so line 7 can set input.value. Line 4 shows HTMLDivElement. Line 5 asks for cart-widget, a name the browser doesn't know (a page can define its own elements like this), so it falls through to the general signature and line 6 shows plain HTMLElement. Line 8 prints 2 DIV CART-WIDGET. In your editor, pointing at createElement shows the signature it matched and (+2 overloads).

That's the pattern to copy: precise signatures first, so callers get exact types, and a general one last, so nothing reasonable is turned away. Now sort some calls to the two-signature parsePrice from the start of the lesson:

Common mix-ups

• "Overloads let me write a separate body for each way of calling." No. There is one body. The overload lines are removed before the code runs, and your own code inside the body tells the cases apart.
• "Callers can use the implementation signature too." No. It's hidden. Every call must match one of the overloads above it.
• "TypeScript checks that each branch returns what its overload promises." No. It checks the body only against the implementation signature, so swapped branches get no error.
• "A value of type string | string[] can call a function with a string overload and a list overload." No. A call must fit one overload. Add a signature that takes the union, last, or use a union parameter.
• "The order of overloads doesn't matter." No. TypeScript uses the first one that fits, so a general one at the top hides the precise ones.
• "More overloads make a function easier to use." No. If the return type is the same, a union or an optional parameter is simpler for callers.

Practice exercises

Each exercise is TypeScript. When you fix code, press Edit & run on the starter code: the errors update as you type, and the console shows what it prints. Try a guess first, then use the hints.

1function parsePrice(input: string): number;2function parsePrice(input: string[]): number[];3function parsePrice(input: string | string[]) {4  return Array.isArray(input) ? input.map(Number) : Number(input);5}6 7const prices = parsePrice(["3", "4", "5"]);

1function parsePrice(input: string): number;2function parsePrice(input: string[]): number[];3function parsePrice(input: string | string[]) {4  return Array.isArray(input) ? input.map(Number) : Number(input);5}6 7const prices = parsePrice(["3", "4", "5"]);8//    ^?

function formatPrice(price: number): string;
function formatPrice(prices: number[]): string[];
function formatPrice(price: number | number[]) {
  return Array.isArray(price) ? price.map((one) => "$" + one) : "$" + price;
}

const tea = formatPrice(3);
const cart = formatPrice([3, 4]);
const cake = formatPrice("4");

1function formatPrice(price: number): string;2function formatPrice(prices: number[]): string[];3function formatPrice(price: number | number[]) {4  return Array.isArray(price) ? price.map((one) => "$" + one) : "$" + price;5}6 7const tea = formatPrice(3);8const cart = formatPrice([3, 4]);9const cake = formatPrice("4"); // line 9: text fits neither signature

1function formatPrice(price: number): string;2function formatPrice(price: number | number[]) {3  return Array.isArray(price) ? price.map((one) => "$" + one) : "$" + price;4}5 6console.log(formatPrice(4));7console.log(formatPrice([3, 4]));

1function formatPrice(price: number): string;2function formatPrice(prices: number[]): string[];3function formatPrice(price: number | number[]) {4  return Array.isArray(price) ? price.map((one) => "$" + one) : "$" + price;5}6 7console.log(formatPrice(4));8const labels = formatPrice([3, 4]);9//    ^?10console.log(labels.join(", "));

1function toCents(price: number): number;2function toCents(prices: number[]): number[];3function toCents(price: number) {4  return Math.round(price * 100);5}6 7console.log(toCents(4.5));

1function toCents(price: number): number;2function toCents(prices: number[]): number[];3function toCents(price: number | number[]) {4  return Array.isArray(price) ? price.map((one) => Math.round(one * 100)) : Math.round(price * 100);5}6 7console.log(toCents(4.5));8console.log(toCents([3, 4.25]).join(", "));

1function countItems(items: string): number;2function countItems(items: string[]): number;3function countItems(items: string | string[]) {4  return items.length;5}6 7function countSearch(query: string | string[]) {8  return countItems(query);9}10console.log(countSearch(["tea", "cake"]));

1function countItems(items: string | string[]) {2  return items.length;3}4 5function countSearch(query: string | string[]) {6  return countItems(query);7}8console.log(countSearch(["tea", "cake"]));

1function toLabel(price: number | number[]): string | string[];2function toLabel(price: number): string;3function toLabel(prices: number[]): string[];4function toLabel(price: number | number[]) {5  return Array.isArray(price) ? price.map((one) => "$" + one) : "$" + price;6}7 8const label = toLabel(4);9console.log(label.toUpperCase());

1function toLabel(price: number): string;2function toLabel(prices: number[]): string[];3function toLabel(price: number | number[]): string | string[];4function toLabel(price: number | number[]) {5  return Array.isArray(price) ? price.map((one) => "$" + one) : "$" + price;6}7 8const label = toLabel(4);9//    ^?10console.log(label.toUpperCase());

Check your understanding

For each question, find the signature a call matches, from the top. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• Overload signatures list the ways a function can be called, each with its own return type, above one implementation.
• TypeScript tries the overloads from the top and uses the first that fits. If none fits, it says No overload matches this call.
• The implementation signature is hidden from callers, must cover every overload, and is the only thing the body is checked against.
• Overloads are removed with the types. The browser runs one function, and your code tells the cases apart.
• A call matches one overload, so a union argument needs a union signature, placed last, or a union parameter.
• Overload only when the return type depends on the arguments. Otherwise use a union or an optional parameter.

Coming next: this in TypeScript. It shows how to say what this is inside a function, and how TypeScript catches a method called without its object.