Optional & Default Parameters

You can use ? to mark parameters as optional. When declaring your function’s parameters, all required parameters have to come first, followed by optional parameters:

```ts
function log(message: string, userId?: string) {
  let time = new Date().toISOString()
  console.log(time, message, userId || 'Not signed in')
}

log('Page loaded')
log('User signed in', 'da763be')
```

You can even provide default values for optional parameters. Semantically it’s similar to making a parameter optional: from a user’s point of view they don’t have to pass it in, and from a function’s point of view default parameters have to come after required ones. For example, we can rewrite log from ??? as:

function log(message: string, userId = 'Not signed in') {
  let time = new Date().toISOString()
  console.log(time, message, userId)
}

log('User clicked on a button', 'da763be')
log('User signed out')

Notice how when we give userId a default value, we don’t have to type it anymore. TSC is smart enough to infer the parameter’s type from its default value, keeping our code terse and easy to read. You’ll find yourself using default parameters over optional parameters often.

Rest Parameters

If a function takes a list of arguments, you can of course simply pass the list in as an array:

```ts
function sum(numbers: number[]): number {
  return numbers.reduce((total, n) => total + n, 0)
}

sum([1, 2, 3]) // 6
```

Sometimes, you might opt for a variadic function API — one that takes a variable number of arguments — instead of a unary API that takes a single argument. Traditionally, that required using JavaScript’s magic arguments object. Because arguments is only array-like, and not a true array, we first have to convert it to an array before we can call the built-in .reduce on it:

function sumVariadic(): number {
  return Array
    .from(arguments)
    .reduce((total, n) => total + n, 0)
}

sumVariadic(1, 2, 3) // 6

There’s one big problem with using arguments: it’s totally unsafe! If you hover over total or n in your text editor, you’ll see output similar to the following:

Figure 3-1. Using arguments is unsafe

Meaning, TSC inferred that both n and total are of type any, and silently let it pass. How can we safely type variadic functions?

Rest parameters to the rescue! Instead of resorting to the unsafe arguments magic variable, we can instead use rest parameters to safely make our sum function accept any number of arguments:

function sumVariadicSafe(...numbers: number[]): number {
  return numbers.reduce((total, n) => total + n, 0)
}

sumVariadicSafe(1, 2, 3) // 6

That’s it! Notice that the only change between this variadic sum and our original unary sum function (???) is the extra ... in the parameter list — nothing else has to change, and it’s totally typesafe.

A function can have at most one rest parameter, and that parameter has to be the last one in the function’s parameter list. For example, take a look at TSC’s built-in definition for console.log in ??? (if you don’t know what an interface is, don’t worry - we’ll cover it in Chapter 7). console.log takes an optional message, and any number of additional arguments to log.

```ts
interface Console {
  log(message?: any, ...optionalParams: any[]): void
}
```

call, apply, and bind

In addition to invoking a function with parentheses (), JavaScript supports at least two other ways to call a function. Take add from earlier in the chapter:

add(10, 20)
add.call(null, 10, 20)
add.apply(null, [10, 20])

call binds a value to this within your function (in this example, we bind null to this), and applies the rest of its arguments as arguments to your function. apply does the same, but spreads its second argument over your function’s parameters.

bind is similar, in that it binds a this-argument and a list of parameters to your function. The difference is that bind does not invoke your function; instead, it returns a new function, that you can then invoke with (), .call, or .apply, passing more arguments in to be bound to the so-far unbound parameters if you want.

Generator Functions

Generator functions (generators for short) are a convenient way to, well, generate a bunch of values. They give the generator’s consumer fine control over the pace at which you produce those values. Because they’re lazy — that is, they only compute the next value when a consumer asks for it — they can do things that can be hard to do otherwise, like generate infinite lists.

They work like this:

function* createFibonacciGenerator() {
  let a = 0
  let b = 1
  while (true) {
    yield a;
    [a, b] = [b, a + b]
  }
}

let fibonacciGenerator = createFibonacciGenerator() // IterableIterator<number>
fibonacciGenerator.next()   // {value: 0, done: false}
fibonacciGenerator.next()   // {value: 1, done: false}
fibonacciGenerator.next()   // {value: 1, done: false}
fibonacciGenerator.next()   // {value: 2, done: false}
fibonacciGenerator.next()   // {value: 3, done: false}
fibonacciGenerator.next()   // {value: 5, done: false}

We called createFibonacciGenerator, and that returned an IterableIterator. Every time we call next(), the iterator computes the next Fibonacci number and `yield`s it back to us. Notice how TSC is able to infer the type of our iterator from the type of the value we `yield`ed.

We won’t delve deeper into generators in this book — they’re a big topic, and since this book is about TypeScript, I don’t want to get sidetracked with JavaScript features. The short of it is they’re a super cool JavaScript language feature that TypeScript supports too. To learn more about generators, head to their page on MDN.

Iterators

Iterators are the flip side to generators: while generators are a way to produce a stream of values, iterators are a way to consume those values. The terminology can get pretty confusing, so let’s start with a couple of definitions:

Iterable

Any object that contains a property called Symbol.iterator whose value is a generator.

Iterator

Any object that defines a method called next(), which returns an object with the properties value and done.

When you create a generator (for example, by calling createFibonacciGenerator()), you get a value back that’s both an iterable and an iterator — an iterable iterator — because it defines both an Symbol.iterator property and a next() method.

You can manually define an iterator or an iterable by creating an object (or a class) that implements Symbol.iterator or next() respectively. For example, let’s define an iterator that returns the numbers 1 through 10:

let numbers = {
  *[Symbol.iterator]() {
    for (let n = 1; n <= 10; n++) {
      yield n
    }
  }
}

If you type that iterator into your IDE and hover over it, you’ll see TSC infers its type as:

let numbers: {
  [Symbol.iterator](): IterableIterator<number>;
}

In other words, numbers is an iterator, and calling the generator function numbers[Symbol.iterator] returns an iterable iterator.

Not only can you define your own iterators, but you can use JavaScript’s built-in iterators for common collection types — Array, Map, Set, String, and so on² — to do things like:

// Iterate over an iterator with for-of
for (let a of numbers) {
  // 1, 2, 3, etc.
}

// Spread an iterator
let allNumbers = [...numbers] // number[]

// Destructure an iterator
let [one, two, ...rest] = numbers // [number, number, number[]]

Again, we won’t go more deeply into iterators in this book. Read more about iterators and async iterators on MDN.

Function Types

So far, we’ve learned to type functions’ parameters and return types. Now, let’s switch gears and talk about how we can express the full types of functions themselves.

Let’s revisit sum from the top of this chapter. As a reminder, sum looks like this:

function sum(a: number, b: number): number {
  return a + b
}

What is the type of sum? It’s a function that takes two numbers and returns a number. In TypeScript we can express its type as:

(a: number, b: number) => number

This is TypeScript’s syntax for a function’s type, or type signature. You’ll notice it looks remarkably similar to an arrow function - this is intentional! When you pass functions around as arguments, or return them from other functions, this is the syntax you will use to type them.

Function type signatures only contain type-level code — that is, types only, no values. That means function type signatures can express parameter types, this types (see Chapter 7), return types, rest types, and optional types, and they cannot express default values (since a default value is a value, not a type). And since they have no body for TSC to infer from, function types require explicit return type annotations.

function area(radius: number): number | null {
  if (radius < 0) {
    return null
  }
  return Math.PI * (radius ** 2)
}

let r: number = 3
let a = area(r)
if (a !== null) {
  console.info('result:', a)
}

Let’s go through a few of the examples of functions we’ve seen so far in this chapter, and pull out their types into standalone type aliases:

// function greet(name: string)
type Greet = (name: string) => string

// function log(message: string, userId?: string)
type Log = (message: string, userId?: string) => void

// function sumVariadicSafe(...numbers: number[]): number
type SumVariadicSafe = (...numbers: number[]) => number

Getting the hang of it? The functions’ types look remarkably similar to their implementations. This is intentional, and is a language design choice that makes function types easier to reason about.

Let’s make the relationship between function types and their implementations more concrete: if I have a function type, how can I declare a function that implements that type? To do this, you can combine the function type with a function expression that implements that type. For example, let’s rewrite Log to use its shiny new signature:

type Log = (message: string, userId?: string) => void

let log: Log = ( 
  message, 
  userId = 'Not signed in' 
) => {
  let time = new Date().toISOString()
  console.log(time, message, userId)
}

We declare a function expression log, and explicitly type it as type Log.

We don’t need to annotate our parameters twice. Since message is already annotated as a string as part of the type definition for Log, we don’t need to type it again here. Instead, we let TypeScript infer it for us from Log.

We add a default value for userId, since we captured userId’s type in our definition for Log, but we couldn’t capture the default value as part of Log because Log is a type and can’t contain values.

Notice that this is the first example we’ve looked at where we didn’t have to explicitly annotate our function parameter types. Because we already declared that log is of type Log, TSC is able to infer from context that message has to be of type string. This is a powerful feature of TypeScript’s type inference called contextal typing. We’ll revisit contextual typing more throughout this book.

Overloaded Function Types

The function type syntax we used in the last section — type Fn = (...) => ... — is a shorthand call signature. We can instead write it out more explicitly. Again taking the example of Log:

// Shorthand call signature
type Log = (message: string, userId?: string) => void

// Full call signature
type Log = {
  (message: string, userId?: string): void
}

The two are completely equivalent in every way, and differ only in syntax.

Would you ever want to use a full call signature over the shorthand? For simple cases like our Log function, you should prefer the shorthand; but for more complicated functions, there are a few good use cases for full signatures.

The first of these is overloading a function type. But first, what does it even mean to overload a function?

Overloaded function

A function with multiple call signatures.

In most programming languages, once you declare a function that takes some set of parameters and yields some return type, you can call that function with exactly that set of parameters, and you will always get that same return type back. Not so in JavaScript. Because JavaScript is such a dynamic language, it’s a common pattern for there to be multiple ways to call a given function; not only that, but sometimes the output type will actually depend on the input type for an argument!

TypeScript models this dynamism — overloaded function declarations, and a function’s output type depending on its input type — with its static type system. We might take this language feature for granted, but it’s a really advanced feature for a type system to have!³

You can use overloaded function signatures to design really expressive APIs. For example, let’s design an API to book a vacation — we’ll call it Reserve. As usual, let’s start by sketching out its types (with a full type signature this time):

type Reserve = {
  (from: Date, to: Date, destination: string): Reservation
}

Let’s then stub out an implementation for Reserve:

let reserve: Reserve = (from, to, destination) => {
  // ...
}

So if a user wants to book a trip to Bali, she has to call our reserve API with a from date, a to date, and "Bali" as a destination.

We might re-purpose our API to support one way trips too:

type Reserve = {
  (from: Date, to: Date, destination: string): Reservation
  (from: Date, destination: string): Reservation
}

You’ll notice that when you try to run this code, TSC will give you an error at the point where you implement Reserve:

Figure 3-2. TypeError when missing a unified overload signature

This is because of the way call signature overloading works in TypeScript. If you declare a set of overload signatures for a function f, from a caller’s point of view f’s type is the union of those overload signatures. But from f’s implementation’s point of view, there needs to be a single, unified type that can actually be implemented; you need to manually declare this unified call signature when implementing f — it won’t be inferred for you. For our Reserve example, we can update our reserve function like this:

type Reserve = {
  (from: Date, to: Date, destination: string): Reservation
  (from: Date, destination: string): Reservation
} 

let reserve: Reserve = (
  from: Date,
  toOrDestination: Date | string,
  destination?: string
) => { 
  // ...
}

We declare two overloaded function signatures.

The implementation’s signature is the result of us manually combining the two overload signatures (in other words, we computed Signature1 | Signature2 by hand).

let reserve: Reserve = (
  from: any,
  toOrDestination: any,
  destination?: any
) => {
  // ...
}

function getMonth(date: any): number | undefined {
  if (date instanceof Date) {
    return date.getMonth()
  }
}

function getMonth(date: Date): number {
  return date.getMonth()
}

Since reserve might be called in either of two ways, when you implement reserve you have to prove to TSC that you checked how it was called:

let reserve: Reserve = (
  from: Date,
  toOrDestination: Date | string,
  destination?: string
) => {
  if (toOrDestination instanceof Date && destination != null) {
    // Book a one-way trip
  } else if (typeof toOrDestination === 'string') {
    // Book a round trip
  }
}

Overloads come up naturally in browser DOM APIs. For example, the createElement DOM API is used to create a new HTML element. It takes a string corresponding to an HTML tag, and returns a new HTML element of that tag’s type. TypeScript comes with specific types for each HTML element. For example:

• HTMLAnchorElement for <a> elements

• HTMLCanvasElement for <canvas> elements

• HTMLTableElement for <table> elements

Overloaded call signatures are a natural way to model how createElement works. Think about how you might type createElement (try to answer this by yourself before you read on!).

The answer:

type CreateElement = {
  (tag: 'a'): HTMLAnchorElement 
  (tag: 'canvas'): HTMLCanvasElement
  (tag: 'table'): HTMLTableElement
  (tag: string): HTMLElement 
}

let createElement: CreateElement = (tag: string): HTMLElement => { 
  // ...
}

We overload on the parameter’s type, matching on it with string literal types.

We add a catch-all case: if the user passed a custom tag name, or a cutting-edge experimental tag name that hasn’t made its way into TypeScript’s typings yet, we return a generic HTMLElement.

To type the implementation’s parameter, we combine all the types that parameter might have in createElement’s overload signatures, resulting in 'a' | 'canvas' | 'table' | string. Since the three string literal types are all subtypes of string, the type reduces to just string.

function createElement(tag: 'a'): HTMLAnchorElement
function createElement(tag: 'canvas'): HTMLCanvasElement
function createElement(tag: 'table'): HTMLTableElement
function createElement(tag: string): HTMLElement {
  // ...
}

Full type signatures aren’t limited to overloading how you call a function. You can also use them to model properties on functions. Since JavaScript functions are just callable objects, you can assign properties to them to do things like:

function warnUser(warning) {
  if (warnUser.wasCalled) {
    return
  }
  warnUser.wasCalled = true
  alert(warning)
}
warnUser.wasCalled = false

That is, we show the user a warning, and we don’t show a warning more than once. Let’s use TypeScript to type that (admittedly silly) example’s full signature:

type WarnUser = {
  (warning: string): void
  wasCalled: boolean
}

You can then rewrite warnUser as a function expression that implements that signature:

let warnUser: WarnUser = (warning: string) => {
  if (warnUser.wasCalled) {
    return
  }
  warnUser.wasCalled = true
  alert(warning)
}
warnUser.wasCalled = false

Note that TSC is smart enough to realize that though we didn’t assign wasCalled to warnUser when we declared the warnUser function, we did assign wasCalled to it right after.

Using Bounded Polymorphism to Model Arity

A second place where you’ll find yourself using bounded polymorphism is to model some kinds of variadic functions (functions that take multiple arguments). For example, let’s implement our own version of JavaScript’s built-in apply function. We’ll define and use it like this, using unknown for the types we’ll fill in later:

function apply(
  f: (...args: unknown[]) => unknown,
  ...args: unknown[]
): unknown {
  return f(...args)
}

function fill(length: number, value: string): string[] {
  return Array.from({length}, () => value)
}

apply(fill, 10, 'a') // An array of 10 'a's

Now let’s fill in the `unknown`s. The constraints we want to express are:

• f should be a function that takes some set of arguments T, and returns some type R. We don’t know how many arguments it’ll have ahead of time.

• apply takes f, along with the same set of arguments T that f itself takes. Again, we don’t know exactly how many arguments to expect ahead of time.

• apply returns the same type R that f returns.

It looks like we’ll need two type parameters: T, which is an array of arguments, an R, which is an arbitrary return value. Let’s fill in the types:

function apply<T extends unknown[], R>(
  f: (...args: T) => R,
  ...args: T
): R {
  return f(...args)
}

Now when we call apply, TSC will know exactly what the return type is, and it will complain when we pass the wrong number of arguments:

let a = apply(fill, 10, 'a') // string[]
let b = apply(fill, 10) // Error: Expected 3 arguments, but got 2.
let b = apply(fill, 10, 'a', 'z') // Error: Expected 3 arguments, but got 4.