Functions are the fundamental building block of any application in JavaScript.\nThey’re how you build up layers of abstraction, mimicking classes, information hiding, and modules.\nIn TypeScript, while there are classes, namespaces, and modules, functions still play the key role in describing how to do things.\nTypeScript also adds some new capabilities to the standard JavaScript functions to make them easier to work with.
\nTo begin, just as in JavaScript, TypeScript functions can be created both as a named function or as an anonymous function.\nThis allows you to choose the most appropriate approach for your application, whether you’re building a list of functions in an API or a one-off function to hand off to another function.
\nTo quickly recap what these two approaches look like in JavaScript:
\n\nts// Named function\nfunction add(x, y) {\n return x + y;\n}\n\n// Anonymous function\nlet myAdd = function(x, y) {\n return x + y;\n};
Just as in JavaScript, functions can refer to variables outside of the function body.\nWhen they do so, they’re said to capture these variables.\nWhile understanding how this works (and the trade-offs when using this technique) is outside of the scope of this article, having a firm understanding how this mechanic works is an important piece of working with JavaScript and TypeScript.
\n\ntslet z = 100;\n\nfunction addToZ(x, y) {\n return x + y + z;\n}
Let’s add types to our simple examples from earlier:
\n\ntsfunction add(x: number, y: number): number {\n return x + y;\n}\n\nlet myAdd = function(x: number, y: number): number {\n return x + y;\n};
We can add types to each of the parameters and then to the function itself to add a return type.\nTypeScript can figure the return type out by looking at the return statements, so we can also optionally leave this off in many cases.
\nNow that we’ve typed the function, let’s write the full type of the function out by looking at each piece of the function type.
\n\ntslet myAdd: (x: number, y: number) => number = function(\n x: number,\n y: number\n): number {\n return x + y;\n};
A function’s type has the same two parts: the type of the arguments and the return type.\nWhen writing out the whole function type, both parts are required.\nWe write out the parameter types just like a parameter list, giving each parameter a name and a type.\nThis name is just to help with readability.\nWe could have instead written:
\n\ntslet myAdd: (baseValue: number, increment: number) => number = function(\n x: number,\n y: number\n): number {\n return x + y;\n};
As long as the parameter types line up, it’s considered a valid type for the function, regardless of the names you give the parameters in the function type.
\nThe second part is the return type.\nWe make it clear which is the return type by using a fat arrow (=>) between the parameters and the return type.\nAs mentioned before, this is a required part of the function type, so if the function doesn’t return a value, you would use void instead of leaving it off.
Of note, only the parameters and the return type make up the function type.\nCaptured variables are not reflected in the type.\nIn effect, captured variables are part of the “hidden state” of any function and do not make up its API.
\nIn playing with the example, you may notice that the TypeScript compiler can figure out the type even if you only have types on one side of the equation:
\n\nts// myAdd has the full function type\nlet myAdd = function(x: number, y: number): number {\n return x + y;\n};\n\n// The parameters 'x' and 'y' have the type number\nlet myAdd: (baseValue: number, increment: number) => number = function(x, y) {\n return x + y;\n};
This is called “contextual typing”, a form of type inference.\nThis helps cut down on the amount of effort to keep your program typed.
\nIn TypeScript, every parameter is assumed to be required by the function.\nThis doesn’t mean that it can’t be given null or undefined, but rather, when the function is called, the compiler will check that the user has provided a value for each parameter.\nThe compiler also assumes that these parameters are the only parameters that will be passed to the function.\nIn short, the number of arguments given to a function has to match the number of parameters the function expects.
\ntsfunction buildName(firstName: string, lastName: string) {\n return firstName + \" \" + lastName;\n}\n\nlet result1 = buildName(\"Bob\"); // error, too few parameters\nlet result2 = buildName(\"Bob\", \"Adams\", \"Sr.\"); // error, too many parameters\nlet result3 = buildName(\"Bob\", \"Adams\"); // ah, just right
In JavaScript, every parameter is optional, and users may leave them off as they see fit.\nWhen they do, their value is undefined.\nWe can get this functionality in TypeScript by adding a ? to the end of parameters we want to be optional.\nFor example, let’s say we want the last name parameter from above to be optional:
\ntsfunction buildName(firstName: string, lastName?: string) {\n if (lastName) return firstName + \" \" + lastName;\n else return firstName;\n}\n\nlet result1 = buildName(\"Bob\"); // works correctly now\nlet result2 = buildName(\"Bob\", \"Adams\", \"Sr.\"); // error, too many parameters\nlet result3 = buildName(\"Bob\", \"Adams\"); // ah, just right
Any optional parameters must follow required parameters.\nHad we wanted to make the first name optional, rather than the last name, we would need to change the order of parameters in the function, putting the first name last in the list.
\nIn TypeScript, we can also set a value that a parameter will be assigned if the user does not provide one, or if the user passes undefined in its place.\nThese are called default-initialized parameters.\nLet’s take the previous example and default the last name to \"Smith\".
\ntsfunction buildName(firstName: string, lastName = \"Smith\") {\n return firstName + \" \" + lastName;\n}\n\nlet result1 = buildName(\"Bob\"); // works correctly now, returns \"Bob Smith\"\nlet result2 = buildName(\"Bob\", undefined); // still works, also returns \"Bob Smith\"\nlet result3 = buildName(\"Bob\", \"Adams\", \"Sr.\"); // error, too many parameters\nlet result4 = buildName(\"Bob\", \"Adams\"); // ah, just right
Default-initialized parameters that come after all required parameters are treated as optional, and just like optional parameters, can be omitted when calling their respective function.\nThis means optional parameters and trailing default parameters will share commonality in their types, so both
\n\ntsfunction buildName(firstName: string, lastName?: string) {\n // ...\n}
and
\n\ntsfunction buildName(firstName: string, lastName = \"Smith\") {\n // ...\n}
share the same type (firstName: string, lastName?: string) => string.\nThe default value of lastName disappears in the type, only leaving behind the fact that the parameter is optional.
Unlike plain optional parameters, default-initialized parameters don’t need to occur after required parameters.\nIf a default-initialized parameter comes before a required parameter, users need to explicitly pass undefined to get the default initialized value.\nFor example, we could write our last example with only a default initializer on firstName:
\ntsfunction buildName(firstName = \"Will\", lastName: string) {\n return firstName + \" \" + lastName;\n}\n\nlet result1 = buildName(\"Bob\"); // error, too few parameters\nlet result2 = buildName(\"Bob\", \"Adams\", \"Sr.\"); // error, too many parameters\nlet result3 = buildName(\"Bob\", \"Adams\"); // okay and returns \"Bob Adams\"\nlet result4 = buildName(undefined, \"Adams\"); // okay and returns \"Will Adams\"
Required, optional, and default parameters all have one thing in common: they talk about one parameter at a time.\nSometimes, you want to work with multiple parameters as a group, or you may not know how many parameters a function will ultimately take.\nIn JavaScript, you can work with the arguments directly using the arguments variable that is visible inside every function body.
In TypeScript, you can gather these arguments together into a variable:
\n\ntsfunction buildName(firstName: string, ...restOfName: string[]) {\n return firstName + \" \" + restOfName.join(\" \");\n}\n\n// employeeName will be \"Joseph Samuel Lucas MacKinzie\"\nlet employeeName = buildName(\"Joseph\", \"Samuel\", \"Lucas\", \"MacKinzie\");
Rest parameters are treated as a boundless number of optional parameters.\nWhen passing arguments for a rest parameter, you can use as many as you want; you can even pass none.\nThe compiler will build an array of the arguments passed in with the name given after the ellipsis (...), allowing you to use it in your function.
The ellipsis is also used in the type of the function with rest parameters:
\n\ntsfunction buildName(firstName: string, ...restOfName: string[]) {\n return firstName + \" \" + restOfName.join(\" \");\n}\n\nlet buildNameFun: (fname: string, ...rest: string[]) => string = buildName;
thisLearning how to use this in JavaScript is something of a rite of passage.\nSince TypeScript is a superset of JavaScript, TypeScript developers also need to learn how to use this and how to spot when it’s not being used correctly.\nFortunately, TypeScript lets you catch incorrect uses of this with a couple of techniques.\nIf you need to learn how this works in JavaScript, though, first read Yehuda Katz’s Understanding JavaScript Function Invocation and “this”.\nYehuda’s article explains the inner workings of this very well, so we’ll just cover the basics here.
this and arrow functionsIn JavaScript, this is a variable that’s set when a function is called.\nThis makes it a very powerful and flexible feature, but it comes at the cost of always having to know about the context that a function is executing in.\nThis is notoriously confusing, especially when returning a function or passing a function as an argument.
Let’s look at an example:
\n\ntslet deck = {\n suits: [\"hearts\", \"spades\", \"clubs\", \"diamonds\"],\n cards: Array(52),\n createCardPicker: function() {\n return function() {\n let pickedCard = Math.floor(Math.random() * 52);\n let pickedSuit = Math.floor(pickedCard / 13);\n\n return { suit: this.suits[pickedSuit], card: pickedCard % 13 };\n };\n }\n};\n\nlet cardPicker = deck.createCardPicker();\nlet pickedCard = cardPicker();\n\nalert(\"card: \" + pickedCard.card + \" of \" + pickedCard.suit);
Notice that createCardPicker is a function that itself returns a function.\nIf we tried to run the example, we would get an error instead of the expected alert box.\nThis is because the this being used in the function created by createCardPicker will be set to window instead of our deck object.\nThat’s because we call cardPicker() on its own.\nA top-level non-method syntax call like this will use window for this.\n(Note: under strict mode, this will be undefined rather than window).
We can fix this by making sure the function is bound to the correct this before we return the function to be used later.\nThis way, regardless of how it’s later used, it will still be able to see the original deck object.\nTo do this, we change the function expression to use the ECMAScript 6 arrow syntax.\nArrow functions capture the this where the function is created rather than where it is invoked:
\ntslet deck = {\n suits: [\"hearts\", \"spades\", \"clubs\", \"diamonds\"],\n cards: Array(52),\n createCardPicker: function() {\n // NOTE: the line below is now an arrow function, allowing us to capture 'this' right here\n return () => {\n let pickedCard = Math.floor(Math.random() * 52);\n let pickedSuit = Math.floor(pickedCard / 13);\n\n return { suit: this.suits[pickedSuit], card: pickedCard % 13 };\n };\n }\n};\n\nlet cardPicker = deck.createCardPicker();\nlet pickedCard = cardPicker();\n\nalert(\"card: \" + pickedCard.card + \" of \" + pickedCard.suit);
Even better, TypeScript will warn you when you make this mistake if you pass the --noImplicitThis flag to the compiler.\nIt will point out that this in this.suits[pickedSuit] is of type any.
this parametersUnfortunately, the type of this.suits[pickedSuit] is still any.\nThat’s because this comes from the function expression inside the object literal.\nTo fix this, you can provide an explicit this parameter.\nthis parameters are fake parameters that come first in the parameter list of a function:
\ntsfunction f(this: void) {\n // make sure `this` is unusable in this standalone function\n}
Let’s add a couple of interfaces to our example above, Card and Deck, to make the types clearer and easier to reuse:
\ntsinterface Card {\n suit: string;\n card: number;\n}\ninterface Deck {\n suits: string[];\n cards: number[];\n createCardPicker(this: Deck): () => Card;\n}\nlet deck: Deck = {\n suits: [\"hearts\", \"spades\", \"clubs\", \"diamonds\"],\n cards: Array(52),\n // NOTE: The function now explicitly specifies that its callee must be of type Deck\n createCardPicker: function(this: Deck) {\n return () => {\n let pickedCard = Math.floor(Math.random() * 52);\n let pickedSuit = Math.floor(pickedCard / 13);\n\n return { suit: this.suits[pickedSuit], card: pickedCard % 13 };\n };\n }\n};\n\nlet cardPicker = deck.createCardPicker();\nlet pickedCard = cardPicker();\n\nalert(\"card: \" + pickedCard.card + \" of \" + pickedCard.suit);
Now TypeScript knows that createCardPicker expects to be called on a Deck object.\nThat means that this is of type Deck now, not any, so --noImplicitThis will not cause any errors.
this parameters in callbacksYou can also run into errors with this in callbacks, when you pass functions to a library that will later call them.\nBecause the library that calls your callback will call it like a normal function, this will be undefined.\nWith some work you can use this parameters to prevent errors with callbacks too.\nFirst, the library author needs to annotate the callback type with this:
\ntsinterface UIElement {\n addClickListener(onclick: (this: void, e: Event) => void): void;\n}
this: void means that addClickListener expects onclick to be a function that does not require a this type.\nSecond, annotate your calling code with this:
\ntsclass Handler {\n info: string;\n onClickBad(this: Handler, e: Event) {\n // oops, used `this` here. using this callback would crash at runtime\n this.info = e.message;\n }\n}\nlet h = new Handler();\nuiElement.addClickListener(h.onClickBad); // error!
With this annotated, you make it explicit that onClickBad must be called on an instance of Handler.\nThen TypeScript will detect that addClickListener requires a function that has this: void.\nTo fix the error, change the type of this:
\ntsclass Handler {\n info: string;\n onClickGood(this: void, e: Event) {\n // can't use `this` here because it's of type void!\n console.log(\"clicked!\");\n }\n}\nlet h = new Handler();\nuiElement.addClickListener(h.onClickGood);
Because onClickGood specifies its this type as void, it is legal to pass to addClickListener.\nOf course, this also means that it can’t use this.info.\nIf you want both then you’ll have to use an arrow function:
\ntsclass Handler {\n info: string;\n onClickGood = (e: Event) => {\n this.info = e.message;\n };\n}
This works because arrow functions use the outer this, so you can always pass them to something that expects this: void.\nThe downside is that one arrow function is created per object of type Handler.\nMethods, on the other hand, are only created once and attached to Handler’s prototype.\nThey are shared between all objects of type Handler.
JavaScript is inherently a very dynamic language.\nIt’s not uncommon for a single JavaScript function to return different types of objects based on the shape of the arguments passed in.
\n\ntslet suits = [\"hearts\", \"spades\", \"clubs\", \"diamonds\"];\n\nfunction pickCard(x): any {\n // Check to see if we're working with an object/array\n // if so, they gave us the deck and we'll pick the card\n if (typeof x == \"object\") {\n let pickedCard = Math.floor(Math.random() * x.length);\n return pickedCard;\n }\n // Otherwise just let them pick the card\n else if (typeof x == \"number\") {\n let pickedSuit = Math.floor(x / 13);\n return { suit: suits[pickedSuit], card: x % 13 };\n }\n}\n\nlet myDeck = [\n { suit: \"diamonds\", card: 2 },\n { suit: \"spades\", card: 10 },\n { suit: \"hearts\", card: 4 }\n];\nlet pickedCard1 = myDeck[pickCard(myDeck)];\nalert(\"card: \" + pickedCard1.card + \" of \" + pickedCard1.suit);\n\nlet pickedCard2 = pickCard(15);\nalert(\"card: \" + pickedCard2.card + \" of \" + pickedCard2.suit);
Here, the pickCard function will return two different things based on what the user has passed in.\nIf the users passes in an object that represents the deck, the function will pick the card.\nIf the user picks the card, we tell them which card they’ve picked.\nBut how do we describe this to the type system?
The answer is to supply multiple function types for the same function as a list of overloads.\nThis list is what the compiler will use to resolve function calls.\nLet’s create a list of overloads that describe what our pickCard accepts and what it returns.
\ntslet suits = [\"hearts\", \"spades\", \"clubs\", \"diamonds\"];\n\nfunction pickCard(x: { suit: string; card: number }[]): number;\nfunction pickCard(x: number): { suit: string; card: number };\nfunction pickCard(x): any {\n // Check to see if we're working with an object/array\n // if so, they gave us the deck and we'll pick the card\n if (typeof x == \"object\") {\n let pickedCard = Math.floor(Math.random() * x.length);\n return pickedCard;\n }\n // Otherwise just let them pick the card\n else if (typeof x == \"number\") {\n let pickedSuit = Math.floor(x / 13);\n return { suit: suits[pickedSuit], card: x % 13 };\n }\n}\n\nlet myDeck = [\n { suit: \"diamonds\", card: 2 },\n { suit: \"spades\", card: 10 },\n { suit: \"hearts\", card: 4 }\n];\nlet pickedCard1 = myDeck[pickCard(myDeck)];\nalert(\"card: \" + pickedCard1.card + \" of \" + pickedCard1.suit);\n\nlet pickedCard2 = pickCard(15);\nalert(\"card: \" + pickedCard2.card + \" of \" + pickedCard2.suit);
With this change, the overloads now give us type checked calls to the pickCard function.
In order for the compiler to pick the correct type check, it follows a similar process to the underlying JavaScript.\nIt looks at the overload list and, proceeding with the first overload, attempts to call the function with the provided parameters.\nIf it finds a match, it picks this overload as the correct overload.\nFor this reason, it’s customary to order overloads from most specific to least specific.
\nNote that the function pickCard(x): any piece is not part of the overload list, so it only has two overloads: one that takes an object and one that takes a number.\nCalling pickCard with any other parameter types would cause an error.