Function types

A function that takes another function

In JavaScript you pass functions to other functions all the time: a click handler to addEventListener, a rule to map, a "tell me when you're done" function to a save. A function passed like this is called a callback (the Callbacks lesson covers them). Here a cart's save function takes one:

function saveCart(onSaved) {
  onSaved(3);
}

saveCart((count) => console.log("Saved " + count + " items"));
saveCart("done");

Line 1 makes saveCart, which takes a function called onSaved. Line 2 calls it with 3, the number of items saved. Line 5 passes an arrow function, and it prints Saved 3 items. Line 6 passes the text "done" instead. When line 2 tries to call it, JavaScript throws TypeError: onSaved is not a function, and the code stops. Nothing warned you before it ran.

In the Typing functions lesson, you wrote types like price: number on parameters. A parameter that holds a function needs a type too: one that says how the function will be called. That is a function type:

1function saveCart(onSaved: (count: number) => void) {2  onSaved(3);3}4 5saveCart((count) => console.log("Saved " + count + " items"));6saveCart("done");

Line 1 now says onSaved: (count: number) => void. Read it as "a function that takes a number called count and gives back nothing to use". Line 5 passes such a function, so it's fine. Line 6 gets an error, on purpose here, because it's the bug:

• Argument of type 'string' is not assignable to parameter of type '(count: number) => void' means "you passed text where a function has to go". An argument is the value you pass in a call.

Function type expressions

The type (count: number) => void is called a function type expression. It looks like an arrow function, but it's a type, so it never runs. It has three parts:

• The parameters in brackets, each with a name and a type: (price: number).
• An arrow, =>.
• The type the function gives back: string, or void for nothing to use.

Writing a long function type over and over is tiring, so you can give it a name. type PriceFormatter = … is a type alias: a name for a type, which you can use anywhere a type goes. You met them in Type aliases & interfaces, and a function type works the same way.

1type PriceFormatter = (price: number) => string;2 3const format: PriceFormatter = (price) => "$" + price.toFixed(2);4//                              ^?5console.log(format(4));

Line 1 names the type PriceFormatter: a function that takes a number and returns a string. Line 3 stores an arrow function in format and says it's a PriceFormatter. Notice that (price) has no type written. The query on line 4 shows TypeScript still knows it: (parameter) price: number. It took the type from PriceFormatter. Line 5 prints $4.00.

Which functions can go on line 3? Try five, and watch the list under the code:

1type PriceFormatter = (price: number) => string;2 3const format: PriceFormatter = (price) => "$" + price.toFixed(2);4console.log(format(4));

Matches and Takes nothing have no errors. A function may take fewer parameters than the type lists, because JavaScript ignores extra arguments. Returns a number fails because a PriceFormatter must give back a string. Takes text fails because callers will pass a number. Needs two fails because callers pass only one argument, so currency would always be undefined. In each error, the first line names the two types, and the indented line under it gives the reason.

One thing catches almost everyone. In a function type, every parameter needs a name, and the name comes first:

1type PriceFormatter = (number) => string;

You might read (number) => string as "takes a number". TypeScript reads it as a parameter named number, with no type. With strict checking on, as in this lesson, it says Parameter has a name but no type. Did you mean 'arg0: number'? Write a name and a type: (price: number) => string.

Typing callbacks

When you write a function that takes a callback, the callback's type is a promise about how you'll call it. Here is a small function that calls a callback once for each price, the way forEach does:

1type PriceCallback = (price: number, index: number) => void;2 3function forEachPrice(prices: number[], callback: PriceCallback) {4  for (let i = 0; i < prices.length; i++) callback(prices[i], i);5}6 7forEachPrice([3, 4], (price, index) => console.log(index + ": " + price));8//                    ^?

Line 1 names the callback's type: it gets a price and an index, both numbers, and gives back nothing to use. Line 3 says forEachPrice takes a list of numbers and a PriceCallback. Line 4 loops over the prices and calls the callback with each price and its position. Line 7 passes a callback, and the query on line 8 shows price is a number. It prints 0: 3, then 1: 4.

Now pick other callbacks for line 7:

1type PriceCallback = (price: number, index: number) => void;2 3function forEachPrice(prices: number[], callback: PriceCallback) {4  for (let i = 0; i < prices.length; i++) callback(prices[i], i);5}6 7forEachPrice([3, 4], (price, index) => console.log(index + ": " + price));

Uses the price takes one parameter, and that's fine. Returns a value is fine too: more on that below. Expects text gets an error, and running it anyway stops with a TypeError. Wants three gets an error because forEachPrice never passes a third value.

The table below sums up what a callback may do. Read each row as: the callback does this, then what TypeScript says, and why.

Don't make callback parameters optional

Since a callback may skip the index, you might think the type should mark it optional with ?. That says something else: "I might call you without an index". TypeScript then makes every callback deal with a missing one:

1type PriceCallback = (price: number, index?: number) => void;2 3function forEachPrice(prices: number[], callback: PriceCallback) {4  for (let i = 0; i < prices.length; i++) callback(prices[i], i);5}6 7forEachPrice([3, 4], (price, index) => console.log(index.toFixed()));

Line 1 writes index?: number. Line 4 always passes the index, but TypeScript only reads the type. So on line 7 it says 'index' is possibly 'undefined', an error for something that can't happen. When it runs, it prints 0 and 1. Write callback parameters without ?, unless you really call the callback without them.

A void callback may return a value

In the playground, Returns a value had no error, even though PriceCallback returns void. Compare it with a function you write with : void yourself:

1const saved: number[] = [];2[3, 4].forEach((price) => saved.push(price));3console.log(saved.join(", "));4 5const logPrice = function (price: number): void {6  return price;7};

On line 2, forEach's callback type returns void, and saved.push(price) returns a number (the new length). That's allowed: void in a function type means "the caller ignores what comes back". Line 3 prints 3, 4. Lines 5 to 7 are different. There, : void is written on the function itself, so it must not return a value, and line 6 gets Type 'number' is not assignable to type 'void', as in the last lesson.

Call signatures: functions with properties

A JavaScript function is also an object, so it can carry properties (the Functions are objects lesson shows how). A function type expression can't list properties. For a function that has some, write a call signature inside an object type:

1type PriceRule = {2  label: string;3  (total: number): number;4};5 6function tenOff(total: number) {7  return total - 10;8}9tenOff.label = "10 off";10 11function applyRule(rule: PriceRule, total: number) {12  console.log(rule.label + ": " + rule(total));13}14 15applyRule(tenOff, 50);16applyRule((total: number) => total / 2, 50);

Lines 1 to 4 describe a PriceRule. Line 2 is an ordinary property: a label that is text. Line 3 is the call signature: it says a PriceRule can be called with a number and gives back a number. Notice it uses a colon before the return type, not an arrow.

Lines 6 to 8 declare tenOff, and line 9 gives it a label. TypeScript notices a property you add to a declared function like this, so tenOff now has both parts. Line 12 reads the label and calls the rule. Line 15 passes tenOff and prints 10 off: 40.

Line 16 passes an arrow function. It can be called the right way, but it has no label, so TypeScript reports it, on purpose here. The first line of the error says the arrow function isn't a PriceRule, and the line under it gives the reason: Property 'label' is missing in type '(total: number) => number' but required in type 'PriceRule'. Run it anyway and line 12 prints undefined: 25.

The table below compares the two ways to write a function's type. Read each row as a question, then each way's answer.

Contextual typing: types from where a function goes

You've seen callbacks with no types written on their parameters, like (price) => …, and TypeScript still knew price was a number. When you write a function right where a function type is expected, TypeScript takes the parameter types from that type. This is called contextual typing: the place the function goes, its context, decides the types. It works with the browser's and JavaScript's own functions too:

1const prices = [3, 4, 5];2const labels = prices.map((price) => "$" + price.toFixed(2));3//                         ^?4console.log(labels.join(", "));

Line 1 makes an array of numbers. Line 2 passes a callback to map (the map, filter & reduce lesson covers it). The query on line 3 shows (parameter) price: number: TypeScript knows map passes each element of a number array. So price.toFixed(2) is checked, and line 4 prints $3.00, $4.00, $5.00.

Take the same arrow function out of its context, and there's nothing to take the type from:

1const showPrice = (price) => "$" + price.toFixed(2);

Line 1 stores the arrow function in a plain variable. Nothing says what price will be, so TypeScript says Parameter 'price' implicitly has an 'any' type. any is the type that turns checking off, and strict mode won't let it slip in unnoticed. Fix it by writing (price: number), or by giving the variable a function type, as format: PriceFormatter did.

Event listeners use contextual typing too. The browser's types know which kind of event each name sends (the Introduction to events lesson covers listeners). Type a different event name and watch the type of event change:

1const button = document.createElement("button");2button.addEventListener("keydown", (event) => {3  //                                ^?4  console.log(event.key);5});

With keydown or keyup, event is a KeyboardEvent, so line 4 can read event.key. With click it's a PointerEvent, and with input a plain Event; neither has a key, so line 4 gets an error. A misspelled name like keydwon gets no error of its own, because any name is allowed; TypeScript just falls back to Event.

A search box that calls you back

A real page often has a small component that reports what the user did through a callback. Here is a search box: you pass it a function, and it calls that function with the cleaned-up search text each time the user types.

1type SearchHandler = (query: string) => void;2 3function createSearchBox(onSearch: SearchHandler) {4  const input = document.createElement("input");5  input.addEventListener("input", () => onSearch(input.value.trim()));6  return input;7}8 9const searches: string[] = [];10const box = createSearchBox((query) => searches.push(query));11//                           ^?12box.value = " tea ";13box.dispatchEvent(new Event("input"));14console.log(searches.join(", "));

Line 1 names the handler's type: it gets the search text and gives back nothing to use. Line 3 says createSearchBox takes one. Lines 4 and 5 make an <input> and, on every input event, call onSearch with the text, trimmed of spaces. Line 10 passes a handler. The query on line 11 shows query is a string, from contextual typing. The handler returns push's number, and void lets that go. Lines 12 and 13 act like a user typing " tea ", and line 14 prints tea.

The search box's author wrote one type, on line 1. Everyone who uses the box gets their query typed for free, and gets an error if their handler expects anything but a string.

Common mix-ups

TypeScript has a built-in type called Function. It sounds like the right type for a callback, but it lets almost anything through:

1function runLater(callback: Function) {2  return callback(1, 2, 3);3}4 5const result = runLater(() => "done");6//    ^?7console.log(result.toFixed());

Line 1 types callback as Function. Line 2 calls it with three numbers, which nobody checks. The query on line 6 shows const result: any: a call to a Function gives back any. So line 7's result.toFixed() gets no error, and it throws a TypeError when it runs, because result is the text "done". Write the real type instead, like () => string.

• "(number) => string is a function that takes a number." No. It's a parameter named number, with no type. Write (price: number) => string.
• "A callback must take every parameter its type lists." No. It may take fewer. The extra arguments are passed and ignored.
• "Parameter names in a callback must match the type's." No. Only the position and the type count: (clicks) => … fits (count: number) => void.
• "A callback for a void type must not return anything." No. The caller ignores what comes back, so (price) => saved.push(price) is fine. Only a function written with : void must not return a value.
• "Mark a callback parameter optional if some callbacks don't need it." No. ? means you might not pass it, and every callback then has to check for undefined.
• "Function is a good type for a callback." No. Any call is allowed and the result is any, so mistakes slip through. Write the real function type.

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.

1const names = ["Tea", "Cake"];2const loud = names.map((name) => name.toUpperCase());

1const names = ["Tea", "Cake"];2const loud = names.map((name) => name.toUpperCase());3//                      ^?

type OnAdd = (item: string, quantity: number) => void;

const logAdd: OnAdd = (item, quantity) => console.log(quantity + " x " + item);
const badAdd: OnAdd = (item: number) => console.log(item);

1type OnAdd = (item: string, quantity: number) => void;2 3const logAdd: OnAdd = (item, quantity) => console.log(quantity + " x " + item);4const badAdd: OnAdd = (item: number) => console.log(item); // line 4: item is a string

1function onCartChange(listener) {2  listener(3, 12);3}4 5onCartChange((count, total) => console.log(count + " items, $" + total));

1function onCartChange(listener: (count: number, total: number) => void) {2  listener(3, 12);3}4 5onCartChange((count, total) => console.log(count + " items, $" + total));

1type PriceCallback = (price: number) => void;2 3function forEachPrice(prices: number[], callback: PriceCallback) {4  for (const price of prices) callback(price);5}6 7forEachPrice([3, 4], (price: string) => console.log(price.toUpperCase()));

1type PriceCallback = (price: number) => void;2 3function forEachPrice(prices: number[], callback: PriceCallback) {4  for (const price of prices) callback(price);5}6 7forEachPrice([3, 4], (price) => console.log(price.toFixed(2)));8//                    ^?

1type Discount = {2  label: string;3  (total: number): number;4};5 6function fiveOff(total: number) {7  return total - 5;8}9 10const discount: Discount = fiveOff;11console.log(discount.label + ": " + discount(20));

1type Discount = {2  label: string;3  (total: number): number;4};5 6function fiveOff(total: number) {7  return total - 5;8}9fiveOff.label = "5 off";10 11const discount: Discount = fiveOff;12console.log(discount.label + ": " + discount(20));

1type ButtonProps = { label: string; onPress: (count: number) => void };2 3function makeButton(props: ButtonProps) {4  let count = 0;5  return () => {6    count++;7    props.onPress(count);8  };9}10 11const press = makeButton({ label: "Add tea", onPress: (label: string) => console.log(label + " pressed") });12press();13press();

1type ButtonProps = { label: string; onPress: (count: number) => void };2 3function makeButton(props: ButtonProps) {4  let count = 0;5  return () => {6    count++;7    props.onPress(count);8  };9}10 11const press = makeButton({ label: "Add tea", onPress: (count) => console.log("Pressed " + count) });12press();13press();

Check your understanding

For each question, ask how the function will be called: what it's given, and what happens to what it gives back. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• A function type describes a function as a value: (price: number) => string takes a number and gives back a string.
• Every parameter in a function type needs a name and a type. (number) => string names a parameter number.
• A type alias gives a function type a name, like type PriceFormatter = (price: number) => string.
• A callback may take fewer parameters than its type lists, but not more, and not different types.
• void in a callback type means the result is ignored, so the callback may return anything.
• A call signature, { (total: number): number }, describes a function that also has properties.
• Contextual typing gives a callback's parameters their types from where you pass it. Avoid the Function type.

Coming next: Function overloads. They describe one function that can be called in several different ways, each with its own return type.