2.1.1 Property Value Shorthands

Sometimes we declare objects with one or more properties whose values are references to variables by the same name. For example, we might have a listeners collection, and in order to assign it to a property called listeners of an object literal, we have to repeat its name. The following snippet has a typical example where we have an object literal declaration with a couple of these repetitive properties:

var listeners = []
function listen() {}
var events = {
  listeners: listeners,
  listen: listen
}

Whenever you find yourself in this situation, you can omit the property value and the colon by taking advantage of the new property value shorthand syntax in ES6. As shown in the following example, the new ES6 syntax makes the assignment implicit:

var listeners = []
function listen() {}
var events = { listeners, listen }

As we’ll further explore in the second part of the book, property value shorthands help de-duplicate the code we write without diluting its meaning. In the following snippet, I reimplemented part of localStorage, a browser API for persistent storage, as an in-memory ponyfill.¹ If it weren’t for the shorthand syntax, the storage object would be more verbose to type out:

var store = {}
var storage = { getItem,  setItem, clear }
function getItem(key) {
  return key in store ? store[key] : null
}
function setItem(key, value) {
  store[key] = value
}
function clear() {
  store = {}
}

That’s the first of many ES6 features that are aimed toward reducing complexity in the code you have to maintain. Once you get used to the syntax, you’ll notice that code readability and developer productivity get boosts as well.

2.1.2 Computed Property Names

Sometimes you have to declare objects that contain properties with names based on variables or other JavaScript expressions, as shown in the following piece of code written in ES5. For this example, assume that expertise is provided to you as a function parameter, and is not a value you know beforehand:

var expertise = 'journalism'
var person = {
  name: 'Sharon',
  age: 27
}
person[expertise] = {
  years: 5,
  interests: ['international', 'politics', 'internet']
}

Object literals in ES6 aren’t constrained to declarations with static names. With computed property names, you can wrap any expression in square brackets, and use that as the property name. When the declaration is reached, your expression is evaluated and used as the property name. The following example shows how the piece of code we just saw could declare the person object in a single step, without having to resort to a second statement adding the person’s expertise.

var expertise = 'journalism'
var person = {
  name: 'Sharon',
  age: 27,
  [expertise]: {
    years: 5,
    interests: ['international', 'politics', 'internet']
  }
}

You can’t combine the property value shorthands with computed property names. Value shorthands are simple compile-time syntactic sugar that helps avoid repetition, while computed property names are evaluated at runtime. Given that we’re trying to mix these two incompatible features, the following example would throw a syntax error. In most cases this combination would lead to code that’s hard to interpret for other humans, so it’s probably a good thing that you can’t combine the two.

var expertise = 'journalism'
var journalism = {
  years: 5,
  interests: ['international', 'politics', 'internet']
}
var person = {
  name: 'Sharon',
  age: 27,
  [expertise] // this is a syntax error!
}

A common scenario for computed property names is when we want to add an entity to an object map that uses the entity.id field as its keys, as shown next. Instead of having to have a third statement where we add the grocery to the groceries map, we can inline that declaration in the groceries object literal itself.

var grocery = {
  id: 'bananas',
  name: 'Bananas',
  units: 6,
  price: 10,
  currency: 'USD'
}
var groceries = {
  [grocery.id]: grocery
}

Another case may be whenever a function receives a parameter that it should then use to build out an object. In ES5 code, you’d need to allocate a variable declaring an object literal, then add the dynamic property, and then return the object. The following example shows exactly that, when creating an envelope that could later be used for Ajax messages that follow a convention: they have an error property with a description when something goes wrong, and a success property when things turn out okay:

function getEnvelope(type, description) {
  var envelope = {
    data: {}
  }
  envelope[type] = description
  return envelope
}

Computed property names help us write the same function more concisely, using a single statement:

function getEnvelope(type, description) {
  return {
    data: {},
    [type]: description
  }
}

The last enhancement coming to object literals is about functions.

2.1.3 Method Definitions

Typically, you can declare methods on an object by adding properties to it. In the next snippet, we’re creating a small event emitter that supports multiple kinds of events. It comes with an emitter#on method that can be used to register event listeners, and an emitter#emit method that can be used to raise events:

var emitter = {
  events: {},
  on: function (type, fn) {
    if (this.events[type] === undefined) {
      this.events[type] = []
    }
    this.events[type].push(fn)
  },
  emit: function (type, event) {
    if (this.events[type] === undefined) {
      return
    }
    this.events[type].forEach(function (fn) {
      fn(event)
    })
  }
}

Starting in ES6, you can declare methods on an object literal using the new method definition syntax. In this case, we can omit the colon and the function keyword. This is meant as a terse alternative to traditional method declarations where you need to use the function keyword. The following example shows how our emitter object looks when using method definitions.

var emitter = {
  events: {},
  on(type, fn) {
    if (this.events[type] === undefined) {
      this.events[type] = []
    }
    this.events[type].push(fn)
  },
  emit(type, event) {
    if (this.events[type] === undefined) {
      return
    }
    this.events[type].forEach(function (fn) {
      fn(event)
    })
  }
}

Arrow functions are another way of declaring functions in ES6, and they come in several flavors. Let’s investigate what arrow functions are, how they can be declared, and how they behave semantically.

2.2.1 Lexical Scoping

In the body of an arrow function, this, arguments, and super point to the containing scope, since arrow functions don’t create a new scope. Consider the following example. We have a timer object with a seconds counter and a start method defined using the syntax we learned about earlier. We then start the timer, wait for a few seconds, and log the current amount of elapsed seconds:

var timer = {
  seconds: 0,
  start() {
    setInterval(() => {
      this.seconds++
    }, 1000)
  }
}
timer.start()
setTimeout(function () {
  console.log(timer.seconds)
}, 3500)
// <- 3

If we had defined the function passed to setInterval as a regular anonymous function instead of using an arrow function, this would’ve been bound to the context of the anonymous function, instead of the context of the start method. We could have implemented timer with a declaration like var self = this at the beginning of the start method, and then referencing self instead of this. With arrow functions, the added complexity of keeping context references around fades away and we can focus on the functionality of our code.

In a similar fashion, lexical binding in ES6 arrow functions also means that function calls won’t be able to change the this context when using .call, .apply, .bind, etc. That limitation is usually more useful than not, as it ensures that the context will always be preserved and constant.

Let’s now shift our attention to the following example. What do you think the console.log statement will print?

function puzzle() {
  return function () {
    console.log(arguments)
  }
}
puzzle('a', 'b', 'c')(1, 2, 3)

The answer is that arguments refers to the context of the anonymous function, and thus the arguments passed to that function will be printed. In this case, those arguments are 1, 2, 3.

What about in the following case, where we use an arrow function instead of the anonymous function in the previous example?

function puzzle() {
  return () => console.log(arguments)
}
puzzle('a', 'b', 'c')(1, 2, 3)

In this case, the arguments object refers to the context of the puzzle function, because arrow functions don’t create a closure. For this reason, the printed arguments will be 'a', 'b', 'c'.

I’ve mentioned there are several flavors of arrow functions, but so far we’ve only looked at their fully fleshed version. What are the other ways to represent an arrow function?

2.2.2 Arrow Function Flavors

Let’s look one more time at the arrow function syntax we’ve learned so far:

var example = (parameters) => {
  // function body
}

An arrow function with exactly one parameter can omit the parentheses. This is optional. It’s useful when passing the arrow function to another method, as it reduces the amount of parentheses involved, making it easier for some humans to parse the code:

var double = value => {
  return value * 2
}

Arrow functions are heavily used for simple functions, such as the double function we just saw. The following flavor of arrow functions does away with the function body. Instead, you provide an expression such as value * 2. When the function is called, the expression is evaluated and its result is returned. The return statement is implicit, and there’s no need for curly braces denoting the function body anymore, as you can only use a single expression:

var double = (value) => value * 2

Note that you can combine implicit parentheses and implicit return, making for concise arrow functions:

var double = value => value * 2

Now that you understand arrow functions, let’s ponder about their merits and where they might be a good fit.

2.2.3 Merits and Use Cases

As a rule of thumb, you shouldn’t blindly adopt ES6 features wherever you can. Instead, it’s best to reason about each case individually and see whether adopting the new feature actually improves code readability and maintainability. ES6 features are not strictly better than what we had all along, and it’s a bad idea to treat them as such.

There are a few situations where arrow functions may not be the best tool. For example, if you have a large function comprised of several lines of code, replacing function with => is hardly going to improve your code. Arrow functions are often most effective for short routines, where the function keyword and syntax boilerplate make up a significant portion of the function expression.

Properly naming a function adds context to make it easier for humans to interpret them. Arrow functions can’t be explicitly named, but they can be named implicitly by assigning them to a variable. In the following example, we assign an arrow function to the throwError variable. When calling this function results in an error, the stack trace properly identifies the arrow function as throwError:

var throwError = message => {
  throw new Error(message)
}
throwError('this is a warning')
<- Uncaught Error: this is a warning
  at throwError

Arrow functions are neat when it comes to defining anonymous functions that should probably be lexically bound anyway, and they can definitely make your code more terse in some situations. They are particularly useful in most functional programming situations, such as when using .map, .filter, or .reduce on collections, as shown in the following example:

[1, 2, 3, 4]
  .map(value => value * 2)
  .filter(value => value > 2)
  .forEach(value => console.log(value))
// <- 4
// <- 6
// <- 8

2.3.1 Destructuring Objects

Imagine you had a program with some comic book characters, Bruce Wayne being one of them, and you want to refer to properties in the object that describes him. Here’s the example object we’ll be using for Batman:

var character = {
  name: 'Bruce',
  pseudonym: 'Batman',
  metadata: {
    age: 34,
    gender: 'male'
  },
  batarang: ['gas pellet', 'bat-mobile control', 'bat-cuffs']
}

If you wanted a pseudonym variable referencing character.pseudonym, you could write the following bit of ES5 code. This is commonplace when, for instance, you’ll be referencing pseudonym in several places in your codebase and you’d prefer to avoid typing out character.pseudonym each time:

var pseudonym = character.pseudonym

With destructuring in assignment, the syntax becomes a bit more clear. As you can see in the next example, you don’t have to write pseudonym twice, while still clearly conveying intent. The following statement is equivalent to the previous one written in ES5 code:

var { pseudonym } = character

Just like you could declare multiple comma-separated variables with a single var statement, you can also declare multiple variables within the curly braces of a destructuring expression:

var { pseudonym, name } = character

In a similar fashion, you could mix and match destructuring with regular variable declarations in the same var statement. While this might look a bit confusing at first, it’ll be up to any JavaScript coding style guides you follow to determine whether it’s appropriate to declare several variables in a single statement. In any case, it goes to show the flexibility offered by destructuring syntax:

var { pseudonym } = character, two = 2

If you want to extract a property named pseudonym but would like to declare it as a variable named alias, you can use the following destructuring syntax, known as aliasing. Note that you can use alias or any other valid variable name:

var { pseudonym: alias } = character
console.log(alias)
// <- 'Batman'

While aliases don’t look any simpler than the ES5 flavor, alias = character.pseudonym, they start making sense when you consider the fact that destructuring supports deep structures, as in the following example:

var { metadata: { gender } } = character

In cases like the previous one, where you have deeply nested properties being destructured, you might be able to convey a property name more clearly if you choose an alias. Consider the next snippet, where a property named code wouldn’t have been as indicative of its contents as colorCode could be:

var { metadata: { gender: characterGender } } = character

The scenario we just saw repeats itself frequently, because properties are often named in the context of their host object. While palette.color.code is perfectly descriptive, code on its own could mean a wide variety of things, and aliases such as colorCode can help you bring context back into the variable name while still using destructuring.

Whenever you access a nonexistent property in ES5 notation, you get a value of undefined:

console.log(character.boots)
// <- undefined
console.log(character['boots'])
// <- undefined

With destructuring, the same behavior prevails. When declaring a destructured variable for a property that’s missing, you’ll get back undefined as well.

var { boots } = character
console.log(boots)
// <- undefined

A destructured declaration accessing a nested property of a parent object that’s null or undefined will throw an Exception, just like regular attempts to access properties of null or undefined would, in other cases.

var { boots: { size } } = character
// <- Exception
var { missing } = null
// <- Exception

When you think of that piece of code as the equivalent ES5 code shown next, it becomes evident why the expression must throw, given that destructuring is mostly syntactic sugar.

var nothing = null
var missing = nothing.missing
// <- Exception

As part of destructuring, you can provide default values for those cases where the value is undefined. The default value can be anything you can think of: numbers, strings, functions, objects, a reference to another variable, etc.

var { boots = { size: 10 } } = character
console.log(boots)
// <- { size: 10 }

Default values can also be provided in nested property destructuring.

var { metadata: { enemy = 'Satan' } } = character
console.log(enemy)
// <- 'Satan'

For use in combination with aliases, you should place the alias first, and then the default value, as shown next.

var { boots: footwear = { size: 10 } } = character

It’s possible to use the computed property names syntax in destructuring patterns. In this case, however, you’re required to provide an alias to be used as the variable name. That’s because computed property names allow arbitrary expressions and thus the compiler wouldn’t be able to infer a variable name. In the following example we use the value alias, and a computed property name to extract the boots property from the character object.

var { ['boo' + 'ts']: characterBoots } = character
console.log(characterBoots)
// <- true

This flavor of destructuring is probably the least useful, as characterBoots = character[type] is usually simpler than { [type]: characterBoots } = character, as it’s a more sequential statement. That being said, the feature is useful when you have properties you want to declare in the object literal, as opposed to using subsequent assignment statements.

That’s it, as far as objects go, in terms of destructuring. What about arrays?

2.3.2 Destructuring Arrays

The syntax for destructuring arrays is similar to that of objects. The following example shows a coordinates object that’s destructured into two variables: x and y. Note how the notation uses square brackets instead of curly braces; this denotes we’re using array destructuring instead of object destructuring. Instead of having to sprinkle your code with implementation details like x = coordinates[0], with destructuring you can convey your meaning clearly and without explicitly referencing the indices, naming the values instead.

var coordinates = [12, -7]
var [x, y] = coordinates
console.log(x)
// <- 12

When destructuring arrays, you can skip uninteresting properties or those that you otherwise don’t need to reference.

var names = ['James', 'L.', 'Howlett']
var [ firstName, , lastName ] = names
console.log(lastName)
// <- 'Howlett'

Array destructuring allows for default values just like object destructuring.

var names = ['James', 'L.']
var [ firstName = 'John', , lastName = 'Doe' ] = names
console.log(lastName)
// <- 'Doe'

In ES5, when you have to swap the values of two variables, you typically resort to a third, temporary variable, as in the following snippet.

var left = 5
var right = 7
var aux = left
left = right
right = aux

Destructuring helps you avoid the aux declaration and focus on your intent. Once again, destructuring helps us convey intent more tersely and effectively for the use case.

var left = 5
var right = 7
[left, right] = [right, left]

The last area of destructuring we’ll be covering is function parameters.

2.3.3 Function Parameter Defaults

Function parameters in ES6 enjoy the ability of specifying default values as well. The following example defines a default exponent with the most commonly used value.

function powerOf(base, exponent = 2) {
  return Math.pow(base, exponent)
}

Defaults can be applied to arrow function parameters as well. When we have default values in an arrow function we must wrap the parameter list in parentheses, even when there’s a single parameter.

var double = (input = 0) => input * 2

Default values aren’t limited to the rightmost parameters of a function, as in a few other programming languages. You could provide default values for any parameter, in any position.

function sumOf(a = 1, b = 2, c = 3) {
  return a + b + c
}
console.log(sumOf(undefined, undefined, 4))
// <- 1 + 2 + 4 = 7

In JavaScript it’s not uncommon to provide a function with an options object, containing several properties. You could determine a default options object if one isn’t provided, as shown in the next snippet.

var defaultOptions = { brand: 'Volkswagen', make: 1999 }
function carFactory(options = defaultOptions) {
  console.log(options.brand)
  console.log(options.make)
}
carFactory()
// <- 'Volkswagen'
// <- 1999

The problem with this approach is that as soon as the consumer of carFactory provides an options object, you lose all of your defaults.

carFactory({ make: 2000 })
// <- undefined
// <- 2000

We can mix function parameter default values with destructuring, and get the best of both worlds.

2.3.4 Function Parameter Destructuring

A better approach than merely providing a default value might be to destructure options entirely, providing default values for each property, individually, within the destructuring pattern. This approach also lets you reference each option without going through an options object, but you lose the ability to reference options directly, which might represent an issue in some situations.

function carFactory({ brand = 'Volkswagen', make = 1999 }) {
  console.log(brand)
  console.log(make)
}
carFactory({ make: 2000 })
// <- 'Volkswagen'
// <- 2000

In this case, however, we’ve once again lost the default value for the case where the consumer doesn’t provide any options. Meaning carFactory() will now throw when an options object isn’t provided. This can be remedied by using the syntax shown in the following snippet of code, which adds a default options value of an empty object. The empty object is then filled, property by property, with the default values on the destructuring pattern.

function carFactory({
  brand = 'Volkswagen',
  make = 1999
} = {}) {
  console.log(brand)
  console.log(make)
}
carFactory()
// <- 'Volkswagen'
// <- 1999

Besides default values, you can use destructuring in function parameters to describe the shape of objects your function can handle. Consider the following code snippet, where we have a car object with several properties. The car object describes its owner, what kind of car it is, who manufactured it, when, and the owner’s preferences when he purchased the car.

var car = {
  owner: {
    id: 'e2c3503a4181968c',
    name: 'Donald Draper'
  },
  brand: 'Peugeot',
  make: 2015,
  model: '208',
  preferences: {
    airbags: true,
    airconditioning: false,
    color: 'red'
  }
}

If we wanted to implement a function that only takes into account certain properties of a parameter, it might be a good idea to reference those properties explicitly by destructuring up front. The upside is that we become aware of every required property upon reading the function’s signature.

When we destructure everything up front, it’s easy to spot when input doesn’t adhere to the contract of a function. The following example shows how every property we need could be specified in the parameter list, laying bare the shape of the objects we can handle in the getCarProductModel API.

var getCarProductModel = ({ brand, make, model }) => ({
  sku: brand + ':' + make + ':' + model,
  brand,
  make,
  model
})
getCarProductModel(car)

Besides default values and filling an options object, let’s explore what else destructuring is good at.

2.3.5 Use Cases for Destructuring

Whenever there’s a function that returns an object or an array, destructuring makes it much terser to interact with. The following example shows a function that returns an object with some coordinates, where we grab only the ones we’re interested in: x and y. We’re avoiding an intermediate point variable declaration that often gets in the way without adding a lot of value to the readability of your code.

function getCoordinates() {
  return { x: 10, y: 22, z: -1, type: '3d' }
}
var { x, y } = getCoordinates()

The case for default option values bears repeating. Imagine you have a random function that produces random integers between a min and a max value, and that it should default to values between 1 and 10. This is particularly interesting as an alternative to named parameters in languages with strong typing features, such as Python and C#. This pattern, where you’re able to define default values for options and then let consumers override them individually, offers great flexibility.

function random({ min = 1, max = 10 } = {}) {
  return Math.floor(Math.random() * (max - min)) + min
}
console.log(random())
// <- 7
console.log(random({ max: 24 }))
// <- 18

Regular expressions are another great fit for destructuring. Destructuring empowers you to name groups from a match without having to resort to index numbers. Here’s an example RegExp that could be used for parsing simple dates, and an example of destructuring those dates into each of their components. The first entry in the resulting array is reserved for the raw input string, and we can discard it.

function splitDate(date) {
  var rdate = /(\d+).(\d+).(\d+)/
  return rdate.exec(date)
}
var [ , year, month, day] = splitDate('2015-11-06')

You’ll want to be careful when the regular expression doesn’t match, as that returns null. Perhaps a better approach would be to test for the failure case before destructuring, as shown in the following bit of code.

var matches = splitDate('2015-11-06')
if (matches === null) {
  return
}
var [, year, month, day] = matches

Let’s turn our attention to spread and rest operators next.

2.4.1 Rest Parameters

You can now precede the last parameter in any JavaScript function with three dots, converting it into a special “rest parameter.” When the rest parameter is the only parameter in a function, it gets all arguments passed to the function: it works just like the .slice solution we saw earlier, but you avoid the need for a complicated construct like arguments, and it’s specified in the parameter list.

function join(...list) {
  return list.join(', ')
}
join('first', 'second', 'third')
// <- 'first, second, third'

Named parameters before the rest parameter won’t be included in the list.

function join(separator, ...list) {
  return list.join(separator)
}
join('; ', 'first', 'second', 'third')
// <- 'first; second; third'

Note that arrow functions with a rest parameter must include parentheses, even when it’s the only parameter. Otherwise, a SyntaxError would be thrown. The following piece of code is a beautiful example of how combining arrow functions and rest parameters can yield concise functional expressions.

var sumAll = (...numbers) => numbers.reduce(
  (total, next) => total + next
)
console.log(sumAll(1, 2, 5))
// <- 8

Compare that with the ES5 version of the same function. Granted, it’s all in the complexity. While terse, the sumAll function can be confusing to readers unused to the .reduce method, or because it uses two arrow functions. This is a complexity trade-off that we’ll cover in the second part of the book.

function sumAll() {
  var numbers = Array.prototype.slice.call(arguments)
  return numbers.reduce(function (total, next) {
    return total + next
  })
}
console.log(sumAll(1, 2, 5))
// <- 8

Next up we have the spread operator. It’s also denoted with three dots, but it serves a slightly different purpose.

2.4.2 Spread Operator

The spread operator can be used to cast any iterable object into an array. Spreading effectively expands an expression onto a target such as an array literal or a function call. The following example uses ...arguments to cast function parameters into an array literal.

function cast() {
  return [...arguments]
}
cast('a', 'b', 'c')
// <- ['a', 'b', 'c']

We could use the spread operator to split a string into an array with each code point that makes up the string.

[...'show me']
// <- ['s', 'h', 'o', 'w', ' ', 'm', 'e']

You can place additional elements to the left and to the right of a spread operation and still get the result you would expect.

function cast() {
  return ['left', ...arguments, 'right']
}
cast('a', 'b', 'c')
// <- ['left', 'a', 'b', 'c', 'right']

Spread is an useful way of combining multiple arrays. The following example shows how you can spread arrays anywhere into an array literal, expanding their elements into place.

var all = [1, ...[2, 3], 4, ...[5], 6, 7]
console.log(all)
// <- [1, 2, 3, 4, 5, 6, 7]

Note that the spread operator isn’t limited to arrays and arguments. The spread operator can be used with any iterable object. Iterable is a protocol in ES6 that allows you to turn any object into something that can be iterated over. We’ll research the iterable protocol in Chapter 4.

Before ES6, whenever you had a dynamic list of arguments that needed to be applied to a function call, you’d use .apply. This is inelegant because .apply also takes a context for this, which, in this scenario, you don’t want to concern yourself with.

fn.apply(null, ['a', 'b', 'c'])

Besides spreading onto arrays, you can also spread items onto function calls. The following example shows how you could use the spread operator to pass an arbitrary number of arguments to the multiply function.

function multiply(left, right) {
  return left * right
}
var result = multiply(...[2, 3])
console.log(result)
// <- 6

Spreading arguments onto a function call can be combined with regular arguments as much as necessary, just like with array literals. The next example calls print with a couple of regular arguments and a couple of arrays being spread over the parameter list. Note how conveniently the rest list parameter matches all the provided arguments. Spread and rest can help make code intent more clear without diluting your codebase.

function print(...list) {
  console.log(list)
}
print(1, ...[2, 3], 4, ...[5])
// <- [1, 2, 3, 4, 5]

Another limitation of .apply is that combining it with the new keyword, when instantiating an object, becomes very verbose. Here’s an example of combining new and .apply to create a Date object. Ignore for a moment that months in JavaScript dates are zero-based, turning 11 into December, and consider how much of the following line of code is spent bending the language in our favor, just to instantiate a Date object.

new (Date.bind.apply(Date, [null, 2015, 11, 31]))
// <- Thu Dec 31 2015

As shown in the next snippet, the spread operator strips away all the complexity and we’re only left with the important bits. It’s a new instance, it uses ... to spread a dynamic list of arguments over the function call, and it’s a Date. That’s it.

new Date(...[2015, 11, 31])
// <- Thu Dec 31 2015

The following table summarizes the use cases we’ve discussed for the spread operator.

2.5.1 String Interpolation

With template literals, you’re able to interpolate any JavaScript expressions inside your templates. When the template literal expression is reached, it’s evaluated and you get back the compiled result. The following example interpolates a name variable into a template literal.

var name = 'Shannon'
var text = `Hello, ${ name }!`
console.log(text)
// <- 'Hello, Shannon!'

We’ve already established that you can use any JavaScript expressions, and not just variables. You can think of each expression in a template literal as defining a variable before the template runs, and then concatenating each variable with the rest of the string. However, the code becomes easier to maintain because it doesn’t involve manually concatenating strings and JavaScript expressions. The variables you use in those expressions, the functions you call, and so on, should all be available to the current scope.

It will be up to your coding style guides to decide how much logic you want to cram into the interpolation expressions. The following code snippet, for example, instantiates a Date object and formats it into a human-readable date inside a template literal.

`The time and date is ${ new Date().toLocaleString() }.`
// <- 'the time and date is 8/26/2015, 3:15:20 PM'

You could interpolate mathematical operations.

`The result of 2+3 equals ${ 2 + 3 }`
// <- 'The result of 2+3 equals 5'

You could even nest template literals, as they are also valid JavaScript expressions.

`This template literal ${ `is ${ 'nested' }` }!`
// <- 'This template literal is nested!'

Another perk of template literals is their multiline string representation support.

2.5.2 Multiline Template Literals

Before template literals, if you wanted to represent strings in multiple lines of JavaScript, you had to resort to escaping, concatenation, arrays, or even elaborate hacks using comments. The following snippet summarizes some of the most common multiline string representations prior to ES6.

var escaped =
'The first line\n\
A second line\n\
Then a third line'

var concatenated =
'The first line\n' `
'A second line\n' `
'Then a third line'

var joined = [
'The first line',
'A second line',
'Then a third line'
].join('\n')

Under ES6, you could use backticks instead. Template literals support multiline strings by default. Note how there are no \n escapes, no concatenation, and no arrays involved.

var multiline =
`The first line
A second line
Then a third line`

Multiline strings really shine when you have, for instance, a chunk of HTML you want to interpolate some variables into. If you need to display a list within the template, you could iterate the list, mapping its items into the corresponding markup, and then return the joined result from an interpolated expression. This makes it a breeze to declare subcomponents within your templates, as shown in the following piece of code.

var book = {
  title: 'Modular ES6',
  excerpt: 'Here goes some properly sanitized HTML',
  tags: ['es6', 'template-literals', 'es6-in-depth']
}
var html = `<article>
  <header>
    <h1>${ book.title }</h1>
  </header>
  <section>${ book.excerpt }</section>
  <footer>
    <ul>
      ${
        book.tags
          .map(tag => `<li>${ tag }</li>`)
          .join('\n      ')
      }
    </ul>
  </footer>
</article>`

The template we’ve just prepared would produce output like what’s shown in the following snippet of code. Note how spacing was preserved,³ and how <li> tags are properly indented thanks to how we joined them together using a few spaces.

<article>
  <header>
    <h1>Modular ES6</h1>
  </header>
  <section>Here goes some properly sanitized HTML</section>
  <footer>
    <ul>
      <li>es6</li>
      <li>template-literals</li>
      <li>es6-in-depth</li>
    </ul>
  </footer>
</article>

A downside when it comes to multiline template literals is indentation. The following example shows a typically indented piece of code with a template literal contained in a function. While we may have expected no indentation, the string has four spaces of indentation.

function getParagraph() {
  return `
    Dear Rod,

    This is a template literal string that's indented
    four spaces. However, you may have expected for it
    to be not indented at all.

    Nico
  `
}

While not ideal, we could get away with a utility function to remove indentation from each line in the resulting string.

function unindent(text) {
  return text
    .split('\n')
    .map(line => line.slice(4))
    .join('\n')
    .trim()
}

Sometimes, it might be a good idea to pre-process the results of interpolated expressions before inserting them into your templates. For these advanced kinds of use cases, it’s possible to use another feature of template literals called tagged templates.

2.5.3 Tagged Templates

By default, JavaScript interprets \ as an escape character with special meaning. For example, \n is interpreted as a newline, \u00f1 is interpreted as ñ, etc. You could avoid these rules using the String.raw tagged template. The next snippet shows a template literal using String.raw, which prevents \n from being interpreted as a newline.

var text = String.raw`"\n" is taken literally.
It'll be escaped instead of interpreted.`
console.log(text)
// "\n" is taken literally.
// It'll be escaped instead of interpreted.

The String.raw prefix we’ve added to our template literal is a tagged template. It’s used to parse the template. Tagged templates receive a parameter with an array containing the static parts of the template, as well as the result of evaluating each expression, each in its own parameter.

As an example, consider the tagged template literal in the next code snippet.

tag`Hello, ${ name }. I am ${ emotion } to meet you!`

That tagged template expression would, in practice, be translated into the following function call.

tag(
  ['Hello, ', '. I am ', ' to meet you!'],
  'Maurice',
  'thrilled'
)

The resulting string is built by taking each part of the template and placing one of the expressions next to it, until there are no more parts of the template left. It might be hard to interpret the argument list without looking at a potential implementation of the default template literal tag, so let’s do that.

The following snippet of code shows a possible implementation of the default tag. It provides the same functionality as a template literal does when a tagged template isn’t explicitly provided. It reduces the parts array into a single value, the result of evaluating the template literal. The result is initialized with the first part, and then each other part of the template is preceded by one of the values. We’ve used the rest parameter syntax for ...values in order to make it easier to grab the result of evaluating each expression in the template. We’re using an arrow function with an implicit return statement, given that its expression is relatively simple.

function tag(parts, ...values) {
  return parts.reduce(
    (all, part, index) => all + values[index - 1] + part
  )
}

You can try the tag template using code like in the following snippet. You’ll notice you get the same output as if you omitted tag, since we’re copying the default behavior.

var name = 'Maurice'
var emotion = 'thrilled'
var text = tag`Hello, ${ name }. I am ${ emotion } to meet you!`
console.log(text)
// <- 'Hello Maurice, I am thrilled to meet you!'

Multiple use cases apply to tagged templates. One possible use case might be to make user input uppercase, making the string sound satirical. That’s what the following piece of code does. We’ve modified tag slightly so that any interpolated strings are uppercased.

function upper(parts, ...values) {
  return parts.reduce((all, part, index) =>
    all + values[index - 1].toUpperCase() + part
  )
}
var name = 'Maurice'
var emotion = 'thrilled'
upper`Hello, ${ name }. I am ${ emotion } to meet you!`
// <- 'Hello MAURICE, I am THRILLED to meet you!'

A decidedly more useful use case would be to sanitize expressions interpolated into your templates, automatically, using a tagged template. Given a template where all expressions are considered user input, we could use a hypothetical sanitize library to remove HTML tags and similar hazards, preventing cross-site scripting (XSS) attacks where users might inject malicious HTML into our websites.

function sanitized(parts, ...values) {
  return parts.reduce((all, part, index) =>
    all + sanitize(values[index - 1]) + part
  )
}
var comment = 'Evil comment<iframe src="http://evil.corp">
    </iframe>'
var html = sanitized`<div>${ comment }</div>`
console.log(html)
// <- '<div>Evil comment</div>'

Phew, that malicious <iframe> almost got us. Rounding out ES6 syntax changes, we have the let and const statements.

2.6.1 Block Scoping and let Statements

Instead of having to declare a new function if we want a deeper scoping level, block scoping allows you to just leverage existing code branches like those in if, for, or while statements; you could also create new {} blocks arbitrarily. As you may or may not know, the JavaScript language allows us to create an indiscriminate number of blocks, just because we want to.

{{{{{ var deep = 'This is available from outer scope.'; }}}}}
console.log(deep)
// <- 'This is available from outer scope.'

With var, because of lexical scoping, one could still access the deep variable from outside those blocks, and not get an error. Sometimes it can be very useful to get errors in these situations, particularly if one or more of the following is true:

• Accessing the inner variable breaks some sort of encapsulation principle in our code

• The inner variable doesn’t belong in the outer scope at all

• The block in question has many siblings that would also want to use the same variable name

• One of the parent blocks already has a variable with the name we need, but the name is still appropriate to use in the inner block

The let statement is an alternative to var. It follows block scoping rules instead of the default lexical scoping rules. With var, the only way of getting a deeper scope is to create a nested function, but with let you can just open another pair of curly braces. This means you don’t need entirely new functions to get a new scope; a simple {} block will do.

let topmost = {}
{
  let inner = {}
  {
    let innermost = {}
  }
  // attempts to access innermost here would throw
}
// attempts to access inner here would throw
// attempts to access innermost here would throw

One useful aspect of let statements is that you can use them when declaring a for loop, and variables will be scoped to the contents of the loop, as shown next.

for (let i = 0; i < 2; i++) {
  console.log(i)
  // <- 0
  // <- 1
}
console.log(i)
// <- i is not defined

Given let variables declared in a loop are scoped to each step in the loop, the bindings would work as expected in combination with an asynchronous function call, as opposed to what we’re used to with var. Let’s look at concrete examples.

First, we’ll look at the typical example of how var scoping works. The i binding is scoped to the printNumbers function, and its value increases all the way to 10 as each timeout callback is scheduled. By the time each callback runs—one every 100 milliseconds—i has a value of 10 and thus that’s what’s printed every single time.

function printNumbers() {
  for (var i = 0; i < 10; i++) {
    setTimeout(function () {
      console.log(i)
    }, i * 100)
  }
}
printNumbers()

Using let, in contrast, binds the variable to the block’s scope. Indeed, each step in the loop still increases the value of the variable, but a new binding is created each step of the way, meaning that each timeout callback will hold a reference to the binding holding the value of i at the point when the callback was scheduled, printing every number from 0 through 9 as expected.

function printNumbers() {
  for (let i = 0; i < 10; i++) {
    setTimeout(function () {
      console.log(i)
    }, i * 100)
  }
}
printNumbers()

One more thing of note about let is a concept called the “Temporal Dead Zone.”

2.6.2 Temporal Dead Zone

In so many words: if you have code such as the following code snippet, it’ll throw. Once execution enters a scope, and until a let statement is reached, attempting to access the variable for said let statement will throw. This is known as the Temporal Dead Zone (TDZ).

{
  console.log(name)
  // <- ReferenceError: name is not defined
  let name = 'Stephen Hawking'
}

If your code tries to access name in any way before the let name statement is reached, the program will throw. Declaring a function that references name before it’s defined is okay, as long as the function doesn’t get executed while name is in the TDZ, and name will be in the TDZ until the let name statement is reached. This snippet won’t throw because return name isn’t executed until after name leaves the TDZ.

function readName() {
  return name
}
let name = 'Stephen Hawking'
console.log(readName())
// <- 'Stephen Hawking'

But the following snippet will, because access to name occurs before leaving the TDZ for name.

function readName() {
  return name
}
console.log(readName())
// ReferenceError: name is not defined
let name = 'Stephen Hawking'

Note that the semantics for these examples don’t change when name isn’t actually assigned a value when initially declared. The next snippet throws as well, as it still tries to access name before leaving the TDZ.

function readName() {
  return name
}
console.log(readName())
// ReferenceError: name is not defined
let name

The following bit of code works because it leaves the TDZ before accessing name in any way.

function readName() {
  return name
}
let name
console.log(readName())
// <- undefined

The only tricky part to remember is that it’s okay to declare functions that access a variable in the TDZ as long as the statements accessing TDZ variables aren’t reached before the let declaration is reached.

The whole point of the TDZ is to make it easier to catch errors where accessing a variable before it’s declared in user code leads to unexpected behavior. This happened a lot before ES6 due both to hoisting and poor coding conventions. In ES6 it’s easier to avoid. Keep in mind that hoisting still applies for let as well. That means variables will be created when we enter the scope, and the TDZ will be born, but they will be inaccessible until code execution hits the place where the variable was actually declared, at which point we leave the TDZ and are allowed to access the variable.

We made it through the Temporal Dead Zone! It’s now time to cover const, a similar statement to let but with a few major differences.

2.6.3 Const Statements

The const statement is block scoped like let, and it follows TDZ semantics as well. In fact, TDZ semantics were implemented because of const, and then TDZ was also applied to let for consistency. The reason why const needed TDZ semantics is that it would otherwise have been possible to assign a value to a hoisted const variable before reaching the const declaration, meaning that the declaration itself would throw. The temporal dead zone defines a solution that solves the problem of making const assignment possible only at declaration time, helps avoid potential issues when using let, and also makes it easy to eventually implement other features that benefit from TDZ semantics.

The following snippet shows how const follows block scoping rules exactly like let.

const pi = 3.1415
{
  const pi = 6
  console.log(pi)
  // <- 6
}
console.log(pi)
// <- 3.1415

We’ve mentioned major differences between let and const. The first one is that const variables must be declared using an initializer. A const declaration must be accompanied by an initializer, as shown in the following snippet.

const pi = 3.1415
const e // SyntaxError, missing initializer

Besides the assignment when initializing a const, variables declared using a const statement can’t be assigned to. Once a const is initialized, you can’t change its value. Under strict mode, attempts to change a const variable will throw. Outside of strict mode, they’ll fail silently, as demonstrated by the following piece of code.

const people = ['Tesla', 'Musk']
people = []
console.log(people)
// <- ['Tesla', 'Musk']

Note that creating a const variable doesn’t mean that the assigned value becomes immutable. This is a common source of confusion, and it is strongly recommended that you pay attention when reading the following warning.

Let’s take a moment to discuss the merits of const and let.

2.6.4 Merits of const and let

New features should never be used for the sake of using new features. ES6 features should be used where they genuinely improve code readability and maintainability. The let statement is able to, in many cases, simplify pieces of code where you’d otherwise declare var statements at the top of a function just so that hoisting doesn’t produce unexpected results. Using the let statement you’d be able to place your declarations at the top of a code block, instead of the top of the whole function, reducing the latency in mental trips to the top of the scope.

Using the const statement is a great way to prevent accidents. The following piece of code is a plausibly error-prone scenario where we pass a reference to an items variable off to a checklist function, which then returns a todo API that in turn interacts with said items reference. When the items variable is changed to reference another list of items, we’re in for a world of hurt—the todo API still works with the value items used to have, but items is referencing something else now.

var items = ['a', 'b', 'c']
var todo = checklist(items)
todo.check()
console.log(items)
// <- ['b', 'c']
items = ['d', 'e']
todo.check()
console.log(items)
// <- ['d', 'e'], would be ['c'] if items had been constant
function checklist(items) {
  return {
    check: () => items.shift()
  }
}

This type of problem is hard to debug because it might take a while until you figure out that the reference was modified. The const statement helps prevent this scenario by producing a runtime error (under strict mode), which should help capture the bug soon after it’s introduced.

A similar benefit of using the const statement is its ability to visually identify variables that aren’t reassigned. The const cue signals that the variable binding is read-only and thus we have one less thing to worry about when reading a piece of code.

If we choose to default to using const and use let for variables that need to be reassigned, all variables will follow the same scoping rules, which makes code easier to reason about. The reason why const is sometimes proposed as the “default” variable declaration type is that it’s the one that does the least: const prevents reassignment, follows block scoping, and the declared binding can’t be accessed before the declaration statement is executed. The let statement allows reassignment, but behaves like const, so it naturally follows to choose let when we’re in need of a reassignable variable.

On the counter side, var is a more complex declaration because it is hard to use in code branches due to function scoping rules, it allows reassignment, and it can be accessed before the declaration statement is reached. The var statement is inferior to const and let, which do less, and is thus less prominent in modern JavaScript codebases.

Throughout this book, we’ll follow the practice of using const by default and let when reassignment is desirable. You can learn more about the rationale behind this choice in Chapter 9.

3.1.1 Class Fundamentals

When learning about new language features, it’s always a good idea to look at existing constructs first, and then see how the new feature improves those use cases. We’ll start by looking at a simple prototype-based JavaScript constructor and then compare that with the newer classes syntax in ES6.

The following code snippet represents a fruit using a constructor function and adding a couple of methods to the prototype. The constructor function takes a name and the amount of calories for a fruit, and defaults to the fruit being in a single piece. There’s a .chop method that will slice another piece of fruit, and then there’s a .bite method. The person passed into .bite will eat a piece of fruit, getting satiety equal to the remaining calories divided by the amount of fruit pieces left.

function Fruit(name, calories) {
  this.name = name
  this.calories = calories
  this.pieces = 1
}
Fruit.prototype.chop = function () {
  this.pieces++
}
Fruit.prototype.bite = function (person) {
  if (this.pieces < 1) {
    return
  }
  const calories = this.calories / this.pieces
  person.satiety += calories
  this.calories -= calories
  this.pieces--
}

While fairly simple, the piece of code we just put together should be enough to note a few things. We have a constructor function that takes a couple of parameters, a pair of methods, and a number of properties. The next snippet codifies how one should create a Fruit and a person that chops the fruit into four slices and then takes three bites.

const person = { satiety: 0 }
const apple = new Fruit('apple', 140)
apple.chop()
apple.chop()
apple.chop()
apple.bite(person)
apple.bite(person)
apple.bite(person)
console.log(person.satiety)
// <- 105
console.log(apple.pieces)
// <- 1
console.log(apple.calories)
// <- 35

When using class syntax, as shown in the following code listing, the constructor function is declared as an explicit member of the Fruit class, and methods follow the object literal method definition syntax. When we compare the class syntax with the prototype-based syntax, you’ll notice we’re reducing the amount of boilerplate code quite a bit by avoiding explicit references to Fruit.prototype while declaring methods. The fact that the entire declaration is kept inside the class block also helps the reader understand the scope of this piece of code, making our classes’ intent clearer. Lastly, having the constructor explicitly as a method member of Fruit makes the class syntax easier to understand when compared with the prototype-based flavor of class syntax.

class Fruit {
  constructor(name, calories) {
    this.name = name
    this.calories = calories
    this.pieces = 1
  }
  chop() {
    this.pieces++
  }
  bite(person) {
    if (this.pieces < 1) {
      return
    }
    const calories = this.calories / this.pieces
    person.satiety += calories
    this.calories -= calories
    this.pieces--
  }
}

A not-so-minor detail you might have missed is that there aren’t any commas in between method declarations of the Fruit class. That’s not a mistake our copious copyeditors missed, but rather part of the class syntax. The distinction can help avoid mistakes where we treat plain objects and classes as interchangeable even though they’re not, and at the same time it makes classes better suited for future improvements to the syntax such as public and private class fields.

The class-based solution is equivalent to the prototype-based piece of code we wrote earlier. Consuming a fruit wouldn’t change in the slightest; the API for Fruit remains unchanged. The previous piece of code where we instantiated an apple, chopped it into smaller pieces, and ate most of it would work well with our class-flavored Fruit as well.

It’s worth noting that class declarations aren’t hoisted to the top of their scope, unlike function declarations. That means you won’t be able to instantiate, or otherwise access, a class before its declaration is reached and executed.

new Person() // <- ReferenceError: Person is not defined
class Person {
}

Besides the class declaration syntax presented earlier, classes can also be declared as expressions, just like with function declarations and function expressions. You may omit the name for a class expression, as shown in the following bit of code.

const Person = class {
  constructor(name) {
    this.name = name
  }
}

Class expressions could be easily returned from a function, making it possible to create a factory of classes with minimal effort. In the following example we create a JakePerson class dynamically in an arrow function that takes a name parameter and then feeds that to the parent Person constructor via super().

const createPersonClass = name => class extends Person {
  constructor() {
    super(name)
  }
}
const JakePerson = createPersonClass('Jake')
const jake = new JakePerson()

We’ll dig deeper into class inheritance later. Let’s take a more nuanced look at properties and methods first.

3.1.2 Properties and Methods in Classes

It should be noted that the constructor method declaration is an optional member of a class declaration. The following bit of code shows an entirely valid class declaration that’s comparable to an empty constructor function by the same name.

class Fruit {
}
function Fruit() {
}

Any arguments passed to new Log() will be received as parameters to the constructor method for Log, as depicted next. You can use those parameters to initialize instances of the class.

class Log {
  constructor(...args) {
    console.log(args)
  }
}
new Log('a', 'b', 'c')
// <- ['a' 'b' 'c']

The following example shows a class where we create and initialize an instance property named count upon construction of each instance. The get next method declaration indicates instances of our Counter class will have a next property that will return the results of calling its method, whenever that property is accessed.

class Counter {
  constructor(start) {
    this.count = start
  }
  get next() {
    return this.count++
  }
}

In this case, you could consume the Counter class as shown in the next snippet. Each time the .next property is accessed, the count raises by one. While mildly useful, this sort of use case is usually better suited by methods than by magical get property accessors, and we need to be careful not to abuse property accessors, as consuming an object that abuses of accessors may become very confusing.

const counter = new Counter(2)
console.log(counter.next)
// <- 2
console.log(counter.next)
// <- 3
console.log(counter.next)
// <- 4

When paired with setters, though, accessors may provide an interesting bridge between an object and its underlying data store. Consider the following example where we define a class that can be used to store and retrieve JSON data from localStorage using the provided storage key.

class LocalStorage {
  constructor(key) {
    this.key = key
  }
  get data() {
    return JSON.parse(localStorage.getItem(this.key))
  }
  set data(data) {
    localStorage.setItem(this.key, JSON.stringify(data))
  }
}

Then you could use the LocalStorage class as shown in the next example. Any value that’s assigned to ls.data will be converted to its JSON object string representation and stored in localStorage. Then, when the property is read from, the same key will be used to retrieve the previously stored contents, parse them as JSON into an object, and returned.

const ls = new LocalStorage('groceries')
ls.data = ['apples', 'bananas', 'grapes']
console.log(ls.data)
// <- ['apples', 'bananas', 'grapes']

Besides getters and setters, you can also define regular instance methods, as we’ve explored earlier when creating the Fruit class. The following code example creates a Person class that’s able to eat Fruit instances as we had declared them earlier. We then instantiate a fruit and a person, and have the person eat the fruit. The person ends up with a satiety level equal to 40, because he ate the whole fruit.

class Person {
  constructor() {
    this.satiety = 0
  }
  eat(fruit) {
    while (fruit.pieces > 0) {
      fruit.bite(this)
    }
  }
}
const plum = new Fruit('plum', 40)
const person = new Person()
person.eat(plum)
console.log(person.satiety)
// <- 40

Sometimes it’s necessary to add static methods at the class level, rather than members at the instance level. Using syntax available before ES6, instance members have to be explicitly added to the prototype chain. Meanwhile, static methods should be added to the constructor directly.

function Person() {
  this.hunger = 100
}
Person.prototype.eat = function () {
  this.hunger--
}
Person.isPerson = function (person) {
  return person instanceof Person
}

JavaScript classes allow you to define static methods like Person.isPerson using the static keyword, much like you would use get or set as a prefix to a method definition that’s a getter or a setter.

The following example defines a MathHelper class with a static sum method that’s able to calculate the sum of all numbers passed to it in a function call, by taking advantage of the Array#reduce method.

class MathHelper {
  static sum(...numbers) {
    return numbers.reduce((a, b) => a + b)
  }
}
console.log(MathHelper.sum(1, 2, 3, 4, 5))
// <- 15

Finally, it’s worth mentioning that you could also declare static property accessors, such as getters or setters (static get, static set). These might come in handy when maintaining global configuration state for a class, or when a class is used under a singleton pattern. Of course, you’re probably better off using plain old JavaScript objects at that point, rather than creating a class you never intend to instantiate or only intend to instantiate once. This is JavaScript, a highly dynamic language, after all.

3.1.3 Extending JavaScript Classes

You could use plain JavaScript to extend the Fruit class, but as you will notice by reading the next code snippet, declaring a subclass involves esoteric knowledge such as Parent.call(this) in order to pass in parameters to the parent class so that we can properly initialize the subclass, and setting the prototype of the subclass to an instance of the parent class’s prototype. As you can readily find heaps of information about prototypal inheritance around the web, we won’t be delving into detailed minutia about prototypal inheritance.

function Banana() {
  Fruit.call(this, 'banana', 105)
}
Banana.prototype = Object.create(Fruit.prototype)
Banana.prototype.slice = function () {
  this.pieces = 12
}

Given the ephemeral knowledge one has to remember, and the fact that Object.create was only made available in ES5, JavaScript developers have historically turned to libraries to resolve their prototype inheritance issues. One such example is util.inherits in Node.js, which is usually favored over Object.create for legacy support reasons.

const util = require('util')
function Banana() {
  Fruit.call(this, 'banana', 105)
}
util.inherits(Banana, Fruit)
Banana.prototype.slice = function () {
  this.pieces = 12
}

Consuming the Banana constructor is no different than how we used Fruit, except that the banana has a name and calories already assigned to it, and they come with an extra slice method we can use to promptly chop the banana instance into 12 pieces. The following piece of code shows the Banana in action as we take a bite.

const person = { satiety: 0 }
const banana = new Banana()
banana.slice()
banana.bite(person)
console.log(person.satiety)
// <- 8.75
console.log(banana.pieces)
// <- 11
console.log(banana.calories)
// <- 96.25

Classes consolidate prototypal inheritance, which up until recently had been highly contested in user-space by several libraries trying to make it easier to deal with prototypal inheritance in JavaScript.

The Fruit class is ripe for inheritance. In the following code snippet we create the Banana class as an extension of the Fruit class. Here, the syntax clearly signals our intent and we don’t have to worry about thoroughly understanding prototypal inheritance in order to get to the results that we want. When we want to forward parameters to the underlying Fruit constructor, we can use super. The super keyword can also be used to call functions in the parent class, such as super.chop, and it’s not just limited to the constructor for the parent class.

class Banana extends Fruit {
  constructor() {
    super('banana', 105)
  }
  slice() {
    this.pieces = 12
  }
}

Even though the class keyword is static we can still leverage JavaScript’s flexible and functional properties when declaring classes. Any expression that returns a constructor function can be fed to extends. For example, we could have a constructor function factory and use that as the base class.

The following piece of code has a createJuicyFruit function where we forward the name and calories for a fruit to the Fruit class using a super call, and then all we have to do to create a Plum is extend the intermediary JuicyFruit class.

const createJuicyFruit = (...params) =>
  class JuicyFruit extends Fruit {
    constructor() {
      this.juice = 0
      super(...params)
    }
    squeeze() {
      if (this.calories <= 0) {
        return
      }
      this.calories -= 10
      this.juice += 3
    }
  }
class Plum extends createJuicyFruit('plum', 30) {
}

Let’s move onto Symbol. While not an iteration or flow control mechanism, learning about Symbol is crucial to shaping an understanding of iteration protocols, which are discussed at length later in the chapter.

3.2.1 Local Symbols

Symbols can be created using the Symbol wrapper object. In the following piece of code, we create our first symbol.

const first = Symbol()

While you can use the new keyword with Number and String, the new operator throws a TypeError when we try it on Symbol. This avoids mistakes and confusing behavior like new Number(3) !== Number(3). The following snippet shows the error being thrown.

const oops = new Symbol()
// <- TypeError, Symbol is not a constructor

For debugging purposes, you can create symbols using a description.

const mystery = Symbol('my symbol')

Like numbers or strings, symbols are immutable. Unlike other value types, however, symbols are unique. As shown in the next piece of code, descriptions don’t affect that uniqueness. Symbols created using the same description are also unique and thus different from each other.

console.log(Number(3) === Number(3))
// <- true
console.log(Symbol() === Symbol())
// <- false
console.log(Symbol('my symbol') === Symbol('my symbol'))
// <- false

Symbols are of type symbol, new in ES6. The following snippet shows how typeof returns the new type string for symbols.

console.log(typeof Symbol())
// <- 'symbol'
console.log(typeof Symbol('my symbol'))
// <- 'symbol'

Symbols can be used as property keys on objects. Note how you can use a computed property name to avoid an extra statement just to add a weapon symbol key to the character object, as shown in the following example. Note also that, in order to access a symbol property, you’ll need a reference to the symbol that was used to create said property.

const weapon = Symbol('weapon')
const character = {
  name: 'Penguin',
  [weapon]: 'umbrella'
}
console.log(character[weapon])
// <- 'umbrella'

Keep in mind that symbol keys are hidden from many of the traditional ways of pulling keys from an object. The next bit of code shows how for..in, Object.keys, and Object.getOwnPropertyNames fail to report on symbol properties.

for (let key in character) {
  console.log(key)
  // <- 'name'
}
console.log(Object.keys(character))
// <- ['name']
console.log(Object.getOwnPropertyNames(character))
// <- ['name']

This aspect of symbols means that code that was written before ES6 and without symbols in mind won’t unexpectedly start stumbling upon symbols. In a similar fashion, as shown next, symbol properties are discarded when representing an object as JSON.

console.log(JSON.stringify(character))
// <- '{"name":"Penguin"}'

That being said, symbols are by no means a safe mechanism to conceal properties. Even though you won’t stumble upon symbol properties when using reflection or serialization methods, symbols are revealed by a dedicated method as shown in the next snippet of code. In other words, symbols are not nonenumerable, but hidden in plain sight. Using Object.getOwnPropertySymbols we can retrieve all symbols used as property keys on any given object.

console.log(Object.getOwnPropertySymbols(character))
// <- [Symbol(weapon)]

Now that we’ve established how symbols work, what can we use them for?

3.2.2 Practical Use Cases for Symbols

Symbols could be used by a library to map objects to DOM elements. For example, a library that needs to associate the API object for a calendar to the provided DOM element. Before ES6, there wasn’t a clear way of mapping DOM elements to objects. You could add a property to a DOM element pointing to the API, but polluting DOM elements with custom properties is a bad practice. You have to be careful to use property keys that won’t be used by other libraries, or worse, by the language itself in the future. That leaves you with using an array lookup table containing an entry for each DOM/API pair. That, however, might be slow in long-running applications where the array lookup table might grow in size, slowing down the lookup operation over time.

Symbols, on the other hand, don’t have this problem. They can be used as properties that don’t have a risk of clashing with future language features, as they’re unique. The following code snippet shows how a symbol could be used to map DOM elements into calendar API objects.

const cache = Symbol('calendar')
function createCalendar(el) {
  if (cache in el) { // does the symbol exist in the element?
    return el[cache] // use the cache to avoid re-instantiation
  }
  const api = el[cache] = {
    // the calendar API goes here
  }
  return api
}

There is an ES6 built-in—the WeakMap—that can be used to uniquely map objects to other objects without using arrays or placing foreign properties on the objects we want to be able to look up. In contrast with array lookup tables, WeakMap lookups are constant in time or O(1). We’ll explore WeakMap in Chapter 5, alongside other ES6 collection built-ins.

const character = {
  name: 'Thor',
  toJSON: () => ({
    key: 'value'
  })
}
console.log(JSON.stringify(character))
// <- '"{"key":"value"}"'

const character = {
  name: 'Thor',
  toJSON: true
}
console.log(JSON.stringify(character))
// <- '"{"name":"Thor","toJSON":true}"'

const json = Symbol('alternative to toJSON')
const character = {
  name: 'Thor',
  [json]: () => ({
    key: 'value'
  })
}
stringify(character)
function stringify(target) {
  if (json in target) {
    return JSON.stringify(target[json]())
  }
  return JSON.stringify(target)
}

stringify.as = json

3.2.3 Global Symbol Registry

A code realm is any JavaScript execution context, such as the page your application is running in, an <iframe> within that page, a script running through eval, or a worker of any kind—such as web workers, service workers, or shared workers.¹ Each of these execution contexts has its own global object. Global variables defined on the window object of a page, for example, aren’t available to a ServiceWorker. In contrast, the global symbol registry is shared across all code realms.

There are two methods that interact with the runtime-wide global symbol registry: Symbol.for and Symbol.keyFor. What do they do?

const example = Symbol.for('example')
console.log(example === Symbol.for('example'))
// <- true

const example = Symbol.for('example')
console.log(Symbol.keyFor(example))
// <- 'example'

console.log(Symbol.keyFor(Symbol()))
// <- undefined

const example = Symbol.for('example')
console.log(Symbol.keyFor(Symbol('example')))
// <- undefined

const d = document
const frame = d.body.appendChild(d.createElement('iframe'))
const framed = frame.contentWindow
const s1 = window.Symbol.for('example')
const s2 = framed.Symbol.for('example')
console.log(s1 === s2)
// <- true

3.2.4 Well-Known Symbols

So far we’ve covered symbols you can create using the Symbol function and those you can create through Symbol.for. The third and last kind of symbols we’re going to cover are the well-known symbols. These are built into the language instead of created by JavaScript developers, and they provide hooks into internal language behavior, allowing you to extend or customize aspects of the language that weren’t accessible prior to ES6.

A great example of how symbols can add extensibility to the language without breaking existing code is the Symbol.toPrimitive well-known symbol. It can be assigned a function to determine how an object is cast into a primitive value. The function receives a hint parameter that can be 'string', 'number', or 'default', indicating what type of primitive value is expected.

const morphling = {
  [Symbol.toPrimitive](hint) {
    if (hint === 'number') {
      return Infinity
    }
    if (hint === 'string') {
      return 'a lot'
    }
    return '[object Morphling]'
  }
}
console.log(+morphling)
// <- Infinity
console.log(`That is ${ morphling }!`)
// <- 'That is a lot!'
console.log(morphling + ' is powerful')
// <- '[object Morphling] is powerful'

Another example of a well-known symbol is Symbol.match. A regular expression that sets Symbol.match to false will be treated as a string literal when passed to .startsWith, .endsWith, or .includes. These three functions are new string methods in ES6. First we have .startsWith, which can be used to determine if the string starts with another string. Then there’s .endsWith, which finds out whether the string ends in another one. Lastly, the .includes method returns true if a string contains another one. The next snippet of code shows how Symbol.match can be used to compare a string with the string representation of a regular expression.

const text = '/an example string/'
const regex = /an example string/
regex[Symbol.match] = false
console.log(text.startsWith(regex))
// <- true

If the regular expression wasn’t modified through the symbol, it would’ve thrown because the .startsWith method expects a string instead of a regular expression.

const frame = document.createElement('iframe')
document.body.appendChild(frame)
Symbol.iterator === frame.contentWindow.Symbol.iterator
// <- true

console.log(Symbol.keyFor(Symbol.iterator))
// <- undefined

3.3.1 Extending Objects with Object.assign

The need to provide default values for a configuration object is not at all uncommon. Typically, libraries and well-designed component interfaces come with sensible defaults that cater to the most frequented use cases.

A Markdown library, for example, might convert Markdown into HTML by providing only an input parameter. That’s its most common use case, simply parsing Markdown, and so the library doesn’t demand that the consumer provides any options. The library might, however, support many different options that could be used to tweak its parsing behavior. It could have an option to allow <script> or <iframe> tags, or an option to highlight keywords in code snippets using CSS.

Imagine, for example, that you want to provide a set of defaults like the one shown next.

const defaults = {
  scripts: false,
  iframes: false,
  highlightSyntax: true
}

One possibility would be to use the defaults object as the default value for the options parameter, using destructuring. In this case, the users must provide values for every option whenever they decide to provide any options at all.

function md(input, options=defaults) {
}

The default values have to be merged with user-provided configuration, somehow. That’s where Object.assign comes in, as shown in the following example. We start with an empty {} object—which will be mutated and returned by Object.assign—we copy the default values over to it, and then copy the options on top. The resulting config object will have all of the default values plus the user-provided configuration.

function md(input, options) {
  const config = Object.assign({}, defaults, options)
}

For any properties that had a default value where the user also provided a value, the user-provided value will prevail. Here’s how Object.assign works. First, it takes the first argument passed to it; let’s call it target. It then iterates over all keys of each of the other arguments; let’s call them sources. For each source in sources, all of its properties are iterated and assigned to target. The end result is that rightmost sources—in our case, the options object—overwrite any previously assigned values, as shown in the following bit of code.

const defaults = {
  first: 'first',
  second: 'second'
}
function applyDefaults(options) {
  return Object.assign({}, defaults, options)
}
applyDefaults()
// <- { first: 'first', second: 'second' }
applyDefaults({ third: 3 })
// <- { first: 'first', second: 'second', third: 3 }
applyDefaults({ second: false })
// <- { first: 'first', second: false }

Before Object.assign made its way into the language, there were numerous similar implementations of this technique in user-land JavaScript, with names like assign, or extend. Adding Object.assign to the language consolidates these options into a single method.

Note that Object.assign takes into consideration only own enumerable properties, including both string and symbol properties.

const defaults = {
  [Symbol('currency')]: 'USD'
}
const options = {
  price: '0.99'
}
Object.defineProperty(options, 'name', {
  value: 'Espresso Shot',
  enumerable: false
})
console.log(Object.assign({}, defaults, options))
// <- { [Symbol('currency')]: 'USD', price: '0.99' }

Note, however, that Object.assign doesn’t cater to every need. While most user-land implementations have the ability to perform deep assignment, Object.assign doesn’t offer a recursive treatment of objects. Object values are assigned as properties on target directly, instead of being recursively assigned key by key.

In the following bit of code you might expect the f property to be added to target.a while keeping b.c and b.d intact, but the b.c and b.d properties are lost when using Object.assign.

Object.assign({}, { a: { b: 'c', d: 'e' } }, { a: { f: 'g' } })
// <- { a: { f: 'g' } }

In the same vein, arrays don’t get any special treatment either. If you expected recursive behavior in Object.assign the following snippet of code may also come as a surprise, where you may have expected the resulting object to have 'd' in the third position of the array.

Object.assign({}, { a: ['b', 'c', 'd'] }, { a: ['e', 'f'] })
// <- { a: ['e', 'f'] }

At the time of this writing, there’s an ECMAScript stage 3 proposal² to implement spread in objects, similar to how you can spread iterable objects onto an array in ES6. Spreading an object onto another is equivalent to using an Object.assign function call.

The following piece of code shows a few cases where we’re spreading the properties of an object onto another one, and their Object.assign counterpart. As you can see, using object spread is more succinct and should be preferred where possible.

const grocery = { ...details }
// Object.assign({}, details)
const grocery = { type: 'fruit', ...details }
// Object.assign({ type: 'fruit' }, details)
const grocery = { type: 'fruit', ...details, ...fruit }
// Object.assign({ type: 'fruit' }, details, fruit)
const grocery = { type: 'fruit', ...details, color: 'red' }
// Object.assign({ type: 'fruit' }, details, { color: 'red' })

As a counterpart to object spread, the proposal includes object rest properties, which is similar to the array rest pattern. We can use object rest whenever we’re destructuring an object.

The following example shows how we could leverage object rest to get an object containing only properties that we haven’t explicitly named in the parameter list. Note that the object rest property must be in the last position of destructuring, just like the array rest pattern.

const getUnknownProperties = ({ name, type, ...unknown }) =>
  unknown
getUnknownProperties({
  name: 'Carrot',
  type: 'vegetable',
  color: 'orange'
})
// <- { color: 'orange' }

We could take a similar approach when destructuring an object in a variable declaration statement. In the next example, every property that’s not explicitly destructured is placed in a meta object.

const { name, type, ...meta } = {
  name: 'Carrot',
  type: 'vegetable',
  color: 'orange'
}
// <- name = 'Carrot'
// <- type = 'vegetable'
// <- meta = { color: 'orange' }

We dive deeper into object rest and spread in Chapter 9.

3.3.2 Comparing Objects with Object.is

The Object.is method is a slightly different version of the strict equality comparison operator, ===. For the most part, Object.is(a, b) is equal to a === b. There are two differences: the case of NaN and the case of -0 and +0. This algorithm is referred to as SameValue in the ECMAScript specification.

When NaN is compared to NaN, the strict equality comparison operator returns false because NaN is not equal to itself. The Object.is method, however, returns true in this special case.

NaN === NaN
// <- false
Object.is(NaN, NaN)
// <- true

Similarly, when -0 is compared to +0, the === operator produces true while Object.is returns false.

-0 === +0
// <- true
Object.is(-0, +0)
// <- false

These differences may not seem like much, but dealing with NaN has always been cumbersome because of its special quirks, such as typeof NaN being 'number' and it not being equal to itself.

3.3.3 Object.setPrototypeOf

The Object.setPrototypeOf method does exactly what its name conveys: it sets the prototype of an object to a reference to another object. It’s considered the proper way of setting the prototype, as opposed to using __proto__, which is a legacy feature.

Before ES6, we were introduced to Object.create in ES5. Using that method, we could create an object based on any prototype passed into Object.create, as shown next.

const baseCat = { type: 'cat', legs: 4 }
const cat = Object.create(baseCat)
cat.name = 'Milanesita'

The Object.create method is, however, limited to newly created objects. In contrast, we could use Object.setPrototypeOf to change the prototype of an object that already exists, as shown in the following code snippet.

const baseCat = { type: 'cat', legs: 4 }
const cat = Object.setPrototypeOf(
  { name: 'Milanesita' },
  baseCat
)

Note however that there are serious performance implications when using Object.setPrototypeOf as opposed to Object.create, and some careful consideration is in order before you decide to go ahead and sprinkle Object.setPrototypeOf all over a codebase.

3.4.1 A Primer on JavaScript Decorators

The syntax for JavaScript decorators is fairly similar to that of Python decorators. JavaScript decorators may be applied to classes and any statically defined properties, such as those found on an object literal declaration or in a class declaration—even if they are get accessors, set accessors, or static properties.

The proposal defines a decorator as an @ followed by a sequence of dotted identifiers⁴ and an optional argument list. Here are a few examples:

• @decorators.frozen is a valid decorator

• @decorators.frozen(true) is a valid decorator

• @decorators().frozen() is a syntax error

• @decorators['frozen'] is a syntax error

Zero or more decorators can be attached to class declarations and class members.

@inanimate
class Car {}

@expensive
@speed('fast')
class Lamborghini extends Car {}

class View {
  @throttle(200) // reconcile once every 200ms at most
  reconcile() {}
}

Decorators are implemented by way of functions. Member decorator functions take a member descriptor and return a member descriptor. Member descriptors are similar to property descriptors, but with a different shape. The following bit of code has the member descriptor interface, as defined by the decorators proposal. An optional finisher function receives the class constructor, allowing us to perform operations related to the class whose property is being decorated.

interface MemberDescriptor {
  kind: "Property"
  key: string,
  isStatic: boolean,
  descriptor: PropertyDescriptor,
  extras?: MemberDescriptor[]
  finisher?: (constructor): void;
}

In the following example we define a readonly member decorator function that makes decorated members nonwritable. Taking advantage of the object rest parameter and object spread, we modify the property descriptor to be non-writable while keeping the rest of the member descriptor unchanged.

function readonly({ descriptor, ...rest }) {
  return {
    ...rest,
    descriptor: {
      ...descriptor,
      writable: false
    }
  }
}

Class decorator functions take a ctor, which is the class constructor being decorated; a heritage parameter, containing the parent class when the decorated class extends another class; and a members array, with a list of member descriptors for the class being decorated.

We could implement a class-wide readonlyMembers decorator by reusing the readonly member decorator on each member descriptor for a decorated class, as shown next.

function readonlyMembers(ctor, heritage, members) {
  return members.map(member => readonly(member))
}

3.4.2 Stacking Decorators and a Warning About Immutability

With all the fluff around immutability you may be tempted to return a new property descriptor from your decorators, without modifying the original descriptor. While well-intentioned, this may have an undesired effect, as it is possible to decorate the same class or class member several times.

If any decorators in a piece of code returned an entirely new descriptor without taking into consideration the descriptor parameter they receive, they’d effectively lose all the decoration that took place before the different descriptor was returned.

We should be careful to write decorators that take into account the supplied descriptor. Always create one that’s based on the original descriptor that’s provided as a parameter.

3.4.3 Use Case By Example: Attributes in C#

A long time ago, I was first getting acquainted with C# by way of an Ultima Online⁵ server emulator written in open source C# code—RunUO. RunUO was one of the most beautiful codebases I’ve ever worked with, and it was written in C# to boot.

They distributed the server software as an executable and a series of .cs files. The runuo executable would compile those .cs scripts at runtime and dynamically mix them into the application. The result was that you didn’t need the Visual Studio IDE (nor msbuild), or anything other than just enough programming knowledge to edit one of the “scripts” in those .cs files. All of the above made RunUO the perfect learning environment for the new developer.

RunUO relied heavily on reflection. RunUO’s developers made significant efforts to make it customizable by players who were not necessarily invested in programming, but were nevertheless interested in changing a few details of the game, such as how much damage a dragon’s fire breath inflicts or how often it shot fireballs. Great developer experience was a big part of their philosophy, and you could create a new kind of Dragon just by copying one of the monster files, changing it to inherit from the Dragon class, and overriding a few properties to change its color hue, its damage output, and so on.

Just as they made it easy to create new monsters—or “non-player characters” (NPC in gaming slang)--they also relied on reflection to provide functionality to in-game administrators. Administrators could run an in-game command and click on an item or a monster to visualize or change properties without ever leaving the game.

Figure 3-1. Modifying properties for a RunUO item in-game from the Ultima Online client

Not every property in a class is meant to be accessible in-game, though. Some properties are only meant for internal use, or not meant to be modified at runtime. RunUO had a CommandPropertyAttribute decorator,⁶ which defined that the property could be modified in-game and let you also specify the access level required to read and write that property. This decorator was used extensively throughout the RunUO codebase.⁷

The PlayerMobile class, which governed how a player’s character works, is a great place to look at these attributes. PlayerMobile has several properties that are accessible in-game⁸ to administrators and moderators. Here are a couple of getters and setters, but only the first one has the CommandProperty attribute—making that property accessible to Game Masters in-game.

[CommandProperty(AccessLevel.GameMaster)]
public int Profession
{
  get{ return m_Profession }
  set{ m_Profession = value }
}

public int StepsTaken
{
  get{ return m_StepsTaken }
  set{ m_StepsTaken = value }
}

One interesting difference between C# attributes and JavaScript decorators is that reflection in C# allows us to pull all custom attributes from an object using MemberInfo#getCustomAttributes. RunUO leverages that method to pull up information about each property that should be accessible in-game when displaying the dialog that lets an administrator view or modify an in-game object’s properties.

3.4.4 Marking Properties in JavaScript

In JavaScript, there’s no such thing—not in the existing proposal draft, at least—to get the custom attributes on a property. That said, JavaScript is a highly dynamic language, and creating this sort of “labels” wouldn’t be much of a hassle. Decorating a Dog with a “command property” wouldn’t be all that different from RunUO and C#.

class Dog {
  @commandProperty('game-master')
  name;
}

The commandProperty function would need to be a little more sophisticated than its C# counterpart. Given that there is no reflection around JavaScript decorators⁹, we could use a runtime-wide symbol to keep around an array of command properties for any given class.

function commandProperty(writeLevel, readLevel = writeLevel) {
  return ({ key, ...rest }) => ({
    key,
    ...rest,
    finisher(ctor) {
      const symbol = Symbol.for('commandProperties')
      const commandPropertyDescriptor = {
        key,
        readLevel,
        writeLevel
      }
      if (!ctor[symbol]) {
        ctor[symbol] = []
      }
      ctor[symbol].push(commandPropertyDescriptor)
    }
  })
}

A Dog class could have as many command properties as we deemed necessary, and each would be listed behind a symbol property. To find the command properties for any given class, all we’d have to do is use the following function, which retrieves a list of command properties from the symbol property, and offers a default value of []. We always return a copy of the original list to prevent consumers from accidentally making changes to it.

function getCommandProperties(ctor) {
  const symbol = Symbol.for('commandProperties')
  const properties = ctor[symbol] || []
  return [...properties]
}
getCommandProperties(Dog)
// <- [{ key: 'name', readLevel: 'game-master',
// writeLevel: 'game-master' }]

We could then iterate over known safe command properties and render a way of modifying those during runtime, through a simple UI. Instead of maintaining long lists of properties that can be modified, relying on some sort of heuristics bound to break from time to time, or using some sort of restrictive naming convention, decorators are the cleanliest way to implement a protocol where we mark properties as special for some particular use case.

In the following chapter we’ll look at more features coming in ES6 and how they can be used to iterate over any JavaScript objects, as well as how to master flow control using promises and generators.

4.1.1 Getting Started with Promises

As an example, let’s take a look at the new fetch API for the browser. This API is a simplification of XMLHttpRequest. It aims to be super simple to use for the most basic use cases: making a GET request against an HTTP resource. It provides an extensive API that caters to advanced use cases, but that’s not our focus for now. In its most basic incarnation, you can make a GET /items HTTP request using a piece of code like the following.

fetch('/items')

The fetch('/items') statement doesn’t seem all that exciting. It makes a “fire and forget” GET request against /items, meaning you ignore the response and whether the request succeeded. The fetch method returns a Promise. You can chain a callback using the .then method on that promise, and that callback will be executed once the /items resource finishes loading, receiving a response object parameter.

fetch('/items').then(response => {
  // do something
})

The following bit of code displays the promise-based API with which fetch is actually implemented in browsers. Calls to fetch return a Promise object. Much like with events, you can bind as many reactions as you’d like, using the .then and .catch methods.

const p = fetch('/items')
p.then(res => {
  // handle response
})
p.catch(err => {
  // handle error
})

Reactions passed to .then can be used to handle the fulfillment of a promise, which is accompanied by a fulfillment value; and reactions passed to .catch are executed with a rejection reason that can be used when handling rejections. You can also register a reaction to rejections in the second argument passed to .then. The previous piece of code could also be expressed as the following.

const p = fetch('/items')
p.then(
  res => {
    // handle response
  },
  err => {
    // handle error
  }
)

Another alternative is to omit the fulfillment reaction in .then(fulfillment, rejection), this being similar to the omission of a rejection reaction when calling .then. Using .then(null, rejection) is equivalent to .catch(rejection), as shown in the following snippet of code.

const p = fetch('/items')
p.then(res => {
  // handle response
})
p.then(null, err => {
  // handle error
})

When it comes to promises, chaining is a major source of confusion. In an event-based API, chaining is made possible by having the .on method attach the event listener and then returning the event emitter itself. Promises are different. The .then and .catch methods return a new promise every time. That’s important because chaining can have wildly different results depending on where you append a .then or a .catch call.

A promise is created by passing the Promise constructor a resolver that decides how and when the promise is settled, by calling either a resolve method that will settle the promise in fulfillment or a reject method that’d settle the promise as a rejection. Until the promise is settled by calling either function, it’ll be in a pending state and any reactions attached to it won’t be executed. The following snippet of code creates a promise from scratch where we’ll wait for a second before randomly settling the promise with a fulfillment or rejection result.

new Promise(function (resolve, reject) {
  setTimeout(function () {
    if (Math.random() > 0.5) {
      resolve('random success')
    } else {
      reject(new Error('random failure'))
    }
  }, 1000)
})

Promises can also be created using Promise.resolve and Promise.reject. These methods create promises that will immediately settle with a fulfillment value and a rejection reason, respectively.

Promise
  .resolve({ result: 123 })
  .then(data => console.log(data.result))
// <- 123

When a p promise is fulfilled, reactions registered with p.then are executed. When a p promise is rejected, reactions registered with p.catch are executed. Those reactions can, in turn, result in three different situations depending on whether they return a value, a Promise, a thenable, or throw an error. Thenables are objects considered promise-like that can be cast into a Promise using Promise.resolve as observed in Section 4.1.3: Creating a Promise from Scratch.

A reaction may return a value, which would cause the promise returned by .then to become fulfilled with that value. In this sense, promises can be chained to transform the fulfillment value of the previous promise over and over, as shown in the following snippet of code.

Promise
  .resolve(2)
  .then(x => x * 7)
  .then(x => x - 3)
  .then(x => console.log(x))
// <- 11

A reaction may return a promise. In contrast with the previous piece of code, the promise returned by the first .then call in the following snippet will be blocked until the one returned by its reaction is fulfilled, which will take two seconds to settle because of the setTimeout call.

Promise
  .resolve(2)
  .then(x => new Promise(function (resolve) {
    setTimeout(() => resolve(x * 1000), x * 1000)
  }))
  .then(x => console.log(x))
// <- 2000

A reaction may also throw an error, which would cause the promise returned by .then to become rejected and thus follow the .catch branch, using said error as the rejection reason. The following example shows how we attach a fulfillment reaction to the fetch operation. Once the fetch is fulfilled the reaction will throw an error and cause the rejection reaction attached to the promise returned by .then to be executed.

const p = fetch('/items')
  .then(res => { throw new Error('unexpectedly') })
  .catch(err => console.error(err))

Let’s take a step back and pace ourselves, walking over more examples in each particular use case.

4.1.2 Promise Continuation and Chaining

In the previous section we’ve established that you can chain any number of .then calls, each returning its own new promise, but how exactly does this work? What is a good mental model of promises, and what happens when an error is raised?

When an error happens in a promise resolver, you can catch that error using p.catch as shown next.

new Promise((resolve, reject) => reject(new Error('oops')))
  .catch(err => console.error(err))

A promise will settle as a rejection when the resolver calls reject, but also if an exception is thrown inside the resolver as well, as demonstrated by the next snippet.

new Promise((resolve, reject) => { throw new Error('oops') })
  .catch(err => console.error(err))

Errors that occur while executing a fulfillment or rejection reaction behave in the same way: they result in a promise being rejected, the one returned by the .then or .catch call that was passed the reaction where the error originated. It’s easier to explain this with code, such as the following piece.

Promise
  .resolve(2)
  .then(x => { throw new Error('failed') })
  .catch(err => console.error(err))

It might be easier to decompose that series of chained method calls into variables, as shown next. The following piece of code might help you visualize the fact that, if you attached the .catch reaction to p1, you wouldn’t be able to catch the error originated in the .then reaction. While p1 is fulfilled, p2—a different promise than p1, resulting from calling p1.then—is rejected due to the error being thrown. That error could be caught, instead, if we attached the rejection reaction to p2.

const p1 = Promise.resolve(2)
const p2 = p1.then(x => { throw new Error('failed') })
const p3 = p2.catch(err => console.error(err))

Here is another situation where it might help you to think of promises as a tree-like data structure. In Figure 4-2 it becomes clear that, given the error originates in the p2 node, we couldn’t notice it by attaching a rejection reaction to p1.

Figure 4-2. Understanding the tree structure of promises reveals that rejection reactions can only catch errors that arise in a given branch of promise-based code.

In order for the reaction to handle the rejection in p2, we’d have to attach the reaction to p2 instead, as shown in Figure 4-3.

Figure 4-3. By attaching a rejection handler on the branch where an error is produced, we’re able to handle the rejection.

We’ve established that the promise you attach your reactions onto is important, as it determines what errors it can capture and what errors it cannot. It’s also worth noting that as long as an error remains uncaught in a promise chain, a rejection handler will be able to capture it. In the following example we’ve introduced an intermediary .then call in between p2, where the error originated, and p4, where we attach the rejection reaction. When p2 settles with a rejection, p3 becomes settled with a rejection, as it depends on p2 directly. When p3 settles with a rejection, the rejection handler in p4 fires.

const p1 = Promise.resolve(2)
const p2 = p1.then(x => { throw new Error('failed') })
const p3 = p2.then(x => x * 2)
const p4 = p3.catch(err => console.error(err))

Typically, promises like p4 fulfill because the rejection handler in .catch doesn’t raise any errors. That means a fulfillment handler attached with p4.then would be executed afterwards. The following example shows how you could print a statement to the browser console by creating a p4 fulfillment handler that depends on p3 to settle successfully with fulfillment.

const p1 = Promise.resolve(2)
const p2 = p1.then(x => { throw new Error('failed') })
const p3 = p2.catch(err => console.error(err))
const p4 = p3.then(() => console.log('crisis averted'))

Similarly, if an error occurred in the p3 rejection handler, we could capture that one as well using .catch. The next piece of code shows how an exception being thrown in p3 could be captured using p3.catch just like with any other errors arising in previous examples.

const p1 = Promise.resolve(2)
const p2 = p1.then(x => { throw new Error('failed') })
const p3 = p2.catch(err => { throw new Error('oops') })
const p4 = p3.catch(err => console.error(err))

The following example prints err.message once instead of twice. That’s because no errors happened in the first .catch, so the rejection branch for that promise wasn’t executed.

fetch('/items')
  .then(res => res.a.prop.that.does.not.exist)
  .catch(err => console.error(err.message))
  .catch(err => console.error(err.message))
// <- 'Cannot read property "prop" of undefined'

In contrast, the next snippet will print err.message twice. It works by saving a reference to the promise returned by .then, and then tacking two .catch reactions onto it. The second .catch in the previous example was capturing errors produced in the promise returned from the first .catch, while in this case both rejection handlers branch off of p.

const p = fetch('/items').then(res =>
  res.a.prop.that.does.not.exist
)
p.catch(err => console.error(err.message))
p.catch(err => console.error(err.message))
// <- 'Cannot read property "prop" of undefined'
// <- 'Cannot read property "prop" of undefined'

We should observe, then, that promises can be chained arbitrarily. As we just saw, you can save a reference to any point in the promise chain and then append more promises on top of it. This is one of the fundamental points to understanding promises.

Let’s use the following snippet as a crutch to enumerate the sequence of events that arise from creating and chaining a few promises. Take a moment to inspect the following bit of code.

const p1 = fetch('/items')
const p2 = p1.then(res => res.a.prop.that.does.not.exist)
const p3 = p2.catch(err => {})
const p4 = p3.catch(err => console.error(err.message))

Here is an enumeration of what is going on as that piece of code is executed:

1. fetch returns a brand new p1 promise.

2. p1.then returns a brand new p2 promise, which will react if p1 is fulfilled.

3. p2.catch returns a brand new p3 promise, which will react if p2 is rejected.

4. p3.catch returns a brand new p4 promise, which will react if p3 is rejected.

5. When p1 is fulfilled, the p1.then reaction is executed.

6. Afterwards, p2 is rejected because of an error in the p1.then reaction.

7. Since p2 was rejected, p2.catch reactions are executed, and the p2.then branch is ignored.

8. The p3 promise from p2.catch is fulfilled, because it doesn’t produce an error or result in a rejected promise.

9. Because p3 was fulfilled, the p3.catch is never followed. The p3.then branch would’ve been used instead.

You should think of promises as a tree structure. This bears repetition: you should think of promises as a tree structure.¹ Let’s reinforce this concept with Figure 4-4.

Figure 4-4. Given the tree structure, we realize that p3 is fulfilled, as it doesn’t produce an exception nor is it rejected. For that reason, p4 can never follow the rejection branch, given its parent was fulfilled.

It all starts with a single promise, which we’ll next learn how to construct. Then you add branches with .then or .catch. You can tack as many .then or .catch calls as you want onto each branch, creating new branches and so on.

4.1.3 Creating a Promise from Scratch

We already know that promises can be created using a function such as fetch, Promise.resolve, Promise.reject, or the Promise constructor function. We’ve already used fetch extensively to create promises in previous examples. Let’s take a more nuanced look at the other three ways we can create a promise.