Homepage ▸ Exploring JavaScript (ES2024 Edition)
You can support this book: buy it or donate
(Ad, please don’t block.)

33 Arrays (Array)

33.1 Cheat sheet: Arrays

JavaScript Arrays are a very flexible data structure and used as lists, stacks, queues, tuples (e.g. pairs), and more.

Some Array-related operations destructively change Arrays. Others non-destructively produce new Arrays with the changes applied to a copy of the original content.

33.1.1 Using Arrays

Creating an Array, reading and writing elements:

// Creating an Array
const arr = ['a', 'b', 'c']; // Array literal
assert.deepEqual(
  arr,
  [ // Array literal
    'a',
    'b',
    'c', // trailing commas are ignored
  ]
);

// Reading elements
assert.equal(
  arr[0], 'a' // negative indices don’t work
);
assert.equal(
  arr.at(-1), 'c' // negative indices work
);

// Writing an element
arr[0] = 'x';
assert.deepEqual(
  arr, ['x', 'b', 'c']
);

The length of an Array:

const arr = ['a', 'b', 'c'];
assert.equal(
  arr.length, 3 // number of elements
);
arr.length = 1; // removing elements
assert.deepEqual(
  arr, ['a']
);
arr[arr.length] = 'b'; // adding an element
assert.deepEqual(
  arr, ['a', 'b']
);

Adding elements destructively via .push():

const arr = ['a', 'b'];

arr.push('c'); // adding an element
assert.deepEqual(
  arr, ['a', 'b', 'c']
);

// Pushing Arrays (used as arguments via spreading (...)):
arr.push(...['d', 'e']);
assert.deepEqual(
  arr, ['a', 'b', 'c', 'd', 'e']
);

Adding elements non-destructively via spreading (...):

const arr1 = ['a', 'b'];
const arr2 = ['c'];
assert.deepEqual(
  [...arr1, ...arr2, 'd', 'e'],
  ['a', 'b', 'c', 'd', 'e']
);

Looping over elements:

const arr = ['a', 'b', 'c'];
for (const value of arr) {
  console.log(value);
}

Output:

a
b
c

Looping over index-value pairs:

const arr = ['a', 'b', 'c'];
for (const [index, value] of arr.entries()) {
  console.log(index, value);
}

Output:

0 a
1 b
2 c

33.1.2 The most commonly used Array methods

This section demonstrates a few common Array methods. There is a more comprehensive quick reference at the end of this chapter.

Destructively adding or removing an Array element at the start or the end:

// Adding and removing at the start
const arr1 = ['■', '●'];
arr1.unshift('▲');
assert.deepEqual(
  arr1, ['▲', '■', '●']
);
arr1.shift();
assert.deepEqual(
  arr1, ['■', '●']
);

// Adding and removing at the end
const arr2 = ['■', '●'];
arr2.push('▲');
assert.deepEqual(
  arr2, ['■', '●', '▲']
);
arr2.pop();
assert.deepEqual(
  arr2, ['■', '●']
);

Finding Array elements:

> ['■', '●', '■'].includes('■')
true
> ['■', '●', '■'].indexOf('■')
0
> ['■', '●', '■'].lastIndexOf('■')
2
> ['●', '', '▲'].find(x => x.length > 0)
'●'
> ['●', '', '▲'].findLast(x => x.length > 0)
'▲'
> ['●', '', '▲'].findIndex(x => x.length > 0)
0
> ['●', '', '▲'].findLastIndex(x => x.length > 0)
2

Transforming Arrays (creating new ones without changing the originals):

> ['▲', '●'].map(x => x+x)
['▲▲', '●●']
> ['■', '●', '■'].filter(x => x === '■') 
['■', '■']
> ['▲', '●'].flatMap(x => [x,x])
['▲', '▲', '●', '●']

Copying parts of an Array:

> ['■', '●', '▲'].slice(1, 3)
['●', '▲']
> ['■', '●', '▲'].slice() // complete copy
['■', '●', '▲']

Concatenating the strings in an Array:

> ['■','●','▲'].join('-')
'■-●-▲'
> ['■','●','▲'].join('')
'■●▲'

.sort() sorts its receiver and returns it (if we don’t want to change the receiver, we can use .toSorted()):

// By default, string representations of the Array elements
// are sorted lexicographically:
const arr = [200, 3, 10];
arr.sort();
assert.deepEqual(
  arr, [10, 200, 3]
);

// Sorting can be customized via a callback:
assert.deepEqual(
  [200, 3, 10].sort((a, z) => a - z), // sort numerically
  [3, 10, 200]
);

33.2 Ways of using Arrays: fixed layout vs. sequence

There are two ways of using Arrays in JavaScript:

Normally, an Array is used in either of these ways. But we can also mix the two approaches.

As an example of the difference between the two ways, consider the Array returned by Object.entries():

> Object.entries({a:1, b:2, c:3})
[
  [ 'a', 1 ],
  [ 'b', 2 ],
  [ 'c', 3 ],
]

It is a sequence of pairs – fixed-layout Arrays with a length of two.

Note that the difference between fixed layout and sequence may not

Sequence Arrays are very flexible that we can use them as (traditional) arrays, stacks, and queues. We’ll see how later.

33.3 Basic Array operations

33.3.1 Creating, reading, writing Arrays

The best way to create an Array is via an Array literal:

const arr = ['a', 'b', 'c'];

The Array literal starts and ends with square brackets []. It creates an Array with three elements: 'a', 'b', and 'c'.

Trailing commas are allowed and ignored in Array literals:

const arr = [
  'a',
  'b',
  'c',
];

To read an Array element, we put an index in square brackets (indices start at zero):

const arr = ['a', 'b', 'c'];
assert.equal(arr[0], 'a');

To change an Array element, we assign to an Array with an index:

const arr = ['a', 'b', 'c'];
arr[0] = 'x';
assert.deepEqual(arr, ['x', 'b', 'c']);

The range of Array indices is 32 bits (excluding the maximum length): [0, 232−1)

33.3.2 The .length of an Array

Every Array has a property .length that can be used to both read and change(!) the number of elements in an Array.

The length of an Array is always the highest index plus one:

> const arr = ['a', 'b'];
> arr.length
2

If we write to the Array at the index of the length, we append an element:

> arr[arr.length] = 'c';
> arr
[ 'a', 'b', 'c' ]
> arr.length
3

Another way of (destructively) appending an element is via the Array method .push():

> arr.push('d');
> arr
[ 'a', 'b', 'c', 'd' ]

If we set .length, we are pruning the Array by removing elements:

> arr.length = 1;
> arr
[ 'a' ]

Icon “exercise” Exercise: Removing empty lines via .push()

exercises/arrays/remove_empty_lines_push_test.mjs

33.3.3 Referring to elements via negative indices

Most Array methods support negative indices. If an index is negative, it is added to the length of an Array to produce a usable index. Therefore, the following two invocations of .slice() are equivalent: They both copy arr starting at the last element.

> const arr = ['a', 'b', 'c'];
> arr.slice(-1)
[ 'c' ]
> arr.slice(arr.length - 1)
[ 'c' ]
33.3.3.1 .at(): reading single elements (supports negative indices) [ES2022]

The Array method .at() returns the element at a given index. It supports positive and negative indices (-1 refers to the last element, -2 refers to the second-last element, etc.):

> ['a', 'b', 'c'].at(0)
'a'
> ['a', 'b', 'c'].at(-1)
'c'

In contrast, the bracket operator [] does not support negative indices (and can’t be changed because that would break existing code). It interprets them as keys of non-element properties:

const arr = ['a', 'b', 'c'];

arr[-1] = 'non-element property';
// The Array elements didn’t change:
assert.deepEqual(
  Array.from(arr), // copy just the Array elements
  ['a', 'b', 'c']
);

assert.equal(
  arr[-1], 'non-element property'
);

33.3.4 Clearing Arrays

To clear (empty) an Array, we can either set its .length to zero:

const arr = ['a', 'b', 'c'];
arr.length = 0;
assert.deepEqual(arr, []);

or we can assign a new empty Array to the variable storing the Array:

let arr = ['a', 'b', 'c'];
arr = [];
assert.deepEqual(arr, []);

The latter approach has the advantage of not affecting other locations that point to the same Array. If, however, we do want to reset a shared Array for everyone, then we need the former approach.

33.3.5 Spreading into Array literals

Inside an Array literal, a spread element consists of three dots (...) followed by an expression. It results in the expression being evaluated and then iterated over. Each iterated value becomes an additional Array element – for example:

> const iterable = ['b', 'c'];
> ['a', ...iterable, 'd']
[ 'a', 'b', 'c', 'd' ]

That means that we can use spreading to create a copy of an Array and to convert an iterable to an Array:

const original = ['a', 'b', 'c'];

const copy = [...original];

const iterable = original.keys();
assert.deepEqual(
  [...iterable], [0, 1, 2]
);

However, for both previous use cases, I find Array.from() more self-descriptive and prefer it:

const copy2 = Array.from(original);

assert.deepEqual(
  Array.from(original.keys()), [0, 1, 2]
);

Spreading is also convenient for concatenating Arrays (and other iterables) into Arrays:

const arr1 = ['a', 'b'];
const arr2 = ['c', 'd'];

const concatenated = [...arr1, ...arr2, 'e'];
assert.deepEqual(
  concatenated,
  ['a', 'b', 'c', 'd', 'e']);

Due to spreading using iteration, it only works if the value is iterable:

> [...'abc'] // strings are iterable
[ 'a', 'b', 'c' ]
> [...123]
TypeError: 123 is not iterable
> [...undefined]
TypeError: undefined is not iterable

Icon “warning” Spreading and Array.from() produce shallow copies

Copying Arrays via spreading or via Array.from() is shallow: We get new entries in a new Array, but the values are shared with the original Array. The consequences of shallow copying are demonstrated in “Spreading into object literals (...)” (§30.4).

33.3.6 Arrays: listing indices and entries

Method .keys() lists the indices of an Array:

const arr = ['a', 'b'];
assert.deepEqual(
  Array.from(arr.keys()), // (A)
  [0, 1]);

.keys() returns an iterable. In line A, we convert that iterable to an Array.

Listing Array indices is different from listing properties. The former produces numbers; the latter produces stringified numbers (in addition to non-index property keys):

const arr = ['a', 'b'];
arr.prop = true;

assert.deepEqual(
  Object.keys(arr),
  ['0', '1', 'prop']);

Method .entries() lists the contents of an Array as [index, element] pairs:

const arr = ['a', 'b'];
assert.deepEqual(
  Array.from(arr.entries()),
  [[0, 'a'], [1, 'b']]);

33.3.7 Checking if a value is an Array: Array.isArray()

Array.isArray() checks if a value is an Array:

> Array.isArray([])
true

We can also use instanceof:

> [] instanceof Array
true

However, instanceof has one downside: It doesn’t work if a value comes from another realm. Roughly, a realm is an instance of JavaScript’s global scope. Some realms are isolated from each other (e.g., Web Workers in browsers), but there are also realms between which we can move data – for example, same-origin iframes in browsers. x instanceof Array checks the prototype chain of x and therefore returns false if x is an Array from another realm.

typeof considers Arrays to be objects:

> typeof []
'object'

33.4 for-of and Arrays

We have already encountered the for-of loop earlier in this book. This section briefly recaps how to use it for Arrays.

33.4.1 for-of: iterating over elements

The following for-of loop iterates over the elements of an Array:

for (const element of ['a', 'b']) {
  console.log(element);
}

Output:

a
b

33.4.2 for-of: iterating over indices

This for-of loop iterates over the indices of an Array:

for (const element of ['a', 'b'].keys()) {
  console.log(element);
}

Output:

0
1

33.4.3 for-of: iterating over [index, element] pairs

The following for-of loop iterates over [index, element] pairs. Destructuring (described later), gives us convenient syntax for setting up index and element in the head of for-of.

for (const [index, element] of ['a', 'b'].entries()) {
  console.log(index, element);
}

Output:

0 a
1 b

33.5 Array-like objects

Some operations that work with Arrays require only the bare minimum: values must only be Array-like. An Array-like value is an object with the following properties:

For example, Array.from() accepts Array-like objects and converts them to Arrays:

// .length is implicitly 0 in this case
assert.deepEqual(
  Array.from({}),
  []
);

assert.deepEqual(
  Array.from({length: 2, 0: 'a', 1: 'b'}),
  [ 'a', 'b' ]
);

The TypeScript interface for Array-like objects is:

interface ArrayLike<T> {
  length: number;
  [n: number]: T;
}

Icon “details” Array-like objects are relatively rare in modern JavaScript

Array-like objects used to be more common before ES6; now we don’t see them very often.

33.6 Converting iterables and Array-like values to Arrays

There are two common ways of converting iterables and Array-like values to Arrays:

I prefer the latter – I find it more self-explanatory.

33.6.1 Converting iterables to Arrays via spreading (...)

Inside an Array literal, spreading via ... converts any iterable object into a series of Array elements. For example:

// Get an Array-like collection from a web browser’s DOM
const domCollection = document.querySelectorAll('a');

// Alas, the collection is missing many Array methods
assert.equal('slice' in domCollection, false);

// Solution: convert it to an Array
const arr = [...domCollection];
assert.deepEqual(
  arr.map(x => x.href),
  ['https://2ality.com', 'https://exploringjs.com']);

The conversion works because the DOM collection is iterable.

33.6.2 Converting iterables and Array-like objects to Arrays via Array.from()

Array.from() can be used in two modes.

33.6.2.1 Mode 1 of Array.from(): converting

The first mode has the following type signature:

.from<T>(iterable: Iterable<T> | ArrayLike<T>): Array<T>

Interface Iterable is shown in the chapter on synchronous iteration. Interface ArrayLike appeared earlier in this chapter.

With a single parameter, Array.from() converts anything iterable or Array-like to an Array:

> Array.from(new Set(['a', 'b'])) // iterable
[ 'a', 'b' ]
> Array.from({length: 2, 0:'a', 1:'b'}) // Array-like
[ 'a', 'b' ]
33.6.2.2 Mode 2 of Array.from(): converting and mapping

The second mode of Array.from() involves two parameters:

.from<T, U>(
  iterable: Iterable<T> | ArrayLike<T>,
  mapFunc: (v: T, i: number) => U,
  thisArg?: any)
  : Array<U>

In this mode, Array.from() does several things:

In other words: we are going from an iterable with elements of type T to an Array with elements of type U.

This is an example:

> Array.from(new Set(['a', 'b']), x => x + x)
[ 'aa', 'bb' ]

33.7 Creating and filling Arrays with arbitrary lengths

The best way of creating an Array is via an Array literal. However, we can’t always use one: The Array may be too large, we may not know its length during development, or we may want to keep its length flexible. Then I recommend the following techniques for creating, and possibly filling, Arrays.

33.7.1 Creating an Array and adding elements later

The most common technique for creating an Array and adding elements later, is to start with an empty Array and push values into it:

const arr = [];
for (let i=0; i<3; i++) {
  arr.push('*'.repeat(i));
}
assert.deepEqual(
  arr, ['', '*', '**']
);

33.7.2 Creating an Array filled with a primitive value

The following code creates an Array that is filled with a primitive value:

> new Array(3).fill(0)
[ 0, 0, 0 ]

.fill() replaces each Array element or hole with a given value. We use it to fill an Array that has 3 holes:

> new Array(3)
[ , , ,]

Note that the result has three holes (empty slots) – the last comma in an Array literal is always ignored.

33.7.3 Creating an Array filled with objects

If we use .fill() with an object, then each Array element will refer to this same single object:

const arr = new Array(3).fill({});
arr[0].prop = true;
assert.deepEqual(
  arr, [
    {prop: true},
    {prop: true},
    {prop: true},
  ]);

How can we fix this? We can use Array.from():

> Array.from(new Array(3), () => ({}))
[{}, {}, {}]

Calling Array.from() with two arguments:

In contrast to .fill(), which reuses the same object multiple times, the previous code creates a new object for each element.

Could we have used .map() in this case? Unfortunately not because .map() ignores but preserves holes (whereas Array.from() treats them as undefined elements):

> new Array(3).map(() => ({}))
[ , , ,]

For large sizes, the temporary Array in the first argument can consume quite a bit of memory. The following approach doesn’t have this downside but is less self-descriptive:

> Array.from({length: 3}, () => ({}))
[{}, {}, {}]

Instead of a temporary Array, we are using a temporary Array-like object.

33.7.4 Creating an Array with a range of integers

To create an Array with a range of integers, we use Array.from() similarly to how we did in the previous subsection:

function createRange(start, end) {
  return Array.from({length: end-start}, (_, i) => i+start);
}
assert.deepEqual(
  createRange(2, 5),
  [2, 3, 4]);

Here is an alternative, slightly hacky technique for creating integer ranges that start at zero:

/** Returns an iterable */
function createRange(end) {
  return new Array(end).keys();
}
assert.deepEqual(
  Array.from(createRange(4)),
  [0, 1, 2, 3]);

This works because .keys() treats holes like undefined elements and lists their indices.

33.7.5 Typed Arrays work well if the elements are all integers or all floats

When dealing with Arrays of integers or floats, we should consider Typed Arrays, which were created for this purpose.

33.8 Multidimensional Arrays

JavaScript does not have real multidimensional Arrays; we need to resort to Arrays whose elements are Arrays:

function initMultiArray(...dimensions) {
  function initMultiArrayRec(dimIndex) {
    if (dimIndex >= dimensions.length) {
      return 0;
    } else {
      const dim = dimensions[dimIndex];
      const arr = [];
      for (let i=0; i<dim; i++) {
        arr.push(initMultiArrayRec(dimIndex+1));
      }
      return arr;
    }
  }
  return initMultiArrayRec(0);
}

const arr = initMultiArray(4, 3, 2);
arr[3][2][1] = 'X'; // last in each dimension
assert.deepEqual(arr, [
  [ [ 0, 0 ], [ 0, 0 ], [ 0, 0 ] ],
  [ [ 0, 0 ], [ 0, 0 ], [ 0, 0 ] ],
  [ [ 0, 0 ], [ 0, 0 ], [ 0, 0 ] ],
  [ [ 0, 0 ], [ 0, 0 ], [ 0, 'X' ] ],
]);

33.9 Arrays are actually dictionaries (advanced)

In this section, we examine how exactly Arrays store their elements: in properties. We usually don’t need to know that but it helps with understanding a few rarer Array phenomena.

33.9.1 Array indices are (slightly special) property keys

You’d think that Array elements are special because we are accessing them via numbers. But the square brackets operator [] for doing so is the same operator that is used for accessing properties. It coerces any non-symbol value to a string. Therefore, Array elements are (almost) normal properties (line A) and it doesn’t matter if we use numbers or strings as indices (lines B and C):

const arr = ['a', 'b'];
arr.prop = 123;
assert.deepEqual(
  Object.keys(arr),
  ['0', '1', 'prop']); // (A)

assert.equal(arr[0], 'a');  // (B)
assert.equal(arr['0'], 'a'); // (C)

To make matters even more confusing:

Property keys (strings!) that are used for Array elements are called indices. A string str is an index if converting it to a 32-bit unsigned integer and back results in the original value. Written as a formula:

ToString(ToUint32(str)) === str
33.9.1.1 Listing indices

When listing property keys, indices are treated specially – they always come first and are sorted like numbers ('2' comes before '10'):

const arr = [];
arr.prop = true;
arr[1] = 'b';
arr[0] = 'a';

assert.deepEqual(
  Object.keys(arr),
  ['0', '1', 'prop']);

Note that .length, .entries() and .keys() treat Array indices as numbers and ignore non-index properties:

assert.equal(arr.length, 2);
assert.deepEqual(
  Array.from(arr.keys()), [0, 1]);
assert.deepEqual(
  Array.from(arr.entries()), [[0, 'a'], [1, 'b']]);

We used Array.from() to convert the iterables returned by .keys() and .entries() to Arrays.

33.9.2 Arrays can have holes

We distinguish two kinds of Arrays in JavaScript:

Arrays can be sparse in JavaScript because Arrays are actually dictionaries from indices to values.

Icon “tip” Recommendation: avoid holes

So far, we have only seen dense Arrays and it’s indeed recommended to avoid holes: They make our code more complicated and are not handled consistently by Array methods. Additionally, JavaScript engines optimize dense Arrays, making them faster.

33.9.2.1 Creating holes

We can create holes by skipping indices when assigning elements:

const arr = [];
arr[0] = 'a';
arr[2] = 'c';

assert.deepEqual(Object.keys(arr), ['0', '2']); // (A)

assert.equal(0 in arr, true); // element
assert.equal(1 in arr, false); // hole

In line A, we are using Object.keys() because arr.keys() treats holes as if they were undefined elements and does not reveal them.

Another way of creating holes is to skip elements in Array literals:

const arr = ['a', , 'c'];

assert.deepEqual(Object.keys(arr), ['0', '2']);

We can also delete Array elements:

const arr = ['a', 'b', 'c'];
assert.deepEqual(Object.keys(arr), ['0', '1', '2']);
delete arr[1];
assert.deepEqual(Object.keys(arr), ['0', '2']);
33.9.2.2 How do Array operations treat holes?

Alas, there are many different ways in which Array operations treat holes.

Some Array operations remove holes:

> ['a',,'b'].filter(x => true)
[ 'a', 'b' ]

Some Array operations ignore holes:

> ['a', ,'a'].every(x => x === 'a')
true

Some Array operations ignore but preserve holes:

> ['a',,'b'].map(x => 'c')
[ 'c', , 'c' ]

Some Array operations treat holes as undefined elements:

> Array.from(['a',,'b'], x => x)
[ 'a', undefined, 'b' ]
> Array.from(['a',,'b'].entries())
[[0, 'a'], [1, undefined], [2, 'b']]

Object.keys() works differently than .keys() (strings vs. numbers, holes don’t have keys):

> Array.from(['a',,'b'].keys())
[ 0, 1, 2 ]
> Object.keys(['a',,'b'])
[ '0', '2' ]

There is no rule to remember here. If it ever matters how an Array operation treats holes, the best approach is to do a quick test in a console.

33.10 Destructive vs. non-destructive Array operations

Some Array operations are destructive: They change the Array they operate on – e.g., setting an element:

> const arr = ['a', 'b', 'c'];
> arr[1] = 'x';
> arr // the original was modified
[ 'a', 'x', 'c' ]

Other Array operations are non-destructive: They produce new Arrays that contain the desired changes and don’t touch the originals – e.g., method .with() is the non-destructive version of setting elements:

> const arr = ['a', 'b', 'c'];
> arr.with(1, 'x') // produces copy with changes
[ 'a', 'x', 'c' ]
> arr // the original is unchanged
[ 'a', 'b', 'c' ]

33.10.1 How to make destructive Array methods non-destructive

These are three common destructive Array methods:

We’ll get to .sort() and .splice() later in this chapter. .reverse() rearranges an Array so that the order of its elements is reversed: The element that was previously last now comes first; the second-last element comes second; etc.:

const original = ['a', 'b', 'c'];
const reversed = original.reverse();

assert.deepEqual(reversed, ['c', 'b', 'a']);
assert.ok(reversed === original); // .reverse() returned `this`
assert.deepEqual(original, ['c', 'b', 'a']);

To prevent a destructive method from changing an Array, we can make a copy before using it – e.g.:

const reversed1 = original.slice().reverse();
const reversed2 = [...original].reverse();
const reversed3 = Array.from(original).reverse();

Another option is to use the non-destructive version of a destructive method. That’s what we’ll explore next.

33.10.2 Non-destructive versions of .reverse(), .sort(), .splice() [ES2023]

These are the non-destructive versions of the destructive Array methods .reverse(), .sort() and .splice():

We have used .reverse() in the previous subsection. Its non-destructive version is used like this:

const original = ['a', 'b', 'c'];
const reversed = original.toReversed();

assert.deepEqual(reversed, ['c', 'b', 'a']);
// The original is unchanged
assert.deepEqual(original, ['a', 'b', 'c']);

33.11 Adding and removing elements at either end of an Array

33.11.1 Destructively adding and removing elements at either end of an Array

JavaScript’s Array is quite flexible and more like a combination of array, stack, and queue. Let’s explore ways of destructively adding and removing Array elements.

.push() adds elements at the end of an Array:

const arr1 = ['a', 'b'];
arr1.push('x', 'y'); // append single elements
assert.deepEqual(arr1, ['a', 'b', 'x', 'y']);

const arr2 = ['a', 'b'];
arr2.push(...['x', 'y']); // (A) append Array
assert.deepEqual(arr2, ['a', 'b', 'x', 'y']);

Spread arguments (...) are a feature of function calls. In line A, we used it to push an Array.

.pop() is the inverse of .push() and removes elements at the end of an Array:

const arr2 = ['a', 'b', 'c'];
assert.equal(arr2.pop(), 'c');
assert.deepEqual(arr2, ['a', 'b']);

.unshift() adds element at the beginning of an Array:

const arr1 = ['a', 'b'];
arr1.unshift('x', 'y'); // prepend single elements
assert.deepEqual(arr1, ['x', 'y', 'a', 'b']);

const arr2 = ['a', 'b'];
arr2.unshift(...['x', 'y']); // prepend Array
assert.deepEqual(arr2, ['x', 'y', 'a', 'b']);

.shift() is the inverse of .unshift() and removes elements at the beginning of an Array:

const arr1 = ['a', 'b', 'c'];
assert.equal(arr1.shift(), 'a');
assert.deepEqual(arr1, ['b', 'c']);

Icon “tip” Tip: remembering the functionality of push, pop, shift and unshift

My recommendation is to focus on remembering the following two methods:

The remaining two methods, pop and unshift, are inverses of these two methods.

Icon “exercise” Exercise: Implementing a queue via an Array

exercises/arrays/queue_via_array_test.mjs

33.11.2 Non-destructively prepending and appending elements

Spread elements (...) are a feature of Array literals. In this section, we’ll use it to non-destructively prepend and append elements to Arrays.

Non-destructive prepending:

const arr1 = ['a', 'b'];
assert.deepEqual(
  ['x', 'y', ...arr1], // prepend single elements
  ['x', 'y', 'a', 'b']);
assert.deepEqual(arr1, ['a', 'b']); // unchanged!

const arr2 = ['a', 'b'];
assert.deepEqual(
  [...['x', 'y'], ...arr2], // prepend Array
  ['x', 'y', 'a', 'b']);
assert.deepEqual(arr2, ['a', 'b']); // unchanged!

Non-destructive appending:

const arr1 = ['a', 'b'];
assert.deepEqual(
  [...arr1, 'x', 'y'], // append single elements
  ['a', 'b', 'x', 'y']);
assert.deepEqual(arr1, ['a', 'b']); // unchanged!

const arr2 = ['a', 'b'];
assert.deepEqual(
  [...arr2, ...['x', 'y']], // append Array
  ['a', 'b', 'x', 'y']);
assert.deepEqual(arr2, ['a', 'b']); // unchanged!

33.12 Array methods that accept element callbacks

The following Array methods accept callbacks to which they feed Array elements:

Element callbacks have type signatures that look as follows:

callback: (value: T, index: number, array: Array<T>) => boolean

That is, the callback gets three parameters (it is free to ignore any of them):

What the callback is expected to return depends on the method it is passed to. Possibilities include:

33.13 Transforming with element callbacks: .map(), .filter(), .flatMap()

In this section, we explore methods that accept element callbacks which tell them how to transform an input Array into an output Array.

33.13.1 .map(): Each output element is derived from its input element

Each element of the output Array is the result of applying the callback to the corresponding input element:

> [1, 2, 3].map(x => x * 3)
[ 3, 6, 9 ]
> ['how', 'are', 'you'].map(str => str.toUpperCase())
[ 'HOW', 'ARE', 'YOU' ]
> [true, true, true].map((_x, index) => index)
[ 0, 1, 2 ]

.map() can be implemented as follows:

function map(arr, mapFunc) {
  const result = [];
  for (const [i, x] of arr.entries()) {
    result.push(mapFunc(x, i, arr));
  }
  return result;
}

Icon “exercise” Exercise: Numbering lines via .map()

exercises/arrays/number_lines_test.mjs

33.13.2 .filter(): Only keep some of the elements

The Array method .filter() returns an Array collecting all elements for which the callback returns a truthy value.

For example:

> [-1, 2, 5, -7, 6].filter(x => x >= 0)
[ 2, 5, 6 ]
> ['a', 'b', 'c', 'd'].filter((_x,i) => (i%2)===0)
[ 'a', 'c' ]

.filter() can be implemented as follows:

function filter(arr, filterFunc) {
  const result = [];
  for (const [i, x] of arr.entries()) {
    if (filterFunc(x, i, arr)) {
      result.push(x);
    }
  }
  return result;
}

Icon “exercise” Exercise: Removing empty lines via .filter()

exercises/arrays/remove_empty_lines_filter_test.mjs

33.13.3 .flatMap(): Replace each input element with zero or more output elements [ES2019]

The type signature of Array<T>.prototype.flatMap() is:

.flatMap<U>(
  callback: (value: T, index: number, array: Array<T>) => U|Array<U>,
  thisValue?: any
): Array<U>

Both .map() and .flatMap() take a function callback as a parameter that controls how an input Array is translated to an output Array:

This is .flatMap() in action:

> ['a', 'b', 'c'].flatMap(x => [x,x])
[ 'a', 'a', 'b', 'b', 'c', 'c' ]
> ['a', 'b', 'c'].flatMap(x => [x])
[ 'a', 'b', 'c' ]
> ['a', 'b', 'c'].flatMap(x => [])
[]

We’ll consider use cases next, before exploring how this method could be implemented.

33.13.3.1 Use case: filtering and mapping at the same time

The result of the Array method .map() always has the same length as the Array it is invoked on. That is, its callback can’t skip Array elements it isn’t interested in. The ability of .flatMap() to do so is useful in the next example.

We will use the following function processArray() to create an Array that we’ll then filter and map via .flatMap():

function processArray(arr, callback) {
  return arr.map(x => {
    try {
      return { value: callback(x) };
    } catch (e) {
      return { error: e };
    }
  });
}

Next, we create an Array results via processArray():

const results = processArray([1, -5, 6], throwIfNegative);
assert.deepEqual(results, [
  { value: 1 },
  { error: new Error('Illegal value: -5') },
  { value: 6 },
]);

function throwIfNegative(value) {
  if (value < 0) {
    throw new Error('Illegal value: '+value);
  }
  return value;
}

We can now use .flatMap() to extract just the values or just the errors from results:

const values = results.flatMap(
  result => result.value ? [result.value] : []);
assert.deepEqual(values, [1, 6]);
  
const errors = results.flatMap(
  result => result.error ? [result.error] : []);
assert.deepEqual(errors, [new Error('Illegal value: -5')]);
33.13.3.2 Use case: mapping single input values to multiple output values

The Array method .map() maps each input Array element to one output element. But what if we want to map it to multiple output elements?

That becomes necessary in the following example:

> stringsToCodePoints(['many', 'a', 'moon'])
['m', 'a', 'n', 'y', 'a', 'm', 'o', 'o', 'n']

We want to convert an Array of strings to an Array of Unicode characters (code points). The following function achieves that via .flatMap():

function stringsToCodePoints(strs) {
  return strs.flatMap(str => Array.from(str));
}
33.13.3.3 A simple implementation

We can implement .flatMap() as follows. Note: This implementation is simpler than the built-in version, which, for example, performs more checks.

function flatMap(arr, mapFunc) {
  const result = [];
  for (const [index, elem] of arr.entries()) {
    const x = mapFunc(elem, index, arr);
    // We allow mapFunc() to return non-Arrays
    if (Array.isArray(x)) {
      result.push(...x);
    } else {
      result.push(x);
    }
  }
  return result;
}

Icon “exercise” Exercises: .flatMap()

33.14 .reduce(): computing a summary for an Array

Method .reduce() is a powerful tool for computing a “summary” of an Array arr. A summary can be any kind of value:

reduce is also known as foldl (“fold left”) in functional programming and popular there. One caveat is that it can make code difficult to understand.

.reduce() has the following type signature (inside an Array<T>):

.reduce<U>(
  callback: (accumulator: U, element: T, index: number, array: Array<T>) => U,
  init?: U)
  : U

T is the type of the Array elements, U is the type of the summary. The two may or may not be different. accumulator is just another name for “summary”.

To compute the summary of an Array arr, .reduce() feeds all Array elements to its callback one at a time:

const accumulator_0 = callback(init, arr[0]);
const accumulator_1 = callback(accumulator_0, arr[1]);
const accumulator_2 = callback(accumulator_1, arr[2]);
// Etc.

callback combines the previously computed summary (stored in its parameter accumulator) with the current Array element and returns the next accumulator. The result of .reduce() is the final accumulator – the last result of callback after it has visited all elements.

In other words: callback does most of the work; .reduce() just invokes it in a useful manner.

We could say that the callback folds Array elements into the accumulator. That’s why this operation is called “fold” in functional programming.

Example: applying a binary operator to a whole Array

Let’s look at an example of .reduce() in action: function addAll() computes the sum of all numbers in an Array arr.

function addAll(arr) {
  const startSum = 0;
  const callback = (sum, element) => sum + element;
  return arr.reduce(callback, startSum);
}
assert.equal(addAll([1,  2, 3]), 6); // (A)
assert.equal(addAll([7, -4, 2]), 5);

In this case, the accumulator holds the sum of all Array elements that callback has already visited.

How was the result 6 derived from the Array in line A? Via the following invocations of callback:

callback(0, 1) --> 1
callback(1, 2) --> 3
callback(3, 3) --> 6

Notes:

Alternatively, we could have implemented addAll() via a for-of loop:

function addAll(arr) {
  let sum = 0;
  for (const element of arr) {
    sum = sum + element;
  }
  return sum;
}

It’s hard to say which of the two implementations is “better”: the one based on .reduce() is a little more concise, while the one based on for-of may be a little easier to understand – especially if someone is not familiar with functional programming.

Example: finding indices via .reduce()

The following function is an implementation of the Array method .indexOf(). It returns the first index at which the given searchValue appears inside the Array arr:

const NOT_FOUND = -1;
function indexOf(arr, searchValue) {
  return arr.reduce(
    (result, elem, index) => {
      if (result !== NOT_FOUND) {
        // We have already found something: don’t change anything
        return result;
      } else if (elem === searchValue) {
        return index;
      } else {
        return NOT_FOUND;
      }
    },
    NOT_FOUND);
}
assert.equal(indexOf(['a', 'b', 'c'], 'b'), 1);
assert.equal(indexOf(['a', 'b', 'c'], 'x'), -1);

One limitation of .reduce() is that we can’t finish early. In a for-of loop, we can immediately return the result once we have found it.

Example: doubling Array elements

Function double(arr) returns a copy of inArr whose elements are all multiplied by 2:

function double(inArr) {
  return inArr.reduce(
    (outArr, element) => {
      outArr.push(element * 2);
      return outArr;
    },
    []);
}
assert.deepEqual(
  double([1, 2, 3]),
  [2, 4, 6]);

We modify the initial value [] by pushing into it. A non-destructive, more functional version of double() looks as follows:

function double(inArr) {
  return inArr.reduce(
    // Don’t change `outArr`, return a fresh Array
    (outArr, element) => [...outArr, element * 2],
    []);
}
assert.deepEqual(
  double([1, 2, 3]),
  [2, 4, 6]);

This version is more elegant but also slower and uses more memory.

Icon “exercise” Exercises: .reduce()

33.14.1 .reduceRight(): the end-to-start version of .reduce()

.reduce() visits elements from start to end:

> ['a', 'b', 'c'].reduce((acc, x) => acc + x)
'abc'

.reduceRight() has the same functionality but visits elements from end to start:

> ['a', 'b', 'c'].reduceRight((acc, x) => acc + x)
'cba'

33.15 .sort(): sorting Arrays

.sort() has the following type definition:

sort(compareFunc?: (a: T, b: T) => number): this

By default, .sort() sorts string representations of the elements. These representations are compared via <. This operator compares code unit values (char codes) lexicographically (the first characters are most significant).

.sort() sorts in place; it changes and returns its receiver:

> const arr = ['a', 'c', 'b'];
> arr.sort() === arr
true
> arr
[ 'a', 'b', 'c' ]

Icon “details” .sort() is stable

Since ECMAScript 2019, sorting is guaranteed to be stable: If elements are considered equal by sorting, then sorting does not change the order of those elements (relative to each other).

33.15.1 Customizing the sort order

We can customize the sort order via the parameter compareFunc, which must return a number that is:

We’ll see an example of a compare function in the next subsection.

Icon “tip” Tip for remembering these rules

A negative number is less than zero (etc.).

33.15.2 Sorting numbers

Lexicographical sorting doesn’t work well for numbers:

> [200, 3, 10].sort()
[ 10, 200, 3 ]

We can fix this by writing a compare function:

function compareNumbers(a, b) {
  if (a < b) {
    return -1; // any negative number will do
  } else if (a === b) {
    return 0;
  } else {
    return 1; // any positive number will do
  }
}
assert.deepEqual(
  [200, 3, 10].sort(compareNumbers),
  [3, 10, 200]
);

Icon “question” Why doesn’t .sort() automatically pick the right sorting approach for numbers?

It would have to examine all Array elements and make sure that they are numbers before switching from lexicographical sorting to numeric sorting.

33.15.3 A trick for sorting numbers

The following trick uses the fact that (e.g.) the result for “less than” can be any negative number:

> [200, 3, 10].sort((a, z) => a - z)
[ 3, 10, 200 ]

33.15.4 Sorting human-language strings

When sorting human-language strings, we need to be aware that they are compared according to their code unit values (char codes):

> ['pie', 'cookie', 'éclair', 'Pie', 'Cookie', 'Éclair'].sort()
[ 'Cookie', 'Pie', 'cookie', 'pie', 'Éclair', 'éclair' ]

All unaccented uppercase letters come before all unaccented lowercase letters, which come before all accented letters. We can use Intl, the JavaScript internationalization API if we want proper sorting for human languages:

const arr = ['pie', 'cookie', 'éclair', 'Pie', 'Cookie', 'Éclair'];
assert.deepEqual(
  arr.sort(new Intl.Collator('en').compare),
  ['cookie', 'Cookie', 'éclair', 'Éclair', 'pie', 'Pie']
);

33.15.5 Sorting objects

We also need to use a compare function if we want to sort objects. As an example, the following code shows how to sort objects by age.

const arr = [ {age: 200}, {age: 3}, {age: 10} ];
assert.deepEqual(
  arr.sort((obj1, obj2) => obj1.age - obj2.age),
  [{ age: 3 }, { age: 10 }, { age: 200 }]
);

Icon “exercise” Exercise: Sorting objects by name

exercises/arrays/sort_objects_test.mjs

33.16 Arrays can use operations for iterables

Arrays are iterable and therefore can use operations that accept iterables. These are described elsewhere:

33.17 Quick reference: Array

Legend:

Negative indices: If a method supports negative indices that means that such indices are added to .length before they are used: -1 becomes this.length-1, etc. In other words: -1 refers to the last element, -2 to the second-last element, etc. .at() is one method that supports negative indices:

const arr = ['a', 'b', 'c'];
assert.equal(
  arr.at(-1), 'c'
);

33.17.1 new Array()

33.17.2 Array.*

33.17.3 Array.prototype.*: getting, setting and visiting single elements

33.17.4 Array.prototype.*: keys and values

33.17.5 Array.prototype.*: destructively adding or removing elements at either end of an Array

33.17.6 Array.prototype.*: combining, extracting and changing sequences of elements

Icon “tip” Tip: telling .slice() and .splice() apart

33.17.7 Array.prototype.*: searching for elements

33.17.8 Array.prototype.*: filtering and mapping

33.17.9 Array.prototype.*: computing summaries

33.17.10 Array.prototype.*: converting to string

33.17.11 Array.prototype.*: sorting and reversing

33.17.12 Sources of the quick reference

Comments
Next: Typed Arrays: handling binary data [ES6] (advanced)