Typing functions

A function that says what it needs

A shop page shows prices like $4.00. Here is a small function that does it. It uses toFixed(2), a number method that writes the number with two digits after the point. Text doesn't have that method.

function formatPrice(price) {
  return "$" + price.toFixed(2);
}

console.log(formatPrice(4));
console.log(formatPrice("4"));

Line 1 makes a function with one parameter, price: the name a value gets inside the function. Line 5 calls it with the argument 4, the value you pass in, and prints $4.00. Line 6 passes the text "4", maybe read from a form. Text has no toFixed, so the code stops with TypeError: price.toFixed is not a function. Nothing warned you before it ran. (The Parameters lesson covers how arguments fill parameters.)

In TypeScript you write a type after each parameter, the same way you write one after a variable. Here is the same code with one type added:

1function formatPrice(price: number) {2  return "$" + price.toFixed(2);3}4 5console.log(formatPrice(4));6console.log(formatPrice("4"));

Line 1 now says price: number: whoever calls formatPrice must pass a number. Line 5 does. Line 6 passes text, so TypeScript marks line 6, on purpose here, because it's the bug:

• Argument of type 'string' is not assignable to parameter of type 'number' means "the value you passed in is text, but this parameter only takes a number". "Assignable" means "allowed to be stored there".
• The error is on the call, line 6, not inside the function. The function is fine; the call gives it the wrong thing.

A function's types are a promise in both directions. The parameter types say what every call must pass in. The return type says what every call gets back. This lesson covers both, and the ways to make a parameter optional.

Types on parameters

Once a parameter has a type, TypeScript checks every call: the kind of each argument, and how many arguments there are. Try it. Each button changes the call on line 5. Watch the list under the code, and the result on the right.

1function formatPrice(price: number) {2  return "$" + price.toFixed(2);3}4 5console.log(formatPrice(4));

Press each button. A number has no errors. Text gets the error from the overview, and when it runs the code stops. Text, converted wraps the text in Number(…), which turns it into a number, so the error disappears. Nothing and One too many both get Expected 1 arguments, but got …: TypeScript counts the arguments too. Plain JavaScript never counts; a missing argument is undefined and an extra one is ignored.

What if you leave the type off? TypeScript doesn't look at the calls to guess a parameter's type. It only looks at the function itself, and price on its own could be anything:

1function formatPrice(price) {2  return "$" + price.toFixed(2);3}

Line 1 has no type on price. TypeScript says Parameter 'price' implicitly has an 'any' type. The type any switches checking off: anything goes in, and nothing is checked. "Implicitly" means you didn't write it; TypeScript would have to pick it for you. Strict mode, which these examples use, turns on a setting called noImplicitAny that makes this an error, so you notice. Here is the same code with that setting off:

1function formatPrice(price) {2  //                 ^?3  return "$" + price.toFixed(2);4}5 6console.log(formatPrice("4"));

The list under the code shows the setting this example changes. The query on line 2 shows (parameter) price: any. There are no errors at all, not even on line 6, which passes text. Run it and it stops with the same TypeError as plain JavaScript. That's why you write a type on every parameter that has no default: it's the one place TypeScript can't work a type out for you.

Parameter types look the same in every kind of function: arrow functions and function expressions too.

1const lineTotal = (price: number, quantity: number) => price * quantity;2 3const applyTax = function (total: number, rate: number) {4  return total + total * rate;5};6 7console.log(lineTotal(3, 2));8console.log(applyTax(10, 0.5));

Line 1 is an arrow function with two number parameters. Line 3 stores a function expression in applyTax, with its types in the same place: after each parameter name. Line 7 prints 6, and line 8 prints 15: 10 plus half of 10.

Return types: worked out or written

You usually don't have to write what a function returns. TypeScript reads the return lines and works it out, which is called inference:

1function lineTotal(price: number, quantity: number) {2//       ^?3  return price * quantity;4}5 6const total = lineTotal(3, 2);7//    ^?8console.log(total);

Line 1 types the two parameters and nothing else. The query on line 2 points at lineTotal and shows its whole signature, the list of what goes in and what comes out: function lineTotal(price: number, quantity: number): number. The : number at the end is the return type TypeScript worked out, because a number times a number is a number. Line 6 calls it, the query on line 7 shows const total: number, and line 8 prints 6.

You can also write the return type yourself, after the closing bracket of the parameters. Then TypeScript checks every return line against it:

1function cartLabel(count: number): string {2  if (count === 1) return "1 item";3  return count + " items";4}5 6console.log(cartLabel(1));7console.log(cartLabel(3));

Line 1 says cartLabel takes a number and returns a string. Lines 2 and 3 both return text, so there are no errors. Line 6 prints 1 item and line 7 prints 3 items.

Why write it, if TypeScript can work it out? Because it changes where a mistake gets reported. In the next playground, line 2 has a mistake: free shipping returns the text "free" instead of a number. Switch the return type on and off, and watch where the error lands.

1function shippingCost(total: number) {2  if (total > 50) return "free";3  return 5;4}5 6const cost = shippingCost(60);7//    ^?8console.log(cost + 10);

With No return type, the query on line 7 shows const cost: "free" | 5, a union: cost is either the exact text "free" or the exact number 5. The function itself looks fine to TypeScript, and the error appears on line 8, where the result is used. Its message names the wider types, string | number: cost may be text or a number, so TypeScript can't tell whether + should add or join. With Return type: number, the error moves to line 2, right on the mistake. Fixed: return 0 removes it, and the code prints 10.

A written return type also catches a path that forgets to return:

1function discountFor(code: string): number {2  if (code === "SAVE10") return 10;3}

Line 1 promises a number. Line 2 returns 10 for one coupon code, but for any other code the function reaches its end without a return, and JavaScript gives back undefined. TypeScript says Function lacks ending return statement and return type does not include 'undefined': "some path reaches the end, so it would return undefined, and your return type doesn't allow that". Adding return 0; before the closing brace fixes it.

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

Optional, default, and rest parameters

By default every parameter is required. Three kinds of parameter let a call pass fewer or more arguments. The first is an optional parameter: put ? after its name.

1function greet(name: string, title?: string) {2  //                             ^?3  return "Hello, " + (title ? title + " " : "") + name;4}5 6console.log(greet("Asha"));7console.log(greet("Asha", "Dr."));

Line 1 says title?: string, so a call may leave it out. The query on line 2 shows its type inside the function: string | undefined, "a string, or undefined when it was left out". Line 3 checks title before using it. Line 6 leaves it out and prints Hello, Asha; line 7 passes one and prints Hello, Dr. Asha.

If the function forgets to check, TypeScript points at the place it could go wrong:

1function greet(name: string, title?: string) {2  return "Hello, " + title.toUpperCase() + " " + name;3}

Line 2 calls title.toUpperCase(). TypeScript says 'title' is possibly 'undefined': when a call leaves the title out, this line would throw a TypeError.

The second kind is a default parameter: = value after the name. A call may leave it out, and then it gets the default. You usually don't write its type; TypeScript works it out from the default.

1function shippingFee(total: number, fee = 5) {2  //                                ^?3  return total + fee;4}5 6console.log(shippingFee(20));7console.log(shippingFee(20, 0));8console.log(shippingFee(20, undefined));

Line 1 gives fee the default 5, and the query on line 2 shows (parameter) fee: number: inside the function it's always a number, never undefined. Line 6 leaves it out and prints 25. Line 7 passes 0, which is a real value, and prints 20. Line 8 passes undefined, which counts as leaving it out, and prints 25.

1function shippingFee(total: number, fee = 5) {2//       ^?3  return total + fee;4}

The query on line 2 shows the signature callers see: function shippingFee(total: number, fee?: number): number. From outside, a default parameter is just an optional one; only the function knows what it falls back to.

Optional and default parameters go after the required ones. TypeScript won't let a required parameter follow an optional one:

1function addToCart(note?: string, item: string) {2  return item;3}

Line 1 puts the optional note first. TypeScript says A required parameter cannot follow an optional parameter: arguments fill parameters from left to right, so there'd be no way to pass item without passing a note first. Swap them to (item: string, note?: string).

The third kind is a rest parameter: ... before the name collects every remaining argument into one array (the Spread & rest lesson covers it in JavaScript). Its type is an array type, like number[], "an array of numbers".

1function cartTotal(...prices: number[]) {2  //                  ^?3  let total = 0;4  for (const price of prices) total += price;5  return total;6}7 8console.log(cartTotal(3, 4, 5));9console.log(cartTotal());10const saved = [2, 2];11console.log(cartTotal(...saved));12console.log(cartTotal(3, "4"));

Line 1 says ...prices: number[], and the query on line 2 confirms (parameter) prices: number[]. Line 8 passes three numbers and prints 12. Line 9 passes none, so prices is an empty array and it prints 0. Line 11 spreads an array into the call and prints 4. Line 12 is the error on purpose: every argument must be a number, and "4" is text. Run it anyway, and 3 + "4" joins into 34.

Now try all three kinds together. orderSummary has a required item, a quantity with the default 1, and an optional note. Type different arguments on line 6:

1function orderSummary(item: string, quantity = 1, note?: string) {2  const line = quantity + " x " + item;3  return note ? line + " (" + note + ")" : line;4}5 6console.log(orderSummary("Tea"));

With "Tea", quantity uses its default and note is left out. Passing undefined as the second argument also uses the default, so you can still pass a note. An empty box gets Expected 1-3 arguments, but got 0: one argument is required, and up to three are allowed.

The table below lists the kinds of parameter. Read each row as: this parameter, can a call leave it out, and its type inside the function.

void: when nothing comes back

Some functions do a job, like printing or saving, and give nothing back. In JavaScript such a call still gives back a value: undefined. TypeScript gives these functions a special return type, void:

1function logOrder(id: number) {2  console.log("Order " + id);3}4 5const result = logOrder(7);6//    ^?7console.log(result);

logOrder has no return. Line 5 keeps what the call gives back, and the query on line 6 shows const result: void. void means "this function gives back nothing you should use". When it runs, line 5 prints Order 7 and line 7 prints undefined, because that's what JavaScript returns.

Because a void result isn't meant to be used, TypeScript stops you from relying on it:

1function logOrder(id: number): void {2  console.log("Order " + id);3}4 5if (logOrder(7)) {6  console.log("Logged");7}

Line 1 writes the return type void itself. Line 5 asks whether the result is true, as if the function reported success. TypeScript says An expression of type 'void' cannot be tested for truthiness: the result is always undefined, so the if would never run. When it runs, it prints Order 7 and never Logged.

1function logOrder(id: number): void {2  console.log("Order " + id);3  return id;4}

A function you write as : void must not return a value. Line 3 returns id, and TypeScript says Type 'number' is not assignable to type 'void'.

undefined is different. It's a real value a caller may use. Write it in a return type when "nothing found" is a result the caller should handle:

1function findCoupon(code: string): number | undefined {2  if (code === "SAVE10") return 10;3}4 5const discount = findCoupon("HELLO");6//    ^?7console.log(discount ?? 0);

Line 1 says findCoupon returns a number, or undefined when the code isn't known. Because the return type includes undefined, falling off the end after line 2 is allowed. The query on line 6 shows const discount: number | undefined, and line 7 uses it: ?? gives 0 when the left side is undefined, so it prints 0.

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

Typing a checkout's helper functions

Here is the kind of code a real checkout page has: a few small functions that work out and show a total. Each one uses something from this lesson.

1type CartItem = { name: string; price: number; quantity: number };2 3function lineTotal(item: CartItem): number {4  return item.price * item.quantity;5}6 7function cartTotal(...items: CartItem[]): number {8  let total = 0;9  for (const item of items) total += lineTotal(item);10  return total;11}12 13function formatPrice(amount: number, currency = "$"): string {14  return currency + amount.toFixed(2);15}16 17function logCheckout(total: number, coupon?: string): void {18  const note = coupon ? " with " + coupon : "";19  console.log("Checkout: " + formatPrice(total) + note);20}21 22const tea: CartItem = { name: "Tea", price: 3, quantity: 2 };23const cake: CartItem = { name: "Cake", price: 4, quantity: 1 };24logCheckout(cartTotal(tea, cake));25logCheckout(cartTotal(cake), "SAVE10");

Line 1 is a type alias: type CartItem = … names the shape every cart item has. Line 3 takes one item and returns a number. Line 7 takes any number of items with a rest parameter. Line 13 has a default currency, so callers usually pass only the amount. Line 17 has an optional coupon and returns void, because it only prints. Line 24 prints Checkout: $10.00 (two teas at 3 and a cake at 4), and line 25 prints Checkout: $4.00 with SAVE10.

Notice what you didn't have to write: no types on total or note, and no type on currency. TypeScript works those out. The return types are written because other parts of the page call these functions, and a mistake inside one should be reported there, not at every call.

Common mix-ups

An optional parameter and a parameter whose type includes undefined look alike inside the function. They aren't the same for callers:

1function greet(name: string, title: string | undefined) {2  return title ? title + " " + name : name;3}4 5console.log(greet("Asha", undefined));6console.log(greet("Asha"));

Line 1 says title: string | undefined, with no ?. Line 5 passes undefined and prints Asha. Line 6 leaves it out, and TypeScript says Expected 2 arguments, but got 1. The type allows undefined; only ? lets a call leave the argument out.

• "TypeScript checks the arguments while the code runs." No. It checks the calls before the code runs. While it runs, the types are gone, and formatPrice("4") still throws.
• "I have to write the return type on every function." No. TypeScript works it out from the return lines. Write it when you want mistakes reported inside the function.
• "TypeScript can work out a parameter's type from the calls." No. It never looks at the calls, so a parameter with no type and no default is any, which strict mode reports. (A function you pass to another function is different: Function types shows how it gets its types from where it goes.)
• "note?: string and note: string | undefined are the same." No. Only ? lets a call leave the argument out. Inside the function, both are string | undefined.
• "Extra arguments are fine, like in JavaScript." No. TypeScript counts them: Expected 1 arguments, but got 2. Use a rest parameter if a function really takes any number.
• "void is just another name for undefined." No. undefined is a value you can use. void means the caller shouldn't use the result at all.

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.

function applyDiscount(total: number, percent: number) {
  return total - (total * percent) / 100;
}

console.log(applyDiscount(20, 10));
console.log(applyDiscount(20, "10"));

1function applyDiscount(total: number, percent: number) {2  return total - (total * percent) / 100;3}4 5console.log(applyDiscount(20, 10));6console.log(applyDiscount(20, "10")); // line 6: "10" is text

1function hasItems(cart: string[]) {2  return cart.length > 0;3}4 5const ready = hasItems(["Tea"]);

1function hasItems(cart: string[]) {2  return cart.length > 0;3}4 5const ready = hasItems(["Tea"]);6//    ^?

1function lineTotal(price, quantity) {2  return price * quantity;3}4 5console.log(lineTotal(3, 2));

1function lineTotal(price: number, quantity: number) {2  return price * quantity;3}4 5console.log(lineTotal(3, 2));

1function greet(name: string, title: string) {2  return title ? title + " " + name : name;3}4 5console.log(greet("Asha"));

1function greet(name: string, title?: string) {2  return title ? title + " " + name : name;3}4 5console.log(greet("Asha"));

1function tagList(label: string, ...tags) {2  return label + ": " + tags.join(", ");3}4 5console.log(tagList("Tea", "hot", "large"));

1function tagList(label: string, ...tags: string[]) {2  return label + ": " + tags.join(", ");3}4 5console.log(tagList("Tea", "hot", "large"));

1function shippingFor(country: string): number {2  if (country === "IN") return 0;3  if (country === "US") return 5;4}5 6console.log(shippingFor("FR"));

1function shippingFor(country: string): number {2  if (country === "IN") return 0;3  if (country === "US") return 5;4  return 10;5}6 7console.log(shippingFor("FR"));

Check your understanding

For each question, think about what TypeScript checks: the arguments at each call, and the return lines against the return type. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• Write a type after every parameter that has no default: price: number. TypeScript can't work a parameter's type out from the calls.
• TypeScript checks each call: the kind of each argument, and how many there are.
• The return type is worked out from the return lines. Write it, like ): number, to have mistakes reported inside the function.
• name?: string may be left out, and is string | undefined inside. fee = 5 may be left out, and is always a number inside.
• A rest parameter, ...prices: number[], takes any number of arguments as an array.
• void means "nothing for you to use". undefined is a value a caller can use.

Coming next: Function types. It shows how to describe a function itself as a type, so you can type callbacks and event handlers.