Ecma? ECMAScript? TC39?

What we think of as “JavaScript” is standardized as “ECMAScript” by Ecma International,¹ a standards organization responsible for multiple computing standards. The ECMAScript standard is ECMA-262. The people in charge of the standard are members of Ecma International Technical Committee 39 (“TC39”), charged with “Standardization of the general purpose, cross platform, vendor-neutral programming language ECMAScript. This includes the language syntax, semantics, and libraries and complementary technologies that support the language.”² They manage other standards as well, such as the JSON Syntax Specification (ECMA-404), and notably the ECMAScript Internationalization API Specification (ECMA-402).

In this book and in common usage, JavaScript is ECMAScript and vice versa. Sometimes, particularly during the decade of different groups doing different things, “JavaScript” was used to specifically mean the language Mozilla was developing (which had several features that either never made it into ECMAScript, or changed markedly before they did), but since Harmony that usage is increasingly outdated.

ES6? ES7? ES2015? ES2020?

Having all these various abbreviations can be confusing, not least because some have edition numbers but others have years. This section explains what they are and why there are two kinds of them.

Up through the 5th Edition, TC39 referred to versions of the specification via their edition number. The full title of the 5th Edition spec is:

• Standard ECMA-262
• 5th Edition / December 2009
• ECMAScript Language Specification

Since “ECMAScript 5th Edition” is a bit of a mouthful, saying “ES5” was the natural thing to do.

Starting with the 6th Edition in 2015, TC39 adopted a continual improvement process where the specification is a living editor's draft³ with annual snapshots. (More about that later in this chapter.) When they did that, they added the year to the language name:

• Standard ECMA-262
• 6th Edition / June 2015
• ECMAScript® 2015 Language Specification

So the ECMAScript 6th Edition standard (“ES6”) defines ECMAScript 2015, or “ES2015” for short. Prior to publication, “ES6” became a buzzword of its own and is still in common usage. (Unfortunately, it's often used inaccurately, referring not just to features from ES2015, but also to features that came afterward in ES2016, ES2017, and so on.)

That's why there are two styles, the style using the edition (ES6, ES7, …) and the style using the year (ES2015, ES2016, …). Which you use is up to you. ES6 is ES2015 (or sometimes, incorrectly, ES2015+), ES7 is ES2016, ES8 is ES2017, and so on through (as of this book's release) ES11, which is ES2020. You'll also see “ESnext” or “ES.next,” which are sometimes used to refer to upcoming changes.

In this book, I use what I see as the emerging consensus: the old style for ES5 and earlier, and the new style for ES2015 and later.

All of that said, although I will usually call out the specific edition where a feature was introduced, the fact that Array.prototype.includes is from ES2016 and Object.values is from ES2017 doesn't really matter very much. What matters more is what's actually supported in your target environments and whether you need to either refrain from using a specific feature, or transpile and/or polyfill it. (More on transpiling and polyfilling later in the “Using Today's Toys in Yesterday's Environments, and Tomorrow's Toys Today” section.)

JavaScript “Engines,” Browsers, and Others

In this book I'll use the term “JavaScript engine” to refer to the software component that runs JavaScript code. A JavaScript engine must know how to:

• Parse JavaScript,
• Either interpret it or compile it to machine code (or both), and
• Run the result within an environment that works as described by the specification.

JavaScript engines are also sometimes called virtual machines, or VMs for short.

One usual place you find JavaScript engines is in web browsers, of course:

• Google's Chrome browser uses their V8 engine (also used in Chromium, Opera, and Microsoft Edge v79 and later), except on iOS (more on that in a bit).
• Apple's Safari browser (for Mac OS and for iOS) uses their JavaScriptCore engine.
• Mozilla's Firefox uses their SpiderMonkey engine, except on iOS.
• Microsoft's Internet Explorer uses their JScript engine, which is increasingly out of date as it only gets security fixes.
• Microsoft Edge v44 and earlier (“Legacy Edge”) uses Microsoft's Chakra engine. In January 2020, Edge v79 was released, which is based on the Chromium project and uses the V8 engine, except on iOS. (The version number jumped from 44 to 79 to align with Chromium.) Chakra is still used in various products that use the Microsoft WebView control, such as Microsoft Office JavaScript add-ins, though it may be replaced at some stage. (WebView2, using Chromium Edge, is in developer preview as of early 2020.)

Chrome, Firefox, Edge, and other browsers running on Apple's iOS operating system for iPad and iPhone can't currently use their own JavaScript engines, because to compile and run JavaScript (rather than just interpreting it), they have to allocate executable memory, and only Apple's own iOS apps are allowed to do that, not ones from other vendors. So Chrome and Firefox (and others) have to use Apple's JavaScriptCore instead on iOS even though they use their own engine on desktop and Android. (At least, that's true for now; the V8 team added an “interpreter only” mode to V8 in 2019, which means Chrome and others using V8 could use that mode on iOS, since it doesn't have to use executable memory.) In this book, if I say something is “supported by Chrome” or “supported by Firefox,” I'm referring to the non-iOS versions using V8 or SpiderMonkey, respectively.

JavaScript engines are also used in desktop applications (Electron,⁴ React Native,⁵ and others), web servers and other kinds of servers (often using Node.js⁶), non-web applications, embedded apps—just about everywhere.

Who's in Charge

You learned earlier that Ecma International's Technical Committee 39 (TC39) is in charge of creating and releasing updated specifications for the ECMAScript standard. The committee is made up of JavaScript developers, framework authors, large website authors/maintainers, programming language researchers, representatives from all the major JavaScript engines, influential JavaScripters, and other stakeholders in JavaScript's success and future. They have regular meetings, historically six per year for three days. To participate in meetings as a member, your organization can join Ecma.⁹ TC39 navigates the difficult waters of developers' desires, implementation complexity, security concerns, backward compatibility, and many other design inputs to bring new and useful features to the JavaScript community.

To ensure that the committee works as part of the community rather than separate from it, TC39 maintains the ecma262 GitHub repository¹⁰ with the up-to-date specification (browsable at https://tc39.es/ecma262/) and a proposals repository¹¹ for proposals going through the TC39 process described in the next section. Some members are also active on the TC39 Discourse group.¹² Notes of the TC39 meetings and associated materials (slides, etc.) are posted to https://github.com/tc39/notes.

You can learn more about TC39, and how to get involved, at https://tc39.es/. You can also learn more about how TC39 works at https://github.com/tc39/how-we-work.

The Process

TC39 adopted a well-defined process in November 2013 and first published it in January 2014. The process has multiple stages that TC39 moves proposals through (Stage 0 through Stage 4), with clear expectations at each stage, and clear criteria for moving from one stage to the next. Once a proposal meets the criteria to move to the next stage, the committee decides by consensus whether to move it forward.

It's worth reading the process document itself,¹³ but in brief, the stages are:

• Stage 0 – Strawperson: Someone's had an idea they think is worth considering so they've thought about it, written it up a bit, and put it forward. (This stage almost isn't a stage, and the term has been applied to different things at different times.) If the person putting it forward isn't a TC39 member, they need to register as a non-member contributor¹⁴ (which anyone can do). Some Stage 0 proposals end up being listed in the TC39 proposals repository, but others don't; typically it's just ones that have gained a potential champion who is a committee member. If a Stage 0 proposal gains enough interest, a TC39 member may get it added to the agenda for a TC39 meeting to be discussed and considered for Stage 1.
• Stage 1 – Proposal: Once a proposal has been put to the committee and there's consensus to investigate it further, the committee moves it to Stage 1 with a champion to guide it through the process. If there isn't already a GitHub repo for it, the originator or champion or another interested party creates one. Then members of the community (whether on the committee or not) discuss it, develop it further, research similar technology in other languages or environments, refine the scope, figure out the general form of a solution, and generally flesh out the idea. As a result of this work, it might turn out that the benefits aren't worth the costs, or it could be that the idea needs to be broken up and added to other proposals, etc. But if the proposal has legs, the people involved (who may have changed over time) will put together some initial draft specification language, API, and semantics and put it forward to TC39 to be considered for Stage 2.
• Stage 2 – Draft: When it's ready, a Stage 1 proposal can be presented at a TC39 meeting to be considered for Stage 2. This means seeking consensus that the proposal should go ahead, with the expectation it will likely go through the entire process. Stage 2 is the stage where the community refines the precise syntax, semantics, API, and so on and describes the solution in detail using formal specification language. Often, polyfills and/or Babel plugins get created at this stage to enable experimentation with real use. Depending on its scope, a proposal may stay at Stage 2 for some time as the details are worked out.
• Stage 3 – Candidate: Once the team has matured a proposal to a final draft form and created formal specification language for it, the champion can put it forward for Stage 3. This means seeking consensus that the proposal is ready to be implemented in JavaScript engines. At Stage 3, the proposal itself is nearly stable. Changes at this point are expected to be limited to implementation-driven feedback, such as corner cases discovered during implementation, web-compatibility issues, or difficulty of implementation.
• Stage 4 – Finished: At this point, the feature is complete and is ready to be added to the editor's draft at https://tc39.es/ecma262/. To reach this final stage, the feature must have acceptance tests in TC39's test262 test suite;¹⁵ at least two distinct compatible implementations that pass the tests (for instance, shipping in V8 in Chrome Canary and SpiderMonkey in Firefox Nightly, or SpiderMonkey in Firefox and JavaScriptCore in Safari Tech Preview, etc.). Once those criteria are met, the final step to reach Stage 4 is for the team working on the feature to send a pull request to the ecma262 repository to incorporate the specification changes into the editor's draft, and the ECMAScript editor group to accept that PR.

That's the process proposals go through to become part of JavaScript. But not every change is a proposal. Smaller changes can be made through consensus at TC39 meetings based on a pull request to the specification. For instance, the output of Date.prototype.toString changed between ES2017 and ES2018 (see Chapter 17) as the result of consensus on a pull request, not a staged proposal. Often, these are editorial changes, or changes reflecting the reality of what JavaScript engines already do but which isn't in the specification, or changes to what the specification says to do that have been agreed on because TC39 believes they're both desirable and “web compatible” (won't break a large amount of existing code), such as the change in ES2019 making Array.prototype.sort a stable sort (see Chapter 11). If you want to know what changes are being considered or made in this way, watch the “needs consensus” label in the https://github.com/tc39/ecma262 repo (and similarly the https://github.com/tc39/ecma402 repo for ECMA-402 changes). To find ones that have been completed, look in the “has consensus,” “editorial change,” and/or “normative change” labels. At some point there may be a more formal process for these “needs consensus” changes, but for now this is how you watch for them.

Getting Involved

If you see a proposal that interests you and you want to get involved, when should you do that? What should that involvement look like?

One key thing is: get involved early. Once a proposal has reached Stage 3, only critical changes based on implementation experience are typically considered. The best times to get involved are at Stages 0, 1, and 2. That's when you can provide insight based on your experience, help define semantics, try out what's being proposed using tools like Babel (which you'll learn about in a later section), etc. It's not that you can't find a useful role in a Stage 3 proposal (there are sometimes tasks to be done in terms of firming up specification text or helping write developer documentation), just be aware that suggesting changes at Stage 3 usually isn't useful unless you're one of the people implementing it in a JavaScript engine and you run into a problem.

So: you've found a proposal you want to get involved in; what now? It's up to you, but here are some suggestions:

• Do your research. Read the proposal's explainer (the README.md that's linked from the TC39 list of proposals) and other documents closely and carefully. If they refer to prior art (such as a similar feature in another language), it's useful to read up on that prior art. If there's initial specification text, read it. (This guide may be helpful there: https://timothygu.me/es-howto/.) You want to be sure that the input you provide is well-informed.
• Try the feature out! Even if you can't use it yet, you can write speculative code (code you can't run, but can think about) to consider how well the proposal is solving the problem it sets out to solve. If there's a Babel plugin for it, try writing and running code. See how the feature works for you and provide feedback on it.
• Look for ways you can help. Aside from suggestions and feedback, there are lots of ways to help with a proposal. For instance, you can look for issues where a consensus has been reached about what to do, but no one's had the time to do it (researching prior art, updating the explainer, updating spec text). You could do those updates, if it's something you're comfortable doing. You can coordinate with the proposal authors by discussing contributions in GitHub issues.

When getting involved, remember to treat everyone with respect and to be friendly, patient, inclusive, and considerate. Be careful with the words you choose. You're more likely to have influence by treating people well and demonstrating a collaborative spirit than by seeming cross, dismissive, or obstructive. Note that TC39's meetings and online spaces used to develop proposals are governed by a Code of Conduct.¹⁶ Please refer improper conduct to TC39's Code of Conduct committee (see the linked document).

Transpiling an Example with Babel

In this section, we'll take a quick look at using Babel to transpile code using an ES2015 feature, called an arrow function, into ES5-compatible code that works on IE11. But this is just an example; you could just as easily use Babel to transform code using a Stage 3 feature not yet present in any shipping JavaScript engine into ES2020-compatible code. Babel also supports some transforms that aren't in the process at all, such as JSX²⁵ (used in some JavaScript frameworks, notably React²⁶). The truly adventurous can write their own transform plugins just for use on their projects!

To install Babel, you'll want Node.js and npm (Node Package Manager). If you don't already have those installed on your system, either:

• Go to https://nodejs.org/ and use the appropriate installer/package for your system to install it; or
• Use the Node Version Manager, which provides a handy way to install Node versions and to switch between them: https://github.com/nvm-sh/nvm

npm comes bundled with Node.js, so you don't have to install it separately.

Once you have them installed:

1. Create a directory for this example (for instance, example in your home directory).
2. Open a command prompt/terminal window and change to the directory you just created.
3. Use npm to create a package.json file: Type
   • npm init

   and press Enter. npm will ask a series of questions; answer the questions as you like (or just press Enter in response to all of them). When done, it will write out package.json to your example directory.

4. Next, install Babel. (The following steps are from going to https://babeljs.io/docs/setup/#installation and then clicking the CLI button; you might want to check there for updates.) Type
   • npm install --save-dev @babel/core @babel/cli

   and press Enter. npm will download and install Babel, its command-line interface, and all of its dependencies into your example project. (You may get a warning related to a module called fsevents and/or some deprecation warnings; that's okay.)

5. At this point, you could start using Babel by calling it directly, but let's make it easier by adding an npm script entry to package.json. Open package.json in your favorite editor. If there isn't a top-level scripts entry, create one (but current versions of npm will have included one with a test script that shows an error). Within the scripts entry, add this setting:

   "build": "babel src -d lib"

   Now your package.json should look something like Listing 1-1. (Yours may still have a test entry in scripts; that's fine. It also may have a different license, I always change the default to MIT.) Make sure to save the file.

6. Babel is highly modular. Although we've installed it, we haven't told it to do anything yet. For this example, we'll use one of its presets to tell it to transform ES2015 code to ES5 code, by installing and then configuring the preset. To install the preset, type
   • npm install --save-dev babel-preset-env

   and press Enter. In the next step we'll configure it.

7. Now we need to create a configuration file for Babel, .babelrc (note the leading dot). Create the file with these contents (or use the one from the chapter downloads):

   {
     "presets": [
       [
         "env",
         {
           "targets": {
             "ie": "11"
           }
         }
       ]
     ]
   }

That configuration tells Babel to use its env preset, which the Babel documentation describes as “… a smart preset that allows you to use the latest JavaScript without needing to micromanage which syntax transforms … are needed by your target environment(s).” In this configuration, setting the target "ie": "11" tells the env preset that you're targeting IE11, which is appropriate for the following example. For your real use, you'll want to look at the documentation for the env preset²⁷ and/or other presets or plugins you may want to use instead.

That's it for the Babel setup for this example. Now let's create some code for it to transpile. Create a subdirectory of your example directory called src, and create a file in it called index.js with the contents of Listing 1-2. (At the end of the process, I'll show you a list of what files should be where, so don't worry too much if you're slightly unsure; just create the file and you can move it if it ends up in the wrong place.)

The code in Listing 1-2 uses just one ES2015+ feature: an arrow function, the entry => this.rex.test(entry) within the call to some, which I've highlighted in the code. (Yes, that's really a function.) You'll learn about arrow functions in Chapter 3. The brief, incomplete version is that they offer a concise way to define a function (as you can see) and that they close over this just like closing over a variable (rather than having this set by how they're called). When obj.checkArray(…) is called, this within the call refers to obj even within the some callback, so this.rex refers to the rex property on obj. That wouldn't be true if the callback were a traditional function.

At this point, your example directory should have these contents:

example/
+−− node_modules/
|   +−− (various directories and files)
+−− src/
|   +−− index.js
+−− .babelrc
+−− package.json
+−− package-lock.json

You're ready to transpile! Type

• npm run build

and press Enter. Babel will do its thing, create the lib output directory for you, and write the ES5 version of index.js to it. The result in lib/index.js will look something like Listing 1-3.

If you compare src/index.js (Listing 1-2) to lib/index.js (Listing 1-3), you'll see only a couple of changes (other than whitespace). First, Babel added a "use strict"; directive to the top of the transpiled file (recall that strict mode is a feature added in ES5 that modifies the behavior of a couple of things that were problematic for various reasons). This is Babel's default, but it can be turned off if you have code that relies on loose mode.

The interesting thing, though, is how it rewrote the arrow function. It created a variable within checkArray called _this, set its value to this, and then used a traditional function as the some callback; within the function, it used _this instead of this. That fits with my earlier description of arrow functions—that they close over this just like closing over a variable. Babel just made that happen in a way an ES5 environment can understand.

This is obviously just a very small example, but it illustrates the point and gives you a taste of one tool you might use if you need to do this in your projects. Babel can be integrated into your build system, whether you use Gulp,²⁸ Grunt,²⁹ Webpack,³⁰ Browserify,³¹ Rollup,³² or just about any other; the installation page at https://babeljs.io/docs/setup/#installation has instructions for all the major ones.

const Basics

As you know, const creates a constant:

const answer = 42;
console.log(answer); // 42

It's exactly like creating a variable with let, with all the same scope rules, the Temporal Dead Zone, etc., except that you cannot assign a new value to a constant, whereas of course you can assign a new value to a variable.

What do you think happens when you try to assign a new value to a constant? What would be the most useful thing?

Right—you get an error:

const answer = 42;
console.log(answer); // 42
answer = 67;         // TypeError: invalid assignment to const 'answer'

At first glance, it may seem that you'd only want to use const for things like avoiding having “magic numbers” in code, such as a standard delay you might use in code before showing a busy message when you're doing something the user initiated:

const BUSY_DISPLAY_DELAY = 300; // milliseconds

But const is useful for far more than that. Although we frequently do change the values of variables, we just as frequently don't change their values; we just use them to hold unchanging information.

Let's look at a real-world example: Listing 2-2 has a simple loop for appending text to divs depending on whether they have a particular class. It seems to make fairly straightforward use of variables.

There are four variables in that code. If you look closely, you'll see that one of them isn't like the other three. Can you spot what's different?

One of them has a value that never changes: list. The others ( n, element, and text) are actually variables, but list is a constant.

We'll come back to that code in a later section after covering a couple more aspects of const, but in the back of your mind in the meantime, consider how you might apply let and const to that code (without removing any of the identifiers) based on what you know so far.

Objects Referenced by a const Are Still Mutable

It's important to remember what it is that can't be changed with a constant: the value of the constant. If that value is an object reference, it doesn't in any way mean that the object is immutable (that its state can't be changed); the object is still mutable (it can still be changed). It just means you can't make the constant point to a different object (because that would change the value of the constant). Let's explore that:

const obj = {
    value: "before"
};
console.log(obj.value);       // "before"

So far, you have a reference to an object in a constant. In memory, you have something like Figure 2-1.

The obj constant doesn't directly contain the object, it contains a reference to the object (shown in Figure 2-1 as “Ref55462” but of course that's just conceptual; you never see the real value of object references). So if you change the object's state:

obj.value = "after";
console.log(obj.value);       // "after"

you're not changing the value of the obj constant; it's still a reference to the same object (“Ref55462”). It's just that the object's state has been updated so it stores a different value for its value property; see Figure 2-2.

What const does is prevent you changing the actual value of obj, either to make it refer to a different object, or to set it to null, or something else entirely:

obj = {}; // TypeError: invalid assignment to const 'obj'

Here's a practical example, a function that adds a paragraph with the given HTML to a parent element:

function addParagraph(parent, html) {
    const p = document.createElement("p");
    p.innerHTML = html;
    parent.appendChild(p);    return p;
}

Since the code only changes the state of the paragraph (by setting its innerHTML property), not which paragraph p refers to, you can make p constant.

The “Closures in Loops” Problem

You're probably familiar with the “closures in loops” problem, though perhaps not by that name; run the code in Listing 2-3 to see the problem in action.

(Ignore any features setTimeout may have to help us with this problem; it's just a placeholder for any asynchronous operation.)

You might expect that code to output 1, then 2, then 3, but instead it outputs 4, 4, 4. The reason is that each timer doesn't run its callback until after the loop finishes. By the time they call the callbacks, counter's value is 4, and because it's declared with var, counter is defined throughout the closuresInLoopsProblem function. All three timer callbacks close over the same counter variable, so they all see the value 4.

In ES5 and earlier, the usual way to solve that is by introducing another function and passing counter into it as an argument, then using that argument instead of counter in the console.log. Coders frequently do it with an inline anonymous function they call immediately, such as in Listing 2-4.

When you run that, it outputs the expected 1, 2, 3, because the timer functions are using value, not counter, and each call to the anonymous wrapper function gets its own value parameter for the timer function to close over. Nothing changes any of those value parameters, so the callbacks log the expected values (1, 2, and 3).

Thanks to ES2015's let, though, you can solve it much more simply: by just changing var to let. Run the code in Listing 2-5.

Running that also gives you the expected 1, 2, 3. One small change, one massive impact. But how does it work? Surely the functions still close over counter? How can they all see different values?

Just like the calls to the anonymous function created multiple value parameters for the timer functions to close over, the loop above in Listing 2-5 creates multiple counter variables for the timer functions created in the loop to close over, one for each loop iteration. So each iteration gets its own counter variable.

To understand how, we need to look more closely at how variables (and constants) work in JavaScript. This will also help you with some later chapters.

Bindings: How Variables, Constants, and Other Identifiers Work

Earlier in this chapter you learned that const's constants work just like let's variables in terms of scope, the kinds of values they can hold, etc. There's a good reason for that. Under the covers, variables and constants are the same thing, which the specification calls bindings (specifically in this case, identifier bindings): a link between an identifier and the storage for its value. When you create a variable, for instance with

let x = 42;

you're creating a binding for the identifier named x and storing the value 42 in that binding's storage slot. In that case, it's a mutable binding (a binding whose value can change). When you create a constant, you create an immutable binding (a binding whose value cannot change).

Identifier bindings have names and values. Sound like anything you know? They're a bit like object properties aren't they? And like object properties, they're in a container, which I'm going to call an environment object.¹ For instance, the environment object for the context where this code runs:

let a = 1;
const b = 2;

would look something like Figure 2-3.

To handle nested scopes, environment objects are linked together in a chain: each has a link to the one “outside” it. If code needs an identifier that isn't in the current environment object, it follows the link to the outer environment object to find it (repeating as necessary, up through the global environment—which is how global variables work).

The outer environment is set in various ways. For instance, when code execution enters a block with block-scoped identifiers in it, the environment object for the block gets the environment object for the code containing the block as its outer environment. When a function is called, the environment object for the call gets the environment where the function was created (which is saved on the function; the spec calls it the [[Environment]] internal slot of the function) as its outer environment. That's how closures work.

For instance, consider this code (assume it’s at global scope):

let x = 1;
function example() {
    const y = 2;
    return function() {
        let z = 3;
        console.log(z, y, x);
    };
}
const f = example();
f();

Within the f() call, when code execution gets to the console.log line, the environment object chain looks something like Figure 2-4 (overleaf).

Let's follow that through:

• The JavaScript engine creates the global environment ( EnvObject1) and adds the bindings x, f, and example to it.
• It creates the example function, setting example's saved environment link to the current environment (the global one, EnvObject1), and setting the example binding's value to the function.
• It runs the let x = 1; line, setting x to 1.
• It runs the const f = example(); line:
  • It creates a new environment object for the call ( EnvObject2), setting its outer environment to example's saved environment ( EnvObject1).
  • It creates a binding called y in that environment object.
  • It runs the const y = 2; line, setting y to 2.
  • It creates the function, setting the current environment ( EnvObject2, the one for the call to example) as its saved environment.
  • It returns the function from the call.
  • It assigns the function to f.
• Finally, the engine runs the f(); line, calling the function f refers to:
  • It creates a new environment object for the call ( EnvObject3), setting its outer environment to the function's saved environment ( EnvObject2, the one from the call to example earlier), and creating the z binding on it.
  • It sets z to 3.
  • It runs the console.log line.

In the console.log line, the engine finds z in the current environment, but has to go to the outer environment (the one for the call to example)to find y, and has to go two levels out to find x.

How does all this help us understand closuresInLoopsWithLet? Let's look at that function again; see Listing 2-6.

When executing the for loop, the JavaScript engine creates a new environment object for each loop iteration, each with its own, separate counter variable, so each timer callback closes over a different counter variable. Here's what the JavaScript engine does with that loop:

1. It creates an environment object for the call; let's call it CallEnvObject.
2. It sets CallEnvObject's outer environment reference to the saved environment on the closuresInLoopsWithLet function (the one where it was created; in this case, the global environment).
3. It begins processing the for by remembering the list of variables declared with let in the initialization part of the for; in this case, there's just one, counter, though you could have more.
4. It creates a new environment object for the initialization part of the loop, using CallEnvObject as its outer environment, and creates a binding on it for counter with the value 1.
5. It creates a new environment object ( LoopEnvObject1) for the first iteration, using CallEnvObject as its outer environment object.
6. Referring to its list from Step 3, it creates a binding for counter on LoopEnvObject1, setting its value to 1 (the value from the initialization environment object).
7. It sets LoopEnvObject1 as the current environment object.
8. Because the test counter <= 3 is true, it executes the body of the for by creating the first timer function (let's call it timerFunction1), giving it a reference to LoopEnvObject1 as its saved environment object.
9. It calls setTimeout passing a reference to timerFunction1 into it.

At this point, you have something like Figure 2-5 in memory.

Now the JavaScript engine is ready for the next loop iteration:

10. It creates a new environment object ( LoopEnvObject2) using CallEnvObject as its outer environment.
11. Using its list of bindings from Step 3, it creates a binding for counter on LoopEnvObject2 and sets its value to the current value of counter on LoopEnvObject1 (1, in this case).
12. It sets LoopEnvObject2 as the current environment object.
13. It does the “increment” part of the for loop: ++counter. The counter it increments is the one in the current environment object, LoopEnvObject2. Since its value is 1, it becomes 2.
14. It continues with the for loop: since the condition is true, it executes the loop body by creating the second timer function ( timerFunction2), giving it a reference to LoopEnvObject2 so it closes over the information in it.
15. It calls setTimeout passing in a reference to timerFunction2.

As you can see, the two timer functions close over different environment objects with different copies of counter. The first one still has counter = 1; the second one has counter = 2. At this point, you have something like Figure 2-6 in memory.

The whole thing happens for the third and last loop iteration and you end up with something like Figure 2-7 (see page opposite) in memory.

When the timer functions are called by the timers, since they each use a separate environment object, each with its own copy of counter, you see 1, 2, 3 instead of the 4, 4, 4 you saw with var where all were sharing the same environment object and variable.

In short, the mechanics of block scope in the loop did exactly what our ES5 solution's anonymous function did: gave each timer function a different environment object to close over with its own copy of the binding ( counter in the let solution, value in the ES5 solution). But it did it more efficiently, without requiring a separate function and function call.

Sometimes, of course, you want the old behavior. In that case, just declare the variable before the loop (which is, of course, what var did).

The only part of the behavior you've just learned about that's specific to for loops is the part where it keeps track of what let variables were created in the initializer part of the for and copies the value of those bindings from one environment object to the next. But the fact a block gets its own environment object isn't at all limited to for loops, and among other things that means while and do-while loops also benefit from blocks getting their own environment objects. Let's look at how.

while and do-while Loops

while and do-while also benefit from the fact blocks get their own environment objects. Since they don't have for's initialization expression, they don't do the thing where they copy forward the values of the bindings declared there, but the block associated with each loop iteration still gets its own environment. Let's see that in action. Run Listing 2-7.

When you run closuresInWhileLoops, the output in the console is:

inside = 1, outside = 4
inside = 2, outside = 4
inside = 3, outside = 4

All of the timer functions close over a single outside variable (because it was declared outside the loop), but they each close over their own inside variable. See Figure 2-8.

Performance Implications

Thinking about how block scope in loops works, you might be thinking: “Wait, if I use block variables in the loop and it has to create a new environment object to hold them and set up a chain, and (for for loops) copy the iteration binding value from one to the next, won't that slow down my loops?”

There are two answers to that:

1. You probably don't care. Remember that premature optimization is just that: premature. Worry about it if and when you have a real performance problem you're solving.
2. Yes and no. It is definitely more overhead if the JavaScript engine hasn't optimized the difference away, and there are times (including our closures in loops example) where it can't optimize the difference away. Other times, if we're not creating closures or the engine can determine that the closures don't use the per-loop-iteration variables, it may well be able to optimize the difference away. Modern engines do a lot of optimization. When ES2015's let was newish, Chrome's V8 engine ran for loops markedly slower if you used let for the loop variable than if you used var. That speed difference disappeared (for cases where closures weren't being created and such) as V8's engineers found ways to optimize it.

If you run into an actual problem with a loop, and it's not important that you have separate copies of the variables, just move them into the enclosing scope:

let n;
for (n = 0; n < aReallyReallyBigNumber; ++n) {
    // …
}

or if you don't want it in that scope, wrap the entire loop in an anonymous block and declare the variable in that block:

function wrappingInAnonymousBlock() {
    // …some unrelated code…
 
    // Now we've identified a performance/memory problem with the per-iteration
    // initialization of 'n', so we use an anonymous block to have just one 'n'
    {
        let n;
        for (n = 0; n < aReallyReallyBigNumber; ++n) {
            // …
        }
    }
 
    // …more unrelated code…
}
wrappingInAnonymousBlock();

const in Loop Blocks

In the earlier section on const, you saw a simple div update loop (repeated in Listing 2-8) where one of the variables ( list) actually never changed, and I asked you to think about how you'd apply let and const to the code (without removing any identifiers).

Did you come up with something like Listing 2-9?

At the time, you may not have thought to move element and text into the for loop's block, or if you did you may have left them as let rather than const declarations. But their values within the block never change, and of course each block gets its own copy of them, so they're constants within its scope and we can mark our intent just to use them, not modify them, by declaring them const.

You don't have to declare something const just because you don't change it. Whether you do is a matter of style and something your team should discuss and come to agreement on (do use const, don't use const, or leave it up to individual style). There are pragmatic benefits to using it during development (you get an early error if you try to change something a teammate declared const; you then either purposefully change the declaration or don't change the value of that constant), but your team may be using full test suites that will also find the error (albeit somewhat later).

const in for-in Loops

In addition to the usual for loop with the four parts (initialization, test, increment, body), JavaScript has other types of for loop: for-in, for-of, and for-await-of. (You’ll learn about for-of in Chapter 6; for-await-of in Chapter 9.) Let's take a quick look at a typical for-in:

var obj = {a: 1, b: 2};
for (var key in obj) {
    console.log(key + ": " + obj[key]);
}

If you were going to write that in ES2015+, would you use let or const for key?

You can use either. for-in loops with lexical declarations get a separate environment object for each loop iteration just like while does. Since the code in the loop body doesn't change key, it can be const if you like:

const obj = {a: 1, b: 2};
for (const key in obj) {
    console.log(key + ": " + obj[key]);
}

Use const or let Instead of var

Old habit: Using var.

New habit: Use const or let instead. The only remaining use cases for var are legacy code, for instance having a top-level

var MyApp = MyApp || {};

in several scripts that may be loaded on a page and all write to different parts of the MyApp object, and doing that is superseded by modules (see Chapter 13).

If you adopt const for “variables” you don't intend to change, you'll probably find that you use const much more than you originally thought you would, especially since with object references it doesn't mean you can't change the state of the object, it just means you can't change what object the constant refers to. If you're writing object-heavy code (which is almost inevitable with JavaScript), it's surprising how few actual variables you end up with.

Keep Variables Narrowly Scoped

Old habit: Listing vars at the top of the function, since that's where var was hoisted to anyway.

New habit: Use let and const in the narrowest appropriate scope, where reasonable. This improves the maintainability of the code.

Use Block Scope Instead of Inline Anonymous Functions

Old habit: Using inline anonymous functions to solve the closures-with-loops problem:

for (var n = 0; n < 3; ++n) {
    (function(value) {
        setTimeout(function() {
            console.log(value);
        }, 10);
    })(n);
}

New habit: Use block scope instead:

for (let n = 0; n < 3; ++n) {
    setTimeout(function() {
        console.log(n);
    }, 10);
}

Much cleaner and easier to read.

That said, don't replace perfectly good named, reusable functions with block scope without good reason:

// If it's already like this, with a reusable named function, no need
// to move the function code into the loop
function delayedLog(msg, delay) {
    setTimeout(function() {
        console.log(msg);
    }, delay);
}
// …later…
for (let n = 0; n < 3; ++n) {
    delayedLog(n, 10);
}

Block scope isn't a substitute for rightsizing functions, but it is a useful tool for eliminating confusing inline anonymous ones.

If you use scoping functions at global scope to avoid creating global variables, you can even replace those with a block (or a module, as you’ll learn in Chapter 13). Blocks don't have to be attached to a flow-control statement like if or for; they can be free-standing. So your scoping function can just be a scoping block:

{                         // Scoping block
    let answer = 42;      // 'answer' is local to the block, not global
    console.log(answer);
}

Arrow Function Syntax

Arrow functions come in two forms: ones with a concise body (often called concise arrow functions) and ones with a standard function body (I call them verbose arrow functions, though they're still not as verbose as traditional functions). We'll look at the concise form first.

Suppose you want to filter an array, keeping only the entries whose value is less than 30. You'd probably do it by using Array.prototype.filter and passing in a callback function. In ES5, that would look like this:

var array = [42, 67, 3, 23, 14];
var filtered = array.filter(function(entry) {
    return entry < 30;
});
console.log(filtered); // [3, 23, 14]

This is a common use case for callbacks: a callback that needs to do something simple and return a value. Arrow functions provide a very concise way to do it:

const array = [42, 67, 3, 23, 14];
const filtered = array.filter(entry => entry < 30);
console.log(filtered); // [3, 23, 14]

When you compare it to the traditional function you're used to, it almost doesn't look like a function at all! Don't worry, you'll soon get used to it.

As you can see, the concise form of an arrow function is literally just the name of the parameter(s) it accepts, then an arrow ( =>) to tell the parser this is an arrow function, and then an expression defining the value it returns. That's it. No function keyword, no curly braces to define a function body, no return keyword; just the parameters, the arrow, and the body expression.

When you want an arrow function to accept multiple parameters, you need to wrap its parameter list in parentheses to make it clear that they're all parameters for the arrow function. For instance, if you wanted to sort the array rather than filtering it, you'd do this:

const array = [42, 67, 3, 23, 14];
array.sort((a, b) => a - b);
console.log(array); // [3, 14, 23, 42, 67]

Notice the parentheses around the parameters. Why do you think the syntax had to require them?

Consider how it would look if they weren’t there:

array.sort(a, b => a - b);

See the problem? Right! It looks like we're passing two arguments to the sort method: a variable called a, and the arrow function b => a - b. So the parentheses are necessary if you have multiple parameters. (You can always include them, even if there's only one parameter, if you like to be consistent.)

You also use parentheses when you don't need to accept any parameters, such as in a timer callback—just leave them empty:

setTimeout(() => console.log("timer fired"), 200);

Although concise arrow functions are frequently written without line breaks, that's not at all a requirement of the concise syntax; if you had a complex calculation to do in the array.sort callback, you could put it on its own line:

const array = [42, 67, 3, 23, 14];
array.sort((a, b) =>
    a % 2 ? b % 2 ? a - b : -1 : b % 2 ? 1 : a - b
);
console.log(array); // [3, 23, 67, 14, 42]

That code sorts the array in two groups: first the odd numbers and then the even ones. The body of the function is still a single (complicated) expression, which is important for the concise arrow form.

But what if your arrow function needs to have multiple statements rather than just a single expression? Maybe you think the sort call would be clearer if you broke up that complicated expression (I certainly think it would be). For that, you can use the function body form (or as I call it, verbose form) by providing a function body using curly braces after the arrow:

const array = [42, 67, 3, 23, 14];
array.sort((a, b) => {
    const aIsOdd = a % 2;
    const bIsOdd = b % 2;
    if (aIsOdd) {
        return bIsOdd ? a - b : -1;
    }
    return bIsOdd ? 1 : a - b;
});
console.log(array); // [3, 23, 67, 14, 42]

That callback does exactly what the earlier one did, using multiple simple statements rather than a single complex expression.

Two things to notice about the verbose form:

• There's an opening curly brace immediately after the arrow. That's what tells the parser that you're using the verbose form, where the function body is inside curly braces just like with traditional functions.
• You use return to return a value, just like with a traditional function. If you didn't use return, then just like a traditional function, the arrow function wouldn't explicitly provide a return value and calling it would result in the value undefined.

Just as a concise arrow function doesn't have to be on one line, a verbose one doesn't have to be on multiple lines. As is usually the case, where you do line breaks is up to you.

There's one “gotcha” to be aware of with the concise form of arrow functions: a concise arrow function returning an object created with an object literal.

Suppose you have an array of strings and you want to convert it into an array of objects using the string as their name property. That sounds like a job for Array's map method and a concise arrow function:

const a = ["Joe", "Mohammed", "MarÍa"];
const b = a.map(name => {name: name});        // Doesn't work
console.log(b);

But when you try to run that, you get an array with a bunch of undefineds in it instead of objects. (Or depending on the object you create, a syntax error.) What happened?

The issue is that the opening curly brace tells the JavaScript parser that you're using the verbose form, not the concise form, so it uses that brace to start the body and then uses the contents ( name: name) as the body of the verbose arrow function, like this traditional function:

const a = ["Joe", "Mohammed", "MarÍa"];
const b = a.map(function(name) {              // Doesn't work
    name: name
});
console.log(b);

Since the function doesn't return anything (because the parser thinks you're using the verbose form), the result of calling it is the value undefined, and you end up with an array filled with undefined. The body of the function isn't a syntax error (in this example) because it looks like a label (you remember labels, the things you can use with nested loops to break the outer loop) followed by a freestanding reference to a variable. That's valid syntax, although it doesn't do anything.

The answer is to wrap the object literal in parentheses so that the parser doesn't see a curly brace just after the arrow, and knows you're using the concise form:

const a = ["Joe", "Mohammed", "MarÍa"];
const b = a.map(name => ({name: name}));        // Works
console.log(b);

Or, of course, use the verbose form and return. Whatever seems clearest to you when writing it.

Brief tangent: the object literal in that call to map could be even shorter thanks to shorthand properties, which you'll learn about in Chapter 5.

Arrow Functions and Lexical this

So far, you've seen that arrow functions can make your code more concise. That's useful just on its own, but it's not their main trick. Their main trick is that unlike traditional functions, they don't have their own version of this. Instead, they close over the this of the context where they're created, just like closing over a variable.

Why is that useful? Let's take a familiar problem: you're writing code in an object method, and you want to use a callback, but you want this within the callback to refer to your object. With a traditional function, it wouldn't, because traditional functions have their own this that's set by how they're called. Because of that, it's common to use a variable the callback can close over as a workaround, as in this ES5 code:

Thingy.prototype.delayedPrepAndShow = function() {
    var self = this;
    this.showTimer = setTimeout(function() {
        self.prep();
        self.show();
    }, this.showDelay);
};

Now you're using the variable self instead of this inside the callback, so it doesn't matter that the callback has its own version of this with a different value.

Since arrow functions don't have their own this, they close over this just like the ES5 example closes over the variable self. So you can rewrite that callback as an arrow function without any need for the self variable:

Thingy.prototype.delayedPrepAndShow = function() {
    this.showTimer = setTimeout(() => {
        this.prep();
        this.show();
    }, this.showDelay);
};

Much simpler. (In Chapter 4 you'll learn a new way to create that method, instead of assigning to a Thingy.prototype property.)

this isn't the only thing that arrow functions close over. They also close over arguments (the automatic pseudo-array of all of the arguments the function received), and two other things you'll learn about in Chapter 4 ( super and new.target).

Arrow Functions Cannot Be Constructors

Since they don't have their own this, it stands to reason that arrow functions can't be constructor functions. That is, you can't use them with new:

const Doomed = () => { };
const d = new Doomed(); // TypeError: Doomed is not a constructor

After all, the primary purpose of a constructor function is to fill in the newly constructed object, which is passed to the function as this. If the function doesn't have its own this, it can't set properties on the new object, and it doesn't make sense for it to be a constructor. Using them as constructors is explicitly disallowed.

Explicitly disallowing it made it possible for arrow functions to be lighter-weight than traditional functions, because they don't have to have a prototype property on them with an object attached to it. You'll recall that when you use a function as a constructor, the prototype of the new object that's created is assigned from the function's prototype:

function Thingy() {
}
var t = new Thingy();
console.log(Object.getPrototypeOf(t) === Thingy.prototype); // true

Since the JavaScript engine can't know in advance whether you're going to use a traditional function as a constructor, it has to put the prototype property and an object for it to refer to on every traditional function you create. (Subject to optimization, of course.)

But since arrow functions can't be constructors, they don't get a prototype property:

function traditional() {
}
const arrow = () => {
};
console.log("prototype" in traditional); // true
console.log("prototype" in arrow);       // false

Arrow functions aren't the only new things about functions in modern JavaScript, though, not at all.

Defaults Are Expressions

A parameter default is an expression; it doesn't have to be just a literal value. The default can even call a function. The default expression is evaluated when the function is called, not when the function is defined, and only if the default is needed for that particular call to the function.

For instance, suppose you wanted to use a different duration for each type of animation, and you had a function that gave you the default duration for a given type. You could write the animate function like this:

function animate(type, duration = getDefaultDuration(type)) {
    // …do the work…
}

getDefaultDuration isn't called unless needed. That's treated almost exactly like this:

function animate(type, duration) {
    if (duration === undefined) {
        duration = getDefaultDuration(type);
    }
    // …do the work…
}

The main difference relates to scope, which we'll come to in a moment.

In that example, the default for duration uses the type parameter. That's fine, because type comes before duration. If type came after duration, it would be a ReferenceError if duration's default were needed for a particular call:

function animate(duration = getDefaultDuration(type), type) {
    // …do the work…
}
animate(undefined, "dissolve"); // ReferenceError: type is not defined

This is just as though you'd tried to access the value of a variable declared with let before the let declaration, as you saw in Chapter 2. From the JavaScript engine's perspective, that function looks a lot like this (again, other than scope):

function animate() {
    let duration = /*…get the value of argument 0…*/;
    if (duration === undefined) {
        duration = getDefaultDuration(type);
    }
    let type = /*…get the value of argument 1…*/;
    // …do the work…
}

If you call it without a duration, the code filling in the default tries to use type when it's in the Temporal Dead Zone, so you get an error.

The rule is simple: a default can use parameters listed before it, but not parameters listed after it.

Defaults Are Evaluated in Their Own Scope

As you've learned, defaults can refer to other parameters as long as they're before the default in the list, and they can refer to things that are part of the outer scope (like the getDefaultDuration function in the earlier example). But they can't refer to anything defined within the function body, not even things that are hoisted. Run Listing 3-3.

I've used var there because it doesn't have the Temporal Dead Zone; it's hoisted to the top of the scope where it's declared. But the default value expression still couldn't use it. The reason is that defaults are evaluated in their own scope, which exists between the scope containing the function and the scope inside the function (see Figure 3-1). It's as though the function were wrapped in another function that handled doing the defaults, a bit like this:

function example(value) {
    if (value === undefined) {
        value = x;
    }
    const exampleImplementation = () => {
        var x = 42;
        console.log(value);
    };
    return exampleImplementation();
}
example(); // ReferenceError: x is not defined

That's not literally how it's done, of course, but conceptually it's very close.

Fortunately, just looking at a function with its parameter list, the pieces are visually distinct (the parameter list is set apart from the function body), so it's easy to understand the parameter list having its own scope.

Defaults Don't Add to the Arity of the Function

The arity of a function is typically defined as the number of formal declared parameters it has, which in JavaScript you can get from the length property of the function:

function none() {
}
console.log(none.length); // 0
function one(a) {
}
console.log(one.length);  // 1
function two(a, b) {
}
console.log(two.length);  // 2

In JavaScript, parameters with default values don't get counted when calculating the arity, and in fact they prevent any subsequent parameters from being counted as well:

function stillOne(a, b = 42) {
}
console.log(stillOne.length);    // 1
function oneYetAgain(a, b = 42, c) {
}
console.log(oneYetAgain.length); // 1

The result for the stillOne function is simple enough: it has one parameter without a default and one with, so its arity is 1. The result for the oneYetAgain function is more interesting in that its c parameter doesn't have an explicit default, but because the parameter in front of it does, it isn't counted toward the arity.

Function Declarations in Blocks: Standard Semantics

The simplest handling is the standard semantics, which are always in effect in strict mode (even on web browsers). I suggest you use strict mode in order to avoid accidentally writing code relying on legacy semantics. With standard semantics, function declarations are effectively converted into function expressions assigned to let variables (so they're scoped to the block they're in), hoisted to the top of the block. Let's take the earlier branching function and add a bit more logging to see the hoisting:

"use strict";
function branching(num) {
    console.log(num);
    if (num < 0.5) {
        console.log("true branch, typeof doSomething = " + typeof doSomething);
        function doSomething() {
            console.log("true");
        }
    } else {
        console.log("false branch, typeof doSomething = " + typeof doSomething);
        function doSomething() {
            console.log("false");
        }
    }
    doSomething();
}
branching(Math.random());

In strict mode, the JavaScript engine treats that code as though it were like this:

"use strict";
function branching(num) {
    console.log(num);
    if (num < 0.5) {
        let doSomething = function doSomething() {
            console.log("true");
        };
        console.log("true branch, typeof doSomething = " + typeof doSomething);
    } else {
        let doSomething = function doSomething() {
            console.log("false");
        };
        console.log("false branch, typeof doSomething = " + typeof doSomething);
    }
    doSomething();
}
branching(Math.random());

Notice how each declaration was effectively hoisted within its block, up above the console.log call.

Naturally, if you run that, it fails, because the doSomething at the very end is not a declared identifier in the function's top level scope, since the doSomething in each block is block-scoped. So let's change our example to something that will run, and run it; see Listing 3-4.

Now, when you run it, f ends up referring to one function or the other, and either logs “true” or “false.” Because of hoisting, doSomething refers to the function when it's assigned to f, even though that assignment is above the declaration.

Function Declarations in Blocks: Legacy Web Semantics

In loose mode on web browsers, legacy web semantics defined by Annex B of the specification apply. (Some engines apply them even outside web browsers.) The specification notes that, when not treating function declarations in blocks as syntax errors, the different ways engines handled them meant that only scenarios that were handled the same way by an intersection of those JavaScript engines could be relied upon. Those three scenarios are:

1. A function is declared and only referenced within a single block.
2. A function is declared and possibly used within a single block but also referenced by an inner function definition that is not contained within that same block.
3. A function is declared and possibly used within a single block but also referenced within subsequent blocks.

The example branching function we've used in this chapter doesn't fit any of those three scenarios, because it has two function declarations using the same name in two different blocks, and then references that name in code following those blocks. But if you have legacy loose-mode code matching one of these three scenarios, you can expect it to work cross-browser. That doesn't mean you should write new code that relies on legacy web semantics. Instead, write code relying only on the standard semantics (perhaps using strict mode to ensure that).

The legacy semantics are much the same as standard semantics, but in addition to the let variable within the block for the function declared in the block, there's also a var variable for it in the containing function's scope (or global scope, if all of this isn't inside a function). Unlike the let in the block, the var's assignment isn't hoisted to the top of the block, it's done when the function declaration is reached in the code. (This seems odd, but it's to support case #2 of the intersection of behaviors across major engines prior to standardization.)

Again, the branching example doesn't fit the list of common handling that legacy semantics are meant to address, but legacy semantics do say how it's meant to be handled now (whereas in older engines it may not be handled this way): because there's a doSomething var-style variable at function scope, the doSomething call at the end works. Let's look at the example again, without the "use strict";, and with logging both before and after the function declarations. Load and run Listing 3-5.

As you can see, this time the doSomething at the end isn't out of scope. In loose mode, the JavaScript engine treats that effectively like the following (except, of course, both varDoSomething and letDoSomething are simply doSomething):

function branching(num) {
    var varDoSomething;
    console.log("num = " + num + ", typeof doSomething = " + typeof varDoSomething);
    if (num < 0.5) {
        let letDoSomething = function doSomething() {
            console.log("true");
        };
        console.log("true branch, typeof doSomething = " + typeof letDoSomething);
        varDoSomething = letDoSomething; // where the declaration was
        console.log("end of true block");
    } else {
        let letDoSomething = function doSomething() {
            console.log("false");
        };
        console.log("false branch, typeof doSomething = " + typeof letDoSomething);
        varDoSomething = letDoSomething; // where the declaration was
        console.log("end of false block");
    }
    varDoSomething();
}
branching(Math.random());

Since the functions are assigned to a function-scope var variable, it's accessible outside the blocks. But the declarations are still hoisted within their blocks.

But again, it's best not to write new code relying on these legacy semantics. Instead, the consistency of strict mode is the way to go.

Use Arrow Functions Instead of Various this Value Workarounds

Old habit: Various workarounds for having access to the calling context's this in a callback, such as:

• Using a variable, e.g. var self = this;
• Using Function.prototype.bind
• Using the thisArg parameter of functions that support it

Examples:

// Using a variable
var self</span>
 = this;
this.entries.forEach(function(entry) {
    if (entry.matches(str)) {
        self</span>
.appendEntry(entry);
    }
});
 
// Using Function.prototype.bind
this.entries.forEach(function(entry) {
    if (entry.matches(str)) {
        this.appendEntry(entry);
    }
}.bind(this));
 
// Using 'thisArg'
this.entries.forEach(function(entry) {
    if (entry.matches(str)) {
        this.appendEntry(entry);
    }
}, this);

New habit: Use an arrow function:

this.entries.forEach(entry => {
    if (entry.matches(str)) {
        this.appendEntry(entry);
    }
});

Use Arrow Functions for Callbacks When Not Using this or arguments

Old habit: Using traditional functions for callbacks that don't use this or arguments (because you didn't have a choice):

someArray.sort(function(a, b) {
    return a - b;
});

New habit: If the callback doesn't use this or arguments, use an arrow function. Arrow functions are lighter-weight and more concise:

someArray.sort((a, b) => a - b);

The majority of array callbacks (such as on sort, forEach, map, reduce, …), callbacks on string replace calls, promise creation and resolution callbacks (you'll learn about promises in Chapter 8), and many others can all usually be arrow functions.

Consider Arrow Functions Elsewhere As Well

Old habit: Using traditional functions for everything, because (again) you didn't have a choice.

New habit: Consider whether using an arrow function makes sense even if it's not a callback. This will be primarily a matter of style. For example, look at this function, which produces an initial-capped string from an input string:

function initialCap(str) {
    return str.charAt(0).toUpperCase() + str.substring(1);
}

Compared with the arrow function version:

const initialCap = str =>
    str.charAt(0).toUpperCase() + str.substring(1);

In theory, the arrow function doesn't have the cruft associated with the traditional function. Also, you can use const as in that example to avoid the identifier being reassigned (or use let if you don't want to prevent that).

Traditional functions aren't going anywhere, of course. Hoisting is sometimes useful, some prefer having the function keyword flag up functions, and if brevity is your thing it's worth noting that even

let x = () => { /*…*/ };

is ever-so-slightly longer than

function x() { /*…*/ }

although grantedlet

x=()=>{ /*…*/ };

is ever-so-slightly shorter.

It largely comes down to your style preference (and your team’s).

Don't Use Arrow Functions When the Caller Needs to Control the Value of this

Old habit: Using a traditional function as a callback where it's important that the caller controls what this is.

New habit: Um…keep doing that.

Sometimes, it's important that the caller sets what this is. For instance, in browser code using jQuery, you frequently want jQuery to control what this is in a callback. Or when responding to DOM events that you've hooked up with addEventListener, because it will set this to refer to the element when calling your callback (although you can use the event object's currentTarget property instead). Or when defining object methods that are shared between objects (for instance, because they're on the prototype), because it's important to allow this to be set when they're called.

So while switching to arrow functions is useful in some cases, sometimes an old traditional function (or the method syntax you'll learn about in Chapters 4 and 5) is what you want.

Use Default Parameter Values Rather Than Code Providing Defaults

Old habit: Using code inside the function to provide a default for a parameter:

function doSomething(delay) {
    if (delay === undefined) {
        delay = 300;
    }
    // …
}

New habit: Where possible, use default parameter values instead:

function doSomething(delay = 300) {
    // …
}

Use a Rest Parameter Instead of the arguments Keyword

Old habit: Using the arguments pseudo-array in functions accepting varying numbers of arguments.

New habit: Use a rest parameter.

Consider Trailing Commas if Warranted

Old habit: Not including a trailing comma in parameter lists and function calls (because they weren't allowed):

function example(
    question,   // (string) The question, must end with a question mark
    answer      // (string) The answer, must end with appropriate punctuation
) {
    // …
}
// …
example(
    "Do you like building software?",
    "Big time!"
);

New habit: Depending on your style/your team's style, you could consider using trailing commas so adding further parameters/arguments as the code evolves doesn't require changing the lines defining what used to be the last parameter or argument:

function example(
    question,   // (string) The question, must end with a question mark
    answer,     // (string) The answer, must end with appropriate punctuation
) {
    // …
}
// …
example(
    "Do you like building software?",
    "Big time!",
);

However, this is a matter of style.

Adding a Constructor

Even with just what we have so far, the class has a default constructor, since we haven't provided an explicit one; more about that in a moment. For now, let's add a constructor to the class that actually does something. You define code for the constructor in a constructor definition, like this:

class Color {
    constructor(r = 0, g = 0, b = 0) {
        this.r = r;
        this.g = g;
        this.b = b;
    }
}

This defines the function that will be associated with the class's identifier, Color. Notice the syntax: you don't use the keyword function anywhere, just the name constructor, an opening parenthesis, the parameter list if any (in this case, r, g, and b), a closing parenthesis, the curly braces to define the constructor body, and the code for the constructor within those braces. (In real-world code, you might validate the r, g, and b values; I've left that out of the example to keep it short.)

In ES5 and earlier, you probably would have defined that constructor like this:

// Older (~ES5) near-equivalent
function Color(r, g, b) {
    // …
}

but since class declarations aren't hoisted like function declarations, those aren't exactly equivalent; it's more like a function expression assigned to a variable:

// Older (~ES5) near-equivalent
var Color = function Color(r, g, b) {
    // …
};

One thing to note here is how with class syntax, you write a structure for the class as a whole and write the constructor definition separately within it, whereas with the old syntax you just defined a function (and it was down to how you used that function whether it was just a function or the constructor for a class). The new syntax is like that so you can define other aspects of the class declaratively, within the same container: the class construct.

As noted earlier, providing an explicit constructor is optional; the Color class would be perfectly valid without one (other than not setting up its x, y, and z properties). If you don't provide a constructor, the JavaScript engine creates one for you that does nothing, exactly as though you had this in the class:

constructor() {
}

(In subclasses it does something, as you'll learn later.)

The constructor is a function, but you can only call it as part of the object creation process: running the constructor function must be the result of using new (either directly or indirectly by using new on a subclass) or the result of calling Reflect.construct (which you'll learn about in Chapter 14). If you try to call it when not creating an object, it throws an error:

Color();      // TypeError: Class constructor Color cannot
              // be invoked without 'new'

This addresses a whole range of bugs the old syntax didn't, where a function meant to be a constructor could also be called without new, leading to extremely confusing results (or bloated code to prevent it).

Let's add that “bloated code” to the ES5 Color example to make it (somewhat) disallow calls except through new:

// Older (~ES5) near-equivalent
var Color = function Color(r, g, b) {
    if (!(this instanceof Color)) {
        throw new TypeError(
            "Class constructor Color cannot be invoked without 'new'"
        );
    }
    // …
};

That doesn't actually force it to be called as part of the object construction process (you could just call it via Color.call or Color.apply with a preexisting object), but it at least makes an attempt to.

You can see that already, even in a minimal class, you're getting real advantages in terms of robustness from using the new syntax, while cutting down boilerplate code.

Code inside a class is always in strict mode, even if the surrounding code is not. So to be really thorough with the ES5 example, we'd have to wrap all that in a scoping function and use strict mode within it. But let's just assume our code is already in strict mode rather than further complicating our ES5 example.

Adding Instance Properties

At least for now, the standard way to set up properties on new instances of a class is to assign to them in the constructor just like you do in ES5:

class Color {
    constructor(r = 0, g = 0, b = 0) {
        this.r = r;
        this.g = g;
        this.b = b;
    }
}

Because those properties are created through basic assignment, they're configurable, writable, and enumerable.

Naturally, in addition to (or instead of) properties you get from parameters, you could set up a property that doesn't come from a constructor argument, just using a literal or a value that comes from somewhere else. If you wanted all Color instances to start out black, for instance, you could leave off the r, g, and b parameters and just make the r, g, and b properties all start out with the value zero:

class Color {
    constructor() {
        this.r = 0;
        this.g = 0;
        this.b = 0;
    }
}

Adding a Prototype Method

Now let's add a method that will be put on the class's prototype object so all instances have access to it:

class Color {
    constructor(r = 0, g = 0, b = 0) {
        this.r = r;
        this.g = g;
        this.b = b;
    }
    toString() {
        return "rgb(" + this.r + ", " + this.g + ", " + this.b + ")";
    }
}

Note that there's no comma between the constructor definition and the toString definition, as there would be if they were in an object literal. A class definition isn't like an object literal; you don't separate things with commas. (If you do, you'll get a syntax error.)

The method syntax shown earlier puts the method on the Color.prototype object, so instances of the class inherit that method from their prototype:

const c = new Color(30, 144, 255);
console.log(c.toString());            // "rgb(30, 144, 255)"

Contrast the new syntax with how prototype functions are typically added in ES5:

// Older (~ES5) near-equivalent
Color.prototype.toString = function toString() {
    return "rgb(" + this.r + ", " + this.g + ", " + this.b + ")";
};

The new syntax, ES2015's method syntax, is more declarative and concise. It also marks the function specifically as a method, which gives it access to features it wouldn't have as a simple function (such as super; you'll learn about that later). The new syntax also makes the method non-enumerable, a reasonable default for methods on prototypes, which the ES5 version shown earlier doesn't. (To make it non-enumerable in the ES5 code, you'd have to define it with Object.defineProperty instead of using assignment.)

A method is also, by definition, not a constructor function, and so the JavaScript engine doesn't put a prototype property and associated object on it:

class Color {
    // …
    toString() {
        // …
    }
}
const c = new Color(30, 144, 255);
console.log(typeof c.toString.prototype); // "undefined"

Since methods aren't constructors, trying to call them via new results in an error.

In contrast, in ES5, all functions might be used as constructors as far as the engine knows, and so it has to give them a prototype property with an object attached:

// Older (~ES5) near-equivalent
var Color = function Color(r, g, b) {
    // …
};
Color.prototype.toString = function toString() {
    // …
};
var c = new Color(30, 144, 255);
console.log(typeof c.toString.prototype); // "object"

In theory, then, method syntax is more memory-efficient than the older function syntax. In practice, it wouldn't be surprising if JavaScript engines were already able to optimize away unneeded prototype properties even on ES5 methods.

Adding a Static Method

In building up the example Color class, so far you've seen a constructor, a couple of instance properties, and a prototype method. Let's add a static method, which is a method attached to Color itself instead of to the prototype:

class Color {
    // …
 
    static fromCSS(css) {
        const match = /^#?([0-9a-f]{3}|[0-9a-f]{6});?$/i.exec(css);
        if (!match) {
            throw new Error("Invalid CSS code: " + css);
        }
        let vals = match[1];
        if (vals.length === 3) {
            vals = vals[0] + vals[0] + vals[1] + vals[1] + vals[2] + vals[2];
        }
        return new this(
            parseInt(vals.substring(0, 2), 16),
            parseInt(vals.substring(2, 4), 16),
            parseInt(vals.substring(4, 6), 16)
        );
    }
}

The static keyword tells the JavaScript engine to put that method on Color itself, not on Color.prototype. You call it on Color directly:

const c = Color.fromCSS("#1E90FF");
console.log(c.toString());           // "rgb(30, 144, 255)"

Previously in ES5 you would have done this by assigning to a property on the Color function:

Color.fromCSS = function fromCSS(css) {
    // …
};

As with prototype methods, using method syntax means that fromCSS doesn't have a prototype property with an object assigned to it, which that ES5 version would, and can't be called as a constructor.

Adding an Accessor Property

Let's add an accessor property to the Color class. An accessor property is a property with a getter method, setter method, or both. For Color, let's provide an rgb property that gets the color as a standard rgb(r,g,b) string, and update the toString method to use that property instead of creating the string itself:

class Color {
    // …
 
    get rgb() {
        return "rgb(" + this.r + ", " + this.g + ", " + this.b + ")";
    }
 
    toString() {
        return this.rgb;
    }
}
let c = new Color(30, 144, 255);
console.log(c.rgb);           // "rgb(30, 144, 255)"

As you can see, this is just like defining an accessor in an object literal in ES5. There's one small difference in the result: accessor properties in class constructs are non-enumerable, which again makes sense for something defined on a prototype, whereas accessor properties defined in object literals are enumerable.

So far, Color's rgb accessor is read-only (a getter with no setter). If you wanted to add a setter, you'd define a set method as well:

class Color {
    // …
 
    get rgb() {
        return "rgb(" + this.r + ", " + this.g + ", " + this.b + ")";
    }
 
    set rgb(value) {
        let s = String(value);
        let match = /^rgb\((\d{1,3}),(\d{1,3}),(\d{1,3})\)$/i.exec(
            s.replace(/\s/g, "")
        );
        if (!match) {
            throw new Error("Invalid rgb color string '" + s + "'");
        }
        this.r = parseInt(match[1], 10);
        this.g = parseInt(match[2], 10);
        this.b = parseInt(match[3], 10);
    }
 
    // …
}

Now you can set rgb as well as getting it:

let c = new Color();
console.log(c.rgb);           // "rgb(0, 0, 0)"
c.rgb = "rgb(30, 144, 255)";
console.log(c.r);             // 30
console.log(c.g);             // 144
console.log(c.b);             // 255
console.log(c.rgb);           // "rgb(30, 144, 255)"

Defining an accessor in ES5 is a bit painful if you want to add it to the existing object on the prototype property (rather than replacing that object with a new one):

// Older (~ES5) near-equivalent
Object.defineProperty(Color.prototype, "rgb", {
    get: function() {
        return "rgb(" + this.r + ", " + this.g + ", " + this.b + ")";
    },
    set: function(value) {
        // …
    },
    configurable: true
});

You can also define static accessor properties, though that's likely to be a rare use case. Simply define an accessor with static before it:

class StaticAccessorExample {
    static get cappedClassName() {
        return this.name.toUpperCase();
    }
}
console.log(StaticAccessorExample.cappedClassName); // STATICACCESSOREXAMPLE

Computed Method Names

Sometimes, you want to create methods with names that are determined at runtime rather than literally provided in the code. This is particularly important when using Symbols, which you'll learn about in Chapter 5. In ES5 it was easy enough to do that with brackets property accessor syntax:

// Older (~ES5) example
var name = "foo" + Math.floor(Math.random() * 1000);
SomeClass.prototype[name] = function() {
    // …
};

In ES2015, you can do much the same with method syntax:

let name = "foo" + Math.floor(Math.random() * 1000);
class SomeClass {
    [name]() {
        // …
    }
}

Note the square brackets around the method name. They work exactly the same way they do in a property accessor:

• You can put any expression inside them.
• The expression is evaluated when the class definition is evaluated.
• If the result isn't a string or a Symbol (Chapter 5), it's converted to a string.
• The result is used as the method name.

Static methods and accessor property methods can have computed names as well. Here's an example of a static method that gets its name from the result of a multiplication expression:

class Guide {
    static [6 * 7]() {
        console.log("Life, the Universe, and Everything");
    }
}
Guide["42"](); // "Life, the Universe, and Everything"

The super Keyword

To add features to ColorWithAlpha, in many cases you’ll need to know about a new keyword: super. You use super in constructors and methods to refer to aspects of the superclass. There are two ways you can use it:

• super(): In a subclass constructor, you call super as though it were a function to create the object and have the superclass do its initialization of the object.
• super.property and super.method(): You refer to properties and methods of the superclass prototype by accessing them on super rather than on this. (Of course, you can use either dot notation, super.property, or brackets notation, super["property"].)

The next two sections go into the details of using super.

Writing Subclass Constructors

ColorWithAlpha will need a property that Color doesn't have: the opacity. Let's give it a property called a (“alpha”) to store it in. The a property will have values in the range 0 to 1 (inclusive); for instance, the value 0.7 means the color is 70% opaque (30% transparent).

Since ColorWithAlpha needs to accept a fourth construction parameter, it can't just use the default constructor anymore. It needs its own:

class ColorWithAlpha extends Color {
    constructor(r = 0, g = 0, b = 0, a = 1) {
        super(r, g, b);
        this.a = a;
    }
}

The first thing ColorWithAlpha does is call super, passing in the r, g, and b parameters. This creates the object and lets Color do its initialization of the object. In ES5, the constructor might look like this:

// Older (~ES5) near-equivalent
var ColorWithAlpha = function ColorWithAlpha(r, g, b, a) {
    Color.call(this, r, g, b);
    this.a = a;
};

The Color.call(this, r, g, b) is the near-equivalent of super(r, g, b). But there's a significant difference: in ES5, the object was created before the first line of ColorWithAlpha ran. You could reverse the two lines in it if you wanted to (though it would be poor practice):

var ColorWithAlpha = function ColorWithAlpha(r, g, b, a) {
    this.a = a;                 // Works even though it's before the call to Color
    Color.call(this, r, g, b);
};

That isn't true with class. At the beginning of ColorWithAlpha's code, the object hasn't been created yet. If you try to use this, you'll get an error. You can only use this once the object has been created, and it isn't created until you call super. Try running the code in Listing 4-5.

The exact error you get will vary from JavaScript engine to JavaScript engine. Here are some examples:

• ReferenceError: Must call super constructor in derived class before accessing 'this' or returning from derived constructor
• ReferenceError: must call super constructor before using |this| in ColorWithAlpha class constructor
• ReferenceError: this is not defined

This requirement is there to ensure that the initialization of the object being constructed is done from the base upward. You can have code in your constructor prior to calling super, but it cannot use this or anything else instance-specific until after the object has been created and the superclass has had its chance to initialize the instance.

Not only is this off-limits until you call super, but you must call super at some point in a subclass constructor. If you don't, an error occurs when the constructor returns. Finally, unsurprisingly, trying to call super twice is an error: you can't create the object when it already exists!

Inheriting and Accessing Superclass Prototype Properties and Methods

Sometimes, a subclass overrides the definition of a method, providing its own instead of using the one inherited from the superclass. For instance, ColorWithAlpha should have its own toString that uses rgba notation and includes the a property:

class ColorWithAlpha extends Color {
    // …
 
    toString() {
        return "rgba(" + this.r + ", " +
                         this.g + ", " +
                         this.b + ", " +
                         this.a + ")";
    }
}

With that in place, calling toString on a ColorWithAlpha instance will use that definition instead of the one from Color.

Sometimes, though, the subclass method needs to call the superclass method as part of its implementation. Obviously this.methodName() wouldn't work, because it would just be calling itself; you need to go up a level. To do that, you call the superclass method via super.methodName().

Let's look at that by adding a brightness method to Color that calculates the brightness (luminance) of the color:

class Color {
    // …
 
    brightness() {
        return Math.sqrt(
            (this.r * this.r * 0.299) +
            (this.g * this.g * 0.587) +
            (this.b * this.b * 0.114)
        );
    }
}

Without getting into the math (and this is just one definition of luminance; there are others), those constants adjust the colors to allow for the fact that human eyes perceive the brightness of red, green, and blue differently.

That definition of brightness works for Color, but not ColorWithAlpha, which needs to take its opacity into account: at a minimum it needs to dim its brightness based on its transparency, and ideally it wants to know what background color will be behind it so it can account for the brightness of that color, since the background color will partially show through. So ColorWithAlpha needs its own version of brightness, like this:

class ColorWithAlpha extends Color {
    // …
    brightness(bgColor) {
        let result = super.brightness() * this.a;
        if (bgColor && this.a !== 1) {
            result = (result + (bgColor.brightness() * (1 - this.a))) / 2;
        }
        return result;
    }
}

It uses Color's brightness to get the basic brightness of its color ( super.brightness()), then applies the opacity. If it was given a background color and the current color isn't fully opaque, it takes the background color's brightness into account. Listing 4-6 has the full code of Color and ColorWithAlpha so far, and some examples using brightness. Run it, perhaps stepping through it in the debugger, to see all this in action.

Let's look at how you might define that brightness method in ES5:

// Older (~ES5) near-equivalent
ColorWithAlpha.prototype.brightness = function brightness(bgColor) {
    var result = Color.prototype.brightness.call(this) * this.a;
    if (bgColor && this.a !== 1) {
        result = (result + (bgColor.brightness() * (1 - this.a))) / 2;
    }
    return result;
};

The highlighted line with the superclass brightness call can be written several ways. This way explicitly refers to Color (the superclass), which isn't ideal since you might change the parent class when refactoring. Another option is to use Object.getPrototypeOf on ColorWithAlpha.prototype:

    var superproto = Object.getPrototypeOf(ColorWithAlpha.prototype);
    var result = superproto.brightness.call(this) * this.a;

Or use Object.getPrototypeOf twice:

    var superproto = Object.getPrototypeOf(Object.getPrototypeOf(this));
    var result = superproto.brightness.call(this) * this.a;

They're all awkward, and they all have to manage this by using call. In ES2015+, super just handles it for you.

This syntax isn’t just for methods, you can use it to access non-method properties on the prototype as well. But it’s rare to have non-method properties on class prototype objects, and rarer still to want to access them directly rather than through the instance.

Inheriting Static Methods

Earlier you learned how to create a static method in a class. In JavaScript, static methods are inherited by subclasses. Run Listing 4-7, which shows using fromCSS (which is defined on Color) on ColorWithAlpha.

Note how you can call fromCSS on ColorWithAlpha, and note that the result is a ColorWithAlpha instance, not a Color instance. Let's look at why that works.

At the beginning of this section on subclassing, you learned that using the extends clause creates two inheritance chains: one on the constructor itself, and one on the constructor's prototype object; see Figure 4-2, which is a copy of the earlier Figure 4-1.

The constructor inheritance chain is a new thing in ES2015. Up through ES5, there was no standard way to have a true JavaScript function whose prototype was anything but Function.prototype. But it makes perfect sense for a subclass's constructor to use the superclass constructor as its prototype, and consequently to inherit its properties and methods.

But why did fromCSS create a ColorWithAlpha object instead of a Color object, if it's defined on Color? We touched on that very briefly earlier in this chapter. Let's look again at how Color defines fromCSS:

class Color {
    // …
 
    static fromCSS(css) {
        const match = /^#?([0-9a-f]{3}|[0-9a-f]{6});?$/i.exec(css);
        if (!match) {
            throw new Error("Invalid CSS code: " + css);
        }
        let vals = match[1];
        if (vals.length === 3) {
            vals = vals[0] + vals[0] + vals[1] + vals[1] + vals[2] + vals[2];
        }
        return new this(
            parseInt(vals.substring(0, 2), 16),
            parseInt(vals.substring(2, 4), 16),
            parseInt(vals.substring(4, 6), 16)
        );
    }
}

The key thing there is that it creates the object using new this, rather than new Color. If you call fromCSS on Color, this within the call is Color; but if you call it on ColorWithAlpha, this within the call is ColorWithAlpha, so that's the constructor that gets called by new this. Try copying the accessing-static-method-through-subclass.js file from the downloads and changing it to new Color instead.

Methods Returning New Instances

In this section you'll learn about patterns for creating new instances of a class from its methods, both static methods like Color.fromCSS and instance methods like slice and map on arrays.

You've already seen a static method using one pattern to create an instance of the class: Color.fromCSS, which uses new this(/*…*) to create the new instance. It works pretty well. When you call Color.fromCSS, you get a Color instance. When you call ColorWithAlpha.fromCSS, you get a ColorWithAlpha instance. That's the behavior you usually want. In an instance method, you’d use this.constructor rather than this, because this.constructor usually refers to the constructor of the object. For instance, here’s a method for Color that returns a color that’s half the brightness of the original:

halfBright() {
    const ctor = this.constructor || Color;
    return new ctor(
        Math.round(this.r / 2),
        Math.round(this.g / 2),
        Math.round(this.b / 2)
    );
}

But suppose you wanted to create a Color subclass in which fromCSS and halfBright returned an instance of Color instead? (That’s a slightly odd thing to have fromCSS do, but let’s ignore that for the moment.) With the current implementations of fromCSS and halfBright, you'd have to override them and use Color explicitly, along these lines:

class ColorSubclass extends Color {
    static fromCSS(css) {
        return Color.fromCSS(css);
    }
    halfBright() {
        return new Color(
            Math.round(this.r / 2),
            Math.round(this.g / 2),
            Math.round(this.b / 2)
        );
    }
}

That’s okay for just one method or maybe even two. But what if Color had several other operations that created new instances and you wanted those to create Color rather than ColorSubclass instances? You’d have to override all of them, too. That could start to get messy. (Think about all of the array methods like slice and map that create new arrays, and the hassle it would be to override all of them in an array subclass if you didn't want the default behavior.)

If you want most methods that create new instances to use the same constructor in a way that’s easy for subclasses to override, there’s a better alternative: Symbol.species.

Symbols are something we haven't covered yet. You'll learn about them in Chapter 5. For the moment, all you need to know is that they're a new kind of primitive, they can be used as a property key (like a string, but they're not strings), and that there are “well known” ones available as properties on the Symbol function, including the one we'll use here: Symbol.species.

Symbol.species is part of a pattern designed specifically to allow subclasses to control what happens in methods that need to create new instances of “the” class. In the base class (Color in this example), instead of using the constructor the method has from this or this.constructor as we’ve done so far, methods using the species pattern determine the constructor to use by looking up the Symbol.species property on this / this.constructor. If the result is null or undefined, the class defines a default that it uses instead. In fromCSS that would look like this:

static fromCSS(css) {
    // …
    let ctor = this[Symbol.species];
    if (ctor === null || ctor === undefined) {
        ctor = Color;
    }
    return new ctor(/*…*/);
}

Since null and undefined are both falsy, and a constructor function by definition is never falsy, you could simplify that a bit:

static fromCSS(css) {
    // …
    const ctor = this && this[Symbol.species] || Color;
    return new ctor(/*…*/);
}

(Later you'll learn why we're using an explicit fallback there, Color, rather than using this.)

Note that the code is a bit defensive, checking that this is truthy (since class code is in strict mode and this can be any value, including undefined).

Again, though, it may be a bit odd for a static method to do that (depending on your use case). Let’s look at doing it in the prototype method halfBright:

halfBright() {
    const ctor = this && this.constructor &&
                 this.constructor[Symbol.species] || Color;
    return new Color(
        Math.round(this.r / 2),
        Math.round(this.g / 2),
        Math.round(this.b / 2)
    );
}

(In Chapter 19 you’ll learn about optional chaining, which would make the first statement in halfBright simpler: const ctor = this?.constructor?.[Symbol.species] || Color;)

When using the Symbol.species pattern, the base class defines that property in a clever way—as an accessor returning this:

class Color {
    static get [Symbol.species]() {
        return this;
    }
    // …
}

That way, if the subclass doesn't override the Symbol.species property, it'll be just as though the class used new this(/*…*/): the constructor the method was called on will be used ( Color or ColorWithAlpha, depending). But if the subclass overrides the Symbol.species property, the constructor from that override gets used instead.

Putting all those pieces together:

class Color {
    static get [Symbol.species]() {
        return this;
    }
    static fromCSS(css) {
        const ctor = this && this[Symbol.species] || Color;
        return new ctor(/*…*/);
    }
    halfBright() {
        const ctor = this && this.constructor &&
                     this.constructor[Symbol.species] || Color;
        return new ctor(/*…*/); 
   }
   // …
}

The standard library objects that use this pattern only use it for prototype and instance methods, not static methods. That’s because there was no strong reason for using it in static methods, and doing so you end up with odd or even misleading code like ColorWithAlpha.fromCSS returning a Color instance instead of a ColorWithAlpha instance. See Listing 4-9 for a simple synthetic example more along the lines of how the standard library uses the species pattern.

Notice how calling create on Sub1 created a Sub1 instance, and calling clone on that instance also created a Sub1 instance; calling create on Sub2 created a Sub2 instance, but calling clone on a Sub2 instance created a Base instance.

Earlier I said I'd tell you why we're using an explicit default in that example ( Base; and Color in the earlier examples) if the value of the Symbol.species property is null or undefined. That's what the built-in classes like Array do. They could have used this (in static methods) or this.constructor (in prototype methods) as the default instead, but by using an explicit default, they give subclasses of subclasses a way to ask for the original default rather than the current subclass constructor. So with the Base from the previous example, in this code:

class Sub extends Base {
}
 
class SubSub1 extends Sub {
}
 
class SubSub2 extends Sub {
    static get [Symbol.species]() {
        return null;
    }
}
 
const x = new SubSub1(1).clone();
console.log(x.constructor.name); // "SubSub1"
 
const y = new SubSub2(2).clone();
console.log(y.constructor.name); // "Base", not "SubSub2" or "Sub"

the default from Base is applied in SubSub2’s clone method, rather than something from a subclass. (Try it using explicit-constructor-default.js from the downloads.)

Subclassing Built-ins

In ES5, some of the built-in constructors such as Error and Array were notoriously impossible to properly subclass; that's been fixed in ES2015. Subclassing a built-in with class is just like subclassing anything else. (You can also subclass them without class syntax via Reflect.construct; more on that in Chapter 14.) Let's look at an array example. Listing 4-10 shows a very simple Elements class that extends Array with a style method that sets style information on the DOM elements in the array. Try running it in a page with at least three div elements in it (there's a subclassing-array.html file in the downloads you can use).

The “Usage” code at the end:

• Creates an instance of Elements, which is a subclass of Array
• Uses its select method to add all div elements on the page to the instance (using the array method push to add them)
• Styles those elements with green text
• Creates a new Elements instance using the array method slice to take just the second and third div elements
• Adds a red border around those div elements with the style method

(Note how using slice created a new Elements instance, not just a new Array. That's because Array uses the Symbol.species pattern you learned about in the last section, and Elements doesn’t override the default.)

Elements is just an example, of course. In a real implementation, you'd probably pass the selector into the Elements constructor rather than using a separate select call afterward to populate the instance. Doing that in a robust way requires using a feature you haven't learned about yet (iterable spread, in Chapter 6). If you want to see what it would look like (also using for-of [Chapter 6], Object.entries [Chapter 5], and destructuring [Chapter 7]), refer to subclassing-array-using-later-chapter-features.js in the downloads.

Where super Is Available

Before ES2015, we used the term method loosely in JavaScript to refer to any function assigned to an object property (or perhaps only the ones that use this). As of ES2015, while that's still common informally, there is now a distinction between true methods and functions assigned to properties: code inside a true method has access to super; code in a traditional function assigned to a property does not. Let's prove that to ourselves with Listing 4-11: read through and try to run it.

The JavaScript engine will refuse to parse that code, complaining that super wasn't expected on the line marked in the listing. But why not?

Because methods have a link to the object on which they're created, but traditional functions assigned to properties don't. When used in a property lookup operation like super.foo, super relies on an internal field of the containing function called [[HomeObject]]. The JavaScript engine gets the object from the [[HomeObject]] field of the method, gets its prototype, and then looks for the method property on that object, like this pseudocode:

// Pseudocode
let method = (the running method);
let homeObject = method.[[HomeObject]];
let proto = Object.getPrototypeOf(homeObject);
let value = proto.foo;

“But wait,” you say. “Why would super care where the method was defined? It just goes to this's prototype, right? Or this's prototype's prototype?”

No, it can't work that way. To see why, consider the three-layer hierarchy in Listing 4-12.

When you create that obj instance, its prototype chain looks like Figure 4-3.

Let's suppose super worked from this, knowing that it needed to go to this's prototype's prototype because it's being used in a prototype method. When you call obj.test, this equals obj. When it uses super.test(), getting the prototype of the prototype works: the prototype of obj is SubSub.prototype, and the prototype of SubSub.prototype is Sub.prototype, so it gets test from Sub.prototype; all is good so far. Then, it calls Sub.prototype's test with this set to obj. As part of its code, Sub.prototype.test also calls super.test(). Now the JavaScript engine is stuck. It can't do the same thing it did to get from SubSub to Sub because this is still obj, so this's prototype's prototype is still Sub.prototype, and it would just end up in the same place. Look through the code in Listing 4-13 and run it; eventually it raises a stack overflow error because Sub.prototype.test keeps calling itself.

That's why the methods need to have a field saying what object they're defined on (their [[HomeObject]]), so the JavaScript engine can get that object and then get its prototype to access the super's version of test. Refer to Figure 4-4 to follow through the following explanation: within obj.test, to do super.test() the JavaScript engine looks at the [[HomeObject]] on obj.test, which is SubSub.prototype, then gets the prototype of that object ( Sub.prototype) and calls the test method on it. To handle the super.test() in Sub.prototype.test, the engine gets [[HomeObject]] from Sub.prototype.test and gets its prototype, which is Base.prototype, and then calls the test method on it.

There is an important consequence of this: copying methods from object to object (a familiar pattern with “mixins”—objects with utility functions you copy into multiple prototypes) doesn't change the method's [[HomeObject]]. If you use super in a mixin method, it continues to use the prototype of its original home object, not the prototype of the object it's been copied to. This can create subtle cross-talk between the method's original home and the object you copied it to. If you do that on purpose (using a feature of the mixin's original parent), that's fine; but if you use super in a mixin method expecting it to work within the hierarchy of its new home, it'll be a bug.

At one stage when ES2015 was being developed, there was a function you could use to change the [[HomeObject]] of a method (specifically to enable mixins), but it was dropped before the spec was completed and hasn't been added back (yet). So for the moment at least, define mixins with traditional functions, or don't use super in them, or if you do, do it because you intend it to continue to work within its original hierarchy, not its new one.

class Declarations

class declarations work very similarly to function declarations, although with an important difference.

Like function declarations, class declarations:

• Add the class's name to the current scope, and
• Don't need a semicolon after the closing curly brace. (You can put one there, because JavaScript ignores unnecessary semicolons, but it's not needed by the declaration.)

Unlike function declarations, class declarations:

• Are not hoisted, they're half-hoisted: the identifier is reserved throughout the scope, but not initialized until the declaration is reached in the step-by-step execution of the code.
• Participate in the Temporal Dead Zone.
• Do not create a property on the global object for the class name if used at global scope; instead, they create globals that aren't properties of the global object.

Those last bits probably seem familiar. That's because they're the same as the rules you learned in Chapter 2 for let and const. Those rules apply to class declarations, too.

Listing 4-17 demonstrates the various aspects of a class declaration. (The code in Listing 4-17 must be run at global scope to demonstrate what happens with class declarations at global scope. Remember that you can't run this in Node.js in the usual way; you have to either use a browser or run it in Node.js's REPL environment. See Chapter 1.)

class Expressions

class expressions work very similarly to function expressions:

• They have both named and anonymous forms.
• They do not add the class's name to the scope in which they appear, but do make the class's name available within the class definition itself (if it has a name).
• They result in a value (the class's constructor) that can be assigned to a variable or a constant, passed into a function, or ignored.
• The JavaScript engine will infer the value of the name property for a class created with an anonymous class expression from context, using the same rules you learned in Chapter 3 for anonymous function expressions.
• When used as the right-hand side of an assignment, they do not terminate the assignment expression; if the class expression is the last thing in the assignment expression, it should be followed by a semicolon. (In many cases, Automatic Semicolon Insertion [ASI] can correct a missing semicolon, but not always.)

Listing 4-18 demonstrates aspects of the class expression.

Use class When Creating Constructor Functions

Old habit: Using traditional function syntax to create constructor functions (because you had no choice!):

var Color = function Color(r, g, b) {
    this.r = r;
    this.g = g;
    this.b = b;
};
Color.prototype.toString = function toString() {
    return "rgb(" + this.r + ", " + this.g + ", " + this.b + ")";
};
console.log(String(new Color(30, 144, 255)));

New habit: Use class instead:

class Color  {
    constructor(r, g, b) {
        this.r = r;
        this.g = g;
        this.b = b;
    }
    toString() {
        return "rgb(" + this.r + ", " + this.g + ", " + this.b + ")";
    }
};
console.log(String(new Color(30, 144, 255)));

This doesn't mean you should start using class if you don't use constructor functions; constructor functions and their prototype property (in both ES5 and ES2015+) are just one way of using JavaScript's prototypical inheritance. But if you do use constructor functions, then given all the benefits of conciseness, expressiveness, and functionality, using class instead is clearly beneficial.

Object.setPrototypeOf

The primary way to do it is via Object.setPrototypeOf, which accepts the object to change and the prototype to give it. Here's an example:

const p1 = {
    greet: function() {
        console.log("p1 greet, name = " + this.name);
    }
};
const p2 = {
    greet: function() {
        console.log("p2 greet, name = " + this.name);
    }
};
const obj = Object.create(p1);
obj.name = "Joe";
obj.greet(); // p1 greet, name = Joe
Object.setPrototypeOf(obj, p2);
obj.greet(); // p2 greet, name = Joe

In that code, obj starts out using p1 as its prototype, so the first call to obj.greet() uses p1's greet and shows "p1 greet, name = Joe". Then the code changes the prototype of obj to use p2, so the second call to greet uses p2's greet and shows "p2 greet, name = Joe" instead.

Again, changing the prototype of an object after you've created it is unusual, and doing so may well de-optimize the object, making property lookup on it much slower. But if you absolutely have to do it, now you can via a standard mechanism.

The __proto__ Property on Browsers

In the browser environment, you can use an accessor property called __proto__ to get and set the prototype of an object, but don't do so in new code. Officially, it's not defined for JavaScript engines that aren't in a browser (although the engine may provide it anyway).

Here's an example of using __proto__; this is the same code as an example from the last section using Object.setPrototypeOf, the only change is the second-to-last line:

const p1 = {
    greet: function() {
        console.log("p1 greet, name = " + this.name);
    }
};
const p2 = {
    greet: function() {
        console.log("p2 greet, name = " + this.name);
    }
};
const obj = Object.create(p1);
obj.name = "Joe";
obj.greet(); // p1 greet, name = Joe
obj.__proto__ = p2;
obj.greet(); // p2 greet, name = Joe

__proto__ is an accessor property defined by Object.prototype, so the object you use it on has to inherit from Object.prototype (directly or indirectly) for you to use it. An object created via Object.create(null), for instance, doesn't have __proto__, and neither would any object that used that object as its prototype.

The __proto__ Literal Property Name on Browsers

__proto__ can also be used in an object literal to set the prototype of the resulting object:

const p = {
    hi() {
        console.log("hi");
    }
};
const obj = {
    __proto__: p
};
obj.hi(); // "hi"

This is explicit syntax, not a by-product of the __proto__ accessor property, and it only works when specified literally. For instance, you can't use a computed property name to do it:

const p = {
    hi() {
        console.log("hi");
    }
};
const name = "__proto__";
const obj = {
    [name]: p
};
obj.hi(); // TypeError: obj.hi is not a function

Again, don't use __proto__ in new code; use Object.create to create an object with the correct prototype in the first place, and use Object.getPrototypeOf and Object.setPrototypeOf if necessary to get or set the prototype afterward. That way, you don't have to worry about whether the code is running in a browser or not, and (in the case of the accessor property) whether the object inherits from Object.prototype or not.

Why Symbols?

We'll look at how you create and use Symbols in a moment, but first let's ask the question: Why is it so important to have guaranteed-unique values you can use as property keys?

Guaranteed-unique values are just generally useful (as the popularity of GUIDs demonstrates), but one key motivator for Symbols in JavaScript was that they made it possible to add several things to ES2015 that couldn't have been added otherwise. Several of the new features require looking for new properties on objects and using them if they exist. That wouldn’t be backward-compatible if the keys were strings.

For example, the toString function on Object.prototype creates a string in the form "[object XYZ]". For objects created by the built-in constructors like Date, the XYZ will be the name of the constructor ( "[object Date]", "[object Array]", etc.). But before ES2015, for instances created by your own constructors (or just plain objects), the string would just be "[object Object]".

In ES2015, TC39 wanted to be able to let the programmer decide what the XYZ should be with the default toString, by specifying an object property with the name that should be used. The problem is, there's no safe string name they could have picked for that property, because any string name they picked may have been used in the wild for a different purpose, so using it might break existing code. But they couldn't just start using the name of the constructor, either, because that would also break existing code that relied on seeing "[object Object]" for those objects. The new feature had to be opt-in.

Symbols to the rescue! Object.toString looks for a property identified by a Symbol, not a string. That means it can't conflict with any other property that may exist on objects defined before ES2015 (since Symbols didn't exist yet). Here's that property in action:

class Example1 {
}
class Example2 {
   get [Symbol.toStringTag]() {
     return "Example2";
   }
}
console.log(new Example1().toString()); // "[object Object]"
console.log(new Example2().toString()); // "[object Example2]"

The value of Symbol.toStringTag is a predefined well-known Symbol¹ that the Object.prototype.toString method looks for: when it would have returned "[object Object]" in ES5, in ES2015+ it looks for the Symbol.toStringTag property and if its value is a string, toString uses its value for the XYZ part of the resulting "[object XYZ]" string; if not, it uses Object as it used to. In the example, new Example1().toString() returned "[object Object]" because there was no property on the object with the appropriate Symbol name. But the call to new Example2().toString() returned "[object Example2]" because the property was there (inherited from Example.prototype) and had the value "Example2".

The common use case for toStringTag is classes as in the preceding example, but it works just as well for plain objects, which is useful if you prefer other types of object factories rather than constructor functions:

// Direct usage
const obj1 = {
    [Symbol.toStringTag]: "Nifty"
};
console.log(obj1.toString()); // "[object Nifty]"
 
// Via a prototype
const p = {
    [Symbol.toStringTag]: "Spiffy"
};
const obj2 = Object.create(p);
console.log(obj2.toString()); // "[object Spiffy]"

Enough of the why of Symbols, let's look at the how.

Creating and Using Symbols

You get a new, unique Symbol by calling the Symbol function. It's not a constructor—remember, Symbols are primitives—so you don't use new. Once you have your Symbol, you can add it to an object using computed property name notation during creation, or using brackets notation after creation:

const mySymbol = Symbol();
const obj = {
    [mySymbol]: 6                  // Computed property name
};
const anotherSymbol = Symbol();
obj[anotherSymbol] = 7;            // Brackets notation
console.log(obj[mySymbol]);        // 6
console.log(obj[anotherSymbol]);   // 7

As an aid to debugging, you can give a Symbol a description when creating it, by passing a string into Symbol:

const mySymbol = Symbol("my symbol");
console.log(mySymbol); // Symbol(my symbol)

In an environment where console.log shows a representation of the Symbol, the console.log of mySymbol in that code might show "Symbol(my symbol)", which is the string returned by toString on Symbols.

As of ES2019, a Symbol's description is available as a description property on the Symbol:

const mySymbol = Symbol("my symbol");
console.log(mySymbol.description); // "my symbol"

The description is purely a description, it has no other meaning. (Later, you'll see Symbol.for, in which the description is also used for another purpose.) The description is not the value of the Symbol, and two different Symbols can have the same description but still be different Symbols:

const a = Symbol("my symbol");
console.log(a);       // Symbol(my symbol)
const b = Symbol("my symbol");
console.log(b);       // Symbol(my symbol)
console.log(a === b); // false
const obj = {
    [a]: 6,
    [b]: 7
};
console.log(obj[a]); // 6
console.log(obj[b]); // 7

Properties keyed by Symbols rather than strings are not included in for-in loops or the array returned by Object.keys, even when they're enumerable properties (and own² properties, in the case of Object.keys).

Symbols Are Not for Privacy

One common misconception about Symbols is that they're for private properties. For instance, consider this code:

const everUpward = (() => {
    const count = Symbol("count");
    return {
        [count]: 0,
        increment() {
            return ++this[count];
        },
        get() {
            return this[count];
        }
    };
})();
console.log(everUpward.get());            // 0
everUpward.increment();
console.log(everUpward.get());            // 1
console.log(everUpward["count"]);         // undefined
console.log(everUpward[Symbol("count")]); // undefined

If you don't have access to the Symbol stored in count, you can't get the property, right? It's not the "count" property, after all, and the count constant is private to the function in which it's declared.

No, the Symbol stored in count isn't private (even though the constant referring to it is) because Symbols are discoverable. For instance, you can get the Symbols an object uses via the aptly named Object.getOwnPropertySymbols. Since they're discoverable, Symbols don't provide any privacy for properties. A bit of obscurity, perhaps, particularly if you don't give them descriptions; but no privacy. Truly private properties will be introduced in ES2020 or later via an entirely different mechanism (see Chapter 18), or you can use a WeakMap (Chapter 12) to hold truly private information for an object.

So why the misconception? Partially because of the path Symbols took on their way to being added to JavaScript: they started life as “private Name objects” and were indeed originally expected to be used as a mechanism for creating private properties on objects. Over time, their name changed, they became primitives, and using them for private properties didn't pan out, but having a guaranteed-unique identifier turned out to be quite useful, so Symbols were kept.

Global Symbols

When you call Symbol to create your Symbol, only your code knows about it unless you make it accessible to other code somehow (for instance, by making it the key of a property on an object). Normally that's what you want. But a complication can arise, particularly for library authors, especially when you need to use Symbols across realms.

A realm is the overall container in which a bit of code lives, consisting of a global environment, the intrinsics for that environment (Array, Object, Date, etc.), all the code loaded into that environment, and other bits of state and such. If you think of a browser, the realm your code lives in is the window for the page you've included it in and all of that window's associated stuff (pardon the technical jargon).

Your code doesn't only have access to its own realm, though, it can also get access to things in other realms: a child window has a different realm from its parent window, a web worker has its own realm distinct from the realm that created it, etc. But in many cases, code in those realms can pass objects between the realms. That's not a problem, but if code in two different realms needs to share access to a property identified by a Symbol, then the Symbol needs to be shared as well. This is where global Symbols come in.

For instance, suppose you're writing a class called BarkCounter, and BarkCounter stores information on objects using a Symbol. See the fairly silly example in Listing 5-1.

Instances of the BarkCounter class count the number of times you call bark on them (I told you it was silly). They respond to a bark call by incrementing the count and returning the new value. They store the count of bark calls in a property keyed with the Symbol stored in the barks constant. If you pass an object into the BarkCounter constructor that has a property keyed with that Symbol, it copies the count of barks from that instance; otherwise, it starts at 0. You can ask it to show the number of barks in the console, but you can't ask it to give you the number of barks.

Here's BarkCounter in action:

const b1 = new BarkCounter();
b1.bark();
b1.bark();
b1.showBarks("b1");           // b1: Barks = 2
const b2 = new BarkCounter(b1);
b2.showBarks("b2");           // b2: Barks = 2

Notice that that code successfully copied the barks count from b1 to b2. That's because the code creating b2 passes b1 into the same BarkCounter constructor that created it, so the same Symbol is used when looking up the number of barks on b1.

Let's look at a cross-realm example by using BarkCounter in a main window and in an iframe, passing an instance of BarkCounter from the main window to the iframe. See Listings 5-2 and 5-3.

barkcounter-main-1.html loads an iframe, and once it's loaded creates an instance of BarkCounter ( b1) and passes it to a global function in the iframe called useBarkCounter. The main window and the iframe are different realms.

barkcounter-frame-1.html's useBarkCounter receives the BarkCounter instance and, like the code shown earlier, passes it into the BarkCounter constructor, which tries to copy the number of barks from b1 into the new instance.

Copy those files along with barkcounter-version-1.js to your local web server, then in your browser open the developer tools console and load barkcounter-main-1.html. The output is:

The barks property didn't get copied. (If it had, that last line would show 2, not 0.) Why not?

The problem is that the copy of BarkCounter loaded into the main window is separate from the copy of BarkCounter loaded in the iframe window, and they both create their own barks Symbol. Those Symbols are, by definition, not equal, so when the BarkCounter constructor tried to get the number of barks from b1, it didn't see any and used 0 as its starting point.

Ideally, all loaded copies of BarkCounter should share the same Symbol for barks. You could do that by passing the Symbol from the main window to the iframe along with b1, but that gets complicated quickly. In this particular case you could also loop through the properties of b1 and see if any were named with a Symbol that had the appropriate description, but that doesn't work in all situations (not least if the Symbol doesn't have a description, or a different Symbol has the same description).

Instead, you can do it by publishing the Symbol to the global Symbol registry associated with a string key by using the Symbol.for function instead of the Symbol function. It's a small modification to the BarkCounter code, changing this line:

const barks = Symbol("nifty-barks");

to this:

const barks = Symbol.for("nifty-barks");

Symbol.for checks to see if there's a Symbol in the global registry for the key you provide and returns it if there is; if not, it creates a new Symbol (using the key as the description), adds it to the registry, and returns that new Symbol.

That change is in the “–2” versions of the files ( barkcounter-version-2.js, barkcounter-main-2.html, and barkcounter-frame-2.html). Load those onto your local server and run them in the browser, and you'll see:

Both copies of BarkCounter use the same global Symbol: the main file's call to Symbol.for created and registered it, then the frame file's Symbol.for call retrieved the registered Symbol. So copying the number of barks from b1 to b2 works, because both BarkCounter constructors use the same Symbol for the property.

As with global variables, avoid global Symbols when you have other alternatives, but use them when they're the right thing. If you do use them, be sure to use a sufficiently unique name to avoid conflicts with other uses, or with ones that may be defined in future versions of the specification.

You'll see a particularly handy use of global Symbols in Chapter 6 when learning about iterators and iterables.

One final thing about global Symbols: if you need to know if a Symbol is in the global Symbol registry, and if so what key it's assigned to, you can use Symbol.keyFor:

const s = Symbol.for("my-nifty-symbol");
const key = Symbol.keyFor(s);
console.log(key); // "my-nifty-symbol"

Symbol.keyFor returns undefined if the Symbol you pass to it isn't in the global registry.

Well-Known Symbols

The specification defines several well-known Symbols that get used by various operations in the language. These Symbols are accessible via properties on the Symbol function. You saw one of these in Chapter 4 (Symbol.species) and another earlier in this chapter (Symbol.toStringTag). Here's a list of all of the well-known Symbols in ES2015–ES2018 (ES2019 didn't add any and it doesn't look like ES2020 will) and the chapter they're covered in:

• Symbol.asyncIterator (Chapter 9)
• Symbol.hasInstance (Chapter 17)
• Symbol.isConcatSpreadable (Chapter 17)
• Symbol.iterator (Chapter 6)
• Symbol.match (Chapter 10)
• Symbol.replace (Chapter 10)
• Symbol.search (Chapter 10)
• Symbol.species (Chapter 4)
• Symbol.split (Chapter 10)
• Symbol.toPrimitive (Chapter 5)
• Symbol.toStringTag (Chapter 5)
• Symbol.unscopables (Chapter 17)

All currently defined well-known Symbols are also global (so they're shared across realms), although the spec leaves the door open to having some that aren't global in the future.

Object.assign

Object.assign is JavaScript's version of the common “extend” function that copies properties from one or more source objects into a target object. Suppose you have a function that presents a message box to a user that supports the options title, text, icon, className, and buttons, where all of them (and even the options object itself) are optional.³ That's a fair number of options. You could accept them as parameters to the function, but doing that raises some issues:

• You have to remember the order when writing calls to the function (though your IDE may be able to help).
• If most of them are optional, the code in the function that figures out which options the caller has supplied and which they omitted can quickly become quite complex.
• If several have the same type (most of the options in this example are strings), it can be not just complex, but impossible for the function code to determine which ones the caller supplied.

Although you could use the default parameter values feature you learned about in Chapter 3 and pass undefined for the ones you want defaults for, that's quite awkward.

In this situation, it's common to use an object with properties for the options, instead of discrete parameters. To make some of those properties optional, the usual approach is to copy the passed-in object and mix in defaults from a defaults object. In ES5 without any helper functions, it looks something like this, which is fairly cumbersome:

function showDialog(opts) {
    var options = {};
    var optionName;
    var hasOwn = Object.prototype.hasOwnProperty;
    for (optionName in defaultOptions) {
        if (hasOwn.call(defaultOptions, optionName)) {
            options[optionName] = defaultOptions[optionName];
        }
    }
    if (opts) { // remember that `opts` is optional
        for (optionName in opts) {
            if (hasOwn.call(opts, optionName)) {
                options[optionName] = opts[optionName];
            }
        }
    }
    // (Use `options.title`, `options.text`, etc.)
}

This is so common and so cumbersome that the “extend” function became common in many toolkits (jQuery, Underscore/Lodash, etc.) and became an idiom in JavaScript. The traditional “extend” accepts a target object and then any number of source objects, copying own, enumerable properties from the source objects to the target object, and then returning the target object as its return value.

Which is what Object.assign does. Here's that showDialog function using Object.assign rather than using inline code (and switching to const, although it's not necessary):

function showDialog(opts) {
    const options = Object.assign({}, defaultOptions, opts);
    // (Use `options.title`, `options.text`, etc.)
}

Much cleaner! That creates an object and passes it as the first argument (the “target” object), followed by the source objects to copy, then remembers that object (which is the return value) in options.

Object.assign works through the source objects ( defaultOptions and opts in the example) in order left-to-right, so the last one “wins” when more than one of them has a value for the same property (since its value overwrites any previous ones).That means the final options object will have options from opts for the options opts has, or defaults from defaultOptions for the ones opts doesn't have.

Object.assign skips arguments that are null or undefined, so the showDialog code doesn't have to do anything to handle the case where opts wasn't provided by the caller at all.

Like the “extend” functions that inspired it, Object.assign only copies own, enumerable properties from the source objects, not inherited ones, and not ones marked non-enumerable, just like the loops in the cumbersome version did. It returns the target object. However, it copies properties keyed by Symbols as well as those keyed by strings, which the for-in example earlier would not ( for-in only loops through the string-named properties of an object).

In Chapter 7 you'll learn a different way you can solve this specific problem using destructuring parameters, and later in this chapter you'll learn about ES2018's property spread, which works a lot like Object.assign but doesn't quite replace it (as you'll learn later).

Object.is

ES2015's Object.is compares two values according to the specification's SameValue abstract operation. The SameValue operation is like === (strict equality) except:

• NaN is equal to itself (whereas NaN === NaN is false)
• Positive zero ( +0) and negative zero ( -0) are not equal to each other (whereas +0 === -0 is true)

So:

console.log(Object.is(+0, -0));   // false
console.log(Object.is(NaN, NaN)); // true

and for everything else, it's just like ===.

Object.values

ES5 added Object.keys, which gives you an array of the names of the object's own, enumerable properties whose keys are strings (not Symbols). Object.values, added in ES2017, is the logical counterpart: it provides an array of the values of those same properties.

const obj = {
    a: 1,
    b: 2,
    c: 3
};
console.log(Object.values(obj)); // [1, 2, 3]

The values of inherited properties, non-enumerable properties, and properties keyed by Symbols are not included.

Object.entries

Rounding out the list of ways of accessing the own, enumerable string-keyed properties, ES2017 also added Object.entries, which gives you an array of [name, value] arrays:

const obj = {
    a: 1,
    b: 2,
    c: 3
};
console.log(Object.entries(obj)); // [["a", 1], ["b", 2], ["c", 3]]

Object.entries makes for quite a powerful tool, particularly in combination with the for-of loop you'll learn about in Chapter 6; destructuring, which you'll learn about in Chapter 7; and Object.fromEntries, which you'll learn about … now!

Object.fromEntries

Object.fromEntries is a utility function added in ES2019 that accepts a list (any iterable) of key/value pairs and creates an object from them:

const obj = Object.fromEntries([
    ["a", 1],
    ["b", 2],
    ["c", 3]
]);
console.log(obj);
// => {a: 1, b: 2, c: 3}

fromEntries is the converse of Object.entries. It's also handy for turning a Map (Chapter 12) into an object, since Map.prototype.entries returns the exact type of list Object.fromEntries expects.

Object.getOwnPropertySymbols

ES2015’s Object.getOwnPropertySymbols is the counterpoint to the ES5 method Object.getOwnPropertyNames but, as the method name suggests, it returns an array of Symbols for the object’s own Symbol-named properties (whereas Object.getOwnPropertyNames returns an array of strings for the string-named ones).

Object.getOwnPropertyDescriptors

ES2017's Object.getOwnPropertyDescriptors returns an object with property descriptors for all of the object's own properties (including non-enumerable ones and ones keyed with Symbols rather than strings).

One use for it is passing the object it returns into Object.defineProperties on another object, to copy the definitions to that object:

const s = Symbol("example");
const o1 = {
    // A property named with a Symbol
    [s]: "one",
    // An accessor property
    get example() {
        return this[s];
    },
    set example(value) {
        this[s] = value;
    },
    // A data property
    data: "value"
};
// A non-enumerable property
Object.defineProperty(o1, "nonEnum", {
    value: 42,
    writable: true,
    configurable: true
});
// Copy those properties to a new object
const descriptors = Object.getOwnPropertyDescriptors(o1);
const o2 = Object.defineProperties({}, descriptors);
console.log(o2.example); // "one"
o2.example = "updated";
console.log(o2[s]);      // "updated", the accessor property wrote to the [s] prop
console.log(o2.nonEnum); // 42
console.log(o2.data);    // "value"

Contrast this with using Object.assign in that same situation, which wouldn't copy the accessor property as an accessor property; instead, it would copy the value returned by the accessor property as of when Object.assign was called. It also wouldn't copy the non-enumerable property.

Use Computed Syntax When Creating Properties with Dynamic Names

Old habit: Creating properties whose names are determined at runtime as a second step after creating the object:

let name = "answer";
let obj = {};
obj[name] = 42;
console.log(obj[name]); // 42

New habit: Use computed property names instead:

let name = "answer";
let obj = {
    [name]: 42
};
console.log(obj[name]); // 42

Use Shorthand Syntax When Initializing a Property from a Variable with the Same Name

Old habit: Providing the name of a property even when the property's value is coming from an in-scope identifier (for instance, a variable) with the same name:

function getMinMax() {
    let min, max;
    // …
    return {min: min, max: max};
}

New habit: Use shorthand property syntax instead:

function getMinMax() {
    let min, max;
    // …
    return {min, max};
}

Use Object.assign instead of Custom “Extend” Functions or Copying All Properties Explicitly

Old habit: Using a custom extend (or similar) function or laboriously copying all of the (own, enumerable) properties from one object to another existing object with a loop.

New habit: Use Object.assign instead.

Use Spread Syntax When Creating a New Object Based on an Existing Object's Properties

Old habit: Using a custom extend or Object.assign to create a new object based on an existing object's properties:

const s1 = {a: 1, b: 2};
const s2 = {a: "updated", c: 3};
const dest = Object.assign({}, s1, s2);
console.log(dest); // {"a": "updated", "b": 2, "c": 3}

New habit: Use property spread syntax:

const s1 = {a: 1, b: 2};
const s2 = {a: "updated", c: 3};
const dest = {…s1, …s2};
console.log(dest); // {"a": "updated", "b": 2, "c": 3}

Use Symbol to Avoid Name Collision

Old habit: Using obscure string names for properties in an attempt to avoid colliding with names outside your control.

New habit: Use Symbols for those instead.

Use Object.getPrototypeOf/setPrototypeOf Instead of __proto__

Old habit: Getting or setting the prototype of an object via the previously non-standard extension __proto__.

New habit: Use the standard Object.getPrototypeOf and Object.setPrototypeOf instead (even though __proto__ is now standardized on web browsers).

Use Method Syntax for Methods

Old habit: Using a property initializer for functions that you intend to be methods of the object:

const obj = {
    example: function() {
        // …
    }
};

New habit: Use method syntax instead:

const obj = {
    example() {
        // …
    }
};

Just remember that if you use super, the method will have a link to its original object, so if you copy it to another object, it will continue to use the prototype of its original object, not the new one. If you don't use super (and don't use eval), a good JavaScript engine will optimize that link away.

Iterators and Iterables

Many languages have some kind of “for each” construct for looping through the entries of an array or list or other collection object. For years, JavaScript only had the for-in loop, which isn't a general-purpose tool (it's just for looping through the properties of an object). The new Iterator and Iterable “interfaces” (see note) and new language constructs that use them change that.

An iterator is an object with a next method; each time you call next, it returns the next value (if any) in the sequence it represents, and a flag saying whether it's done.

An iterable is an object with a standard method for getting an iterator for its contents. All list- or collection-style objects in the JavaScript standard library are iterable—arrays, strings, typed arrays (Chapter 11), Maps (Chapter 12), and Sets (Chapter 12). Plain objects are not iterable by default.

Let's examine the basics.

The for-of Loop: Using an Iterator Implicitly

You can get and use the iterator directly, but it's more common to use it indirectly, for instance by using the new for-of loop. for-of gets an iterator from the iterable and uses it to loop through the iterable's contents.

Arrays are iterable, so let's look at looping through an array with for-of:

const a = ["a", "b", "c"];
for (const value of a) {
    console.log(value);
}
// =>
// "a"
// "b"
// "c"

Running that code shows "a", then "b", then "c": the for-of statement gets an iterator from the array behind the scenes, then uses it to loop through the values, making each value available as value within the loop body.

Note that for-of is different from for-in. If you use for-in on that array, you get "0", then "1", then "2"—the names of the properties for the array's entries. for-of provides the values of the entries, as defined by the array's iterator. This also means that for-of will only give you values of the array's entries, not the values of any other properties you may have added to it (since arrays are objects). Compare:

const a = ["a", "b", "c"];
a.extra = "extra property";
for (const value of a) {
    console.log(value);
}
// The above produces "a", "b", and "c"
 
for (const key in a) {
    console.log(key);
}
// The above produces "0", "1", "2", and "extra"

Did you notice the const value in the examples so far? You'll remember from Chapter 2 that when you declare a variable in a for loop with let, a new variable is created for each iteration of the loop. That's true in a for-of or for-in loop as well. But in for-of/ for-in, since the variable's value is never modified by the loop statement,¹ you can declare it with const if you like. ( let or var would also be fine, with the usual caveats on the scope of var. If you want to change the value in the loop body, use let.)

for-of is very convenient and you'll use it a lot. But because it does everything for you, it doesn't help you understand the details of iterators much. How does it get the iterator? How does it use it? Let's look more closely…

Using an Iterator Explicitly

Suppose you wanted to use the iterator explicitly. You'd do that like this:

const a = ["a", "b", "c"];
const it = a[Symbol.iterator](); // Step 1
let result = it.next();          // Step 2
while (!result.done) {           // Step 3.a
    console.log(result.value);   // Step 3.b
    result = it.next();          // Step 3.c
}

Let's look at each step of that.

Step 1 gets an iterator from the array. Iterables provide a method for this whose name is the well-known Symbol Symbol.iterator (you learned about well-known Symbols in Chapter 5). You call that method to get the iterator:

const it = a[Symbol.iterator]();

Step 2 calls the iterator's next function to get a result object. A result object is an object conforming to the IteratorResult interface, which essentially means it has a done property indicating whether the iterator is done iterating, and a value property containing the value for the current iteration:

let result = it.next();

Step 3 performs the loop, using a series of sub-steps. (a) while the done property on the result object is false (or at least falsy²), it (b) uses the value, then (c) calls next again:

while (!result.done) {           // Step 3.a
    console.log(result.value);   // Step 3.b
    result = it.next();          // Step 3.c
}

You've probably noted that coding the result = it.next() call in two places introduces a minor code maintenance hazard. That's one reason to use for-of or other automatic constructs where possible. But you could also do the call in the while loop's condition expression:

const a = ["a", "b", "c"];
const it = a[Symbol.iterator]();
let result;
while (!(result = it.next()).done) {
    console.log(result.value);
}

Now it's in just one place.

Although a result object is defined as having a done property and a value property, done is optional if its value would be false, and value is optional if its value would be undefined.

Those are the basic steps of using an iterator.

Stopping Iteration Early

When you're using an iterator, you may have reason to stop early. For instance, if you're searching through an iterator's sequence for something, you'd probably stop when you found it. But if you just stop calling next, the iterator doesn't know you're done with it. It may well be holding onto resources it could let go of if you're done with it. It will let go of them eventually anyway when it gets garbage collected (unless they're something that garbage collection doesn't handle), but iterators have a way to be more proactive: an optional method called return. It tells the iterator you're done with it, and that it should clean up any resources it would normally clean up once it had reached the end of the sequence.

Since it's optional, you need to test for it before you call it. Here's an example:

const a = ["a", "b", "c", "d"];
const it = a[Symbol.iterator]();
let result;
while (!(result = it.next()).done) {
    if (result.value === "c") {
        if (it.return) {
            it.return();
        }
        break;
    }
}

(In Chapter 19 you'll learn about optional chaining, which would let you write that more concisely. Instead of the if, you could just write it.return?.(); See that chapter for details.)

The specification says that return must return a result object (like next does) which “typically” has done set to true, and that if you pass an argument into return, the result object's value should “typically” be that argument's value, but it also says that requirement is not enforced (and later you'll see ways to break it). Consequently, you probably don't want to count on either behavior. Iterators provided by the JavaScript runtime itself will behave that way if they have a return, but you can't count on iterators from third-party libraries doing so.

You may be wondering how you call return on the iterator if you're using for-of, since you don't have an explicit reference to the iterator:

const a = ["a", "b", "c", "d"];
for (const value of a) {
    if (value === "c") {
        if (???.return) {
            ???.return();
        }
        break;
    }
}

The answer is: you don't have to, because for-of does it for you when you exit the loop without completing it (that is, by using break, or by returning, or throwing an error). So you don't have to worry about it at all:

const a = ["a", "b", "c", "d"];
for (const value of a) {
    if (value === "c") {
        break; // This is just fine, it calls the iterator's `return`
    }
}

There's a second optional method: throw. You won't normally use it with simple iterators, and for-of never calls it (even if you throw an error from the body of the for-of). You'll learn about throw later in this chapter where you learn about generator functions.

Iterator Prototype Objects

All iterator objects provided by the JavaScript runtime inherit from a prototype object providing the appropriate next method for the iterable you got it from. For instance, array iterators inherit from an array iterator prototype object, which provides the appropriate next method for arrays. That array iterator prototype is known in the specification as %ArrayIteratorPrototype%. String iterators inherit from %StringIteratorPrototype%, Map (Chapter 12) iterators inherit from %MapIteratorPrototype%, etc.

All of these iterator prototypes have an underlying prototype, which the spec creatively calls %IteratorPrototype%. It defines just one property, and the property it defines may seem a bit odd, since it isn't part of the Iterator interface. It defines a Symbol.iterator method that returns this; effectively:

const iteratorPrototype = { // (This name is conceptual, not actual)
    [Symbol.iterator]() {
        return this;
    }
};

You're probably thinking, “But wait, isn't that for iterables? Why would you have it on an iterator instead?!”

The answers are: “Yes,” and, “So that they're also iterable.” Making an iterator iterable makes it possible to pass the iterator to for-of or other constructs expecting an iterable. For instance, if you wanted to loop over all entries but the first in an array without using slice to get a subset of the array:

const a = ["one", "two", "three", "four"];
const it = a[Symbol.iterator]();
it.next();
for (const value of it) {
    console.log(value);
}
// =>
// "two"
// "three"
// "four"

You'll learn more about that in the “Iterable Iterators” section later in this chapter, but I wanted to explain the seemingly odd method provided by %IteratorPrototype%.

Mostly, you won't need to care about these prototype objects. However, there are at least two situations where you might want to access these prototypes:

1. If you want to add functionality to the iterators
2. If you were implementing an iterator manually (see the next section), which you typically won't do

You'll see #2 in the next section. Let’s look at #1: adding functionality.

Before we do, note that all the usual caveats about modifying the prototypes of built-in objects apply:

1. Ensure that any properties/methods you add are non-enumerable.
2. Ensure that they have names that are unlikely to conflict with features that may be added in the future. You might consider using Symbols.
3. In the vast majority of cases, library code (rather than application or page-specific code) should avoid prototype modifications entirely.

With all of that said, let's add a method to all iterators (or at least, ones inheriting from %IteratorPrototype%): finding the first entry that matches a condition, like the find method on arrays. We won't call it find, because that would violate caveat (B), so we'll call it myFind. Just like the find on arrays, it'll accept a callback and optional argument to use as this when calling the callback, and return the first result object for which the callback returns a truthy value, or the last result object (which will have done = true) if it never does.

To add a method to %IteratorPrototype%, first we have to get a reference to it. There's no public global or property that refers directly to it, but we know from the specification that the prototype of an array iterator is %ArrayIteratorPrototype%, and we know (also from the spec) that its prototype is %IteratorPrototype%. So we can get %IteratorPrototype% by creating an array, getting an iterator for it, and getting its prototype's prototype:

const iteratorPrototype = Object.getPrototypeOf(
    Object.getPrototypeOf([][Symbol.iterator]())
);

The specification even has a note saying exactly that.

Now that we have a reference to it, we can add our method to it. Normally, methods on prototypes are non-enumerable, but are writable and configurable, so we'll use Object.defineProperty. The method itself is quite simple: call next until the callback returns a truthy value, or we run out of values.

Object.defineProperty(iteratorPrototype, "myFind", {
    value(callback, thisArg) {
        let result;
        while (!(result = this.next()).done) {
            if (callback.call(thisArg, result.value)) {
                break;
            }
        }
        return result;
    },
    writable: true,
    configurable: true
});

Run the code in Listing 6-1 to see it in action. Once the new method is defined, the example uses it to find entries in an array of strings that have the letter “e” in them.

An extension like this is only useful when the iterator is being used explicitly, though. Later when you learn about generator functions, you'll learn a simpler way to do this.

Making Something Iterable

You've seen that you get an iterator by calling an iterable's Symbol.iterator method. And you've seen that an iterator is an object with, at minimum, a next method that returns the “next” result object with value and done. To make something iterable, you simply provide that Symbol.iterator method.

Let's create a pseudo-array with just a plain object:

const a = {
    0: "a",
    1: "b",
    2: "c",
    length: 3
};

That object is not iterable, because plain objects by default are not iterable:

for (const value of a) { // TypeError: a is not iterable
    console.log(value);
}

To make it iterable, you need to add a function as its Symbol.iterator property:

a[Symbol.iterator] = /* function goes here */;

The next step is to write the function, having it return an iterator object. Later in this chapter you'll learn about generator functions, which you'll probably use most of the time to implement iterators. But since generator functions do most of the work for you, they hide some of the details, so let's do it manually first.

As a first approach, you'd probably implement the iterator for this pseudo-array object something like this:

// Take 1
a[Symbol.iterator] = function() {
    let index = 0;
    return {
        next: () => {
            if (index < this.length) {
                return {value: this[index++], done: false};
            }
            return {value: undefined, done: true};
        }
    };
};

(Note that next is an arrow function. It's important that it uses the this that the Symbol.iterator method was called with, regardless of how it's called, so that this refers to the pseudo-array. Alternatively, you could use method syntax and use a rather than this in both places it's used, since next closes over a in this example. But if you were doing this on a class and needed to access instance information like length, you wouldn't usually have anything but this to close over, so an arrow function makes sense.)

That version is okay, but it doesn't make the iterator inherit from %IteratorPrototype%, like all iterators you get from the JavaScript runtime do. So if you add to %IteratorPrototype% as we did earlier with myFind, this iterator won't have the addition. It also doesn't inherit the prototype property that makes iterators iterable. Let's make it inherit from %IteratorPrototype%:

// Take 2
a[Symbol.iterator] = function() {
    let index = 0;
    const itPrototype = Object.getPrototypeOf(
        Object.getPrototypeOf([][Symbol.iterator]())
    );
    const it = Object.assign(Object.create(itPrototype), {
        next: () => {
            if (index < this.length) {
                return {value: this[index++], done: false};
            }
            return {value: undefined, done: true};
        }
    });
    return it;
};

If you write these manual iterators a lot, you'll probably want a reusable function to do most of that for you which you just pass your next implementation into. But again, you'll probably use generator functions instead. (We'll get to that section soon, really.)

Try running the code in Listing 6-2.

That example is just for a single object, but often you'll want to define a class of objects that are all iterable. The typical way to do that is by putting the Symbol.iterator function on a prototype object that the class of objects uses. Let's look at an example using the class syntax you learned in Chapter 4: a very simple LinkedList class that's iterable. See Listing 6-3.

It's fundamentally the same as the previous iterator implementation; it's just defined on the prototype rather than directly on the object. Also, since next doesn't use this (unlike the pseudo-array example, this doesn't need any instance-specific information; each node links to the next), it can be defined using method syntax rather than as a property referring to an arrow function.

Iterable Iterators

Earlier you learned that all iterators inheriting from %IteratorPrototype% are also iterable, because %IteratorPrototype% provides a Symbol.iterator method that does return this—simply returning the iterator it was called on. There are various reasons to make iterators iterable:

As described earlier, you might want to skip or specially handle an entry or some entries, then process the rest with a for-of loop or other mechanism that consumes an iterable (rather than an iterator).

Or suppose you want to provide an iterator without any iterable object, for instance as the return value of a function. The caller may want to use for-of or similar on it. Making it iterable lets them do that.

Here's an example of a function returning an iterator that's also iterable. The iterator provides the parent of the DOM element we pass it (and then that parent's parent, etc., until it runs out of parents):

// Example that doesn't inherit from %IteratorPrototype% (if it did,
// we wouldn't need to implement the [Symbol.iterator] function)
function parents(element) {
    return {
        next() {
            element = element && element.parentNode;
            if (element && element.nodeType === Node.ELEMENT_NODE) {
                return {value: element};
            }
            return {done: true};
        },
        // Makes this iterator an iterable
        [Symbol.iterator]() {
            return this;
        }
    };
}

You wouldn't really write the function like that, of course, because firstly, you'd probably write a generator function instead (we'll get there, I promise!), and secondly, even if you didn't, you'd have the iterator inherit from %IteratorPrototype% instead of implementing Symbol.iterator yourself. But try it out with the page in Listing 6-4. Then, try modifying it to make the iterator inherit from %IteratorPrototype% instead of implementing the Symbol.iterator method yourself.

Iterable Spread Syntax

Iterable spread syntax provides a way to consume an iterable by spreading out its result values as discrete values when calling a function or creating an array. (In Chapter 5 you learned about another kind of spread, property spread syntax, which is similar but different, and only used in object literals.)

Spread syntax for arrays and other iterables was introduced in ES2015. Let's look at an example: finding the lowest number in an array of numbers. You could write a loop to do it, but you know that Math.min accepts a variable number of arguments and returns the lowest of them. For example:

console.log(Math.min(27, 14, 12, 64)); // 12

So you could use that if you had discrete numbers to pass in. But if you have an array of numbers:

// ES5
var a = [27, 14, 12, 64];

then how do you supply them to Math.min as discrete arguments? The old pre-ES2015 way was to use Function.prototype.apply. It was long-winded and odd-looking:

// ES5
var a = [27, 14, 12, 64];
console.log(Math.min.apply(Math, a)); // 12

With spread syntax, though, you can spread out the array as discrete arguments instead:

const a = [27, 14, 12, 64];
console.log(Math.min(
…
a)); // 12

As you can see, spread uses the ellipsis (three dots in a row, like the rest parameter you learned about in Chapter 3 and property spread you learned about in Chapter 5).

You can use spread syntax anywhere in the argument list. For instance, if you had two numbers in individual variables as well as the list of numbers in the array:

const num1 = 16;
const num2 = 50;
const a = [27, 14, 12, 64];

and you wanted to get the minimum value of all of them, you could do any of these:

console.log(Math.min(num1, num2, …a)); // Math.min(16, 50, 27, 14, 12, 64) == 12
console.log(Math.min(num1, …a, num2)); // Math.min(16, 27, 14, 12, 64, 50) == 12
console.log(Math.min(…a, num1, num2)); // Math.min(27, 14, 12, 64, 16, 50) == 12

Where you put the spread changes the order of the arguments passed to Math.max. It happens that Math.max doesn't care about the order, but other functions that accept variable parameter lists may well care (for instance, the push method of arrays pushes the arguments you give it into the array in the order you give them).

The other use of iterable spread syntax is expanding an array (or other iterable) inside an array literal:

const defaultItems = ["a", "b", "c"];
function example(items) {
    const allItems = […items, …defaultItems];
    console.log(allItems);
}
example([1, 2, 3]); // 1, 2, 3, "a", "b", "c"

Note that, again, order matters. If you put defaultItems first, then items, you'd get a different result:

const defaultItems = ["a", "b", "c"];
function example(items) {
    const allItems = […defaultItems, …items];
    console.log(allItems);
}
example([1, 2, 3]); // "a", "b", "c", 1, 2, 3

Iterators, for-of, and the DOM

The majority use of JavaScript is, of course, on web browsers or applications built with web technologies. The DOM has various collection objects, such as the NodeList returned by querySelectorAll or the older HTMLCollection returned by getElementsByTagName and other older methods. You're probably wondering, “Can I use for-of on those? Are they iterable?”

NodeList is on modern, cutting-edge browsers (up-to-date Chrome, Firefox, Edge, and Safari), and HTMLCollection is too on all of those except the pre-Chromium version of Edge. The WHAT-WG DOM specification marks NodeList as iterable, but not HTMLCollection, so the old version of Edge is in line with the specification while the others add this feature to HTMLCollection despite it not being specified.

Listing 6-5 shows a (silly) example iterating through a NodeList from querySelectorAll.

You probably don't need to convert DOM collections to arrays nearly as much now as you had to in the past. For instance, you used to have to convert a DOM collection to an array to use forEach on it; on modern browsers, that's no longer necessary, because the collections have forEach now. But if you have a specific need for an array (perhaps you want to use some advanced array methods), you can use iterable spread to convert the DOM collection to one. This converts a NodeList into an array, for instance:

const niftyLinkArray = […document.querySelectorAll("div.nifty> a")];

If you're transpiling for use on older browsers, you'll probably need a polyfill to make iteration work for arrays, and that's true for DOM collections as well. Typically, the transpiler you're using will offer polyfills for iteration for Array.prototype at least, and possibly NodeList.prototype as well. They may be optional ones you need to specifically enable. If your preferred polyfill only handles Array.prototype and not the DOM collections, you can apply the Array.prototype one to the DOM collections. (The same with Array.prototype.forEach.) See Listing 6-6. (It's written in ES5 so it can be used directly even in older environments. You'd include it in your bundle after any polyfills you're using.) But double-check first that the tool you're using doesn't handle these for you; it's generally better to use curated polyfills rather than rolling your own.

A Basic Generator Function Just Producing Values

We'll start with a very basic generator function with only a one-way flow of information: producing values. See Listing 6-7.

When you run Listing 6-7, it shows the numbers 1 through 3 in the console:

1. The code calls simple, getting a generator object, then gives that object to for-of.
2. for-of asks the generator object for an iterator. The generator object returns itself as the iterator (generator objects inherit indirectly from %IteratorPrototype% and so they have the “ return this” Symbol.iterator method it provides).
3. for-of uses the generator object's next method to get the values in the loop and pass each of them to console.log.

There are some new things in that code.

First, note the * after the function keyword. That's what makes it a generator function. You can have whitespace after function and before the * if you like, it's purely a matter of style.

Second, note the new keyword yield. It marks where a generator function seemingly pauses and then resumes. The value you put after it (if any) is the value the generator produces at that point. So in Listing 6-7, the yield n; produces 1, then 2, then 3, and then it's done. The code using the generator sees those via the for-of (because generators are also iterators).

Using Generator Functions to Create Iterators

Since generator functions create generators, and generators are a form of iterator, you can use generator function syntax to write your own iterator—and doing so is much simpler and more concise than all of that code you saw earlier creating the iterator object with the right prototype and implementing the next method. Let's look again at the earlier implementation of an example iterator; see Listing 6-8 (which repeats Listing 6-2 from earlier).

Compare that to Listing 6-9, which does the same thing with a generator function.

Much simpler, much clearer (once you know what yield means). The generator function does all the heavy lifting for you. You write the logic rather than worrying about the plumbing details.

That example uses property definition syntax:

[Symbol.iterator]: function*() {

but it could have used method syntax as well, since generator functions can be methods. Let's look at that …

Generator Functions As Methods

Generator functions can be methods, with all the features of methods (such as being able to use super). Earlier you saw an example of a very simple iterable LinkedList class, with a manually implemented iterator. Let's revisit that class implementing the iterator with a generator function instead, using method syntax. See Listing 6-10.

Notice how the generator method is declared: you put an asterisk (*) in front of the method name, just like the asterisk in front of the function name after the keyword function. (In this example the method name is using the computed name syntax you learned about in Chapter 4, but it could be a simple name if we weren’t defining a Symbol-named method.) This mirrors the syntax of getter and setter method declarations, using * where get or set would be. Also notice how much simpler, clearer, and more concise the generator version is than the manually coded one.

Using a Generator Directly

So far you've seen consuming the values from generators via for-of, as though they were just iterators. Like iterators, you can use the generator directly as well; see Listing 6-11.

That code gets the generator object ( g) from the generator function ( simple), then uses it exactly the way you saw iterators used before (since generators are iterators). That isn't very exciting, but it becomes much more interesting when you start passing values to the generator rather than just taking values from it, as you'll learn in the next section.

Consuming Values with Generators

Up until now, all of the generators you've seen in this chapter only produced values, by providing an operand to yield. This is really useful for writing iterators and never-ending sequences like Fibonacci numbers and such, but generators have another trick up their sleeve: they can consume values, too. The result of the yield operator is the value pushed to the generator, the value it can consume.

You can't push values to generators via for-of, so instead you have to use them directly and pass the value you want to push to the generator into next when calling it.

Here's a really simple example: a generator that sums two numbers pushed to it. See Listing 6-12.

Let's follow Listing 6-12 through in detail:

1. const gen = add() calls the generator function and stores the generator object it returns in the gen constant. None of the logic inside the generator function has run yet—the “starting” line does not appear in the log.
2. gen.next() runs the generator code up until the first yield. The "starting" line is output, then the operand of the first yield, "Please provide value 1", is evaluated and provided by the generator to the caller.
3. That value is received by the calling code in the first result object, which is stored in result.
4. console.log(result) shows the first result: {value: "Please provide value 1", done: false}.
5. gen.next(35) sends the value 35 to the generator.
6. The generator code continues: that value (35) becomes the result of the yield. (That's the generator consuming the value passed to it.) The code assigns that value to value1, logs it, and produces (yields) the value "Please provide value 2".
7. The calling code receives that value on the next result object, and logs that new result object: {value: "Please provide value 2", done: false}.
8. gen.next(7) sends the value 7 to the generator.
9. The generator code continues: that value (7) becomes the result of yield. The code assigns it to value2, logs the value, and returns the sum of value1 and value2.
10. The calling code receives the result object, saves it in result, and logs it. Note that this time, value is the sum (42), and done is true. It's true because the generator returned that value, rather than yielding it.

This example is obviously extremely basic, but it demonstrates how the logic in the generator function seemingly pauses, waiting for the next input from the code using the generator.

Notice that in that example, the first call to gen.next() doesn't have any argument. In fact, if you put an argument there, the generator never sees it. That first call to next advances the generator from the beginning of the function to the first yield, then returns a result object with the value that the first yield produces. Since generator function code receives values from next as the result of yield, there's no way for them to receive a value passed in that first call to next. To provide initial input to the generator, pass an argument in the generator function's arguments list, rather than to the first call to next. (In the example, to give add a value right at the outset, you'd pass it into add rather than passing it to the first call to next.)

The very basic example you've seen so far doesn't have the generator's logic depend on the values pushed to it, but often those values will be used for branching within the generator. Listing 6-13 shows an example of that; run it in a browser.

As you can see from the listing, that generator branches a fair bit based on the values it consumes. It's a state machine, but it's written using the same logical flow syntax you use in other JavaScript code.

It's common for generators to involve loops, sometimes endless loops. See Listing 6-14, which shows a “keep a running sum of the last three inputs” generator.

The generator in Listing 6-14 keeps track of the last three values you feed it, returning an updated sum of those last three each time you call it. When you're using it, you don't have to keep track of the values yourself or worry about the logic of maintaining the running sum, including subtracting values from it when they drop off; you just push values to it and use the sum it produces.

Using return in a Generator Function

As you saw briefly earlier, the generator created by a generator function does an interesting thing when you use the return statement with a return value: it produces a result object that has the return value and done = true. Here's an example:

function* usingReturn() {
    yield 1;
    yield 2;
    return 3;
}
console.log("Using for-of:");
for (const value of usingReturn()) {
    console.log(value);
}
// =>
// 1
// 2
console.log("Using the generator directly:");
const g = usingReturn();
let result;
while (!(result = g.next()).done) {
    console.log(result);
}
// =>
// {value: 1, done: false}
// {value: 2, done: false}
console.log(result);
// =>
// {value: 3, done: true}

There are a couple of things to notice there:

• for-of doesn't see the value on the done = true result object, because like the while loops you've seen, it checks done and exits without looking at value.
• The final console.log(result); shows the return value along with done = true.

The generator only provides the return value once. If you keep calling next even after getting a result object with done = true, you'll get result objects with done = true and value = undefined.

Precedence of the yield Operator

The yield operator has very low precedence. That means that as much of the expression following it as possible is grouped together before yield is done. It's important to be aware of that, because otherwise reasonable-looking code can trip you up. For example, suppose you were consuming a value in a generator and wanted to use the value in a calculation. This seems okay at first glance:

let a = yield + 2 + 30; // WRONG

It does run, but the results are odd:

function* example() {
    let a = yield + 2 + 30; // WRONG
    return a;
}
const gen = example();
console.log(gen.next());   // {value: 32, done: false}
console.log(gen.next(10)); // {value: 10, done: true}

The first call just primes the generator (remember that code in generator functions doesn't see a value passed to the first call to next). The result of the second call is just the value passed in; it doesn't get 2 and 30 added to it. Why? A clue to the answer can be found in the first call's result, which has value = 32.

Remember that the expression to the right of yield is its operand, which is evaluated and becomes the value from next. That line is really doing this:

let a = yield (+ 2 + 30);

which is really just:

let a = yield 2 + 30;

because the unary + that was in front of the 2 doesn't do anything to the 2 (it's already a number).

If you tried to use multiplication rather than addition or subtraction there, you'd get a syntax error:

let a = yield * 2 + 30; // ERROR

That happens because there's no unary * operator.

You might think you'd just move yield to the end:

let a = 2 + 30 + yield; // ERROR

but the JavaScript grammar doesn't allow that (largely for historical and parsing-complexity reasons). Instead, the clearest way is just to put it in its own statement:

function* example() {
    let x = yield;
    let a = x + 2 + 30;
    return a;
}
const gen = example();
console.log(gen.next());   // {value: undefined, done: false}
console.log(gen.next(10)); // {value: 42, done: true}

However, if you prefer you can use parentheses around the yield instead, and then use it anywhere in the expression that makes sense:

function* example() {
    let a = (yield) + 2 + 30;
    return a;
}
const gen = example();
console.log(gen.next());   // {value: undefined, done: false}
console.log(gen.next(10)); // {value: 42, done: true}

The return and throw Methods: Terminating a Generator

Generators created by generator functions implement both of the optional methods of the Iterator interface, return and throw. Using them, code using the generator can, in effect, inject a return statement or throw statement into the generator function's logic where the current yield is.

You'll remember from slightly earlier in this chapter that when a generator issues a return statement, the calling code sees a result object with both a meaningful value and done = true:

function* example() {
    yield 1;
    yield 2;
    return 3;
}
const gen = example();
console.log(gen.next()); // {value: 1, done: false}
console.log(gen.next()); // {value: 2, done: false}
console.log(gen.next()); // {value: 3, done: true}

By using the generator's return method, the calling code can issue a return that isn't actually in the generator function's code; run Listing 6-15.

The first call to gen.next() advances the generator to the first yield and produces the value 1. The gen.return(42) call then forces the generator to return 42, exactly as though it had return 42 in its code where that first yield is (the one where it's suspended when return is called). And just as if it had return 42 in its code, the function terminates, so the yield 2 and yield 3 statements are both skipped. Since the generator has completed, all following calls to next just return a result object with done = true and value = undefined, as you can see in the last call in Listing 6-15.

The throw method works the same way, injecting a throw instead of a return. Run Listing 6-16.

This is exactly as though the generator had throw new Error("boom"); in its logic where the current yield is.

Just as with the return and throw statements, a generator can use try/ catch/ finally to interact with injected returns and throws. Run Listing 6-17.

Notice how the throw was handled by the generator: it responded by switching from counting up (in the try block) to counting down (in the catch block). This isn't particularly useful on its own and isn't something you'd want to do without a very strong reason (you'd be better off writing the generator so you could pass it a value via gen.next() that told the generator to change direction), but can be useful when a generator chains to another generator, in the usual way that using try/ catch can be useful when calling one function from another. More on generators chaining to each other in the next section.

Yielding a Generator or Iterable: yield*

A generator can pass control to another generator (or any iterable) and then pick up again when that generator (or iterable) is done by using yield*. Run Listing 6-18.

Running Listing 6-18 produces the following output:

When outer yields to collect with yield*, calls you make to the next method of outer's generator call next on the generator from collect, producing those values and passing in the ones it consumes. For instance, this line in outer:

let data1 = yield* collect(2);

translates roughly (but only roughly) to this:

// Indicative, but not exactly correct
let gen1 = collect(2);
let result, input;
while (!(result = gen1.next(input)).done) {
    input = yield result.value;
}
let data1 = result.value;

However, in addition to that, the JavaScript runtime ensures that calls to throw and return when a generator is doing yield* propagate down through the pipeline to the deepest generator/iterator and take effect from there upward. (Whereas with the “indicative” code shown earlier, calling throw or return on that generator wouldn't get passed on; it would just take effect in the generator you called it on.)

Listing 6-19 shows an example of using return to terminate an inner generator along with its outer generator.

Running that, notice how when the generator from outer is using yield* to pass control to the generator from inner, the call to return on the generator from outer is forwarded to the inner generator and takes effect there, as you can see by the console.log in its finally block. But it didn't just cause a return there, it also caused one in the outer generator as well. It's as though there were a return 42 in the inner generator, and the outer generator returned the inner's return value, where the yields each generator was suspended at were.

The outer generator doesn't have to stop producing values just because you terminated the inner one. In the downloads, the file forwarded-return-with-yield.js is just like forwarded-return.js with this line just above the console.log("outer terminated"); line:

        yield "outer finally";

Run forwarded-return-with-yield.js. It produces slightly different output:

const gen = outer();
let result = gen.next();
console.log(result);     // {value: "outer before", done: false}
result = gen.next();
console.log(result);     // {value: "inner 0", done: false}
result = gen.next();
console.log(result);     // {value: "inner 1", done: false}
result = gen.return(42); // "inner terminated"
console.log(result);     // {value: "outer finally", done: false}
result = gen.next();     // "outer terminated"
console.log(result);     // {value: 42, done: true}

Notice that the gen.return call didn't return the value that you passed into it ( 42). Instead, it returned the value "outer finally" produced in the outer generator by the new yield and still has done = false. But later, after the final next call, when the generator is finished it returns a result object with value = 42 and done = true. It may seem odd that the 42 was retained and then returned later, but that's how finally blocks work outside generator functions, too. For example:

function example() {
    try {
        console.log("a");
        return 42;
    } finally {
        console.log("b");
    }
}
const result = example(); // "a"
                          // "b"
console.log(result);      // 42

It's possible for the generator to return a different value than the one you give in the return method call. This is, again, like having a return statement. What does this non-generator function return?

function foo() {
    try {
        return "a";
    } finally {
        return "b";
    }
}
console.log(foo());

Right! It returns "b", because it overrides the first return with the one in the finally block. This is generally poor practice, but it is possible.

Generator functions can do that too, including overriding an injected return:

function* foo(n) {
    try {
        while (true) {
            n = yield n * 2;
        }
    } finally {
        return "override";  // (Generally poor practice)
    }
}
const gen = foo(2);
console.log(gen.next());    // { value: 4, done: false }
console.log(gen.next(3));   // { value: 6, done: false }
console.log(gen.return(4)); // { value: "override", done: true }

Notice that the result object returned from the return had value = "override", not value = 4.

Since yield* forwards these calls to the innermost generator, the inner in Listing 6-19 could do the same thing. Here's a pared-down example of that:

function* inner() {
    try {
        yield "something";
    } finally {
        return "override"; // (Generally poor practice)
    }
}
function* outer() {
    yield* inner();
}
const gen = outer();
let result = gen.next();
console.log(gen.return(42)); // {value: "override", done: true}

Notice how the call to return got forwarded from outer's generator to inner's. That made inner effectively issue a return on the yield line, but then that return was overridden by the one in the finally block. Then, the call to return also made outer return inner's return value, even though there's no code in outer that does that.

Using the throw method in this situation is simpler to understand: it behaves exactly as though the innermost active generator/iterator had used the throw statement. So naturally it propagates up through the (effective) call stack until/unless it's caught via try/ catch (or overridden with a return in a finally block as in the previous example):

function* inner() {
    try {
        yield "something";
        console.log("inner - done");
    } finally {
        console.log("inner - finally");
    }
}
function* outer() {
    try {
        yield* inner();
        console.log("outer - done");
    } finally {
        console.log("outer - finally");
    }
}
const gen = outer();
let result = gen.next();
result = gen.throw(new Error("boom")); // inner - finally
                                       // outer - finally
                                       // Uncaught Error: "boom"

Use Constructs That Consume Iterables

Old habit: Using a for loop or forEach to loop through arrays:

for (let n = 0; n < array.length; ++n) {
    console.log(array[n]);
}
// or
array.forEach(entry => console.log(entry));

New habit: When you don't need the index in the body of the loop, use for-of instead:

for (const entry of array) {
    console.log(entry);
}

However, there are still use cases for for and forEach:

• If you need the index variable in the body of the loop³
• If you're passing a preexisting function to forEach instead of creating a new one

Use DOM Collection Iteration Features

Old habit: Converting a DOM collection to an array just to loop through it, or using Array.prototype.forEach.call on a DOM collection:

Array.prototype.slice.call(document.querySelectorAll("div")).forEach(div => {
    // …
});
// or
Array.prototype.forEach.call(document.querySelectorAll("div"), div => {
    // …
});
 

New habit: Ensure DOM collections are iterable in your environment (perhaps by polyfilling) and use that iterability directly:

for (const div of document.querySelectorAll("div")) {
    // …
}

Use the Iterable and Iterator Interfaces

Old habit: Defining custom iteration techniques on your own collection types.

New habit: Make the collection types iterable instead by implementing the Symbol.iterator function and an iterator (perhaps written using a generator function).

Use Iterable Spread Syntax in Most Places You Used to Use Function.prototype.apply

Old habit: Using Function.prototype.apply when using an array to provide discrete arguments to a function:

const array = [23, 42, 17, 27];
console.log(Math.min.apply(Math, array)); // 17

New habit: Use spread syntax:

const array = [23, 42, 17, 27];
console.log(Math.min(…array)); // 17

Use Generators

Old habit: Writing highly complex state machines that can be better modeled with code-flow syntax.

New habit: Define the logic in a generator function instead and use the resulting generator object. For state machines that aren’t better modeled with code-flow syntax, though, a generator function may not be the right choice.

Use Destructuring When Getting Only Some Properties from an Object

Old habit: Getting an object from a function and remembering it in a variable, only to then use only a small number of its properties:

const person = getThePerson();
console.log("The person is " + person.firstName + " " + person.lastName);

New habit: Use destructuring instead in situations where you don't need the object itself for anything later:

const {firstName, lastName} = getThePerson();
console.log("The person is " + firstName + " " + lastName);

Use Destructuring for Options Objects

Old habit: Using options objects for functions with lots of options.

New habit: Consider using destructuring.

Before destructuring, a function accepting five options, where the five option's default is based on the one option's value, might look like this:

function doSomethingNifty(options) {
    options = Object.assign({}, options, {
        // The default options
        one: 1,
        two: 2,
        three: 3,
        four: 4
 
    });
    if (options.five === undefined) {
        options.five = options.one * 5;
    }
    console.log("The 'five' option is: " + options.five);
    // …
}
doSomethingNifty(); // The 'five' option is: 5

That hides the defaults inside the function's code, meaning that any complicated default value has to be special-cased, and meaning you have to do a property access on your options object each time you use an option.

Instead, you can define your default options as destructuring defaults, handle the defaulting of five within the destructuring default, provide an overall blank object for the parameter default value, and the use the resulting bindings directly:

function doSomethingNifty({
        one = 1,
        two = 2,
        three = 3,
        four = 4,
        five = one * 5
} = {}) {
    console.log("The 'five' option is: " + five);
    // …
}
doSomethingNifty(); // The 'five' option is: 5

Overview

A promise is an object with three possible states:

• Pending: The promise is pending/outstanding/not yet settled.
• Fulfilled: The promise has been settled with a value. This usually means success.
• Rejected: The promise has been settled with a rejection reason. This usually means failure.

A promise starts out pending and then can only be settled (fulfilled or rejected) once. A settled promise can't go back to being pending. A fulfilled promise can't change to a rejected one or vice versa. Once settled, the promise's state never changes.

A fulfilled promise has a fulfillment value (usually simply value); a rejected promise has a rejection reason (sometimes simply reason, though error is common as well).

When you resolve a promise, you're either fulfilling it with a value or you're making it dependent on another promise.² When you make it dependent on another promise, you “resolve it to” the other promise. That means ultimately it might be fulfilled or rejected, depending on what happens to the other promise.

When you reject a promise, you're making it rejected with a rejection reason.

You can't directly observe a promise's state and value/rejection reason (if any); you can only get them by adding handler functions that the promise calls. A JavaScript promise has three methods for registering handlers:

• then: Adds a fulfillment handler to call if/when the promise gets fulfilled³
• catch: Adds a rejection handler to call if/when the promise gets rejected
• finally: Adds a finally handler to call if/when the promise gets settled, regardless of how (added in ES2018)

One of the key aspects of promises is that then, catch, and finally return a new promise. The new promise is connected to the promise you called the method on: it will get fulfilled or rejected depending on what happens to that original promise and what your handler function(s) do. We'll come back to this key point throughout this chapter.

Example

Listing 8-1 has a simple example of creating and using a promise, using setTimeout for the asynchronous operation being observed. Run the example repeatedly. Half the time, the promise it creates gets fulfilled; the other half, it gets rejected.

There are three parts to that:

1. Creating the promise: done by the example function, which creates and returns it
2. Resolving or rejecting the promise: done by the example function's timer callback
3. Using the promise: done by the code calling example

example uses the Promise constructor to create the promise, passing in a function. The function you give the Promise constructor has a fancy name: executor function. The Promise constructor calls the executor function (synchronously) passing two functions to it as arguments: resolve and reject. (Those are the conventional names. But of course, you can use whatever names you want for the parameters in your executor function. Sometimes you see fulfill instead of resolve, although that's not quite correct as you'll see in a moment.) You use the resolve and reject functions to determine what happens to the promise:

• If you call resolve with another promise,⁴ the promise gets resolved to that other promise (it will get fulfilled or rejected depending on what happens to that other promise). This is why fulfill isn't an accurate name for the first function; when you call it with another promise, it doesn't fulfill the promise you created, it just resolves it to that other promise, which might reject.
• If you call resolve with any other value, the promise gets fulfilled with that value.
• If you call reject, the promise gets rejected using the reason you pass into reject (usually an Error, but that's a matter of style). Unlike resolve, reject doesn't do something different if you give it a promise. It always uses what you give it as the rejection reason.

The promise can only be resolved or rejected using those functions. Nothing can resolve or reject it without them. They aren't available as methods on the promise object itself, so you can give the promise object to other code knowing that the code receiving it can only consume the promise, not resolve or reject it.

In example's case, it calls setTimeout to start an asynchronous operation. It has to use setTimeout or similar because, again, promises are just a way of observing the completion of asynchronous operations, not creating asynchronous operations.⁵ When the timer expires, example's timer callback either calls resolve or reject depending on the random result.

Turning to how the promise is used: The code using example uses a chain of calls, in this case then followed by catch followed by finally, to hook up a fulfillment handler, a rejection handler, and a finally handler, respectively. Chaining is quite common with promise methods, for reasons you'll learn as you progress through the chapter.

Run the code in Listing 8-1 enough times to see both a fulfillment and a rejection. When the promise gets fulfilled, the chain calls the fulfillment handler with the fulfillment value, then the finally handler (which doesn't receive any value). When the promise gets rejected, the chain calls the rejection handler with the rejection reason, then the finally handler (which, again, doesn't receive any value). It would also call the rejection handler (and then the finally handler) if the original promise was fulfilled but the fulfillment handler threw an error; more on that in a bit.

The fulfillment, rejection, and finally handlers serve the same purpose as the blocks in a try/ catch/ finally statement:

try {
    // do something
    // fulfillment handler
} catch (error) {
    // rejection handler
} finally {
    // finally handler
}

There are slight differences you'll learn later, particularly around finally, but that's fundamentally a good way to think about fulfillment, rejection, and finally handlers.

Using new Promise is fairly rare compared with using a promise from an API function or the ones you get from then, catch, and finally, so we'll focus initially on using promises, then come back to the details of creating them.

Promises and “Thenables”

JavaScript's promises follow rules defined by the ECMAScript specification, which draw heavily on prior art, in particular the Promises/A+ specification and the work leading up to it. JavaScript's promises are fully compliant with the Promises/A+ specification, and have some additional features intentionally not covered by that specification, such as catch and finally. (The Promises/A+ specification is intentionally minimalist and defines only then, because what catch and finally do can be done with the two-argument version of then that you’ll learn about in a later section.)

One aspect of the Promises/A+ specification is the concept of “thenables” as distinct from “promises.” Here's how that specification defines them:

• A “promise” is an object or function with a then method whose behavior conforms to [the Promises/A+ specification].
• A “thenable” is an object or function that defines a then method.

So all promises are thenables, but not all thenables are promises. An object might define a method called then that doesn't work as defined for promises; that object would be a thenable, but not a promise.

Why is this important? Interoperability.

Sometimes, a promise implementation needs to know whether a value is a simple value it can use to fulfill the promise, or a thenable it should resolve the promise to. It does that by checking if the value is an object with a then method: if so, the object is assumed to be a thenable and the promise implementation uses its then method to resolve the promise to the thenable. This is imperfect, since an object can have a then method that means something completely unrelated to promises, but it was the best solution at the time promises were being added to JavaScript because it allowed the multiple promise libraries that existed at the time (and still exist) to interoperate without every implementation having to be updated to add some other feature to mark its promises as being promises. (It would have been a great use case for a Symbol [Chapter 5], for instance, if it had been possible to update every library to add it.)

Up to this point, I've used “promise” with a footnote in a couple of places where “thenable” would be more accurate. Now that you know what a thenable is, I'll start using it where appropriate.

The then Method

You've already briefly seen the then method in action, hooking into a promise's fulfillment.⁶ Let's look at then in a bit more detail. Consider this very basic call to then:

p2 = p1.then(result => doSomethingWith(result.toUpperCase()));

As you've already learned, it registers a fulfillment handler, creating and returning a new promise ( p2) that will get fulfilled or rejected depending on what happens to the original promise ( p1) and what you do in your handler. If p1 gets rejected, the handler isn’t called and p2 is rejected with p1’s rejection reason. If p1 gets fulfilled, the handler gets called. Here's what happens to p2 depending on what your handler does:

• If you return a thenable, p2 gets resolved to that thenable (it will get fulfilled or rejected depending on what happens to that thenable).
• If you return any other value, p2 gets fulfilled with that value.
• If you use throw (or call a function that throws), p2 gets rejected using what you threw (usually an Error) as the rejection reason.

Those three bullet points probably seem familiar. That's because they're nearly identical to the bullet points you saw earlier saying what you can do with the resolve and reject functions you get in a promise executor function. Returning something from your then handler is just like calling resolve. Using throw in your handler is just like calling reject.

This ability to return a thenable is one of the keys of promises, so let's look at it more closely.

Chaining Promises

The fact that you can return a promise (or any thenable) from a then/ catch/ finally handler to resolve the promise they create means that if you need to do a series of asynchronous operations that provide promises/thenables, you can use then on the first operation and have the handler return the thenable for the second operation, repeated as many times as you need. Here's a chain with three operations returning promises:

firstOperation()
.then(firstResult => secondOperation(firstResult)) // or: .then(secondOperation)
.then(secondResult => thirdOperation(secondResult * 2))
.then(thirdResult => { /* Use `thirdResult` */ })
.catch(error => { console.error(error); });

When that code runs, firstOperation starts the first operation and returns a promise. Calls to then and catch set up handlers for what happens next (see Figure 8-1, overleaf). Later, when the first operation completes, what happens next depends on what happened to the first operation: if it fulfills its promise, the first fulfillment handler gets run and starts the second operation, returning the promise secondOperation provides. See Figure 8-2 (overleaf).

If the second operation fulfills its promise, that fulfills the promise the first then returned, and the next fulfillment handler gets run (Figure 8-3): it starts the third operation and returns the promise of its result. If the third operation fulfills its promise, that fulfills the promise from the second then. That calls the code that uses the third result. Provided that code doesn't throw or return a rejected promise, the chain completes (Figure 8-4, opposite). The rejection handler doesn't get run at all in that case, since there were no rejections.

If the first operation rejects its promise, though, that rejects the promise from the first then, which rejects the promise from the second then, which rejects the promise from the third then, which calls the rejection handler at the end. None of the then callbacks get called, because they were for fulfillment, not rejection. See Figure 8-5.

If the first operation succeeds and its fulfillment handler starts the second operation and returns its promise, but the second operation fails and rejects its promise, that rejects the promise from the first then, which rejects the promise from the second then, which rejects the promise from the third then, which calls the rejection handler. See Figure 8-6. (Similarly, if the first operation succeeds but the fulfillment handler throws, the same thing happens: the remaining fulfillment handlers are skipped, and the rejection handler runs.)

Naturally, the same is true if the first and second operations fulfill their promises but the third rejects its promise (or the handler starting it throws). See Figure 8-7.

If all three operations succeed, the final fulfillment handler is run. If that handler throws, either directly or by calling a function that throws, the rejection handler gets run. See Figure 8-8.

As you can see, a promise chain of this kind is very much like a try/ catch block around three synchronous operations (and some final code), like this:

// The same logic with synchronous operations
try {
    const firstResult = firstOperation();
    const secondResult = secondOperation(firstResult);
    const thirdResult = thirdOperation(secondResult * 2);
    // Use `thirdResult` here
} catch (error) {
    console.error(error);
}

Just as the separation of the main logic from the error logic is useful in try/ catch synchronous code, the separation of the main (fulfillment) logic from the error (rejection) logic in promise chains is useful.

You can see these various scenarios play out by repeatedly running the basic-promise-chain.js file from the downloads. That file uses Math.random to give each operation (first, second, and third) a 20% chance of failing, and to give the final fulfillment handler a 20% chance of throwing.

Comparison with Callbacks

Let's compare the promise chain from the previous section with using bare callbacks. For this comparison, let's assume that the functions starting the asynchronous operations accept a callback: if the operation succeeds, they call the callback with null as the first argument and the result value as the second; if the operation fails, they call the callback with an error as the first argument. (This is one of the more common patterns for callbacks, popularized by Node.js among others.) Here's how the previous sequence would look using that convention:

firstOperation((error, firstResult) => {
    if (error) {
        console.error(error);
        // (Perhaps you'd use `return;` here to avoid the `else`)
    } else {
        secondOperation(firstResult, (error, secondResult) => {
            if (error) {
                console.error(error);
                // Perhaps: `return;`
            } else {
                thirdOperation(secondResult * 2, (error, thirdResult) => {
                    if (error) {
                        console.error(error);
                        // Perhaps: `return;`
                    } else {
                        try {
                            /* Use `thirdResult` */
                        } catch (error) {
                            console.error(error);
                        }
                    }
                });
            }
        });
    }
});

You can run this using basic-callback-chain.js from the downloads.

Notice how each step has to be nested in the callback of the previous step. This is the famous “callback hell,” and part of the reason some programmers use just a two-character indentation—despite how hard it is to read—so their deeply nested callbacks don't go off the right of the screen. It's possible to write that code without having the callbacks nested within one another, but it's awkward and verbose.

Really, to be more accurate there would need to be a try/ catch block around the call to secondOperation and another one around the call to thirdOperation, but I didn't want to overcomplicate the example—which underscores the point about how promises make this simpler.

The catch Method

You've already learned that the catch method registers a handler that gets called when the promise gets rejected. Other than that the handler you give it gets called on rejection rather than fulfillment, catch is exactly like then. With this:

p2 = p1.catch(error => doSomethingWith(error))

catch registers a rejection handler on p1, creating and returning a new promise ( p2) that will get fulfilled or rejected depending on what happens to the original promise ( p1) and what you do in your handler. If p1 gets fulfilled, the handler isn’t called and p2 is fulfilled with p1’s fulfillment value. If p1 gets rejected, the handler gets called. Here's what happens to p2 depending on what your handler does:

• If you return a thenable, p2 gets resolved to that thenable.
• If you return any other value, p2 gets fulfilled with that value.
• If you use throw, p2 gets rejected using what you threw as the rejection reason.

Sound familiar? Right! That's exactly what then does with its handler, which is, in turn, exactly what the resolve function you get in a promise executor function does. The consistency is useful, you don't have to remember different rules for different resolution mechanisms.

One thing to notice in particular is that if you return a non-thenable from the catch handler, the promise from catch gets fulfilled. That converts the rejection from p1 into a fulfillment of p2. If you think about it, that's just like the catch in a try/ catch: unless you re-throw the error in your catch block, the catch block stops the error from propagating. The catch method on promises works the same way.

There's a slight downside to that: it means you can inadvertently mask errors by putting a catch handler in the wrong place. Consider:

someOperation()
    .catch(error => {
        reportError(error);
    })
    .then(result => {
        console.log(result.someProperty);
    });

With that code, if the operation started by someOperation fails, reportError gets called with the error (so far, so good), but you'll get an error in the console that looks something like this:

Uncaught (in promise) TypeError: Cannot read property 'someProperty' of undefined

Why is it trying to read someProperty of undefined? The promise rejected, so why is the then handler being called?

Let's go back to our try/ catch/ finally analogue. That code is the logical (not literal) equivalent of this:

let result;
try {
    result = someOperation();
} catch (error) {
    reportError(error);
    result = undefined;
}
console.log(result.someProperty);

The catch caught the error and output it, but didn't do anything to propagate the error. So the code after the try/ catch still runs and tries to use result.someProperty, which fails because result is undefined.

The promise version is doing the same thing, because the rejection handler caught the error, handled it, and then didn't return anything, which is like returning undefined. That fulfilled the promise from catch with undefined. So that promise called its fulfillment handler, passed in undefined as result, and when the handler tried to use result.someProperty, it caused a new error.

“But what's with this ‘unhandled rejection’ thing?” you may be asking. If a promise gets rejected and no code is in place to handle the rejection, JavaScript engines report an “unhandled rejection” since that's usually a bug. The code in that example doesn't handle errors from the final fulfillment handler (the one with result.someProperty in it), so when the error trying to use result.someProperty makes the promise from then reject, it's an “Unhandled rejection,” since there's nothing to handle it.

Sometimes, of course, you might want to put a catch in the middle specifically to do exactly that: handle an error and allow the chain to continue with some substitute value or similar. It's absolutely fine if you're doing it on purpose.

The finally Method

The finally method is, as you've learned, very much like the finally block of a try/ catch/ finally. It adds a handler that gets called whether the promise gets fulfilled or rejected (like a finally block). Like then and catch, it returns a new promise that gets fulfilled or rejected based on what happens to the original promise and what the finally handler does. But unlike then and catch, its handler is always called, and the things its handler can do to what's passing through it are limited.

Here's a simple example:

function doStuff() {
    spinner.start();
    return getSomething()
        .then(result => render(result.stuff))
        .finally(() => spinner.stop());
}

This function starts a spinner spinning to show the user it's doing something, uses getSomething—a function that returns a promise—to start an asynchronous operation, then shows the result if the promise gets fulfilled, and stops the spinner no matter what happens to the promise.

Note that this function doesn't attempt to handle errors; instead, it returns the final promise in the chain. That’s fairly normal; it allows the calling code to know whether the operation succeeded and allows error handling to happen at the highest level (often an event handler or similar, e.g., the entry point into the JavaScript code). By using finally, this code can defer error handling to the caller while being sure to stop the spinner even when an error occurs.

In the normal case, a finally handler has no effect on the fulfillment or rejection passing through it (again, like a finally block): any value it returns other than a thenable that is/gets rejected is ignored. But if it throws an error or returns a thenable that rejects, that error/rejection supersedes any fulfillment or rejection passing through it (just like throw in a finally block). So it can't change a fulfillment value—not even if it returns a different value—but it can change a rejection reason into a different rejection reason, it can change a fulfillment into a rejection, and it can delay a fulfillment (by returning a thenable that is ultimately fulfilled; you'll see an example in a moment).

Or to put it another way: it's like a finally block that can't contain a return statement.⁷ It might have a throw or might call a function that throws, but it can't return a new value.

Run the code in Listing 8-2 to see an example.

In that example, doSomething calls returnWithDelay and has a finally handler (in the real world, it would be for some kind of cleanup). doSomething returns the promise created by calling finally. The code calls doSomething and uses the promise it returns (the one from finally). Note that the finally handler returns a value, but the promise from finally doesn't use that as its fulfillment value. It uses the value it received from the promise it was called on instead. The return value from the finally handler wasn’t a thenable, so it was completely ignored.

The reason for preventing a finally handler from changing fulfillments is twofold:

• The primary use case of finally is to clean up when you’re done with something, but without affecting that thing's result.
• Pragmatically, the promise mechanism can't tell the difference between a function that doesn't use return at all (code execution just “falls off the end” of the function), a function that uses return with no operand, and a function that uses return undefined, because the result of calling all three of those functions is the same: the value undefined. For example:

  function a() {
  }
  function b() {
      return;
  }
  function c() {
      return undefined;
  }
  console.log(a()); // undefined
  console.log(b()); // undefined
  console.log(c()); // undefined

  In contrast, in a try/ catch/ finally structure, the JavaScript engine can tell the difference between a finally block where code execution just falls off the end (not affecting the return value of the function it's in) and one that issues a return statement. Since the promise mechanism can’t tell that difference, though, and since the primary purpose of a finally handler is to do cleanup without changing anything, it makes sense to ignore the return value of the finally handler.