3
Language Basics

At the core of any language is a description of how it should work at the most basic level. This description typically defines syntax, operators, data types, and built-in functionality upon which complex solutions can be built. As previously mentioned, ECMA-262 defines all of this information for JavaScript in the form of a pseudolanguage called ECMAScript.

ECMAScript as defined in ECMA-262 is implemented with increasing uniformity across all major browsers. A decade ago, major browsers had widely divergent support for some ECMAScript features. Today, features included in the annual ECMAScript editions are usually supported by all major browsers in less than a year.

SYNTAX

ECMAScript's syntax borrows heavily from C and other C-like languages such as Java and Perl. Developers familiar with such languages should have an easy time picking up the somewhat looser syntax of ECMAScript.

Case-Sensitivity

The first concept to understand is that everything is case-sensitive; variables, function names, and operators are all case-sensitive, meaning that a variable named test is different from a variable named Test. Similarly, typeof can't be the name of a function because it's a keyword (described in the next section); however, "Typeof" is a perfectly valid function name.

Identifiers

An identifier is the name of a variable, function, or function argument. Identifiers may be one or more characters in the following format:

The first character must be a letter, an underscore (_), or a dollar sign ($).
All other characters may be letters, underscores, dollar signs, or numbers.

Letters in an identifier may include extended ASCII or Unicode letter characters such as À and Æ, though this is not recommended.

By convention, ECMAScript identifiers use camel case, meaning that the first letter is lowercase and each additional word is offset by a capital letter, like this:

firstSecond
myCar
doSomethingImportant

Although this is not strictly enforced, it is considered a best practice to adhere to the built-in ECMAScript functions and objects that follow this format.

Comments

ECMAScript uses C-style comments for both single–line and block comments. A single–line comment begins with two forward-slash characters, such as this:

// single line comment

A block comment begins with a forward slash and asterisk (/*) and ends with the opposite (*/), as in this example:

/* This is a multi-line
comment */

Strict Mode

ECMAScript 5 introduced the concept of strict mode. Strict mode is a different parsing and execution model for JavaScript, where some of the erratic behavior of ECMAScript 3 is addressed and errors are thrown for unsafe activities. To enable strict mode for an entire script, include the following at the top:

"use strict";

Although this may look like a string that isn't assigned to a variable, this is a pragma that tells supporting JavaScript engines to change into strict mode. The syntax was chosen specifically so as not to break ECMAScript 3 syntax.

You may also specify just a function to execute in strict mode by including the pragma at the top of the function body:

function doSomething() {
  "use strict";
  // function body
}

Strict mode is effectively the assumed modality in modern JavaScript. ES6 modules and classes automatically apply strict mode without the “use strict” directive. Furthermore, modern code compilers and bundlers such as Webpack will automatically insert the directive.

Statements

Statements in ECMAScript are terminated by a semicolon, though omitting the semicolon makes the parser determine where the end of a statement occurs, as in the following examples:

let sum = a + b    // valid even without a semicolon - not recommended
let diff = a - b;  // valid - preferred

Even though a semicolon is not required at the end of statements, you should always include one. Including semicolons helps prevent errors of omission, such as not finishing what you were typing, and allows developers to compress ECMAScript code by removing extra white space (such compression causes syntax errors when lines do not end in a semicolon). Including semicolons also improves performance in certain situations because parsers try to correct syntax errors by inserting semicolons where they appear to belong.

Multiple statements can be combined into a code block by using C-style syntax, beginning with a left curly brace ({) and ending with a right curly brace (}):

if (test) {
  test = false;
  console.log(test);
}

Control statements, such as if, require code blocks only when executing multiple statements. However, it is considered a best practice to always use code blocks with control statements, even if there's only one statement to be executed, as in the following examples:

// valid, but error-prone and should be avoided
if (test)
  console.log(test);

// preferred
if (test) {  console.log(test);
}

Using code blocks for control statements makes the intent clearer, and there's less chance for errors when changes need to be made.

KEYWORDS AND RESERVED WORDS

ECMA-262 describes a set of reserved keywords that have specific uses, such as indicating the beginning or end of control statements or performing specific operations. By rule, keywords are reserved and cannot be used as identifiers or property names. The complete list of keywords for ECMA-262, sixth edition is as follows:

await break case catch class const continue
debugger default delete do else export
extends false finally for function if import
in instanceof let new null return super switch
this throw true try typeof var void while
with yield

The specification also describes a set of future reserved words that cannot be used as identifiers or property names. Though reserved words don't have any specific usage in the language, they are reserved for future use as keywords.

The following is the complete list of future reserved words defined in ECMA-262:

Always reserved:

enum


Reserved in strict mode:

arguments eval implements interface package private protected public static

VARIABLES

ECMAScript variables are loosely typed, meaning that a variable can hold any type of data. Every variable is simply a named placeholder for a value. There are three keywords that can be used to declare a variable: var, const, and let.

The var Keyword

To define a variable, use the var operator (note that var is a keyword) followed by the variable name (an identifier, as described earlier), like this:

var message;

This code defines a variable named message that can be used to hold any value. (Without initialization, it holds the special value undefined, which is discussed in the next section.) ECMAScript implements variable initialization, so it's possible to define the variable and set its value at the same time, as in this example:

var message = "hi";

Here, message is defined to hold a string value of "hi". Doing this initialization doesn't mark the variable as being a string type; it is simply the assignment of a value to the variable. It is still possible to not only change the value stored in the variable but also change the type of value, such as this:

var message = "hi";
message = 100;  // legal, but not recommended

In this example, the variable message is first defined as having the string value "hi" and then overwritten with the numeric value 100. Although it's not recommended to switch the data type that a variable contains, it is completely valid in ECMAScript.

var Declaration Scope

It's important to note that using the var operator to define a variable makes it local to the function scope in which it was defined. For example, defining a variable inside of a function using var means that the variable is destroyed as soon as the function exits, as shown here:

function test() {
  var message = "hi";  // local variable
}
test();
console.log(message); // error!

Here, the message variable is defined within a function using var. The function is called test(), which creates the variable and assigns its value. Immediately after that, the variable is destroyed so the last line in this example causes an error. It is, however, possible to define a variable globally by simply omitting the var operator as follows:

function test() {
  message = "hi";  // global variable
}
test();
console.log(message); // "hi"

By removing the var operator from the example, the message variable becomes global. As soon as the function test() is called, the variable is defined and becomes accessible outside of the function once it has been executed.

If you need to define more than one variable, you can do it using a single statement, separating each variable (and optional initialization) with a comma like this:

var message = "hi",
    found = false,
    age = 29;

Here, three variables are defined and initialized. Because ECMAScript is loosely typed, variable initializations using different data types may be combined into a single statement. Though inserting line breaks and indenting the variables isn't necessary, it helps to improve readability.

When you are running in strict mode, you cannot define variables named eval or arguments. Doing so results in a syntax error.

var Declaration Hoisting

When using var, the following is possible because variables declared using that keyword are hoisted to the top of the function scope:

function foo() {
  console.log(age);
  var age = 26;
}
foo();  // undefined

This does not throw an error because the ECMAScript runtime technically treats it like this:

function foo() {
  var age;
  console.log(age);
  age = 26;
}
foo();  // undefined

This is “hoisting,” where the interpreter pulls all variable declarations to the top of its scope. It also allows you to use redundant var declarations without penalty:

function foo() {
  var age = 16;
  var age = 26;
  var age = 36;
  console.log(age);
}
foo();  // 36

let Declarations

let operates in nearly the same way as var, but with some important differences. Most notable is that let is block scoped, but var is function scoped.

if (true) {
  var name = 'Bob';
  console.log(name);  // Bob
}
console.log(name);    // Bob

if (true) {
  let age = 26;
  console.log(age);   // 26
}
console.log(age);     // ReferenceError: age is not defined

Here, the age variable cannot be referenced outside the if block because its scope does not extend outside the block. Block scope is strictly a subset of function scope, so any scope limitations that apply to var declarations will also apply to let declarations.

A let declaration also does not allow for any redundant declarations within a block scope. Doing so will result in an error:

var name;
var name;
let age;
let age;  // SyntaxError; identifier 'age' has already been declared

The JavaScript engine will keep track of identifiers used for variable declarations and the block scope they were declared inside, so nesting using identical identifiers will not throw errors because no redeclaration is occurring:

var name = 'Alice';
console.log(name);  // 'Alice'
if (true) {
  var name = 'Bob';
  console.log(name);  // 'Bob'
}

let age = 30;
console.log(age);  // 30
if (true) {
  let age = 26;
  console.log(age);  // 26
}

The declaration redundancy errors are not affected if let is mixed with var. The different keywords do not declare different types of variables—they just specify how the variables exist inside the relevant scope.

var name;
let name;  // SyntaxError

let age;
var age;   // SyntaxError

Temporal Dead Zone

Another important behavior of let distinguishing it from var is that let declarations cannot be used in a way that assumes hoisting:

// name is hoisted
console.log(name);  // undefined
var name = 'Bob';

// age is not hoisted
console.log(age);  // ReferenceError: age is not defined
let age = 26;

When parsing the code, JavaScript engines will still be aware of the let declarations that appear later in a block, but these variables will be unable to be referenced in any way before the actual declaration occurs. The segment of execution that occurs before the declaration is referred to as the “temporal dead zone,” and any attempted references to these variables will throw a ReferenceError.

Global Declarations

Unlike the var keyword, when declaring variables using let in the global context, variables will not attach to the window object as they do with var.

var name = 'Bob';
console.log(window.name);  // 'Bob'

let age = 26;
console.log(window.age);   // undefined

However, let declarations will still occur inside the global block scope, which will persist for the lifetime of the page. Therefore, you must ensure your page does not attempt duplicate declarations in order to avoid throwing a SyntaxError.

Conditional Declaration

When using var to declare variables, because the declaration is hoisted, the JavaScript engine will happily combine redundant declarations into a single declaration at the top of the scope. Because let declarations are scoped to blocks, it's not possible to check if a let variable has previously been declared and conditionally declare it only if it has not.

<script>
  var name = 'Alice';
  let age = 26;
</script>

<script>
  // Suppose this script is unsure about what has already been declared in the page.
  // It will assume variables have not been declared.

  var name = 'Bob';
  // No problems here, since this will be handled as a single hoisted declaration.
  // There is no need to check if it was previously declared.

  let age = 36;
  // This will throw an error when 'age' has already been declared.
</script>

Using a try/catch statement or the typeof operator are not solutions, as the let declaration inside the conditional block will be scoped to that block.

<script>
  let name = 'Alice';
  let age = 36;
</script>

<script>
  // Suppose this script is unsure about what has already been declared in the page.
  // It will assume variables have not been declared.

  if (typeof name === 'undefined') {
    let name;
  }
  // 'name' is restricted to the if {} block scope,
  // so this assignment will act as a global assignment
  name = 'Bob';


  try (age) {
    // If age is not declared, this will throw an error
  }
  catch(error) {
    let age;
  }
  // 'age' is restricted to the catch {} block scope,
  // so this assignment will act as a global assignment
  age = 26;
</script>

Because of this, you cannot rely on a conditional declaration pattern.

let Declaration in for Loops

Prior to the advent of let, for loop definition involved using an iterator variable whose definition would bleed outside the loop body:

for (var i = 0; i < 5; ++i) {
  // do loop things
}
console.log(i);  // 5

This is no longer a problem when switching to let declarations, as the iterator variable will be scoped only to the for loop block:

for (let i = 0; i < 5; ++i) {
  // do loop things
}
console.log(i);  // ReferenceError: i is not defined

When using var, a frequent problem encountered was the singular declaration and modification of the iterator variable:

for (var i = 0; i < 5; ++i) {
  setTimeout(() => console.log(i), 0)
}
// You might expect this to console.log 0, 1, 2, 3, 4
// It will actually console.log 5, 5, 5, 5, 5

This happens because the loop exits with its iterator variable still set to the value that caused the loop to exit: 5. When the timeouts later execute, they reference this same variable, and consequently console.log its final value.

When using let to declare the loop iterator, behind the scenes the JavaScript engine will actually declare a new iterator variable each loop iteration. Each setTimeout references that separate instance, and therefore it will console.log the expected value: the value of the iterator variable when that loop iteration was executed.

for (let i = 0; i < 5; ++i) {
  setTimeout(() => console.log(i), 0)
}
// console.logs 0, 1, 2, 3, 4

This per-iteration declarative behavior is applicable for all styles of for loops, including for-in and for-of loops.

const Declarations

const behaves identically to that of let but with one important difference—it must be initialized with a value, and that value cannot be redefined after declaration. Attempting to modify a const variable will result in a runtime error.

const age = 26;
age = 36;  // TypeError: assignment to a constant

// const still disallows redundant declaration
const name = 'Bob';
const name = 'Alice';  // SyntaxError

// const is still scoped to blocks
const name = 'Bob';
if (true) {
  const name = 'Alice';
}
console.log(name);  // Bob

The const declaration is only enforced with respect to the reference to the variable that it points to. If a const variable references an object, it does not violate the const constraints to modify properties inside that object.

const person = {};
person.name = 'Bob';  // ok

Even though the JavaScript engine is creating new instances of let iterator variables in for loops, and even though const variables behave similarly to let variables, you cannot use const to declare for loop iterators:

for (const i = 0; i < 10; ++i) {}  // TypeError: assignment to constant variable

However, if you were to declare a for loop variable that is not modified, const is allowed—precisely because a new variable is declared for each iteration. This is especially relevant in the case of for-of and for-in loops:

let i = 0;
for (const j = 7; i < 5; ++i) {
  console.log(j);
}
// 7, 7, 7, 7, 7

for (const key in {a: 1, b: 2}) {
  console.log(key);
}
// a, b

for (const value of [1,2,3,4,5]) {
  console.log(value);
}
// 1, 2, 3, 4, 5

Declaration Styles and Best Practices

The introduction of let and const in ECMAScript 6 bring objectively better tooling to the language in the form of increased precision of declaration scope and semantics. It is no secret that the bizarre behavior of var declarations caused the JavaScript community to pull its collective hair out for years as a result of all the problems it caused. In the wake of the introduction of these new keywords, there are some increasingly common patterns emerging that can improve code quality.

Don't Use var

With let and const, most developers will find that they no longer need to use var in their codebase anywhere. The patterns that emerge from restricting variable declaration to only let and const will serve to enforce higher codebase quality thanks to careful management of variable scope, declaration locality, and const correctness.

Prefer const Over let

Using const declarations allows the browser runtime to enforce constant variables, as well as for static code analysis tools to foresee illegal reassignment operations. Therefore, many developers feel it is to their advantage to, by default, declare variables as const unless they know they will need to reassign its value at some point. This allows for developers to more concretely reason about values that they know will never change, and also for quick detection of unexpected behavior in cases where the code execution attempts to perform an unanticipated value reassignment.

DATA TYPES

There are seven simple data types (also called primitive types) in ECMAScript: Undefined, Null, Boolean, Number, BigInt, String, and Symbol. There is also one complex data type called Object, which is an unordered list of name–value pairs. Because there is no way to define your own data types in ECMAScript, all values can be represented as one of these eight. Having only eight data types may seem like too few to fully represent data; however, ECMAScript's data types have dynamic aspects that make each single data type behave like several.

The typeof Operator

Because ECMAScript is loosely typed, there needs to be a way to determine the data type of a given variable. The typeof operator provides that information. Using the typeof operator on a value returns one of the following strings:

“undefined” if the value is undefined
“boolean” if the value is a Boolean
“string” if the value is a string
“number” if the value is a number
“object” if the value is an object (other than a function) or null
“function” if the value is a function
“symbol” if the value is a Symbol
“bigint” if the value is a BigInt

The typeof operator is called like this:

let message = "some string";
console.log(typeof message);   // "string"
console.log(typeof(message));  // "string"
console.log(typeof 95);        // "number"

In this example, both a variable (message) and a numeric literal are passed into the typeof operator. Note that because typeof is an operator and not a function, no parentheses are required (although they can be used).

Be aware there are a few cases where typeof seemingly returns a confusing but technically correct value. Calling typeof null returns “object,” as the special value null is considered to be an empty object reference.

The Undefined Type

The Undefined type has only one value, which is the special value undefined. When a variable is declared using var or let but not initialized, it is assigned the value of undefined as follows:

let message;
console.log(message == undefined);  // true

In this example, the variable message is declared without initializing it. When compared with the literal value of undefined, the two are equal. This example is identical to the following:

let message = undefined;
console.log(message == undefined);  // true

Here the variable message is explicitly initialized to be undefined. This is unnecessary because, by default, any uninitialized variable gets the value of undefined.

Note that a variable containing the value of undefined is different from a variable that hasn't been defined at all. Consider the following:

let message;   // this variable is declared but has a value of undefined

// make sure this variable isn't declared
// let age

console.log(message);  // "undefined"
console.log(age);      // causes an error

In this example, the first console.log displays the variable message, which is "undefined". In the second console.log, an undeclared variable called age is passed into the console.log() function, which causes an error because the variable hasn't been declared. Only one useful operation can be performed on an undeclared variable: you can call typeof on it (calling delete on an undeclared variable won't cause an error, but this isn't very useful and in fact throws an error in strict mode).

The typeof operator returns “undefined” when called on an uninitialized variable, but it also returns “undefined” when called on an undeclared variable, which can be a bit confusing. Consider this example:

let message;   // this variable is declared but has a value of undefined

// make sure this variable isn't declared
// let age

console.log(typeof message);  // "undefined"
console.log(typeof age);      // "undefined"

In both cases, calling typeof on the variable returns the string "undefined". Logically, this makes sense because no real operations can be performed with either variable even though they are technically very different.

The value undefined is falsy; therefore, you are able to more succinctly check for it wherever you might need to. Bear in mind, however, that many other possible values are also falsy, so be careful in scenarios where you need to test for an exact value of undefined rather than just a falsy value:

let message;   // this variable is declared but has a value of undefined
// 'age' is not declared

if (message) {
  // This block will not execute
}

if (!message) {
  // This block will execute
}

if (age) {
  // This will throw an error
}

The Null Type

The Null type is the second data type that has only one value: the special value null. Logically, a null value is an empty object pointer, which is why typeof returns “object” when it's passed a null value in the following example:

let car = null;
console.log(typeof car);   // "object"

When defining a variable that is meant to later hold an object, it is advisable to initialize the variable to null as opposed to anything else. That way, you can explicitly check for the value null to determine if the variable has been filled with an object reference at a later time, such as in this example:

if (car != null) {
  // do something with car
}

The value undefined is a derivative of null, so ECMA-262 defines them to be superficially equal as follows:

console.log(null == undefined);   // true

Using the equality operator (==) between null and undefined always returns true, though keep in mind that this operator converts its operands for comparison purposes (covered in detail later in this chapter).

Even though null and undefined are related, they have very different uses. As mentioned previously, you should never explicitly set the value of a variable to undefined, but the same does not hold true for null. Any time an object is expected but is not available, null should be used in its place. This helps to keep the paradigm of null as an empty object pointer and further differentiates it from undefined.

The null type is falsy; therefore, you are able to more succinctly check for it wherever you might need to. Bear in mind, however, that many other possible values are also falsy, so be careful in scenarios where you need to test for an exact value of null rather than just a falsy value:

let message = null;
let age;

if (message) {
  // This block will not execute
}

if (!message) {
  // This block will execute
}

if (age) {
  // This block will not execute
}

if (!age) {
  // This block will execute
}

The Boolean Type

The Boolean type is one of the most frequently used types in ECMAScript and has only two literal values: true and false. These values are distinct from numeric values, so true is not equal to 1, and false is not equal to 0. Assignment of Boolean values to variables is as follows:

let found = true;
let lost = false;

Note that the Boolean literals true and false are case–sensitive, so True and False (and other mixings of uppercase and lowercase) are valid as identifiers but not as Boolean values.

Though there are just two literal Boolean values, all types of values have Boolean equivalents in ECMAScript. To convert a value into its Boolean equivalent, the special Boolean() casting function is called, like this:

let message = "Hello world!";
let messageAsBoolean = Boolean(message);

In this example, the string message is converted into a Boolean value and stored in messageAsBoolean. The Boolean() casting function can be called on any type of data and will always return a Boolean value. The rules for when a value is converted to true or false depend on the data type as much as the actual value. The following table outlines the various data types and their specific conversions.

DATA TYPE	VALUES CONVERTED TO TRUE	VALUES CONVERTED TO FALSE
Boolean	`true`	`false`
String	Any nonempty string	"" (empty string)
Number	Any nonzero number (including infinity)	`0`, `NaN` (See the “NaN” section later in this chapter.)
Object	Any object	`null`
Undefined	n/a	`undefined`

These conversions are important to understand because flow-control statements, such as the if statement, automatically perform this Boolean conversion, as shown here:

let message = "Hello world!";
if (message) {
  console.log("Value is true");
}

In this example, the console.log will be displayed because the string message is automatically converted into its Boolean equivalent (true). It's important to understand what variable you're using in a flow-control statement because of this automatic conversion. Mistakenly using an object instead of a Boolean can drastically alter the flow of your application.

The Number Type

The ECMAScript Number data type uses the IEEE–754 format to represent both integers and floating-point values (also called double–precision values in some languages). To support the various types of numbers, there are several different number literal formats.

The most basic number literal format is that of a decimal integer, which can be entered directly as shown here:

let intNum = 55;  // integer

Integers can also be represented as binary (base 2), octal (base 8), or hexadecimal (base 16) literals. For a binary literal, the 0b prefix must be followed by a sequence of 1s and 0s:

let binaryNum1 = 0b110;  // binary for 6
let binaryNum2 = 0b333;  // invalid binary - SyntaxError

An octal literal can be defined both implicitly and explicitly. For the implicit declaration, the first digit must be a zero (0) followed by a sequence of octal digits (numbers 0 through 7). If a number out of this range is detected in the literal, then the leading zero is ignored and the number is treated as a decimal, as in the following examples:

let octalNum1 = 070;   // octal for 56
let octalNum2 = 079;   // invalid octal - interpreted as 79

An octal literal can also be defined explicitly, with a 0o prefix:

let octalNum3 = 0o70;  // octal for 56
let octalNum4 = 0o79;  // invalid octal – SyntaxError

Octal literals are invalid when running in strict mode and will cause the JavaScript engine to throw a syntax error. To create a hexadecimal literal, you must make the first two characters 0x (case insensitive), followed by any number of hexadecimal digits (0 through 9, and A through F). Letters may be in uppercase or lowercase. Here's an example:

let hexNum1 = 0xA;   // hexadecimal for 10
let hexNum2 = 0x1f;  // hexadecimal for 31

Numbers created using binary, octal, or hexadecimal format are treated as decimal numbers in all arithmetic operations.

Floating-Point Values

To define a floating-point value, you must include a decimal point and at least one number after the decimal point. Although an integer is not necessary before a decimal point, it is recommended. Here are some examples:

let floatNum1 = 1.1;
let floatNum2 = 0.1;
let floatNum3 = .1;   // valid, but not recommended

For very large or very small numbers, floating-point values can be represented using e-notation. E-notation is used to indicate a number that should be multiplied by 10 raised to a given power. The format of e-notation in ECMAScript is to have a number (integer or floating-point) followed by an uppercase or lowercase letter E, followed by the power of 10 to multiply by. Consider the following:

let floatNum = 3.125e7;  // equal to 31250000

In this example, floatNum is equal to 31,250,000 even though it is represented in a more compact form using e-notation. The notation essentially says, “Take 3.125 and multiply it by 10⁷.”

E-notation can also be used to represent very small numbers, such as 0.00000000000000003, which can be written more succinctly as 3e–17. By default, ECMAScript converts any floating-point value with at least six zeros after the decimal point into e-notation (for example, 0.0000003 becomes 3e–7).

Floating-point values are accurate up to 17 decimal places but are far less accurate in arithmetic computations than whole numbers. For instance, adding 0.1 and 0.2 yields 0.30000000000000004 instead of 0.3. These small rounding errors make it difficult to test for specific floating-point values. Consider this example:

if (a + b == 0.3) {      // avoid!
  console.log("You got 0.3.");
}

Here, the sum of two numbers is tested to see if it's equal to 0.3. This will work for 0.05 and 0.25 and for 0.15 and 0.15. But if applied to 0.1 and 0.2, as discussed previously, this test would fail. Therefore you should never test for specific floating-point values.

Numeric Separators

All numbers can use a single underscore as a numeric separator for increased readability. The underscore can appear as many times as needed in a number literal—the interpreter will silently ignore them:

let oneMillion = 1_000_000;
let binary = 0b0100_0000;
let float = 1_000.000_001;

The underscore cannot start or end a number literal, cannot reside next to a decimal, and cannot follow a leading 0:

let invalid1 = _101;  // ReferenceError, _101 interpreted as variable name
let invalid2 = 101_;  // SyntaxError
let invalid3 = 0_01;  // SyntaxError
let invalid4 = 1._4;  // SyntaxError

Range of Values

Not all numbers in the world can be represented in the ECMAScript Number data type because of memory constraints. The smallest number that can be represented in ECMAScript is stored in Number.MIN_VALUE and is 5e–324 on most browsers; the largest number is stored in Number.MAX_VALUE and is 1.7976931348623157e+308 on most browsers. If a calculation results in a number that cannot be represented by JavaScript's numeric range, the number automatically gets the special value of Infinity. Any negative number that can't be represented is –Infinity (negative infinity), and any positive number that can't be represented is simply Infinity (positive infinity).

If a calculation returns either positive or negative Infinity, that value cannot be used in any further calculations, because Infinity has no numeric representation with which to calculate. To determine if a value is finite (that is, it occurs between the minimum and the maximum), there is the isFinite() function. This function returns true only if the argument is between the minimum and the maximum values, as in this example:

let result = Number.MAX_VALUE + Number.MAX_VALUE;
console.log(isFinite(result));  // false

Though it is rare to do calculations that take values outside of the range of finite numbers, it is possible and should be monitored when doing very large or very small calculations.

NaN

There is a special numeric value called NaN, short for Not a Number, which is used to indicate when an operation intended to return a number has failed (as opposed to throwing an error). For example, taking the square root of a negative number typically causes an error in other programming languages, halting code execution. In ECMAScript, taking the square root of a negative number returns NaN, which allows other processing to continue.

The value NaN has a couple of unique properties. First, any operation involving NaN always returns NaN (for instance, NaN /10), which can be problematic in the case of multistep computations. Second, NaN is not equal to any value, including NaN. For example, the following returns false:

console.log(NaN == NaN);  // false

For this reason, ECMAScript provides the isNaN() function. This function accepts a single argument, which can be of any data type, to determine if the value is “not a number.” When a value is passed into isNaN(), an attempt is made to convert it into a number. Some nonnumerical values convert into numbers directly, such as the string “10” or a Boolean value. Any value that cannot be converted into a number causes the function to return true. Consider the following:

console.log(isNaN(NaN));     // true
console.log(isNaN(10));      // false - 10 is a number
console.log(isNaN("10"));    // false - can be converted to number 10
console.log(isNaN("blue"));  // true - cannot be converted to a number
console.log(isNaN(true));    // false - can be converted to number 1

This example tests five different values. The first test is on the value NaN itself, which, obviously, returns true. The next two tests use numeric 10 and the string “10,” which both return false because the numeric value for each is 10. The string “blue,” however, cannot be converted into a number, so the function returns true. The Boolean value of true can be converted into the number 1, so the function returns false.

Number Conversions

There are three functions to convert nonnumeric values into numbers: the Number() casting function, the parseInt() function, and the parseFloat() function. The first function, Number(), can be used on any data type; the other two functions are used specifically for converting strings to numbers. Each of these functions reacts differently to the same input.

The Number() function performs conversions based on these rules:

When applied to Boolean values, true and false get converted into 1 and 0, respectively.
When applied to numbers, the value is simply passed through and returned.
When applied to null, Number() returns 0.
When applied to undefined, Number() returns NaN.
When applied to strings, the following rules are applied:
- If the string contains only numeric characters, optionally preceded by a plus or minus sign, it is always converted to a decimal number, so Number(“1”) becomes 1, Number(“123”) becomes 123, and Number(“011”) becomes 11 (note: leading zeros are ignored).
- If the string contains a valid floating-point format, such as “1.1,” it is converted into the appropriate floating-point numeric value (once again, leading zeros are ignored).
- If the string contains a valid hexadecimal format, such as “0xf,” it is converted into an integer that matches the hexadecimal value.
- If the string is empty (contains no characters), it is converted to 0.
- If the string contains anything other than these previous formats, it is converted into NaN.
When applied to objects, the valueOf() method is called and the returned value is converted based on the previously described rules. If that conversion results in NaN, the toString() method is called and the rules for converting strings are applied.

Converting to numbers from various data types can get complicated, as indicated by the number of rules there are for Number(). Here are some concrete examples:

let num1 = Number("Hello world!");  // NaN
let num2 = Number("");              // 0
let num3 = Number("000011");        // 11
let num4 = Number(true);            // 1

In these examples, the string “Hello world” is converted into NaN because it has no corresponding numeric value, and the empty string is converted into 0. The string “000011” is converted to the number 11 because the initial zeros are ignored. Last, the value true is converted to 1.

Because of the complexities and oddities of the Number() function when converting strings, the parseInt() function is usually a better option when you are dealing with integers. The parseInt() function examines the string much more closely to see if it matches a number pattern. Leading white space in the string is ignored until the first non–white space character is found. If this first character isn't a number, the minus sign, or the plus sign, parseInt() always returns NaN, which means the empty string returns NaN (unlike with Number(), which returns 0). If the first character is a number, plus, or minus, then the conversion goes on to the second character and continues on until either the end of the string is reached or a nonnumeric character is found. For instance, “1234blue” is converted to 1234 because “blue” is completely ignored. Similarly, “22.5” will be converted to 22 because the decimal is not a valid integer character.

Assuming that the first character in the string is a number, the parseInt() function also recognizes the various integer formats (decimal, octal, and hexadecimal, as discussed previously). This means when the string begins with “0x,” it is interpreted as a hexadecimal integer; if it begins with “0” followed by a number, it is interpreted as an octal value.

Here are some conversion examples to better illustrate what happens:

let num1 = parseInt("1234blue");  // 1234
let num2 = parseInt("");          // NaN
let num3 = parseInt("0xA");       // 10 - hexadecimal
let num4 = parseInt(22.5);        // 22
let num5 = parseInt("70");        // 70 - decimal
let num6 = parseInt("0xf");       // 15 - hexadecimal

All of the different numeric formats can be confusing to keep track of, so parseInt() provides a second argument: the radix (number of digits). If you know that the value you're parsing is in hexadecimal format, you can pass in the radix 16 as a second argument and ensure that the correct parsing will occur, as shown here:

let num = parseInt("0xAF", 16);     // 175

In fact, by providing the hexadecimal radix, you can leave off the leading “0x” and the conversion will work as follows:

let num1 = parseInt("AF", 16);  // 175
let num2 = parseInt("AF");      // NaN

In this example, the first conversion occurs correctly, but the second conversion fails. The difference is that the radix is passed in on the first line, telling parseInt() that it will be passed a hexadecimal string; the second line sees that the first character is not a number and stops automatically.

Passing in a radix can greatly change the outcome of the conversion. Consider the following:

let num1 = parseInt("10", 2);   // 2 - parsed as binary
let num2 = parseInt("10", 8);   // 8 - parsed as octal
let num3 = parseInt("10", 10);  // 10 - parsed as decimal
let num4 = parseInt("10", 16);  // 16 - parsed as hexadecimal

Because leaving off the radix allows parseInt() to choose how to interpret the input, it's advisable to always include a radix to avoid errors.

The parseFloat() function works in a similar way to parseInt(), looking at each character starting in position 0. It also continues to parse the string until it reaches either the end of the string or a character that is invalid in a floating-point number. This means that a decimal point is valid the first time it appears, but a second decimal point is invalid and the rest of the string is ignored, resulting in “22.34.5” being converted to 22.34.

Another difference in parseFloat() is that initial zeros are always ignored. This function will recognize any of the floating-point formats discussed earlier, as well as the decimal format (leading zeros are always ignored). Hexadecimal numbers always become 0. Because parseFloat() parses only decimal values, there is no radix mode. A final note: if the string represents a whole number (no decimal point or only a zero after the decimal point), parseFloat() returns an integer. Here are some examples:

let num1 = parseFloat("1234blue");  // 1234 - integer
let num2 = parseFloat("0xA");       // 0
let num3 = parseFloat("22.5");      // 22.5
let num4 = parseFloat("22.34.5");   // 22.34
let num5 = parseFloat("0908.5");    // 908.5
let num6 = parseFloat("3.125e7");   // 31250000

The BigInt Type

The BigInt data type is a primitive for dealing with large integers that exceed Number.MAX_SAFE_INTEGER. Under the hood, the BigInt primitive allocates an object in memory to represent arbitrarily large integers that cannot fit inside a CPU register. Instead of the typical IEEE–754 64-bit format, the JavaScript engine represents one large number with a collection of smaller values that can fit into a CPU register. Each BigInt is a signed integer.

A BigInt can be created either by appending “n” to the end of an integer literal or with the BigInt() function:

let bigintA = 12345n;
let bigintB = BigInt(12345);
let bigintC = BigInt(0x12345);
let bigintD = BigInt("12345");
let bigintE = BigInt("0o12345");

As shown above, the BitInt() function can be passed a number literal (or string equivalent) in binary, octal, decimal, or hexadecimal format.

A BigInt is similar to a Number, but the two types cannot be mixed when using arithmetic or bitwise operators. Furthermore, a BigInt cannot be used with any built-in Math methods:

123n + 123n;       // ok

123 + 123n;        // TypeError
Math.round(123n);  // TypeError

Conversion

Integer values can be converted to and from the BigInt format, but because the underlying representation in memory is fundamentally different, a loss of precision may occur. The BigInt type is incompatible with non-integers:

123n === BigInt(123);  // true
123 === Number(123n);  // true

// Note loss of precision
Number(BigInt(10000000000054321));  // 10000000000054320
Number(54321n + BigInt(1E16));      // 10000000000054320

BigInt(0.5);  // RangeError

Operators

BigInt supports nearly all the arithmetic, unary, and bitwise operators used by the Number type. Note with bigintB that the remainder from a division operation is automatically rounded down:

let bigintA = 10n ** 2n;  // 100n
let bigintB = 100n / 3n;  // 33n
let bigintC = 16n | 8n;   // 24n
let bigintD = -8n + -8n;  // -16n

There are two operators that are not supported:

The zero-fill right shift >>> operator is not supported.
The unary + operator is not supported.

Although mixing Number and BigInt is not allowed with arithmetic and bitwise operators, you can still use comparison operators and sorting between the types:

4n> 3;  // true

[5n, 1, 3n].sort(); // [1, 3n, 5n]

Static Methods

BigInt features two static methods, asIntN and asUintN, for clamping integers. Clamping an integer means truncating it to a given number of least significant bits:

BigInt.asIntN(bits, bigint) clamps to a signed integer.
BigInt.asUintN(bits, biting) clamps to an unsigned integer.

A BigInt is represented as a two's complement number in memory, so clamping methods must be used carefully. As shown in the following examples, the output may be dramatically different than the input number even though the total number of bits is reduced:

// Clamps 00011000 to 1000
BigInt.asIntN(4, 24n);   // -8n
BigInt.asUintN(4, 24n);  // 8n

// Clamps 11111111 to 1111
BigInt.asIntN(4, -1n);   // -1n
BigInt.asUintN(4, -1n);  // 15n

// Clamps 00010000 to 10000
BigInt.asIntN(5, 16n);   // -16n

// Clamps 00010000 to 010000
BigInt.asIntN(6, 16n);   // 16n

JSON

BigInt does not support JSON serialization, but the built-in JSON global can be provided with replacer and reviver methods to convert in and out:

let data = {
  bigNumber: 1234n
};

JSON.stringify(data);  // TypeError

const replacer = (k, v) => typeof v === 'bigint' ? v.toString() : v;

JSON.stringify(data, replacer);
// {"bigNumber": "1234" }

const reviver = (k, v) => k === "bigNumber" ? BigInt(v) : v;

JSON.parse(`{"bigNumber": "1234"}`, reviver);
// { bigNumber: 1234n }

The String Type

The String data type represents a sequence of zero or more 16-bit Unicode characters. Strings can be delineated by either double quotes ("), single quotes ('), or backticks (`), so all of the following are legal:

let firstName = "John";
let middleName = 'Jacob';
let lastName = `Jingleheimerschmidt`

Unlike some languages in which using different quotes changes how the string is interpreted, there is no difference in the syntaxes in ECMAScript. Note, however, that a string beginning with a certain character must end with the same character. For example, the following will cause a syntax error:

let firstName = 'Alice";  // syntax error - quotes must match

Character Literals

The String data type includes several character literals to represent nonprintable or otherwise useful characters, as listed in the following table:

LITERAL	MEANING
`\n`	New line
`\t`	Tab
`\b`	Backspace
`\r`	Carriage return
`\f`	Form feed
`\\`	Backslash (\)
`\'`	Single quote (')—used when the string is delineated by single quotes. Example: 'He said, \'hey.\".
`\"`	Double quote (")—used when the string is delineated by double quotes. Example: "He said, \"hey.\"".
\`	Backtick (`)—used when the string is delineated by backticks. Example: `He said, \`hey.\``.
`\xnn`	A character represented by hexadecimal code nn (where n is a hexadecimal digit 0-F). Example: \x41 is equivalent to "A".
`\unnnn`	A Unicode character represented by the hexadecimal code *nnnn* (where n is a hexadecimal digit 0-F). Example: \u03a3 is equivalent to the Greek character Σ.

These character literals can be included anywhere with a string and will be interpreted as if they were a single character, as shown here:

let text = "This is the letter sigma: \u03a3.";

In this example, the variable text is 28 characters long even though the escape sequence is 6 characters long. The entire escape sequence represents a single character, so it is counted as such.

The length of any string can be returned by using the length property, as follows:

console.log(text.length);  // 28

This property returns the number of 16-bit characters in the string.

The Nature of Strings

Strings are immutable in ECMAScript, meaning that once they are created, their values cannot change. To change the string held by a variable, the original string must be destroyed and the variable filled with another string containing a new value, like this:

let lang = "Java";
lang = lang + "Script";

Here, the variable lang is defined to contain the string “Java.” On the next line, lang is redefined to combine “Java” with “Script,” making its value “JavaScript.” This happens by creating a new string with enough space for 10 characters and then filling that string with “Java” and “Script.” The last step in the process is to destroy the original string “Java” and the string “Script,” because neither is necessary anymore.

Converting to a String

There are two ways to convert a value into a string. The first is to use the toString() method that almost every value has. This method's only job is to return the string equivalent of the value. Consider this example:

let age = 11;
let ageAsString = age.toString();      // the string "11"
let found = true;
let foundAsString = found.toString();  // the string "true"

The toString() method is available on values that are numbers, Booleans, objects, and strings. (Yes, each string has a toString() method that simply returns a copy of itself.) If a value is null or undefined, this method is not available.

In most cases, toString() doesn't have any arguments. However, when used on a number value, toString() actually accepts a single argument: the radix in which to output the number. By default, toString() always returns a string that represents the number as a decimal, but by passing in a radix, toString() can output the value in binary, octal, hexadecimal, or any other valid base, as in this example:

let num = 10;
console.log(num.toString());     // "10"
console.log(num.toString(2));    // "1010"
console.log(num.toString(8));    // "12"
console.log(num.toString(10));   // "10"
console.log(num.toString(16));   // "a"

This example shows how the output of toString() can change for numbers when providing a radix. The value 10 can be output into any number of numeric formats. Note that the default (with no argument) is the same as providing a radix of 10.

If you're not sure that a value isn't null or undefined, you can use the String() casting function, which always returns a string regardless of the value type. The String() function follows these rules:

If the value has a toString() method, it is called (with no arguments) and the result is returned.
If the value is null, “null” is returned.
If the value is undefined, “undefined” is returned.

Consider the following:

let value1 = 10;
let value2 = true;
let value3 = null;
let value4;

console.log(String(value1));   // "10"
console.log(String(value2));   // "true"
console.log(String(value3));   // "null"
console.log(String(value4));   // "undefined"

Here, four values are converted into strings: a number, a Boolean, null, and undefined. The result for the number and the Boolean are the same as if toString() were called. Because toString() isn't available on null and undefined, the String() method simply returns literal text for those values.

Template Literals

It is also possible to define strings using template literals. This is accomplished using the backtick (`) delimiter. Unlike their single and double quoted counterparts, template literals respect new line characters, and can be defined spanning multiple lines:

let myMultiLineString = 'first line\nsecond line';
let myMultiLineTemplateLiteral = `first line
second line`;

console.log(myMultiLineString);
// first line
// second line"

console.log(myMultiLineTemplateLiteral);
// first line
// second line

console.log(myMultiLineString === myMultiLinetemplateLiteral);   // true

As the name suggests, template literals are especially useful when defining templates, such as HTML:

let pageHTML = `
<div>
<a href="#">
    <span>Jake</span>
  </a>
</div>`;

Because template literals will exactly match the whitespace inside the backticks, special care will need to be applied when defining them. A correctly formatted template string may appear to have improper indentation:

// This template literal has 25 spaces following the line return character
let myTemplateLiteral = `first line
                         second line`;
console.log(myTemplateLiteral.length);  // 47

// This template literal begins with a line return character
let secondTemplateLiteral = `
first line
second line`;
console.log(secondTemplateLiteral[0] === '\n'); // true

// This template literal has no unexpected whitespace characters
let thirdTemplateLiteral = `first line
second line`;
console.log(thirdTemplateLiteral[0]);
// first line
// second line

Interpolation

One of the most useful features of template literals is their support for interpolation, which allows you to insert values at one or more places inside a single unbroken definition. Technically, template literals aren't strings, they are special JavaScript syntactical expressions that evaluate into strings. Template literals are evaluated immediately when they are defined and converted into a string instance, and any interpolated variables will be drawn from its immediate scope.

This can be accomplished using a JavaScript expression inside ${}:

let value = 5;
let exponent = 'second';

// Formerly, interpolation was accomplished as follows:
let interpolatedString =
  value + ' to the ' + exponent + ' power is ' + (value * value);

// The same thing accomplished with template literals:
let interpolatedTemplateLiteral =
  `${ value } to the ${ exponent } power is ${ value * value }`;

console.log(interpolatedString);           // 5 to the second power is 25
console.log(interpolatedTemplateLiteral);  // 5 to the second power is 25

The value being interpolated will eventually be coerced into a string, but any JavaScript expression can safely be interpolated. Nesting template strings is safe with no escaping required:

console.log(`Hello, ${ `World` }!`);  // Hello, World!

String() is invoked to coerce the expression result into a string:

let foo = { toString: () => 'World' };
console.log(`Hello, ${ foo }!`);      // Hello, World!

Invoking functions and methods inside interpolated expressions is allowed:

function capitalize(word) {
  return `${ word[0].toUpperCase() }${ word.slice(1) }`;
}
console.log(`${ capitalize('hello') }, ${ capitalize('world') }!`);  // Hello, World!

Additionally, templates can safely interpolate their previous value:

let value = '';
function append() {
  value = `${value}abc`
  console.log(value);
}
append();  // abc
append();  // abcabc
append();  // abcabcabc

Template Literal Tag Functions

Template literals also support the ability to define tag functions, which are able to define custom interpolation behavior. The tag function is passed the individual pieces after the template has been split by the interpolation token and after the expressions have been evaluated.

A tag function is defined as a regular function and is applied to a template literal by being prepended to it, as shown in the code that follows. The tag function will be passed the template literal split into its pieces: the first argument is an array of the raw strings, and the remaining arguments are the results of the evaluated expressions. The return value of this function will be the string evaluated from the template literal.

This is best demonstrated by example:

let a = 6;
let b = 9;

function simpleTag(strings, aValExpression, bValExpression, sumExpression) {
  console.log(strings);
  console.log(aValExpression);
  console.log(bValExpression);
  console.log(sumExpression);

  return 'foobar';
}

let untaggedResult = `${ a } + ${ b } = ${ a + b }`;
let taggedResult = simpleTag`${ a } + ${ b } = ${ a + b }`;
// ["", " + ", " = ", ""]
// 6
// 9
// 15

console.log(untaggedResult);  // "6 + 9 = 15"
console.log(taggedResult);    // "foobar"

Because there are a variable number of expression arguments, using the spread operator to combine them into a single collection is usually prudent:

let a = 6;
let b = 9;

function simpleTag(strings, ...expressions) {
  console.log(strings);
  for(const expression of expressions) {
    console.log(expression);
  }

  return 'foobar';
}
let taggedResult = simpleTag`${ a } + ${ b } = ${ a + b }`;
// ["", " + ", " = ", ""]
// 6
// 9
// 15

console.log(taggedResult);  // "foobar"

For a template literal with n interpolated values, the number of expression arguments to the tag function will always be n, and the number of string pieces in the first argument will always be exactly n + 1. Therefore, if you wished to “zip” the strings and the evaluated expressions together into the default returned string, you could do so as follows:

let a = 6;
let b = 9;

function zipTag(strings, ...expressions) {
  return strings[0] +
         expressions.map((e, i) => `${e}${strings[i + 1]}`)
                    .join('');
}

let untaggedResult =     `${ a } + ${ b } = ${ a + b }`;
let taggedResult = zipTag`${ a } + ${ b } = ${ a + b }`;

console.log(untaggedResult);  // "6 + 9 = 15"
console.log(taggedResult);    // "6 + 9 = 15"

Raw Strings

It is also possible to use template literals to give you access to the raw template literal contents without being converted into actual character representations, such as a new line or Unicode character. This can be done by using the String.raw tag function, which is available by default.

// Unicode demo
// \u00A9 is the copyright symbol
console.log(`\u00A9`);            // ©
console.log(String.raw`\u00A9`);  // \u00A9

// Newline demo
console.log(`first line\nsecond line`);
// first line
// second line

console.log(String.raw`first line\nsecond line`);  // "first line\nsecond line"

// This does not work for actual newline characters: they do not
// undergo conversion from their plaintext escaped equivalents
console.log(`first line
second line`);
// first line
// second line

console.log(String.raw`first line
second line`);
// first line
// second line

The raw values are also available as a property on each element in the string piece collection inside the tag function:

function printRaw(strings) {
  console.log('Actual characters:');
  for (const string of strings) {
    console.log(string);
  }

  console.log('Escaped characters;');
  for (const rawString of strings.raw) {
    console.log(rawString);
  }
}

printRaw`\u00A9${ 'and' }\n`;
// Actual characters:
// ©
// (newline)
// Escaped characters:
// \u00A9
// \n

The Symbol Type

Symbols are primitive values, and symbol instances are unique and immutable. The purpose of a symbol is to be a guaranteed unique identifier for object properties that does not risk property collision.

Although they may seem to share some similarities with private properties, symbols are not intended to offer private property behavior (especially because the Object API offers methods to easily discover symbol properties). Instead, symbols are intended to be used as unique tokens that can be used to key special properties with something other than a string.

Basic Symbol Use

Symbols are instantiated using the Symbol() function. Because it is its own primitive type, the typeof operator will identify a symbol as symbol.

let sym = Symbol();
console.log(typeof sym);  // symbol

When invoking the function, you can provide an optional string that can be used for identifying the symbol instance when debugging. The string you provide is totally separate from the symbol's definition or identity:

let genericSymbol = Symbol();
let otherGenericSymbol = Symbol();

let fooSymbol = Symbol('foo');
let otherFooSymbol = Symbol('foo');

console.log(genericSymbol == otherGenericSymbol);  // false
console.log(fooSymbol == otherFooSymbol);          // false

Symbols do not have a literal string syntax, and this is central to their purpose. The specification governing how symbols operate allows you to create a new Symbol instance and use it to key a new property on an object with the guarantee that you will not be overwriting an existing object property—irrespective of whether it is using a string or symbol as a key.

let genericSymbol = Symbol();
console.log(genericSymbol);  // Symbol()

let fooSymbol = Symbol('foo');
console.log(fooSymbol);      // Symbol(foo);

Importantly, the Symbol() function cannot be used with the new keyword. The purpose of this is to avoid symbol object wrappers, as is possible with Boolean, String, and Number, which support constructor behavior and instantiate a primitive wrapper object:

let myBoolean = new Boolean();
console.log(typeof myBoolean);  // "object"

let myString = new String();
console.log(typeof myString);   // "object"

let myNumber = new Number();
console.log(typeof myNumber);   // "object"

let mySymbol = new Symbol();  // TypeError: Symbol is not a constructor

Should you want to utilize an object wrapper, you can make use of the Object() function:

let mySymbol = Symbol();
let myWrappedSymbol = Object(mySymbol);
console.log(typeof myWrappedSymbol);  // "object"

Using the Global Symbol Registry

In scenarios where different parts of the runtime would like to share and reuse a symbol instance, it is possible to create and reuse symbols in a string-keyed global symbol registry.

This behavior can be achieved using Symbol.for():

let fooGlobalSymbol = Symbol.for('foo');
console.log(typeof fooGlobalSymbol);  // symbol

Symbol.for() is an idempotent operation for each string key. The first time it is called with a given string, it will check the global runtime registry, find that no symbol exists, generate a new symbol instance, and add it to the registry. Additional invocations with the same string key will check the global runtime registry, find that a symbol does exist for that string, and return that symbol instance instead.

let fooGlobalSymbol = Symbol.for('foo');          // creates new symbol
let otherFooGlobalSymbol = Symbol.for('foo');     // reuses existing symbol

console.log(fooGlobalSymbol === otherFooGlobalSymbol);  // true

Symbols defined in the global registry are totally distinct from symbols created using Symbol(), even if they share a description:

let localSymbol = Symbol('foo');
let globalSymbol = Symbol.for('foo');

console.log(localSymbol === globalSymbol);  // false

The global registry requires string keys, so anything you provide as an argument to Symbol.for() will be converted to a string. Additionally, the key used for the registry will also be used as the symbol description.

let emptyGlobalSymbol = Symbol.for();
console.log(emptyGlobalSymbol);   // Symbol(undefined)

It is possible to check against the global registry using Symbol.keyFor(), which accepts a symbol and will return the global string key for that global symbol, or undefined if the symbol is not a global symbol.

// Create global symbol
let s = Symbol.for('foo');
console.log(Symbol.keyFor(s));   // foo

// Create regular symbol
let s2 = Symbol('bar');
console.log(Symbol.keyFor(s2));  // undefined

Using Symbol.keyFor() with a non-symbol will throw a TypeError:

Symbol.keyFor(123);  // TypeError: 123 is not a symbol

Using Symbols as Properties

Anywhere you can normally use a string or number property, you can also use a symbol. This includes object literal properties and Object.defineProperty()/Object.defineProperties(). An object literal can only use a symbol as a property inside the computed property syntax.

let s1 = Symbol('foo'),
    s2 = Symbol('bar'),
    s3 = Symbol('baz'),
    s4 = Symbol('qux');

let o = {
  [s1]: 'foo val'
};
// Also valid:   o[s1] = 'foo val';

console.log(o);
// {Symbol(foo): foo val}

Object.defineProperty(o, s2, {value: 'bar val'});

console.log(o);
// {Symbol(foo): foo val, Symbol(bar): bar val}

Object.defineProperties(o, {
  [s3]: {value: 'baz val'},
  [s4]: {value: 'qux val'}
});

console.log(o);
// {Symbol(foo): foo val, Symbol(bar): bar val,
//  Symbol(baz): baz val, Symbol(qux): qux val}

Just as Object.getOwnPropertyNames() returns an array of regular properties on an object instance, Object.getOwnPropertySymbols() returns an array of symbol properties on an object instance. The return values of these two methods are mutually exclusive. Object.getOwnPropertyDescriptors() will return an object containing both regular and symbol property descriptors. Reflect.ownKeys() will return both types of keys:

let s1 = Symbol('foo'),
    s2 = Symbol('bar');

let o = {
  [s1]: 'foo val',
  [s2]: 'bar val',
  baz: 'baz val',
  qux: 'qux val'
};

console.log(Object.getOwnPropertySymbols(o));
// [Symbol(foo), Symbol(bar)]

console.log(Object.getOwnPropertyNames(o));
// ["baz", "qux"]

console.log(Object.getOwnPropertyDescriptors(o));
// {baz: {...}, qux: {...}, Symbol(foo): {...}, Symbol(bar): {...}}

console.log(Reflect.ownKeys(o));
// ["baz", "qux", Symbol(foo), Symbol(bar)]

Because a property counts as a reference to that symbol in memory, Symbols are not lost if directly created and used as properties. However, declining to keep an explicit reference to a property means that traversing all the object's symbol properties will be required to recover the property key:

let o = {
  [Symbol('foo')]: 'foo val',
  [Symbol('bar')]: 'bar val'
};

console.log(o);
// {Symbol(foo): "foo val", Symbol(bar): "bar val"}

let barSymbol = Object.getOwnPropertySymbols(o)
              .find((symbol) => symbol.toString().match(/bar/));

console.log(barSymbol);
// Symbol(bar)

Well-Known Symbols

ECMAScript includes a collection of well-known symbols that are used throughout the language to expose internal language behaviors for direct access, overriding, or emulating. These well-known symbols exist as string properties on the Symbol factory function.

One of the primary utilities of these well-known symbols is redefining them as to alter the behavior of the native language constructs. For example, because it is known how the for-of loop will use the Symbol.iterator property on whatever object is provided to it, it is possible to provide a custom definition of Symbol.iterator's value in a custom object in order to control how for-of behaves when provided with that object.

There is nothing special about these well-known symbols, they are regular string properties on the Symbol global that key an instance of a symbol. Each well-defined symbol property is non-writeable, non-enumerable, and non-configurable.

Symbol.asyncIterator

Per the ECMAScript specification, this symbol is used as a property for “A method that returns the default AsyncIterator for an object. Called by the semantics of the for-await-of statement.” It is used to identify the function that implements the asynchronous iterator API.

Language constructs such as the for-await-of loop make use of this function to perform asynchronous iteration. They will invoke the function keyed by Symbol.asyncIterator and expect it to return an object which implements the iterator API. In many cases, this will take the form of an AsyncGenerator, an object which implements this API:

class Foo {
  async *[Symbol.asyncIterator]() {}
}

let f = new Foo();

console.log(f[Symbol.asyncIterator]());
// AsyncGenerator {<suspended>}

Specifically, the object produced by the Symbol.asyncIterator function should sequentially produce a Promise via its next() method. This can be through explicit next() method definition or implicitly through an async generator function:

class Emitter {
  constructor(max) {
    this.max = max;
    this.asyncIdx = 0;
  }

  async *[Symbol.asyncIterator]() {
    while(this.asyncIdx < this.max) {
      yield new Promise((resolve) => resolve(this.asyncIdx++));
    }
  }
}

async function asyncCount() {
  let emitter = new Emitter(5);

  for await(const x of emitter) {
    console.log(x);
  }
}

asyncCount();
// 0
// 1
// 2
// 3
// 4

Symbol.hasInstance

This symbol is used as a property for a method that determines if a constructor object recognizes an object as one of the constructor's instances and is called by the semantics of the instanceof operator. The instanceof operator provides a way of determining if an object instance has a prototype in its prototype chain. Typical use of the instanceof is as follows:

function Foo() {}
let f = new Foo();
console.log(f instanceof Foo);  // true

class Bar {}
let b = new Bar();
console.log(b instanceof Bar);  // true

In ES6, the instanceof operator is using a Symbol.hasInstance function to evaluate this relationship. The Symbol.hasInstance keys a function which performs the same behavior but with the operands reversed:

function Foo() {}
let f = new Foo();
console.log(Foo[Symbol.hasInstance](f));  // true

class Bar {}
let b = new Bar();
console.log(Bar[Symbol.hasInstance](b));  // true

This property is defined on the Function prototype, and therefore it is automatically available by default to all function and class definitions. Because the instanceof operator will seek the property definition on the prototype chain like any other property, it is possible to redefine the function on an inherited class as a static method:

class Bar {}
class Baz extends Bar {
  static [Symbol.hasInstance]() {
    return false;
  }
}

let b = new Baz();
console.log(Bar[Symbol.hasInstance](b));  // true
console.log(b instanceof Bar);            // true
console.log(Baz[Symbol.hasInstance](b));  // false
console.log(b instanceof Baz);            // false

Symbol.isConcatSpreadable

Per the ECMAScript specification, this symbol is used as a property for “A Boolean valued property that if true indicates that an object should be flattened to its array elements by Array.prototype.concat().” The Array.prototype.concat method in ES6 will select how to join an array-like object to the array instance based on the type of object it is passed. The value of Symbol.isConcatSpreadable allows you to override this behavior.

Array objects by default will be flattened into the existing array; a value of false or falsy value will append the entire object to the array. Array-like objects by default will be appended to the array; a value of true or truthy value will flatten the array-like object into the array instance. Other objects which are not array-like will be ignored when Symbol.isConcatSpreadable is set to true.

let initial = ['foo'];

let array = ['bar'];
console.log(array[Symbol.isConcatSpreadable]);  // undefined
console.log(initial.concat(array));             // ['foo', 'bar']
array[Symbol.isConcatSpreadable] = false;
console.log(initial.concat(array));             // ['foo', Array(1)]

let arrayLikeObject = { length: 1, 0: 'baz' };
console.log(arrayLikeObject[Symbol.isConcatSpreadable]);  // undefined
console.log(initial.concat(arrayLikeObject));             // ['foo', {...}]
arrayLikeObject[Symbol.isConcatSpreadable] = true;
console.log(initial.concat(arrayLikeObject));             // ['foo', 'baz']

let otherObject = new Set().add('qux');
console.log(otherObject[Symbol.isConcatSpreadable]);  // undefined
console.log(initial.concat(otherObject));             // ['foo', Set(1)]
otherObject[Symbol.isConcatSpreadable] = true;
console.log(initial.concat(otherObject));             // ['foo']

Symbol.iterator

This symbol is used as a property for a method that returns the default iterator for an object and is called by the semantics of the for-of statement. It is used to identify the function that implements the iterator API.

Language constructs such as the for-of loop make use of this function to perform iteration. They will invoke the function keyed by Symbol.iterator and expect it to return an object which implements the iterator API. In many cases, this will take the form of a Generator, an object which implements this API:

class Foo {
  *[Symbol.iterator]() {}
}

let f = new Foo();

console.log(f[Symbol.iterator]());
// Generator {<suspended>}

Specifically, the object produced by the Symbol.iterator function should sequentially produce values via its next() method. This can be through explicit next() method definition or implicitly through a generator function:

class Emitter {
  constructor(max) {
    this.max = max;
    this.idx = 0;
  }

  *[Symbol.iterator]() {
    while(this.idx < this.max) {
      yield this.idx++;
    }
  }
}

function count() {
  let emitter = new Emitter(5);

  for (const x of emitter) {
    console.log(x);
  }
}

count();
// 0
// 1
// 2
// 3
// 4

Symbol.match

This symbol is used as a property for a regular expression method that matches the regular expression against a string and is called by the String.prototype.match() method. The String.prototype.match() method will use the function keyed by Symbol.match to evaluate the expression. The regular expression prototype has this function defined by default, and therefore all regular expression instances are valid parameters to the String method by default:

console.log(RegExp.prototype[Symbol.match]);
// Æ' [Symbol.match]() { [native code] }

console.log('foobar'.match(/bar/));
//  ["bar", index: 3, input: "foobar", groups: undefined]

Providing something other than a regular expression to this method will cause it to be converted to a RegExp object. If you wish to circumvent this behavior and have the method use the parameter directly, it is possible to pass something other than a regular expression instance to the match() method by defining a Symbol.match function to supplant the behavior that would otherwise be exhibited by the regular expression. This function has a single parameter which is the string instance upon which match() is invoked. The return value is unrestricted:

class FooMatcher {
  static [Symbol.match](target) {
    return target.includes('foo');
  }
}

console.log('foobar'.match(FooMatcher));  // true
console.log('barbaz'.match(FooMatcher));  // false

class StringMatcher {
  constructor(str) {
    this.str = str;
  }

  [Symbol.match](target) {
    return target.includes(this.str);
  }
}

console.log('foobar'.match(new StringMatcher('foo')));  // true
console.log('barbaz'.match(new StringMatcher('qux')));  // false

Symbol.replace

This symbol is used as a property for a regular expression method that replaces matched substrings of a string and is called by the String.prototype.replace() method. The String.prototype.replace() method will use the function keyed by Symbol.replace to evaluate the expression. The regular expression prototype has this function defined by default, and therefore all regular expression instances are valid parameters to the String method by default:

console.log(RegExp.prototype[Symbol.replace]);
// Æ' [Symbol.replace]() { [native code] }

console.log('foobarbaz'.replace(/bar/, 'qux'));
// 'fooquxbaz'

Providing something other than a regular expression to this method will cause it to be converted to a RegExp object. If you wish to circumvent this behavior and have the method use the parameter directly, it is possible to pass something other than a regular expression instance to the replace() method by defining a Symbol.replace function to supplant the behavior that would otherwise be exhibited by the regular expression. This function has two parameters, the string instance upon which replace() is invoked and the replacement string. The return value is unrestricted:

class FooReplacer {
  static [Symbol.replace](target, replacement) {
    return target.split('foo').join(replacement);
  }
}

console.log('barfoobaz'.replace(FooReplacer, 'qux'));
// "barquxbaz"

class StringReplacer {
  constructor(str) {
    this.str = str;
  }

  [Symbol.replace](target, replacement) {
    return target.split(this.str).join(replacement);
  }
}

console.log('barfoobaz'.replace(new StringReplacer('foo'), 'qux'));
// "barquxbaz"

Symbol.search

This symbol is used as a property for a regular expression method that returns the index within a string that matches the regular expression and is called by the String.prototype.search() method. The String.prototype.search() method will use the function keyed by Symbol.search to evaluate the expression. The regular expression prototype has this function defined by default, and therefore all regular expression instances are valid parameters to the String method by default:

console.log(RegExp.prototype[Symbol.search]);
// Æ' [Symbol.search]() { [native code] }

console.log('foobar'.search(/bar/));
// 3

Providing something other than a regular expression to this method will cause it to be converted to a RegExp object. If you wish to circumvent this behavior and have the method use the parameter directly, it is possible to pass something other than a regular expression instance to the search() method by defining a Symbol.search function to supplant the behavior that would otherwise be exhibited by the regular expression. This function has a single parameter which is the string instance upon which search() is invoked. The return value is unrestricted:

class FooSearcher {
  static [Symbol.search](target) {
    return target.indexOf('foo');
  }
}

console.log('foobar'.search(FooSearcher));  // 0
console.log('barfoo'.search(FooSearcher));  // 3
console.log('barbaz'.search(FooSearcher));  // -1

class StringSearcher {
  constructor(str) {
    this.str = str;
  }

  [Symbol.search](target) {
    return target.indexOf(this.str);
  }
}

console.log('foobar'.search(new StringSearcher('foo')));  // 0
console.log('barfoo'.search(new StringSearcher('foo')));  // 3
console.log('barbaz'.search(new StringSearcher('qux')));  // -1

Symbol.species

This symbol is used as a property for a function valued property that is the constructor function that is used to create derived objects. This is most commonly used for build-in types which expose methods that instantiate derived objects for the return value of an instance method. Defining a static getter method with Symbol.species allows you to override the prototype definition for the newly created instance:

class Bar extends Array {}
class Baz extends Array {
  static get [Symbol.species]() {
    return Array;
  }
}

let bar = new Bar();
console.log(bar instanceof Array);  // true
console.log(bar instanceof Bar);    // true
bar = bar.concat('bar');
console.log(bar instanceof Array);  // true
console.log(bar instanceof Bar);    // true

let baz = new Baz();
console.log(baz instanceof Array);  // true
console.log(baz instanceof Baz);    // true
baz = baz.concat('baz');
console.log(baz instanceof Array);  // true
console.log(baz instanceof Baz);    // false

Symbol.split

This symbol is used as a property for a regular expression method that splits a string at the indices that match the regular expression and is called by the String.prototype.split() method. The String.prototype.split() method will use the function keyed by Symbol.split to evaluate the expression. The regular expression prototype has this function defined by default, and therefore all regular expression instances are valid parameters to the String method by default:

console.log(RegExp.prototype[Symbol.split]);
// Æ' [Symbol.split]() { [native code] }

console.log('foobarbaz'.split(/bar/));
// ['foo', 'baz']

Providing something other than a regular expression to this method will cause it to be converted to a RegExp object. If you wish to circumvent this behavior and have the method use the parameter directly, it is possible to pass something other than a regular expression instance to the split() method by defining a Symbol.split function to supplant the behavior that would otherwise be exhibited by the regular expression. This function has a single parameter which is the string instance upon which split() is invoked. The return value is unrestricted:

class FooSplitter {
  static [Symbol.split](target) {
    return target.split('foo');
  }
}

console.log('barfoobaz'.split(FooSplitter));
// ["bar", "baz"]

class StringSplitter {
  constructor(str) {
    this.str = str;
  }

  [Symbol.split](target) {
    return target.split(this.str);
  }
}

console.log('barfoobaz'.split(new StringSplitter('foo')));
// ["bar", "baz"]

Symbol.toPrimitive

This symbol is used as a property for a method that converts an object to a corresponding primitive value and is called by the ToPrimitive abstract operation. There are a number of built-in operations which will attempt to coerce an object into a primitive value: a string, a number, or an unspecified primitive type. For a custom object instance, it is possible to divert this behavior by defining a function on the instance's Symbol.toPrimitive property.

Based on a string parameter provided to the function (either string, number, or default), you are able to control the returned primitive:

class Foo {}
let foo = new Foo();

console.log(3 + foo);       // "3[object Object]"
console.log(3 - foo);       // NaN
console.log(String(foo));   // "[object Object]"

class Bar {
  constructor() {
    this[Symbol.toPrimitive] = function(hint) {
      switch (hint) {
        case 'number':
          return 3;
        case 'string':
          return 'string bar';
        case 'default':
        default:
          return 'default bar';
      }
    }
  }
}
let bar = new Bar();

console.log(3 + bar);       // "3default bar"
console.log(3 - bar);       // 0
console.log(String(bar));   // "string bar"

Symbol.toStringTag

This symbol is used as a property for “A String valued property that is used in the creation of the default string description of an object. Accessed by the built-in method Object.prototype.toString().”

Object identification via the toString() method will retrieve the instance identifier specified by Symbol.toStringTag, defaulting to Object. Built-in types have this value already specified, but custom class instances require explicit definition:

let s = new Set();

console.log(s);                      // Set(0) {}
console.log(s.toString());           // [object Set]
console.log(s[Symbol.toStringTag]);  // Set

class Foo {}
let foo = new Foo();

console.log(foo);                      // Foo {}
console.log(foo.toString());           // [object Object]
console.log(foo[Symbol.toStringTag]);  // undefined

class Bar {
  constructor() {
    this[Symbol.toStringTag] = 'Bar';
  }
}
let bar = new Bar();

console.log(bar);                      // Bar {}
console.log(bar.toString());           // [object Bar]
console.log(bar[Symbol.toStringTag]);  // Bar

Symbol.unscopables

Per the ECMAScript specification, this symbol is used as a property for “An object valued property whose own and inherited property names are property names that are excluded from the with environment bindings of the associated object.” Setting this symbol so it keys an object mapping a corresponding property to true will prevent a with environment binding, as shown here:

let o = { foo: 'bar' };

with (o) {
  console.log(foo);  // bar
}

o[Symbol.unscopables] = {
  foo: true
};

with (o) {
  console.log(foo);  // ReferenceError
}

The Object Type

Objects in ECMAScript start out as nonspecific groups of data and functionality. Objects are created by using the new operator followed by the name of the object type to create. Developers create their own objects by creating instances of the Object type and adding properties and/or methods to it, as shown here:

let o = new Object();

This syntax is similar to Java, although ECMAScript requires parentheses to be used only when providing arguments to the constructor. If there are no arguments, as in the following example, then the parentheses can be omitted safely (though that's not recommended):

let o = new Object;  // legal, but not recommended

Instances of Object aren't very useful on their own, but the concepts are important to understand because, similar to java.lang.Object in Java, the Object type in ECMAScript is the base from which all other objects are derived. All of the properties and methods of the Object type are also present on other, more specific objects.

Each Object instance has the following properties and methods:

constructor—The function that was used to create the object. In the previous example, the constructor is the Object() function.
hasOwnProperty(propertyName)—Indicates if the given property exists on the object instance (not on the prototype). The property name must be specified as a string (for example, o.hasOwnProperty("name")).
isPrototypeof(object)—Determines if the object is a prototype of another object.
propertyIsEnumerable(propertyName)—Indicates if the given property can be enumerated using the for-in statement (discussed later in this chapter). As with hasOwnProperty(), the property name must be a string.
toLocaleString()—Returns a string representation of the object that is appropriate for the locale of execution environment.
toString()—Returns a string representation of the object.
valueOf()—Returns a string, number, or Boolean equivalent of the object. It often returns the same value as toString().

Because Object is the base for all objects in ECMAScript, every object has these base properties and methods.

OPERATORS

ECMA-262 describes a set of operators that can be used to manipulate data values. The operators range from mathematical operations (such as addition and subtraction) and bitwise operators to relational operators and equality operators. Operators are unique in ECMAScript in that they can be used on a wide range of values, including strings, numbers, Booleans, and even objects. When used on objects, operators typically call the valueOf() and/or toString() method to retrieve a value they can work with.

Unary Operators

Operators that work on only one value are called unary operators. They are the simplest operators in ECMAScript.

Increment/Decrement

The increment and decrement operators are taken directly from C and come in two versions: prefix and postfix. The prefix versions of the operators are placed before the variable they work on; the postfix ones are placed after the variable. To use a prefix increment, which adds 1 to a numeric value, you place two plus signs (++) in front of a variable like this:

let age = 29;
++age;

In this example, the prefix increment changes the value of age to 30 (adding 1 to its previous value of 29). This is effectively equal to the following:

let age = 29;
age = age + 1;

The prefix decrement acts in a similar manner, subtracting 1 from a numeric value. To use a prefix decrement, place two minus signs (--) before a variable, as shown here:

let age = 29;
--age;

Here the age variable is decremented to 28 (subtracting 1 from 29).

When using either a prefix increment or a prefix decrement, the variable's value is changed before the statement is evaluated. (In computer science, this is usually referred to as having a side effect.) Consider the following:

let age = 29;
let anotherAge = --age + 2;

console.log(age);         // 28
console.log(anotherAge);  // 30

In this example, the variable anotherAge is initialized with the decremented value of age plus 2. Because the decrement happens first, age is set to 28, and then 2 is added, resulting in 30.

The prefix increment and decrement are equal in terms of order of precedence in a statement and are therefore evaluated left to right. Consider this example:

let num1 = 2;
let num2 = 20;
let num3 = --num1 + num2;
let num4 = num1 + num2;
console.log(num3);  // 21
console.log(num4);  // 21

Here, num3 is equal to 21 because num1 is decremented to 1 before the addition occurs. The variable num4 also contains 21, because the addition is also done using the changed values.

The postfix versions of increment and decrement use the same syntax (++ and --, respectively) but are placed after the variable instead of before it. Postfix increment and decrement differ from the prefix versions in one important way: the increment or decrement doesn't occur until after the containing statement has been evaluated. In certain circumstances, this difference doesn't matter, as in this example:

let age = 29;
age++;

Moving the increment operator after the variable doesn't change what these statements do, because the increment is the only operation occurring. However, when mixed together with other operations, the difference becomes apparent, as in the following example:

let num1 = 2;
let num2 = 20;
let num3 = num1-- + num2;
let num4 = num1 + num2;
console.log(num3);  // 22
console.log(num4);  // 21

With just one simple change in this example, using postfix decrement instead of prefix, you can see the difference. In the prefix example, num3 and num4 both ended up equal to 21, whereas this example ends with num3 equal to 22 and num4 equal to 21. The difference is that the calculation for num3 uses the original value of num1 (2) to complete the addition, whereas num4 is using the decremented value (1).

All four of these operators work on any values, meaning not just integers but strings, Booleans, floating-point values, and objects. The increment and decrement operators follow these rules regarding values:

When used on a string that is a valid representation of a number, convert to a number and apply the change. The variable is changed from a string to a number.
When used on a string that is not a valid number, the variable's value is set to NaN. The variable is changed from a string to a number.
When used on a Boolean value that is false, convert to 0 and apply the change. The variable is changed from a Boolean to a number.
When used on a Boolean value that is true, convert to 1 and apply the change. The variable is changed from a Boolean to a number.
When used on a floating-point value, apply the change by adding or subtracting 1.
When used on an object, call its valueOf() method to get a value to work with. Apply the other rules. If the result is NaN, then call toString() and apply the other rules again. The variable is changed from an object to a number.

The following example demonstrates some of these rules:

let s1 = "2";
let s2 = "z";
let b = false;
let f = 1.1;
let o = {
  valueOf() {
    return -1;
  }
};

s1++;  // value becomes numeric 3
s2++;  // value becomes NaN
b++;   // value becomes numeric 1
f--;   // value becomes 0.10000000000000009 (due to floating-point inaccuracies)
o--;   // value becomes numeric -2

Unary Plus and Minus

The unary plus and minus operators are familiar symbols to most developers and operate the same way in ECMAScript as they do in high-school math. The unary plus is represented by a single plus sign (+) placed before a variable and does nothing to a numeric value, as shown in this example:

let num = 25;
num = +num;
console.log(num);  // 25

When the unary plus is applied to a nonnumeric value, it performs the same conversion as the Number() casting function: the Boolean values of false and true are converted to 0 and 1, string values are parsed according to a set of specific rules, and objects have their valueOf() and/or toString() method called to get a value to convert.

The following example demonstrates the behavior of the unary plus when acting on different data types:

let s1 = "01";
let s2 = "1.1";
let s3 = "z";
let b = false;
let f = 1.1;
let o = {
  valueOf() {
    return -1;
  }
};

s1 = +s1;  // value becomes numeric 1
s2 = +s2;  // value becomes numeric 1.1
s3 = +s3;  // value becomes NaN
b = +b;    // value becomes numeric 0
f = +f;    // no change, still 1.1
o = +o;    // value becomes numeric -1

The unary minus operator's primary use is to negate a numeric value, such as converting 1 into –1. The simple case is illustrated here:

let num = 25;
num = -num;
console.log(num);  // -25

When used on a numeric value, the unary minus simply negates the value (as in this example). When used on nonnumeric values, unary minus applies all of the same rules as unary plus and then negates the result, as shown here:

let s1 = "01";
let s2 = "1.1";
let s3 = "z";
let b = false;
let f = 1.1;
let o = {
  valueOf() {
    return -1;
  }
};

s1 = -s1;  // value becomes numeric -1
s2 = -s2;  // value becomes numeric -1.1
s3 = -s3;  // value becomes NaN
b = -b;    // value becomes numeric 0
f = -f;    // change to -1.1
o = -o;    // value becomes numeric 1

The unary plus and minus operators are used primarily for basic arithmetic but can also be useful for conversion purposes, as illustrated in the previous example.

Bitwise Operators

The next set of operators works with numbers at their very base level, with the bits that represent them in memory. All numbers in ECMAScript are stored in IEEE–754 64-bit format, but the bitwise operations do not work directly on the 64-bit representation. Instead, the value is converted into a 32-bit integer, the operation takes place, and the result is converted back into 64 bits. To the developer, it appears that only the 32-bit integer exists because the 64-bit storage format is transparent. With that in mind, consider how 32-bit integers work.

Signed integers use the first 31 of the 32 bits to represent the numeric value of the integer. The 32nd bit represents the sign of the number: 0 for positive or 1 for negative. Depending on the value of that bit, called the sign bit, the format of the rest of the number is determined. Positive numbers are stored in true binary format, with each of the 31 bits representing a power of 2, starting with the first bit (called bit 0), representing 2⁰, the second bit represents 2¹, and so on. If any bits are unused, they are filled with 0 and essentially ignored. For example, the number 18 is represented as 00000000000000000000000000010010, or more succinctly as 10010. These are the five most significant bits and can be used, by themselves, to determine the actual value (see Figure 3.1).

An illustration of breakdown of binary integer representation. — **FIGURE 3.1**: Breakdown of binary integer representation

Negative numbers are also stored in binary code but in a format called two's complement. The two's complement of a number is calculated in three steps:

Determine the binary representation of the absolute value (for example, to find –18, first determine the binary representation of 18).
Find the one's complement of the number, which essentially means that every 0 must be replaced with a 1, and vice versa.
Add 1 to the result.

Using this process to determine the binary representation –18, start with the binary representation of 18, which is the following:

0000 0000 0000 0000 0000 0000 0001 0010

Next, take the one's complement, which is the inverse of this number:

1111 1111 1111 1111 1111 1111 1110 1101

Finally, add 1 to the one's complement as follows:

1111 1111 1111 1111 1111 1111 1110 1101
                    1
---------------------------------------
1111 1111 1111 1111 1111 1111 1110 1110

So the binary equivalent of –18 is 11111111111111111111111111101110. Keep in mind that you have no access to bit 31 when dealing with signed integers.

ECMAScript does its best to keep all of this information from you. When outputting a negative number as a binary string, you get the binary code of the absolute value preceded by a minus sign, as in this example:

let num = -18;
console.log(num.toString(2));  // "-10010"

When you convert the number –18 to a binary string, the result is –10010. The conversion process interprets the two's complement and represents it in an arguably more logical form.

When you apply bitwise operators to numbers in ECMAScript, a conversion takes place behind the scenes: the 64-bit number is converted into a 32-bit number, the operation is performed, and then the 32-bit result is stored back into a 64-bit number. This gives the illusion that you're dealing with true 32-bit numbers, which makes the binary operations work in a way similar to the operations of other languages. A curious side effect of this conversion is that the special values NaN and Infinity both are treated as equivalent to 0 when used in bitwise operations.

If a bitwise operator is applied to a nonnumeric value, the value is first converted into a number using the Number() function (this is done automatically), and then the bitwise operation is applied. The resulting value is a number.

Bitwise NOT

The bitwise NOT is represented by a tilde (~) and simply returns the one's complement of the number. Bitwise NOT is one of just a few ECMAScript operators related to binary mathematics. Consider this example:

let num1 = 25;       // binary 00000000000000000000000000011001
let num2 = ~num1;    // binary 11111111111111111111111111100110
console.log(num2);   // -26

Here, the bitwise NOT operator is used on 25, producing –26 as the result. This is the end effect of the bitwise NOT: it negates the number and subtracts 1. The same outcome is produced with the following code:

let num1 = 25;
let num2 = -num1 - 1;
console.log(num2);     // -26

Realistically, though this returns the same result, the bitwise operation is much faster because it works at the very lowest level of numeric representation.

Bitwise AND

The bitwise AND operator is indicated by the ampersand character (&) and works on two values. Essentially, bitwise AND lines up the bits in each number and then, using the rules in the following truth table, performs an AND operation between the two bits in the same position.

BIT FROM FIRST NUMBER	BIT FROM SECOND NUMBER	RESULT
1	1	1
1	0	0
0	1	0
0	0	0

A bitwise AND operation returns 1 if both bits are 1. It returns 0 if any bits are 0.

As an example, to AND the numbers 25 and 3 together, use the following code:

let result = 25 & 3;
console.log(result);  // 1

The result of a bitwise AND between 25 and 3 is 1. Why is that? Take a look:

 25 = 0000 0000 0000 0000 0000 0000 0001 1001
  3 = 0000 0000 0000 0000 0000 0000 0000 0011
---------------------------------------------
AND = 0000 0000 0000 0000 0000 0000 0000 0001

As you can see, only one bit (bit 0) contains a 1 in both 25 and 3. Because of this, every other bit of the resulting number is set to 0, making the result equal to 1.

Bitwise OR

The bitwise OR operator is represented by a single pipe character (|) and also works on two numbers. Bitwise OR follows the rules in this truth table:

BIT FROM FIRST NUMBER	BIT FROM SECOND NUMBER	RESULT
1	1	1
1	0	1
0	1	1
0	0	0

A bitwise OR operation returns 1 if at least one bit is 1. It returns 0 only if both bits are 0.

Using the same example as for bitwise AND, if you want to OR the numbers 25 and 3 together, the code looks like this:

let result = 25 | 3;
console.log(result);   // 27

The result of a bitwise OR between 25 and 3 is 27:

 25 = 0000 0000 0000 0000 0000 0000 0001 1001
  3 = 0000 0000 0000 0000 0000 0000 0000 0011
---------------------------------------------
 OR = 0000 0000 0000 0000 0000 0000 0001 1011

In each number, four bits are set to 1, so these are passed through to the result. The binary code 11011 is equal to 27.

Bitwise XOR

The bitwise XOR operator is represented by a caret (^) and also works on two values. Here is the truth table for bitwise XOR:

BIT FROM FIRST NUMBER	BIT FROM SECOND NUMBER	RESULT
1	1	0
1	0	1
0	1	1
0	0	0

Bitwise XOR is different from bitwise OR in that it returns 1 only when exactly one bit has a value of 1 (if both bits contain 1, it returns 0).

To XOR the numbers 25 and 3 together, use the following code:

let result = 25 ^ 3;
console.log(result);  // 26

The result of a bitwise XOR between 25 and 3 is 26, as shown here:

 25 = 0000 0000 0000 0000 0000 0000 0001 1001
  3 = 0000 0000 0000 0000 0000 0000 0000 0011
---------------------------------------------
XOR = 0000 0000 0000 0000 0000 0000 0001 1010

Four bits in each number are set to 1; however, the first bit in both numbers is 1, so that becomes 0 in the result. All of the other 1s have no corresponding 1 in the other number, so they are passed directly through to the result. The binary code 11010 is equal to 26. (Note that this is one less than when performing bitwise OR on these numbers.)

Left Shift

The left shift is represented by two less-than signs (<<) and shifts all bits in a number to the left by the number of positions given. For example, if the number 2 (which is equal to 10 in binary) is shifted 5 bits to the left, the result is 64 (which is equal to 1000000 in binary), as shown here:

let oldValue = 2;              // equal to binary 10
let newValue = oldValue << 5;  // equal to binary 1000000 which is decimal 64

Note that when the bits are shifted, five empty bits remain to the right of the number. The left shift fills these bits with 0s to make the result a complete 32-bit number (see Figure 3.2).

An illustration of before and after left shift operation. — **FIGURE 3.2**: Before and after left shift operation

Note that left shift preserves the sign of the number it's operating on. For instance, if –2 is shifted to the left by five spaces, it becomes –64, not positive 64.

Signed Right Shift

The signed right shift is represented by two greater-than signs (>>) and shifts all bits in a 32-bit number to the right while preserving the sign (positive or negative). A signed right shift is the exact opposite of a left shift. For example, if 64 is shifted to the right five bits, it becomes 2:

let oldValue = 64;             // equal to binary 1000000
let newValue = oldValue>> 5;  // equal to binary 10 which is decimal 2

Once again, when bits are shifted, the shift creates empty bits. This time, the empty bits occur at the left of the number but after the sign bit (see Figure 3.3). Once again, ECMAScript fills these empty bits with the value in the sign bit to create a complete number.

An illustration of before and after right shift operation. — **FIGURE 3.3**: Before and after right shift operation

Unsigned Right Shift

The unsigned right shift is represented by three greater-than signs (>>>) and shifts all bits in a 32-bit number to the right. For numbers that are positive, the effect is the same as a signed right shift. Using the same example as for the signed-right-shift example, if 64 is shifted to the right five bits, it becomes 2:

let oldValue = 64;              // equal to binary 1000000
let newValue = oldValue>>> 5;  // equal to binary 10 which is decimal 2

For numbers that are negative, however, something quite different happens. Unlike signed right shift, the empty bits get filled with zeros regardless of the sign of the number. For positive numbers, it has the same effect as a signed right shift; for negative numbers, the result is quite different. The unsigned-right-shift operator considers the binary representation of the negative number to be representative of a positive number instead. Because the negative number is the two's complement of its absolute value, the number becomes very large, as you can see in the following example:

let oldValue = -64;             // equal to binary 11111111111111111111111111000000
let newValue = oldValue>>> 5;  // equal to decimal 134217726

When an unsigned right shift is used to shift –64 to the right by five bits, the result is 134217726. This happens because the binary representation of –64 is 11111111111111111111111111000000, but because the unsigned right shift treats this as a positive number, it considers the value to be 4294967232. When this value is shifted to the right by five bits, it becomes 00000111111111111111111111111110, which is 134217726.

Boolean Operators

Almost as important as equality operators, Boolean operators are what make a programming language function. Without the capability to test relationships between two values, statements such as if…else and loops wouldn't be useful. There are three Boolean operators: NOT, AND, and OR.

Logical NOT

The logical NOT operator is represented by an exclamation point (!) and may be applied to any value in ECMAScript. This operator always returns a Boolean value, regardless of the data type it's used on. The logical NOT operator first converts the operand to a Boolean value and then negates it, meaning that the logical NOT behaves in the following ways:

If the operand is an object, false is returned.
If the operand is an empty string, true is returned.
If the operand is a nonempty string, false is returned.
If the operand is the number 0, true is returned.
If the operand is any number other than 0 (including Infinity), false is returned.
If the operand is null, true is returned.
If the operand is NaN, true is returned.
If the operand is undefined, true is returned.

The following example illustrates this behavior:

console.log(!false);   // true
console.log(!"blue");  // false
console.log(!0);       // true
console.log(!NaN);     // true
console.log(!"");      // true
console.log(!12345);   // false

The logical NOT operator can also be used to convert a value into its Boolean equivalent. By using two NOT operators in a row, you can effectively simulate the behavior of the Boolean() casting function. The first NOT returns a Boolean value no matter what operand it is given. The second NOT negates that Boolean value and so gives the true Boolean value of a variable. The end result is the same as using the Boolean() function on a value, as shown here:

console.log(!!"blue");  // true
console.log(!!0);       // false
console.log(!!NaN);     // false
console.log(!!"");      // false
console.log(!!12345);   // true

Logical AND

The logical AND operator is represented by the double ampersand (&&) and is applied to two values, as in this example:

let result = true && false;

Logical AND behaves as described in the following truth table:

OPERAND 1	OPERAND 2	RESULT
`true`	`true`	`true`
`true`	`false`	`false`
`false`	`true`	`false`
`false`	`false`	`false`

Logical AND can be used with any type of operand, not just Boolean values. When either operand is not a primitive Boolean, logical AND does not always return a Boolean value; instead, it does one of the following:

If the first operand is an object, then the second operand is always returned.
If the second operand is an object, then the object is returned only if the first operand evaluates to true.
If both operands are objects, then the second operand is returned.
If either operand is null, then null is returned.
If either operand is NaN, then NaN is returned.
If either operand is undefined, then undefined is returned.

The logical AND operator is a short-circuited operation, meaning that if the first operand determines the result, the second operand is never evaluated. In the case of logical AND, if the first operand is false, no matter what the value of the second operand, the result can't be equal to true. Consider the following example:

let found = true;
let result = (found && someUndeclaredVariable);  // error occurs here
console.log(result);  // this line never executes

This code causes an error when the logical AND is evaluated, because the variable someUndeclaredVariable isn't declared. The value of the variable found is true, so the logical AND operator continued to evaluate the variable someUndeclaredVariable. When it did, an error occurred because someUndeclaredVariable is not declared and therefore cannot be used in a logical AND operation. If found is instead set to false, as in the following example, the error won't occur:

let found = false;
let result = (found && someUndeclaredVariable);  // no error
console.log(result);  // works

In this code, the console.log is displayed successfully. Even though the variable someUndeclaredVariable is undefined, it is never evaluated because the first operand is false. This means that the result of the operation must be false, so there is no reason to evaluate what's to the right of the &&. Always keep in mind short-circuiting when using logical AND.

Logical OR

The logical OR operator is represented by the double pipe (||) in ECMAScript, like this:

let result = true || false;

Logical OR behaves as described in the following truth table:

OPERAND 1	OPERAND 2	RESULT
`true`	`true`	`true`
`true`	`false`	`true`
`false`	`true`	`true`
`false`	`false`	`false`

Just like logical AND, if either operand is not a Boolean, logical OR will not always return a Boolean value; instead, it does one of the following:

If the first operand is an object, then the first operand is returned.
If the first operand evaluates to false, then the second operand is returned.
If both operands are objects, then the first operand is returned.
If both operands are null, then null is returned.
If both operands are NaN, then NaN is returned.
If both operands are undefined, then undefined is returned.

Also like the logical AND operator, the logical OR operator is short-circuited. In this case, if the first operand evaluates to true, the second operand is not evaluated. Consider this example:

let found = true;
let result = (found || someUndeclaredVariable);  // no error
console.log(result);  // works

As with the previous example, the variable someUndefinedVariable is undefined. However, because the variable found is set to true, the variable someUndefinedVariable is never evaluated and thus the output is “true.” If the value of found is changed to false, an error occurs, as in the following example:

let found = false;
let result = (found || someUndeclaredVariable);  // error occurs here
console.log(result);  // this line never executes

You can also use this behavior to avoid assigning a null or undefined value to a variable. Consider the following:

let myObject = preferredObject || backupObject;

In this example, the variable myObject will be assigned one of two values. The preferredObject variable contains the value that is preferred if it's available, whereas the backupObject variable contains the backup value if the preferred one isn't available. If preferredObject isn't null, then it's assigned to myObject; if it is null, then backupObject is assigned to myObject. This pattern is used very frequently in ECMAScript for variable assignment and is used throughout this book.

Multiplicative Operators

There are three multiplicative operators in ECMAScript: multiply, divide, and modulus. These operators work in a manner similar to their counterparts in languages such as Java, C, and Perl, but they also include some automatic type conversions when dealing with nonnumeric values. If either of the operands for a multiplication operation isn't a number, it is converted to a number behind the scenes using the Number() casting function. This means that an empty string is treated as 0, and the Boolean value of true is treated as 1.

Multiply

The multiply operator is represented by an asterisk (*) and is used, as one might suspect, to multiply two numbers. The syntax is the same as in C, as shown here:

let result = 34 * 56;

However, the multiply operator also has the following unique behaviors when dealing with special values:

If the operands are numbers, regular arithmetic multiplication is performed, meaning that two positives or two negatives equal a positive, whereas operands with different signs yield a negative. If the result cannot be represented by ECMAScript, either Infinity or –Infinity is returned.
If either operand is NaN, the result is NaN.
If Infinity is multiplied by 0, the result is NaN.
If Infinity is multiplied by any finite number other than 0, the result is either Infinity or –Infinity, depending on the sign of the second operand.
If Infinity is multiplied by Infinity, the result is Infinity.
If either operand isn't a number, it is converted to a number behind the scenes using Number() and then the other rules are applied.

Divide

The divide operator is represented by a slash (/) and divides the first operand by the second operand, as shown here:

let result = 66 / 11;

The divide operator, like the multiply operator, has special behaviors for special values. They are as follows:

If the operands are numbers, regular arithmetic division is performed, meaning that two positives or two negatives equal a positive, whereas operands with different signs yield a negative. If the result can't be represented in ECMAScript, it returns either Infinity or –Infinity.
If either operand is NaN, the result is NaN.
If Infinity is divided by Infinity, the result is NaN.
If zero is divided by zero, the result is NaN.
If a nonzero finite number is divided by zero, the result is either Infinity or –Infinity, depending on the sign of the first operand.
If Infinity is divided by any number, the result is either Infinity or –Infinity, depending on the sign of the second operand.
If either operand isn't a number, it is converted to a number behind the scenes using Number() and then the other rules are applied.

Modulus

The modulus (remainder) operator is represented by a percent sign (%) and is used in the following way:

let result = 26 % 5;  // equal to 1

Just like the other multiplicative operators, the modulus operator behaves differently for special values, as follows:

If the operands are numbers, regular arithmetic division is performed, and the remainder of that division is returned.
If the dividend is an infinite number and the divisor is a finite number, the result is NaN.
If the dividend is a finite number and the divisor is 0, the result is NaN.
If Infinity is divided by Infinity, the result is NaN.
If the dividend is a finite number and the divisor is an infinite number, then the result is the dividend.
If the dividend is zero and the divisor is nonzero, the result is zero.
If either operand isn't a number, it is converted to a number behind the scenes using Number() and then the other rules are applied.

Exponentiation Operator

The exponentiation operator (**) is equivalent to Math.pow().

console.log(Math.pow(3, 2);     // 9
console.log(3 ** 2);            // 9

console.log(Math.pow(16, 0.5);  // 4
console.log(16** 0.5);          // 4

The operator also gets its own exponentiate assignment operator, **=, which performs the exponentiation and subsequent assignment of the result:

let squared = 3;
squared **= 2;
console.log(squared);  // 9

let sqrt = 16;
sqrt **= 0.5;
console.log(sqrt);     // 4

Additive Operators

The additive operators, add and subtract, are typically the simplest mathematical operators in programming languages. In ECMAScript, however, a number of special behaviors are associated with each operator. As with the multiplicative operators, conversions occur behind the scenes for different data types. For these operators, however, the rules aren't as straightforward.

Add

The add operator (+) is used just as one would expect, as shown in the following example:

let result = 1 + 2;

If the two operands are numbers, they perform an arithmetic add and return the result according to the following rules:

If either operand is NaN, the result is NaN.
If Infinity is added to Infinity, the result is Infinity.
If –Infinity is added to –Infinity, the result is –Infinity.
If Infinity is added to –Infinity, the result is NaN.
If +0 is added to +0, the result is +0.
If –0 is added to +0, the result is +0.
If –0 is added to –0, the result is –0.

If, however, one of the operands is a string, then the following rules apply:

If both operands are strings, the second string is concatenated to the first.
If only one operand is a string, the other operand is converted to a string and the result is the concatenation of the two strings.

If either operand is an object, number, or Boolean, its toString() method is called to get a string value and then the previous rules regarding strings are applied. For undefined and null, the String() function is called to retrieve the values “undefined” and “null,” respectively.

Consider the following:

let result1 = 5 + 5;    // two numbers
console.log(result1);         // 10
let result2 = 5 + "5";  // a number and a string
console.log(result2);         // "55"

This code illustrates the difference between the two modes for the add operator. Normally, 5 + 5 equals 10 (a number value), as illustrated by the first two lines of code. However, if one of the operands is changed to a string, “5,” the result becomes “55” (which is a primitive string value) because the first operand gets converted to “5” as well.

One of the most common mistakes in ECMAScript is being unaware of the data types involved with an addition operation. Consider the following:

let num1 = 5;
let num2 = 10;
let message = "The sum of 5 and 10 is " + num1 + num2;
console.log(message);  // "The sum of 5 and 10 is 510"

In this example, the message variable is filled with a string that is the result of two addition operations. One might expect the final string to be “The sum of 5 and 10 is 15”; however, it actually ends up as “The sum of 5 and 10 is 510.” This happens because each addition is done separately. The first combines a string with a number (5), which results in a string. The second takes that result (a string) and adds a number (10), which also results in a string. To perform the arithmetic calculation and then append that to the string, just add some parentheses like this:

let num1 = 5;
let num2 = 10;
let message = "The sum of 5 and 10 is " + (num1 + num2);
console.log(message);  // "The sum of 5 and 10 is 15"

Here, the two number variables are surrounded by parentheses, which instruct the interpreter to calculate its result before adding it to the string. The resulting string is “The sum of 5 and 10 is 15.”

Subtract

The subtract operator (-) is another that is used quite frequently. Here's an example:

let result = 2 - 1;

Just like the add operator, the subtract operator has special rules to deal with the variety of type conversions present in ECMAScript. They are as follows:

If the two operands are numbers, perform arithmetic subtract and return the result.
If either operand is NaN, the result is NaN.
If Infinity is subtracted from Infinity, the result is NaN.
If –Infinity is subtracted from –Infinity, the result is NaN.
If –Infinity is subtracted from Infinity, the result is Infinity.
If Infinity is subtracted from –Infinity, the result is –Infinity.
If +0 is subtracted from +0, the result is +0.
If –0 is subtracted from +0, the result is –0.
If –0 is subtracted from –0, the result is +0.
If either operand is a string, a Boolean, null, or undefined, it is converted to a number (using Number() behind the scenes) and the arithmetic is calculated using the previous rules. If that conversion results in NaN, then the result of the subtraction is NaN.
If either operand is an object, its valueOf() method is called to retrieve a numeric value to represent it. If that value is NaN, then the result of the subtraction is NaN. If the object doesn't have valueOf() defined, then toString() is called and the resulting string is converted into a number.

The following are some examples of these behaviors:

let result1 = 5 - true;  // 4 because true is converted to 1
let result2 = NaN - 1;   // NaN
let result3 = 5 - 3;     // 2
let result4 = 5 - "";    // 5 because "" is converted to 0
let result5 = 5 - "2";   // 3 because "2" is converted to 2
let result6 = 5 - null;  // 5 because null is converted to 0

Relational Operators

The less-than (<), greater-than (>), less-than-or-equal-to (<=), and greater-than-or-equal-to (>=) relational operators perform comparisons between values in the same way that you learned in math class. Each of these operators returns a Boolean value, as in this example:

let result1 = 5> 3;  // true
let result2 = 5 < 3;  // false

As with other operators in ECMAScript, there are some conversions and other oddities that happen when using different data types. They are as follows:

If the operands are numbers, perform a numeric comparison.
If the operands are strings, compare the character codes of each corresponding character in the string.
If one operand is a number, convert the other operand to a number and perform a numeric comparison.
If an operand is an object, call valueOf() and use its result to perform the comparison according to the previous rules. If valueOf() is not available, call toString() and use that value according to the previous rules.
If an operand is a Boolean, convert it to a number and perform the comparison.

When a relational operator is used on two strings, an interesting behavior occurs. Many expect that less-than means “alphabetically before” and greater-than means “alphabetically after,” but this is not the case. For strings, each of the first string's character codes is numerically compared against the character codes in a corresponding location in the second string. After this comparison is complete, a Boolean value is returned. The problem here is that the character codes of uppercase letters are all lower than the character codes of lowercase letters, meaning that you can run into situations like this:

let result = "Brick" < "alphabet";  // true

In this example, the string “Brick” is considered to be less than the string “alphabet” because the letter B has a character code of 66 and the letter a has a character code of 97. To force a true alphabetic result, you must convert both operands into a common case (upper or lower) and then compare like this:

let result = "Brick".toLowerCase() < "alphabet".toLowerCase();  // false

Converting both operands to lowercase ensures that “alphabet” is correctly identified as alphabetically before “Brick.”

Another sticky situation occurs when comparing numbers that are strings, such as in this example:

let result = "23" < "3";  // true

This code returns true when comparing the string “23” to “3.” Because both operands are strings, they are compared by their character codes (the character code for “2” is 50; the character code for “3” is 51). If, however, one of the operands is changed to a number as in the following example, the result makes more sense:

let result = "23" < 3;  // false

Here, the string “23” is converted into the number 23 and then compared to 3, giving the expected result. Whenever a number is compared to a string, the string is converted into a number and then numerically compared to the other number. This works well for cases like the previous example, but what if the string can't be converted into a number? Consider this example:

let result = "a" < 3;  // false because "a" becomes NaN

The letter “a” can't be meaningfully converted into a number, so it becomes NaN. As a rule, the result of any relational operation with NaN is false, which is interesting when considering the following:

let result1 = NaN < 3;   // false
let result2 = NaN>= 3;  // false

In most comparisons, if a value is not less than another, it is always greater than or equal to it. When using NaN, however, both comparisons return false.

Equality Operators

Determining whether two variables are equivalent is one of the most important operations in programming. This is fairly straightforward when dealing with strings, numbers, and Boolean values, but the task gets a little complicated when you take objects into account. Originally ECMAScript's equal and not-equal operators performed conversions into like types before doing a comparison. The question of whether these conversions should, in fact, take place was then raised. The end result was for ECMAScript to provide two sets of operators: equal and not equal to perform conversion before comparison, and identically equal and not identically equal to perform comparison without conversion.

Equal and Not Equal

The equal operator in ECMAScript is the double equal sign (==), and it returns true if the operands are equal. The not-equal operator is the exclamation point followed by an equal sign (!=), and it returns true if two operands are not equal. Both operators do conversions to determine if two operands are equal (often called type coercion).

When performing conversions, the equal and not-equal operators follow these basic rules:

If an operand is a Boolean value, convert it into a numeric value before checking for equality. A value of false converts to 0, whereas a value of true converts to 1.
If one operand is a string and the other is a number, attempt to convert the string into a number before checking for equality.
If one of the operands is an object and the other is not, the valueOf() method is called on the object to retrieve a primitive value to compare according to the previous rules.

The operators also follow these rules when making comparisons:

Values of null and undefined are equal.
Values of null and undefined cannot be converted into any other values for equality checking.
If either operand is NaN, the equal operator returns false and the not-equal operator returns true. Important note: even if both operands are NaN, the equal operator returns false because, by rule, NaN is not equal to NaN.
If both operands are objects, then they are compared to see if they are the same object. If both operands point to the same object, then the equal operator returns true. Otherwise, the two are not equal.

The following table lists some special cases and their results:

EXPRESSION	VALUE
`null == undefined`	`true`
`"NaN" == NaN`	`false`
`5 == NaN`	`false`
`NaN == NaN`	`false`
`NaN != NaN`	`true`
`false == 0`	`true`
`true == 1`	`true`
`true == 2`	`false`
`undefined == 0`	`false`
`null == 0`	`false`
`"5" == 5`	`true`

Identically Equal and Not Identically Equal

The identically equal and not identically equal operators do the same thing as equal and not equal, except that they do not convert operands before testing for equality. The identically equal operator is represented by three equal signs (===) and returns true only if the operands are equal without conversion, as in this example:

let result1 = ("55" == 55);   // true - equal because of conversion
let result2 = ("55" === 55);  // false - not equal because different data types

In this code, the first comparison uses the equal operator to compare the string “55” and the number 55, which returns true. As mentioned previously, this happens because the string “55” is converted to the number 55 and then compared with the other number 55. The second comparison uses the identically equal operator to compare the string and the number without conversion, and of course, a string isn't equal to a number, so this outputs false.

The not identically equal operator is represented by an exclamation point followed by two equal signs (!==) and returns true only if the operands are not equal without conversion. For example:

let result1 = ("55" != 55);  // false - equal because of conversion
let result2 = ("55" !== 55);   // true - not equal because different data types

Here, the first comparison uses the not-equal operator, which converts the string "55" to the number 55, making it equal to the second operand, also the number 55. Therefore, this evaluates to false because the two are considered equal. The second comparison uses the not identically equal operator. It helps to think of this operation as saying, “Is the string 55 different from the number 55?” The answer to this is yes (true).

Keep in mind that while null == undefined is true because they are similar values, null === undefined is false because they are not the same type.

Conditional Operator

The conditional operator is one of the most versatile in ECMAScript, and it takes on the same form as in Java, which is as follows:

variable = boolean_expression ? true_value : false_value;

This basically allows a conditional assignment to a variable depending on the evaluation of the boolean_expression. If it's true, then true_value is assigned to the variable; if it's false, then false_value is assigned to the variable, as in this instance:

let max = (num1> num2) ? num1 : num2;

In this example, max is to be assigned the number with the highest value. The expression states that if num1 is greater than num2, then num1 is assigned to max. If, however, the expression is false (meaning that num1 is less than or equal to num2), then num2 is assigned to max.

Nullish Coalescing Operator

The nullish coalescing operator ?? provides a concise way to handle nullish (null or undefined) values in expressions. It is a binary operator that returns the right-hand operand if the left-hand operand is either null or undefined. Otherwise, it returns the left-hand operand. It can be used as follows:

variable = expression ?? nullish_fallback_value;

Without the use of ??, the above expression could be expressed using a conditional operator as follows:

variable = expression !== null && expression !== undefined ? expression : nullish_fallback_value;

The ?? operator is particularly useful in situations where you need to be careful when assigning defaults for falsy values. Prior to the introduction of the ??, the || operator was typically used to assign a default value, but its behavior was sometimes undesirable when dealing with falsy values. The following example compares the behavior of these operators:

const values = [null, undefined, 0, ""];

console.log(values.map(x => x || "default"));
// ["default", "default", "default", "default"]

console.log(values.map(x => x ?? "default"));
// ["default", "default", 0, ""]

Assignment Operators

Simple assignment is done with the equal sign (=) and simply assigns the value on the right to the variable on the left, as shown in the following example:

let num = 10;

Compound assignment is done with one of the multiplicative, additive, or bitwise–shift operators followed by an equal sign (=). These assignments are designed as shorthand for such common situations as this:

let num = 10;
num = num + 10;

The second line of code can be replaced with a compound assignment:

let num = 10;
num += 10;

Compound-assignment operators exist for each of the major mathematical operations and a few others as well. They are as follows:

Multiply/assign (*=)
Exponentiation/assign (**=)
Divide/assign (/=)
Modulus/assign (%=)
Add/assign (+=)
Subtract/assign (-=)
Left shift/assign (<<=)
Signed right shift/assign (>>=)
Unsigned right shift/assign (>>>=)
Bitwise OR/assign (|=)
Bitwise AND/assign (&=)
Bitsize XOR/assign (^=)
Logical OR/assign (||=)
Logical AND/assign (&&=)
Nullish coalescing/assign (??=)

These operators are designed specifically as shorthand ways of achieving operations. They do not represent any performance improvement.

Comma Operator

The comma operator allows execution of more than one operation in a single statement, as illustrated here:

let num1 = 1, num2 = 2, num3 = 3;

Most often, the comma operator is used in the declaration of variables; however, it can also be used to assign values. When used in this way, the comma operator always returns the last item in the expression, as in the following example:

let num = (5, 1, 4, 8, 0);  // num becomes 0

In this example, num is assigned the value of 0 because it is the last item in the expression. There aren't many times when commas are used in this way; however, it is helpful to understand that this behavior exists.

STATEMENTS

ECMA-262 describes several statements (also called flow-control statements). Essentially, statements define most of the syntax of ECMAScript and typically use one or more keywords to accomplish a given task. Statements can be simple, such as telling a function to exit, or complicated, such as specifying a number of commands to be executed repeatedly.

The if Statement

One of the most frequently used statements in most programming languages is the if statement. The if statement has the following syntax:

if (condition) statement1 else statement2

The condition can be any expression; it doesn't even have to evaluate to an actual Boolean value. ECMAScript automatically converts the result of the expression into a Boolean by calling the Boolean() casting function on it. If the condition evaluates to true, statement1 is executed; if the condition evaluates to false, statement2 is executed. Each of the statements can be either a single line or a code block (a group of code lines enclosed within braces). Consider this example:

if (i> 25)
  console.log("Greater than 25.");  // one–line statement
else {
  console.log("Less than or equal to 25.");  // block statement
}

It's considered best coding practice to always use block statements, even if only one line of code is to be executed. Doing so can avoid confusion about what should be executed for each condition.

You can also chain if statements together like so:

if (condition1) statement1 else if (condition2) statement2 else statement3

Here's an example:

if (i> 25) {
  console.log("Greater than 25.");
} else if (i < 0) {
  console.log("Less than 0.");
} else {
  console.log("Between 0 and 25, inclusive.");
}

The do-while Statement

The do-while statement is a post-test loop, meaning that the escape condition is evaluated only after the code inside the loop has been executed. The body of the loop is always executed at least once before the expression is evaluated. Here's the syntax:

do {
  statement
} while (expression);

And here's an example of its usage:

let i = 0;
do {
   i += 2;
} while (i < 10);

In this example, the loop continues as long as i is less than 10. The variable starts at 0 and is incremented by two each time through the loop.

The while Statement

The while statement is a pretest loop. This means the escape condition is evaluated before the code inside the loop has been executed. Because of this, it is possible that the body of the loop is never executed. Here's the syntax:

while(expression) statement

And here's an example of its usage:

let i = 0;
while (i < 10) {
   i += 2;
}

In this example, the variable i starts out equal to 0 and is incremented by two each time through the loop. As long as the variable is less than 10, the loop will continue.

The for Statement

The for statement is also a pretest loop with the added capabilities of variable initialization before entering the loop and defining postloop code to be executed. Here's the syntax:

for (initialization; expression; post-loop-expression) statement

And here's an example of its usage:

let count = 10;
for (let i = 0; i < count; i++) {
  console.log(i);
}

This code defines a variable i that begins with the value 0. The for loop is entered only if the conditional expression (i < count) evaluates to true, making it possible that the body of the code might not be executed. If the body is executed, the postloop expression is also executed, iterating the variable i. This for loop is the same as the following:

let count = 10;
let i = 0;
while (i < count) {
  console.log(i);
  i++;
}

Nothing can be done with a for loop that can't be done using a while loop. The for loop simply encapsulates the loop-related code into a single location.

It's important to note that there's no need to use the variable declaration keyword inside the for loop initialization. However, the overwhelming majority of the time you will find that the iterator variable is not useful after the loop completes. In these cases, the cleanest implementation is to use a let declaration inside the loop initialization to declare the iterator variable because its scope will be limited to only the loop itself.

The initialization, control expression, and postloop expression are all optional. You can create an infinite loop by omitting all three, like this:

for (;;) {  // infinite loop
  doSomething();
}

Including only the control expression effectively turns a for loop into a while loop, as shown here:

let count = 10;
let i = 0;
for (; i < count; ) {
  console.log(i);
  i++;
}

This versatility makes the for statement one of the most used in the language.

The for-in Statement

The for-in statement is a strict iterative statement. It is used to enumerate the non-symbol keyed properties of an object. Here's the syntax:

for (property in expression) statement

And here's an example of its usage:

for (const propName in window) {
  document.write(propName);
}

Here, the for-in statement is used to display all the properties of the BOM window object. Each time through the loop, the propName variable is filled with the name of a property that exists on the window object. This continues until all of the available properties have been enumerated. As with the for statement, the const operator in the control statement is not necessary but is recommended for ensuring the use of a local variable that will not be altered.

Object properties in ECMAScript are unordered, so the order in which property names are returned in a for-in statement cannot necessarily be predicted. All enumerable properties will be returned once, but the order may differ across browsers.

Note that the for-in statement simply doesn't execute the body of the loop if the variable representing the object to iterate over is null or undefined.

The for-of Statement

The for-of statement is a strict iterative statement. It is used to loop through elements in an iterable object. Here's the syntax:

for (property of expression) statement

And here's an example of its usage:

for (const el of [2,4,6,8]) {
  document.write(el);
}

Here, the for-of statement is used to display all the elements inside the four-element array. This continues until each element in the array has been looped over. As with the for statement, the const operator in the control statement is not necessary but is recommended for ensuring the use of a local variable that will not be altered.

The for-of loop will iterate in the order that the iterable produces values via its next() method. This is covered in-depth in the Chapter 7.

Note that the for-of statement will throw an error if the entity that it is attempting to iterate over does not support iteration.

Labeled Statements

It is possible to label statements for later use with the following syntax:

label: statement

Here's an example:

start: for (let i = 0; i < count; i++) {
  console.log(i);
}

In this example, the label start can be referenced later by using the break or continue statement. Labeled statements are typically used with nested loops.

The break and continue Statements

The break and continue statements provide stricter control over the execution of code in a loop. The break statement exits the loop immediately, forcing execution to continue with the next statement after the loop. The continue statement, on the other hand, exits the loop immediately, but execution continues from the top of the loop. Here's an example:

let num = 0;

for (let i = 1; i < 10; i++) {
  if (i % 5 == 0) {
    break;
  }
  num++;
}

console.log(num);  // 4

In this code, the for loop increments the variable i from 1 to 10. In the body of a loop, an if statement checks to see if the value of i is evenly divisible by 5 (using the modulus operator). If so, the break statement is executed and the loop is exited. The num variable starts out at 0 and indicates the number of times the loop has been executed. After the break statement has been hit, the next line of code to be executed is the console.log, which displays 4. The number of times the loop has been executed is four because when i equals 5, the break statement causes the loop to be exited before num can be incremented. A different effect can be seen if break is replaced with continue like this:

let num = 0;

for (let i = 1; i < 10; i++) {
  if (i % 5 == 0) {
    continue;
  }
  num++;
}

console.log(num);  // 8

Here, the console.log displays 8, the number of times the loop has been executed. When i reaches a value of 5, the loop is exited before num is incremented, but execution continues with the next iteration, when the value is 6. The loop then continues until its natural completion, when i is 10. The final value of num is 8 instead of 9 because one increment didn't occur due to the continue statement.

Both the break and continue statements can be used in conjunction with labeled statements to return to a particular location in the code. This is typically used when there are loops inside of loops, as in the following example:

let num = 0;

outermost:
for (let i = 0; i < 10; i++) {
   for (let j = 0; j < 10; j++) {
    if (i == 5 && j == 5) {
      break outermost;
    }
    num++;
  }
}

console.log(num);  // 55

In this example, the outermost label indicates the first for statement. Each loop normally executes 10 times, meaning that the num++ statement is normally executed 100 times and, consequently, num should be equal to 100 when the execution is complete. The break statement here is given one argument: the label to break to. Adding the label allows the break statement to break not just out of the inner for statement (using the variable j) but also out of the outer for statement (using the variable i). Because of this, num ends up with a value of 55, because execution is halted when both i and j are equal to 5. The continue statement can be used in the same way, as shown in the following example:

let num = 0;

outermost:
for (let i = 0; i < 10; i++) {
   for (let j = 0; j < 10; j++) {
    if (i == 5 && j == 5) {
      continue outermost;
    }
    num++;
  }
}

console.log(num);  // 95

In this case, the continue statement forces execution to continue—not in the inner loop but in the outer loop. When j is equal to 5, continue is executed, which means that the inner loop misses five iterations, leaving num equal to 95.

Using labeled statements in conjunction with break and continue can be very powerful but can cause debugging problems if overused. Always use descriptive labels and try not to nest more than a few loops.

The with Statement

The with statement sets the scope of the code within a particular object. The syntax is as follows:

with (expression) statement;

The with statement was created as a convenience for times when a single object was being coded to over and over again, as in this example:

let qs = location.search.substring(1);
let hostName = location.hostname;
let url = location.href;

Here, the location object is used on every line. This code can be rewritten using the with statement as follows:

with(location) {
  let qs = search.substring(1);
  let hostName = hostname;
  let url = href;
}

In this rewritten version of the code, the with statement is used in conjunction with the location object. This means that each variable inside the statement is first considered to be a local variable. If it's not found to be a local variable, the location object is searched to see if it has a property of the same name. If so, then the variable is evaluated as a property of location.

In strict mode, the with statement is not allowed and is considered a syntax error.

The switch Statement

Closely related to the if statement is the switch statement, another flow-control statement adopted from other languages. The syntax for the switch statement in ECMAScript closely resembles the syntax in other C-based languages, as you can see here:

switch (expression) {
  case value1:
    statement
    break;
  case value2:
    statement
    break;
  case value3:
    statement
    break;
  case value4:
    statement
    break;
  default:
    statement
}

Each case in a switch statement says, “If the expression is equal to the value, execute the statement.” The break keyword causes code execution to jump out of the switch statement. Without the break keyword, code execution falls through the original case into the following one. The default keyword indicates what is to be done if the expression does not evaluate to one of the cases. (In effect, it is an else statement.)

Essentially, the switch statement prevents a developer from having to write something like this:

if (i == 25) {
  console.log("25");
} else if (i == 35) {
  console.log("35");
} else if (i == 45) {
  console.log("45");
} else {
  console.log("Other");
}

The equivalent switch statement is as follows:

switch (i) {
  case 25:
    console.log("25");
    break;
  case 35:
    console.log("35");
    break;
  case 45:
    console.log("45");
    break;
  default:
    console.log("Other");
}

It's best to always put a break statement after each case to avoid having cases fall through into the next one.

Although the switch statement was borrowed from other languages, it has some unique characteristics in ECMAScript. First, the switch statement works with all data types (in many languages it works only with numbers), so it can be used with strings and even with objects. Second, the case values need not be constants; they can be variables and even expressions.

FUNCTIONS

Functions are the core of any language because they allow the encapsulation of statements that can be run anywhere and at any time. Functions in ECMAScript are declared using the function keyword or arrow syntax, followed by a set of arguments and then the body of the function.

The basic function syntax is as follows:

function functionName(arg0, arg1,...,argN) {
  statements
}

Here's an example:

function sayHi(name, message) {
  console.log("Hello " + name + ", " + message);
}

This function can then be called by using the function name, followed by the function arguments enclosed in parentheses (and separated by commas, if there are multiple arguments). The code to call the sayHi() function looks like this:

sayHi("Alice", "how are you today?");

The output of this function call is, “Hello Alice, how are you today?” The named arguments name and message are used as part of a string concatenation that is ultimately displayed in a console.log.

Functions in ECMAScript need not specify whether they return a value. Any function can return a value at any time by using the return statement followed by the value to return. Consider this example:

function sum(num1, num2) {
  return num1 + num2;
}

The sum() function adds two values together and returns the result. Note that aside from the return statement, there is no special declaration indicating that the function returns a value. This function can be called using the following:

const result = sum(5, 10);

Keep in mind that a function stops executing and exits immediately when it encounters the return statement. Therefore, any code that comes after a return statement will never be executed. For example:

function sum(num1, num2) {
  return num1 + num2;
  console.log("Hello world");  // never executed
}

In this example, the console.log will never be displayed because it appears after the return statement.

It's also possible to have more than one return statement in a function, like this:

function diff(num1, num2) {
  if (num1 < num2) {
    return num2 - num1;
  } else {
    return num1 - num2;
  }
}

Here, the diff() function determines the difference between two numbers. If the first number is less than the second, it subtracts the first from the second; otherwise it subtracts the second from the first. Each branch of the code has its own return statement that does the correct calculation.

The return statement can also be used without specifying a return value. When used in this way, the function stops executing immediately and returns undefined as its value. This is typically used in functions that don't return a value to stop function execution early, as in the following example, where the console.log won't be displayed:

function sayHi(name, message) {
  return;
  console.log("Hello " + name + ", " + message);  // never called
}

Strict mode places several restrictions on functions:

No function can be named eval or arguments.
No named parameter can be named eval or arguments.
No two named parameters can have the same name.

If any of these occur, it's considered a syntax error and the code will not execute.

SUMMARY

The core language features of JavaScript are defined in ECMA-262 as a pseudolanguage named ECMAScript. ECMAScript contains all of the basic syntax, operators, data types, and objects necessary to complete basic computing tasks, though it provides no way to get input or to produce output. Understanding ECMAScript and its intricacies is vital to a complete understanding of JavaScript as implemented in web browsers. The following are some of the basic elements of ECMAScript:

The basic data types in ECMAScript are Undefined, Null, Boolean, Number, BigInt, String, and Symbol.
There is also a complex data type, Object, that is the base type for all objects in the language.
A strict mode places restrictions on certain error-prone parts of the language.
ECMAScript provides a lot of the basic operators available in C and other C-like languages, including arithmetic operators, Boolean operators, relational operators, equality operators, and assignment operators.
The language features flow-control statements borrowed heavily from other languages, such as the if statement, the for statement, and the switch statement.

Functions in ECMAScript behave differently than functions in other languages:

There is no need to specify the return value of the function because any function can return any value at any time.
Functions that don't specify a return value actually return the special value undefined.

4
Variables, Scope, and Memory

The nature of variables in JavaScript, as defined in ECMA-262, is quite unique compared to that of other languages. Being loosely typed, a variable is literally just a name for a particular value at a particular time. Because there are no rules defining the type of data that a variable must hold, a variable's value and data type can change during the lifetime of a script. Though this is an interesting, powerful, and problematic feature, there are many more complexities related to variables.

PRIMITIVE AND REFERENCE VALUES

ECMAScript variables may contain two different types of data: primitive values and reference values. Primitive values are simple atomic pieces of data, while reference values are objects that may be made up of multiple values.

When a value is assigned to a variable, the JavaScript engine must determine if it's a primitive or a reference value. The seven primitive types were discussed in the previous chapter: Undefined, Null, Boolean, Number, BigInt, String, and Symbol. These variables are said to be accessed by value, because you are manipulating the actual value stored in the variable.

Reference values are objects stored in memory. Unlike other languages, JavaScript does not permit direct access of memory locations, so direct manipulation of the object's memory space is not allowed. When you manipulate an object, you're really working on a reference to that object rather than the actual object itself. For this reason, such values are said to be accessed by reference.

Dynamic Properties

Primitive and reference values are defined similarly: a variable is created and assigned a value. What you can do with those values once they're stored in a variable, however, is quite different. When you work with reference values, you can add, change, or delete properties and methods at any time. Consider this example:

let person = new Object();
person.name = "Alice";
console.log(person.name);  // "Alice"

Here, an object is created and stored in the variable person. Next, a property called name is added and assigned the string value of “Alice.” The new property is then accessible from that point on, until the object is destroyed or the property is explicitly removed.

Primitive values can't have properties added to them even though attempting to do so won't cause an error. Here's an example:

let name = "Alice";
name.age = 27;
console.log(name.age);  // undefined

Here, a property called age is defined on the string name and assigned a value of 27. On the very next line, however, the property is gone. Only reference values can have properties defined dynamically for later use.

Note that the instantiation of a primitive type can be accomplished using only the primitive literal form. If you were to use the new keyword, JavaScript will create an Object type, but one that behaves like a primitive. Here's an example to distinguish between the two:

let name1 = "Alice";
let name2 = new String("Bob");
name1.age = 27;
name2.age = 26;
console.log(name1.age);  // undefined
console.log(name2.age);  // 26
console.log(typeof name1); // string
console.log(typeof name2); // object

Copying Values

Aside from differences in how they are stored, primitive and reference values act differently when copied from one variable to another. When a primitive value is assigned from one variable to another, the value stored on the variable object is created and copied into the location for the new variable. Consider the following example:

let num1 = 5;
let num2 = num1;

Here, num1 contains the value of 5. When num2 is initialized to num1, it also gets the value of 5. This value is completely separate from the one that is stored in num1 because it's a copy of that value.

Each of these variables can now be used separately with no side effects. This process is diagrammed in Figure 4.1.

An illustration of variable object before and after copy. — **FIGURE 4.1**: Variable object before and after copy

When a reference value is assigned from one variable to another, the value stored on the variable object is also copied into the location for the new variable. The difference is that this value is actually a pointer to an object stored on the heap. Once the operation is complete, two variables point to exactly the same object, so changes to one are reflected on the other, as in the following example:

let obj1 = new Object();
let obj2 = obj1;
obj1.name = "Alice";
console.log(obj2.name);  // "Alice"

In this example, the variable obj1 is filled with a new instance of an object. This value is then copied into obj2, meaning that both variables are now pointing to the same object. When the property name is set on obj1, it can later be accessed from obj2 because they both point to the same object. Figure 4.2 shows the relationship between the variables on the variable object and the object on the heap.

An illustration of relationship between variable objects and the heap. — **FIGURE 4.2**: Relationship between variable objects and the heap

Argument Passing

All function arguments in ECMAScript are passed by value. This means that the value outside of the function is copied into an argument on the inside of the function the same way a value is copied from one variable to another. If the value is primitive, then it acts just like a primitive variable copy, and if the value is a reference, it acts just like a reference variable copy. This is often a point of confusion for developers because variables are accessed both by value and by reference, but arguments are passed only by value.

When an argument is passed by value, the value is copied into a local variable (a named argument and, in ECMAScript, a slot in the arguments object). When an argument is passed by reference, the location of the value in memory is stored into a local variable, which means that changes to the local variable are reflected outside of the function. (This is not possible in ECMAScript.) Consider the following example:

function addTen(num) {
  num += 10;
  return num;
}

let count = 20;
let result = addTen(count);
console.log(count);   // 20 - no change
console.log(result);  // 30

Here, the function addTen() has an argument, num, which is essentially a local variable. When called, the variable count is passed in as an argument. This variable has a value of 20, which is copied into the argument num for use inside of addTen(). Within the function, the argument num has its value changed by adding 10, but this doesn't change the original variable count that exists outside of the function. The argument num and the variable count do not recognize each other; they only happen to have the same value. If num had been passed by reference, then the value of count would have changed to 30 to reflect the change made inside the function. This fact is obvious when using primitive values such as numbers, but things aren't as clear when using objects. Take this, for example:

function setName(obj) {
  obj.name = "Alice";
}

let person = new Object();
setName(person);
console.log(person.name);  // "Alice"

In this code, an object is created and stored in the variable person. This object is then passed into the setName() method, where it is copied into obj. Inside the function, obj and person both point to the same object. The result is that obj is accessing an object by reference, even though it was passed into the function by value. When the name property is set on obj inside the function, this change is reflected outside the function, because the object that it points to exists globally on the heap. Many developers incorrectly assume that when a local change to an object is reflected globally, that means an argument was passed by reference. To prove that objects are passed by value, consider the following modified code:

function setName(obj) {
  obj.name = "Alice";
  obj = new Object();
  obj.name = "Greg";
}

let person = new Object();
setName(person);
console.log(person.name);  // "Alice"

The only change between this example and the previous one is that two lines have been added to setName() that redefine obj as a new object with a different name. When person is passed into setName(), its name property is set to “Alice.” Then the variable obj is set to be a new object and its name property is set to “Greg.” If person were passed by reference, then person would automatically be changed to point to the object whose name is “Greg.” However, when person.name is accessed again, its value is “Alice,” indicating that the original reference remained intact even though the argument's value changed inside the function. When obj is overwritten inside the function, it becomes a pointer to a local object. That local object is destroyed as soon as the function finishes executing.

Determining Type

The typeof operator, introduced in the previous chapter, is the best way to determine if a variable is a primitive type. More specifically, it's the best way to determine if a variable is a string, number, Boolean, or undefined. If the value is an object or null, then typeof returns “object,” as in this example:

let s = "Alice";
let b = true;
let i = 22;
let u;
let n = null;
let o = new Object();

console.log(typeof s);   // string
console.log(typeof i);   // number
console.log(typeof b);   // boolean
console.log(typeof u);   // undefined
console.log(typeof n);   // object
console.log(typeof o);   // object

Although typeof works well for primitive values, it's of little use for reference values. Typically, you don't care that a value is an object—what you really want to know is what type of object it is. To aid in this identification, ECMAScript provides the instanceof operator, which is used with the following syntax:

result = variable instanceof constructor

The instanceof operator returns true if the variable is an instance of the given reference type (identified by its prototype chain, as discussed in the Chapter 8, “Objects, Classes, and Object-Oriented Programming”). Consider this example:

console.log(person instanceof Object);   // is the variable person an Object?
console.log(colors instanceof Array);    // is the variable colors an Array?
console.log(pattern instanceof RegExp);  // is the variable pattern a RegExp?

All reference values, by definition, are instances of Object, so the instanceof operator always returns true when used with a reference value and the Object constructor. Similarly, if instanceof is used with a primitive value, it will always return false, because primitives aren't objects.

EXECUTION CONTEXT AND SCOPE

The concept of execution context, referred to as context for simplicity, is of the utmost importance in JavaScript. The execution context of a variable or function defines what other data it has access to, as well as how it should behave. Each execution context has an associated variable object upon which all of its defined variables and functions exist. This object is not accessible by code but is used behind the scenes to handle data.

The global execution context is the outermost one. Depending on the host environment for an ECMAScript implementation, the object representing this context may differ. In web browsers, the global context is said to be that of the window object (discussed in the Chapter 12, “The Browser Object Model”), so all global variables and functions defined with var are created as properties and methods on the window object. Declarations using let and const at the top level are not defined in the global context, but they are resolved identically on the scope chain. When an execution context has executed all of its code, it is destroyed, taking with it all of the variables and functions defined within it (the global context isn't destroyed until the application exits, such as when a web page is closed or a web browser is shut down).

Each function call has its own execution context. Whenever code execution flows into a function, the function's context is pushed onto a context stack. After the function has finished executing, the stack is popped, returning control to the previously executing context. This facility controls execution flow throughout an ECMAScript program.

When code is executed in a context, a scope chain of variable objects is created. The purpose of the scope chain is to provide ordered access to all variables and functions that an execution context has access to. The front of the scope chain is always the variable object of the context whose code is executing. If the context is a function, then the activation object is used as the variable object. An activation object starts with a single defined variable called arguments. (This doesn't exist for the global context.) The next variable object in the chain is from the containing context, and the next after that is from the next containing context. This pattern continues until the global context is reached; the global context's variable object is always the last of the scope chain.

Identifiers are resolved by navigating the scope chain in search of the identifier name. The search always begins at the front of the chain and proceeds to the back until the identifier is found. (If the identifier isn't found, typically an error occurs.)

Consider the following code:

var color = "blue";

function changeColor() {
  if (color === "blue") {
    color = "red";
  } else {
    color = "blue";
  }
}

changeColor();

In this simple example, the function changeColor() has a scope chain with two objects in it: its own variable object (upon which the arguments object is defined) and the global context's variable object. The variable color is therefore accessible inside the function, because it can be found in the scope chain.

Additionally, locally defined variables can be used interchangeably with global variables in a local context. Here's an example:

var color = "blue";

function changeColor() {
  let anotherColor = "red";

  function swapColors() {
    let tempColor = anotherColor;
    anotherColor = color;
    color = tempColor;

    // color, anotherColor, and tempColor are all accessible here
  }

  // color and anotherColor are accessible here, but not tempColor
  swapColors();
}

// only color is accessible here
changeColor();

There are three execution contexts in this code: global context, the local context of changeColor(), and the local context of swapColors(). The global context has one variable, color, and one function, changeColor(). The local context of changeColor() has one variable named anotherColor and one function named swapColors(), but it can also access the variable color from the global context. The local context of swapColors() has one variable, named tempColor, that is accessible only within that context. Neither the global context nor the local context of changeColors() has access to tempColor. Within swapColors(), though, the variables of the other two contexts are fully accessible because they are parent execution contexts. Figure 4.3 represents the scope chain for the previous example.

An illustration of example scope chain for nested functions. — **FIGURE 4.3**: Example scope chain for nested functions

In this figure, the rectangles represent specific execution contexts. An inner context can access everything from all outer contexts through the scope chain, but the outer contexts cannot access anything within an inner context. The connection between the contexts is linear and ordered. Each context can search up the scope chain for variables and functions, but no context can search down the scope chain into another execution context. There are three objects in the scope chain for the local context of swapColors(): the swapColors() variable object, the variable object from changeColor(), and the global variable object. The local context of swapColors() begins its search for variable and function names in its own variable object before moving along the chain. The scope chain for the changeColor() context has only two objects: its own variable object and the global variable object. This means that it cannot access the context of swapColors().

Scope Chain Augmentation

Even though there are only two primary types of execution contexts, global and function (the third exists inside of a call to eval()), there are other ways to augment the scope chain. Certain statements cause a temporary addition to the front of the scope chain that is later removed after code execution. There are two times when this occurs, specifically when execution enters either of the following:

The catch block in a try-catch statement
A with statement

Both of these statements add a variable object to the front of the scope chain. For the with statement, the specified object is added to the scope chain; for the catch statement, a new variable object is created and contains a declaration for the thrown error object. Consider the following:

function buildUrl() {
  let qs = "?debug=true";

  with(location){
    let url = href + qs;
  }

  return url;
}

In this example, the with statement is acting on the location object, so location itself is added to the front of the scope chain. There is one variable, qs, defined in the buildUrl() function. When the variable href is referenced, it's actually referring to location.href, which is in its own variable object. When the variable qs is referenced, it's referring to the variable defined in buildUrl(), which is in the function context's variable object. Inside the with statement is a variable declaration for url, which becomes part of the function's context and can, therefore, be returned as the function value.

Variable Declaration

ECMAScript variables can either be function scoped or block scoped. Furthermore, a block scoped variable can be declared as a const.

Function Scope Declaration Using var

When a variable is declared using var, it is automatically added to the most immediate context available. In a function, the most immediate one is the function's local context; in a with statement, the most immediate is the function context. If a variable is initialized without first being declared, it gets added to the global context automatically, as in this example:

function add(num1, num2) {
  var sum = num1 + num2;
  return sum;
}

let result = add(10, 20);  // 30
console.log(sum);          // causes an error: sum is not a valid variable

Here, the function add() defines a local variable named sum that contains the result of an addition operation. This value is returned as the function value, but the variable sum isn't accessible outside the function. If the var keyword is omitted from this example, sum becomes accessible after add() has been called, as shown here:

function add(num1, num2) {
  sum = num1 + num2;
  return sum;
}

let result = add(10, 20);  // 30
console.log(sum);          // 30

Here, the variable sum is initialized to a value without ever having been declared using var. When add() is called, sum is created in the global context and continues to exist even after the function has completed, allowing you to access it later.

A var declaration will be brought to the top of the function or global scope and before any existing code inside it. This is referred to as “hoisting.” This allows you to safely use a hoisted variable anywhere in the same scope without consideration for whether or not it was declared yet. However, in practice, this can lead to legal yet bizarre code in which a variable is used before it is declared. Here is an example of two equivalent code snippets in the global scope:

var name = "Jake";

// This is equivalent to:

name = 'Jake';
var name;

Here is an example of two equivalent functions:

function fn1() {
  var name = 'Jake';
}

// This is equivalent to:
function fn2() {
  var name;
  name = 'Jake';
}

You can prove to yourself that a variable is hoisted by inspecting it before its declaration. The hoisting of the declaration means you will see undefined instead of ReferenceError:

console.log(name);  // undefined
var name = 'Jake';

function() {
  console.log(name);  // undefined
  var name = 'Jake';
}

Block Scope Declaration Using let

Declaring variables with let operates much in the same way as var, but it is scoped at the block level. Block scope is defined as the nearest set of enclosing curly braces {}. This means if blocks, while blocks, function blocks, and even standalone blocks will be the extent of the scope of any variable declared with let.

if (true) {
  let a;
}
console.log(a);  // ReferenceError: a is not defined

while (true) {
  let b;
}
console.log(b);  // ReferenceError: b is not defined

function foo() {
  let c;
}
console.log(c);  // ReferenceError: c is not defined
                 // This should be unsurprising, as
                 // a var declaration would also throw an Error

// This is not an object literal, this is a standalone block.
// The JavaScript interpreter will identify it as such based on its contents.
{
  let d;
}
console.log(d);  // ReferenceError: d is not defined

In a similar departure from the behavior of var, let cannot be declared twice inside the same block scope. Duplicate var declarations are simply ignored; duplicate let declarations throw a SyntaxError.

var a;
var a;
// No errors thrown

{
  let b;
  let b;
}
// SyntaxError: Identifier 'b' has already been declared

The behavior of let is especially useful when using iterators inside loops. Iterator declarations using var will bleed outside the loop after it completes, which is frequently a very undesirable behavior. Consider these two examples:

for (var i = 0; i < 10; ++i) {}
console.log(i);  // 10

for (let j = 0; j < 10; ++j) {}
console.log(j);  // ReferenceError: j is not defined

let is technically hoisted in the JavaScript runtime, but because of the “temporal dead zone,” you are prevented from using the variable above its actual declaration. Therefore, for the purposes of writing JavaScript, let is not hoisted in the same way as var.

Constant Declaration Using const

A variable declared using const must be initialized to some value. Once declared, it cannot be reassigned to a new value at any point in its lifetime.

const a;  // SyntaxError: Missing initializer in const declaration

const b = 3;
console.log(b);  // 3
b = 4;  // TypeError: Assignment to a constant variable

Apart from its const rule enforcement, const variables behave identically to let variables:

if (true) {
  const a = 0;
}
console.log(a);  // ReferenceError: a is not defined

while (true) {
  const b = 1;
}
console.log(b);  // ReferenceError: b is not defined

function foo() {
  const c = 2;
}
console.log(c);  // ReferenceError: c is not defined

{
  const d = 3;
}
console.log(d);  // ReferenceError: d is not defined

The const declaration only applies to the top-level primitive or object. In other words, a const variable assigned to an object cannot be reassigned to another reference value, but the keys inside that object are not protected.

const o1 = {};
o1 = {};  // TypeError: Assignment to a constant variable;

const o2 = {};
o2.name = 'Jake';
console.log(o2.name);  // 'Jake'

If you wish to make the entire object immutable, you can use Object.freeze(), although attempted property assignment will not raise errors; it will just silently fail:

const o3 = Object.freeze({});
o3.name = 'Jake';
console.log(o3.name);  // undefined

Because const declarations imply that the value is of a single type and immutable, the JavaScript runtime compiler can replace all instances of it with its actual value instead of performing a variable lookup through a lookup table. The Google Chrome V8 engine performs such an optimization.

Identifier Lookup

When an identifier is referenced for either reading or writing within a particular context, a search must take place to determine what identifier it represents. The search starts at the front of the scope chain, looking for an identifier with the given name. If it finds that identifier name in the local context, then the search stops and the variable is set; if the search doesn't find the variable name, it continues along the scope chain. (Note that objects in the scope chain also have a prototype chain, so searching may include each object's prototype chain.) This process continues until the search reaches the global context's variable object. If the identifier isn't found there, it hasn't been declared.

To better illustrate how identifier lookup occurs, consider the following example:

var color = 'blue';

function getColor() {
  return color;
}

console.log(getColor());  // 'blue'

When the function getColor() is called in this example, the variable color is referenced. At that point, a two-step search begins. First getColor()'s variable object is searched for an identifier named color. When it isn't found, the search goes to the next variable object (from the global context) and then searches for an identifier named color. Because color is defined in that variable object, the search ends.

Given this search process, referencing local variables automatically stops the search from going into another variable object. This means that identifiers in a parent context cannot be referenced if an identifier in the local context has the same name, as in this example:

var color = 'blue';

function getColor() {
  let color = 'red';
  return color;
}

console.log(getColor());  // 'red'

Using block scoped declarations does not change the search process, but it can add extra levels to the lexical hierarchy:

var color = 'blue';

function getColor() {
  let color = 'red';
  {
    let color = 'green';
    return color;
  }
}

console.log(getColor());  // 'green'

In this modified code, a local variable named color is declared inside the getColor() function. When the function is called, the variable is declared. When the second line of the function is executed, it knows that a variable named color must be used. The search begins in the local context, where it finds a variable named color with a value of 'green'. Because the variable was found, the search stops and the local variable is used, meaning that the function returns 'green'. Any lines of code appearing after the declaration of color as a local variable cannot access the global color variable without qualifying it as window.color. If one of the operands is an object and the other is not, the valueOf() method is called on the object to retrieve a primitive value to compare according to the previous rules.

GARBAGE COLLECTION

JavaScript is a garbage-collected language, meaning that the execution environment is responsible for managing the memory required during code execution. In languages such as C and C++, keeping track of memory usage is a principle concern and the source of many issues for developers.

JavaScript frees developers from worrying about memory management by automatically allocating what is needed and reclaiming memory that is no longer being used. The basic idea is simple: figure out which variables aren't going to be used and free the memory associated with them. This process is periodic, with the garbage collector running at specified intervals (or at predefined collection moments in code execution). The process of garbage collection is an approximate and imperfect solution because the general problem of knowing whether some piece of memory is needed is “undecidable,” meaning it cannot be solved by an algorithm.

Consider the normal life cycle of a local variable in a function. The variable comes into existence during the execution of the function. At that time, memory is allocated on the stack (and possibly on the heap) to provide storage space for the value. The variable is used inside the function and then the function ends. At that point, this variable is no longer needed, so its memory can be reclaimed for later use. In this situation, it's obvious that the variable isn't needed, but not all situations are as obvious. The garbage collector must keep track of which variables can and can't be used so it can identify likely candidates for memory reclamation. The strategy for identifying the unused variables may differ on an implementation basis.

Performance

The garbage collector runs periodically and can potentially be an expensive process if there are a large number of variable allocations in memory, so the timing of the garbage-collection process is important. In particular, on mobile devices with limited system memory, garbage collection can noticeably degrade the speed and framerate of rendering. You cannot know when garbage collection is coming, so the best strategy is to organize your code in such a way that it allows garbage collection to do its job to the best of its ability whenever it is scheduled to run.

Modern garbage collectors decide when to run based on a collection of heuristics that are measured from the JavaScript runtime environment. These heuristics will vary by engine, but they will all be approximately based upon the size and number of objects that have been allocated. For example, from a V8 blog post in 2016: “At the end of a full garbage collection, V8's heap growing strategy determines when the next garbage collection will happen based on the amount of live objects with some additional slack.”

Managing Memory

In a garbage-collected programming environment, developers typically don't have to worry about memory management. However, JavaScript runs in an environment where memory management and garbage collection operate uniquely. The amount of memory available for use in web browsers is typically much less than is available for desktop applications, and even more so for mobile browsers. This is more of a security feature than anything else, ensuring that a web page running JavaScript can't crash the operating system by using up all the system memory. The memory limits affect not only variable allocation but also the call stack and the number of statements that can be executed in a single thread.

Keeping the amount of used memory to a minimum leads to better page performance. The best way to optimize memory usage is to ensure that you're keeping around only data that is necessary for the execution of your code. When data is no longer necessary, it's best to set the value to null, freeing up the reference—this is called dereferencing the value. This advice applies mostly to global values and properties of global objects. Local variables are dereferenced automatically when they go out of context, as in this example:

function createPerson(name){
  let localPerson = new Object();
  localPerson.name = name;
  return localPerson;
}

let globalPerson = createPerson("Alice");

// do something with globalPerson

globalPerson = null;

In this code, the variable globalPerson is filled with a value returned from the createPerson() function. Inside createPerson(), localPerson creates an object and adds a name property to it. The variable localPerson is returned as the function value and assigned to globalPerson. Because localPerson goes out of context after createPerson() has finished executing, it doesn't need to be dereferenced explicitly. Because globalPerson is a global variable, it should be dereferenced when it's no longer needed, which is what happens in the last line.

Keep in mind that dereferencing a value doesn't automatically reclaim the memory associated with it. The point of dereferencing is to make sure the value is out of context and will be reclaimed the next time garbage collection occurs.

Performance Boosts with const and let Declarations

Because const and let are scoped to a block instead of a function, depending on how your code is organized this may signal to the garbage collector that an allocated variable is eligible for cleanup far sooner than it would have been when using var. This would occur in situations when the block scope terminates far sooner than the function scope.

Hidden Classes and the delete Operation

The most popular browser engine is the V8 JavaScript engine. This engine utilizes “hidden classes” when compiling the interpreted JavaScript code into actual machine code, and if you are writing performance-sensitive code, this might matter to you.

During runtime, V8 will associate hidden classes for every object created to keep track of the shape of its properties. Objects that are able to share the same hidden class will have better performance, and V8 will optimize for this but may not always be able to. Consider the following code snippet:

function Article() {
  this.title = 'Inauguration Ceremony Features Kazoo Band';
}

let a1 = new Article();
let a2 = new Article();

Behind the scenes, V8 will configure the two class instances to share the same hidden class. This makes sense because they share a constructor and prototype. Suppose you then appended the following line to the end of this code:

a2.author = 'Jake';

Now, the two Article instances will have two divergent hidden class implementations. Depending on the frequency of this operation and the size of the hidden classes, this can have meaningful impacts on performance.

The solution, of course, is to avoid JavaScript's ready-fire-aim dynamic property assignment and instead declare all properties inside the constructor, as shown here:

function Article(opt_author) {
  this.title = 'Inauguration Ceremony Features Kazoo Band';
  this.author = opt_author;
}

let a1 = new Article();
let a2 = new Article('Jake');

Now, the two instances will behave in essentially the same way (not counting the return values of hasOwnProperty), and they will also share a hidden class, potentially yielding improved performance. Bear in mind though that using the delete keyword can generate the same hidden class fragmentation. This is demonstrated here:

function Article() {
  this.title = 'Inauguration Ceremony Features Kazoo Band';
  this.author = 'Jake';
}

let a1 = new Article();
let a2 = new Article();

delete a1.author;

At the end of this snippet, the two instances will no longer share a hidden class even though they use a unified constructor. Dynamic deletion of a property will yield the same effect as dynamic addition. Best practices dictate that unwanted properties should be set to null. It will allow the hidden classes to remain intact and shared, and it has the same effect on removing references for the benefit of the garbage collector.

function Article() {
  this.title = 'Inauguration Ceremony Features Kazoo Band';
  this.author = 'Jake';
}

let a1 = new Article();
let a2 = new Article();

a1.author = null;

Memory Leaks

Poorly written JavaScript can yield some sneaky and insidious memory leaks. On devices with limited memory, or in the context of functions that are called many times, this can cause big problems. Overwhelmingly, memory leaks in JavaScript are caused by unwanted references.

One of the most common and easily fixed memory leaks is accidentally declaring global variables. In the following code, the name variable is not prefixed with a declaration keyword:

function setName() {
  name = 'Jake';
}

In this example, the interpreter will handle this as window.name = 'Jake', and, of course, properties set on the window object will never be cleaned up if the window object itself is not cleaned up. This is easily fixed by prefixing the declaration with var, let, or const, which will all go out of scope at the end of the function's execution.

Interval timers can also quietly cause memory leaks. In the following code, the code sets an interval, which references a variable provided through a closure:

let name = 'Jake';
setInterval(() => {
  console.log(name);
}, 100);

As long as this interval timer is running, the handler function containing a reference to name remains allocated. The garbage collector recognizes this and therefore is unable to clean up the outer variable.

JavaScript closures are an exceedingly common way to leak memory without realizing it. Consider the following example:

let outer = function() {
  let name = 'Jake';
  return function() {
    return name;
  };
};

This leaks the memory allocated for name. This code creates an internal closure, so as long as the outer function exists, the name variable cannot be cleaned up because there will be a persistent reference to it through that closure. If the contents of the name variable were extremely large instead of just a short string, major problems could result.

Static Allocation and Object Pools

At the very end of the JavaScript performance spectrum, you may find yourself wanting to squeeze the very last bit of performance juice out of the browser. To accomplish this, a good place to focus is on minimizing the number of garbage collection operations the browser performs. Because you do not directly control when garbage collection occurs, you can instead optimize around the heuristics that browsers use when scheduling garbage collection. In theory, if you can responsibly use allocated memory and at the same time obviate superfluous garbage collection, then you will be able to make performance gains that would otherwise be lost freeing memory.

One important metric measured by the browser to decide when to schedule garbage collection is the rate of object churn. If lots of objects are being instantiated and then going out of scope, the browser will schedule garbage collections more aggressively, which of course will slow down the application. Consider the following example, a two dimensional vector addition function:

function addVector(a, b) {
  let resultant = new Vector();
  resultant.x = a.x + b.x;
  resultant.y = a.y + b.y;
  return resultant;
}

When invoked, this function creates a new object on the heap, modifies it, and returns it to the caller. If the lifetime of this vector object is short, it will soon lose all its references and be eligible for garbage collection. If this vector addition function is called frequently, the garbage collection scheduler will see this high rate of object churn, and garbage collection will be scheduled more frequently.

Instead of this dynamic vector creation, suppose you changed the method to use an existing vector object:

function addVector(a, b, resultant) {
  resultant.x = a.x + b.x;
  resultant.y = a.y + b.y;
  return resultant;
}

Of course, this requires the resultant vector argument to be fresh and instantiated somewhere else, but the behavior of this function is the same. Where then to create a vector while avoiding the gaze of the garbage collector heuristics?

One strategy is to use an object pool. At some point in initialization, you will create an object pool that manages a collection of recyclable objects. Your application can request an object from this pool, set its properties, use it, and return it to the pool when it's done. Because no object instantiation is occurring, garbage collection heuristics won't measure an uptick in object churn, and garbage collection will occur less frequently. An object pool pseudo-implementation might look something like this:

// vectorPool is the existing object pool
let v1 = vectorPool.allocate();
let v2 = vectorPool.allocate();
let v3 = vectorPool.allocate();

v1.x = 10;
v1.y = 5;
v2.x = -3;
v2.y = -6;

addVector(v1, v2, v3);

console.log([v3.x, v3.y]); // [7, -1]

vectorPool.free(v1);
vectorPool.free(v2);
vectorPool.free(v3);

// If the objects had properties referencing other objects,
// those would need to be set to null here as well
v1 = null;
v2 = null;
v3 = null;

If the object pool only allocates vectors as necessary (which creates new ones when they don't exist and reuses ones that already exist), this implementation is essentially a greedy algorithm that will have monotonically increasing yet static memory. This pool must maintain the collection using some structure, and a good choice is an Array. However, the implementation using an array must be designed carefully as to not incur additional garbage collection. Consider the following example:

let vectorList = new Array(100);
let vector = new Vector();
vectorList.push(vector);

Because JavaScript uses dynamically sized arrays, the engine will delete the array of size 100 and create a new array of size 200. The garbage collector will see this deletion and may be encouraged to run sooner because of it. This dynamic allocation can be avoided by creating an appropriately sized array upon initialization, which will enable you to avoid the aforementioned resizing operation. It will require, however, that you gain a sense of how large this array should be.

SUMMARY

Two types of values can be stored in JavaScript variables: primitive values and reference values. Primitive values have one of the seven primitive data types: Undefined, Null, Boolean, Number, BigInt, String, and Symbol. Primitive and reference values have the following characteristics:

Primitive values are of a fixed size and so are stored in memory on the stack.
Copying primitive values from one variable to another creates a second copy of the value.
Reference values are objects and are stored in memory on the heap.
A variable containing a reference value actually contains just a pointer to the object, not the object itself.
Copying a reference value to another variable copies just the pointer, so both variables end up referencing the same object.
The typeof operator determines a value's primitive type, whereas the instanceof operator is used to determine the reference type of a value.

All variables, primitive and reference, exist within an execution context (also called a scope) that determines the lifetime of the variable and which parts of the code can access it. Execution context can be summarized as follows:

Execution contexts exist globally (called the global context), within functions, and within blocks.
Each time a new execution context is entered, it creates a scope chain to search for variables and functions.
Contexts that are local to a function or block have access not only to variables in that scope but also to variables in any containing contexts and the global context.
The global context has access only to variables and functions in the global context and cannot directly access any data inside local contexts.
The execution context of variables helps to determine when memory will be freed.

JavaScript is a garbage-collected programming environment where the developer need not be concerned with memory allocation or reclamation. JavaScript's garbage-collection routine can be summarized as follows:

Values that go out of scope will automatically be marked for reclamation and will be deleted during the garbage-collection process.
Dereferencing variables helps not only with circular references but also with garbage collection in general. To aid in memory reclamation, global objects, properties on global objects, and circular references should all be dereferenced when no longer needed.

5
Basic Reference Types

A reference value (object) is an instance of a specific reference type. In ECMAScript, reference types are structures used to group data and functionality together and are often incorrectly called classes. Although technically an object-oriented language, ECMAScript lacks some basic constructs that have traditionally been associated with object-oriented programming, including classes and interfaces. Reference types are also sometimes called object definitions because they describe the properties and methods that objects should have.

Again, objects are considered to be instances of a particular reference type. New objects are created by using the new operator followed by a constructor. A constructor is simply a function whose purpose is to create a new object. Consider the following line of code:

let now = new Date();

This code creates a new instance of the Date reference type and stores it in the variable now. The constructor being used is Date(), which creates a simple object with only the default properties and methods. ECMAScript provides a number of native reference types, such as Date, to help developers with common computing tasks.

THE DATE TYPE

The ECMAScript Date type is based on an early version of java.util.Date from Java. As such, the Date type stores dates as the number of milliseconds that have passed since midnight on January 1, 1970 UTC (Universal Time Code). Using this data storage format, the Date type can accurately represent dates 285,616 years before or after January 1, 1970.

To create a date object, use the new operator along with the Date constructor, like this:

let now = new Date();

When the Date constructor is used without any arguments, the created object is assigned the current date and time. To create a date based on another date or time, you must pass in the millisecond representation of the date (the number of milliseconds after midnight, January 1, 1970 UTC, the Unix epoch). To aid in this process, ECMAScript provides two methods: Date.parse() and Date.UTC().

The Date.parse() method accepts a string argument representing a date. It attempts to convert the string into a millisecond representation of a date. ECMA-262 defines which date formats Date.parse() should support, filling in a void left by the third edition. All implementations must now support the following date formats:

month/date/year (such as 5/23/2019)
month_name date, year (such as May 23, 2019)
day_of_week month_name date year hours:minutes:seconds time_zone (such as Tue May 23 2019 00:00:00 GMT-0700)
ISO 8601 extended format YYYY-MM-DDTHH:mm:ss.sssZ (such as 2019-05-23T00:00:00) For instance, to create a date object for May 23, 2019, you can use the following code:

let someDate = new Date(Date.parse("May 23, 2019"));

If the string passed into Date.parse() doesn't represent a date, then it returns NaN. The Date constructor will call Date.parse() behind the scenes if a string is passed in directly, meaning that the following code is identical to the previous example:

let someDate = new Date("May 23, 2019");

This code produces the same result as the previous example.

The Date.UTC() method also returns the millisecond representation of a date but constructs that value using different information than Date.parse(). The arguments for Date.UTC() are the year, the zero-based month (January is 0, February is 1, and so on), the day of the month (1 through 31), and the hours (0 through 23), minutes, seconds, and milliseconds of the time. Of these arguments, only the first two (year and month) are required. If the day of the month isn't supplied, it's assumed to be 1, while all other omitted arguments are assumed to be 0. Here are two examples of Date.UTC() in action:

// January 1, 2000 at midnight GMT
let y2k = new Date(Date.UTC(2000, 0));
 
// May 5, 2005 at 5:55:55 PM GMT
let allFives = new Date(Date.UTC(2005, 4, 5, 17, 55, 55));

Two dates are created in this example. The first date is for midnight (GMT) on January 1, 2000, which is represented by the year 2000 and the month 0 (which is January). Because the other arguments are filled in (the day of the month as 1 and everything else as 0), the result is the first day of the month at midnight. The second date represents May 5, 2005, at 5:55:55 PM GMT. Even though the date and time contain only fives, creating this date requires some different numbers: the month must be set to 4 because months are zero-based, and the hour must be set to 17 because hours are represented as 0 through 23. The rest of the arguments are as expected.

As with Date.parse(), Date.UTC() is mimicked by the Date constructor but with one major difference: the date and time created are in the local time zone, not in GMT. However, the Date constructor takes the same arguments as Date.UTC(), so if the first argument is a number, the constructor assumes that it is the year of a date, the second argument is the month, and so on. The preceding example can then be rewritten as this:

// January 1, 2000 at midnight in local time
let y2k = new Date(2000, 0);
 
// May 5, 2005 at 5:55:55 PM local time
let allFives = new Date(2005, 4, 5, 17, 55, 55);

This code creates the same two dates as the previous example, but this time both dates are in the local time zone as determined by the system settings.

ECMAScript also offers Date.now(), which returns the millisecond representation of the date and time at which the method is executed. This method makes it trivial to use Date objects for code profiling, such as:

// get start time
let start = Date.now();
 
// call a function
doSomething();
 
// get stop time
let stop = Date.now(),
  result = stop – start;

Inherited Methods

As with the other reference types, the Date type overrides toLocaleString(), toString(), and valueOf(), though unlike the previous types, each method returns something different. The Date type's toLocaleString() method returns the date and time in a format appropriate for the locale in which the browser is being run. This often means that the format includes AM or PM for the time and doesn't include any time-zone information (the exact format varies from browser to browser). The toString() method typically returns the date and time with time-zone information, and the time is typically indicated in 24-hour notation (hours ranging from 0 to 23). The following displays the format for toLocaleString() and toString() when representing the date/time of February 1, 2019, at midnight PST (Pacific Standard Time) in the “en-US” locale:

toLocaleString() — 2/1/2019 12:00:00 AM
toString() — Thu Feb 1 2019 00:00:00 GMT-0800 (Pacific Standard Time)

Modern browsers have converged to output the same strings for these two methods. When using legacy browsers, there are differences between the formats that browsers return for each method. These differences mean toLocaleString() and toString() are useful only for debugging purposes, not for display purposes.

The valueOf() method for the Date type doesn't return a string at all because it is overridden to return the milliseconds representation of the date so that operators (such as less-than and greater-than) will work appropriately for date values. Consider this example:

let date1 = new Date(2019, 0, 1);    // "January 1, 2019"
let date2 = new Date(2019, 1, 1);    // "February 1, 2019"
 
console.log(date1 < date2);  // true
console.log(date1> date2);  // false

The date January 1, 2019, comes before February 1, 2019, so it would make sense to say that the former is less than the latter. Because the milliseconds representation of January 1, 2019, is less than that of February 1, 2019, the less-than operator returns true when the dates are compared, providing an easy way to determine the order of dates.

Date-Formatting Methods

There are several Date type methods used specifically to format the date as a string. They are as follows:

toDateString()—Displays the date's day of the week, month, day of the month, and year in an implementation-specific format.
toTimeString()—Displays the date's hours, minutes, seconds, and time zone in an implementation-specific format.
toLocaleDateString()—Displays the date's day of the week, month, day of the month, and year in an implementation- and locale-specific format.
toLocaleTimeString()—Displays the date's hours, minutes, and seconds in an implementation-specific format.
toUTCString()—Displays the complete UTC date in an implementation-specific format.

The output of these methods, as with toLocaleString() and toString(), varies widely from browser to browser and therefore can't be employed in a user interface for consistent display of a date.

Date/Time Component Methods

The remaining methods of the Date type (listed in the following table) deal directly with getting and setting specific parts of the date value. Note that references to a UTC date mean the date value when interpreted without a time-zone offset (the date when converted to GMT).

METHOD	DESCRIPTION
`getTime()`	Returns the milliseconds representation of the date; same as `valueOf()`.
`setTime(milliseconds)`	Sets the milliseconds representation of the date, thus changing the entire date.
`getFullYear()`	Returns the four-digit year (2019 instead of just 19).
`getUTCFullYear()`	Returns the four-digit year of the UTC date value.
`setFullYear(year)`	Sets the year of the date. The year must be given with four digits (2019 instead of just 19).
`setUTCFullYear(year)`	Sets the year of the UTC date. The year must be given with four digits (2019 instead of just 19).
`getMonth()`	Returns the month of the date, where 0 represents January and 11 represents December.
`getUTCMonth()`	Returns the month of the UTC date, where 0 represents January and 11 represents December.
`setMonth(month)`	Sets the month of the date, which is any number 0 or greater. Numbers greater than 11 add years.
`setUTCMonth(month)`	Sets the month of the UTC date, which is any number 0 or greater. Numbers greater than 11 add years.
`getDate()`	Returns the day of the month (1 through 31) for the date.
`getUTCDate()`	Returns the day of the month (1 through 31) for the UTC date.
`setDate(date)`	Sets the day of the month for the date. If the date is greater than the number of days in the month, the month value also gets increased.
`setUTCDate(date)`	Sets the day of the month for the UTC date. If the date is greater than the number of days in the month, the month value also gets increased.
`getDay()`	Returns the date's day of the week as a number (where 0 represents Sunday and 6 represents Saturday).
`getUTCDay()`	Returns the UTC date's day of the week as a number (where 0 represents Sunday and 6 represents Saturday).
`getHours()`	Returns the date's hours as a number between 0 and 23.
`getUTCHours()`	Returns the UTC date's hours as a number between 0 and 23.
`setHours(hours)`	Sets the date's hours. Setting the hours to a number greater than 23 also increments the day of the month.
`setUTCHours(hours)`	Sets the UTC date's hours. Setting the hours to a number greater than 23 also increments the day of the month.
`getMinutes()`	Returns the date's minutes as a number between 0 and 59.
`getUTCMinutes()`	Returns the UTC date's minutes as a number between 0 and 59.
`setMinutes(minutes)`	Sets the date's minutes. Setting the minutes to a number greater than 59 also increments the hour.
`setUTCMinutes(minutes)`	Sets the UTC date's minutes. Setting the minutes to a number greater than 59 also increments the hour.
`getSeconds()`	Returns the date's seconds as a number between 0 and 59.
`getUTCSeconds()`	Returns the UTC date's seconds as a number between 0 and 59.
`setSeconds(seconds)`	Sets the date's seconds. Setting the seconds to a number greater than 59 also increments the minutes.
`setUTCSeconds(seconds)`	Sets the UTC date's seconds. Setting the seconds to a number greater than 59 also increments the minutes.
`getMilliseconds()`	Returns the date's milliseconds.
`getUTCMilliseconds()`	Returns the UTC date's milliseconds.
`setMilliseconds(milliseconds)`	Sets the date's milliseconds.
`setUTCMilliseconds(milliseconds)`	Sets the UTC date's milliseconds.
`getTimezoneOffset()`	Returns the number of minutes that the local time zone is offset from UTC. For example, Eastern Standard Time returns 300. This value changes when an area goes into Daylight Saving Time.

THE REGEXP TYPE

ECMAScript supports regular expressions through the RegExp type. Regular expressions are easy to create using syntax similar to Perl, as shown here:

let expression = /pattern/flags;

The pattern part of the expression can be any simple or complicated regular expression, including character classes, quantifiers, grouping, lookaheads, and backreferences. Each expression can have zero or more flags indicating how the expression should behave. Three supported flags represent matching modes, as follows:

g—Indicates global mode, meaning the pattern will be applied to all of the string instead of stopping after the first match is found.
i—Indicates case-insensitive mode, meaning the case of the pattern and the string are ignored when determining matches.
m—Indicates multiline mode, meaning the pattern will continue looking for matches after reaching the end of one line of text.
y—Indicates sticky mode, meaning the pattern will only look at the string contents beginning at lastIndex.
u—Indicates Unicode mode is enabled.
s—Indicates singleline mode, meaning the wildcard character "." will match line break characters.
d—Indicates the result of a match should contain the start and end indices for each capture group.

A regular expression is created using a combination of a pattern and these flags to produce different results, as in this example:

// Match all instances of "at" in a string.
let pattern1 = /at/g;
 
// Match the first instance of "bat" or "cat", regardless of case.
let pattern2 = /[bc]at/i;
 
// Match all three-character combinations ending with "at", regardless of case.
let pattern3 = /.at/gi;

As with regular expressions in other languages, all metacharacters must be escaped when used as part of the pattern. The metacharacters are as follows:

( [ { \ ^ $ | ) ] } ? * + .

Each metacharacter has one or more uses in regular-expression syntax and so must be escaped by a backslash when you want to match the character in a string. Here are some examples:

// Match the first instance of "bat" or "cat", regardless of case.
let pattern1 = /[bc]at/i;
 
// Match the first instance of "[bc]at", regardless of case.
let pattern2 = /\[bc\]at/i;
 
// Match all three-character combinations ending with "at", regardless of case.
let pattern3 = /.at/gi;
 
// Match all instances of ".at", regardless of case.
let pattern4 = /\.at/gi;

In this code, pattern1 matches all instances of "bat" or "cat", regardless of case. To match "[bc]at" directly, both square brackets need to be escaped with a backslash, as in pattern2. In pattern3, the dot indicates that any character can precede "at" to be a match. If you want to match ".at", then the dot needs to be escaped, as in pattern4.

The preceding examples all define regular expressions using the literal form. Regular expressions can also be created by using the RegExp constructor, which accepts two arguments: a string pattern to match and an optional string of flags to apply. Any regular expression that can be defined using literal syntax can also be defined using the constructor, as in this example:

// Match the first instance of "bat" or "cat", regardless of case.
let pattern1 = /[bc]at/i;
 
// Same as pattern1, just using the constructor.
let pattern2 = new RegExp("[bc]at", "i");

Here, pattern1 and pattern2 define equivalent regular expressions. Note that both arguments of the RegExp constructor are strings (regular-expression literals should not be passed into the RegExp constructor). Because the pattern argument of the RegExp constructor is a string, there are some instances in which you need to double-escape characters. All metacharacters must be double-escaped, as must characters that are already escaped, such as \n (the \ character, which is normally escaped in strings as \\ becomes \\\\ when used in a regular-expression string). The following table shows some patterns in their literal form and the equivalent string that would be necessary to use the RegExp constructor.

LITERAL PATTERN	STRING EQUIVALENT
`/\[bc\]at/`	`"\\[bc\\]at"`
`/\.at/`	`"\\.at"`
`/name\/age/`	`"name\\/age"`
`/\d.\d{1,2}/`	`"\\d.\\d{1,2}"`
`/\w\\hello\\123/`	`"\\w\\\\hello\\\\123"`

It is also possible to copy existing regular expression instances and optionally modify their flags using the constructor:

const re1 = /cat/g;
console.log(re1);  // "/cat/g"
 
const re2 = new RegExp(re1);
console.log(re2);  // "/cat/g"
 
const re3 = new RegExp(re1, "i");
console.log(re3);  // "/cat/i"

Capture groups can be accessed by index, which is a terrific exercise in frustration because indices offer no context as to what they actually contain:

const text = '2018-03-14';
 
const re = /(\d+)-(\d+)-(\d+)/;
 
console.log(re.exec(text));
//["2018-03-14", "2018", "03", "14"]

Named capture groups allow for associating a valid JavaScript identifier with a capture group that can then be retrieved from the groups property of the result:

const text = '2018-03-14';
 
const re = /(?<year>\d+)-(?<month>\d+)-(?<day>\d+)/;
 
console.log(re.exec(text).groups);
// { year: "2018", month: "03", day: "14" }

RegExp Instance Properties

Each instance of RegExp has the following properties that allow you to get information about the pattern:

global—A Boolean value indicating whether the g flag has been set.
ignoreCase—A Boolean value indicating whether the i flag has been set.
unicode—A Boolean value indicating whether the u flag has been set.
sticky—A Boolean value indicating whether the y flag has been set.
lastIndex—An integer indicating the character position where the next match will be attempted in the source string. This value always begins as 0.
multiline—A Boolean value indicating whether the m flag has been set.
source—The string source of the regular expression. This is always returned as if specified in literal form (without opening and closing slashes) rather than a string pattern as passed into the constructor.
flags—The string flags of the regular expression. This is always returned as if specified in literal form (without opening and closing slashes) rather than a string pattern as passed into the constructor.
dotAll—A Boolean value indicating whether the s flag has been set.
hasIndices—A Boolean value indicating whether the d flag has been set.

These properties are helpful in identifying aspects of a regular expression; however, they typically don't have much use, because the information is available in the pattern declaration. Here's an example:

let pattern1 = /\[bc\]at/i;
 
console.log(pattern1.global);     // false
console.log(pattern1.ignoreCase); // true
console.log(pattern1.multiline);  // false
console.log(pattern1.lastIndex);  // 0
console.log(pattern1.source);     // "\[bc\]at"
console.log(pattern1.flags);      // "i"
 
let pattern2 = new RegExp("\\[bc\\]at", "i");
 
console.log(pattern2.global);     // false
console.log(pattern2.ignoreCase); // true
console.log(pattern2.multiline);  // false
console.log(pattern2.lastIndex);  // 0
console.log(pattern2.source);     // "\[bc\]at"
console.log(pattern2.flags);      // "i"

Note that the source and flags properties of each pattern are equivalent even though the first pattern is in literal form and the second uses the RegExp constructor. The source and flags properties normalize the string into the form you'd use in a literal.

RegExp Instance Methods

The primary method of a RegExp object is exec(), which is intended for use with capturing groups. This method accepts a single argument, which is the string on which to apply the pattern, and returns an array of information about the first match or null if no match was found. The returned array, though an instance of Array, contains two additional properties: index, which is the location in the string where the pattern was matched, and input, which is the string that the expression was run against. In the array, the first item is the string that matches the entire pattern. Any additional items represent captured groups inside the expression (if there are no capturing groups in the pattern, then the array has only one item). Consider the following:

let text = "mom and dad and baby";
let pattern = /mom( and dad( and baby)?)?/gi;
 
let matches = pattern.exec(text);
console.log(matches.index);  // 0
console.log(matches.input);  // "mom and dad and baby"
console.log(matches[0]);     // "mom and dad and baby"
console.log(matches[1]);     // " and dad and baby"
console.log(matches[2]);     // " and baby"

In this example, the pattern has two capturing groups. The innermost one matches " and baby", and its enclosing group matches " and dad" or " and dad and baby". When exec() is called on the string, a match is found. Because the entire string matches the pattern, the index property on the matches array is set to 0. The first item in the array is the entire matched string, the second contains the contents of the first capturing group, and the third contains the contents of the third capturing group.

The exec() method returns information about one match at a time even if the pattern is global. When the global flag is not specified, calling exec() on the same string multiple times will always return information about the first match.

let text = "cat, bat, sat, fat";
let pattern = /.at/;
 
let matches = pattern.exec(text);
console.log(matches.index);       // 0
console.log(matches[0]);          // cat
console.log(pattern.lastIndex);   // 0
 
matches = pattern.exec(text);
console.log(matches.index);       // 0
console.log(matches[0]);          // cat
console.log(pattern.lastIndex);   // 0

The pattern in this example is not global, so each call to exec() returns the first match only ("cat"). lastIndex remains unchanged in nonglobal mode.

With the global g flag set on the pattern, each call to exec() moves further into the string looking for matches, as in this example:

let text = "cat, bat, sat, fat";
let pattern = /.at/g;
 
let matches = pattern.exec(text);
console.log(matches.index);       // 0
console.log(matches[0]);          // cat
console.log(pattern.lastIndex);   // 3
 
matches = pattern.exec(text);
console.log(matches.index);       // 5
console.log(matches[0]);          // bat
console.log(pattern.lastIndex);   // 8
 
matches = pattern.exec(text);
console.log(matches.index);       // 10
console.log(matches[0]);          // sat
console.log(pattern.lastIndex);   // 13

This pattern is global, so each call to exec() returns the next match in the string until the end of the string is reached. Note also how the pattern's lastIndex property is affected. In global matching mode, lastIndex is incremented after each call to exec(). lastIndex tracks the index of the character that appears immediately to the right of the last match.

With the sticky y flag set on the pattern, each call to exec() will search for a match in the string only at lastIndex—nowhere else. The sticky flag overrides the global flag.

let text = "cat, bat, sat, fat";
let pattern = /.at/y;
 
let matches = pattern.exec(text);
console.log(matches.index);       // 0
console.log(matches[0]);          // cat
console.log(pattern.lastIndex);   // 3
 
// There is no match starting at character index 3, so exec() will return null
// exec() finding no matches resets lastIndex to 0
matches = pattern.exec(text);
console.log(matches);             // null
console.log(pattern.lastIndex);   // 0
 
// Advancing lastIndex will allow a sticky regex exec() to find the next match:
pattern.lastIndex = 5;
matches = pattern.exec(text);
console.log(matches.index);       // 5
console.log(matches[0]);          // bat
console.log(pattern.lastIndex);   // 8

Another method of regular expressions is test(), which accepts a string argument and returns true if the pattern matches the argument and false if it does not. This method is useful when you want to know if a pattern is matched, but you have no need for the actual matched text. The test() method is often used in if statements, such as the following:

let text = "000-00-0000";
let pattern = /\d{3}-\d{2}-\d{4}/;
 
if (pattern.test(text)) {
  console.log("The pattern was matched.");
}

In this example, the regular expression tests for a specific numeric sequence. If the input text matches the pattern, then a message is displayed. This functionality is often used for validating user input, when you care only if the input is valid, not necessarily why it's invalid.

The inherited methods of toLocaleString() and toString() each return the literal representation of the regular expression, regardless of how it was created. Consider this example:

let pattern = new RegExp("\\[bc\\]at", "gi");
console.log(pattern.toString());      // /\[bc\]at/gi
console.log(pattern.toLocaleString());  // /\[bc\]at/gi

Even though the pattern in this example is created using the RegExp constructor, the toLocaleString() and toString() methods return the pattern as if it were specified in literal format.

PRIMITIVE WRAPPER TYPES

Three special reference types are designed to ease interaction with primitive values: the Boolean type, the Number type, and the String type. These types can act like the other reference types described in this chapter, but they also have a special behavior related to their primitive-type equivalents. Every time a primitive value is read, an object of the corresponding primitive wrapper type is created behind the scenes, allowing access to any number of methods for manipulating the data. Consider the following example:

let s1 = "some text";
let s2 = s1.substring(2);

In this code, s1 is a variable containing a string, which is a primitive value. On the next line, the substring() method is called on s1 and stored in s2. Primitive values aren't objects, so logically they shouldn't have methods, though this still works as you would expect. In truth, there is a lot going on behind the scenes to allow this seamless operation. When s1 is accessed in the second line, it is being accessed in read mode, which is to say that its value is being read from memory. Any time a string value is accessed in read mode, the following three steps occur:

Create an instance of the String type.
Call the specified method on the instance.
Destroy the instance.

You can think of these three steps as they're used in the following three lines of ECMAScript code:

let s1 = new String("some text");
let s2 = s1.substring(2);
s1 = null;

This behavior allows the primitive string value to act like an object. These same three steps are repeated for Boolean and numeric values using the Boolean and Number types, respectively.

The major difference between reference types and primitive wrapper types is the lifetime of the object. When you instantiate a reference type using the new operator, it stays in memory until it goes out of scope, whereas automatically created primitive wrapper objects exist for only one line of code before they are destroyed. This means that properties and methods cannot be added at runtime. Take this for example:

let s1 = "some text";
s1.color = "red";
console.log(s1.color);   // undefined

Here, the second line attempts to add a color property to the string s1. However, when s1 is accessed on the third line, the color property is gone. This happens because the String object that was created in the second line is destroyed by the time the third line is executed. The third line creates its own String object, which doesn't have the color property.

It is possible to create the primitive wrapper objects explicitly using the Boolean, Number, and String constructors. This should be done only when absolutely necessary because it is often confusing for developers as to whether they are dealing with a primitive or reference value. Calling typeof on an instance of a primitive wrapper type returns "object", and all primitive wrapper objects convert to the Boolean value true.

The Object constructor also acts as a factory method and is capable of returning an instance of a primitive wrapper based on the type of value passed into the constructor. For example:

let obj = new Object("some text");
console.log(obj instanceof String);   // true

When a string is passed into the Object constructor, an instance of String is created; a number argument results in an instance of Number, while a Boolean argument returns an instance of Boolean.

Keep in mind that calling a primitive wrapper constructor using new is not the same as calling the casting function of the same name. For example:

let value = "25";
let number = Number(value);   // casting function
console.log(typeof number);     // "number"
let obj = new Number(value);  // constructor
console.log(typeof obj);        // "object"

In this example, the variable number is filled with a primitive number value of 25 while the variable obj is filled with an instance of Number.

Even though it's not recommended to create primitive wrapper objects explicitly, their functionality is important in being able to manipulate primitive values. Each primitive wrapper type has methods that make data manipulation easier.

The Boolean Type

The Boolean type is the reference type corresponding to the Boolean values. To create a Boolean object, use the Boolean constructor and pass in either true or false, as in the following example:

let booleanObject = new Boolean(true);

Instances of Boolean override the valueOf() method to return a primitive value of either true or false. The toString() method is also overridden to return a string of "true" or "false" when called. Unfortunately, not only are Boolean objects of little use in ECMAScript, but they can actually be rather confusing. The problem typically occurs when trying to use Boolean objects in Boolean expressions, as in this example:

let falseObject = new Boolean(false);
let result = falseObject && true;
console.log(result);  // true
 
let falseValue = false;
result = falseValue && true;
console.log(result);  // false

In this code, a Boolean object is created with a value of false. That same object is then ANDed with the primitive value true. In Boolean math, false && true equals false. However, in this line of code, it is the object named falseObject being evaluated, not its value (false). As discussed earlier, all objects are automatically converted to true in Boolean expressions, so falseObject actually is given a value of true in the expression. Then, true && true is equal to true.

There are a couple of other differences between the primitive and the reference Boolean types. The typeof operator returns "boolean" for the primitive but “object” for the reference. Also, a Boolean object is an instance of the Boolean type and will return true when used with the instanceof operator, whereas a primitive value returns false, as shown here:

console.log(typeof falseObject);        // object
console.log(typeof falseValue);         // boolean
console.log(falseObject instanceof Boolean);  // true
console.log(falseValue instanceof Boolean);   // false

It's very important to understand the difference between a primitive Boolean value and a Boolean object—prefer to never use the latter.

The Number Type

The Number type is the reference type for numeric values. To create a Number object, use the Number constructor and pass in any number. Here's an example:

let numberObject = new Number(10);

As with the Boolean type, the Number type overrides valueOf(), toLocaleString(), and toString(). The valueOf() method returns the primitive numeric value represented by the object, whereas the other two methods return the number as a string. The toString() method optionally accepts a single argument indicating the radix in which to represent the number, as shown in the following examples:

let num = 10;
console.log(num.toString());    // "10"
console.log(num.toString(2));   // "1010"
console.log(num.toString(8));   // "12"
console.log(num.toString(10));  // "10"
console.log(num.toString(16));  // "a"

Aside from the inherited methods, the Number type has several additional methods used to format numbers as strings.

The toFixed() method returns a string representation of a number with a specified number of decimal points, as in this example:

let num = 10;
console.log(num.toFixed(2));  // "10.00"

Here, the toFixed() method is given an argument of 2, which indicates how many decimal places should be displayed. As a result, the method returns the string "10.00", filling out the empty decimal places with zeros. If the number has more than the given number of decimal places, the result is rounded to the nearest decimal place, as shown here:

let num = 10.005;
console.log(num.toFixed(2));  // "10.01"

The rounding nature of toFixed() may be useful for applications dealing with currency, though it's worth noting that arithmetic operations between multiple floating point values may not produce exact results—for example, 0.1 + 0.2 = 0.30000000000000004.

Another method related to formatting numbers is the toExponential() method, which returns a string with the number formatted in exponential notation (aka e-notation). Just as with toFixed(), toExponential() accepts one argument, which is the number of decimal places to output. Consider this example:

let num = 10;
console.log(num.toExponential(1));  // "1.0e+1"

This code outputs “1.0e+1” as the result. Typically, this small number wouldn't be represented using e-notation. If you want to have the most appropriate form of the number, the toPrecision() method should be used instead.

The toPrecision() method returns either the fixed or the exponential representation of a number, depending on which makes the most sense. This method takes one argument, which is the total number of digits to use to represent the number (not including exponents). Here's an example:

let num = 99;
console.log(num.toPrecision(1));  // "1e+2"
console.log(num.toPrecision(2));  // "99"
console.log(num.toPrecision(3));  // "99.0"

In this example, the first task is to represent the number 99 with a single digit, which results in "1e+2", otherwise known as 100. Because 99 cannot accurately be represented by just one digit, the method rounded up to 100, which can be represented using just one digit. Representing 99 with two digits yields “99” and with three digits returns “99.0”. The toPrecision() method essentially determines whether to call toFixed() or toExponential() based on the numeric value you're working with; all three methods round up or down to accurately represent a number with the correct number of decimal places.

Similar to the Boolean object, the Number object gives important functionality to numeric values but really should not be instantiated directly because of the same potential problems. The typeof and instanceof operators work differently when dealing with primitive numbers versus reference numbers, as shown in the following examples:

let numberObject = new Number(10);
let numberValue = 10;
console.log(typeof numberObject);       // "object"
console.log(typeof numberValue);        // "number"
console.log(numberObject instanceof Number);  // true
console.log(numberValue instanceof Number);   // false

Primitive numbers always return "number" when typeof is called on them, whereas Number objects return "object". Similarly, a Number object is an instance of Number, but a primitive number is not.

The isInteger() Method and Safe Integers

The isInteger() method is capable of discerning whether or not a number value is stored as an integer or not. This is useful when a trailing decimal 0 may mask whether or not the number is actually stored in floating point format:

console.log(Number.isInteger(1));     // true
console.log(Number.isInteger(1.00));  // true
console.log(Number.isInteger(1.01));  // false

The IEEE 754 number format has a distinct numerical range inside which a binary value can represent exactly one integer value. This numerical range extends from Number.MIN_SAFE_INTEGER, or -2^53 + 1, to Number.MAX_SAFE_INTEGER, or 2^53 - 1. Outside this range, you may attempt to store an integer, but the IEEE 754 encoding format means that this binary value may also alias to a completely different number. To ascertain if an integer is inside this range, the isSafeInteger() method allows you to easily check this:

console.log(Number.isSafeInteger(-1 * (2 ** 53)));      // false
console.log(Number.isSafeInteger(-1 * (2 ** 53) + 1));  // true
 
console.log(Number.isSafeInteger(2 ** 53));             // false
console.log(Number.isSafeInteger((2 ** 53) - 1));       // true

The String Type

The String type is the object representation for strings and is created using the String constructor as follows:

let stringObject = new String("hello world");

The methods of a String object are available on all string primitives. All three of the inherited methods—valueOf(), toLocaleString(), and toString()—return the object's primitive string value.

Each instance of String contains a single property, length, which indicates the number of characters in the string. Consider the following example:

let stringValue = "hello world";
console.log(stringValue.length);   // "11"

This example outputs "11", the number of characters in "hello world". Note that even if the string contains a double-byte character (as opposed to an ASCII character, which uses just one byte), each character is still counted as one.

The String type has a large number of methods to aid in the dissection and manipulation of strings in ECMAScript.

The JavaScript Character

JavaScript strings consist of 16 bit code units. For most characters, each 16 bit code unit will correspond to a single character. The length property indicates how many 16 bit code units occur inside the string:

let message = "abcde";
 
console.log(message.length);  // 5

Furthermore, the charAt() returns the character at a given index, specified by an integer argument to the method. Specifically, this method finds the 16 bit code unit at the specified index and returns the character that corresponds to that code unit:

let message = "abcde";
 
console.log(message.charAt(2));  // "c"

JavaScript strings use a hybridized strategy of two Unicode encodings: UCS-2 and UTF-16. For characters which can be encoded with 16 bits (U+0000 to U+FFFF), these two encodings are effectively identical.

You can inspect the character encoding of a given code unit with the charCodeAt() method. This method returns the code unit value at a given index, specified by an integer argument to the method. This method is demonstrated here:

let message = "abcde";
 
// Unicode "Latin small letter C" is U+0063
console.log(message.charCodeAt(2));  // 99
 
// Decimal 99 === Hexadecimal 63
console.log(99 === 0x63);            // true

The fromCharCode() method is used for creating characters in a string from their UTF-16 code unit representation. This method accepts any number of numbers and returns their character equivalents concatenated into a string:

// Unicode "Latin small letter A" is U+0061
// Unicode "Latin small letter B" is U+0062
// Unicode "Latin small letter C" is U+0063
// Unicode "Latin small letter D" is U+0064
// Unicode "Latin small letter E" is U+0065
 
console.log(String.fromCharCode(0x61, 0x62, 0x63, 0x64, 0x65));  // "abcde"
 
// 0x0061 === 97
// 0x0062 === 98
// 0x0063 === 99
// 0x0064 === 100
// 0x0065 === 101
 
console.log(String.fromCharCode(97, 98, 99, 100, 101));          // "abcde"

For characters in the range of U+0000 to U+FFFF, length, charAt(), charCodeAt(), and fromCharCode() all behave exactly as you would expect them to. This is because every character is represented by exactly 16 bits, and each of these methods are all operating on 16 bit code units. As long as there is parity between character encoding size and code unit size, these methods will behave as expected.

This parity breaks down when expanding into the realm of Unicode supplementary character planes. The idea for this concept is relatively straightforward: 16 bits can only uniquely represent 65,536 characters. This is enough to cover most language character sets and is referred to as the Basic Multilingual Plane (BMP). In order to introduce even more characters, Unicode defined a strategy which used an additional 16 bits per character to select a supplementary or astral plane. Using two 16 bit code units per character is referred to as a surrogate pair.

With the introduction of this convention, the previously discussed string methods begin to break down. Consider the following example, which uses a smiley face emoji – a character which is encoded using a surrogate pair:

// The "smiling face with smiling eyes" emoji is U+1F60A
// 0x1F60A === 128522
let message = "abde";
 
console.log(message.length);         // 6
 
console.log(message.charAt(1));      // b
console.log(message.charAt(2));      // <?>
console.log(message.charAt(3));      // <?>
console.log(message.charAt(4));      // d
 
console.log(message.charCodeAt(1));  // 98
console.log(message.charCodeAt(2));  // 55357
console.log(message.charCodeAt(3));  // 56842
console.log(message.charCodeAt(4));  // 100
 
console.log(String.fromCharCode(0xD83D, 0xDE0A));  // 
 
 
console.log(String.fromCharCode(97, 98, 55357, 56842, 100, 101));  // abde

These methods are still treating each 16 bit code unit like a separate character, when in fact the code units at index 2 and 3 need to be considered together as a single surrogate pair to form a single character. The fromCharCode() method is still working correctly using the two code units separated because this method is literally assembling the string from a provided binary representation. The browser is able to correctly parse the surrogate pair (which was assembled as two separate code units) and correctly interpret it as a single smiley face Unicode character.

To correctly parse a string containing both single-code unit and surrogate pair characters, the codePointAt() method can be used instead of the error-prone charAt(). As is the case with charAt(), this method accepts a 16 bit code unit index and returns the code point at that index. A code point refers to the full Unicode identifier for a single character. The code point for "c" is 0x0063. The code point for “” is 0x1F60A. Code points may either require 16 or 32 bits to fully represent them, and the codePointAt() method will identify the full code point beginning at the specified code unit.

let message = "abde";
 
console.log(message.codePointAt(1));  // 98
console.log(message.codePointAt(2));  // 128522
console.log(message.codePointAt(3));  // 56842
console.log(message.codePointAt(4));  // 100

Notice in this example how a code point can be incorrectly identified if targeted at a code unit index that is not the start of a surrogate pair. This is only problematic for one-off character inspection, and can be averted by traversing the string from left to right and advancing the proper number of code units per iterator. The iterator for a string is intelligent enough to identify surrogate pair code points:

console.log([..."abde"]);  // ["a", "b", "", "d", "e"]

Just as charAt() has an analogue in codePointAt(), fromCharCode() has an analogue in fromCodePoint(). This method accepts any number of code point numbers and returns their character equivalents concatenated into a string:

console.log(String.fromCharCode(97, 98, 55357, 56842, 100, 101));  // abde
console.log(String.fromCodePoint(97, 98, 128522, 100, 101));       // abde

The normalize() Method

Some Unicode characters can be encoded in more than one way. Sometimes, a character can be represented by either a single BMP character or a surrogate pair. For example, consider the following:

// U+00C5: Latin capital letter A with ring above
console.log(String.fromCharCode(0x00C5));          // Å
 
// U+212B: Angstrom sign
console.log(String.fromCharCode(0x212B));          // Å
 
// U+0041: Latin captal letter A
// U+030A: Combining ring above
console.log(String.fromCharCode(0x0041, 0x030A));  // Å

Comparison operators do not care about the visual appearance of characters, and so these three will be considered distinct:

let a1 = String.fromCharCode(0x00C5),
    a2 = String.fromCharCode(0x212B),
    a3 = String.fromCharCode(0x0041, 0x030A);
 
console.log(a1, a2, a3);  // Å, Å, Å
 
console.log(a1 === a2);  // false
console.log(a1 === a3);  // false
console.log(a2 === a3);  // false

Unicode accounts for this by offering four normalization forms by which characters such as this one can be normalized into a consistent format irrespective of their character code derivation. These four normalization forms, Normalization Form D (NFD), Normalization Form C (NFC), Normalization Form KD (NFKD), and Normalization Form KC (NFKC), can be applied to a string using the normalize() method. This method should be provided with a string identifier to specify which normalization form to apply: NFD, NFC, NFKD, or NFKC.

It is possible to determine if a string is already normalized by checking it against the return value of normalize():

let a1 = String.fromCharCode(0x00C5),
    a2 = String.fromCharCode(0x212B),
    a3 = String.fromCharCode(0x0041, 0x030A);
 
// U+00C5 is the NFC/NFKC normalized form of 0+212B
console.log(a1 === a1.normalize("NFD"));   // false
console.log(a1 === a1.normalize("NFC"));   // true
console.log(a1 === a1.normalize("NFKD"));  // false
console.log(a1 === a1.normalize("NFKC"));  // true
 
// U+212B is non-normalized
console.log(a2 === a2.normalize("NFD"));   // false
console.log(a2 === a2.normalize("NFC"));   // false
console.log(a2 === a2.normalize("NFKD"));  // false
console.log(a2 === a2.normalize("NFKC"));  // false
 
// U+0041/U+030A is the NFD/NFKD normalized form of 0+212B
console.log(a3 === a3.normalize("NFD"));   // true
console.log(a3 === a3.normalize("NFC"));   // false
console.log(a3 === a3.normalize("NFKD"));  // true
console.log(a3 === a3.normalize("NFKC"));  // false

Selecting a normal form will allow for the comparison operator to behave as expected between identical characters:

let a1 = String.fromCharCode(0x00C5),
    a2 = String.fromCharCode(0x212B),
    a3 = String.fromCharCode(0x0041, 0x030A);
 
console.log(a1.normalize("NFD") === a2.normalize("NFD"));    // true
console.log(a2.normalize("NFKC") === a3.normalize("NFKC"));  // true
console.log(a1.normalize("NFC") === a3.normalize("NFC"));    // true

String-Manipulation Methods

Several methods manipulate the values of strings. The first of these methods is concat(), which is used to concatenate one or more strings to another, returning the concatenated string as the result. Consider the following example:

let stringValue = "hello ";
let result = stringValue.concat("world");
 
console.log(result);       // "hello world"
console.log(stringValue);  // "hello"

The result of calling the concat() method on stringValue in this example is “hello world”—the value of stringValue remains unchanged. The concat() method accepts any number of arguments, so it can create a string from any number of other strings, as shown here:

let stringValue = "hello ";
let result = stringValue.concat("world", "!");
 
console.log(result);       // "hello world!"
console.log(stringValue);  // "hello"

This modified example concatenates "world" and "!" to the end of "hello". Although the concat() method is provided for string concatenation, the addition operator (+) is used more often and, in most cases, actually performs better than the concat() method even when concatenating multiple strings.

ECMAScript provides three methods for creating string values from a substring: slice(), substr(), and substring(). All three methods return a substring of the string they act on, and all accept either one or two arguments. The first argument is the position where capture of the substring begins; the second argument, if used, indicates where the operation should stop. For slice() and substring(), this second argument is the position before which capture is stopped (all characters up to this point are included except the character at that point). For substr(), the second argument is the number of characters to return. If the second argument is omitted in any case, it is assumed that the ending position is the length of the string. Just as with the concat() method, slice(), substr(), and substring() do not alter the value of the string itself—they simply return a primitive string value as the result, leaving the original unchanged. Consider this example:

let stringValue = "hello world";
console.log(stringValue.slice(3));        // "lo world"
console.log(stringValue.substring(3));    // "lo world"
console.log(stringValue.substr(3));       // "lo world"
console.log(stringValue.slice(3, 7));     // "lo w"
console.log(stringValue.substring(3,7));  // "lo w"
console.log(stringValue.substr(3, 7));    // "lo worl"

In this example, slice(), substr(), and substring() are used in the same manner and, in most cases, return the same value. When given just one argument, 3, all three methods return “lo world” because the second "l" in "hello" is in position 3. When given two arguments, 3 and 7, slice() and substring() return "lo w" (the "o" in "world" is in position 7, so it is not included), while substr() returns "lo worl" because the second argument specifies the number of characters to return.

There are different behaviors for these methods when an argument is a negative number. For the slice() method, a negative argument is treated as the length of the string plus the negative argument.

For the substr() method, a negative first argument is treated as the length of the string plus the number, whereas a negative second number is converted to 0. For the substring() method, all negative numbers are converted to 0. Consider this example:

let stringValue = "hello world";
console.log(stringValue.slice(‐3));         // "rld"
console.log(stringValue.substring(‐3));     // "hello world"
console.log(stringValue.substr(‐3));        // "rld"
console.log(stringValue.slice(3, ‐4));      // "lo w"
console.log(stringValue.substring(3, ‐4));  // "hel"
console.log(stringValue.substr(3, ‐4));     // "" (empty string)

This example clearly indicates the differences between three methods. When slice() and substr() are called with a single negative argument, they act the same. This occurs because –3 is translated into 7 (the length plus the argument), effectively making the calls slice(7) and substr(7). The substring() method, on the other hand, returns the entire string because –3 is translated to 0.

When the second argument is negative, the three methods act differently from one another. The slice() method translates the second argument to 7, making the call equivalent to slice(3, 7) and so returning “lo w”. For the substring() method, the second argument gets translated to 0, making the call equivalent to substring(3, 0), which is actually equivalent to substring(0,3) because this method expects that the smaller number is the starting position and the larger one is the ending position. For the substr() method, the second argument is also converted to 0, which means there should be zero characters in the returned string, leading to the return value of an empty string.

String Location Methods

There are two methods for locating substrings within another string: indexOf() and lastIndexOf(). Both methods search a string for a given substring and return the position (or –1 if the substring isn't found). The difference between the two is that the indexOf() method begins looking for the substring at the beginning of the string, whereas the lastIndexOf() method begins looking from the end of the string. Consider this example:

let stringValue = "hello world";
console.log(stringValue.indexOf("o"));      // 4
console.log(stringValue.lastIndexOf("o"));  // 7

Here, the first occurrence of the string "o" is at position 4, which is the "o" in "hello". The last occurrence of the string "o" is in the word "world", at position 7. If there is only one occurrence of "o" in the string, then indexOf() and lastIndexOf() return the same position.

Each method accepts an optional second argument that indicates the position to start searching from within the string. This means that the indexOf() method will start searching from that position and go toward the end of the string, ignoring everything before the start position, whereas lastIndexOf() starts searching from the given position and continues searching toward the beginning of the string, ignoring everything between the given position and the end of the string. Here's an example:

let stringValue = "hello world";
console.log(stringValue.indexOf("o", 6));      // 7
console.log(stringValue.lastIndexOf("o", 6));  // 4

When the second argument of 6 is passed into each method, the results are the opposite from the previous example. This time, indexOf() returns 7 because it starts searching the string from position 6 (the letter "w") and continues to position 7, where "o" is found. The lastIndexOf() method returns 4 because the search starts from position 6 and continues back toward the beginning of the string, where it encounters the "o" in "hello". Using this second argument allows you to locate all instances of a substring by looping callings to indexOf() or lastIndexOf(), as in the following example:

let stringValue = "Lorem ipsum dolor sit amet, consectetur adipisicing elit";
let positions = new Array();
let pos = stringValue.indexOf("e");
 
while(pos> -1) {
  positions.push(pos);
  pos = stringValue.indexOf("e", pos + 1);
}
 
console.log(positions);  // "3,24,32,35,52"

This example works through a string by constantly increasing the position at which indexOf() should begin. It begins by getting the initial position of “e” in the string and then enters a loop that continually passes in the last position plus one to indexOf(), ensuring that the search continues after the last substring instance. Each position is stored in the positions array so the data can be used later.

String Inclusion Methods

ECMAScript includes three additional methods for determining if a string is included inside another string: startsWith(), endsWith(), and includes(). All methods search a string for a given substring and return a Boolean indicating whether it is not included. The difference between them is that startsWith() checks for a match beginning at index 0, endsWith() checks for a match beginning at index (string.length – substring.length), and includes() checks the entire string.

let message = "foobarbaz";
 
console.log(message.startsWith("foo"));  // true
console.log(message.startsWith("bar"));  // false
 
console.log(message.endsWith("baz"));    // true
console.log(message.endsWith("bar"));    // false
 
console.log(message.includes("bar"));    // true
console.log(message.includes("qux"));    // false

The startsWith() and includes() methods accept an optional second argument that indicates the position to start searching from within the string. This means that the methods will start searching from that position and go toward the end of the string, ignoring everything before the start position. Here's an example:

let message = "foobarbaz";
 
console.log(message.startsWith("foo"));     // true
console.log(message.startsWith("foo", 1));  // false
 
console.log(message.includes("bar"));       // true
console.log(message.includes("bar", 4));    // false

The endsWith() method accepts an optional second argument that indicates the position that should be treated as the end of the string. If this value is not provided, the length of the string is used by default. When a second argument is provided, the method will treat the string as if it only has that many characters:

let message = "foobarbaz";
 
console.log(message.endsWith("bar"));     // false
console.log(message.endsWith("bar", 6));  // true

The trim() Method

ECMAScript features a trim() method on all strings. The trim() method creates a copy of the string, removes all leading and trailing white space, and then returns the result. For example:

let stringValue = "  hello world  ";
let trimmedStringValue = stringValue.trim();
console.log(stringValue);         // "  hello world  "
console.log(trimmedStringValue);  // "hello world"

Note that since trim() returns a copy of a string, the original string remains intact with leading and trailing white space in place.

Also available are the trimLeft() and trimRight() methods that remove white space only from the beginning or end of the string, respectively.

trimStart() and trimEnd() allow for targeted white space removal. These methods are intended to replace trimLeft() and trimRight(), which have ambiguous meaning in the context of right-to-left languages such as Arabic and Hebrew.

These two methods are effectively the opposite of padStart() and padEnd() with a single space character. The following example adds white space to a string and then removes it on either side:

let s = '   foo   ';
 
console.log(s.trimStart());  // "foo   "
console.log(s.trimEnd());    // "   foo"

The repeat() Method

ECMAScript features a repeat() method on all strings. The repeat() method accepts a single integer argument count, copies the string count times, and concatenates all the copies.

let stringValue = "na ";
console.log(stringValue.repeat(16) + "batman");
// na na na na na na na na na na na na na na na na batman

The padStart() and padEnd() Methods

The padStart() and padEnd() methods will copy a string and, if the length of the string is less than the specified length, add padding to either side of a string to extend it to a certain length. The first argument is the desired length, and the second is the optional string to add as a pad. If not provided, the U+0020 ‘space' character will be used.

let stringValue = "foo";
 
console.log(stringValue.padStart(6));       // "   foo"
console.log(stringValue.padStart(9, "."));  // "......foo"
 
console.log(stringValue.padEnd(6));         // "foo   "
console.log(stringValue.padEnd(9, "."));    // "foo......"

The optional argument is not limited to a single character. If provided a multiple-character string, the method will use the concatenated padding and truncate it to the exact length. Additionally, if the length is less than or equal to the string length, the operation is effectively a no-op.

let stringValue = "foo";
 
console.log(stringValue.padStart(8, "bar"));  // "barbafoo"
console.log(stringValue.padStart(2));         // "foo"
 
console.log(stringValue.padEnd(8, "bar"));    // "foobarba"
console.log(stringValue.padEnd(2));           // "foo"

String Iterators and Destructuring

The string prototype exposes an @@iterator method on each string, which allows for iteration through individual characters. Manual use of the iterator works as follows:

let message = "abc";
let stringIterator = message[Symbol.iterator]();
 
console.log(stringIterator.next());  // {value: "a", done: false}
console.log(stringIterator.next());  // {value: "b", done: false}
console.log(stringIterator.next());  // {value: "c", done: false}
console.log(stringIterator.next());  // {value: undefined, done: true}

When used in a for-of loop, the loop will use this iterator to visit each character in order:

for (const c of "abcde") {
  console.log(c);
}
 
// a
// b
// c
// d
// e

The string iterator becomes especially useful since it allows for interoperability with the destructuring operator. This allows you to easily split a string by its characters:

let message = "abcde";
 
console.log([...message]);  // ["a", "b", "c", "d", "e"]

String Case Methods

The next set of methods involves case conversion. Four methods perform case conversion: toLowerCase(), toLocaleLowerCase(), toUpperCase(), and toLocaleUpperCase(). The toLowerCase() and toUpperCase() methods are the original methods, modeled after the same methods in java.lang.String. The toLocaleLowerCase() and toLocaleUpperCase() methods are intended to be implemented based on a particular locale. In many locales, the locale-specific methods are identical to the generic ones; however, a few languages (such as Turkish) apply special rules to Unicode case conversion, and this necessitates using the locale-specific methods for proper conversion. Here are some examples:

let stringValue = "hello world";
console.log(stringValue.toLocaleUpperCase());  // "HELLO WORLD"
console.log(stringValue.toUpperCase());        // "HELLO WORLD"
console.log(stringValue.toLocaleLowerCase());  // "hello world"
console.log(stringValue.toLowerCase());        // "hello world"

This code outputs "HELLO WORLD" for both toLocaleUpperCase() and toUpperCase(), just as "hello world" is output for both toLocaleLowerCase() and toLowerCase(). Generally speaking, if you do not know the language in which the code will be running, it is safer to use the locale-specific methods.

String Pattern-Matching Methods

The String type has several methods designed to pattern-match within the string. The first of these methods is match() and is essentially the same as calling a RegExp object's exec() method. The match() method accepts a single argument, which is either a regular-expression string or a RegExp object. Consider this example:

let text = "cat, bat, sat, fat";
let pattern = /.at/;
 
// same as pattern.exec(text)
let matches = text.match(pattern);
console.log(matches.index);      // 0
console.log(matches[0]);         // "cat"
console.log(pattern.lastIndex);  // 0

The array returned from match() is the same array that is returned when the RegExp object's exec() method is called with the string as an argument: the first item is the string that matches the entire pattern, and each other item (if applicable) represents capturing groups in the expression.

When using the global flag, match() will only return an array of matches—all capture groups are lost. To preserve capture groups when matching multiple values, use matchAll() instead. It accepts only global regular expressions and returns a RegExpStringIterator iterable of each match() therein. This distinction is demonstrated here:

 
const text = "abcdeazcde";
 
console.log(text.match(/a(.)c/));
// ['abc', 'b', index: 0, input: 'abcdeazcde', groups: undefined]
 
console.log(text.match(/a(.)c/g));
// ['abc', 'azc']
 
console.log([...text.matchAll(/a(.)c/g)]);
// [
//.   ['abc', 'b', index: 0, input: 'abcdeazcde', groups: undefined],
//.   ['azc', 'z', index: 5, input: 'abcdeazcde', groups: undefined]
// ]

Another method for finding patterns is search(). The only argument for this method is the same as the argument for match(): a regular expression specified by either a string or a RegExp object. The search() method returns the index of the first pattern occurrence in the string or –1 if it's not found. search() always begins looking for the pattern at the beginning of the string. Consider this example:

let text = "cat, bat, sat, fat";
let pos = text.search(/at/);
console.log(pos);  // 1

Here, search(/at/) returns 1, which is the first position of “at” in the string.

To simplify replacing substrings, ECMAScript provides the replace() method. This method accepts two arguments. The first argument can be a RegExp object or a string (the string is not converted to a regular expression), and the second argument can be a string or a function. If the first argument to replace() is a string, then only the first occurrence of the substring will be replaced. There are two ways to replace all instances of a substring: provide a regular expression with the global flag specified, or use replaceAll():

const text = "cat, bat, sat, fat";
let result = text.replace("at", "ond");
console.log(result);  // "cond, bat, sat, fat"
 
result = text.replace(/at/g, "ond");
console.log(result);  // "cond, bond, sond, fond"
 
result = text.replaceAll("at", "ond");
console.log(result);  // "cond, bond, sond, fond"

In this example, the string "at" is first passed into replace() with a replacement text of "ond". The result of the operation is that "cat" is changed to "cond", but the rest of the string remains intact. By changing the first argument to a regular expression with the global flag set, each instance of "at" is replaced with "ond". replaceAll() mirrors the global flag behavior.

When the second argument is a string, there are several special character sequences that can be used to insert values from the regular-expression operations. ECMA-262 specifies the following table of values.

SEQUENCE	REPLACEMENT TEXT
`$$`	$
`$&`	The substring matching the entire pattern. Same as `RegExp.lastMatch`.
`$'`	The part of the string occurring before the matched substring. Same as `RegExp.rightContext`.
$`	The part of the string occurring after the matched substring. Same as `RegExp.leftContext`.
`$n`	The nth capture, where n is a value 0–9. For instance, $1 is the first capture, $2 is the second, and so on. If there is no capture then the empty string is used.
`$nn`	The nnth capture, where nn is a value 01–99. For instance, $01 is the first capture, $02 is the second, and so on. If there is no capture then the empty string is used.

Using these special sequences allows replacement using information about the last match, such as in this example:

let text = "cat, bat, sat, fat";
result = text.replace(/(.at)/g, "word ($1)");
console.log(result);  // word (cat), word (bat), word (sat), word (fat)

Here, each word ending with "at" is replaced with "word" followed in parentheses by what it replaces by using the $1 sequence.

The second argument of replace() or replaceAll() may also be a function. When there is a single match, the function gets passed three arguments: the string match, the position of the match within the string, and the whole string. When there are multiple capturing groups, each matched string is passed in as an argument, with the last two arguments being the position of the pattern match in the string and the original string. The function should return a string indicating what the match should be replaced with. Using a function as the second argument allows more granular control over replacement text, as in this example:

function htmlEscape(text) {
  return text.replace(/[<>"&]/g, function(match, pos, originalText) {
    switch(match) {
      case "<":
        return "<";
      case ">":
        return ">";
      case "&":
        return "&";
      case "\"":
        return """;
    }
  });
}
 
console.log(htmlEscape("<p class=\"greeting\">Hello world!</p>"));
// "<p class="greeting">Hello world!</p>"

Here, the function htmlEscape() is defined to escape four characters for insertion into HTML: the less-than, greater-than, ampersand, and double-quote characters all must be escaped. The easiest way to accomplish this is to have a regular expression to look for those characters and then define a function that returns the specific HTML entities for each matched character.

The last string method for dealing with patterns is split(), which separates the string into an array of substrings based on a separator. The separator may be a string or a RegExp object. (The string is not considered a regular expression for this method.) An optional second argument, the array limit, ensures that the returned array will be no larger than a certain size. Consider this example:

let colorText = "red,blue,green,yellow";
let colors1 = colorText.split(",");       // ["red", "blue", "green", "yellow"]
let colors2 = colorText.split(",", 2);    // ["red", "blue"]
let colors3 = colorText.split(/[^\,]+/);  // ["", ",", ",", ",", ""]

In this example, the string colorText is a comma-separated string of colors. The call to split(",") retrieves an array of those colors, splitting the string on the comma character. To truncate the results to only two items, a second argument of 2 is specified. Last, using a regular expression, it's possible to get an array of the comma characters. Note that in this last call to split(), the returned array has an empty string before and after the commas. This happens because the separator specified by the regular expression appears at the beginning of the string (the substring "red") and at the end (the substring "yellow").

The localeCompare() Method

The last method is localeCompare(), which compares one string to another and returns one of three values as follows:

If the string should come alphabetically before the string argument, a negative number is returned. (Most often this is –1, but it is up to each implementation as to the actual value.)
If the string is equal to the string argument, 0 is returned.
If the string should come alphabetically after the string argument, a positive number is returned. (Most often this is 1, but once again, this is implementation-specific.)

Here's an example:

let stringValue = "yellow";
console.log(stringValue.localeCompare("brick"));  // 1
console.log(stringValue.localeCompare("yellow")); // 0
console.log(stringValue.localeCompare("zoo"));  // -1

In this code, the string “yellow” is compared to three different values: "brick", "yellow", and "zoo". Because "brick" comes alphabetically before "yellow", localeCompare() returns 1; “yellow” is equal to “yellow”, so localeCompare() returns 0 for that line; and “zoo” comes after “yellow”, so localeCompare() returns –1 for that line. Once again, because the values are implementation-specific, it is best to use localeCompare() as shown in this example:

function determineOrder(value) {
  let result = stringValue.localeCompare(value);
  if (result < 0) {
    console.log(`The string 'yellow' comes before the string '${value}'.`);
  } else if (result> 0) {
    console.log(`The string 'yellow' comes after the string '${value}'.`);
  } else {
    console.log(`The string 'yellow' is equal to the string '${value}'.`);
  }
}
 
determineOrder("brick");
determineOrder("yellow");
determineOrder("zoo");

By using this sort of construct, you can be sure that the code works correctly in all implementations.

The unique part of localeCompare() is that an implementation's locale (country and language) indicates exactly how this method operates. In the United States, where English is the standard language for ECMAScript implementations, localeCompare() is case-sensitive, determining that uppercase letters come alphabetically after lowercase letters. However, this may not be the case in other locales.

SINGLETON BUILT-IN OBJECTS

ECMA-262 defines a built-in object as “any object supplied by an ECMAScript implementation, independent of the host environment, which is present at the start of the execution of an ECMAScript program.” This means the developer does not need to explicitly instantiate a built-in object; it is already instantiated. You have already learned about most of the built-in objects, such as Object, Array, and String. There are two singleton built-in objects defined by ECMA-262: Global and Math.

The Global Object

The Global object is the most unique in ECMAScript because it isn't explicitly accessible. ECMA-262 specifies the Global object as a sort of catchall for properties and methods that don't otherwise have an owning object. In truth, there is no such thing as a global variable or global function; all variables and functions defined globally become properties of the Global object. Functions covered earlier in this book, such as isNaN(), isFinite(), parseInt(), and parseFloat(), are actually methods of the Global object. In addition to these, there are several other methods available on the Global object.

URI-Encoding Methods

The encodeURI() and encodeURIComponent() methods are used to encode URIs (Uniform Resource Identifiers) to be passed to the browser. To be valid, a URI cannot contain certain characters, such as spaces. The URI-encoding methods encode the URIs so that a browser can still accept and understand them, replacing all invalid characters with a special UTF-8 encoding.

The encodeURI() method is designed to work on an entire URI (for instance, www.wrox.com/illegal value.js), whereas encodeURIComponent() is designed to work solely on a segment of a URI (such as illegal value.js from the previous URI). The main difference between the two methods is that encodeURI() does not encode special characters that are part of a URI, such as the colon, forward slash, question mark, and pound sign, whereas encodeURIComponent() encodes every nonstandard character it finds. Consider this example:

let uri = "http:// www.wrox.com/illegal value.js#start";
 
// "http:// www.wrox.com/illegal%20value.js#start"
console.log(encodeURI(uri));
 
// "http%3A%2F%2Fwww.wrox.com%2Fillegal%20value.js%23start"
console.log(encodeURIComponent(uri));

Here, using encodeURI() left the value completely intact except for the space, which was replaced with %20. The encodeURIComponent() method replaced all nonalphanumeric characters with their encoded equivalents. This is why encodeURI() can be used on full URIs, whereas encodeURIComponent() can be used only on strings that are appended to the end of an existing URI.

The two counterparts to encodeURI() and encodeURIComponent() are decodeURI() and decodeURIComponent(). The decodeURI() method decodes only characters that would have been replaced by using encodeURI(). For instance, %20 is replaced with a space, but %23 is not replaced because it represents a pound sign (#), which encodeURI() does not replace. Likewise, decodeURIComponent() decodes all characters encoded by encodeURIComponent(), essentially meaning it decodes all special values. Consider this example:

let uri = "http%3A%2F%2Fwww.wrox.com%2Fillegal%20value.js%23start";
 
// http%3A%2F%2Fwww.wrox.com%2Fillegal value.js%23start
console.log(decodeURI(uri));
 
// http:// www.wrox.com/illegal value.js#start
console.log(decodeURIComponent(uri));

Here, the uri variable contains a string that is encoded using encodeURIComponent(). The first value output is the result of decodeURI(), which replaced only the %20 with a space. The second value is the output of decodeURIComponent(), which replaces all the special characters and outputs a string that has no escaping in it. (This string is not a valid URI.)

The eval() Method

The final method is perhaps the most powerful in the entire ECMAScript language: the eval() method. This method works like an entire ECMAScript interpreter and accepts one argument, a string of ECMAScript (or JavaScript) to execute. Here's an example:

eval("console.log('hi')");

This line is functionally equivalent to the following:

console.log("hi");

When the interpreter finds an eval() call, it interprets the argument into actual ECMAScript statements and then inserts it into place. Code executed by eval() is considered to be part of the execution context in which the call is made, and the executed code has the same scope chain as that context. This means variables that are defined in the containing context can be referenced inside an eval() call, such as in this example:

let msg = "hello world";
eval("console.log(msg)");  // "hello world"

Here, the variable msg is defined outside the context of the eval() call, yet the call to console.log() still displays the text “hello world” because the second line is replaced with a real line of code. Likewise, you can define a function or variables inside an eval() call that can be referenced by the code outside, as follows:

eval("function sayHi() { console.log('hi'); }");
sayHi();

Here, the sayHi() function is defined inside an eval() call. Because that call is replaced with the actual function, it is possible to call sayHi() on the following line. This works the same for variables:

eval("let msg = 'hello world';");
console.log(msg);  // "hello world"

Any variables or functions created inside of eval() will not be hoisted, as they are contained within a string when the code is being parsed. They are created only at the time of eval() execution.

In strict mode, variables and functions created inside of eval() are not accessible outside, so these last two examples would cause errors. Also, in strict mode, assigning a value to eval causes an error:

"use strict";
eval = "hi";  // causes error

Global Object Properties

The Global object has a number of properties, some of which have already been mentioned in this book. The special values of undefined, NaN, and Infinity are all properties of the Global object. Additionally, all native reference type constructors, such as Object and Function, are properties of the Global object. The following table lists all of the properties.

PROPERTY	DESCRIPTION
`undefined`	The special value `undefined`
`NaN`	The special value `NaN`
`Infinity`	The special value `Infinity`
`Object`	Constructor for `Object`
`Array`	Constructor for `Array`
`Function`	Constructor for `Function`
`Boolean`	Constructor for `Boolean`
`String`	Constructor for `String`
`Number`	Constructor for `Number`
`Date`	Constructor for `Date`
`RegExp`	Constructor for `RegExp`
`Symbol`	Pseudo-constructor for `Symbol`
`Error`	Constructor for `Error`
`EvalError`	Constructor for `EvalError`
`RangeError`	Constructor for `RangeError`
`ReferenceError`	Constructor for `ReferenceError`
`SyntaxError`	Constructor for `SyntaxError`
`TypeError`	Constructor for `TypeError`
`URIError`	Constructor for `URIError`

The Window Object

Though ECMA-262 doesn't indicate a way to access the Global object directly, web browsers implement it such that the window is the Global object's delegate. Therefore, all variables and functions declared in the global scope become properties on window. Consider this example:

var color = "red";
 
function sayColor() {
  console.log(window.color);
}
 
window.sayColor();  // "red"

Here, a global variable named color and a global function named sayColor() are defined. Inside sayColor(), the color variable is accessed via window.color to show that the global variable became a property of window. The function is then called directly off of the window object as window.sayColor(), which pops up the console.log.

Another way to retrieve the Global object is to use the following code:

let global = function() {
  return this;
}();

This code creates an immediately-invoked function expression that returns the value of this. As mentioned previously, the this value is equivalent to the Global object when a function is executed with no explicit this value specified (either by being an object method or via call()/apply()). Thus, calling a function that simply returns this is a consistent way to retrieve the Global object in any execution environment.

The Math Object

ECMAScript provides the Math object as a common location for mathematical formulas, information, and computation. The Math object offers a number of properties and methods to help these computations.

Math Object Properties

The Math object has several properties, consisting mostly of special values in the world of mathematics. The following table describes these properties.

PROPERTY	DESCRIPTION
`Math.E`	The value of e, the base of the natural logarithms
`Math.LN10`	The natural logarithm of 10
`Math.LN2`	The natural logarithm of 2
`Math.LOG2E`	The base 2 logarithm of e
`Math.LOG10E`	The base 10 logarithm of e
`Math.PI`	The value of π
`Math.SQRT1_2`	The square root of ½
`Math.SQRT2`	The square root of 2

Although the meanings and uses of these values are outside the scope of this book, they are defined in the ECMAScript specification and available when you need them.

The min() and max() Methods

The Math object also contains many methods aimed at performing both simple and complex mathematical calculations.

The min() and max() methods determine which number is the smallest or largest in a group of numbers. These methods accept any number of parameters, as shown in the following example:

let max = Math.max(3, 54, 32, 16);
console.log(max);  // 54
 
let min = Math.min(3, 54, 32, 16);
console.log(min);  // 3

Out of the numbers 3, 54, 32, and 16, Math.max() returns the number 54, whereas Math.min() returns the number 3. These methods are useful for avoiding extra loops and if statements to determine the maximum value out of a group of numbers.

To find the maximum or the minimum value in an array, you can use the spread operator as follows:

let values = [1, 2, 3, 4, 5, 6, 7, 8];
let max = Math.max(...values);

Rounding Methods

The next group of methods has to do with rounding decimal values into integers. Four methods—Math.ceil(), Math.floor(), Math.round(), and Math.fround()—handle rounding in different ways as described here:

The Math.ceil() method represents the ceiling function, which always rounds numbers up to the nearest integer value.
The Math.floor() method represents the floor function, which always rounds numbers down to the nearest integer value.
The Math.round() method represents a standard round function, which rounds up if the number is at least halfway to the next integer value (0.5 or higher) and rounds down if not. This is the way you were taught to round in elementary school.
The Math.fround() method returns the nearest single precision (32 bits) floating point representation of the number.

The following example illustrates how these methods work:

console.log(Math.ceil(25.9));   // 26
console.log(Math.ceil(25.5));   // 26
console.log(Math.ceil(25.1));   // 26
 
console.log(Math.round(25.9));  // 26
console.log(Math.round(25.5));  // 26
console.log(Math.round(25.1));  // 25
 
console.log(Math.fround(0.4));   // 0.4000000059604645
console.log(Math.fround(0.5));   // 0.5
console.log(Math.fround(25.9));  // 25.899999618530273
 
console.log(Math.floor(25.9));  // 25
console.log(Math.floor(25.5));  // 25
console.log(Math.floor(25.1));  // 25

For all values between 25 and 26 (exclusive), Math.ceil() always returns 26 because it will always round up. The Math.round() method returns 26 only if the number is 25.5 or greater; otherwise it returns 25. Last, Math.floor() returns 25 for all numbers between 25 and 26 (exclusive).

The random() Method

The Math.random() method returns a random number between the 0 and the 1, including 0 but not including 1. This is a favorite tool of websites that are trying to display random quotes or random facts upon entry of a website. You can use Math.random() to select numbers within a certain integer range by using the following formula:

number = Math.floor(Math.random() * total_number_of_choices + first_possible_value)

The Math.floor() method is used here because Math.random() always returns a decimal value, meaning that multiplying it by a number and adding another still yields a decimal value. So, if you wanted to select a number between 1 and 10, the code would look like this:

let num = Math.floor(Math.random() * 10 + 1);

You see 10 possible values (1 through 10), with the first possible value being 1. If you want to select a number between 2 and 10, then the code would look like this:

let num = Math.floor(Math.random() * 9 + 2);

There are only nine numbers when counting from 2 to 10, so the total number of choices is nine, with the first possible value being 2. Many times, it's just easier to use a function that handles the calculation of the total number of choices and the first possible value, as in this example:

function selectFrom(lowerValue, upperValue) {
  let choices = upperValue - lowerValue + 1;
  return Math.floor(Math.random() * choices + lowerValue);
}
 
let num = selectFrom(2,10);
console.log(num);  // number between 2 and 10, inclusive

Here, the function selectFrom() accepts two arguments: the lowest value that should be returned and the highest value that should be returned. The number of choices is calculated by subtracting the two values and adding one and then applying the previous formula to those numbers. So it's possible to select a number between 2 and 10 (inclusive) by calling selectFrom(2,10). Using the function, it's easy to select a random item from an array, as shown here:

let colors = ["red", "green", "blue", "yellow", "black", "purple", "brown"];
let color = colors[selectFrom(0, colors.length-1)];

In this example, the second argument to selectFrom() is the length of the array minus 1, which is the last position in an array.

Other Methods

The Math object has a lot of methods related to various simple and higher-level mathematical operations. It's beyond the scope of this book to discuss the ins and outs of each or in what situations they may be used, but the following table enumerates the remaining methods of the Math object.

METHOD	DESCRIPTION
`Math.abs(x)`	Returns the absolute value of `x`
`Math.exp(x)`	Returns `Math.E` raised to the power of `x`
`Math.expm1(x)`	Equivalent to `Math.exp(x) - 1`
`Math.log(x)`	Returns the natural logarithm of `x`
`Math.log1p(x)`	Equivalent to `1 + Math.log(x)`
`Math.pow(x, power)`	Returns `x` raised to the power of `power`
`Math.pow(...nums)`	Returns the square root of the sum of the squares of each number in `nums`
`Math.clz32(x)`	Returns the number of leading zeroes of a 32-bit integer `x`
`Math.sign(x)`	Returns 1, 0, -0, or -1 indicating the sign of `x`
`Math.trunc(x)`	Returns the integer component of `x`, removing any decimals
`Math.sqrt(x)`	Returns the square root of `x`
`Math.cbrt(x)`	Returns the cubic root of `x`
`Math.acos(x)`	Returns the arc cosine of `x`
`Math.acosh(x)`	Returns the hyperbolic arc cosine of `x`
`Math.asin(x)`	Returns the arc sine of `x`
`Math.asin(x)`	Returns the hyperbolic arc sine of `x`
`Math.atan(x)`	Returns the arc tangent of `x`
`Math.atanh(x)`	Returns the hyperbolic arc tangent of `x`
`Math.atan2(y, x)`	Returns the arc tangent of `y/x`
`Math.cos(x)`	Returns the cosine of `x`
`Math.sin(x)`	Returns the sine of `x`
`Math.tan(x)`	Returns the tangent of `x`

Even though these methods are defined by ECMA-262, the results are implementation-dependent for those dealing with sines, cosines, and tangents, because you can calculate each value in many different ways. Consequently, the precision of the results may vary from one implementation to another.

SUMMARY

Objects in JavaScript are called reference values, and several built-in reference types can be used to create specific types of objects, as follows:

Reference types are similar to classes in traditional object-oriented programming but are implemented differently.
The Date type provides information about dates and times, including the current date and time and calculations.
The RegExp type is an interface for regular-expression support in ECMAScript, providing most basic and some advanced regular-expression functionality.

One of the unique aspects of JavaScript is that functions are actually instances of the Function type, meaning functions are objects. Because functions are objects, functions have methods that can be used to augment how they behave.

Because of the existence of primitive wrapper types, primitive values in JavaScript can be accessed as if they were objects. There are three primitive wrapper types: Boolean, Number, and String. They all have the following characteristics:

Each of the wrapper types maps to the primitive type of the same name.
When a primitive value is accessed in read mode, a primitive wrapper object is instantiated so that it can be used to manipulate the data.
As soon as a statement involving a primitive value is executed, the wrapper object is destroyed.

There are also two built-in objects that exist at the beginning of code execution: Global and Math. The Global object isn't accessible in most ECMAScript implementations; however, web browsers implement it as the window object. The Global object contains all global variables and functions as properties. The Math object contains properties and methods to aid in complex mathematical calculations.

6
Advanced Reference Types

THE OBJECT TYPE

Up to this point, most of the reference-value examples have used the Object type, which is one of the most commonly used types in ECMAScript. Although instances of Object don't have much functionality, they are ideally suited to storing and transmitting data around an application.

There are two ways to explicitly create an instance of Object. The first is to use the new operator with the Object constructor like this:

let person = new Object();
person.name = "Matt";
person.age = 29;

The other way is to use object literal notation. Object literal notation is a shorthand form of object definition designed to simplify creating an object with numerous properties. For example, the following defines the same person object from the previous example using object literal notation:

let person = {
  name: "Matt",
  age: 29
};

In this example, the left curly brace ({) signifies the beginning of an object literal because it occurs in an expression context. An expression context in ECMAScript is a context in which a value (expression) is expected. Assignment operators indicate that a value is expected next, so the left curly brace indicates the beginning of an expression. The same curly brace, when appearing in a statement context, such as follows an if statement condition, indicates the beginning of a block statement.

Next, the name property is specified, followed by a colon, followed by the property's value. A comma is used to separate properties in an object literal, so there's a comma after the string "Matt" but not after the value 29 because age is the last property in the object. Including a comma after the last property is allowed in all modern browsers.

Property names can also be specified as strings or numbers when using object literal notation, such as in this example:

let person = {
  "name": "Matt",
  "age": 29,
  5: true
};

This example produces an object with a name property, an age property, and a property 5. Note that numeric property names are automatically converted to strings.

It's also possible to create an object with only the default properties and methods using object literal notation by leaving the space between the curly braces empty, such as this:

let person = {};  // same as new Object()
person.name = "Matt";
person.age = 29;

This example is equivalent to the first one in this section, though it looks a little strange. Prefer to use object literal notation only when you're going to specify properties for readability.

Though it's acceptable to use either method of creating Object instances, developers tend to favor object literal notation because it requires less code and visually encapsulates all related data. In fact, object literals have become a preferred way of passing a large number of optional arguments to a function, such as in this example:

function displayInfo(args) {
  let output = "";
 
  if (typeof args.name == "string"){
    output += "Name: " + args.name + "\n";
  }
 
  if (typeof args.age == "number") {
    output += "Age: " + args.age + "\n";
  }
 
  alert(output);
}
 
displayInfo({
  name: "Matt",
  age: 29
});
 
displayInfo({
  name: "Greg"
});

Here, the function displayInfo() accepts a single argument named args. The argument may come in with a property called name or age or both or neither of those. The function is set up to test for the existence of each property using the typeof operator and then to construct a message to display based on availability. This function is then called twice, each time with different data specified in an object literal. The function works correctly in both cases.

Although object properties are typically accessed using dot notation, which is common to many object-oriented languages, it's also possible to access properties via bracket notation. When you use bracket notation, a string containing the property name is placed between the brackets, as in this example:

alert(person["name"]);  // "Matt"
alert(person.name);     // "Matt"

Functionally, there is no difference between the two approaches. The main advantage of bracket notation is that it allows you to use variables for property access, as in this example:

let propertyName = "name";
alert(person[propertyName]);  // "Matt"

You can also use bracket notation when the property name contains characters that would be either a syntax error or a keyword/reserved word. For example:

person["first name"] = "Matt";

Because the name "first name" contains a space, you can't use dot notation to access it. However, property names can contain nonalphanumeric characters—you just need to use bracket notation to access them.

Generally speaking, dot notation is preferred unless variables are necessary to access properties by name.

THE ARRAY TYPE

After the Object type, the Array type is probably the most used in ECMAScript. An ECMAScript array is very different from arrays in most other programming languages. As in other languages, ECMAScript arrays are ordered lists of data, but unlike in other languages, they can hold any type of data in each slot. This means that it's possible to create an array that has a string in the first position, a number in the second, an object in the third, and so on. ECMAScript arrays are also dynamically sized, automatically growing to accommodate any data that is added to them.

Creating Arrays

Arrays can be created in several basic ways. One is to use the Array constructor, as in this line:

let colors = new Array();

If you know the number of items that will be in the array, you can pass the count into the constructor, and the length property will automatically be created with that value. For example, the following creates an array with an initial length value of 20:

let colors = new Array(20);

The Array constructor can also be passed items that should be included in the array. The following creates an array with three string values:

let colors = new Array("red", "blue", "green");

An array can be created with a single value by passing it into the constructor. This gets a little bit tricky because providing a single argument that is a number always creates an array with the given number of items, whereas an argument of any other type creates a one-item array that contains the specified value. Here's an example:

let colors = new Array(3);      // create an array with three items
let names = new Array("Greg");  // create an array with one item, the string "Greg"

It's possible to omit the new operator when using the Array constructor. It has the same result, as you can see here:

let colors = Array(3);      // create an array with three items
let names = Array("Greg");  // create an array with one item, the string "Greg"

A second way to create an array is by using array literal notation. An array literal is specified by using square brackets and placing a comma-separated list of items between them, as in this example:

let colors = ["red", "blue", "green"];  // Creates an array with three strings
let names = [];                         // Creates an empty array
let values = [1,2,];                    // Creates an array with 2 items

In this code, the first line creates an array with three string values. The second line creates an empty array by using empty square brackets. The third line shows the effects of leaving a comma after the last value in an array literal: values is a two-item array containing the values 1 and 2.

The Array constructor also has two additional static methods to create arrays: from() and of(). from() is used for converting array-like constructs into an array instance, whereas of() is used to convert a collection of arguments into an array instance.

The first argument to Array.from() is an arrayLike object, which is anything that is iterable or has a property length and indexed elements. This type can be used in an abundance of different ways:

// Strings will be broken up into an array of single characters
alert(Array.from("Matt"));  // ["M", "a", "t", "t"]
 
// Sets and Maps can be converted into a new array instance using from()
const m = new Map().set(1, 2)
                   .set(3, 4);
const s = new Set().add(1)
                   .add(2)
                   .add(3)
                   .add(4);
 
alert(Array.from(m));  // [[1, 2], [3, 4]]
alert(Array.from(s));  // [1, 2, 3, 4]
 
// Array.from() performs a shallow copy of an existing array
const a1 = [1, 2, 3, 4];
const a2 = Array.from(a1);
alert(a1);         // [1, 2, 3, 4]
alert(a1 === a2);  // false
 
 
// Any iterable object can be used
const iter = {
  *[Symbol.iterator]() {
    yield 1;
    yield 2;
    yield 3;
    yield 4;
 
  }
};
alert(Array.from(iter));  // [1, 2, 3, 4]
 
// The arguments object can now easily be casted into an array:
function getArgsArray() {
  return Array.from(arguments);
}
alert(getArgsArray(1, 2, 3, 4));  // [1, 2, 3, 4]
 
// from() will happily use a custom object with required properties
const arrayLikeObject = {
  0: 1,
  1: 2,
  2: 3,
  3: 4,
  length: 4
};
alert(Array.from(arrayLikeObject));  // [1, 2, 3, 4]

Array.from() also accepts a second optional map function argument. This allows you to augment the new array's values without creating an intermediate array first, which is the case if the same were performed with Array.from().map(). A third optional argument specifies the value of this inside the map function. The overridden this value is not applied inside an arrow function:

const a1 = [1, 2, 3, 4];
const a2 = Array.from(a1, x => x**2);
const a3 = Array.from(a1, function(x) {return x**this.exponent}, {exponent: 2});
alert(a2);  // [1, 4, 9, 16]
alert(a3);  // [1, 4, 9, 16]

Array.of() will convert the list of arguments into an array. This serves to replace the common pre-ES6 method of converting the arguments object into an array using the unwieldy Array.prototype.slice.call(arguments):

alert(Array.of(1, 2, 3, 4));  // [1, 2, 3, 4]
alert(Array.of(undefined));   // [undefined]

Array Holes

Initializing an array with an array literal allows you to create “holes” using sequential commas. ECMAScript will treat the value at the index between the commas as a hole. An array of holes might be created as follows:

const options = [,,,,,];  // Creates an array with 5 items
alert(options.length);    // 5
alert(options);           // [,,,,,]

Methods and iterators introduced in ES6 behave differently than methods present in earlier ECMAScript editions. ES6 additions will universally treat the holes as an existing entry with a value of undefined:

const options = [1,,,,5];
 
for (const option of options) {
  alert(option === undefined);
}
// false
// true
// true
// true
// false
 
const a = Array.from([,,,]); // Array of 3 holes created with ES6's Array.from()
for (const val of a) {
  alert(val === undefined);
}
// true
// true
// true
 
alert(Array.of([,,,])); // [undefined, undefined, undefined]
 
for (const [index, value] of options.entries()) {
  alert(value);
}
// 1
// undefined
// undefined
// undefined
// 5

Conversely, methods available before ES6 will tend to ignore the holes, although exact behavior can vary slightly between methods:

const options = [1,,,,5];
 
// map() will skip the holes entirely
alert(options.map(() => 6));  // [6, undefined, undefined, undefined, 6]
 
// join() treats holes as empty strings
alert(options.join('-'));     // "1----5"

Indexing into Arrays

To get and set array values, you use square brackets and provide the zero-based numeric index of the value, as shown here:

let colors = ["red", "blue", "green"];  // define an array of strings
alert(colors[0]);                       // display the first item
colors[2] = "black";                    // change the third item
colors[3] = "brown";                    // add a fourth item

The index provided within the square brackets indicates the value being accessed. If the index is less than the number of items in the array, then it will return the value stored in the corresponding item, as colors[0] displays "red" in this example. Setting a value works in the same way, replacing the value in the designated position. If a value is set to an index that is past the end of the array, as with colors[3] in this example, the array length is automatically expanded to be that index plus 1 (so the length becomes 4 in this example because the index being used is 3).

The number of items in an array is stored in the length property, which always returns 0 or more, as shown in the following example:

let colors = ["red", "blue", "green"];  // creates an array with three strings
let names = [];                         // creates an empty array
 
alert(colors.length);  // 3
alert(names.length);   // 0

A unique characteristic of length is that it's not read-only. By setting the length property, you can easily remove items from or add items to the end of the array. Consider this example:

let colors = ["red", "blue", "green"]; // creates an array with three strings
colors.length = 2;
alert(colors[2]);  // undefined

Here, the array colors starts out with three values. Setting the length to 2 removes the last item (in position 2), making it no longer accessible using colors[2]. If the length were set to a number greater than the number of items in the array, the new items would each get filled with the value of undefined, as in this example:

let colors = ["red", "blue", "green"];  // creates an array with three strings
colors.length = 4;
alert(colors[3]);  // undefined

This code sets the length of the colors array to 4 even though it contains only three items. Position 3 does not exist in the array, so trying to access its value results in the special value undefined being returned.

The length property can also be helpful in adding items to the end of an array, as in this example:

let colors = ["red", "blue", "green"];  // creates an array with three strings
colors[colors.length] = "black";        // add a color (position 3)
colors[colors.length] = "brown";        // add another color (position 4)

The last item in an array is always at position length–1, so the next available open slot is at position length. Each time an item is added after the last one in the array, the length property is automatically updated to reflect the change. That means colors[colors.length] assigns a value to position 3 in the second line of this example and to position 4 in the last line. The new length is automatically calculated when an item is placed into a position that's outside of the current array size, which is done by adding 1 to the position, as in this example:

let colors = ["red", "blue", "green"];  // creates an array with three strings
colors[99] = "black";                   // add a color (position 99)
alert(colors.length);                   // 100

In this code, the colors array has a value inserted into position 99, resulting in a new length of 100 (99 + 1). Each of the other items, positions 3 through 98, doesn't actually exist and so returns undefined when accessed.

The at() method was introduced to make it easier to access elements within an array, especially when working with negative indices. The method takes an integer argument and returns the element at that position within the array. Positive indices work as expected, while negative indices count from the end of the array, with -1 representing the last element, -2 representing the second to last element, and so on.

let colors = ["red", "blue", "green"];
 
console.log(colors.at(0));       // "red"
console.log(colors.at(-1));      // "green"
console.log(colors.at(-2));      // "blue"
console.log(colors.at(100));     // undefined
console.log(colors.at(-100));    // undefined

Detecting Arrays

A classic ECMAScript problem is determining whether a given object is an array. When dealing with a single web page, and therefore a single global scope, the instanceof operator works well:

if (value instanceof Array){
  // do something on the array
}

The one problem with instanceof is that it assumes a single global execution context. If you are dealing with multiple frames in a web page, you're really dealing with two distinct global execution contexts and therefore two versions of the Array constructor. If you were to pass an array from one frame into a second frame, that array has a different constructor function than an array created natively in the second frame.

To work around this problem, ECMAScript offers the Array.isArray() method. The purpose of this method is to definitively determine if a given value is an array regardless of the global execution context in which it was created. Consider the following example:

if (Array.isArray(value)){
  // do something on the array
}

Iterator Methods

Three methods are exposed on the Array prototype that allow you to inspect the contents of an array: keys(), values(), and entries(). keys() will return an iterator of the array's indices, values() will return an iterator of the array's elements, and entries() will return an iterator of index/value pairs:

const a = ["foo", "bar", "baz", "qux"];
 
// Because these methods return iterators, you can funnel their contents
// into array instances using Array.from()
const aKeys = Array.from(a.keys());
const aValues = Array.from(a.values());
const aEntries = Array.from(a.entries());
 
alert(aKeys);     // [0, 1, 2, 3]
alert(aValues);   // ["foo", "bar", "baz", "qux"]
alert(aEntries);  // [[0, "foo"], [1, "bar"], [2, "baz"], [3, "qux"]]

It is very easy to split out the key-value pairs inside a loop using destructuring:

const a = ["foo", "bar", "baz", "qux"];
 
for (const [idx, element] of a.entries()) [
  alert(idx);
  alert(element);
}
// 0
// foo
// 1
// bar
// 2
// baz
// 3
// qux

Copy and Fill Methods

Two methods, fill() and copyWithin(), respectively allow for batch fill and copy inside an array. Both methods have a similar function signature in that they allow you to specify a range within an existing array instance using an inclusive start and exclusive end index. Arrays that use this method will never be resized.

The fill() method allows you to insert the same value into all or part of an existing array. Specifying the optional start index instructs the fill to begin at that index, and the fill will continue to the end of the array unless an end index is provided. Negative indices are interpreted from the end of the array; another way to think of this is that negative indices have the array length added to them to calculate a positive index:

const zeroes = [0, 0, 0, 0, 0];
 
// Fill the entire array with 5
zeroes.fill(5);
alert(zeroes);   // [5, 5, 5, 5, 5]
zeroes.fill(0);  // reset
 
// Fill all indices>=3 with 6
zeroes.fill(6, 3);
alert(zeroes);   // [0, 0, 0, 6, 6]
zeroes.fill(0);  // reset
 
// Fill all indices>= 1 and < 3 with 7
zeroes.fill(7, 1, 3);
alert(zeroes);   // [0, 7, 7, 0, 0];
zeroes.fill(0);  // reset
 
// Fill all indices>=1 and < 4 with 8
// (-4 + zeroes.length = 1)
// (-1 + zeroes.length = 4)
zeroes.fill(8, -4, -1);
alert(zeroes);   // [0, 8, 8, 8, 0];

fill() silently ignores ranges that exceed the boundaries of the array, are zero length, or go backwards:

const zeroes = [0, 0, 0, 0, 0];
 
// Fill with too low indices is noop
zeroes.fill(1, -10, -6);
alert(zeroes);   // [0, 0, 0, 0, 0]
 
// Fill with too high indices is noop
zeroes.fill(1, 10, 15);
alert(zeroes);   // [0, 0, 0, 0, 0]
 
// Fill with reversed indices is noop
zeroes.fill(2, 4, 2);
alert(zeroes);   // [0, 0, 0, 0, 0]
 
// Fill with partial index overlap is best effort
zeroes.fill(4, 3, 10)
alert(zeroes);   // [0, 0, 0, 4, 4]

Unlike fill(), copyWithin() instead performs an iterative shallow copy of some of the array and overwrites existing values beginning at the provided index. However, it uses the same conventions with respect to start and end indices:

let ints,
    reset = () => ints = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
reset();
 
// Copy the contents of ints beginning at index 0 // to the values beginning at index 5.
// Stops when it reaches the end of the array either in the source
// indices or the destination indices.
ints.copyWithin(5);
alert(ints);  // [0, 1, 2, 3, 4, 0, 1, 2, 3, 4]
reset();
 
// Copy the contents of ints beginning at index 5 // to the values beginning at index 0.
ints.copyWithin(0, 5);
alert(ints);  // [5, 6, 7, 8, 9, 5, 6, 7, 8, 9]
reset();
 
// Copy the contents of ints beginning at index 0 and ending at index 3
// to values beginning at index 4.
ints.copyWithin(4, 0, 3);
alert(ints);  // [0, 1, 2, 3, 0, 1, 2, 7, 8, 9]
reset();
 
// The JS engine will perform a full copy of the range of values before inserting,
// so there is no danger of overwrite during the copy.
ints.copyWithin(2, 0, 6);
alert(ints);  // [0, 1, 0, 1, 2, 3, 4, 5, 8, 9]
reset();
 
// Support for negative indexing behaves identically to fill() in that negative
// indices are calculated relative to the end of the array
ints.copyWithin(-4, -7, -3);
alert(ints);  // [0, 1, 2, 3, 4, 5, 3, 4, 5, 6]

copyWithin() silently ignores ranges that exceed the boundaries of the array, are zero length, or go backwards:

let ints,
    reset = () => ints = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
reset();
 
// Copy with too low indices is noop
ints.copyWithin(1, -15, -12);
alert(ints);   // [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
reset()
 
// Copy with too high indices is noop
ints.copyWithin(1, 12, 15);
alert(ints);   // [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
reset();
 
// Copy with reversed indices is noop
ints.copyWithin(2, 4, 2);
alert(ints);   // [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
reset();
 
// Copy with partial index overlap is best effort
ints.copyWithin(4, 7, 10)
alert(ints);   // [0, 1, 2, 3, 7, 8, 9, 7, 8, 9];

Spread Operator

The spread operator allows you to expand the elements of an array into individual elements, making it easier to merge, copy, or insert elements from one array into another. Using the spread operator, you can merge two or more arrays into a single array:

let array1 = [1, 2, 3];
let array2 = [4, 5, 6];
 
let mergedArray = [...array1, ...array2];
console.log(mergedArray); // [1, 2, 3, 4, 5, 6]

The spread operator can also be used to create a shallow copy of an array:

let originalArray = [1, 2, 3];
let copiedArray = [...originalArray];
 
console.log(copiedArray); // [1, 2, 3]

The flexible syntax of the spread operator allows for sophisticated array operations. For example, you can mix slicing and spreading to interleave arrays:

let array1 = [1, 2, 4];
let array2 = [3];
 
let combinedArray = [...array1.slice(0, 2), ...array2, ...array1.slice(2)];
console.log(combinedArray); // [1, 2, 3, 4]

Rest Operator

The rest operator is used to collect the remaining elements of an array into a new array. It is typically used in function parameters or destructuring assignments.

The rest operator can be used to collect an unknown number of function arguments into an array:

function sum(...numbers) {
  return numbers.reduce((total, num) => total + num, 0);
}
 
console.log(sum(1, 2, 3, 4, 5)); // 15

The rest operator can also be used in destructuring assignments to collect remaining elements of an array:

let [first, second, ...rest] = [1, 2, 3, 4, 5];
 
console.log(first); // 1
console.log(second); // 2
console.log(rest); // [3, 4, 5]

Conversion Methods

As mentioned previously, all ECMAScript objects have toLocaleString(), toString(), and valueOf() methods. The toString() and valueOf() methods return the same value when called on an array. The result is a comma-separated string that contains the string equivalents of each value in the array, which is to say that each item has its toString() method called to create the final string. Take a look at this example:

let colors = ["red", "blue", "green"];  // creates an array with three strings
alert(colors.toString());  // red,blue,green
alert(colors.valueOf());   // red,blue,green
alert(colors);             // red,blue,green

In this code, the toString() and valueOf() methods are first called explicitly to return the string representation of the array, which combines the strings, separating them by commas. The last line passes the array directly into alert(). Because alert() expects a string, it calls toString() behind the scenes to get the same result as when toString() is called directly.

The toLocaleString() method may end up returning the same value as toString() and valueOf(), but not always. When toLocaleString() is called on an array, it creates a comma-delimited string of the array values. The only difference between this and the two other methods is that toLocaleString() calls each item's toLocaleString() instead of toString() to get its string value. Consider the following example:

let person1 = {
  toLocaleString() {
    return "Matthew";
  },
 
  toString() {
    return "Matt";
  }
};
 
let person2 = {
  toLocaleString() {
    return "Grigorios";
  },
 
  toString() {
    return "Greg";
  }
};
 
let people = [person1, person2];
alert(people);                   // Matt,Greg
alert(people.toString());        // Matt,Greg
alert(people.toLocaleString());  // Nikolaos,Grigorios

Here, two objects are defined, person1 and person2. Each object defines both a toString() method and a toLocaleString() method that return different values. An array, people, is created to contain both objects. When passed into alert(), the output is "Matt,Greg" because the toString() method is called on each item in the array (the same as when toString() is called explicitly on the next line). When toLocaleString() is called on the array, the result is "Matthew,Grigorios" because this calls toLocaleString() on each array item.

The inherited methods toLocaleString(), toString(), and valueOf() each return the array items as a comma-separated string. It's possible to construct a string with a different separator using the join() method. The join() method accepts one argument, which is the string separator to use, and returns a string containing all items. Consider this example:

let colors = ["red", "green", "blue"];
alert(colors.join(","));    // red,green,blue
alert(colors.join("||"));   // red||green||blue

Here, the join() method is used on the colors array to duplicate the output of toString(). By passing in a comma, the result is a comma-separated list of values. On the last line, double pipes are passed in, resulting in the string "red||green||blue". If no value or undefined is passed into the join() method, then a comma is used as the separator.

Stack Methods

One of the interesting things about ECMAScript arrays is that they provide a method to make an array behave like other data structures. An array object can act just like a stack, which is one of a group of data structures that restrict the insertion and removal of items. A stack is referred to as a last-in-first-out (LIFO) structure, meaning that the most recently added item is the first one removed. The insertion (called a push) and removal (called a pop) of items in a stack occur at only one point: the top of the stack. ECMAScript arrays provide push() and pop() specifically to allow stack-like behavior.

The push() method accepts any number of arguments and adds them to the end of the array, returning the array's new length. The pop() method, on the other hand, removes the last item in the array, decrements the array's length, and returns that item. Consider this example:

let colors = new Array();                 // create an array
let count = colors.push("red", "green");  // push two items
alert(count);                             // 2
 
count = colors.push("black");  // push another item on
alert(count);                  // 3
 
let item = colors.pop();  // get the last item
alert(item);              // "black"
alert(colors.length);     // 2

In this code, an array is created for use as a stack [note that there's no special code required to make this work; push() and pop() are default methods on arrays]. First, two strings are pushed onto the end of the array using push(), and the result is stored in the variable count (which gets the value of 2). Then, another value is pushed on, and the result is once again stored in count. Because there are now three items in the array, push() returns 3. When pop() is called, it returns the last item in the array, which is the string "black". The array then has only two items left.

The stack methods may be used in combination with all of the other array methods as well, as in this example:

let colors = ["red", "blue"];
colors.push("brown");          // add another item
colors[3] = "black";           // add an item
alert(colors.length);          // 4
 
let item = colors.pop();       // get the last item
alert(item);                   // "black"

Here, an array is initialized with two values. A third value is added via push(), and a fourth is added by direct assignment into position 3. When pop() is called, it returns the string "black", which was the last value added to the array.

Queue Methods

Just as stacks restrict access in a LIFO data structure, queues restrict access in a first-in-first-out (FIFO) data structure. A queue adds items to the end of a list and retrieves items from the front of the list. Because the push() method adds items to the end of an array, all that is needed to emulate a queue is a method to retrieve the first item in the array. The array method for this is called shift(), which removes the first item in the array and returns it, decrementing the length of the array by one. Using shift() in combination with push() allows arrays to be used as queues:

let colors = new Array();                 // create an array
let count = colors.push("red", "green");  // push two items
alert(count);                             // 2
 
count = colors.push("black");  // push another item on
alert(count);                  // 3
 
let item = colors.shift();  // get the first item
alert(item);                // "red"
alert(colors.length);       // 2

This example creates an array of three colors using the push() method. The highlighted line shows the shift() method being used to retrieve the first item in the array, which is "red". With that item removed, "green" is moved into the first position, and "black" is moved into the second, leaving the array with two items.

ECMAScript also provides an unshift() method for arrays. As the name indicates, unshift() does the opposite of shift(): it adds any number of items to the front of an array and returns the new array length. By using unshift() in combination with pop(), it's possible to emulate a queue in the opposite direction, where new values are added to the front of the array and values are retrieved off the back, as in this example:

let colors = new Array();                    // create an array
let count = colors.unshift("red", "green");  // push two items
alert(count);                                // 2
 
count = colors.unshift("black");  // push another item on
alert(count);                     // 3
 
let item = colors.pop();  // get the first item
alert(item);              // "green"
alert(colors.length);     // 2

In this code, an array is created and then populated by using unshift(). First "red" and “green” are added to the array, and then "black" is added, resulting in an order of "black", "red", "green". When pop() is called, it removes the last item, "green", and returns it.

Reordering and Sorting Methods

Two methods deal directly with the ordering of items already in the array: reverse() and sort(). As one might expect, the reverse() method simply reverses the order of items in an array. Consider the following example:

let values = [1, 2, 3, 4, 5];
values.reverse();
alert(values);  // 5,4,3,2,1

Here, the array's values are initially set to 1, 2, 3, 4, and 5, in that order. Calling reverse() on the array reverses the order to 5, 4, 3, 2, 1. This method is fairly straightforward but doesn't provide much flexibility, which is where the sort() method comes in.

By default, the sort() method puts the items in ascending order—with the smallest value first and the largest value last. To do this, the sort() method calls the String() casting function on every item and then compares the strings to determine the correct order. This occurs even if all items in an array are numbers, as in this example:

let values = [0, 1, 5, 10, 15];
values.sort();
alert(values);  // 0,1,10,15,5

Even though the values in this example begin in correct numeric order, the sort() method changes that order based on their string equivalents. So even though 5 is less than 10, the string "10" comes before "5" when doing a string comparison, so the array is updated accordingly. Clearly, this is not an optimal solution in many cases, so the sort() method allows you to pass in a comparison function that indicates which value should come before which.

A comparison function accepts two arguments and returns a negative number if the first argument should come before the second, a zero if the arguments are equal, or a positive number if the first argument should come after the second. Here's an example of a simple comparison function:

function compare(value1, value2) {
  if (value1 < value2) {
    return -1;
  } else if (value1> value2) {
    return 1;
  } else {
    return 0;
  }
}

This comparison function works for most data types and can be used by passing it as an argument to the sort() method, as in the following example:

let values = [0, 1, 5, 10, 15];
values.sort(compare);
alert(values);  // 0,1,5,10,15

When the comparison function is passed to the sort() method, the numbers remain in the correct order. Of course, the comparison function could produce results in descending order if you simply switch the return values like this:

function compare(value1, value2) {
  if (value1 < value2) {
    return 1;
  } else if (value1> value2) {
    return -1;
  } else {
    return 0;
  }
}
 
let values = [0, 1, 5, 10, 15];
values.sort(compare);
alert(values);  // 15,10,5,1,0

Alternately, the compare function can be shortened and defined as an inline arrow function:

let values = [0, 1, 5, 10, 15];
values.sort((a, b) => a < b ? 1 : a> b ? -1 : 0);
alert(values);  // 15,10,5,1,0

In this modified example, the comparison function returns 1 if the first value should come after the second and –1 if the first value should come before the second. Swapping these means the larger value will come first and the array will be sorted in descending order. Of course, if you just want to reverse the order of the items in the array, reverse() is a much faster alternative than sorting.

A much simpler version of the comparison function can be used with numeric types and objects whose valueOf() method returns numeric values (such as the Date object). In either case, you can simply subtract the second value from the first as shown here:

function compare(value1, value2){
  return value2 - value1;
}

Because comparison functions work by returning a number less than zero, zero, or a number greater than zero, the subtraction operation handles all of the cases appropriately.

Developers usually find that ECMAScript's sort() method is unintuitive, so the following table is a quick reference for common sort patterns:

SORT ORDER	SORT SNIPPET	RESULT
Ascending numbers	`arr.sort((a,b) => a - b)`	`[1,2,3]`
Descending numbers	`arr.sort((a,b) => b - a)`	`[3,2,1]`
Ascending strings	`arr.sort((a, b) => a.localeCompare(b))`	`["a","b","c"]`
Descending strings	`arr.sort((a, b) => b.localeCompare(a))`	`["c","b","a"]`
Ascending number property	`arr.sort((a,b) => a.foo – b.foo)`	`[{foo: 1}, {foo: 2}, {foo: 3}]`
Ascending string property	`arr.sort((a, b) => a.foo.localeCompare(b.foo);` `};`	`[{foo:"a"},{foo:"b"},{foo:"c"}]`
Ascending string property, with empty values appearing last	`arr.sort((a, b) => {` `if (a.foo === "") return 1;` `if (b.foo === "") return -1;` `return a.foo.localeCompare(b.foo);` `});`	`[{foo:"a"},{foo:"b"},{foo:""}]`

Manipulation Methods

There are various ways to work with the items already contained in an array. The concat() method, for instance, allows you to create a new array based on all of the items in the current array. This method begins by creating a copy of the array and then appending the method arguments to the end and returning the newly constructed array. When no arguments are passed in, concat() simply clones the array and returns it. If one or more arrays are passed in, concat() appends each item in these arrays to the end of the result. If the values are not arrays, they are simply appended to the end of the resulting array. Consider this example:

let colors = ["red", "green", "blue"];
let colors2 = colors.concat("yellow", ["black", "brown"]);
 
alert(colors);   // ["red", "green","blue"]
alert(colors2);  // ["red", "green", "blue", "yellow", "black", "brown"]

This code begins with the colors array containing three values. The concat() method is called on colors, passing in the string "yellow" and an array containing "black" and "brown". The result, stored in colors2, contains "red", "green", "blue", "yellow", "black", and "brown". The original array, colors, remains unchanged.

You can override this force-flattening default behavior by specifying a special symbol on the argument array instance, Symbol.isConcatSpreadable. This will prevent the concat() method from flattening the result. Conversely, setting the value to true will force array-like objects to be flattened:

let colors = ["red", "green", "blue"];
let newColors = ["black", "brown"];
let moreNewColors = {
  [Symbol.isConcatSpreadable]: true,
  length: 2,
  0: "pink",
  1: "cyan"
};
 
newColors[Symbol.isConcatSpreadable] = false;
 
// Force the array to not be flattened
let colors2 = colors.concat("yellow", newColors);
 
// Force the array-like object to be flattened
let colors3 = colors.concat(moreNewColors);
 
alert(colors);   // ["red", "green","blue"]
alert(colors2);  // ["red", "green", "blue", "yellow", ["black", "brown"]]
alert(colors3);  // ["red", "green", "blue", "pink, "cyan"]

The next method, slice(), creates an array that contains one or more items already contained in an array. The slice() method may accept one or two arguments: the starting and stopping positions of the items to return. If only one argument is present, the method returns all items between that position and the end of the array. If there are two arguments, the method returns all items between the start position and the end position, not including the item in the end position. Keep in mind that this operation does not affect the original array in any way. Consider the following:

let colors = ["red", "green", "blue", "yellow", "purple"];
let colors2 = colors.slice(1);
let colors3 = colors.slice(1, 4);
 
alert(colors2);  // green,blue,yellow,purple
alert(colors3);  // green,blue,yellow

In this example, the colors array starts out with five items. Calling slice() and passing in 1 yields an array with four items, omitting "red" because the operation began copying from position 1, which contains "green". The resulting colors2 array contains "green", "blue", "yellow", and "purple". The colors3 array is constructed by calling slice() and passing in 1 and 4, meaning that the method will begin copying from the item in position 1 and stop copying at the item in position 3. As a result, colors3 contains "green", "blue", and "yellow".

Perhaps the most powerful array method is splice(), which can be used in a variety of ways. The main purpose of splice() is to insert items into the middle of an array, but there are three distinct ways of using this method. They are as follows:

Deletion—Any number of items can be deleted from the array by specifying just two arguments: the position of the first item to delete and the number of items to delete. For example, splice(0, 2) deletes the first two items.
Insertion—Items can be inserted into a specific position by providing three or more arguments: the starting position, 0 (the number of items to delete), and the item to insert. Optionally, you can specify a fourth parameter, fifth parameter, or any number of other parameters to insert. For example, splice(2, 0, "red", "green") inserts the strings "red" and "green" into the array at position 2.
Replacement—Items can be inserted into a specific position while simultaneously deleting items, if you specify three arguments: the starting position, the number of items to delete, and any number of items to insert. The number of items to insert doesn't have to match the number of items to delete. For example, splice(2, 1, "red", "green") deletes one item at position 2 and then inserts the strings "red" and "green" into the array at position 2.

The splice() method always returns an array that contains any items that were removed from the array (or an empty array if no items were removed). These three uses are illustrated in the following code:

let colors = ["red", "green", "blue"];
let removed = colors.splice(0,1);  // remove the first item
alert(colors);                     // green,blue
alert(removed);                    // red - one item array
 
// insert two items at position 1 removed = colors.splice(1, 0, "yellow", "orange");  
alert(colors);  // green,yellow,orange,blue
alert(removed); // empty array
 
// insert two values, remove one removed = colors.splice(1, 1, "red", "purple");
alert(colors);  // green,red,purple,orange,blue
alert(removed); // yellow - one item array

This example begins with the colors array containing three items. When splice() is called the first time, it simply removes the first item, leaving colors with the items "green" and "blue". The second time splice() is called, it inserts two items at position 1, resulting in colors containing "green", "yellow", "orange", and "blue". No items are removed at this point, so an empty array is returned. The last time splice() is called, it removes one item, beginning in position 1, and inserts "red" and "purple". After all of this code has been executed, the colors array contains "green", "red", "purple", "orange", and "blue".

Search and Location Methods

ECMAScript offers two strategies for searching inside an array instance: searching by strict equivalence, and searching with a predicate function.

ECMAScript's strict equivalence lookup methods are indexOf(), lastIndexOf(), and includes(). Each of these methods accepts two arguments: the item to look for and an optional index from which to start looking. The indexOf() and includes() methods start searching from the front of the array (item 0) and continue to the back, whereas lastIndexOf() starts from the last item in the array and continues to the front.

indexOf() and lastIndexOf() each return the position of the item in the array or –1 if the item isn't in the array. includes() returns a Boolean indicating if at least one element in the searched array matched the provided element. An identity comparison is used when comparing the first argument to each item in the array, meaning that the items must be strictly equal as if compared using ===. Here are some examples of this usage:

let numbers = [1, 2, 3, 4, 5, 4, 3, 2, 1];
 
alert(numbers.indexOf(4));      // 3
alert(numbers.lastIndexOf(4));  // 5
alert(numbers.includes(4));     // true
 
alert(numbers.indexOf(4, 4));      // 5
alert(numbers.lastIndexOf(4, 4));  // 3
alert(numbers.includes(4, 7));     // false
 
let person = { name: "Matt" };
let people = [{ name: "Matt" }];
let morePeople = [person];
 
alert(people.indexOf(person));      // -1
alert(morePeople.indexOf(person));  // 0
alert(people.includes(person));     // false
alert(morePeople.includes(person)); // true

ECMAScript also allows you to define a predicate function that will be invoked at each index. The return value of the function determines if the element at that index is considered a match.

A predicate function takes the form predicate(element, index, array), where element is the current element in the array being examined, index is the index of element inside the array, and array is the array instance. A truthy return value indicates a match.

The two methods that make use of this are find() and findIndex(). Both begin searching at the lowest index in the array; find() returns the first matching element, and findIndex() returns the index of the first matching element. Both methods also accept a second optional argument that allows you to specify the value of this inside the predicate.

const people = [
  {
    name: "Matt",
    age: 27
  },
  {
    name: "Matt",
    age: 29
  }
];
 
alert(people.find((element, index, array) => element.age < 28));
// {name: "Matt", age: 27}
 
alert(people.findIndex((element, index, array) => element.age < 28));
// 0

Neither method will continue searching once a match has been found.

const evens = [2, 4, 6];
 
// Last element of array will never be inspected after match is found
evens.find((element, index, array) => {
  alert(element);
  alert(index);
  alert(array);
  return element === 4;
});
// 2
// 0
// [2, 4, 6]
// 4
// 1
// [2, 4, 6]

Iterative Methods

ECMAScript defines five iterative methods for arrays. Each of the methods accepts two arguments: a function to run on each item and an optional scope object in which to run the function (affecting the value of this). The function passed into one of these methods will receive three arguments: the array item value, the position of the item in the array, and the array object itself. Depending on the method, the results of this function's execution may or may not affect the method's return value. The iterative methods are as follows:

every()—Runs the given function on every item in the array and returns true if the function returns true for every item.
filter()—Runs the given function on every item in the array and returns an array of all items for which the function returns true.
forEach()—Runs the given function on every item in the array. This method has no return value.
map()—Runs the given function on every item in the array and returns the result of each function call in an array.
some()—Runs the given function on every item in the array and returns true if the function returns true for any one item.

These methods do not change the values contained in the array.

Of these methods, the two most similar are every() and some(), which both query the array for items matching some criteria. For every(), the passed-in function must return true for every item in order for the method to return true; otherwise, it returns false. The some() method, on the other hand, returns true if at least one of the items causes the passed-in function to return true. Here is an example:

let numbers = [1, 2, 3, 4, 5, 4, 3, 2, 1];
 
let everyResult = numbers.every((item, index, array) => item> 2);
alert(everyResult);  // false
 
let someResult = numbers.some((item, index, array) => item> 2);
alert(someResult);   // true

The next method is filter(), which uses the given function to determine if an item should be included in the array that it returns. This method is very helpful when querying an array for all items matching some criteria. For example, to return an array of all numbers greater than 2, the following code can be used:

let numbers = [1, 2, 3, 4, 5, 4, 3, 2, 1];
 
let filterResult = numbers.filter((item, index, array) => item> 2);
alert(filterResult);   // [3,4,5,4,3]

The map() method also returns an array. Each item in the array is the result of running the passed-in function on the original array item in the same location. This method is helpful when creating arrays whose items correspond to one another or when performing work using each element of an array. For example, you can multiply every number in an array by two and are returned an array of those numbers, as shown here:

let numbers = [1, 2, 3, 4, 5, 4, 3, 2, 1];
 
let mapResult = numbers.map((item, index, array) => item * 2);
 
alert(mapResult);   // [2,4,6,8,10,8,6,4,2]

The last method is forEach(), which simply runs the given function on every item in an array. There is no return value and it is essentially the same as iterating over an array using a for loop. Here's an example:

let numbers = [1, 2, 3, 4, 5, 4, 3, 2, 1];
 
numbers.forEach((item, index, array) => {
  // do something here
});

All of these array methods ease the processing of arrays by performing a number of different operations.

Reduction Methods

ECMAScript offers two reduction methods for arrays: reduce() and reduceRight(). Both methods iterate over all items in the array and build up a value that is ultimately returned. The reduce() method does this starting at the first item and traveling toward the last, whereas reduceRight() starts at the last and travels toward the first.

Both methods accept two arguments: a function to call on each item and an optional initial value upon which the reduction is based. The function passed into reduce() or reduceRight() accepts four arguments: the previous value, the current value, the item's index, and the array object. Any value returned from the function is automatically passed in as the first argument for the next item. The first iteration occurs on the second item in the array, so the first argument is the first item in the array and the second argument is the second item in the array.

You can use the reduce() method to perform operations such as adding all numbers in an array. Here's an example:

let values = [1, 2, 3, 4, 5];
let sum = values.reduce((prev, cur, index, array) => prev + cur, 0);
 
alert(sum);  // 15

The first time the callback function is executed, prev is 1 and cur is 2. The second time, prev is 3 (the result of adding 1 and 2), and cur is 3 (the third item in the array). This sequence continues until all items have been visited and the result is returned. 0 is passed as the second argument to define the initial value; otherwise, reduce() will error when called on an empty array. Note that, when the array is empty with 0 passed as the second argument, or when the array has only one element without 0 passed as the second argument, the callback in the first argument is not called.

The reduceRight() method works in the same way, just in the opposite direction. Consider the following example:

let values = [1, 2, 3, 4, 5];
let sum = values.reduceRight(function(prev, cur, index, array){
  return prev + cur;
});
alert(sum); // 15

In this version of the code, prev is 5 and cur is 4 the first time the callback function is executed. The result is the same, of course, because the operation is simple addition.

The decision to use reduce() or reduceRight() depends solely on the direction in which the items in the array should be visited. They are exactly equal in every other way.

Flattening Methods

The Array prototype has flat() and flatMap() methods to make array flattening operations much easier. Without these methods, flattening arrays is a nasty business that involves either an iterative or recursive solution.

The following is an example of how a simple recursive implementation might look without using these new methods:

function flatten(sourceArray, flattenedArray = []) {
  for (const element of sourceArray) {
    if (Array.isArray(element)) {
      flatten(element, flattenedArray);
    } else {
      flattenedArray.push(element);
    }
  }
 
  return flattenedArray;
}
 
const arr = [[0], 1, 2, [3, [4, 5]], 6];
 
console.log(flatten(arr))
// [0, 1, 2, 3, 4, 5, 6]

In many ways, this example resembles a tree data structure; each element in an array behaves like a child node, and non-array elements are leaves. Therefore, in this example the input array is a tree of height 2 with 7 leaves. Flattening this array is in essence an in-order traversal of the leaves.

It is sometimes useful to be able to specify how many levels of array nesting should be flattened. Consider the following example, which modifies the initial implementation and allows for the flattening depth to be specified:

function flatten(sourceArray, depth, flattenedArray = []) {
  for (const element of sourceArray) {
    if (Array.isArray(element) && depth > 0) {
      flatten(element, depth - 1, flattenedArray);
    } else {
      flattenedArray.push(element);
    }
  }
 
  return flattenedArray;
}
 
 
const arr = [[0], 1, 2, [3, [4, 5]], 6];
 
console.log(flatten(arr, 1));
// [0, 1, 2, 3, [4, 5], 6]

The Array.prototype.flat() method accepts a depth argument (defaulting to a depth of 1) and returns a shallow copy of the Array instance flattened to the specified depth. This is demonstrated here:

const arr = [[0], 1, 2, [3, [4, 5]], 6];
 
console.log(arr.flat(2));
// [0, 1, 2, 3, 4, 5, 6]
 
console.log(arr.flat());
// [0, 1, 2, 3, [4, 5], 6]

Because a shallow copy is performed, arrays with cycles will copy values from the source array when flattening:

const arr = [[0], 1, 2, [3, [4, 5]], 6];
 
arr.push(arr);
 
console.log(arr.flat());
// [0, 1, 2, 3, 4, 5, 6, [0], 1, 2, [3, [4, 5]], 6]

The Array.prototype.flatMap() method allows you to perform a map operation before flattening the array. arr.flatMap(fn) is functionally equivalent to arr.map(fn).flat(), but arr.flatMap() is more efficient since the browser only must perform a single traversal.

The function signature of flatMap() is identical to map(). A simple example is as follows:

const arr = [[1], [3], [5]];
 
console.log(arr.map(([x]) => [x, x + 1]));
// [[1, 2], [3, 4], [5, 6]]
 
console.log(arr.flatMap(([x]) => [x, x + 1]));
// [1, 2, 3, 4, 5, 6]

flatMap() is especially useful in situations where a non-array object's method returns an array, such as split(). Consider the following example, where a collection of input strings is split into words and joined into a single word array:

const arr = ['Lorem ipsum dolor sit amet,', 'consectetur adipiscing elit.'];
 
console.log(arr.flatMap((x) => x.split(/[\W+]/)));
// ["Lorem", "ipsum", "dolor", "sit", "amet", "", "consectetur", "adipiscing", // "elit", ""]

A handy trick (albeit one that may incur a performance hit) is to use an empty array to filter out results after a map. The following example extends the preceding example to strip out the empty strings:

const arr = ['Lorem ipsum dolor sit amet,', 'consectetur adipiscing elit.'];
 
console.log(arr.flatMap((x) => x.split(/[\W+]/)).flatMap((x) => x || []));
// ["Lorem", "ipsum", "dolor", "sit", "amet", consectetur", "adipiscing", "elit"]

Here, each empty string in the results is first mapped to an empty array. When flattening, these empty arrays are effectively skipped in the array that is eventually returned.

TYPED ARRAYS

The typed array is a construct designed for efficiently passing binary data to native libraries. There is no actual “TypedArray” type in JavaScript—rather, the term refers to a collection of specialized arrays that contain numeric types. To understand how to use the typed array, it is helpful to first understand its intended purpose.

History

As web browsers gained adoption, it was not difficult to foresee that the ability to run complex 3D applications inside of them would be in demand. As early as 2006, browser vendors including Mozilla and Opera began to experiment with a programming platform for rendering graphics-intensive applications inside the browser without requiring any plugins. The goal was to develop a JavaScript API that could make use of a 3D graphics API and GPU acceleration to enable rendering of complex graphics on a <canvas> element.

WebGL

The eventual JavaScript API was based on the OpenGL for Embedded Systems (OpenGL ES) 2.0 specification, a subset of OpenGL that specializes in 2D and 3D computer graphics. The new API, named the Web Graphics Library (WebGL), saw its 1.0 release in March 2011. With it, developers were able to write graphics-intensive application code that could natively be interpreted by any WebGL-compliant web browser.

In initial versions of WebGL, a fundamental mismatch between JavaScript arrays and native arrays caused performance issues. The graphics driver APIs often did not want numbers passed to them in JavaScript's default double floating point format. Furthermore, the graphics driver APIs expected arrays of numbers to be passed to them in a binary format, which of course is nothing like the JavaScript array's format in memory. Therefore, each time an array was passed between WebGL and the JavaScript runtime, the WebGL binding would perform the expensive operation of allocating a new array in the destination environment, iterating over the array in its current format, and casting the number into an appropriate format in the new array.

Emergence of Typed Arrays

This, of course, was untenable, and Mozilla solved this problem by implementing CanvasFloatArray, a C-style array of floating point numbers that offered a JavaScript interface. Using this type allowed the JavaScript runtime to allocate, read, and write an array that could be passed directly to and from the graphics driver API. The CanvasFloatArray would eventually be reshaped into the Float32Array, which was the first “type” available for typed arrays as they currently exist.

Using ArrayBuffers

Float32Array is actually one type of “view” that allows the JavaScript runtime to access a block of allocated memory called an ArrayBuffer. The ArrayBuffer is the fundamental unit referred to by all typed arrays and views.

ArrayBuffer is a normal JavaScript constructor that can be used to allocate a specific number of bytes in memory.

const buf = new ArrayBuffer(16);  // Allocates 16 bytes of memory
alert(buf.byteLength);            // 16

An ArrayBuffer can never be resized once it is created. However, you are able to copy all or part of an existing ArrayBuffer into a new instance using slice():

const buf1 = new ArrayBuffer(16);
const buf2 = buf1.slice(4, 12);
alert(buf2.byteLength);  // 8

ArrayBuffer is in some ways similar to the C++ malloc(), with several notable exceptions:

When malloc() fails to allocate, it returns a null pointer. If ArrayBuffer allocation fails, it throws an error.
A malloc() call can take advantage of virtual memory, so the maximum size of the allocation is only bounded by the addressable system memory. ArrayBuffer allocation cannot exceed Number.MAX_SAFE_INTEGER (2 ^ 53) bytes.
A successful malloc() invocation performs no initialization of the actual addresses. Declaring an ArrayBuffer initializes all the bits to 0s.
Heap memory allocated by malloc() cannot be used by the system until free() is invoked or the program exits. Heap memory allocated by declaring an ArrayBuffer is still garbage collected—no manual memory management is required.

The contents of an ArrayBuffer cannot be read or written with only a reference to the buffer instance. To read or write data inside, you must do so with a view. There are different types of views, but they all refer to binary data stored in an ArrayBuffer.

DataViews

The first type of view that allows you to read and write an ArrayBuffer is the DataView. This view is designed for file I/O and network I/O; the API allows for a high degree of control when manipulating buffer data, but it offers reduced performance compared to different view types as a result. A DataView does not assume anything about the buffer contents and is not iterable.

A DataView must be created to read from and write to an ArrayBuffer that already exists. It can use the whole buffer or only part of it, and it maintains a reference to the buffer instance and where in the buffer the view begins.

const buf = new ArrayBuffer(16);
 
// DataView default to use the entire ArrayBuffer
const fullDataView = new DataView(buf);
alert(fullDataView.byteOffset);      // 0
alert(fullDataView.byteLength);      // 16
alert(fullDataView.buffer === buf);  // true
 
// Constructor takes an optional byte offset and byte length
//   byteOffset=0 begins the view at the start of the buffer
//   byteLength=8 restricts the view to the first 8 bytes
const firstHalfDataView = new DataView(buf, 0, 8);
alert(firstHalfDataView.byteOffset);      // 0
alert(firstHalfDataView.byteLength);      // 8
alert(firstHalfDataView.buffer === buf);  // true
 
// DataView will use the remainder of the buffer unless specified
//   byteOffset=8 begins the view at the 9th byte of the buffer
//   byteLength default is the remainder of the buffer
const secondHalfDataView = new DataView(buf, 8);
alert(secondHalfDataView.byteOffset);      // 8
alert(secondHalfDataView.byteLength);      // 8
alert(secondHalfDataView.buffer === buf);  // true

To read from and write to the buffer through a DataView, you will require the use of several components:

The byte offset at which you wish to read or write. This can be thought of as a sort of “address” within the DataView.
Which ElementType the DataView should use for conversion between the Number type in the JavaScript runtime and the binary format in the buffer.
The endianness of the value in memory. Defaults to big-endian.

ElementType

The DataView makes no assumptions about what data type is stored inside the buffer. The API it exposes forces you to specify an ElementType when reading or writing, and the DataView will dutifully perform the conversion to execute that read or write.

ECMAScript supports 10 different ElementType values:

ELEMENTTYPE	BYTES	DESCRIPTION	C EQUIVALENTS	RANGE OF VALUES
`Int8`	1	8-bit signed integer	`signed char` `int8_t`	–2⁷ to 2⁷-1
`Uint8`	1	8-bit unsigned integer	`unsigned char` `uint8_t`	0 to 2⁸-1
`Int16`	2	16-bit signed integer	`short` `int16_t`	–2¹⁵ to 2¹⁵-1
`Uint16`	2	16-bit unsigned integer	`unsigned short` `uint16_t`	0 to 2¹⁶-1
`Int32`	4	32-bit signed integer	`int` `int32_t`	–2³¹ to 2³¹-1
`Uint32`	4	32-bit unsigned integer	`unsigned int` `uint32_t`	0 to 2³²-1
`Float32`	4	32-bit IEEE-754 floating point	`float`	–3.4E+38 to +3.4E+38
`Float64`	8	64-bit IEEE-754 floating point	`double`	–1.7E+308 to +1.7E+308
`BigInt64`	8	64-bit signed integer	`signed long long` `int64_t`	-2⁶³ to 2⁶³-1
`BigUint64`	8	64-bit unsigned integer	`unsigned long long` `uint64_t`	0 to 2⁶⁴-1

The DataView exposes get and set methods for each of these types, which use a byteOffset to address into the buffer for reading and writing values. Types can be used interchangeably, as demonstrated here:

// Allocate two bytes of memory and declare a DataView
const buf = new ArrayBuffer(2);
const view = new DataView(buf);
 
// Demonstrate that the entire buffer is indeed all zeroes
// Check the first and second byte
alert(view.getInt8(0));   // 0
alert(view.getInt8(1));   // 0
// Check the entire buffer
alert(view.getInt16(0));  // 0
 
// Set the entire buffer to ones
// 255 in binary is 11111111 (2^8 – 1)
view.setUint8(0, 255);
// DataView will automatically cast values to the designated ElementType
// 255 in hex is 0xFF
view.setUint8(1, 0xFF);
 
// The buffer is now all ones, which when read as a
// two's complement signed integer should be -1
alert(view.getInt16(0));  // -1

Big-Endian and Little-Endian

The buffer's bytes in the previous example were intentionally symmetrical to avoid the issue of endianness. “Endianness” refers to the convention of byte ordering maintained by a computing system. For the purposes of DataViews, there are only two conventions supported: big-endian and little-endian. Big-endian, also referred to as “network byte order,” means that the most significant byte is held in the first byte, and the least significant byte is held in the last byte. Little-endian means the least significant byte is held in the first byte, and the most significant byte is held in the last byte.

The native endianness of the system executing the JavaScript runtime will determine how it reads and writes bytes, but a DataView does not obey this convention. A DataView is an unbiased interface to a segment of memory and will follow whatever endianness you specify. All DataView API methods default to the big-endian convention but accept an optional final Boolean argument that allows you to enable the little-endian convention by setting it to true.

// Allocate two bytes of memory and declare a DataView
const buf = new ArrayBuffer(2);
const view = new DataView(buf);
 
// Fill the buffer so that the first bit and last bit are 1
view.setUint8(0, 0x80);  // Sets leftmost bit to 1
view.setUint8(1, 0x01);  // Sets rightmost bit to 1
 
// Buffer contents (spaced for readability):
// 0x8  0x0  0x0  0x1
// 1000 0000 0000 0001
 
// Read a big-endian Uint16
// 0x80 is the high byte, 0x01 is the low byte
// 0x8001 = 2^15 + 2^0 = 32768 + 1 = 32769
alert(view.getUint16(0));  // 32769
 
// Read a little-endian Uint16
// 0x01 is the high byte, 0x80 is the low byte
// 0x0180 = 2^8 + 2^7 = 256 + 128 = 384
alert(view.getUint16(0, true));  // 384
 
// Write a big-endian Uint16
view.setUint16(0, 0x0004);
 
// Buffer contents (spaced for readability):
// 0x0  0x0  0x0  0x4
// 0000 0000 0000 0100
 
alert(view.getUint8(0));  // 0
alert(view.getUint8(1));  // 4
 
// Write a little-endian Uint16
view.setUint16(0, 0x0002, true);
 
// Buffer contents (spaced for readability):
// 0x0  0x2  0x0  0x0
// 0000 0010 0000 0000
 
alert(view.getUint8(0));  // 2
alert(view.getUint8(1));  // 0

Corner Cases

A DataView will only complete a read or write if there is sufficient buffer space to do so; otherwise it throws a RangeError:

const buf = new ArrayBuffer(6);
const view = new DataView(buf);
 
// Attempt to get a value that partially extends past end of buffer
view.getInt32(4);
// RangeError
 
// Attempt to get a value past the end of the buffer
view.getInt32(8);
// RangeError
 
// Attempt to get a value past the end of the buffer
view.getInt32(-1);
// RangeError
 
// Attempt to set a value that extends past end of buffer
view.setInt32(4, 123);
// RangeError

A DataView will make a best effort to cast a value into the appropriate type when writing to a buffer, falling back to 0. If it cannot, it will throw an error:

const buf = new ArrayBuffer(1);
const view = new DataView(buf);
 
view.setInt8(0, 1.5);
alert(view.getInt8(0));  // 1
 
view.setInt8(0, [4]);
alert(view.getInt8(0));  // 4
 
view.setInt8(0, 'f');
alert(view.getInt8(0));  // 0
 
view.setInt8(0, Symbol());
// TypeError

Typed Arrays

Typed arrays are another form of an ArrayBuffer view. Though it is similar in concept to a DataView, a typed array is distinguished in that it enforces a single ElementType and obeys the system's native endianness. In exchange, it offers a much broader API and better performance. Typed arrays are designed for efficiently exchanging binary data with native libraries like WebGL. Because the binary representation of typed arrays is in an easily digestible format for the native operating system, JavaScript engines are able to heavily optimize arithmetic, bitwise, and other common operations on typed arrays, and as a result they are extremely fast to use.

Typed arrays can be created to read from an existing buffer, initialized with their own buffer, filled with an iterable, or filled from an existing typed array of any type. They can also be created using <ElementType>.from() and <ElementType>.of():

// Creates a buffer of 12 bytes
const buf = new ArrayBuffer(12);
// Creates an Int32Array that references this buffer
const ints = new Int32Array(buf);
// The typed array recognizes it needs 4 bytes per element,
// and therefore will have a length of 3
alert(ints.length);  // 3
 
// Creates an Int32Array of length 6
const ints2 = new Int32Array(6);
// Each number uses 4 bytes, so the ArrayBuffer is 24 bytes
alert(ints2.length);             // 6
// Like DataView, typed arrays have a reference to their associated buffer
alert(ints2.buffer.byteLength);  // 24
 
// Creates an Int32Array containing [2, 4, 6, 8]
const ints3 = new Int32Array([2, 4, 6, 8]);
alert(ints3.length);             // 4
alert(ints3.buffer.byteLength);  // 16
alert(ints3[2]);                 // 6
 
// Creates an Int16Array with values copies from ints3
const ints4 = new Int16Array(ints3);
// The new typed array allocates its own buffer, and each value
// is converted to its new representation at the same index
alert(ints4.length);             // 4
alert(ints4.buffer.byteLength);  // 8
alert(ints4[2]);                 // 6
 
// Creates an Int16Array from a normal array
const ints5 = Int16Array.from([3, 5, 7, 9]);
alert(ints5.length);             // 4
alert(ints5.buffer.byteLength);  // 8
alert(ints5[2]);                 // 7
 
// Creates a Float32Array from arguments
const floats = Float32Array.of(3.14, 2.718, 1.618);
alert(floats.length);             // 3
alert(floats.buffer.byteLength);  // 12
alert(floats[2]);                 // 1.6180000305175781

Both the constructor and instances expose a BYTES_PER_ELEMENT property that returns the size of each element in that type of array:

alert(Int16Array.BYTES_PER_ELEMENT);  // 2
alert(Int32Array.BYTES_PER_ELEMENT);  // 4
 
const ints = new Int32Array(1),
      floats = new Float64Array(1);
 
alert(ints.BYTES_PER_ELEMENT);        // 4
alert(floats.BYTES_PER_ELEMENT);      // 8

Unless a typed array is initialized with values, its associated buffer is filled with zeroes:

const ints = new Int32Array(4);
alert(ints[0]);  // 0
alert(ints[1]);  // 0
alert(ints[2]);  // 0
alert(ints[3]);  // 0

Typed Array Behavior

In most ways, typed arrays behave like their regular array counterparts would. Typed arrays support nearly all of the Array operators, methods, and properties. Methods that return a new array will return a new typed array with the same element type:

const ints = new Int16Array([1, 2, 3]);
const doubleints = ints.map(x => 2*x);
alert(doubleints instanceof Int16Array);  // true

Typed arrays have a Symbol.iterator defined, meaning that for-of loops and spread operators can also be used:

const ints = new Int16Array([1, 2, 3]);
for (const int of ints) {
  alert(int);
}
// 1
// 2
// 3
 
alert(Math.max(...ints));  // 3

Merging, Copying, and Changing Typed Arrays

Typed arrays still use array buffers as their storage, and array buffers cannot be resized. Therefore, the following methods are not supported by typed arrays:

concat()
pop()
push()
shift()
splice()
unshift()

However, typed arrays do offer two new methods that allow you to copy values in and out of arrays quickly: set() and subarray().

set() copies the values from a provided array or typed array into the current typed array at the specified index:

// Create an int16 array of length 8
const container = new Int16Array(8);
 
// Copy in typed array into first four values
// Offset default to an index of 0
container.set(Int8Array.of(1, 2, 3, 4));
alert(container);  // [1,2,3,4,0,0,0,0]
// Copy in normal array into last four values
// Offset of 4 means begin inserting at the index 4
container.set([5,6,7,8], 4);
alert(container);  // [1,2,3,4,5,6,7,8]
 
// An overflow will throw an error
container.set([5,6,7,8], 7);
// RangeError

subarray() performs the opposite operation of set(), returning a new typed array with values copied out of the original. Providing the start and end indices is optional:

const source = Int16Array.of(2, 4, 6, 8);
 
// Copies the entire array into a new array of the same type
const fullCopy = source.subarray();
alert(fullCopy);  // [2, 4, 6, 8]
 
// Copy the array from index 2 on
const halfCopy = source.subarray(2);
alert(halfCopy);  // [6, 8]
 
// Copy the array from index 1 up until 3
const partialCopy = source.subarray(1, 3);
alert(partialCopy);  // [4, 6]

Typed arrays don't have a native ability to concatenate, but ample tools are available in the typed array API that one can be constructed manually:

// First argument is the type of array that should be returned
// Remaining arguments are all the typed arrays that should be concatenated
function typedArrayConcat(typedArrayConstructor, ...typedArrays) {
  // Count the total elements in all arrays
  const numElements = typedArrays.reduce((x,y) => (x.length || x) + y.length);
 
  // Create an array of the provided type with space for all elements
  const resultArray = new typedArrayConstructor(numElements);
 
  // Perform the successive array transfer
  let currentOffset = 0;
  typedArrays.map(x => {
    resultArray.set(x, currentOffset);
    currentOffset += x.length;
  });
 
  return resultArray;
}
 
const concatArray =  typedArrayConcat(Int32Array,
                                      Int8Array.of(1, 2, 3),
                                      Int16Array.of(4, 5, 6),
                                      Float32Array.of(7, 8, 9));
alert(concatArray);  // [1, 2, 3, 4, 5, 6, 7, 8, 9]
alert(concatArray instanceof Int32Array);  // true

Underflow and Overflow

Overflow and underflow of values in typed arrays will not spill over into other indices, but you still must take into account what element type the array considers its entries. Typed arrays will accept only the relevant bits that each index in the array can hold, irrespective of the effect it will have on the actual numerical value. The following demonstrates how underflow and overflow are handled:

// Signed ints array of length 2
// Each index holds a 2's complement signed integer which can
// range from -128 (-1 * 2^7) to 127 (2^7 – 1)
const ints = new Int8Array(2);
 
// Unsigned ints array of length 2
// Each index holds an unsigned integer which can range from
// 0 to 255 (2^7 – 1)
const unsignedInts = new Uint8Array(2);
 
// Overflow bits will not spill into adjacent indices.
// The index only takes the least significant 8 bits
unsignedInts[1] = 256;    // 0x100
alert(unsignedInts);      // [0, 0]
unsignedInts[1] = 511;    // 0x1FF
alert(unsignedInts);      // [0, 255]
 
// Underflow bits will be converted to their unsigned equivalent.
// 0xFF is -1 as a 2's complement int (truncated to 8 bits),
// but is 255 as an unsigned int
unsignedInts[1] = -1  // 0xFF (truncated to 8 bits)
alert(unsignedInts);  // [0, 255]
 
// Overflow in 2's complement occurs transparently.
// 0x80 is 128 in unsigned int but -128 in 2's complement int
ints[1] = 128;   // 0x80
alert(ints);     // [0, -128]
 
// Underflow in 2's complement occurs transparently.
// 0xFF is 255 in unsigned int but -1 in 2's complement int
ints[1] = 255;  // 0xFF
alert(ints);    // [0, -1]

In addition to the element types, there is also an additional “clamped” array type, Uint8ClampedArray, which prevents overflow in either direction. Values above its maximum value of 255 will be rounded down to 255, and values below 0 will be rounded up to 0.

const clampedInts = new Uint8ClampedArray([-1, 0, 255, 256]);
alert(clampedInts);  // [0, 0, 255, 255]

According to Brendan Eich, “Uint8ClampedArray is totally a historical artifact of the HTML5 canvas element. Avoid unless you really are doing canvas-y things.”

THE MAP TYPE

The ECMAScript Map is a collection reference type that introduces true key-value behavior into the language. Much of what it offers is an overlap with what is provided by the Object type, but there are subtle differences between the Object and Map types that should be taken into account when selecting one for use.

Basic API

An empty Map is instantiated with the new keyword:

const m = new Map();

If you wish to populate the Map when it is initialized, the constructor optionally accepts an iterable object, expecting it to contain key-value pair arrays. Each pair in the iterable argument will be inserted into the newly created Map in the order in which they are iterated:

// Initialize map with nested arrays
const m1 = new Map([
  ["key1", "val1"],
  ["key2", "val2"],
  ["key3", "val3"]
]);
alert(m1.size);  // 3
 
// Initialize map with custom-defined iterator
const m2 = new Map({
  [Symbol.iterator]: function*() {
    yield ["key1", "val1"];
    yield ["key2", "val2"];
    yield ["key3", "val3"];
  }
});
alert(m2.size);  // 3
 
// Map expects values to be key-value whether they are provided or not
const m3 = new Map([[]]);
alert(m3.has(undefined));  // true
alert(m3.get(undefined));  // undefined

Key-value pairs can be added after initialization with set(), queried with get() and has(), counted with the size property, and removed with delete() and clear():

const m = new Map();
 
alert(m.has("firstName"));   // false
alert(m.get("firstName "));  // undefined
alert(m.size);               // 0
 
m.set("firstName", "Matt")
 .set("lastName", "Frisbie");
 
alert(m.has("firstName"));  // true
alert(m.get("firstName"));  // Matt
alert(m.size);              // 2
 
m.delete("firstName");  // deletes only this key-value pair
 
alert(m.has("firstName"));  // false
alert(m.has("lastName"));   // true
alert(m.size);              // 1
 
m.clear();  // destroys all key-value pairs in this Map instance
 
alert(m.has("firstName"));  // false
alert(m.has("lastName"));   // false
alert(m.size);              // 0

The set() method returns the Map instance, so it is possible to chain multiple set operations together, including on the initial declaration:

const m = new Map().set("key1", "val1");
 
m.set("key2", "val2")
 .set("key3", "val3");
 
alert(m.size);  // 3

Unlike an Object, which can only use numbers, strings, or symbols as keys, a Map can use any JavaScript data type as a key. It uses the SameValueZero comparison operation (defined inside the ECMAScript specification and not available in the actual language) and is mostly comparable to using strict object equivalence to check for a key match. As with Object, there is no restriction on what is contained in the value.

Const m = new Map();
 
const functionKey = function() {};
const symbolKey = Symbol();
const objectKey = new Object();
 
m.set(functionKey, "functionValue");
m.set(symbolKey, "symbolValue");
m.set(objectKey, "objectValue");
 
alert(m.get(functionKey));  // functionValue
alert(m.get(symbolKey));    // symbolValue
alert(m.get(objectKey));    // objectValue
 
// SameValueZero checks mean separate instances will not collide
alert(m.get(function() {}));  // undefined

As with strict equivalence, objects and other “collection” types used for keys and values remain unchanged inside a Map when their contents or properties are altered:

const m = new Map();
 
const objKey = {},
      objVal = {},
      arrKey = [],
      arrVal = [];
 
m.set(objKey, objVal);
m.set(arrKey, arrVal);
 
objKey.foo = "foo";
objVal.bar = "bar";
arrKey.push("foo");
arrVal.push("bar");
 
alert(m.get(objKey));  // {bar: "bar"}
alert(m.get(arrKey));  // ["bar"]

The use of the SameValueZero operation may introduce unexpected collisions:

const m = new Map();
 
const a = 0/"",  // NaN
      b = 0/"",  // NaN
      pz = +0,
      nz = -0;
 
alert(a === b);    // false
alert(pz === nz);  // true
 
m.set(a, "foo");
m.set(pz, "bar");
 
alert(m.get(b));   // foo
alert(m.get(nz));  // bar

Order and Iteration

One major departure from the Object type's conventions is that Map instances maintain the order of key-value insertion and allow you to perform iterative operations following insertion order.

A Map instance can provide an Iterator that contains array pairs in the form of [key, value] in insertion order. This iterator can be retrieved using entries(), or the Symbol.iterator property, which references entries():

const m = new Map([
  ["key1", "val1"],
  ["key2", "val2"],
  ["key3", "val3"]
]);
 
alert(m.entries === m[Symbol.iterator]); // true
 
for (let pair of m.entries()) {
  alert(pair);
}
// [key1,val1]
// [key2,val2]
// [key3,val3]
 
for (let pair of m[Symbol.iterator]()) {
  alert(pair);
}
// [key1,val1]
// [key2,val2]
// [key3,val3]

Because entries() is the default iterator, the spread operator can be used to concisely convert a Map into an array:

const m = new Map([
  ["key1", "val1"],
  ["key2", "val2"],
  ["key3", "val3"]
]);
 
alert([...m]); // [[key1,val1],[key2,val2],[key3,val3]]

To use a callback convention instead of an iterator, forEach(callback, opt_thisArg) invokes the callback for each key-value pair. It optionally accepts a second argument, which will override the value of this inside each callback invocation.

Const m = new Map([
  ["key1", "val1"],
  ["key2", "val2"],
  ["key3", "val3"]
]);
 
m.forEach((val, key) => alert(`${key} -> ${val}`));
// key1 -> val1
// key2 -> val2
// key3 -> val3

keys() and values() return an iterator that contains all keys or all values in the Map in insertion order:

const m = new Map([
  ["key1", "val1"],
  ["key2", "val2"],
  ["key3", "val3"]
]);
 
for (let key of m.keys()) {
  alert(key);
}
// key1
// key2
// key3
 
for (let key of m.values()) {
  alert(key);
}
// value1
// value2
// value3

Keys and values exposed inside an iterator are mutable, but the references inside the Map cannot be altered. However, this does not restrict changing properties inside a key or value object. Doing so will not alter their identity with respect to the Map instance:

const m1 = new Map([
  ["key1", "val1"]
]);
 
// String primitive as key is unaltered
for (let key of m.keys()) {
  key = "newKey";
  alert(key);            // newKey
  alert(m.get("key1"));  // val1
}
 
const keyObj = {id: 1};
 
const m = new Map([
  [keyObj, "val1"]
]);
 
// Key object property is altered, but the object still refers
// to the same value inside the map
for (let key of m.keys()) {
  key.id = "newKey";
  alert(key);            // {id: "newKey"}
  alert(m.get(keyObj));  // val1
}
alert(keyObj);           // {id: "newKey"}

Choosing Between Objects and Maps

There are some important differences between objects and maps that may influence when one is chosen over the other.

Keys

The Object type can only use integers, strings, or symbols as keys. A Map may use any type as the key.

Memory Profile

The engine-level implementation of Object and Map will obviously differ between browsers, but the amount of memory required to store a single key-value pair scales linearly with the number of keys. Bulk addition or removal of key-value pairs is also governed by how the engine implements memory allocation for that type. Results may vary by browser, but given a fixed amount of memory, a Map will be able to store roughly 50 percent more key-value pairs than an Object.

Insertion Performance

Inserting a new key-value pair into an Object versus a Map is a roughly comparable operation, but insertion into a Map will generally be slightly faster across all browser engines. For both types, the speed of an insertion does not scale linearly with the number of key-value pairs in the Object or Map. If your code is heavy on insert operations, Map instances offer superior performance.

Lookup Performance

Unlike insertion, looking up a key-value pair in an Object versus a Map is a roughly comparable operation at scale, but a smaller number of key-value pairs favor Object instances in some situations. In situations where an Object instance is being used like an array (for example, consecutive integer properties), the browser engine can perform optimizations such as more efficient layout in memory—this is never possible with a Map. For both types, lookup speed does not scale linearly with the number of key-value pairs in an Object or Map. If your code is heavy on lookup operations, in some scenarios it may be more advantageous to use an Object.

Delete Performance

The performance of the delete operation on Object properties is notorious for being horrendous, and this is still very much the case in many browser engines. Workarounds for pseudo-deleting object properties include assigning undefined or null as the property value, but in many cases this is an obnoxious or unsuitable compromise. Across most browser engines, the Map delete() operation is faster than insert and lookup. If your code is heavy on delete operations, the Map type is the overwhelming favorite.

THE SET TYPE

Set is a collection reference type that introduces set behavior into the language. A Set in many ways behaves more like an augmented Map, as much of the API and behavior is shared.

Basic API

An empty Set is instantiated with the new keyword:

const m = new Set();

If you wish to populate the map when it is initialized, the constructor optionally accepts an iterable object containing elements to be added into the newly created Set instance.

// Initialize set with array
const s1 = new Set(["val1", "val2", "val3"]);
alert(s1.size);  // 3
 
// Initialize set with custom-defined iterator
const s2 = new Set({
  [Symbol.iterator]: function*() {
    yield "val1";
    yield "val2";
    yield "val3";
  }
});
alert(s2.size);  // 3

Values can be added after initialization with add(), queried with has(), counted with the size property, and removed with delete() and clear():

const s = new Set();
 
alert(s.has("Matt"));     // false
alert(s.size);            // 0
 
s.add("Matt")
 .add("Frisbie");
 
alert(s.has("Matt"));     // true
alert(s.size);            // 2
 
s.delete("Matt");
 
alert(s.has("Matt"));     // false
alert(s.has("Frisbie"));  // true
alert(s.size);            // 1
 
s.clear();  // destroys all values in this Set instance
 
alert(s.has("Matt"));     // false
alert(s.has("Frisbie"));  // false
alert(s.size);            // 0

The add() method returns the Set instance, so it is possible to chain multiple operations together, including on the initial declaration:

const s = new Set().add("val1");
 
s.set("val2")
 .set("val3");
 
alert(s.size);  // 3

Like Map, a Set can contain any JavaScript data type as a value. It uses the SameValueZero comparison operation (defined inside the ECMAScript specification and not available in the actual language) and is mostly comparable to using strict object equivalence to check for a key match. There is no restriction on what is contained in the value.

Const s = new Set();
 
const functionVal = function() {};
const symbolVal = Symbol();
const objectVal = new Object();
 
s.add(functionVal);
s.add(symbolVal);
s.add(objectVal);
 
alert(s.has(functionVal));    // true
alert(s.has(symbolVal));      // true
alert(s.has(objectVal));      // true
 
// SameValueZero checks mean separate instances will not collide
alert(s.has(function() {}));  // false

As with strict equivalence, objects and other “collection” types used for values remain unchanged inside a set when their contents or properties are altered:

const s = new Set();
 
const objVal = {},
      arrVal = [];
 
s.add(objVal)
 .add(arrVal);
 
objVal.bar = "bar";
arrVal.push("bar");
 
alert(s.has(objVal));  // true
alert(s.has(arrVal));  // true

The add() and delete() operations are idempotent. Delete() returns a Boolean indicating if that value was present in the set.

Const s = new Set();
 
s.add('foo');
alert(s.size);  // 1
s.add('foo');
alert(s.size);  // 1
 
// Value was present in the set
alert(s.delete('foo'));  // true
 
// Value was not present in the set
alert(s.delete('foo'));  // false

Order and Iteration

Sets maintain the order of value insertion and allow you to perform iterative operations following insertion order.

A Set instance can provide an iterator that contains the set contents in insertion order. This iterator can be retrieved using values(), its alias keys(), or the Symbol.iterator property, which references values():

const s = new Set(["val1", "val2", "val3"]);
 
alert(s.values === s[Symbol.iterator]); // true
alert(s.keys === s[Symbol.iterator]); // true
 
for (let value of s.values()) {
  alert(value);
}
// val1
// val2
// val3
 
for (let value of s[Symbol.iterator]()) {
  alert(value);
}
// val1
// val2
// val3

Because values() is the default iterator, the spread operator can be used to concisely convert a set into an array:

const s = new Set(["val1", "val2", "val3"]);
 
alert([...s]); // [val1,val2,val3]

entries() returns an iterator that contains a two-element array containing a duplicate of all values in the Set in insertion order:

const s = new Set(["val1", "val2", "val3"]);
 
for (let pair of s.entries()) {
  alert(pair);
}
// [val1,val1]
// [val2,val2]
// [val3,val3]

To use a callback convention instead of an iterator, forEach(callback, opt_thisArg) invokes the callback for each value. It optionally accepts a second argument, which will override the value of this inside each callback invocation.

Const s = new Set(["val1", "val2", "val3"]);
 
s.forEach((val, dupVal) => alert(`${val} -> ${dupVal}`));
// val1 -> val1
// val2 -> val2
// val3 -> val3

Changing properties of values in a Set does not alter the value's identity with respect to the Set instance:

const s1 = new Set(["val1"]);
 
// String primitive as value is unaltered
for (let value of s1.values()) {
  value = "newVal";
  alert(value);          // newVal
  alert(s1.has("val1"));  // true
}
 
const valObj = {id: 1};
 
const s2 = new Set([valObj]);
 
// Value object property is altered, but the object still exists
// inside the set
for (let value of s2.values()) {
  value.id = "newVal";
  alert(value);          // {id: "newVal"}
  alert(s2.has(valObj));  // true
}
alert(valObj);           // {id: "newVal"}

WEAK REFERENCES

JavaScript is a garbage-collected language, which means that it automatically manages the allocation and deallocation of memory for objects. When an object is no longer being used, the garbage collector frees up the memory it was using so it can be used for other purposes. However, in some cases, we might want to keep a reference to an object without preventing it from being garbage collected. This kind of reference is called a weak reference. A weak reference is a type of reference that does not prevent an object from being garbage collected. This means that if the only reference to an object is a weak reference, the garbage collector will free up the memory used by the object.

WeakRef

In JavaScript, objects can be weakly referenced with the WeakRef class. Its constructor takes a single argument, the target object that should be weakly referenced:

let obj = { name: "Matt" };
let weakRef = new WeakRef(obj);

This target cannot be changed after instantiation. To access the target that is being weakly referenced, use its deref() method. This method returns the target or returns undefined if the target has been garbage collected. The following example demonstrates what you would see before and after garbage collection takes place:

let obj = { name: "Matt" };
let weakRef = new WeakRef(obj);
 
console.log(weakRef.deref());  // { name: "Matt" }
obj = null;
 
// Eventually, the browser will garbage collect the target object
 
// After GC occurs:
console.log(weakRef.deref()); undefined

FinalizationRegistry

Sometimes, you might want to perform some cleanup or finalization when an object is about to be garbage collected. This is where the FinalizationRegistry object comes in. The FinalizationRegistry allows us to define a callback function that will be called just before an object is garbage collected. Objects can be added and removed to the registry with register() and unregister().

To register an object, the register() method is passed the target object and a held value that will be passed to the handler when GC is about to occur. Here's an example:

let obj = { name: "Matt" };
let finalizationRegistry = new FinalizationRegistry((heldValue) => {
  console.log(`Cleaning up object: ${heldValue}`);
});
 
finalizationRegistry.register(obj, "My held value");
 
obj = null;
 
// After GC:
// "Cleaning up object: My held value"

To unregister an object, call unregister() and pass it the registered object:

let obj = { name: "Matt" };
let finalizationRegistry = new FinalizationRegistry((heldValue) => {
  console.log(`Cleaning up object: ${heldValue}`);
});
 
finalizationRegistry.register(obj, "My held value");
 
obj = null;
 
finalizationRegistry.unregister(obj);
 
// After GC:
// <no output>

FinalizationRegistry is a feature that requires careful consideration and should be avoided if possible. Some things to consider:

The behavior of garbage collection in JavaScript is not guaranteed and may vary depending on the engine and version used.
The use of cleanup callbacks is not recommended for essential program logic because the timing and occurrence of their execution are dependent on the JavaScript engine's implementation.
It is likely that major implementations will execute cleanup callbacks at some point during program execution, but they may occur substantially after the related object was reclaimed.
Certain situations, such as shutting down a program entirely, may prevent the execution of cleanup callbacks altogether.

THE WEAKMAP TYPE

The WeakMap is a collection reference type that introduces augmented key-value behavior into the language. The WeakMap type is a cousin to the Map type, and its API is a strict subset of Map. The “weak” designation describes how JavaScript's garbage collector treats keys in a WeakMap.

Basic API

An empty WeakMap is instantiated with the new keyword:

const wm = new WeakMap();

Keys in a WeakMap can only be of type Object or inherit from Object—all other attempts to set a key with a non-object will throw a TypeError. There are no restrictions on the type of the value.

If you wish to populate the WeakMap when it is initialized, the constructor optionally accepts an iterable object, expecting it to contain valid key-value pair arrays. Each pair in the iterable argument will be inserted into the newly created WeakMap in the order in which they are iterated:

const key1 = {id: 1},
      key2 = {id: 2},
      key3 = {id: 3};
// Initialize WeakMap with nested arrays
const wm1 = new WeakMap([
  [key1, "val1"],
  [key2, "val2"],
  [key3, "val3"]
]);
alert(wm.get(key1));  // val2
alert(wm.get(key2));  // val2
alert(wm.get(key3));  // val3
 
// Initialization is all-or-nothing, a single bad key will
// throw an error and abort the initialization
const wm2 = new WeakMap([
  [key1, "val1"],
  ["BADKEY", "val2"],
  [key3, "val3"]
]);
// TypeError: Invalid value used as WeakMap key
typeof wm2;
// ReferenceError: wm2 is not defined
 
// Primitives can still be used with an object wrapper
const stringKey = new String("key1");
const wm3 = new WeakMap([
  stringKey, "val1"
]);
alert(wm3.get(stringKey));  // "val1"

Key-value pairs can be added after initialization with set(), queried with get() and has(), and removed with delete():

const wm = new WeakMap();
 
const key1 = {id: 1},
      key2 = {id: 2};
 
alert(wm.has(key1));  // false
alert(wm.get(key1));  // undefined
 
wm.set(key1, "Matt")
  .set(key2, "Frisbie");
 
alert(wm.has(key1));  // true
alert(wm.get(key1));  // Matt
 
wm.delete(key1);  // deletes only this key-value pair
 
alert(wm.has(key1));  // false
alert(wm.has(key2));  // true

The set() method returns the WeakMap instance, so it is possible to chain multiple set operations together, including on the initial declaration:

const key1 = {id: 1},
      key2 = {id: 2},
      key3 = {id: 3};
 
const wm = new WeakMap().set(key1, "val1");
 
wm.set(key2, "val2")
  .set(key3, "val3");
 
alert(wm.get(key1));  // val1
alert(wm.get(key2));  // val2
alert(wm.get(key3));  // val3

Weak Keys

The “weak” designation stems from the fact that keys in a WeakMap are “weakly held,” meaning they are not counted as formal references that would otherwise prevent garbage collection. An important distinction for the WeakMap is that the value reference is not weakly held. As long as the key exists, the key-value pair will remain in the map and count as a reference to the value—thereby preventing it from being garbage collected.

Consider the following example:

const wm = new WeakMap();
 
wm.set({}, "val");

Inside set(), a fresh object is initialized and used as a key to a dummy string. Because there are no other references to this object, as soon as this line is finished executing, the object key will be free for garbage collection. When this occurs, the key-value pair will disappear from the WeakMap, and it will be empty. In this example, because there are no other references to the value, this key-value destruction will also mean that the value is eligible for garbage collection.

Consider a slightly different example:

const wm = new WeakMap();
 
const container = {
  key: {}
};
 
wm.set(container.key, "val");
 
function removeReference(){
  container.key = null;
}

Here, the container object maintains a reference to the key in the WeakMap, so the object is ineligible for garbage collection. However, as soon as removeReference() is invoked, the last strong reference to the key object will be destroyed, and garbage collection will eventually wipe out the key-value pair.

Non-Iterable Keys

Because key-value pairs in a WeakMap can be destroyed at any time, it does not make sense to offer the ability to iterate through the key-value pairs. This also excludes the ability to destroy all key-value pairs at once using clear(), which is not part of the WeakMap API. Because iteration is not possible, it is also not possible to retrieve a value from a WeakMap instance unless you have a reference to the key object. Even if code has access to the WeakMap instance, there is no way to inspect its contents.

The reason that WeakMap instances restrict keys to only objects is to preserve the convention that values can only be retrieved from a WeakMap with a reference to the key object. If primitives were allowed, the WeakMap instance would have no way of differentiating between the string primitive that was initially used to set the key-value pair and an identical string primitive that was initialized later—an undesirable behavior.

Utility

Because WeakMap instances do not interfere with garbage collection, they are a terrific tool for cleanup-free metadata association. Consider the following example, which uses a regular Map:

const m = new Map();
 
const loginButton = document.querySelector('#login');
 
// Associates some metadata with the node
m.set(loginButton, {disabled: true});

Suppose after this code executes, the page is changed by JavaScript and the login button is removed from the DOM tree. Because a reference exists inside the Map, the DOM node will linger in memory in perpetuity until explicitly removed from the Map, or until the Map is destroyed.

If, instead, a WeakMap was used, as shown in the following code, the node's removal from the DOM would allow the garbage collector to free the allocated memory immediately (assuming no other lingering references to the object).

const wm = new WeakMap();
 
const loginButton = document.querySelector('#login');
 
// Associates some metadata with the node
wm.set(loginButton, {disabled: true});

THE WEAKSET TYPE

WeakSet is a collection reference type that introduces set behavior into the language. The WeakSet type is a cousin to the Set type, and its API is a strict subset of Set. The “weak” designation describes how JavaScript's garbage collector treats values in a weak map.

Basic API

An empty WeakSet instance is instantiated with the new keyword:

const ws = new WeakSet();

Values in a WeakSet can only be of type or inherit from Object—all other attempts to set a value with a non-object will throw a TypeError.

If you wish to populate the WeakSet when it is initialized, the constructor optionally accepts an iterable object, expecting it to contain valid values. Each value in the iterable argument will be inserted into the newly created WeakSet in the order in which they are iterated:

const val1 = {id: 1},
      val2 = {id: 2},
      val3 = {id: 3};
// Initialize WeakSet with nested arrays
const ws1 = new WeakSet([val1, val2, val3]);
 
alert(ws1.has(val1));  // true
alert(ws1.has(val2));  // true
alert(ws1.has(val3));  // true
 
// Initialization is all-or-nothing, a single bad value will
// throw an error and abort the initialization
const ws2 = new WeakSet([val1, "BADVAL", val3]);
// TypeError: Invalid value used in WeakSet
typeof ws2;
// ReferenceError: ws2 is not defined
 
// Primitives can still be used with an object wrapper
const stringVal = new String("val1");
const ws3 = new WeakSet([stringVal]);
alert(ws3.has(stringVal));  // true

Values can be added after initialization with add(), queried with has(), and removed with delete():

const ws = new WeakSet();
 
const val1 = {id: 1},
      val2 = {id: 2};
 
alert(ws.has(val1));  // false
 
ws.add(val1)
  .add(val2);
 
alert(ws.has(val1));  // true
alert(ws.has(val2));  // true
 
ws.delete(val1);  // deletes only this value
 
alert(ws.has(val1));  // false
alert(ws.has(val2));  // true

The add() method returns the WeakSet instance, so it is possible to chain multiple add operations together, including on the initial declaration:

const val1 = {id: 1},
      val2 = {id: 2},
      val3 = {id: 3};
 
const ws = new WeakSet().add(val1);
 
ws.add(val2)
  .add(val3);
 
alert(ws.has(val1));  // true
alert(ws.has(val2));  // true
alert(ws.has(val3));  // true

Weak Keys

The “weak” designation stems from the fact that values in a WeakSet are “weakly held,” meaning they are not counted as formal references, which would otherwise prevent garbage collection.

Consider the following example:

const ws = new WeakSet();
 
ws.add({});

Inside add(), a fresh object is initialized and used as a value. Because there are no other references to this object, as soon as this line is finished executing, the object value will be free for garbage collection. When this occurs, the value will disappear from the WeakSet, and it will be empty.

Consider a slightly different example:

const ws = new WeakSet();
 
const container = {
  val: {}
};
 
ws.add(container.val);
 
function removeReference(){
  container.val = null;
}

Here, the container object maintains a reference to the value in the WeakSet instance, so the object is ineligible for garbage collection. However, as soon as removeReference() is invoked, the last strong reference to the value object will be destroyed, and garbage collection will eventually wipe out the value.

Non-Iterable Values

Because values in a WeakSet can be destroyed at any time, it does not make sense to offer the ability to iterate through the values. This also excludes the ability to destroy all values at once using clear(), which is not part of the WeakSet API. Because iteration is not possible, it is also not possible to retrieve a value from a WeakSet instance unless you have a reference to the value object. Even if code has access to the WeakSet instance, there is no way to inspect its contents.

WeakSet instances restrict keys to only objects in order to preserve the convention that values can only be retrieved from a WeakSet with a reference to the value object. If primitives were allowed, the WeakSet would have no way of differentiating between the string primitive that was initially used to set the value and an identical string primitive that was initialized later—an undesirable behavior.

Utility

Like WeakMap, WeakSet is useful when you wish to track an object without preventing its garbage collection. Consider the following example, which uses a regular Set:

const disabledElements = new Set();
 
const loginButton = document.querySelector('#login');
 
// Tags the node as "disabled" by adding it to the corresponding set
disabledElements.add(loginButton);

Here, it is possible to check if an element is disabled by seeing if it exists inside disabledElements, which can be done in constant time. However, if the element is removed from the DOM, its presence inside this Set will prevent garbage collection from reallocating its memory.

To allow the garbage collection to reallocate the element's memory a WeakSet can instead be used:

const disabledElements = new WeakSet();
 
const loginButton = document.querySelector('#login');
 
// Tags the node as "disabled" by adding it to the corresponding set
disabledElements.add(loginButton);

Now, when any element in the WeakSet is removed from the DOM, the garbage collector will ignore its presence inside the WeakSet when considering it for garbage collection.

ITERATION AND SPREAD OPERATORS

Iterators and the spread operator are especially useful in the context of collection reference types. These new tools allow for easy interoperability, cloning, and modification of collection reference types.

As shown earlier in the chapter, Array, Map, Set, and all typed arrays define a default iterator. This means that all support ordered iteration and can be passed to a for-of loop:

let iterableThings = [
  Array.of(1, 2),
  typedArr = Int16Array.of(3, 4),
  new Map([[5, 6], [7, 8]]),
  new Set([9, 10])
];
 
 
for (const iterableThing of iterableThings) {
  for (const x of iterableThing) {
    console.log(x);
  }
}
 
// 1
// 2
// 3
// 4
// [5, 6]
// [7, 8]
// 9
// 10

This also means that all these types are compatible with the spread operator. The spread operator is especially useful as it performs a shallow copy on the iterable object. This allows you to easily clone entire objects with a succinct syntax:

let arr1 = [1, 2, 3];
let arr2 = [...arr1];
 
console.log(arr1);           // [1, 2, 3]
console.log(arr2);           // [1, 2, 3]
console.log(arr1 === arr2);  // false

Constructors which expect an iterable object can just be passed the iterable instance to be cloned:

let map1 = new Map([[1, 2], [3, 4]]);
let map2 = new Map(map1);
 
console.log(map1);  // Map {1 => 2, 3 => 4}
console.log(map2);  // Map {1 => 2, 3 => 4}

It also allows for partial array construction:

let arr1 = [1, 2, 3];
let arr2 = [0, ...arr1, 4, 5];
 
console.log(arr2);  // [0, 1, 2, 3, 4, 5]

The shallow copy mechanism means that only object references are copied:

let arr1 = [{}];
let arr2 = [...arr1];
 
arr1[0].foo = â€˜barâ€™;
console.log(arr2[0]); // { foo: â€˜barâ€™ }

Each of these collection reference types support multiple methods of construction, such as the Array.of() and Array.from() static methods. When combined with the spread operator, this makes for extremely easy interoperability:

let arr1 = [1, 2, 3];
 
// Copy array into typed array
let typedArr1 = Int16Array.of(...arr1);
let typedArr2 = Int16Array.from(arr1);
console.log(typedArr1);  // Int16Array [1, 2, 3]
console.log(typedArr2);  // Int16Array [1, 2, 3]
 
// Copy array into map
let map = new Map(arr1.map((x) => [x, â€˜valâ€™ + x]));
console.log(map);  // Map {1 => â€˜val 1â€™, 2 => â€˜val 2â€™, 3 => â€˜val 3â€™}
 
// Copy array in to set
let set = new Set(typedArr2);
console.log(set);  // Set {1, 2, 3}
 
// Copy set back into array
let arr2 = [...set];
console.log(arr2);  // [1, 2, 3]

SUMMARY

JavaScript supports a range of advanced reference types that allow for handling collections of data and managing object references. Objects are unordered collections of key-value pairs, where the keys are strings or symbols and the values can be any data type. Objects have many built-in methods that allow developers to manipulate and iterate over an object's properties.

Arrays are ordered collections of values, which can be of any data type. Arrays have many built-in methods that allow developers to add, remove, and manipulate array elements.

Typed arrays are collections of values of a specific type, such as Int32Array or Float64Array. These are useful for working with binary data and performant numeric operations.

JavaScript allows for weak references to objects. Weak references do not prevent the garbage collector from reclaiming the referenced object, making them useful for tracking objects that are no longer needed by the program. These features are important for memory management and can help prevent memory leaks in large and complex applications.

WeakRef provides a way to create a weak reference to an object, while FinalizationRegistry allows for cleanup code to be executed when the object is no longer needed. WeakSet and WeakMap are collections that only allow weak references to their elements, which can be useful for managing object relationships that should not prevent garbage collection.

7
Iterators and Generators

The term “iteration” is derived from the Latin itero, meaning “repeat” or “do again.” In the context of software, “iteration” means repetitively performing a procedure multiple times, in sequence, and usually with an expectation of termination. The ECMAScript specification introduces two high-level features—iterators and generators—to allow for cleaner, faster, and easier iteration.

INTRODUCTION TO ITERATION

In JavaScript, one of the simplest examples of iteration is a counting loop:

for (let i = 1; i <= 10; ++i) {
  console.log(i);
}

Loops are a fundamental iterative tool because they allow you to specify how many iterations should occur and what should occur during each iteration. Each loop iteration will finish execution before another begins, and the order in which each iteration occurs is well-defined.

Iteration can occur over ordered collections of items. (Consider “ordered” in this context to imply there is an accepted sequence in which all the items should be traversed, with a definitive beginning and end item.) In JavaScript, the most common example of this ordered collection is an array.

let collection = ['foo', 'bar', 'baz'];

for (let index = 0; index < collection.length; ++index) {
  console.log(collection[index]);
}

Because an array has a known length, and because each item in that array can be retrieved via its index, the entire array can be traversed in order by incrementing the range of possible indices.

The fundamental procedure occurring in such a loop is not ideal for several reasons:

Iterating through the data structure requires a specific knowledge of how to use the data structure. Each item in the array can only be retrieved by first referencing the array object and then retrieving an item at a specific index using the [] operator. This does not generalize to other data structures.
The order of traversal is not inherent to the data structure. Incrementing an integer to access sequential indices is specific to the array type and does not generalize to other data structures that have an implicit ordering.

ES5 introduced the Array.prototype.forEach method, which is closer to what is needed (but still not an ideal solution):

let collection = ['foo', 'bar', 'baz'];

collection.forEach((item) => console.log(item));
// foo
// bar
// baz

This solves the problem of separately tracking an index and retrieving items via the array object. However, there is no way to terminate this iteration, the method is limited to arrays, and the callback structure is unwieldy.

With earlier versions of ECMAScript, performing iteration required the use of loops or other auxiliary constructs, which is an increasingly messy affair as code complexity scales. Many languages have addressed this problem with a native language construct that allows iteration to be performed without specific knowledge of how the iteration was actually occurring, and the solution is the iterator pattern. Python, Java, C++, and many other languages offer first-class support for this pattern.

THE ITERATOR PATTERN

The iterator pattern (specifically in the context of ECMAScript) describes a solution in which something can be described as “iterable” and can implement a formal Iterable interface and is consumed by an iterator.

The concept of an “iterable” is intentionally abstract. Frequently, the iterable will take the form of a collection object like an array or set, both of which have a finite number of countable elements and feature an unambiguous order of traversal:

// Arrays have finite countable elements
// In-order traversal visits each index in increasing index order
let arr = [3, 1, 4];

// Sets have finite countable elements
// In-order traversal visits each value in insertion order
let set = new Set().add(3).add(1).add(4);

However, an iterable does not have to be linked to a collection object. It can also be linked to something that only behaves like an array—such as the counting loop from earlier in the chapter. The values generated in this loop are transient, and yet such a loop is performing iteration. Both this counting loop and an array can behave as an iterable.

Anything that implements the Iterable interface can be “consumed” by an object that implements the Iterator interface. An iterator is a separate object created on demand and intended for a single use. Each iterator is associated with an iterable, and the iterator exposes an API to iterate through the associated iterable a single time. The iterator doesn't need to understand the structure of the iterable it is associated with; it only must know how to retrieve sequential values. This separation of concerns is what makes the Iterable/Iterator convention so useful.

The Iterable Protocol

Implementing the Iterable interface requires both the capability to self-identify as supporting iteration and the capability to create an object that implements the Iterator interface. In ECMAScript, this means it must expose a property, the “default iterator,” keyed with the special Symbol.iterator key. This default iterator property must refer to an iterator factory function, which will produce a new iterator when invoked.

Many built-in types implement the Iterable interface:

Strings
Arrays
Maps
Sets
The arguments object
Some DOM collection types like NodeList

Checking for the existence of this default iterator property will expose the factory function:

let num = 1;
let obj = {};

// These types do not have iterator factories
console.log(num[Symbol.iterator]);  // undefined
console.log(obj[Symbol.iterator]);  // undefined

let str = 'abc';
let arr = ['a', 'b', 'c'];
let map = new Map().set('a', 1).set('b', 2).set('c', 3);
let set = new Set().add('a').add('b').add('c');
let els = document.querySelectorAll('div');

// These types all have iterator factories
console.log(str[Symbol.iterator]);  // f values() { [native code] }
console.log(arr[Symbol.iterator]);  // f values() { [native code] }
console.log(map[Symbol.iterator]);  // f values() { [native code] }
console.log(set[Symbol.iterator]);  // f values() { [native code] }
console.log(els[Symbol.iterator]);  // f values() { [native code] }

// Invoking the factory function produces an Iterator
console.log(str[Symbol.iterator]());  // StringIterator {}
console.log(arr[Symbol.iterator]());  // ArrayIterator {}
console.log(map[Symbol.iterator]());  // MapIterator {}
console.log(set[Symbol.iterator]());  // SetIterator {}
console.log(els[Symbol.iterator]());  // ArrayIterator {}

You do not necessarily need to explicitly invoke this factory function to produce an iterator. Anything that implements this protocol is automatically compatible with any language features that accept an iterable. These native language constructs include:

for...of loop
Array destructuring
The spread operator
Array.from()
Set construction
Map construction
Promise.all(), which expects an iterable of promises
Promise.race(), which expects an iterable of promises
The yield* operator, used in generators

Behind the scenes, these native language constructs are invoking the factory function of the provided iterable to create an iterator:

let arr = ['foo', 'bar', 'baz'];

// for...of loops
for (let el of arr) {
  console.log(el);
}
// foo
// bar
// baz

// Array destructuring
let [a, b, c] = arr;
console.log(a, b, c);  // foo, bar, baz

// Spread operator
let arr2 = [...arr];
console.log(arr2);  // ['foo', 'bar', 'baz']

// Array.from()
let arr3 = Array.from(arr);
console.log(arr3);  // ['foo', 'bar', 'baz']

// Set constructor
let set = new Set(arr);
console.log(set);  // Set(3) {'foo', 'bar', 'baz'}

// Map constructor
let pairs = arr.map((x, i) => [x, i]);
console.log(pairs);  // [['foo', 0], ['bar', 1], ['baz', 2]]
let map = new Map(pairs);
console.log(map);  // Map(3) { 'foo'=>0, 'bar'=>1, 'baz'=>2 }

An object still implements the Iterable interface if a parent class up the prototype chain implements the interface:

class FooArray extends Array {}
let fooArr = new FooArray('foo', 'bar', 'baz');

for (let el of fooArr) {
  console.log(el);
}
// foo
// bar
// baz

The Iterator Protocol

An iterator is a single-use object that will iterate through whatever iterable it is associated with. The Iterator API uses a next() method to advance through the iterable. Each successive time next() is invoked, it will return an IteratorResult object containing the next value in the iterator. The current position the iterator is at cannot be known without invoking the next() method.

The next() method returns an object with two properties: done, which is a Boolean indicating if next() can be invoked again to retrieve more values, and value, which will contain the next value in the iterable or undefined if done is true. The done:true state is termed “exhaustion.” This can be demonstrated with a simple array:

// Iterable object
let arr = ['foo', 'bar'];

// Iterator factory
console.log(arr[Symbol.iterator]); // f values() { [native code] }

// Iterator
let iter = arr[Symbol.iterator]();
console.log(iter);  // ArrayIterator {}

// Performing iteration
console.log(iter.next());  // { done: false, value: 'foo' }
console.log(iter.next());  // { done: false, value: 'bar' }
console.log(iter.next());  // { done: true, value: undefined }

Arrays are iterated in order by creating an iterator and invoking next() until it ceases to produce new values. Note how the iterator does not know how to retrieve the next values inside the iterable, nor does it know how large the iterable is. Once the iterator reaches the done:true state, invoking next() is idempotent:

let arr = ['foo'];
let iter = arr[Symbol.iterator]();
console.log(iter.next());  // { done: false, value: 'foo' }
console.log(iter.next());  // { done: true, value: undefined }
console.log(iter.next());  // { done: true, value: undefined }
console.log(iter.next());  // { done: true, value: undefined }

Each iterator represents a one-time ordered traversal of the iterable. Different instances are not aware of each other and will independently traverse the iterable:

let arr = ['foo', 'bar'];
let iter1 = arr[Symbol.iterator]();
let iter2 = arr[Symbol.iterator]();

console.log(iter1.next());  // { done: false, value: 'foo' }
console.log(iter2.next());  // { done: false, value: 'foo' }
console.log(iter2.next());  // { done: false, value: 'bar' }
console.log(iter1.next());  // { done: false, value: 'bar' }

An iterator is not bound to a snapshot of the iterable; it merely uses a cursor to track its progress through the iterable. If the iterable is mutated during iteration, the iterator will incorporate the changes:

let arr = ['foo', 'baz'];
let iter = arr[Symbol.iterator]();

console.log(iter.next());  // { done: false, value: 'foo' }

// Insert value in the middle of array
arr.splice(1, 0, 'bar');

console.log(iter.next());  // { done: false, value: 'bar' }
console.log(iter.next());  // { done: false, value: 'baz' }
console.log(iter.next());  // { done: true, value: undefined }

The term “iterator” can be somewhat nebulous because it refers to a generalized iteration concept, an interface, and formal iterator-type classes. The following example compares an explicit iterator implementation and a native iterator implementation:

// This class implements the Iterable interface.
// Invoking the default iterator factory will return
// an iterator object that implements the Iterator interface.
class Foo {
  [Symbol.iterator]() {
    return {
      next() {
        return { done: false, value: 'foo' };
      }
    }
  }
}
let f = new Foo();

// Logs an object which implements the Iterator interface
console.log(f[Symbol.iterator]()); // { next: f() {} }


// The Array type implements the Iterable interface.
// Invoking the default iterator of an Array type
// will create an instance of ArrayIterator.
let a = new Array();

// Logs an instance of ArrayIterator
console.log(a[Symbol.iterator]()); // Array Iterator {}

Custom Iterator Definition

Like the Iterable interface, any object that implements the Iterator interface can be used as an iterator. Consider the following example where a Counter class is defined to iterate a specific number of times:

class Counter {
  // Counter instance should iterate <limit> times
  constructor(limit) {
    this.count = 1;
    this.limit = limit;
  }

  next() {
    if (this.count <= this.limit) {
      return { done: false, value: this.count++ };
    } else {
      return { done: true, value: undefined };
    }
  }

  [Symbol.iterator]() {
    return this;
  }
}

let counter = new Counter(3);

for (let i of counter) {
  console.log(i);
}
// 1
// 2
// 3

This satisfies the Iterator interface, but this implementation isn't optimal because each class instance can be iterated only once:

for (let i of counter) { console.log(i); }
// 1
// 2
// 3

for (let i of counter) { console.log(i); }
// (nothing logged)

In order to allow for creating multiple iterators from a single iterable, the counter must be created on a per-iterator basis. To address this, you can return an iterator object with the counter variables available through a closure:

class Counter {
  constructor(limit) {
    this.limit = limit;
  }

  [Symbol.iterator]() {
    let count = 1,
        limit = this.limit;
    return {
      next() {
        if (count <= limit) {
          return { done: false, value: count++ };
        } else {
          return { done: true, value: undefined };
        }
      }
    };
  }
}

let counter = new Counter(3);

for (let i of counter) { console.log(i); }
// 1
// 2
// 3
for (let i of counter) { console.log(i); }
// 1
// 2
// 3

Every iterator created in this way also implements the Iterable interface. The Symbol.iterator property refers to a factory that will return the same iterator:

let arr = ['foo', 'bar', 'baz'];
let iter1 = arr[Symbol.iterator]();

console.log(iter1[Symbol.iterator]); // f values() { [native code] }

let iter2 = iter1[Symbol.iterator]();

console.log(iter1 === iter2);  // true

Because every iterator also implements the Iterable interface, they can be used everywhere an iterable is expected, such as a for...of loop:

let arr = [3, 1, 4];
let iter = arr[Symbol.iterator]();

for (let item of arr) { console.log(item); }
// 3
// 1
// 4

for (let item of iter) { console.log(item); }
// 3
// 1
// 4

Early Termination of Iterators

The optional return() method allows for specifying behavior that will execute only if the iterator is closed prematurely. “Closing” an iterator occurs when the construct performing the iteration wishes to indicate to the iterator that it does not intend to finish traversing until exhaustion. Scenarios where this might happen include the following:

A for...of loop exits early via break, continue, return, or throw.
A destructuring operation does not consume all values.

The return() method must return a valid IteratorResult object. A simple iterator implementation should just return { done: true }, as the return value is only used in the context of generators, which is discussed later in the chapter.

As shown in the code that follows, a built-in language construct will automatically invoke the return() method once it identifies that there are further values that need to be iterated over that will not be consumed.

class Counter {
  constructor(limit) {
    this.limit = limit;
  }

  [Symbol.iterator]() {
    let count = 1,
        limit = this.limit;
    return {
      next() {
        if (count <= limit) {
          return { done: false, value: count++ };
        } else {
          return { done: true };
        }
      },
      return() {
        console.log('Exiting early');
        return { done: true };
      }
    };
  }
}

let counter1 = new Counter(5);

for (let i of counter1) {
  if (i > 2) {
    break;
  }
  console.log(i);
}
// 1
// 2
// Exiting early


let counter2 = new Counter(5);

try {
  for (let i of counter2 {
    if (i> 2) {
      throw 'err';
    }
    console.log(i);
  }
} catch(e) {}
// 1
// 2
// Exiting early


let counter3 = new Counter(5);

let [a, b] = counter3;
// Exiting early

If an iterator is not closed, then you are able to pick up iteration where you left off. For example, Array Iterators are not closable:

let a = [1, 2, 3, 4, 5];
let iter = a[Symbol.iterator]();

for (let i of iter) {
  console.log(i);
  if (i> 2) {
    break
  }
}
// 1
// 2
// 3

for (let i of iter) {
  console.log(i);
}
// 4
// 5

Because the return() method is optional, not all iterators are closable. Whether or not an iterator is closable can be ascertained by testing if the return property on the iterator instance is a function object. However, merely adding the method to a non-closable iterator will not make it become closable, as invoking return() does not force the iterator into a closed state. The return() method will, however, still be invoked.

GENERATORS

Generators are a delightfully flexible construct that offers the ability to pause and resume code execution inside a single function block. The implications of this ability are profound; it allows for, among many other things, the ability to define custom iterators and implement coroutines.

Generator Basics

Generators take the form of a function, and the generator designation is performed with an asterisk. Anywhere a function definition is valid, a generator function definition is also valid:

// Generator function declaration
function* generatorFn() {}

// Generator function expression
let generatorFn = function* () {}

// Object literal method generator function
let foo = {
  * generatorFn() {}
}

// Class instance method generator function
class Foo {
  * generatorFn() {}
}

// Class static method generator function
class Bar {
  static * generatorFn() {}
}

The function will be considered a generator irrespective of the whitespace surrounding the asterisk:

// Equivalent generator functions:
function* generatorFnA() {}
function *generatorFnB() {}
function * generatorFnC() {}

// Equivalent generator methods:
class Foo {
  *generatorFnD() {}
  * generatorFnE() {}
}

When invoked, generator functions produce a generator object. Generator objects begin in a state of suspended execution. Like iterators, these generator objects implement the Iterator interface and therefore feature a next() method, which, when invoked, instructs the generator to begin or resume execution.

function* generatorFn() {}

const g = generatorFn();

console.log(g);       // generatorFn {<suspended>}
console.log(g.next);  // f next() { [native code] }

The return value of this next() method matches that of an iterator, with a done and value property. A generator function with an empty function body will act as a passthrough; invoking next() a single time will result in the generator reaching the done:true state.

function* generatorFn() {}

let generatorObject = generatorFn();

console.log(generatorObject);         // generatorFn {<suspended>}
console.log(generatorObject.next());  // { done: true, value: undefined }

The value property is the return value of the generator function, which defaults to undefined and can be specified via the generator function's return value.

function* generatorFn() {
  return 'foo';
}

let generatorObject = generatorFn();

console.log(generatorObject);         // generatorFn {<suspended>}
console.log(generatorObject.next());  // { done: true, value: 'foo' }

Generator function execution will only begin upon the initial next() invocation, as shown here:

function* generatorFn() {
  console.log('foobar');
}

// Nothing is logged yet when the generator function is initially invoked
let generatorObject = generatorFn();

generatorObject.next();  // foobar

Generator objects implement the Iterable interface, and their default iterator is self-referential:

function* generatorFn() {}

console.log(generatorFn);
// f* generatorFn() {}
console.log(generatorFn()[Symbol.iterator]);
// f [Symbol.iterator]() {native code}

console.log(generatorFn());
// generatorFn {<suspended>}
console.log(generatorFn()[Symbol.iterator]());
// generatorFn {<suspended}

const g = generatorFn();

console.log(g === g[Symbol.iterator]());
// true

Interrupting Execution with yield

The yield keyword allows generators to stop and start execution, and it is what makes generators truly useful. Generator functions will proceed with normal execution until they encounter a yield keyword. Upon encountering the keyword, execution will be halted and the scope state of the function will be preserved. Execution will only resume when the next() method is invoked on the generator object:

function* generatorFn() {
  yield;
}

let generatorObject = generatorFn();

console.log(generatorObject.next());  // { done: false, value: undefined }
console.log(generatorObject.next());  // { done: true, value: undefined }

The yield keyword behaves as an intermediate function return, and the yielded value is available inside the object returned by the next() method. A generator function exiting via the yield keyword will have a done value of false; a generator function exiting via the return keyword will have a done value of true:

function* generatorFn() {
  yield 'foo';
  yield 'bar';
  return 'baz';
}

let generatorObject = generatorFn();

console.log(generatorObject.next());  // { done: false, value: 'foo' }
console.log(generatorObject.next());  // { done: false, value: 'bar' }
console.log(generatorObject.next());  // { done: true, value: 'baz' }

Execution progress within a generator function is scoped to each generator object instance. Invoking next() on one generator object does not affect any other:

function* generatorFn() {
  yield 'foo';
  yield 'bar';
  return 'baz';
}

let generatorObject1 = generatorFn();
let generatorObject2 = generatorFn();


console.log(generatorObject1.next());  // { done: false, value: 'foo' }
console.log(generatorObject2.next());  // { done: false, value: 'foo' }
console.log(generatorObject2.next());  // { done: false, value: 'bar' }
console.log(generatorObject1.next());  // { done: false, value: 'bar' }

The yield keyword can only be used inside a generator function; anywhere else will throw an error. Like the function return keyword, the yield keyword must appear immediately inside a generator function definition. Nesting further inside a non-generator function will throw a syntax error:

// valid
function* validGeneratorFn() {
  yield;
}

// invalid
function* invalidGeneratorFnA() {
  function a() {
    yield;
  }
}

// invalid
function* invalidGeneratorFnB() {
  const b = () => {
    yield;
  }
}

// invalid
function* invalidGeneratorFnC() {
  (() => {
    yield;
  })();
}

Using a Generator Object as an Iterable

You will infrequently find the need to explicitly invoke next() on a generator object. Instead, generators are much more useful when consumed as an iterable, as shown here:

function* generatorFn() {
  yield 1;
  yield 2;
  yield 3;
}

for (const x of generatorFn()) {
  console.log(x);
}
// 1
// 2
// 3

This can be especially useful when the need to define custom iterables arises. For example, it is often useful to define an iterable, which will produce an iterator that executes a specific number of times. With a generator, this can be accomplished simply with a loop:

function* nTimes(n) {
  while(n--) {
    yield;
  }
}

for (let _ of nTimes(3)) {
  console.log('foo');
}
// foo
// foo
// foo

The single generator function parameter controls the number of loop iterations. When n reaches 0, the while condition will become falsy, the loop will exit, and the generator function will return.

Using yield for Input and Output

The yield keyword also behaves as an intermediate function parameter. The yield keyword where the generator last paused execution will assume the first value passed to next(). Somewhat confusingly, the value provided to the first next() invocation is not used, as this next() is used to begin the generator function execution:

function* generatorFn(initial) {
  console.log(initial);
  console.log(yield);
  console.log(yield);
}

let generatorObject = generatorFn('foo');

generatorObject.next('bar');  // foo
generatorObject.next('baz');  // baz
generatorObject.next('qux');  // qux

The yield keyword can be simultaneously used as both an input and an output, as is shown in the following example:

function* generatorFn() {
  return yield 'foo';
}

let generatorObject = generatorFn();

console.log(generatorObject.next());       // { done: false, value: 'foo' }
console.log(generatorObject.next('bar'));  // { done: true, value: 'bar' }

Because the function must evaluate the entire expression to determine the value to return, it will pause execution when encountering the yield keyword and evaluate the value to yield, foo. The subsequent next() invocation provides the bar value as the value for that same yield, and this in turn is evaluated as the generator function return value.

The yield keyword is not limited to a one-time use. An infinite counting generator function can be defined as follows:

function* generatorFn() {
  for (let i = 0;;++i) {
    yield i;
  }
}

let generatorObject = generatorFn();

console.log(generatorObject.next().value);  // 0
console.log(generatorObject.next().value);  // 1
console.log(generatorObject.next().value);  // 2
console.log(generatorObject.next().value);  // 3
console.log(generatorObject.next().value);  // 4
console.log(generatorObject.next().value);  // 5
...

Suppose you wanted to define a generator function that would iterate a configurable number of times and produce the index of iteration. This can be accomplished by instantiating a new array, but the same behavior can be accomplished without the array:

function* nTimes(n) {
  for (let i = 0; i < n; ++i) {
    yield i;
  }
}

for (let x of nTimes(3)) {
  console.log(x);
}
// 0
// 1
// 2

Alternately, the following has a slightly less verbose while loop implementation:

function* nTimes(n) {
  let i = 0;
  while(n--) {
    yield i++;
  }
}

for (let x of nTimes(3)) {
  console.log(x);
}
// 0
// 1
// 2

Using generators in this way provides a useful way of implementing ranges or populating arrays:

function* range(start, end) {
  while(end> start) {
    yield start++;
  }
}

for (const x of range(4, 7)) {
  console.log(x);
}
// 4
// 5
// 6

function* zeroes(n) {
  while(n--) {
    yield 0;
  }
}

console.log(Array.from(zeroes(8)));  // [0, 0, 0, 0, 0, 0, 0, 0]

Yielding an Iterable

It is possible to augment the behavior of yield to cause it to iterate through an iterable and yield its contents one at a time. This can be done using an asterisk, as shown here:

// generatorFn is equivalent to:
// function* generatorFn() {
//   for (const x of [1, 2, 3]) {
//     yield x;
//   }
// }
function* generatorFn() {
  yield* [1, 2, 3];
}

let generatorObject = generatorFn();

for (const x of generatorFn()) {
  console.log(x);
}
// 1
// 2
// 3

Like the generator function asterisk, whitespace around the yield asterisk will not alter its behavior:

function* generatorFn() {
  yield* [1, 2];
  yield *[3, 4];
  yield * [5, 6];
}

for (const x of generatorFn()) {
  console.log(x);
}
// 1
// 2
// 3
// 4
// 5
// 6

Because yield* is effectively just serializing an iterable into sequential yielded values, using it isn't any different than placing yield inside a loop. These two generator functions are equivalent in behavior:

function* generatorFnA() {
  for (const x of [1, 2, 3]) {
    yield x;
  }
}

for (const x of generatorFnA()) {
  console.log(x);
}
// 1
// 2
// 3

function* generatorFnB() {
  yield* [1, 2, 3];
}

for (const x of generatorFnB()) {
  console.log(x);
}
// 1
// 2
// 3

The value of yield* is the value property accompanying done:true of the associated iterator. For vanilla iterators, this value will be undefined:

function* generatorFn() {
  console.log('iter value:', yield* [1, 2, 3]);
}

for (const x of generatorFn()) {
  console.log('value:', x);
}
// value: 1
// value: 2
// value: 3
// iter value: undefined

For iterators produced from a generator function, this value will take the form of whatever value is returned from the generator function:

function* innerGeneratorFn() {
  yield 'foo';
  return 'bar';
}
function* outerGeneratorFn(genObj) {
  console.log('iter value:', yield* innerGeneratorFn());
}

for (const x of outerGeneratorFn()) {
  console.log('value:', x);
}
// value: foo
// iter value: bar

Recursive Algorithms Using `yield*`

yield* is especially useful when used in a recursive operation, where the generator can yield itself. Consider the following example:

function* nTimes(n) {
  if (n> 0) {
    yield* nTimes(n - 1);
    yield n - 1;
  }
}

for (const x of nTimes(3)) {
  console.log(x);
}
// 0
// 1
// 2

In this example, each generator is first yielding each value from a newly created generator object, and then yielding a single integer. The result of this is that the generator function will recursively decrement the counter value and instantiate another generator object, which at the top level will have the effect of creating a single iterable that returns incremental integers.

Using recursive generator structure and yield* allows for elegantly expressing recursive algorithms. Consider the following graph implementation, which generates a random bidirectional graph:

class Node {
  constructor(id) {
    this.id = id;
    this.neighbors = new Set();
  }

  connect(node) {
    if (node !== this) {
      this.neighbors.add(node);
      node.neighbors.add(this);
    }
  }
}

class RandomGraph {
  constructor(size) {
    this.nodes = new Set();

    // Create nodes
    for (let i = 0; i < size; ++i) {
      this.nodes.add(new Node(i));
    }

    // Randomly connect nodes
    const threshold = 1 / size;
    for (const x of this.nodes) {
      for (const y of this.nodes) {
        if (Math.random() < threshold) {
          x.connect(y);
        }
      }
    }
  }

  // This is just for debug purposes
  print() {
    for (const node of this.nodes) {
      const ids = [...node.neighbors]
                      .map((n) => n.id)
                      .join(',');

      console.log('${node.id}: ${ids}');
    }
  }
}

const g = new RandomGraph(6);

g.print();
// Example output:
// 0: 2,3,5
// 1: 2,3,4,5
// 2: 1,3
// 3: 0,1,2,4
// 4: 2,3
// 5: 0,4

The graph data structure is well-suited for recursive traversal, and using a recursive generator allows you to do exactly that. To do so, the generator function must accept an iterable, yield each value in that iterable, and recurse on each value. A simple utilization of this would be to test if a graph is connected, meaning that there are no nodes that cannot be reached. This test can be accomplished by beginning at one node and exhaustively attempting to visit every node. The result is a very succinct implementation of a depth first traversal:

class Node {
  constructor(id) {
    ...
  }

  connect(node) {
    ...
  }
}

class RandomGraph {
  constructor(size) {
    ...
  }

  print() {
    ...
  }

  isConnected() {
    const visitedNodes = new Set();

    function* traverse(nodes) {
      for (const node of nodes) {
        if (!visitedNodes.has(node)) {
          yield node;
          yield* traverse(node.neighbors);
        }
      }
    }

    // Grab first node in the Set
    const firstNode = this.nodes[Symbol.iterator]().next().value;

    // Use the recursive generator to iterate every node
    for (const node of traverse([firstNode])) {
      visitedNodes.add(node);
    }

    return visitedNodes.size === this.nodes.size;
  }
}

Using a Generator as the Default Iterator

Because generator objects implement the Iterable interface, and because both generator functions and the default iterator are invoked to produce an iterator, generators are exceptionally well suited to be used as default iterators. The following is a simple example where the default iterator can yield the class's contents in a single line:

class Foo {
  constructor() {
    this.values = [1, 2, 3];
  }
  * [Symbol.iterator]() {
    yield* this.values;
  }
}

const f = new Foo();

for (const x of f) {
  console.log(x);
}
// 1
// 2
// 3

Here, the for...of loop invokes the default iterator—which happens to be a generator function—and produces a generator object. The generator object is an iterable and therefore compatible for use in iteration.

Early Termination of Generators

Like iterators, generators also support the concept of being “closable.” For an object to implement the Iterator interface, it must have a next() and, optionally, a return() method for when the iterator is terminated early. A generator object has both of these methods and an additional third method, throw().

function* generatorFn() {}

const g = generatorFn();

console.log(g);         // generatorFn {<suspended>}
console.log(g.next);    // f next() { [native code] }
console.log(g.return);  // f return() { [native code] }
console.log(g.throw);   // f throw() { [native code] }

The return() and throw() methods are two methods that can be used to coerce the generator into a closed state.

The return() Method

The return() method will force the generator into a closed state, and the value provided to return() will be the value provided in the terminal iterator object:

function* generatorFn() {
  for (const x of [1, 2, 3]) {
    yield x;
  }
}

const g = generatorFn();

console.log(g);            // generatorFn {<suspended>}
console.log(g.return(4));  // { done: true, value: 4 }
console.log(g);            // generatorFn {<closed>}

Unlike iterators, all generator objects have a return() method that forces it into a closed state that it cannot exit once reached. Subsequent invoking of next() will disclose the done:true state, but any provided return value is not stored or propagated:

function* generatorFn() {
  for (const x of [1, 2, 3]) {
    yield x;
  }
}

const g = generatorFn();

console.log(g.next());     // { done: false, value: 1 }
console.log(g.return(4));  // { done: true, value: 4 }
console.log(g.next());     // { done: true, value: undefined }
console.log(g.next());     // { done: true, value: undefined }
console.log(g.next());     // { done: true, value: undefined }

Built-in language constructs such as the for...of loop will sensibly ignore any values returned inside the done:true IteratorObject.

function* generatorFn() {
  for (const x of [1, 2, 3]) {
    yield x;
  }
}

const g = generatorFn();

for (const x of g) {
  if (x> 1) {
    g.return(4);
  }
  console.log(x);
}
// 1
// 2

The throw() Method

The throw() method will inject a provided error into the generator object at the point it is suspended. If the error is unhandled, the generator will close:

function* generatorFn() {
  for (const x of [1, 2, 3]) {
    yield x;
  }
}

const g = generatorFn();

console.log(g);    // generatorFn {<suspended>}
try {
  g.throw('foo');
} catch (e) {
  console.log(e);  // foo
}
console.log(g);    // generatorFn {<closed>}

If, however, the error is handled inside the generator function, then it will not close and can resume execution. The error handling will skip over that yield, so in this example you will see it skip a value. Consider the following example:

function* generatorFn() {
  for (const x of [1, 2, 3]) {
    try {
       yield x;
    } catch(e) {}
  }
}

const g = generatorFn();

console.log(g.next());  // { done: false, value: 1}
g.throw('foo');
console.log(g.next());  // { done: false, value: 3}

In this example, the generator suspends execution at a yield keyword inside a try/catch block. While it is suspended, throw() injects the foo error, which is thrown by the yield keyword. Because this error is thrown inside the generator's try/catch block, it is subsequently caught while still inside the generator. However, because yield threw that error, that value of 2 will not be produced by the generator. Instead, the generator function continues execution, proceeding on to the next loop iteration where it encounters the yield keyword yet again—this time, yielding the value 3.

ASYNCHRONOUS ITERATION

Asynchronous execution involves releasing control of the execution thread to allow slow operations to finish before regaining control, and the iterator protocol involves defining a canonical ordering for arbitrary objects. Asynchronous iteration is merely the logical assimilation of these two concepts.

A synchronous iterator provides you with a { value, done } pair each time next() is invoked. Of course, this requires that the computation and resource fetching needed to determine the contents of this pair be completed by the time the next() invocation exits—otherwise, these values are indeterminate. When using a synchronous iterator to iterate over values that are determined asynchronously, the main execution thread will be blocked while waiting for the asynchronous operation to complete.

With asynchronous iterators, this problem is totally solved. An asynchronous iterator provides you with a promise that resolves to a { value, done } pair each time next() is invoked. This way, the thread of execution can be released and perform work elsewhere while the current loop iteration is being resolved.

Creating and Using an Async Iterator

Async iterators are best understood through comparison with a traditional synchronous iterator. The following is a simple Emitter class, which contains a synchronous generator function that produces a synchronous iterator that will count from 0 to 4:

class Emitter {
  constructor(max) {
    this.max = max;
    this.syncIdx = 0;
  }

  *[Symbol.iterator]() {
    while(this.syncIdx < this.max) {
      yield this.syncIdx++;
    }
  }
}

const emitter = new Emitter(5);

function syncCount() {
  const syncCounter = emitter[Symbol.iterator]();

  for (const x of syncCounter) {
    console.log(x);
  }
}

syncCount();
// 0
// 1
// 2
// 3
// 4

The previous example only works because in each iteration, the next value is immediately able to be yielded. If instead you did not want to block the main thread of execution while determining the next value to yield, you can also define an asynchronous generator function that will yield Promise-wrapped values.

This can be accomplished using async-flavored versions of iterators and generators. ECMAScript defines Symbol.asyncIterator, which allows you to define and invoke Promise-yielding generator functions. The specification also defines an asynchronous for loop iterator, the for-await-of loop, intended to consume this async iterator. Using these, the previous example can be extended to support both synchronous and asynchronous iteration:

class Emitter {
  constructor(max) {
    this.max = max;
    this.syncIdx = 0;
    this.asyncIdx = 0;
  }

  *[Symbol.iterator]() {
    while(this.syncIdx < this.max) {
      yield this.syncIdx++;
    }
  }  async *[Symbol.asyncIterator]() {
  *[Symbol.asyncIterator]() {
    while(this.asyncIdx < this.max) {
      yield new Promise((resolve) => resolve(this.asyncIdx++;
    }
  }
}

const emitter = new Emitter(5);

function syncCount() {
  const syncCounter = emitter[Symbol.iterator]();

  for (const x of syncCounter) {
    console.log(x);
  }
}

async function asyncCount() {
  const asyncCounter = emitter[Symbol.asyncIterator]();

  for await(const x of asyncCounter) {
    console.log(x);
  }
}

syncCount();
// 0
// 1
// 2
// 3
// 4

asyncCount();
// 0
// 1
// 2
// 3
// 4

To further your understanding, swap out the above example so that the synchronous generator is passed to a for-await-of loop:

const emitter = new Emitter(5);

async function asyncIteratorSyncCount() {
  const syncCounter = emitter[Symbol.iterator]();

  for await(const x of syncCounter) {
    console.log(x);
  }
}

asyncIteratorSyncCount();
// 0
// 1
// 2
// 3
// 4

Even though the sync counter iterates through primitive values, the for-await-of loop will handle the values as if they were returned wrapped in promises. This demonstrates the power of the for-await-of loop, which allows it to fluently handle both synchronous and asynchronous iterables. This is not true for a normal for loop, which cannot handle an asynchronous iterator:

function syncIteratorAsyncCount() {
  const asyncCounter = emitter[Symbol.asyncIterator]();

  for (const x of asyncCounter) {
    console.log(x);
  }
}

syncIteratorAsyncCount();
// TypeError: asyncCounter is not iterable

One of the most important concepts to understand about async iterators is that the Symbol.asyncIterator designation doesn't alter the behavior of the generator function or how the generator is consumed. Note that the generator function is defined as an async function and designated as a generator using an asterisk. Symbol.asyncIterator merely suggests to an external construct such as a for-await-of loop that the associated iterator will return a sequence of promise objects.

Understanding the Async Iterator Queue

Of course, the previous example is quite contrived, as the promises returned from the iterator are instantaneously resolved, and therefore it is little more than a thinly wrapped synchronous iterator. Suppose instead that the yielded promises resolved after an indeterminate period of time; what's more, suppose they return out of order. An asynchronous iterator should emulate a synchronous iterator in every way possible, including in-order execution of code associated with each iteration. To address this, asynchronous iterators maintain a queue of callbacks to ensure that the iterator handler for an earlier value will always complete execution before proceeding to a later value, even if the later value resolves before the earlier value.

To prove this, the async iterator in the following example returns promises which resolve after a random period of time—behavior that emulates multiple network requests. The async iteration queue ensures that the promise resolution order does not interfere with the order of iteration. As a result, the integers will be printed in order (at random intervals):

class Emitter {
  constructor(max) {
    this.max = max;
    this.syncIdx = 0;
    this.asyncIdx = 0;
  }

  *[Symbol.iterator]() {
    while(this.syncIdx < this.max) {
      yield this.syncIdx++;
    }
  }
  async *[Symbol.asyncIterator]() {
    while(this.asyncIdx < this.max) {
      yield new Promise((resolve) => {
        setTimeout(() => {
          resolve(this.asyncIdx++);
        }, Math.floor(Math.random() * 1000));
      });
    }
  }
}

const emitter = new Emitter(5);

function syncCount() {
  const syncCounter = emitter[Symbol.iterator]();

  for (const x of syncCounter) {
    console.log(x);
  }
}

async function asyncCount() {
  const asyncCounter = emitter[Symbol.asyncIterator]();

  for await(const x of asyncCounter) {
    console.log(x);
  }
}

syncCount();
// 0
// 1
// 2
// 3
// 4

asyncCount();
// 0
// 1
// 2
// 3
// 4

Async Iterator reject() Handling

Because the composition of asynchronous iterators consists of promises, one must consider the possibility that one of the promises produced by the iterator will reject. Because the design of asynchronous iteration insists on in-order completion, it would not make sense to proceed past a rejected promise through the loop; therefore, a rejected promise will force the iterator to exit:

class Emitter {
  constructor(max) {
    this.max = max;
    this.asyncIdx = 0;
  }

  async *[Symbol.asyncIterator]() {
    while (this.asyncIdx < this.max) {
       if (this.asyncIdx < 3) {
        yield this.asyncIdx++;
       } else {
         throw 'Exited loop';
       }
    }
  }
}

const emitter = new Emitter(5);

async function asyncCount() {
  const asyncCounter = emitter[Symbol.asyncIterator]();

  for await (const x of asyncCounter) {
    console.log(x);
  }
}

asyncCount();
// 0
// 1
// 2
// Uncaught (in promise) Exited loop

Manual Async Iteration Using next()

The for-await-of loop offers two useful features: it makes use of the async iterator queue to ensure in-order execution, and it hides the promise structure of the async iterator. However, using such a loop conceals much of the underlying behavior.

Because the async iterator still follows the iterator protocol, you can just as easily progress through the async iterable using next(). As described earlier, next() contains a promise that will resolve to { value, done }. This means that you must use the Promise API to retrieve methods, but it also means that you are not forced to use the async iterator queue.

const emitter = new Emitter(5);

const asyncCounter = emitter[Symbol.asyncIterator]();

console.log(asyncCounter.next());
// { value: Promise, done: false }

Top-Level Async Loops

As a rule, async behavior—including for-await-of loops—cannot exist outside of an async function. However, you may find it necessary on occasion to make use of async behavior in such a context. This can be accomplished by creating an async IIFE:

class Emitter {
  constructor(max) {
    this.max = max;
    this.asyncIdx = 0;
  }

  async *[Symbol.asyncIterator]() {
    while(this.asyncIdx < this.max) {
      yield new Promise((resolve) => resolve(this.asyncIdx++));
    }
  }
}

const emitter = new Emitter(5);

(async function() {
  const asyncCounter = emitter[Symbol.asyncIterator]();

  for await(const x of asyncCounter) {
    console.log(x);
  }
})();
// 0
// 1
// 2
// 3
// 4

Implementing Observables

Because asynchronous iterators will patiently wait for the next iteration without incurring computational cost, an entirely new avenue for implementing an observable interface opens up. At a high level, this will take the form of capturing events, wrapping them in promises, and then feeding these events through the iterator to allow for the listener to hook into the asynchronous iterator. When an event is fired, the next promise in the async iterator will resolve with that event.

A simplistic example of this would be to capture an observable stream of browser events. This requires a queue of promises, each of which corresponds to a single event. The queue will also preserve the order in which events are generated, which is a desirable feature for this sort of problem.

class Observable {
  constructor() {
    this.promiseQueue = [];

    // Holds the resolver for the next promise in the queue
    this.resolve = null;

    // Pushes the initial promise on the queue which will
    // resolve with the first observed event
    this.enqueue();
  }

  // Create a new promise, save its resolve method, and
  // store it on the queue
  enqueue() {
    this.promiseQueue.push(
      new Promise((resolve) => this.resolve = resolve));
  }

  // Remove the promise at the front of the queue and
  // return it
  dequeue() {
    return this.promiseQueue.shift();
  }
}

To make use of this promise queue, define an asynchronous generator method on this class. This generator should work for any event type:

class Observable {
  constructor() {
    this.promiseQueue = [];

    // Holds the resolver for the next promise in the queue
    this.resolve = null;

    // Pushes the initial promise on the queue which will
    // resolve with the first observed event
    this.enqueue();
  }

  // Create a new promise, save its resolve method, and
  // store it on the queue
  enqueue() {
    this.promiseQueue.push(
      new Promise((resolve) => this.resolve = resolve));
  }

  // Remove the promise at the front of the queue and
  // return it
  dequeue() {
    return this.promiseQueue.shift();
  }

  async *fromEvent (element, eventType) {
    // Whenever an event is generated, resolve the promise
    // at the front of the queue with the event object and
    // enqueue another promise.
    element.addEventListener(eventType, (event) => {
      this.resolve(event);
      this.enqueue();
    });

    // Each resolved promise at the front of the queue will
    // yield the event object to the async iterator
    while (1) {
      yield await this.dequeue();
    }
  }
}

With this fully defined class, it is now trivial to define an observable on DOM elements. Suppose the page has a <button> inside it; you could capture a stream of click events on this button and log each of them to the console as follows:

class Observable {
  constructor() {
    this.promiseQueue = [];

    // Holds the resolver for the next promise in the queue
    this.resolve = null;

    // Pushes the initial promise on the queue which will
    // resolve with the first observed event
    this.enqueue();
  }

  // Create a new promise, save its resolve method, and
  // store it on the queue
  enqueue() {
    this.promiseQueue.push(
      new Promise((resolve) => this.resolve = resolve));
  }

  // Remove the promise at the front of the queue and
  // return it
  dequeue() {
    return this.promiseQueue.shift();
  }

  async *fromEvent (element, eventType) {
    // Whenever an event is generated, resolve the promise
    // at the front of the queue with the event object and
    // enqueue another promise.
    element.addEventListener(eventType, (event) => {
      this.resolve(event);
      this.enqueue();
    });

    // Each resolved promise at the front of the queue will
    // yield the event object to the async iterator
    while (1) {
      yield await this.dequeue();
    }
  }
}


(async function() {
  const observable = new Observable();

  const button = document.querySelector('button');
  const mouseClickIterator = observable.fromEvent(button, 'click');

  for await (const clickEvent of mouseClickIterator) {
    console.log(clickEvent);
  }
})();

SUMMARY

Iteration is a pattern that is encountered in essentially every programming language. The ECMAScript specification formally embraces the concept of iteration by introducing two formal concepts in the language, iterators and generators.

An iterator is an interface that can be implemented by any object and allows for successive visitation of values that it produces. Anything that implements the Iterable interface features a Symbol.iterator property, which references the default iterator. The default iterator behaves as an iterator factory: a function which, when invoked, produces an object that implements the Iterator interface.

Successive values are coerced from an iterator via its next() method, which returns an IteratorObject. This object contains a done property, a Boolean indicating if there are more values available, and a value property, which contains the present value provided from the iterator. This interface can be manually consumed by invoking next() repeatedly, or automatically consumed by native iterable consumers such as the for...of loop.

Generators are a special type of function that, when invoked, produces a generator object. This generator object implements the Iterable interface, and therefore can be used anywhere an iterable is expected. Generators are unique in that they support the yield keyword, which is used to pause execution of the generator function. The yield keyword can also be used to accept input and output through the next() method. When accompanied by an asterisk, the yield keyword will serve to serialize an iterable it is paired with.

Async iteration allows you to write JavaScript that can use iterator and async concepts simultaneously. Like synchronous iteration, anything that implements the Iterable interface features a Symbol.asyncIterator property, which references the default async iterator. Constructs such as the for-await-of loop are capable of iterating and serializing asynchronous operations that may not resolve in their order of iteration but will nevertheless be iterated in that order all the same. This is especially useful when dealing with sequential network requests.

8
Objects, Classes, and Object-Oriented Programming

ECMA-262 defines an object as an unordered collection of properties. Strictly speaking, this means that an object is an array of values in no particular order. Each property or method is identified by a name that is mapped to a value. For this reason (and others yet to be discussed), it helps to think of ECMAScript objects as hash tables: nothing more than a grouping of name-value pairs where the value may be data or a function.

UNDERSTANDING OBJECTS

The canonical way of creating a custom object is to create a new instance of Object and add properties and methods to it, as in this example:

let person = new Object();
person.name = "Alice";
person.age = 29;
person.job = "Software Engineer";
 
person.sayName = function() {
  console.log(this.name);
};

This example creates an object called person that has three properties (name, age, and job) and one method (sayName()). The sayName() method displays the value of this.name, which resolves to person.name. Early JavaScript developers used this pattern frequently to create new objects. A few years later, object literals became the preferred pattern for creating such objects. The previous example can be rewritten using object literal notation as follows:

let person = {
  name: "Alice",
  age: 29,
  job: "Software Engineer",
  sayName() {
    console.log(this.name);
  }
};

The person object in this example is equivalent to the person object in the prior example, with all the same properties and methods. These properties are all created with certain characteristics that define their behavior in JavaScript.

Types of Properties

ECMA-262 describes characteristics of properties using internal-only attributes. These attributes are defined in the ECMAScript specification and implemented in JavaScript engines, but they are not directly accessible in JavaScript. To indicate that an attribute is internal, surround the attribute name with two pairs of square brackets, such as [[Enumerable]].

There are two types of properties: data properties and accessor properties.

Data Properties

Data properties contain a single location for a data value. Values are read from and written to this location. Data properties have four attributes describing their behavior:

[[Configurable]]—Indicates if the property may be redefined by removing the property via delete, changing the property's attributes, or changing the property into an accessor property. By default, this is true for all properties defined directly on an object, as in the previous example.
[[Enumerable]]—Indicates if the property will be returned in a for-in loop. By default, this is true for all properties defined directly on an object, as in the previous example.
[[Writable]]—Indicates if the property's value can be changed. By default, this is true for all properties defined directly on an object, as in the previous example.
[[Value]]—Contains the actual data value for the property. This is the location from which the property's value is read and the location to which new values are saved. The default value for this attribute is undefined.

When a property is explicitly added to an object as in the previous examples, [[Configurable]], [[Enumerable]], and [[Writable]] are all set to true while the [[Value]] attribute is set to the assigned value. For example:

let person = {
  name: "Alice"
};

Here, the property called name is created and a value of "Alice" is assigned. That means [[Value]] is set to "Alice", and any changes to that value are stored in this location.

To change any of the default property attributes, you must use the Object.defineProperty() method. This method accepts three arguments: the object on which the property should be added or modified, the name of the property, and a descriptor object. The properties on the descriptor object match the attribute names: configurable, enumerable, writable, and value. You can use any number of these values to change the corresponding attribute values. For example:

let person = {};
Object.defineProperty(person, "name", {
  writable: false,
  value: "Alice"
});
console.log(person.name);  // "Alice"
person.name = "Greg";
console.log(person.name);  // "Alice"

This example creates a property called name with a value of "Alice" that is read-only. The value of this property can't be changed, and any attempts to assign a new value are ignored in nonstrict mode. In strict mode, an error is thrown when an attempt is made to change the value of a read-only property.

Similar rules apply to creating a nonconfigurable property. For example:

let person = {};
Object.defineProperty(person, "name", {
  configurable: false,
  value: "Alice"
});
console.log(person.name);  // "Alice"
delete person.name;
console.log(person.name);  // "Alice"

Here, setting configurable to false means that the property cannot be removed from the object. Calling delete on the property has no effect in nonstrict mode and throws an error in strict mode. Additionally, once a property has been defined as nonconfigurable, it cannot become configurable again. Any attempt to call Object.defineProperty() and change any attribute other than writable causes an error:

let person = {};
Object.defineProperty(person, "name", {
  configurable: false,
  value: "Alice"
});
 
// Throws an error
Object.defineProperty(person, "name", {
  configurable: true,
  value: "Alice"
});

Although you can call Object.defineProperty() multiple times for the same property, there are limits once configurable has been set to false.

When you are using Object.defineProperty(), the values for configurable, enumerable, and writable default to false unless otherwise specified. In most cases, you likely won't need the powerful options provided by Object.defineProperty(), but it's important to understand the concepts to have a good understanding of JavaScript objects.

Accessor Properties

Accessor properties do not contain a data value. Instead, they contain a combination of a getter function and a setter function (though both are not necessary). When an accessor property is read, the getter function is called, and it's the function's responsibility to return a valid value; when an accessor property is written, a function is called with the new value, and that function must decide how to react to the data. Accessor properties have four attributes:

[[Configurable]]—Indicates if the property may be redefined by removing the property via delete, changing the property's attributes, or changing the property into a data property. By default, this is true for all properties defined directly on an object.
[[Enumerable]]—Indicates if the property will be returned in a for-in loop. By default, this is true for all properties defined directly on an object.
[[Get]]—The function to call when the property is read from. The default value is undefined.
[[Set]]—The function to call when the property is written to. The default value is undefined.

It is not possible to define an accessor property explicitly; you must use Object.defineProperty(). Here's a simple example:

// Define object with pseudo-private member 'year_'
// and public member 'edition'
let book = {
  year_: 2023,
  edition: 1
};
 
Object.defineProperty(book, "year", {
  get() {
    return this.year_;
  },
  set(newValue) {
    if (newValue> 2023) {
      this.year_ = newValue;
      this.edition += newValue - 2023;
    }
  }
});
book.year = 2024;
console.log(book.edition);  // 2

In this code, an object book is created with two default properties: year_ and edition. The underscore on year_ is a common notation to indicate that a property is not intended to be accessed from outside of the object's methods. The year property is defined to be an accessor property where the getter function simply returns the value of year_ and the setter does some calculation to determine the correct edition. So changing the year property to 2024 results in both year_ and edition changing to 2. This is a typical use case for accessor properties, when setting a property value results in some other changes to occur.

It's not necessary to assign both a getter and a setter. Assigning just a getter means that the property cannot be written to and attempts to do so will be ignored. In strict mode, trying to write to a property with only a getter throws an error. Likewise, a property with only a setter cannot be read and will return the value undefined in nonstrict mode, while doing so throws an error in strict mode.

There is no way to modify [[Configurable]] or [[Enumerable]] in browsers that don't support Object.defineProperty().

Accessing Object Properties

To read an object property, you can use the dot notation or square bracket notation. The dot notation is the most common and straightforward approach. It involves specifying the object followed by a dot (.) and then the property name:

const person = {
  name: "Alice",
  age: 30
};
 
console.log(person.name);  // Alice
console.log(person.age);   // 30

Alternatively, you can use square brackets and pass the property name as a string:

console.log(person["name"]);  // Alice
console.log(person["age"]);   // 30

Both approaches yield the same result, but the square bracket notation is useful when the property name needs to be dynamically determined or when it contains special characters or spaces. However, note that static code analysis tools may not always be able to identify that person.name and person["name"] are the same, so I prefer to use the dot notation wherever possible.

Chaining Properties

Nesting objects inside other objects is common practice in JavaScript. From a parent object, accessing child object properties is as simple as recursively using a property access pattern called property chaining. Consider the following example:

const person = {
  name: "Alice",
  address: {
    city: "Chicago",
    street: "1060 W Addison St"
  }
};
 
console.log(person.address.city);        // Chicago
console.log(person.address.postalCode);  // undefined
 
console.log(person.address.postalCode.length); 
// TypeError: Cannot read property 'length' of undefined

In this example, we can safely access properties of the child address object via chained property access operations. This is equivalent to doing the following:

const person = { ... };
const address = person.address;
console.log(address.city);  // Chicago

Chaining property access is fine in situations where the nested object structure is well-defined, but this starts to fall apart where an intermediate object does not exist, as shown in the final line of the example, where a TypeError is thrown. To prevent this, you would need to check the existence of every nested object in the chain—something that can be quite tedious:

const person = { ... };
if (person.address) {
  if (person.address.postalCode) {
    console.log(person.address.postalCode.length);
  }
}

To avoid doing this, you can use the optional chaining operator by appending the question mark (?.) to the property or method you want to access that may or may not be defined. It short-circuits the evaluation and returns undefined if that portion of the chain is undefined or null:

console.log(person.address?.postalCode?.length);       // undefined
 
// Once the optional chaining short-circuits, it will not evaluate
// anything to the right of the operator
console.log(person.address?.postalCode?.foo.bar.baz);  // undefined

Importantly, that operator will only short-circuit the chain for that specific property:

console.log(person.address.postalCode?.length); 
// undefined
 
console.log(person.address?.postalCode.length); 
// TypeError: Cannot read property 'length' of undefined

Object Static Methods

The Object class includes a hefty number of static methods used for inspecting and manipulating objects. Since all non-primitives in JavaScript inherit from Object, these can be used on any object. The following table lists each available method with a brief description of its behavior:

KEY-VALUE	DESCRIPTION
`Object.assign()`	Copies the values of all enumerable properties from one or more source objects to a target object.
`Object.create()`	Creates a new object with the specified prototype object and properties.
`Object.defineProperties()`	Defines new or modifies existing properties of an object, with descriptors for each property.
`Object.defineProperty()`	Defines a new property or modifies an existing property of an object, with a descriptor for the property.
`Object.entries()`	Returns an array of a given object's own enumerable string-keyed property [key-value] pairs.
`Object.freeze()`	Freezes an object, preventing new properties from being added to it and existing properties from being modified or removed.
`Object.fromEntries()`	Returns a new object from an iterable (such as an array or map) of key-value pairs.
`Object.getOwnPropertyDescriptor()`	Returns an object describing the configuration of a specific property on an object.
`Object.getOwnPropertyDescriptors()`	Returns an object containing all own property descriptors of an object.
`Object.getOwnPropertyNames()`	Returns an array of all property names (including non-enumerable properties) found directly on an object.
`Object.getOwnPropertySymbols()`	Returns an array of all symbol properties (including non-enumerable properties) found directly on an object.
`Object.getPrototypeOf()`	Returns the prototype (i.e., the internal `[[Prototype]]` property) of the specified object.
`Object.hasOwn()`	Determines if the specified object has the indicated property as its own property.
`Object.is()`	Determines whether two values are the same value, considering edge cases like `NaN` and -0.
`Object.isExtensible()`	Determines if an object is extensible, i.e., if new properties can be added to it.
`Object.isFrozen()`	Determines if an object is frozen, i.e., if it is not extensible and all its properties are non-configurable.
`Object.isSealed()`	Determines if an object is sealed, i.e., if it is not extensible and all its properties are non-configurable.
`Object.keys()`	Returns an array of a given object's own enumerable property names.
`Object.preventExtensions()`	Prevents new properties from being added to an object, making it non-extensible.
`Object.seal()`	Seals an object, preventing new properties from being added and existing properties from being deleted or configured.
`Object.setPrototypeOf()`	Sets the prototype (i.e., the internal `[[Prototype]]` property) of a specified object to another object or `null`.
`Object.values()`	Returns an array of a given object's own enumerable property values.

Controlling Object Mutability

Object includes static methods to manipulate and control the mutability of objects. Developers can freeze objects to make them completely immutable, determine if an object can have new properties added, seal objects to prevent addition or deletion of properties while allowing property modification, and more.

Freezing Objects

The Object.freeze() method is primarily used to freeze an object and make it object immutable. The frozen object becomes non-extensible and all its existing properties become non-configurable. Once an object is frozen, new properties cannot be added, existing properties cannot be modified or deleted, and the object's prototype cannot be changed. Any attempt to modify a frozen object or its properties will result in an error or failure. You can detect if an object was frozen with Object.isFrozen().

const person = { 
  name: "Alice", 
  age: 30 
};
 
console.log(Object.isFrozen(person));  // false
Object.freeze(person);
console.log(Object.isFrozen(person));  // true
 
 
person.name = "Bob";
// Ignored in non-strict mode
// Throws error in strict mode

Freezing cannot be undone; it is intended to be a permanent operation.

Sealing Objects

The Object.seal() method provides a way to seal an object, making it non-extensible and marking all its existing properties as non-configurable. Sealing an object prevents the addition and deletion of properties while still allowing the modification of existing property values. Once an object is sealed, new properties cannot be added, but existing properties can be modified. The Object.isSealed() method can be used to determine if an object is sealed.

const person = {
  name: "Alice",
  age: 30
};
 
console.log(Object.isSealed(person));  // false
Object.seal(person);
console.log(Object.isSealed(person));  // true
 
person.name = "Bob";  // Modifying existing property is allowed
person.height = "6 feet";  
// Ignored in non-strict mode
// Error in strict mode
 
delete person.age;  
// Ignored in non-strict mode
// Error in strict mode

Sealing an object does not prevent modifications to existing properties, but it prevents new properties from being added and existing properties from being deleted. It is a less strict form of immutability compared to Object.freeze().

Controlling Extensibility

The Object.preventExtensions() method is used to make an object non-extensible, meaning that new properties cannot be added to it. By default, JavaScript objects are extensible, meaning new properties can be added to them. The Object.isExtensible() method can be used to check if an object is extensible or not.

const person = {
  name: "Alice",
  age: 30
};
 
console.log(Object.isExtensible(person));  // true
Object.preventExtensions(person);
console.log(Object.isExtensible(person));  // false
 
person.name = "Bob";  // Modifying existing property is allowed
person.gender = "Female";  
// Ignored in non-strict mode
// Error in strict mode
 
delete person.age;  
// Ignored in non-strict mode
// Error in strict mode

The Object.preventExtensions() method makes an object non-extensible, preventing the addition of new properties while allowing modifications and deletions to existing properties. It differs from Object.seal() as it does not mark existing properties as non-configurable, thus allowing their modification.

Defining Multiple Properties

To define more than one property on an object at once, ECMAScript provides the Object.defineProperties() method. This method allows you to define multiple properties using descriptors at once. There are two arguments: the object on which to add or modify the properties and an object whose property names correspond to the properties' names to add or modify. For example:

let book = {};
Object.defineProperties(book, {
  year_: {
    value: 2023
  },
 
  edition: {
    value: 1
  },
 
  year: {
    get() {
      return this.year_;
    },
 
    set(newValue) {
      if (newValue> 2023) {
        this.year_ = newValue;
        this.edition += newValue - 2023;
      }
    }
  }
});

This code defines two data properties, year_ and edition, and an accessor property called year on the book object. The resulting object is identical to the example in the previous section.

Reading Property Attributes

It's also possible to retrieve the property descriptor for a given property by using the Object.getOwnPropertyDescriptor() method. This method accepts two arguments: the object on which the property resides and the name of the property whose descriptor should be retrieved. The return value is an object with properties for configurable, enumerable, get, and set for accessor properties or configurable, enumerable, writable, and value for data properties. For example:

let book = {};
Object.defineProperties(book, {
  year_: {
    value: 2023
  },
 
  edition: {
    value: 1
  },
 
  year: {
    get: function() {
      return this.year_;
    },
 
    set: function(newValue){
      if (newValue> 2023) {
        this.year_ = newValue;
        this.edition += newValue - 2023;
      }
    }
  }
});
 
let descriptor = Object.getOwnPropertyDescriptor(book, "year_");
console.log(descriptor.value);         // 2023
console.log(descriptor.configurable);  // false
console.log(typeof descriptor.get);    // "undefined"
let descriptor = Object.getOwnPropertyDescriptor(book, "year");
console.log(descriptor.value);        // undefined
console.log(descriptor.enumerable);   // false
console.log(typeof descriptor.get);   // "function"

For the data property year_, value is equal to the original value, configurable is false, and get is undefined. For the accessor property year, value is undefined, enumerable is false, and get is a pointer to the specified getter function.

The Object.getOwnPropertyDescriptors() static method calls Object.getOwnPropertyDescriptor() for all own properties and returns them in a new object. Own properties refers to the properties that are directly defined on an object, as opposed to properties inherited from its prototype chain.

For the previous example, using this static method would return the following object:

let book = {};
Object.defineProperties(book, {
  year_: {
    value: 2023
  },
 
  edition: {
    value: 1
  },
 
  year: {
    get: function() {
      return this.year_;
    },
 
    set: function(newValue){
      if (newValue> 2023) {
        this.year_ = newValue;
        this.edition += newValue - 2023;
      }
    }
  }
});
 
console.log(Object.getOwnPropertyDescriptors(book));
// {
//   edition: {
//     configurable: false,
//     enumerable: false,
//     value: 1,
//     writable: false
//   },
//   year: {
//     configurable: false,
//     enumerable: false,
//     get: f(),
//     set: f(newValue),
//   },
//   year_: {
//     configurable: false,
//     enumerable: false,
//     value: 2019,
//     writable: false
//   }
// }

Merging Objects

JavaScript developers will often find that it is useful to be able to perform a “merge” of two objects. More specifically, this merge will take the form of folding all the local properties of one source object into a destination object, with the source object's properties taking priority in the event of any property collisions.

The Object.assign() method accepts one destination object, and one or many source objects, and for each source object copies the enumerable (Object.propertyIsEnumerable returns true) and own (Object.hasOwnProperty returns true) properties onto the destination object. Properties keyed with strings and symbols will be copied. For each suitable property, the method will use [[Get]] to retrieve a value from the source object and [[Set]] on the destination object to assign the value.

let dest, src, result;
 
/**
 * Simple copy
 */
dest = {};
src = { id: 'src' };
 
result = Object.assign(dest, src);
 
// Object.assign mutates the destination object
// and also returns that object after exiting.
console.log(dest === result);  // true
console.log(dest !== src);     // true
console.log(result);           // { id: src }
console.log(dest);             // { id: src }
 
 
/**
 * Multiple source objects
 */
dest = {};
 
result = Object.assign(dest, { a: 'foo' }, { b: 'bar' });
 
console.log(result);  // { a: foo, b: bar }
 
 
/**
 * Getters and setters
 */
dest = {
  set a(val) {
    console.log('Invoked dest setter with param ${val}');
  }
};
src = {
  get a() {
    console.log('Invoked src getter');
    return 'foo';
  }
};
 
Object.assign(dest, src);
// Invoked src getter
// Invoked dest setter with param foo
 
// Since the setter does not perform an assignment,
// no value is actually transferred
console.log(dest);  // { set a(val) {...} }

Object.assign() is effectively performing a shallow copy from each source object. If multiple source objects have the same property defined, the last one to be copied will be the ultimate value. Furthermore, any value retrieved from accessor properties, such as a getter, on a source object will be assigned as a static value on the destination object—there is no ability to transfer getters and setters between objects.

let dest, src, result;
 
/**
 * Overwritten properties
 */
dest = { id: 'dest' };
 
result = Object.assign(dest, { id: 'src1', a: 'foo' }, { id: 'src2', b: 'bar' });
 
// Object.assign will overwrite duplicate properties.
console.log(result);  // { id: src2, a: foo, b: bar }
 
// This can be observed by using a setter on the destination object:
dest = {
  set id(x) {
    console.log(x);
  }
};
 
Object.assign(dest, { id: 'first' }, { id: 'second' }, { id: 'third' });
// first
// second
// third
 
 
/**
 * Object references
 */
 
dest = {};
src = { a: {} };
 
Object.assign(dest, src);
 
// Shallow property copies means only object references copied.
console.log(dest);              // { a :{} }
console.log(dest.a === src.a);  // true

If an error is thrown during the assignment, it will discontinue and exit with the thrown error. Object.assign() has no concept of “rolling back” earlier assignments so it is a best-effort method that may only partially complete.

let dest, src, result;
 
/**
 * Error handling
 */
dest = {};
src = {
  a: 'foo',
  get b() {
    // Error will be thrown when Object.assign()
    // invokes this getter.
    throw new Error();
  },
  c: 'bar'
};
 
try {
  Object.assign(dest, src);
} catch(e) {}
 
// Object.assign() has no way of rolling back already performed changes,
// so set operations already performed on the destination object before
// the error is thrown remain:
console.log(dest);  // { a: foo }

Object Identity and Equality

There are several tricky corner cases where the === operator exhibits unexpected behavior:

// These are cases where === behaves as expected:
console.log(true === 1);   // false
console.log({} === {});    // false
console.log("2" === 2);    // false
 
// These have different representations in the JS engine // and yet are treated as equal
console.log(+0 === -0);    // true
console.log(+0 === 0);     // true
console.log(-0 === 0);     // true
 
// To determine NaN equivalence, the profoundly annoying isNaN() is required
console.log(NaN === NaN);  // false
console.log(isNaN(NaN));   // true

To address this, the ECMAScript defines Object.is(), which behaves mostly as === does but also accounts for the corner cases listed previously. The method accepts exactly two arguments:

console.log(Object.is(true, 1));   // false
console.log(Object.is({}, {}));    // false
console.log(Object.is("2", 2));    // false
 
// Correct 0, -0, +0 equivalence/nonequivalence:
console.log(Object.is(+0, -0));    // false
console.log(Object.is(+0, 0));     // true
console.log(Object.is(-0, 0));     // false
 
// Correct NaN equivalence:
console.log(Object.is(NaN, NaN));  // true

To check more than two objects, it is trivial to recursively use transitive equality:

function recursivelyCheckEqual(x, ...rest) {
  return Object.is(x, rest[0]) &&
         (rest.length < 2 || recursivelyCheckEqual(...rest));
}

Enhanced Object Syntax

ECMAScript features a handful of extremely useful syntactical tools for defining and interacting with objects. None of them meaningfully change existing engine behavior, but they enormously enhance the convenience of dealing with objects.

All object syntax conventions introduced in this section are also applicable to ECMAScript classes, defined later in this chapter.

Property Value Shorthand

Developers frequently find that, when adding a variable to an object, the property name used to key that variable often will match the variable name itself. For example:

let name = 'Matt';
 
let person = {
  name: name
};
 
console.log(person);  // { name: 'Matt' }

Thus, the property value shorthand convention was introduced. This allows you to simply use the variable itself without the colon notation, and the interpreter will automatically use the variable name as the property key. If the variable name is not found, a ReferenceError will be thrown.

The following code uses this shorthand:

let name = 'Matt';
 
let person = {
  name
};
 
console.log(person);  // { name: 'Matt' }

Minifiers are intelligent enough to preserve property names between scopes to prevent breaking references. Take the following code snippet for example:

function makePerson(name) {
  return {
    name
  };
}
 
let person = makePerson('Matt');
 
console.log(person.name);  // Matt

Compilers are careful to preserve the initial name string identifier inside the function definition even though the parameter identifier is restricted to the function scope. For example, when this is compiled using the Google Closure compiler, the function parameter name will be shortened, but the property name will remain:

function makePerson(a) {
  return {
    name: a
  };
}
 
var person = makePerson("Matt");
 
console.log(person.name);  // Matt

Computed Property Keys

Prior to the introduction of computed property keys, there was no way to dynamically assign property keys in an object literal without declaring the object and then individually using the square bracket notation for property assignment. For example:

const nameKey = 'name';
const ageKey = 'age';
const jobKey = 'job';
 
let person = {};
person[nameKey] = 'Matt';
person[ageKey] = 27;
person[jobKey] = 'Software engineer';
 
console.log(person);  // { name: 'Matt', age: 27, job: 'Software engineer' }

With computed properties, the property assignment can occur inside the object literal's initial definition. Square brackets around the object property key instruct the runtime to evaluate its contents as a JavaScript expression instead of a string:

const nameKey = 'name';
const ageKey = 'age';
const jobKey = 'job';
 
let person = {
  [nameKey]: 'Matt',
  [ageKey]: 27,
  [jobKey]: 'Software engineer'
};
 
console.log(person);  // { name: 'Matt', age: 27, job: 'Software engineer' }

Because the contents are evaluated as a JavaScript expression, it is possible to make the contents of the computed property complex expressions to be evaluated upon instantiation:

const nameKey = 'name';
const ageKey = 'age';
const jobKey = 'job';
let uniqueToken = 0;
 
function getUniqueKey(key) {
  return '${key}_${uniqueToken++}';
}
 
let person = {
  [getUniqueKey(nameKey)]: 'Matt',
  [getUniqueKey(ageKey)]: 27,
  [getUniqueKey(jobKey)]: 'Software engineer'
};
 
console.log(person);  // { name_0: 'Matt', age_1: 27, job_2: 'Software engineer' }

Concise Method Syntax

When defining function properties of an object, the format almost always takes the form of a property key referencing an anonymous function expression, as follows:

let person = {
  sayName: function(name) {
    console.log('My name is ${name}');
  }
};
 
person.sayName('Matt');  // My name is Matt

The new shorthand method syntax follows this pattern and allows the developer to give up the capability to name the function expression—which, most of the time, is not useful anyway—and in exchange dramatically shorten how a function property can be expressed.

The following code uses this shorthand syntax:

let person = {
  sayName(name) {
    console.log('My name is ${name}');
  }
};
 
person.sayName('Matt');  // My name is Matt

This is also applicable to the getter and setter object conventions:

let person = {
  name_: '',
  get name() {
    return this.name_;
  },
  set name(name) {
    this.name_ = name;
  },
  sayName() {
    console.log('My name is ${this.name_}');
  }
};
 
person.name = 'Matt';
person.sayName();  // My name is Matt

Shorthand method syntax and computed property keys can be used together:

const methodKey = 'sayName';
 
let person = {
  [methodKey](name) {
    console.log('My name is ${name}');
  }
}
 
person.sayName('Matt');  // My name is Matt

Object Destructuring

Object destructuring allows you to perform one or many operations using nested data within a single statement. With respect to objects, this gives you the ability to perform assignments from object properties using syntax that matches the structure of an object.

The following is an example of two equivalent code snippets, first without object destructuring:

// Without object destructuring
let person = {
  name: 'Matt',
  age: 27
};
 
let personName = person.name,
    personAge = person.age;
 
console.log(personName);  // Matt
console.log(personAge);   // 27

Second, with object destructuring:

// With object destructuring
let person = {
  name: 'Matt',
  age: 27
};
 
let { name: personName, age: personAge } = person;
 
console.log(personName);  // Matt
console.log(personAge);   // 27

Destructuring allows you to declare multiple variables and simultaneously perform multiple assignments all at once. If you want to reuse the property name as a local variable name, you can use a shorthand syntax, as follows:

let person = {
  name: 'Matt',
  age: 27
};
 
let { name, age } = person;
 
console.log(name);  // Matt
console.log(age);   // 27

Destructuring assignments do not have to match what is inside the object. You can ignore properties when performing an assignment; conversely, if you reference a property that does not exist, undefined will be assigned:

let person = {
  name: 'Matt',
  age: 27
};
 
let { name, job } = person;
 
console.log(name);  // Matt
console.log(job);   // undefined

It is also possible to define default values, which will be applied if a property does not exist in the source object:

let person = {
  name: 'Matt',
  age: 27
};
 
let { name, job='Software engineer' } = person;
 
console.log(name);  // Matt
console.log(job);   // Software engineer

Destructuring uses the internal function ToObject() (which is not directly accessible in the runtime) to coerce a source into an object. This means that primitive values will be treated as objects when used in a destructuring operation; this also means that null and undefined cannot be destructured and will throw an error.

let { length } = 'foobar';
console.log(length);        // 6
 
let { constructor: c } = 4;
console.log(c === Number);  // true
 
let { _ } = null;           // TypeError
 
let { _ } = undefined;      // TypeError

Destructuring does not demand that variable declarations occur inside the destructuring expression. However, doing so requires the assignment expression to be contained inside parentheses:

let personName, personAge;
 
let person = {
  name: 'Matt',
  age: 27
};
 
({name: personName, age: personAge} = person);
 
console.log(personName, personAge);  // Matt, 27

Nested Destructuring

There are no restrictions on referencing nested properties or assignment targets. This allows you to do things like perform copies of object properties:

let person = {
  name: 'Matt',
  age: 27,
  job: {
    title: 'Software engineer'
  }
};
let personCopy = {};
 
 
({
  name: personCopy.name,
  age: personCopy.age,
  job: personCopy.job
} = person);
 
// Because an object reference was assigned into personCopy, changing a property
// inside the person.job object will be propagated to personCopy:
person.job.title = 'Hacker'
 
console.log(person);
// { name: 'Matt', age: 27, job: { title: 'Hacker' } }
 
console.log(personCopy);
// { name: 'Matt', age: 27, job: { title: 'Hacker' } }

Destructuring assignments can be nested to match nested property references:

let person = {
  name: 'Matt',
  age: 27,
  job: {
    title: 'Software engineer'
  }
};
 
// Declares 'title' variable and assigns person.job.title as its value
let { job: { title }} = person;
 
console.log(title);  // Software engineer

You cannot use nested property references when an outer property is undefined. This is true for both source objects and destination objects:

let person = {
  job: {
    title: 'Software engineer'
  }
};
let personCopy = {};
 
// 'foo' is undefined on the source object
({
  foo: {
    bar: personCopy.bar
  }
} = person);
// TypeError: Cannot destructure property 'bar' of 'undefined' or 'null'.
 
// 'job' is undefined on the destination object
({
  job: {
    title: personCopy.job.title
  }
} = person);
// TypeError: Cannot set property 'title' of undefined

Partial Destructuring Completion

It's important to note that a destructured assignment involving multiple properties is a sequential operation with independent outcomes. If, within a single destructured expression with multiple assignments, the initial assignments succeed but a later one throws an error, the destructured assignment will exit having only partially completed:

let person = {
  name: 'Matt',
  age: 27
};
 
let personName, personBar, personAge;
 
try {
  // person.foo is undefined, so this will throw an error
  ({name: personName, foo: { bar: personBar }, age: personAge} = person);
} catch(e) {}
 
console.log(personName, personBar, personAge);
// Matt, undefined, undefined

Parameter Context Matching

It is also possible to perform a destructured assignment inside a function parameter list. It does not affect the arguments object, but it allows you to declare variables inside the function signature that are immediately available inside the function body:

let person = {
  name: 'Matt',
  age: 27
};
 
function printPerson(foo, {name, age}, bar) {
  console.log(arguments);
  console.log(name, age);
}
 
function printPerson2(foo, {name: personName, age: personAge}, bar) {
  console.log(arguments);
  console.log(personName, personAge);
}
 
printPerson('1st', person, '2nd');
// ['1st', { name: 'Matt', age: 27 }, '2nd']
// 'Matt', 27
 
printPerson2('1st', person, '2nd');
// ['1st', { name: 'Matt', age: 27 }, '2nd']
// 'Matt', 27

Rest Operator

When restructuring an object, you can use the rest operator to collect all remaining unspecified enumerable properties into a single object. This can be done as follows:

const person = { name: 'Matt', age: 27, job: 'Engineer' };
const { name, ...remainingData } = person;
 
console.log(name);  // Matt
console.log(remainingData);  // { age: 27, job: 'Engineer' }

The rest operator can be used at most once per object literal and must be listed last. Because there can be only a single rest operator per object literal, it is possible to nest the rest operators. When nesting, because there is no ambiguity about which elements of the property subtree are allocated to any given rest operator, the resulting objects will never overlap with respect to their contents:

const person = { name: 'Matt', age: 27, job: { title: 'Engineer', level: 10 } };
 
const { name, job: { title, ...remainingJobData }, ...remainingPersonData } = person;
 
console.log(name);                 // Matt
console.log(title);                // Engineer
console.log(remainingPersonData);  // { age: 27 }
console.log(remainingJobData);     // { level: 10 }
 
const { ...a, job } = person;
// SyntaxError: Rest element must be last element

The rest operator performs a shallow copy between objects, so object references will be copied instead of creating entire object clones:

const person = { name: 'Matt', age: 27, job: { title: 'Engineer', level: 10 } };
 
const { ...remainingData } = person;
 
console.log(person === remainingData);          // false
console.log(person.job === remainingData.job);  // true

The rest operator will copy all enumerable own properties, including symbols:

const s = Symbol();
const foo = { a: 1, [s]: 2, b: 3 }
 
const {a, ...remainingData} = foo;
 
console.log(remainingData);
// { b: 3, Symbol(): 2 }

Spread Operator

The spread operator allows you to join two objects together in a fashion similar to array concatenation. The spread operator applied to an inner object will perform a shallow copy of all enumerable own properties, including symbols, into the outer object:

const s = Symbol();
const foo = { a: 1 };
const bar = { [s]: 2 };
 
const foobar = {...foo, c: 3, ...bar};
 
console.log(foobar);
// { a: 1, c: 3 Symbol(): 2 }

The order in which the spread objects are listed matters for two reasons:

Objects track insertion order. The properties copied from spread objects will be performed in the order they are listed inside the object literal.
Objects will overwrite properties as duplicates are encountered. The last property encountered will be the one that assumes the value.

These ordering conventions are demonstrated here:

const foo = { a: 1 };
const bar = { b: 2 };
 
const foobar = {c: 3, ...bar, ...foo};
 
console.log(foobar);
// { c: 3, b: 2, a: 1}
 
const baz = { c: 4 };
 
const foobarbaz = {...foo, ...bar, c: 3, ...baz };
 
console.log(foobarbaz);
// { a: 1, b: 2, c: 4 }

As with the rest operator, all copies performed are shallow:

const foo = { a: 1 };
const bar = { b: 2, c: { d: 3 } };
 
const foobar = {...foo, ...bar};
 
console.log(foobar.c === bar.c);  // true

OBJECT CREATION

Although using the Object constructor or an object literal are convenient ways to create single objects, there is an obvious downside: creating multiple objects with the same interface requires a lot of code duplication.

Overview

Through successive specifications, the available features of ECMAScript followed a highly unusual pattern. Through the ECMAScript 5.1 specification, there was no formal support for object-oriented constructs such as classes or inheritance. However, as you will see in the following sections, clever application of prototypal inheritance allowed JavaScript developers to emulate this behavior—quite successfully.

With the ECMAScript 6 specification, formal support for classes and inheritance was introduced. These ECMAScript classes are intended to completely subsume the prototype-based class solutions designed in previous specifications. However, their implementation is, in many ways, merely a syntactical abstraction for ES5.1-style constructor functions and prototypal inheritance.

The Function Constructor Pattern

As mentioned in previous chapters, constructors in ECMAScript are used to create specific types of objects. There are native constructors, such as Object and Array, which are available automatically in the execution environment at runtime. It is also possible to define custom constructors, in the form of a function, that define properties and methods for your own type of object.

Consider the following example that uses the function constructor pattern:

function Person(name, age, job){
  this.name = name;
  this.age = age;
  this.job = job;
  this.sayName = function() {
    console.log(this.name);
  };
}
 
let person1 = new Person("Alice", 29, "Software Engineer");
let person2 = new Person("Greg", 27, "Doctor");
 
person1.sayName();  // Alice
person2.sayName();  // Greg

Note that:

There is no object being created explicitly.
The properties and method are assigned directly onto the this object.
There is no return statement.

Also note the name of the function is Person with an uppercase P. By convention, constructor functions always begin with an uppercase letter, whereas nonconstructor functions begin with a lowercase letter. This convention is borrowed from other object-oriented languages and helps to distinguish function use in ECMAScript because constructors are simply functions that create objects.

To create a new instance of Person, use the new operator. Calling a constructor in this manner will do the following:

A new object is created in memory.
The new object's internal [[Prototype]] pointer is assigned to the constructor's prototype property.
The this value of the constructor is assigned to the new object (so this points to the new object).
The code inside the constructor is executed (adds properties to the new object).
If the constructor function returns a non-null value, that object is returned. Otherwise, the new object that was just created is returned.

At the end of the preceding example, person1 and person2 are each filled with a different instance of Person. Each of these objects has a constructor property that points back to Person, as follows:

console.log(person1.constructor == Person);  // true
console.log(person2.constructor == Person);  // true

The constructor property was originally intended for use in identifying the object type. However, the instanceof operator is a safer way of determining type. Each of the objects in this example is both an instance of Object and an instance of Person, as indicated by using the instanceof operator like this:

console.log(person1 instanceof Object);  // true
console.log(person1 instanceof Person);  // true
console.log(person2 instanceof Object);  // true
console.log(person2 instanceof Person);  // true

Defining your own constructors ensures that instances can be identified as a particular. In this example, person1 and person2 are considered to be instances of Object because all custom objects inherit from Object (the specifics of this are discussed later).

Constructor functions do not have to be expressed as a function declaration. A function expression assigned to a variable behaves identically:

let Person = function(name, age, job) {
  this.name = name;
  this.age = age;
  this.job = job;
  this.sayName = function() {
    console.log(this.name);
  };
};
 
let person1 = new Person("Alice", 29, "Software Engineer");
let person2 = new Person("Greg", 27, "Doctor");
 
person1.sayName();  // Alice
person2.sayName();  // Greg
 
console.log(person1 instanceof Object);  // true
console.log(person1 instanceof Person);  // true
console.log(person2 instanceof Object);  // true
console.log(person2 instanceof Person);  // true

When instantiating, the parentheses after the constructor function are optional if you do not wish to pass any arguments—the new operator will invoke the constructor function no matter what:

function Person() {
  this.name = "Jake";
  this.sayName = function() {
    console.log(this.name);
  };
}
 
let person1 = new Person();
let person2 = new Person;
 
person1.sayName();  // Jake
person2.sayName();  // Jake
 
console.log(person1 instanceof Object);  // true
console.log(person1 instanceof Person);  // true
console.log(person2 instanceof Object);  // true
console.log(person2 instanceof Person);  // true

Constructors as Functions

The only difference between constructor functions and other functions is the way in which they are called. Constructors are, after all, just functions; there's no special syntax to define a constructor that automatically makes it behave as such. Any function that is called with the new operator acts as a constructor, whereas any function called without it acts just as you would expect a normal function call to act. For instance, the Person() function from the previous example may be called in any of the following ways:

// use as a constructor
let person = new Person("Alice", 29, "Software Engineer");
person.sayName();   // "Alice"
 
// call as a function
Person("Greg", 27, "Doctor");  // adds to window
window.sayName();   // "Greg"
 
// call in the scope of another object
let o = new Object();
Person.call(o, "Kristen", 25, "Nurse");
o.sayName();  // "Kristen"

The first part of this example shows the typical use of a constructor—to create a new object via the new operator. The second part shows what happens when the Person() function is called without the new operator: The properties and methods get added to the window object. Remember that the this object always points to the Global object (window in web browsers) when a function is called without an explicitly set this value (by being an object method or through call()/apply()). After the function is called, the sayName() method can be called on the window object, and it will return "Greg". The Person() function can also be called within the scope of a particular object using call() (or apply()). In this case, it's called with a this value of the object o, which then gets assigned all of the properties and the sayName() method.

Problems with Constructors

Though the constructor paradigm is useful, it is not without its faults. The major downside to constructors is that methods are created once for each instance. So, in the previous example, both person1 and person2 have a method called sayName(), but those methods are not the same instance of Function. Remember that all functions are objects in ECMAScript, so every time a function is defined, it's an object being instantiated. Logically, the constructor might look like this:

function Person(name, age, job){
  this.name = name;
  this.age = age;
  this.job = job;
  this.sayName = new Function("console.log(this.name)");  // logical equivalent
}

Thinking about the constructor in this manner makes it clear that each instance of Person gets its own instance of Function that happens to display the name property. To be clear, creating a function in this manner is different with regard to scope chains and identifier resolution, but the mechanics of creating a new instance of Function remain the same. So, functions of the same name on different instances are not equivalent, as the following code proves:

console.log(person1.sayName == person2.sayName);  // false

It doesn't make sense to have two instances of Function that do the same thing, especially when the this object makes it possible to avoid binding functions to particular objects until runtime.

It's possible to work around this limitation by moving the function definition outside of the constructor, as follows:

function Person(name, age, job){
  this.name = name;
  this.age = age;
  this.job = job;
  this.sayName = sayName;
}
 
function sayName() {
  console.log(this.name);
}
 
let person1 = new Person("Alice", 29, "Software Engineer");
let person2 = new Person("Greg", 27, "Doctor");
 
person1.sayName();  // Alice
person2.sayName();  // Greg

In this example, the sayName() function is defined outside the constructor. Inside the constructor, the sayName property is set equal to the global sayName() function. Because the sayName property now contains just a pointer to a function, both person1 and person2 end up sharing the sayName() function that is defined in the global scope. This solves the problem of having duplicate functions that do the same thing but also creates some clutter in the global scope by introducing a function that can realistically be used only in relation to an object. If the object needed multiple methods, that would mean multiple global functions, and all of a sudden the custom reference type definition is no longer nicely grouped in the code. These problems are addressed by using the prototype pattern.

The Prototype Pattern

Each function is created with a prototype property, which is an object containing properties and methods that should be available to instances of a particular reference type. This object is literally a prototype for the object to be created once the constructor is called. The benefit of using the prototype is that all of its properties and methods are shared among object instances. Instead of assigning object information in the constructor, they can be assigned directly to the prototype, as in this example:

function Person() {}
 
Person.prototype.name = "Alice";
Person.prototype.age = 29;
Person.prototype.job = "Software Engineer";
Person.prototype.sayName = function() {
  console.log(this.name);
};
 
let person1 = new Person();
person1.sayName();   // "Alice"
 
let person2 = new Person();
person2.sayName();   // "Alice"
 
console.log(person1.sayName == person2.sayName);  // true

Using a function expression is also suitable:

let Person = function() {};
 
Person.prototype.name = "Alice";
Person.prototype.age = 29;
Person.prototype.job = "Software Engineer";
Person.prototype.sayName = function() {
  console.log(this.name);
};
 
let person1 = new Person();
person1.sayName();   // "Alice"
 
let person2 = new Person();
person2.sayName();   // "Alice"
 
console.log(person1.sayName == person2.sayName);  // true

Here, the properties and the sayName() method are added directly to the prototype property of Person, leaving the constructor empty. However, it's still possible to call the constructor to create a new object and have the properties and methods present. Unlike the constructor pattern, the properties and methods are all shared among instances, so person1 and person2 are both accessing the same set of properties and the same sayName() function. To understand how this works, you must understand the nature of prototypes in ECMAScript.

How Prototypes Work

Whenever a function is created, its prototype property is also created according to a specific set of rules. By default, all prototypes automatically get a property called constructor that points back to the function on which it is a property. In the previous example, for instance, Person.prototype.constructor points back to Person. Then, depending on the constructor, other properties and methods may be added to the prototype.

When defining a custom constructor, the prototype gets the constructor property only by default; all other methods are inherited from Object. Each time the constructor is called to create a new instance, that instance has an internal pointer to the constructor's prototype. In ECMA-262, this is called [[Prototype]]. There is no standardized way to access [[Prototype]] from script, but modern browsers support a property on every object called __proto__. The important thing to understand is that a direct link exists between the instance and the constructor's prototype, but not between the instance and the constructor.

This relationship can be difficult to visualize, so refer to the following table of code snippets demonstrating the various relationships between constructors, prototypes, and instances.

CONCEPT	EXAMPLE SNIPPET
`constructor` function declaration and function expression	`function Person() {}` `let Person = function() {}`
Constructor function's `prototype` object	`console.log(typeof Person.prototype);` `console.log(Person.prototype);` `// {` `// constructor: f Person(),` `// __proto__: Object` `// }`
Cyclical references between `constructor` function and `prototype` object	`console.log(Person.prototype.constructor === Person);` `// true`
Prototype chain termination at the `Object` prototype	`console.log(Person.prototype.__proto__ === Object.prototype);` `// true` `console.log(Person.prototype.__proto__.constructor === Object);` `// true` `console.log(Person.prototype.__proto__.__proto__ === null);` `// true` `console.log(Person.prototype.__proto__);` `// {` `// constructor: f Object(),` `// toString: ...` `// hasOwnProperty: ...` `// isPrototypeOf: ...` `// ...` `// }`
Creating instances of the `constructor` function	`let person1 = new Person(),` `person2 = new Person();`
Distinct objects in constructor, `prototype` object, and instance	`console.log(person1 !== Person);` `// true` `console.log(person1 !== Person.prototype);` `// true` `console.log(Person.prototype !== Person);` `// true`
Instance, `constructor`, and `prototype` relationships	`Console.log(person1.__proto__ === Person.prototype);` `// true` `conosle.log(person1.__proto__.constructor === Person);` `// true`
Instances sharing the same `prototype`	`console.log(person1.__proto__ === person2.__proto__);` `// true`
`instanceof` operator usage	`console.log(person1 instanceof Person);` `// true` `console.log(person1 instanceof Object);` `// true` `console.log(Person.prototype instanceof Object);` `// true`

Consider the original example using the Person constructor and Person.prototype. The relationship between the objects in the example is shown in Figure 8.1.

An illustration of the relationship between constructor, prototype, and instances. — **FIGURE 8.1**: Diagram showing the relationship between `constructor`, `prototype`, and instances

Figure 8.1 shows the relationship between the Person constructor, the Person prototype, and the two instances of Person that exist. Note that Person.prototype points to the prototype object, but Person.prototype.constructor points back to Person. The prototype contains the constructor property and the other properties that were added. Each instance of Person, person1, and person2 has internal properties that point back to Person.prototype only; each has no direct relationship with the constructor. Also note that even though neither of these instances have properties or methods, person1.sayName() works. This is due to the lookup procedure for object properties.

Even though [[Prototype]] is not accessible in all implementations, the isPrototypeOf() method can be used to determine if this relationship exists between objects. Essentially, isPrototypeOf() returns true if [[Prototype]] points to the prototype on which the method is being called, as shown here:

console.log(Person.prototype.isPrototypeOf(person1));  // true
console.log(Person.prototype.isPrototypeOf(person2));  // true

In this code, the prototype.isPrototypeOf() method is called on both person1 and person2. Because both instances have a link to Person.prototype, it returns true.

The ECMAScript Object type has a method called Object.getPrototypeOf(), which returns the value of [[Prototype]]. For example:

console.log(Object.getPrototypeOf(person1) == Person.prototype);  // true
console.log(Object.getPrototypeOf(person1).name);                 // "Alice"

The first line of this code simply confirms that the object returned from Object.getPrototypeOf() is actually the prototype of the object. The second line retrieves the value of the name property on the prototype, which is "Alice". Using Object.getPrototypeOf(), you can retrieve an object's prototype easily, which becomes important once you want to implement inheritance using the prototype (discussed later in this chapter).

The Object type also features a setPrototypeOf() method, which writes a new value into the [[Prototype]] of the instance. This allows you to overwrite the prototype hierarchy of an already-instantiated object:

let biped = {
  numLegs: 2
};
let person = {
  name: 'Matt'
};
 
Object.setPrototypeOf(person, biped);
 
console.log(person.name);                              // Matt
console.log(person.numLegs);                           // 2
console.log(Object.getPrototypeOf(person) === biped);  // true

To avoid these slowdowns, prefer to just create a new object and specify its prototype with Object.create():

let biped = {
  numLegs: 2
};
let person = Object.create(biped);
person.name = 'Matt';
 
console.log(person.name);                              // Matt
console.log(person.numLegs);                           // 2
console.log(Object.getPrototypeOf(person) === biped);  // true

Understanding the Prototype Hierarchy

Whenever a property is accessed for reading on an object, a search is started to find a property with that name. The search begins on the object instance itself. If a property with the given name is found on the instance, then that value is returned; if the property is not found, then the search continues up the pointer to the prototype, and the prototype is searched for a property with the same name. If the property is found on the prototype, then that value is returned.

When person1.sayName() is called, a two-step process happens. First, the JavaScript engine checks, “Does the instance person1 have a property called sayName?” The answer is no, so it continues the search and checks, “Does the person1 prototype have a property called sayName?” The answer is yes, so the function stored on the prototype is accessed. When person2.sayName() is called, the same search executes, ending with the same result.

This is how prototypes are used to share properties and methods among multiple object instances.

Although it's possible to read values on the prototype from object instances, it is not possible to overwrite them. If you add a property to an instance that has the same name as a property on the prototype, you create the property on the instance, which then masks the property on the prototype. Here's an example:

function Person() {}
 
Person.prototype.name = "Alice";
Person.prototype.age = 29;
Person.prototype.job = "Software Engineer";
Person.prototype.sayName = function() {
  console.log(this.name);
};
 
let person1 = new Person();
let person2 = new Person();
 
person1.name = "Greg";
console.log(person1.name);  // "Greg" - from instance
console.log(person2.name);  // "Alice" - from prototype

In this example, the name property of person1 is shadowed by a new value. Both person1.name and person2.name still function appropriately, returning "Greg" (from the object instance) and "Alice" (from the prototype), respectively. When person1.name is accessed, the search began for a property called name on the instance. Because the property exists, it is used without searching the prototype. When person2.name is accessed the same way, the search doesn't find the property on the instance, so it continues to search on the prototype where the name property is found.

Once a property is added to the object instance, it shadows any properties of the same name on the prototype, which means that it blocks access to the property on the prototype without altering it. Even setting the property to null only sets the property on the instance and doesn't restore the link to the prototype. The delete operator, however, completely removes the instance property and allows the prototype property to be accessed again as follows:

function Person() {}
 
Person.prototype.name = "Alice";
Person.prototype.age = 29;
Person.prototype.job = "Software Engineer";
Person.prototype.sayName = function() {
  console.log(this.name);
};
 
let person1 = new Person();
let person2 = new Person();
 
person1.name = "Greg";
console.log(person1.name);   // "Greg" - from instance
console.log(person2.name);   // "Alice" - from prototype
 
delete person1.name;
console.log(person1.name);   // "Alice" - from the prototype

In this modified example, delete is called on person1.name, which previously had been shadowed with the value "Greg". This restores the link to the prototype's name property, so the next time person1.name is accessed, it's the prototype property's value that is returned.

The hasOwnProperty() method determines if a property exists on the instance or on the prototype. This method, which is inherited from Object, returns true only if a property of the given name exists on the object instance, as in this example:

function Person() {}
 
Person.prototype.name = "Alice";
Person.prototype.age = 29;
Person.prototype.job = "Software Engineer";
Person.prototype.sayName = function() {
  console.log(this.name);
};
 
let person1 = new Person();
let person2 = new Person();
 
console.log(person1.hasOwnProperty("name"));  // false
 
person1.name = "Greg";
console.log(person1.name);   // "Greg" - from instance
console.log(person1.hasOwnProperty("name"));  // true
 
console.log(person2.name);   // "Alice" - from prototype
console.log(person2.hasOwnProperty("name"));  // false
 
delete person1.name;
console.log(person1.name);   // "Alice" - from the prototype
console.log(person1.hasOwnProperty("name"));  // false

By injecting calls to hasOwnProperty() in this example, it becomes clear when the instance's property is being accessed and when the prototype's property is being accessed. Calling person1.hasOwnProperty("name") returns true only after name has been overwritten on person1, indicating that it now has an instance property instead of a prototype property. Figure 8.2 illustrates the various steps being taken in this example. (For simplicity, the relationship to the Person constructor has been omitted.)

The Object.hasOwn() method is an alternative shorthand notation for Object.prototype.hasOwnProperty(). The following lines are equivalent:

person.hasOwnProperty("name");
Object.hasOwn(person, "name");

An illustration of the effects of assignment and delete operations. — **FIGURE 8.2**: Diagram showing the effects of assignment and `delete` operations

Prototypes and the in Operator

There are two ways to use the in operator: on its own or as a for-in loop. When used on its own, the in operator returns true when a property of the given name is accessible by the object, which is to say that the property may exist on the instance or on the prototype. Consider the following example:

function Person() {}
 
Person.prototype.name = "Alice";
Person.prototype.age = 29;
Person.prototype.job = "Software Engineer";
Person.prototype.sayName = function() {
  console.log(this.name);
};
 
let person1 = new Person();
let person2 = new Person();
 
console.log(person1.hasOwnProperty("name"));  // false
console.log("name" in person1);  // true
 
person1.name = "Greg";
console.log(person1.name);   // "Greg" - from instance
console.log(person1.hasOwnProperty("name"));  // true
console.log("name" in person1);  // true
 
console.log(person2.name);   // "Alice" - from prototype
console.log(person2.hasOwnProperty("name"));  // false
console.log("name" in person2);  // true
 
delete person1.name;
console.log(person1.name);   // "Alice" - from the prototype
console.log(person1.hasOwnProperty("name"));  // false
console.log("name" in person1);  // true

Throughout the execution of this code, the property name is available on each object either directly or from the prototype. Therefore, calling "name" on person1 always returns true, regardless of whether the property exists on the instance. It's possible to determine if the property of an object exists on the prototype by combining a call to hasOwnProperty() with the in operator:

function hasPrototypeProperty(object, name){
  return !object.hasOwnProperty(name) && (name in object);
}

Because the in operator always returns true as long as the property is accessible by the object, and hasOwnProperty() returns true only if the property exists on the instance, a prototype property can be determined if the in operator returns true but hasOwnProperty() returns false. Consider the following example:

function Person() {}
 
Person.prototype.name = "Alice";
Person.prototype.age = 29;
Person.prototype.job = "Software Engineer";
Person.prototype.sayName = function() {
  console.log(this.name);
};
 
let person = new Person();
console.log(hasPrototypeProperty(person, "name"));  // true
 
person.name = "Greg";
console.log(hasPrototypeProperty(person, "name"));  // false

In this code, the name property first exists on the prototype, so hasPrototypeProperty() returns true. Once the name property is overwritten, it exists on the instance, so hasPrototypeProperty() returns false. Even though the name property still exists on the prototype, it is no longer used because the instance property now exists.

When using a for-in loop, all properties that are accessible by the object and can be enumerated will be returned, which includes properties both on the instance and on the prototype. Instance properties that shadow a non-enumerable prototype property (a property that has [[Enumerable]] set to false) will be returned in the for-in loop because all manually defined properties are enumerable by default.

To retrieve a list of all enumerable instance properties on an object, you can use the Object.keys() method, which accepts an object as its argument and returns an array of strings containing the names of all enumerable properties. For example:

function Person() {}
 
Person.prototype.name = "Alice";
Person.prototype.age = 29;
Person.prototype.job = "Software Engineer";
Person.prototype.sayName = function() {
  console.log(this.name);
};
 
let keys = Object.keys(Person.prototype);
console.log(keys);    // "name,age,job,sayName"
let p1 = new Person();
p1.name = "Rob";
p1.age = 31;
let p1keys = Object.keys(p1);
console.log(p1keys);  // "name,age"

Here, the keys variable is filled with an array containing "name", "age", "job", and "sayName". This is the order in which they would normally appear using for-in. When called on an instance of Person, Object.keys() returns an array of "name" and "age", the only two instance properties.

If you'd like a list of all instance properties (including non-enumerable), you can use Object.getOwnPropertyNames() in the same way:

let keys = Object.getOwnPropertyNames(Person.prototype);
console.log(keys);   // "constructor,name,age,job,sayName"

Note the inclusion of the non-enumerable constructor property in the list of results. Both Object.keys() and Object.getOwnPropertyNames() may be suitable replacements for using for-in.

Because symbol-keyed properties do not have a concept of a “name,” a sibling method to Object.getOwnPropertyNames() is needed. Object.getOwnPropertySymbols() offers the same behavior as Object.getOwnPropertyNames() but with respect to symbols:

let k1 = Symbol('k1'),
    k2 = Symbol('k2');
 
let o = {
  [k1]: 'k1',
  [k2]: 'k2'
};
 
console.log(Object.getOwnPropertySymbols(o));
// [Symbol(k1), Symbol(k2)]

Property Enumeration Order

for-in loops, Object.keys(), Object.getOwnPropertyNames, Object.getOwnPropertySymbols(), and Object.assign() have an important distinction when it comes to property enumeration order. for-in loops and Object.keys() do not have a deterministic order of enumeration—these are determined by the JavaScript engine and may vary by browser.

Object.getOwnPropertyNames(), Object.getOwnPropertySymbols(), and Object.assign() do have a deterministic enumeration order. Number keys will first be enumerated in ascending order, then string and symbol keys enumerated in insertion order. Keys defined inline in an object literal will be inserted in their comma delimited order.

let k1 = Symbol('k1'),
    k2 = Symbol('k2');
 
let o = {
  1: 1,
  first: 'first',
  [k1]: 'sym2',
  second: 'second',
  0: 0
};
 
o[k2] = 'sym2';
o[3] = 3;
o.third = 'third';
0[2] = 2;
 
console.log(Object.getOwnPropertyNames(o));
// ["0", "1", "3", "first", "second", "third"]
 
console.log(Object.getOwnPropertySymbols(o));
// [Symbol(k1), Symbol(k2)]

Object Iteration

The static methods, Object.values() and Object.entries(), can be used for converting an object's contents into a serialized and iterable format. These methods accept an object and return its contents in an array. Object.values() returns an array of the object's values, and Object.entries() returns an array of array pairs, each representing a key-value pair in the object.

These methods are demonstrated here:

const o = {
  foo: 'bar',
  baz: 1,
  qux: {}
};
 
console.log(Object.values(o));
// ["bar", 1, {}]
 
console.log(Object.entries((o)));
// [["foo", "bar"], ["baz", 1], ["qux", {}]]

Note that non-string properties are converted to strings in the output array. Furthermore, the method performs a shallow copy of the object:

const o = {
  qux: {}
};
 
console.log(Object.values(o)[0] === o.qux);
// true
 
console.log(Object.entries(o)[0][1] === o.qux);
// true
Symbol-keyed properties are ignored:
const sym = Symbol();
const o = {
  [sym]: 'foo'
};
 
console.log(Object.values(o));
// []
 
console.log(Object.entries((o)));
// []

ECMAScript also features the static method Object.fromEntries(), which builds an object from a collection of key-value array pairs. This method performs the inverse operation of Object.entries() and is demonstrated here:

const obj = {
  foo: 'bar',
  baz: 'qux'
};
 
const objEntries = Object.entries(obj);
 
console.log(objEntries);
// [["foo", "bar"], ["baz", "qux"]]
 
console.log(Object.fromEntries(objEntries));
// { foo: "bar", baz: "qux" }

The static method expects an iterable object containing any number of iterable objects of size 2. This is especially useful in cases where you wish to convert a Map instance to an Object instance, as the Map iterator's output exactly matches the signature that fromEntries() ingests:

const map = new Map().set('foo', 'bar');
 
console.log(Object.fromEntries(map));
// { foo: "bar" }

Dynamic Nature of Prototypes

Because the process of looking up values on a prototype is a search, changes made to the prototype at any point are immediately reflected on instances, even the instances that existed before the change was made. Here's an example:

let friend = new Person();
 
Person.prototype.sayHi = function() {
  console.log("hi");
};
 
friend.sayHi();  // "hi" - works!

In this code, an instance of Person is created and stored in friend. The next statement adds a method called sayHi() to Person.prototype. Even though the friend instance was created prior to this change, it still has access to the new method. This happens because of the loose link between the instance and the prototype. When friend.sayHi() is called, the instance is first searched for a property named sayHi; when it's not found, the search continues to the prototype. Because the link between the instance and the prototype is simply a pointer, not a copy, the search finds the new sayHi property on the prototype and returns the function stored there.

Although properties and methods may be added to the prototype at any time, and they are reflected instantly by all object instances, you cannot overwrite the entire prototype and expect the same behavior. The [[Prototype]] pointer is assigned when the constructor is called, so changing the prototype to a different object severs the tie between the constructor and the original prototype. Remember that the instance has a pointer to only the prototype, not to the constructor. Consider the following:

function Person() {}
 
let friend = new Person();
 
Person.prototype = {
  constructor: Person,
  name: "Alice",
  age: 29,
  job: "Software Engineer",
  sayName() {
    console.log(this.name);
  }
};
 
friend.sayName();   // error

In this example, a new instance of Person is created before the prototype object is overwritten. When friend.sayName() is called, it causes an error, because the prototype that friend points to doesn't contain a property of that name. Figure 8.3 illustrates why this happens.

An illustration of effects of prototype assignment. — **FIGURE 8.3**: Diagram demonstrating effects of prototype assignment

Overwriting the prototype on the constructor means that new instances will reference the new prototype while any previously existing object instances still reference the old prototype.

Native Object Prototypes

The prototype pattern is important not just for defining custom types but also because it is the pattern used to implement all of the native reference types. Each of these (including Object, Array, String, and so on) has its methods defined on the constructor's prototype. For instance, the sort() method can be found on Array.prototype, and substring() can be found on String.prototype, as shown here:

console.log(typeof Array.prototype.sort);        // "function"
console.log(typeof String.prototype.substring);  // "function"

Through native object prototypes, it's possible to get references to all the default methods and to define new methods. Native object prototypes can be modified just like custom object prototypes, so methods can be added at any time. For example, the following code adds a method called startsWith() to the String primitive wrapper:

String.prototype.startsWith = function (text) {
  return this.indexOf(text) === 0;
};
 
let msg = "Hello world!";
console.log(msg.startsWith("Hello"));   // true

The startsWith() method in this example returns true if some given text occurs at the beginning of a string. The method is assigned to String.prototype, making it available to all strings in the environment. Since msg is a string, the String primitive wrapper is created behind the scenes, making startsWith() accessible.

Problems with Prototypes

The prototype pattern isn't without its faults. For one, it negates the ability to pass initialization arguments into the constructor, meaning that all instances get the same property values by default. Although this is an inconvenience, it isn't the biggest problem with prototypes. The main problem comes with their shared nature.

All properties on the prototype are shared among instances, which is ideal for functions. Properties that contain primitive values also tend to work well, as shown in the previous example, where it's possible to hide the prototype property by assigning a property of the same name to the instance. The real problem occurs when a property contains a reference value. Consider the following example:

function Person() {}
 
Person.prototype = {
  constructor: Person,
  name: "Alice",
  age: 29,
  job: "Software Engineer",
  friends: ["Shelby", "Court"],
  sayName() {
    console.log(this.name);
  }
};
 
let person1 = new Person();
let person2 = new Person();
 
person1.friends.push("Van");
 
console.log(person1.friends);  // "Shelby,Court,Van"
console.log(person2.friends);  // "Shelby,Court,Van"
console.log(person1.friends === person2.friends);  // true

Here, the Person.prototype object has a property called friends that contains an array of strings. Two instances of Person are then created. The person1.friends array is altered by adding another string. Because the friends array exists on Person.prototype, not on person1, the changes made are also reflected on person2.friends (which points to the same array). If the intention is to have an array shared by all instances, then this outcome is okay. Typically, though, instances want to have their own copies of all properties. This is why the prototype pattern is rarely used on its own.

Prototype Inheritance

The concept most often discussed in relation to object-oriented programming is inheritance. Many object-oriented languages support two types of inheritance: interface inheritance, where only the method signatures are inherited, and implementation inheritance, where actual methods are inherited. Interface inheritance is not possible in ECMAScript because functions do not have signatures. Implementation inheritance is the only type of inheritance supported by ECMAScript, and this is done primarily with prototype chaining.

Prototype Chaining

ECMA-262 describes prototype chaining as the primary method of inheritance in ECMAScript. The basic idea is to use the concept of prototypes to inherit properties and methods between two reference types. Recall the relationship between constructors, prototypes, and instances: each constructor has a prototype object that points back to the constructor, and instances have an internal pointer to the prototype. What if the prototype were an instance of another type? That would mean the prototype itself would have a pointer to a different prototype that, in turn, would have a pointer to another constructor. If that prototype were also an instance of another type, then the pattern would continue, forming a chain between instances and prototypes. This is the basic idea behind prototype chaining.

Implementing prototype chaining involves the following code pattern:

function SuperType() {
  this.property = true;
}
 
SuperType.prototype.getSuperValue = function() {
  return this.property;
};
 
function SubType() {
  this.subproperty = false;
}
 
// inherit from SuperType
SubType.prototype = new SuperType();
 
SubType.prototype.getSubValue = function () {
  return this.subproperty;
};
 
let instance = new SubType();
console.log(instance.getSuperValue());  // true

This code defines two types: SuperType and SubType. Each type has a single property and a single method. The main difference between the two is that SubType inherits from SuperType by creating a new instance of SuperType and assigning it to SubType.prototype. This overwrites the original prototype and replaces it with a new object, which means that all properties and methods that typically exist on an instance of SuperType now also exist on SubType.prototype. After the inheritance takes place, a method is assigned to SubType.prototype, adding a new method on top of what was inherited from SuperType. The relationship between the instance and both constructors and prototypes is displayed in Figure 8.4.

An illustration of the relationship between instances, constructors, and prototypes. — **FIGURE 8.4**: Diagram demonstrating the relationship between instances, constructors, and prototypes

Instead of using the default prototype of SubType, a new prototype is assigned. That new prototype happens to be an instance of SuperType, so it not only gets the properties and methods of a SuperType instance but also points back to the SuperType's prototype. So instance points to SubType.prototype and SubType.prototype points to SuperType.prototype. Note that the getSuperValue() method remains on the SuperType.prototype object, but property ends up on SubType.prototype. That's because getSuperValue() is a prototype method, and property is an instance property. SubType.prototype is now an instance of SuperType, so property is stored there. Also note that instance.constructor points to SuperType because the constructor property on the SubType.prototype was overwritten.

Prototype chaining extends to the prototype search mechanism described earlier. As you may recall, when a property is accessed in read mode on an instance, the property is first searched for on the instance. If the property is not found, then the search continues to the prototype. When inheritance has been implemented via prototype chaining, that search can continue up the prototype chain. In the previous example, for instance, a call to instance.getSuperValue() results in a three-step search: the instance, SubType.prototype, and SuperType.prototype, where the method is found. The search for properties and methods always continues until the end of the prototype chain is reached.

Default Prototypes

Up until this point, we've ignored the final step in the prototype chain. All reference types inherit from Object by default, which is accomplished through prototype chaining. The default prototype for any function is an instance of Object, meaning that its internal prototype pointer points to Object.prototype. This is how custom types inherit all of the default methods such as toString() and valueOf(). The previous example has an extra layer of inheritance. Figure 8.5 shows the complete prototype chain.

An illustration of the path of a prototype chain. — **FIGURE 8.5**: Diagram demonstrating the path of a prototype chain

SubType inherits from SuperType, and SuperType inherits from Object. When instance.toString() is called, the method being called actually exists on Object.prototype.

Prototype and Instance Relationships

The relationship between prototypes and instances is discernible in two ways. The first way is to use the instanceof operator, which returns true whenever an instance is used with a constructor that appears in its prototype chain, as in this example:

console.log(instance instanceof Object);     // true
console.log(instance instanceof SuperType);  // true
console.log(instance instanceof SubType);    // true

Here, the instance object is technically an instance of Object, SuperType, and SubType because of the prototype chain relationship. The result is that instanceof returns true for all of these constructors.

The second way to determine this relationship is to use the isPrototypeOf() method. Each prototype in the chain has access to this method, which returns true for an instance in the chain, as in this example:

console.log(Object.prototype.isPrototypeOf(instance));     // true
console.log(SuperType.prototype.isPrototypeOf(instance));  // true
console.log(SubType.prototype.isPrototypeOf(instance));    // true

Working with Methods

Often a subtype will need to either override a supertype method or introduce new methods that don't exist on the supertype. To accomplish this, the methods must be added to the prototype after the prototype has been assigned. Consider this example:

function SuperType() {
  this.property = true;
}
 
SuperType.prototype.getSuperValue = function() {
  return this.property;
};
 
function SubType() {
  this.subproperty = false;
}
 
// inherit from SuperType
SubType.prototype = new SuperType();
 
// new method
SubType.prototype.getSubValue = function () {
  return this.subproperty;
};
 
// override existing method
SubType.prototype.getSuperValue = function () {
  return false;
};
 
let instance = new SubType();
console.log(instance.getSuperValue());   // false

In this code, the highlighted area shows two methods. The first is getSubValue(), which is a new method on the SubType. The second is getSuperValue(), which already exists in the prototype chain but is being shadowed here. When getSuperValue() is called on an instance of SubType, it will call this one, but instances of SuperType will still call the original. The important thing to note is that both of the methods are defined after the prototype has been assigned as an instance of SuperType.

Problems with Prototype Chaining

Even though prototype chaining is a powerful tool for inheritance, it is not without its issues. The major issue revolves around prototypes that contain reference values. Recall from earlier that prototype properties containing reference values are shared with all instances; this is why properties are typically defined within the constructor instead of on the prototype. When implementing inheritance using prototypes, the prototype actually becomes an instance of another type, meaning that what once were instance properties are now prototype properties. The issue is highlighted by the following example:

function SuperType() {
  this.colors = ["red", "blue", "green"];
}
 
function SubType() {}
 
// inherit from SuperType
SubType.prototype = new SuperType();
 
let instance1 = new SubType();
instance1.colors.push("black");
console.log(instance1.colors);  // "red,blue,green,black"
 
let instance2 = new SubType();
console.log(instance2.colors);  // "red,blue,green,black"

In this example, the SuperType constructor defines a property, colors, that contains an array (a reference value). Each instance of SuperType has its own colors property containing its own array. When SubType inherits from SuperType via prototype chaining, SubType.prototype becomes an instance of SuperType, and so it gets its own colors property, which is akin to specifically creating SubType.prototype.colors. The end result: all instances of SubType share a colors property. This is indicated as the changes made to instance1.colors are reflected on instance2.colors.

A second issue with prototype chaining is that you cannot pass arguments into the supertype constructor when the subtype instance is being created. In fact, there is no way to pass arguments into the supertype constructor without affecting all of the object instances. Because of this and the aforementioned issue with reference values on the prototype, prototype chaining is rarely used alone.

CLASSES

The previous sections are an in-depth overview of how it was possible to emulate class-like behavior using only features available in ECMAScript 5. It is not difficult to conclude that the strategies shown presented various problems and tradeoffs. On top of this, the syntax was inarguably excessively verbose and messy.

To address these problems, ECMAScript added the ability to formally define classes using the class keyword. Although ECMAScript classes appear to feature canonical object-oriented programming, they still uses prototype and constructor concepts under the hood.

Class Definition Basics

Similar to the function type, there are two primary ways of defining a class: class declarations and class expressions. Both use the class keyword and curly braces:

// class declaration
class Person {}
 
// class expression
const Animal = class {};

Like function expressions, class expressions cannot be referenced until they are evaluated in execution. However, an important departure from the parallel behavior of function definition is that, while function declarations are hoisted, class declarations are not:

console.log(FunctionExpression);  // undefined
var FunctionExpression = function() {};
console.log(FunctionExpression);  // function() {}
 
 
console.log(FunctionDeclaration); // FunctionDeclaration() {}
function FunctionDeclaration() {}
console.log(FunctionDeclaration); // FunctionDeclaration() {}
 
 
console.log(ClassExpression);     // undefined
var ClassExpression = class {};
console.log(ClassExpression);     // class {}
 
 
console.log(ClassDeclaration);    // ReferenceError: ClassDeclaration is
                                  // not defined
class ClassDeclaration {}
console.log(ClassDeclaration);    // class ClassDeclaration {}

Whereas function declarations are function scoped, class declarations are block scoped:

{
  function FunctionDeclaration() {}
  class ClassDeclaration {}
}
 
console.log(FunctionDeclaration); // FunctionDeclaration() {}
console.log(ClassDeclaration);    // ReferenceError: ClassDeclaration is
                                  // not defined

Class Composition

A class can be composed of the class's constructor method, instance methods, getters, setters, and static class methods. None of these are explicitly required; an empty class definition is valid syntax. By default, everything inside a class definition executes in strict mode.

As with function constructors, most style guides will direct you to capitalize the class name to distinguish it from instances that are created from it (for example, class Foo {} might create an instance foo):

// Valid empty class definition
class Foo {}
 
// Valid class definition with constructor
class Bar {
  constructor() {}
}
 
// Valid class definition with getter
class Baz {
  get myBaz() {}
}
 
// Valid class definition with static method
class Qux {
  static myQux() {}
}

Class expressions may be optionally named. When the expression is assigned to a variable, the name property may be used to retrieve the class expression name string, but the identifier itself is not accessible outside the class expression scope.

let Person = class PersonName {
  identify() {
    console.log(Person.name, PersonName.name);
  }
}
 
let p = new Person();
 
p.identify();              // PersonName, PersonName
 
console.log(Person.name);  // PersonName
console.log(PersonName);   // ReferenceError: PersonName is not defined

The Class Constructor

The constructor keyword is used inside the class definition block to signal the definition of the class's constructor function. Using the method name constructor will signal to the interpreter that this particular function should be invoked to create a fresh instance using the new operator. Definition of the constructor is optional; electing not to define the class constructor is the same as defining the constructor as an empty function.

Instantiation

Instantiating a Person using the new operator operates identically to using new with a function constructor. The only perceptible difference is that the JavaScript interpreter understands that using new with a class means the constructor function should be used for instantiation.

Calling a class constructor using new will do the following:

A new object is created in memory.
The new object's internal [[Prototype]] pointer is assigned to be the constructor's prototype property.
The this value of the constructor is assigned to the new object (so this points to the new object when referenced inside the constructor function).
The code inside the constructor function is executed (adds properties to the new object).
If the constructor function returns an object, that object is returned. Otherwise, the new object that was just created is returned.

class Animal {}
 
class Person {
  constructor() {
    console.log('person ctor');
  }
}
 
class Vegetable {
  constructor() {
    this.color = 'orange';
  }
}
 
let a = new Animal();
 
let p = new Person();  // person ctor
 
let v = new Vegetable();
console.log(v.color);  // orange

Parameters provided when instantiating the class are used as parameters to the constructor function. If you do not require the use of parameters, empty parentheses following the class name are optional:

class Person {
  constructor(name) {
    console.log(arguments.length);
    this.name = name || null;
  }
}
 
let p1 = new Person;          // 0
console.log(p1.name);         // null
 
let p2 = new Person();        // 0
console.log(p2.name);         // null
 
let p3 = new Person('Jake');  // 1
console.log(p3.name);         // Jake

By default, the constructor function will return the this object after execution. If an object is returned from the constructor function, that value will be used as the instantiated object and the newly created this object will be discarded if a reference to it is not preserved. However, if a different object is returned, the returned object will not be associated with the class via instanceof because its prototype pointer was never modified.

class Person {
  constructor(override) {
    this.foo = 'foo';
    if (override) {
      return {
        bar: 'bar'
      };
    }
  }
}
 
let p1 = new Person(),
    p2 = new Person(true);
 
console.log(p1);                    // Person{ foo: 'foo' }
console.log(p1 instanceof Person);  // true
 
console.log(p2);                    // { bar: 'bar' }
console.log(p2 instanceof Person);  // false

One major departure from function constructors is that the use of the new operator with class constructors is mandatory. With function constructors, when electing not to use the new operator, the constructor would use the global this value—typically the window object—inside the constructor. With class constructors, neglecting to use the new operator will throw an error:

function Person() {}
 
class Animal {}
 
// Constructs instance using window as 'this'
let p = Person();
 
let a = Animal();
// TypeError: class constructor Animal cannot be invoked without 'new'

The class constructor method is not special and, after instantiation, behaves as a regular instance method (with the same constructor restrictions). Because of this, you can reference and use it post-instantiation:

class Person {}
 
// Create a new instance using the class
let p1 = new Person();
 
p1.constructor();
// TypeError: Class constructor Person cannot be invoked without 'new'
 
// Create a new instance using the reference to the class constructor
let p2 = new p1.constructor();

Understanding Classes as Special Functions

There is no formal “Class” type in the ECMAScript specification, and in many ways ECMAScript classes behave like special functions. Once declared, the class identifier identifies as a function when checked with the typeof operator:

class Person {}
 
console.log(Person);         // class Person {}
console.log(typeof Person);  // function

The class identifier has a prototype property, and the prototype has a constructor property that refers back to the class itself:

class Person{}
 
console.log(Person.prototype);                         // { constructor: f() }
console.log(Person === Person.prototype.constructor);  // true

As with function constructors, you can use the instanceof operator to test if the constructor prototype appears in the prototype chain of an instance:

class Person {}
 
let p = new Person();
 
console.log(p instanceof Person);  // true

You have likely come to understand that the instanceof operator checks an instance's prototype chain against a constructor function, which in this example would be checking the instance p against the constructor function Person, which appears to be a class.

As shown earlier, the class behaves in the same way as a constructor function, and in the context of classes, the class itself is considered the constructor when new is applied to it. Importantly, the constructor method inside the class definition is not considered to be the constructor and will return false when used with instanceof. If the constructor method is invoked directly, this is the same as using a non-class function constructor, and the instanceof convention will reverse:

class Person {}
 
let p1 = new Person();
 
console.log(p1.constructor === Person);         // true
console.log(p1 instanceof Person);              // true
console.log(p1 instanceof Person.constructor);  // false
 
let p2 = new Person.constructor();
 
console.log(p2.constructor === Person);         // false
console.log(p2 instanceof Person);              // false
console.log(p2 instanceof Person.constructor);  // true

Classes are first-class citizens in JavaScript, meaning they can be passed around as you would any other object or function reference:

// Classes may be defined anywhere a function would, such as inside an array:
let classList = [
  class {
    constructor(id) {
      this.id_ = id;
      console.log('instance ${this.id_}');
    }
  }
];
 
function createInstance(classDefinition, id) {
  return new classDefinition(id);
}
 
let foo = createInstance(classList[0], 3141); // instance 3141

Similar to an immediately invoked function expression, a class can also be immediately instantiated:

// Because it is a class expression, the class name is optional
let p = new class Foo {
  constructor(x) {
    console.log(x);
  }
}('bar');        // bar
 
console.log(p);  // Foo {}

Instance, Prototype, and Class Members

The class definition syntax allows you to neatly define members that should exist on an object instance, members that should exist on the object prototype, and members that should exist on the class itself.

Instance Members

Each time new <classname> is invoked, the constructor function will execute. Inside this function, you are able to populate the freshly created instance (the this object) with “own” properties. There are no restrictions to what may be added to the new instance and no restrictions on members added after the constructor exits.

Each instance is assigned unique member objects, meaning nothing is shared on the prototype:

class Person {
  constructor() {
    // For this example, define a string with object wrapper
    // as to check object equality between instances below
    this.name = new String('Jack');
 
    this.sayName = () => console.log(this.name);
 
    this.nicknames = ['Jake', 'J-Dog']
  }
}
 
let p1 = new Person(),
    p2 = new Person();
 
p1.sayName();  // Jack
p2.sayName();  // Jack
 
console.log(p1.name === p2.name);            // false
console.log(p1.sayName === p2.sayName);      // false
console.log(p1.nicknames === p2.nicknames);  // false
 
p1.name = p1.nicknames[0];
p2.name = p2.nicknames[1];
 
p1.sayName();  // Jake
p2.sayName();  // J-Dog

Class Field Declarations

Assigning initial member values for each instance inside the constructor is such a common pattern that the class field declaration was introduced as shorthand. This allows for members to be initialized inside the class body itself instead of inside the constructor. The following two patterns are identical:

class PersonWithConstructor {
  constructor() {
    this.friendCount = 0;
  }
}
 
class PersonWithClassFields {
  friendCount = 0;
}

If you define a constructor function, the class field declarations will be available inside the constructor:

class Person {
  friendCount = 0;
 
  constructor() {
    console.log(this.friendCount);  // 0
  }
}

Members can be declared but not initialized. They will be treated as having a value of undefined:

class Person {
  friendCount;
 
  constructor() {
    console.log(this.friendCount);  // undefined
  }
}

Prototype Methods and Accessors

To allow for sharing of methods between instances, the class definition syntax allows for definition of methods on the prototype object inside the class body.

class Person {
  constructor() {
    // Everything added to 'this' will exist on each individual instance
    this.locate = () => console.log('instance');
  }
 
  // Everything defined in the class body is defined on the class prototype object
  locate() {
    console.log('prototype');
  }
}
 
let p = new Person();
 
p.locate();                 // instance
Person.prototype.locate();  // prototype

Methods can be defined in either location, but member data such as primitives and objects cannot be added to the prototype inside the class body:

class Person {
  name: 'Jake'
}
// Uncaught SyntaxError: Unexpected token :

Class methods behave identically to object properties, meaning they can be keyed with strings, symbols, or computed values:

const symbolKey = Symbol('symbolKey');
 
class Person {
  stringKey() {
    console.log('invoked stringKey');
  }
  [symbolKey]() {
    console.log('invoked symbolKey');
  }
  ['computed' + 'Key']() {
    console.log('invoked computedKey');
  }
}
 
let p = new Person();
 
p.stringKey();    // invoked stringKey
p[symbolKey]();   // invoked symbolKey
p.computedKey();  // invoked computedKey

Class definitions also support getters and setter accessors. The syntax and behavior are identical to that of regular objects:

class Person {
  set name(newName) {
    this.name_ = newName;
  }
 
  get name() {
    return this.name_;
  }
}
 
let p = new Person();
p.name = 'Jake';
console.log(p.name);  // Jake

Private Class Members

Private class members in JavaScript allow you to define properties and methods that are only accessible within the class itself. They provide encapsulation and information hiding, preventing direct access and modification from outside the class. To declare a private class member, prefix the member name with #. Here's an example that contrasts public and private class members:

class Person {
  #name = "Alice";
  age = 30;
 
  getName() {
    return this.#name;
  }
}
 
const person = new Person();
console.log(person.age);        // 30
console.log(person.getName());  // Alice

In this example, a public variable age and a private variable #name are declared. A public method getName() is used to access the private member, which is a common pattern that protects the #name value by only offering indirect access.

To verify this member is indeed private, the following code attempts to retrieve the private variable in several different ways. Note that both attempts to retrieve the value fail.

console.log(person.#name);
// SyntaxError: Private field '#name' must be declared in an enclosing class
 
console.log(person['age']);    // 30
console.log(person['#name']);  // undefined

The # property prefix imparts special behavior, as JavaScript performs a compile-time check for this character and applies special rules to matching properties:

Private members are only accessible from within the class where they are defined. They cannot be accessed or modified from outside the class.
Private members are not inherited by subclasses. They are specific to the class in which they are defined.
Private members cannot be accessed or overridden by methods or properties with the same name in derived classes.
Constructors cannot be private.
Private members must be declared in the class body; they cannot be added during or after the constructor has been called.

The following example demonstrates some possibly unexpected behavior of private members:

class Person {
  #age;
 
  constructor() {
    this.#age = 30;
    
    // Private members cannot be deleted
    delete this.#age;  // SyntaxError
    
    // You must declare all private members in the class body
    this.#name = "Alice";  // SyntaxError
  }
}
 
new Person();

Fields, methods, getters, setters, async functions, and static members can all be private. The following example gives some examples of the various forms private members can take:

class Person {
  #name;
  #age;
  static #counter = 0;
 
  constructor(name, age) {
    this.#name = name;
    this.#age = age;
    Person.#incrementCounter();  
  }
 
  // Private method
  #getNameInUpperCase() {
    return this.#name.toUpperCase();
  }
 
  // Private getter
  get #capitalizedName() {
    return this.#getNameInUpperCase();
  }
 
  // Public getter
  get name() {
    return this.#name;
  }
 
  // Public getter to access private getter
  get capitalizedName() {
    return this.#capitalizedName;
  }
 
  // Static method
  static getCounter() {
    return Person.#counter;
  }
 
  // Private static method
  static #incrementCounter() {
    Person.#counter += 1;
  }
}
 
let p = new Person("Alice", 30);
console.log(p.name);              // Alice
console.log(p.capitalizedName);   // ALICE
console.log(Person.getCounter()); // 1

Static Class Methods and Accessors

It is also possible to define members on the class itself. These are intended to be used in situations where a piece of data or function is used in a way that is not centered on a specific instance and does not require a class instance to exist. Like prototype members, these are only ever created once per class.

A static class member is designated using the static keyword as a prefix inside the class definition. Inside static methods, this refers to the class itself. All other conventions are identical to prototype members:

class Person {
  // defined on the class
  static species = "sapiens";
 
  constructor() {
    // Everything added to 'this' will exist on each individual instance
    this.locate = () => console.log('instance', this);
  }
 
  // Defined on the class prototype object
  locate() {
    console.log('prototype', this);
  }
 
  // Defined on the class
  static locate() {
    console.log('class', this);
  }
}
 
let p = new Person();
 
console.log(Person.species);  // sapiens
 
p.locate();                   // instance, Person {}
Person.prototype.locate();    // prototype, {constructor: ... }
Person.locate();              // class, class Person {}

Static class methods can be useful as instance factories:

class Person {
  constructor(age) {
    this.age_ = age;
  }
 
  sayAge() {
    console.log(this.age_);
  }
 
  static create() {
    // Create and return a person instance with a random age
    return new Person(Math.floor(Math.random()*100));
  }
}
 
console.log(Person.create());  // Person { age_:... }

Static Initialization Blocks

In cases where static initialization is nontrivial, classes support static initialization blocks for writing complex code to initialize static members. A simple example is as follows:

class Person {
  static name = "Alice";
  static age;
  static {
    this.age = 30;
  }
}

Static initialization blocks provide a way to declare and execute arbitrary initialization logic within a class during its evaluation. The initialization block is useful when you must compute complex static values or inspect existing static values. When reaching for static initialization blocks, keep the following in mind:

Any number of blocks can be used in a class. Blocks will be evaluated in the order they appear.
The blocks must be evaluated synchronously.
The initialization block scope is treated as normal lexical scope.
The this inside a static block refers to the constructor object of the class.

Iterator and Generator Methods

The class definition syntax allows for definition of generator methods on both the prototype and the class itself:

class Person {
  // define generator on prototype
  *createNicknameIterator() {
    yield 'Jack';
    yield 'Jake';
    yield 'J-Dog';
  }
 
  // define generator on class
  static *createJobIterator() {
    yield 'Butcher';
    yield 'Baker';
    yield 'Candlestick maker';
  }
}
 
let jobIter = Person.createJobIterator();
console.log(jobIter.next().value);  // Butcher
console.log(jobIter.next().value);  // Baker
console.log(jobIter.next().value);  // Candlestick maker
 
let p = new Person();
let nicknameIter = p.createNicknameIterator();
console.log(nicknameIter.next().value);  // Jack
console.log(nicknameIter.next().value);  // Jake
console.log(nicknameIter.next().value);  // J-Dog

Because generator methods are supported, it is possible to make a class instance iterable by adding a default iterator:

class Person {
  constructor() {
    this.nicknames = ['Jack', 'Jake', 'J-Dog'];
  }
 
  *[Symbol.iterator]() {
    yield *this.nicknames.entries();
  }
}
 
let p = new Person();
for (let [idx, nickname] of p) {
  console.log(nickname);
}
// Jack
// Jake
// J-Dog

Alternately, to merely return the iterator instance:

class Person {
  constructor() {
    this.nicknames = ['Jack', 'Jake', 'J-Dog'];
  }
 
  [Symbol.iterator]() {
    return this.nicknames.entries();
  }
}
 
let p = new Person();
for (let [idx, nickname] of p) {
  console.log(nickname);
}
// Jack
// Jake
// J-Dog

Class Inheritance

Earlier in the chapter, we covered the laborious details of implementing inheritance using ES5 mechanisms. ECMAScript classes support a native inheritance mechanism. Class inheritance still uses the prototype chain under the hood.

Inheritance Basics

ECMAScript classes use single inheritance, meaning there can only be one parent class. Using the extends keyword, you can inherit from anything that has a [[Construct]] property and a prototype. For the most part, this means inheriting from another class, but this also allows for backwards compatibility with function constructors:

class Vehicle {}
 
// Inherit from class
class Bus extends Vehicle {}
 
let b = new Bus();
console.log(b instanceof Bus);      // true
console.log(b instanceof Vehicle);  // true
 
 
function Person() {}
 
// Inherit from function constructor
class Engineer extends Person {}
 
let e = new Engineer();
console.log(e instanceof Engineer);  // true
console.log(e instanceof Person);    // true

Both class and prototype methods are carried down to the derived class. The value of this reflects the class or instance that is invoking the method:

class Vehicle {
  identifyPrototype(id) {
    console.log(id, this);
  }
 
  static identifyClass(id) {
    console.log(id, this);
  }
}
 
class Bus extends Vehicle {}
 
let v = new Vehicle();
let b = new Bus();
 
b.identifyPrototype('bus');        // bus, Bus {}
v.identifyPrototype('vehicle');    // vehicle, Vehicle {}
 
Bus.identifyClass('bus');          // bus, class Bus {}
Vehicle.identifyClass('vehicle');  // vehicle, class Vehicle {}

Constructors, HomeObjects, and super()

Derived class methods have a reference to their prototype via the super keyword. This is only available for derived classes inside the constructor, instance methods, and static methods. super is used inside the constructor to control when to invoke the parent class constructor.

class Vehicle {
  constructor() {
    this.hasEngine = true;
  }
}
 
class Bus extends Vehicle {
  constructor() {
    // Cannot reference 'this' before super(), will throw ReferenceError
 
    super();  // same as super.constructor()
 
    console.log(this instanceof Vehicle);  // true
    console.log(this);                     // Bus { hasEngine: true }
  }
}
 
new Bus();

super can also be used inside static methods to invoke static methods defined on the inherited class:

class Vehicle {
  static identify() {
    console.log('vehicle');
  }
}
 
class Bus extends Vehicle {
  static identify() {
    super.identify();
  }
}
 
Bus.identify();  // vehicle

Things to note when using super:

super can only be used in a derived class constructor or static method.

class Vehicle {
  constructor() {
    super();
    // SyntaxError: 'super' keyword unexpected
  }
}

The super keyword cannot be referenced by itself; it must be either invoked as a constructor or used to reference a static method.

class Vehicle {}
 
class Bus extends Vehicle {
  constructor() {
    console.log(super);
    // SyntaxError: 'super' keyword unexpected here
  }
}

Calling super() will invoke the parent class constructor and assign the resulting instance to this.

class Vehicle {}
 
class Bus extends Vehicle {
  constructor() {
    super();
 
    console.log(this instanceof Vehicle);
  }
}
 
new Bus();  // true

super() behaves like a constructor function; you must manually pass arguments to it to pass them to the parent constructor.

class Vehicle {
  constructor(licensePlate) {
    this.licensePlate = licensePlate;
  }
}
 
class Bus extends Vehicle {
  constructor(licensePlate) {
    super(licensePlate);
  }
}
 
console.log(new Bus('1337H4X'));  // Bus { licensePlate: '1337H4X' }

If you decline to define a constructor function, super() will be implicitly invoked and all arguments passed to the derived class constructor.

class Vehicle {
  constructor(licensePlate) {
    this.licensePlate = licensePlate;
  }
}
 
class Bus extends Vehicle {}
 
console.log(new Bus('1337H4X'));  // Bus { licensePlate: '1337H4X' }

You cannot reference this inside the constructor before invoking super().

class Vehicle {}
 
class Bus extends Vehicle {
  constructor() {
    console.log(this);
  }
}
 
new Bus();
// ReferenceError: Must call super constructor in derived class
// before accessing 'this' or returning from derived constructor

If a class is derived from a parent class and you explicitly define a constructor, you must either invoke super() or return an object from the constructor.

class Vehicle {}
 
class Car extends Vehicle {}
 
class Bus extends Vehicle {
  constructor() {
    super();
  }
}
 
class Van extends Vehicle {
  constructor() {
    return {};
  }
}
 
console.log(new Car());  // Car {}
console.log(new Bus());  // Bus {}
console.log(new Van());  // {}

Abstract Base Classes

You may find a need to define an abstract base class, which is a class that should be inherited from but not directly instantiated. Although ECMAScript does not explicitly support this, it is easy to implement using new.target, which informs you what was used in conjunction with the new keyword. You can prevent direct instantiation by checking that new.target is never the abstract base class:

// Abstract base class
class Vehicle {
  constructor() {
    console.log(new.target);
    if (new.target === Vehicle) {
      throw new Error('Vehicle cannot be directly instantiated');
    }
  }
}
 
// Derived class
class Bus extends Vehicle {}
 
new Bus();      // class Bus {}
new Vehicle();  // class Vehicle {}
// Error: Vehicle cannot be directly instantiated

It is also possible to require that a method be defined on a derived class by checking for it in the abstract base class constructor. Because prototype methods exist before the constructor is invoked, you can check for them on the this keyword:

// Abstract base class
class Vehicle {
  constructor() {
    if (new.target === Vehicle) {
      throw new Error('Vehicle cannot be directly instantiated');
    }
 
    if (!this.foo) {
      throw new Error('Inheriting class must define foo()');
    }
 
    console.log('success!');
  }
}
 
// Derived class
class Bus extends Vehicle {
  foo() {}
}
 
// Derived class
class Van extends Vehicle {}
 
new Bus();  // success!
new Van();  // Error: Inheriting class must define foo()

Inheriting from Built-In Types

ECMAScript classes offer seamless interoperability with existing built-in reference types, allowing you to extend them easily:

class SuperArray extends Array {
  shuffle() {
    // Fisher-Yates shuffle
    for (let i = this.length - 1; i> 0; i--) {
      const j = Math.floor(Math.random() * (i + 1));
      [this[i], this[j]] = [this[j], this[i]];
    }
  }
}
 
let a = new SuperArray(1, 2, 3, 4, 5);
 
console.log(a instanceof Array);       // true
console.log(a instanceof SuperArray);  // true
 
console.log(a);  // [1, 2, 3, 4, 5]
a.shuffle();
console.log(a);  // [3, 1, 4, 5, 2]

Some built-in types have methods defined in which a new object instance is returned. By default, the type of this object instance will match the type of the original instance:

class SuperArray extends Array {}
 
let a1 = new SuperArray(1, 2, 3, 4, 5);
let a2 = a1.filter(x => !!(x%2))
 
console.log(a1);  // [1, 2, 3, 4, 5]
console.log(a2);  // [1, 3, 5]
console.log(a1 instanceof SuperArray);  // true
console.log(a2 instanceof SuperArray);  // true

If you wish to override this, you can override the Symbol.species accessor, which is used to determine the class to be used to create the returned instance:

class SuperArray extends Array {
  static get [Symbol.species]() {
    return Array;
  }
}
 
let a1 = new SuperArray(1, 2, 3, 4, 5);
let a2 = a1.filter(x => !!(x%2))
 
console.log(a1);  // [1, 2, 3, 4, 5]
console.log(a2);  // [1, 3, 5]
console.log(a1 instanceof SuperArray);  // true
console.log(a2 instanceof SuperArray);  // false

Class Mixins

A common pattern in JavaScript is to bundle together behavior from several different classes into a single package. Although ECMAScript classes do not explicitly support inheriting from multiple classes, the feature offers extensibility that can be cleverly wielded to emulate such behavior.

The reference following the extends keyword is a JavaScript expression. Any syntax is valid there as long as it resolves to a class or function constructor. The expression is evaluated when the class definition is evaluated:

class Vehicle {}
 
function getParentClass() {
  console.log('evaluated expression');
  return Vehicle;
}
 
class Bus extends getParentClass() {}
// evaluated expression

A mixin pattern can be achieved by chaining multiple mixin elements inside the expression, which will resolve into a single class that can be inherited from. If a class Person needs to incorporate mixins A, B, and C, you will in some form architect a pattern that configures B to inherit from A, C to inherit from B, and Person to inherit from C—thereby joining all three mixins into the superclass. There are several strategies that can accomplish such a pattern.

One strategy is to define “nestable” functions that accept a superclass as a parameter, define the mixin class as a subclass of the parameter, and return that class. These mixins can be chained inside each other and provided as the superclass expression:

class Vehicle {}
 
let FooMixin = (Superclass) => class extends Superclass {
  foo() {
    console.log('foo');
  }
};
let BarMixin = (Superclass) => class extends Superclass {
  bar() {
    console.log('bar');
  }
};
let BazMixin = (Superclass) => class extends Superclass {
  baz() {
    console.log('baz');
  }
};
 
class Bus extends FooMixin(BarMixin(BazMixin(Vehicle))) {}
 
let b = new Bus();
b.foo();  // foo
b.bar();  // bar
b.baz();  // baz

It is possible to flatten this nesting using a utility function:

class Vehicle {}
 
let FooMixin = (Superclass) => class extends Superclass {
  foo() {
    console.log('foo');
  }
};
let BarMixin = (Superclass) => class extends Superclass {
  bar() {
    console.log('bar');
  }
};
let BazMixin = (Superclass) => class extends Superclass {
  baz() {
    console.log('baz');
  }
};
 
function mix(BaseClass, ...Mixins) {
  return Mixins.reduce((accumulator, current) => current(accumulator), BaseClass);
}
 
class Bus extends mix(Vehicle, FooMixin, BarMixin, BazMixin) {}
 
let b = new Bus();
b.foo();  // foo
b.bar();  // bar
b.baz();  // baz

SUMMARY

Objects are created and augmented at any point during code execution, making objects into dynamic, rather than strictly defined, entities. The following patterns are used for the creation of objects:

The factory pattern uses a simple function that creates an object, assigns properties and methods, and then returns the object. This pattern fell out of favor when the constructor pattern emerged.
With the constructor pattern, it's possible to define custom reference types that can be created using the new operator in the same way as built-in object instances are created. The constructor pattern does have a downside, however, in that none of its members are reused, including functions. Because functions can be written in a loosely typed manner, there's no reason they cannot be shared by multiple object instances.
The prototype pattern takes this into account, using the constructor's prototype property to assign properties and methods that should be shared. The combination constructor/prototype pattern uses the constructor to define instance properties and the prototype pattern to define shared properties and methods.

Inheritance in JavaScript is implemented primarily using the concept of prototype chaining. Prototype chaining involves assigning a constructor's prototype to be an instance of another type. In doing so, the subtype assumes all of the properties and methods of the supertype in a manner similar to class-based inheritance. The problem with prototype chaining is that all of the inherited properties and methods are shared among object instances, making it ill-suited for use on its own. The constructor stealing pattern avoids these issues, calling the supertype's constructor from inside of the subtype's constructor. This allows each instance to have its own properties but forces the types to be defined using only the constructor pattern. The most popular pattern of inheritance is combination inheritance, which uses prototype chaining to inherit shared properties and methods and uses constructor stealing to inherit instance properties.

ECMAScript classes are a syntactical wrapper for prototype-based concepts. They offer a host of powerful features and have seen continuous enhancements with each ECMAScript version. These classes provide a clean and intuitive syntax for defining objects and for incorporating key features such as constructors, instance methods, static methods, and getters/setters. Furthermore, ECMAScript has introduced additional features like private class fields, public and private class methods, and class fields with initializer expressions.

9
Proxies and Reflect

Proxies and reflection are constructs that afford you the ability to intercept and shim additional behavior into fundamental operations within the language. More specifically, you can define a proxy object associated with a target object, and the proxy object can be used as an abstracted target object within which you can control what happens when various operations are performed before they actually reach the target object.

For developers approaching this subject for the first time, this is a fairly nebulous concept paired with a healthy corpus of new terminology. Working through multiple examples will help to cement your understanding.

PROXY FUNDAMENTALS

As mentioned in the chapter introduction, a proxy behaves as an abstraction for a target object. In many ways, it is analogous to a C++ pointer in that it can be wielded as a stand-in for the target object it points to but is, in fact, totally separate from the target object. The target object can either be manipulated directly or through the proxy, but manipulating directly will circumvent the behavior that a proxy enables.

Creating a Passthrough Proxy

In its simplest form, a proxy can exist as nothing more than an abstracted target object. By default, all operations performed on a proxy object will be transparently propagated through to the target object. Therefore, you are able to use a proxy object in all the same ways and places that you would use the target object that the proxy object is associated with.

A proxy is created using the Proxy constructor. It requires you to provide both a target object and a handler object, without which a TypeError is thrown. For a simple passthrough proxy, using a simple object literal for the handler object will allow all operations to reach the target object unimpeded.

As shown here, all operations performed on the proxy will effectively be applied to the target object instead. The only perceptible difference is the identity of the proxy object.

const target = {
  id: 'target'
};

const handler = {};

const proxy = new Proxy(target, handler);

// The 'id' property will access the same value
console.log(target.id);  // target
console.log(proxy.id);   // target

// Assignment to a target property changes both since
// both are accessing the same value.
target.id = 'foo';
console.log(target.id);  // foo
console.log(proxy.id);   // foo

// Assignment to a proxy property changes both since
// this assignment is conferred to the target object.
proxy.id = 'bar';
console.log(target.id);  // bar
console.log(proxy.id);   // bar

// The hasOwnProperty() method is effectively applied
// to the target in both cases.
console.log(target.hasOwnProperty('id'));  // true
console.log(proxy.hasOwnProperty('id'));   // true

// Strict object equality can still be used to
// differentiate proxy from target.
console.log(target === proxy);  // false

Defining Traps

The primary purpose of a proxy is to allow you to define traps, which behave as “fundamental operation interceptors” inside the handler object. Each handler object is made up of zero, one, or many traps, and each trap corresponds to a fundamental operation that can be directly or indirectly called on the proxy. When these fundamental operations are called on the proxy object, before being invoked on the target object, the proxy will invoke the trap function instead, allowing you to intercept and modify its behavior.

For example, you are able to define a get() trap that is triggered each time any ECMAScript operation performs a get() in one form or another. Such a trap can be defined as follows:

const target = {
  foo: 'bar'
};

const handler = {
  // Traps are keyed by method name inside the handler object
  get() {
    return 'handler override';
  }
};

const proxy = new Proxy(target, handler);

When a get() operation is called on this proxy object, the trap function that is defined for get() will be invoked instead. Of course, get() is not a usable method on ECMAScript objects. The get() operation that is being trapped is shared between multiple operations that can be found in actual JavaScript code. Operations of the form proxy[property], proxy.property, or Object.create(proxy)[property] will all use the fundamental operation get() to retrieve the property, and therefore all of these will invoke the trap function instead when they are used on the proxy. Only the proxy will use the trap handler functions; these operations will behave normally when used with the target object.

const target = {
  foo: 'bar'
};

const handler = {
  // Traps are keyed by method name inside the handler object
  get() {
    return 'handler override';
  }
};

const proxy = new Proxy(target, handler);

console.log(target.foo);                    // bar
console.log(proxy.foo);                     // handler override

console.log(target['foo']);                 // bar
console.log(proxy['foo']);                  // handler override

console.log(Object.create(target)['foo']);  // bar
console.log(Object.create(proxy)['foo']);   // handler override

Trap Parameters and the Reflect API

All traps have access to parameters that will allow you to fully re-create the original behavior of the trapped method. For example, the get() method receives a reference to the target object, the property being looked up, and a reference to the proxy object.

const target = {
  foo: 'bar'
};

const handler = {
  get(trapTarget, property, receiver) {
    console.log(trapTarget === target);
    console.log(property);
    console.log(receiver === proxy);
  }
};

const proxy = new Proxy(target, handler);

proxy.foo;
// true
// foo
// true

Thus, it is possible to define a trap handler that wholly re-creates the behavior of the method being trapped:

const target = {
  foo: 'bar'
};

const handler = {
  get(trapTarget, property, receiver) {
    return trapTarget[property];
  }
};

const proxy = new Proxy(target, handler);

console.log(proxy.foo);   // bar
console.log(target.foo);  // bar

Such a tactic can be implemented for all traps, but not all trap behavior is as simple to re-create as get(); therefore, this is an impractical strategy. Instead of manually implementing the contents of the trapped method, the original behavior of the trapped method is wrapped inside an identically named method on the global Reflect object.

Every method that can be trapped inside a handler object has a corresponding Reflect API method. This method has an identical name and function signature, and performs the exact behavior that the trapped method is intercepting. Therefore, it is possible to define a passthrough proxy using only the Reflect API:

const target = {
  foo: 'bar'
};

const handler = {
  get() {
    return Reflect.get(...arguments);
  }
};

const proxy = new Proxy(target, handler);

console.log(proxy.foo);   // bar
console.log(target.foo);  // bar

Alternately, in a more succinct format:

const target = {
  foo: 'bar'
};

const handler = {
  get: Reflect.get
};

const proxy = new Proxy(target, handler);

console.log(proxy.foo);   // bar
console.log(target.foo);  // bar

If you wish to create a true passthrough proxy that traps every available method and forwards each one to its corresponding Reflect API function, defining an explicit handler object is not required:

const target = {
  foo: 'bar'
};

const proxy = new Proxy(target, Reflect);

console.log(proxy.foo);   // bar
console.log(target.foo);  // bar

The Reflect API allows you to modify the trapped method with minimal boilerplate code. For example, the following decorates the return value whenever a certain property is accessed:

const target = {
  foo: 'bar',
  baz: 'qux'
};

const handler = {
  get(trapTarget, property, receiver) {
    let decoration = '';
    if (property === 'foo') {
      decoration = '!!!';
    }

    return Reflect.get(...arguments) + decoration;
  }
};

const proxy = new Proxy(target, handler);

console.log(proxy.foo);   // bar!!!
console.log(target.foo);  // bar

console.log(proxy.baz);   // qux
console.log(target.baz);  // qux

Trap Invariants

Traps give you a broad ability to change how nearly any fundamental method behaves, but they are not without restriction. Each trapped method is aware of the target object context and trap function signature, and the behavior of the trap handler function must obey the “trap invariants” as specified in the ECMAScript specification. Trap invariants vary by method, but in general they will prevent the trap definition from exhibiting any grossly unexpected behavior.

For example, if a target object has a non-configurable and non-writable data property, a TypeError will be thrown if you attempt to return a value from the trap that is different from the target object's property:

const target = {};
Object.defineProperty(target, 'foo', {
  configurable: false,
  writable: false,
  value: 'bar'
});

const handler = {
  get() {
    return 'qux';
  }
};

const proxy = new Proxy(target, handler);

console.log(proxy.foo);
// TypeError

Revocable Proxies

You may find a need for disabling the association between the proxy object and the target object. For a normal proxy created with new Proxy(), this association lasts the lifetime of the proxy object.

Proxy also exposes a revocable() method, which provides you with an additional revoke function that can be called to disassociate the proxy object from the target object. Revoking the proxy is irreversible. Furthermore, the revoke function is idempotent and will not have a further effect if called multiple times. Any method called on a proxy after it is revoked will throw a TypeError.

The revoke function can be captured upon proxy instantiation:

const target = {
  foo: 'bar'
};

const handler = {
  get() {
    return 'intercepted';
  }
};

const { proxy, revoke } = Proxy.revocable(target, handler);

console.log(proxy.foo);   // intercepted
console.log(target.foo);  // bar

revoke();

console.log(proxy.foo);   // TypeError

Utility of the Reflect API

There are a handful of reasons to favor the Reflect API in certain situations.

Reflect API vs. Object API

When diving into the Reflect API, remember:

The Reflect API is not limited to trap handler.
Most Reflect API methods have an analogue on the Object type.

In general, the Object methods are geared for general application use, and the Reflect methods are geared for fine-tuned object control and manipulation.

Status Flags

Many Reflect methods return a Boolean, indicating if the operation they intend to perform will be successful or not. In certain situations, this is more useful than how other Reflect API methods behave, which will either return the modified object or throw an error (depending on the method). For example, you can use the Reflect API to perform the following refactor:

// Initial code

const o = {};

try {
  Object.defineProperty(o, 'foo', 'bar');
  console.log('success');
} catch(e) {
  console.log('failure');
}

In the event of a problem with defining the new property, Reflect.defineProperty will return false instead of throwing an error, enabling you to do the following:

// Refactored code

const o = {};

if(Reflect.defineProperty(o, 'foo', {value: 'bar'})) {
  console.log('success');
} else {
  console.log('failure');
}

The following Reflect methods provide you with status flags:

Reflect.defineProperty
Reflect.preventExtensions
Reflect.setPrototypeOf
Reflect.set
Reflect.deleteProperty

Supplanting Operators with First-Class Functions

Several Reflect methods offer behavior that is available only via operators:

Reflect.get() accesses behavior that is only available otherwise via object property access.
Reflect.set() accesses behavior that is only available otherwise via the = assignment operator.
Reflect.has() accesses behavior that is only available otherwise via the in operator or with().
Reflect.deleteProperty() accesses behavior that is only available otherwise via the delete operator.
Reflect.construct() accesses behavior that is only available otherwise via the new operator.

Safe Function Application

When invoking a function using the apply method, there is a small possibility that the function being called defines its own apply property. To circumvent this, it is possible to pluck the apply method off the Function prototype, as follows:

Function.prototype.apply.call(myFunc, thisVal, argumentList);

This nightmarish line of code can be avoided and fully replicated using Reflect.apply:

Reflect.apply(myFunc, thisVal, argumentsList);

Proxying a Proxy

Proxies are capable of intercepting Reflect API operations, and this means that it is entirely possible to create a proxy of a proxy. This allows you to build multiple layers of indirection on top of a singular target object:

const target = {
  foo: 'bar'
};

const firstProxy = new Proxy(target, {
  get() {
    console.log('first proxy');
    return Reflect.get(...arguments);
  }
});

const secondProxy = new Proxy(firstProxy, {
  get() {
    console.log('second proxy');
    return Reflect.get(...arguments);
  }
});

console.log(secondProxy.foo);
// second proxy
// first proxy
// bar

Proxy Considerations and Shortcomings

Proxies are an API built upon existing ECMAScript infrastructure, and therefore their implementation was best-effort. For the most part, proxies work very well as a virtualization layer for objects. Nevertheless, proxies cannot always seamlessly integrate with existing ECMAScript constructs in certain scenarios.

this Inside a Proxy

One potential source of trouble with proxies is the value of this. As you might expect, the this value inside a method will respect the object upon which it was called:

const target = {
  thisValEqualsProxy() {
    return this === proxy;
  }
}

const proxy = new Proxy(target, {});

console.log(target.thisValEqualsProxy());  // false
console.log(proxy.thisValEqualsProxy());   // true

Intuitively, this should make perfect sense: Any method called on a proxy, proxy.outerMethod(), which in turn calls another method inside its function body, this.innerMethod(), should effectively be invoking proxy.innerMethod(). In most cases, this is certainly the expected behavior; however, if your target relies on object identity, you may encounter unexpected issues.

Recall the WeakMap private variable implementation from Chapter 6, “Advanced Reference Types,” an abridged version of which is displayed here:

const wm = new WeakMap();

class User {
  constructor(userId) {
    wm.set(this, userId);
  }

  set id(userId) {
    wm.set(this, userId);
  }

  get id() {
    return wm.get(this);
  }
}

Because this implementation relies on the object identity of the User instance, it will encounter problems when that instance is proxied:

const user = new User(123);
console.log(user.id);  // 123

const userInstanceProxy = new Proxy(user, {});
console.log(userInstanceProxy.id);  // undefined

The user instance is initially being keyed in the weak map with the target object, but the proxy is attempting to retrieve that instance with the proxy object. The solution to such a problem is to reconfigure the proxying such that the initial key insertion is done with a proxy instance—a feat that can be accomplished by proxying the User class itself, and instantiating a proxy of the class:

const UserClassProxy = new Proxy(User, {});
const proxyUser = new UserClassProxy(456);
console.log(proxyUser.id);

Proxies and Internal Slots

Often, you will find that instances of built-in reference types can work alongside proxies seamlessly, as is the case with Array. However, some ECMAScript built-in types can rely on mechanisms that proxies cannot control. The result of this is that some methods on a wrapped instance will flat out not work properly.

The canonical example of this is the Date type. Per the ECMAScript specification, Date types rely on the existence of an “internal slot” named [[NumberData]] on the this value when executing methods. Because the internal slot does not exist on the proxy, and because these internal slot values are not accessed via the normal get and set operations that a proxy could otherwise intercept and redirect to the target, the method will throw a TypeError:

const target = new Date();
const proxy = new Proxy(target, {});

console.log(proxy instanceof Date);  // true

proxy.getDate();  // TypeError: 'this' is not a Date object

PROXY TRAPS AND REFLECT METHODS

Proxies are able to trap thirteen different fundamental operations. Each has its own entry in the Reflect API, parameters, associated ECMAScript operations, and invariants.

As demonstrated earlier, several different JavaScript operations may invoke the same trap handler. However, for any single operation that is performed on a proxy object, only one trap handler will ever be called; there is no overlap of trap coverage.

All traps will also intercept their corresponding Reflect API operations if they are invoked on the proxy.

get()

The get() trap is called inside operations that retrieve a property value. Its corresponding Reflect API method is Reflect.get().

const myTarget = {};

const proxy = new Proxy(myTarget, {
  get(target, property, receiver) {
    console.log('get()');
    return Reflect.get(...arguments)
  }
});

proxy.foo;
// get()