API flashcards

new Array(len = 0) [ES1]

Creates an Array of length len that only contains holes:

// Trailing commas are always ignored.
// Therefore: number of commas = number of holes
assert.deepEqual(new Array(3), [,,,]);

Array.from(iterableOrArrayLike, mapFunc?) [ES6]

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

• Converts an iterable or an Array-like object to an Array.
• Optionally, the input values can be translated via mapFunc before they are added to the output Array.

Examples:

> Array.from(new Set(['a', 'b'])) // iterable
[ 'a', 'b' ]
> Array.from({length: 2, 0:'a', 1:'b'}) // Array-like object
[ 'a', 'b' ]

Array.of(...items) [ES6]

Array.of<T>(
  ...items: Array<T>
): Array<T>

This static method is mainly useful for subclasses of Array, where it serves as a custom Array literal:

class MyArray extends Array {}

assert.equal(
  MyArray.of('a', 'b') instanceof MyArray, true
);

Array.prototype.at(index) [ES2022 | Non-mutating]

• Returns the Array element at index. If there is no such element, it returns undefined.

This method is mostly equivalent to getting elements via square brackets:

arr[index] === arr.at(index)

One reason for using .at() is that it supports negative indices:

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

Array.prototype.with(index, value) [ES2023 | Non-mutating]

• Returns the receiver of the method call, with one different element: At index, there is now value.

This method is the non-destructive version of setting elements via square brackets. It supports negative indices:

> ['a', 'b', 'c'].with(2, 'x')
[ 'a', 'b', 'x' ]
> ['a', 'b', 'c'].with(-1, 'x')
[ 'a', 'b', 'x' ]

Array.prototype.forEach(callback) [ES5 | Non-mutating]

Array<T>.prototype.forEach(
  callback: (value: T, index: number, array: Array<T>) => void,
  thisArg?: any
): void

Calls callback for each element.

['a', 'b'].forEach(
  (elem) => console.log(elem)
);
['a', 'b'].forEach(
  (elem, index) => console.log(elem, index)
);

Output:

a
b
a 0
b 1

A for-of loop is usually a better choice: it’s faster, supports break and can iterate over arbitrary iterables.

Array.prototype.keys() [ES6 | Non-mutating]

Returns an iterable over the keys of the receiver.

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

Array.prototype.values() [ES6 | Non-mutating]

Returns an iterable over the values of the receiver.

> Array.from(['a', 'b'].values())
[ 'a', 'b' ]

Array.prototype.entries() [ES6 | Non-mutating]

Returns an iterable over [index, element] pairs.

> Array.from(['a', 'b'].entries())
[ [ 0, 'a' ], [ 1, 'b' ] ]

Array.prototype.pop() [ES3 | Mutating]

Removes and returns the last element of the receiver. That is, it treats the end of the receiver as a stack. The opposite of .push().

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

Array.prototype.push(...items) [ES3 | Mutating]

Adds zero or more items to the end of the receiver. That is, it treats the end of the receiver as a stack. The return value is the length of the receiver after the change. The opposite of .pop().

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

We can push an Array by spreading (...) it into arguments:

> const arr = ['x'];
> arr.push(...['y', 'z'])
3
> arr
[ 'x', 'y', 'z' ]  

Array.prototype.shift() [ES3 | Mutating]

Removes and returns the first element of the receiver. The inverse of .unshift().

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

Array.prototype.unshift(...items) [ES3 | Mutating]

Inserts the items at the beginning of the receiver and returns its length after this modification.

> const arr = ['c', 'd'];
> arr.unshift('e', 'f')
4
> arr
[ 'e', 'f', 'c', 'd' ]

We can push an Array by spreading (...) it into arguments:

> const arr = ['c'];
> arr.unshift(...['a', 'b'])
3
> arr
[ 'a', 'b', 'c' ]

Array.prototype.concat(...items) [ES3 | Non-mutating]

Returns a new Array that is the concatenation of the receiver and all items. Non-Array parameters (such as 'b' in the following example) are treated as if they were Arrays with single elements.

> ['a'].concat('b', ['c', 'd'])
[ 'a', 'b', 'c', 'd' ]

Array.prototype.slice(start?, end?) [ES3 | Non-mutating]

Returns a new Array containing the elements of the receiver whose indices are between (including) start and (excluding) end.

> ['a', 'b', 'c', 'd'].slice(1, 3)
[ 'b', 'c' ]
> ['a', 'b'].slice() // shallow copy
[ 'a', 'b' ]

.slice() supports negative indices:

> ['a', 'b', 'c'].slice(-2)
[ 'b', 'c' ]

It can be used to (shallowly) copy Arrays:

const copy = original.slice();

Array.prototype.splice(start?, deleteCount?, ...items) [ES3 | Mutating]

• At index start,
• removes deleteCount elements (default: all remaining elements) and
• replaces them with items.
• It returns the deleted elements.
• The non-destructive version of this method is .toSpliced().

> const arr = ['a', 'b', 'c', 'd'];
> arr.splice(1, 2, 'x', 'y')
[ 'b', 'c' ]
> arr
[ 'a', 'x', 'y', 'd' ]

If deleteCount is missing, .splice() deletes until the end of the Array:

> const arr = ['a', 'b', 'c', 'd'];
> arr.splice(2)
[ 'c', 'd' ]
> arr
[ 'a', 'b' ]

start can be negative:

> ['a', 'b', 'c'].splice(-2)
[ 'b', 'c' ]

Array.prototype.toSpliced(start?, deleteCount?, ...items) [ES2023 | Non-mutating]

• Creates a new Array where, starting at index start, deleteCount elements are replaced with items.
• If deleteCount is missing, all elements from start until the end are deleted.
• The destructive version of this method is .splice().

> const arr = ['a', 'b', 'c', 'd'];
> arr.toSpliced(1, 2, 'x', 'y')
[ 'a', 'x', 'y', 'd' ]

start can be negative:

> ['a', 'b', 'c'].toSpliced(-2)
[ 'a' ]

Array.prototype.fill(start=0, end=this.length) [ES6 | Mutating]

• Returns this.
• Assigns value to every index between (including) start and (excluding) end.

> [0, 1, 2].fill('a')
[ 'a', 'a', 'a' ]

Caveat: Don’t use this method to fill an Array with an object obj; then each element will refer to the same value (sharing it). In this case, it’s better to use Array.from().

Array.prototype.copyWithin(target, start, end=this.length) [ES6 | Mutating]

• Returns this.

Copies the elements whose indices range from (including) start to (excluding) end to indices starting with target. Overlapping is handled correctly.

> ['a', 'b', 'c', 'd'].copyWithin(0, 2, 4)
[ 'c', 'd', 'c', 'd' ]

start or end can be negative.

Array.prototype.includes(searchElement, fromIndex) [ES2016 | Non-mutating]

Returns true if the receiver has an element whose value is searchElement and false, otherwise. Searching starts at index fromIndex.

> [0, 1, 2].includes(1)
true
> [0, 1, 2].includes(5)
false

Array.prototype.indexOf(searchElement, fromIndex) [ES5 | Non-mutating]

Returns the index of the first element that is strictly equal to searchElement. Returns -1 if there is no such element. Starts searching at index fromIndex, visiting higher indices next.

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

Array.prototype.lastIndexOf(searchElement, fromIndex) [ES5 | Non-mutating]

Returns the index of the last element that is strictly equal to searchElement. Returns -1 if there is no such element. Starts searching at index fromIndex, visiting lower indices next.

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

Array.prototype.find(predicate, thisArg?) [ES6 | Non-mutating]

Array<T>.prototype.find(
  predicate: (value: T, index: number, obj: Array<T>) => boolean,
  thisArg?: any
): T | undefined

• Traverses an Array from start to end.
• Returns the value of the first element for which predicate returns a truthy value.
• If there is no such element, it returns undefined.

> [-1, 2, -3].find(x => x < 0)
-1
> [1, 2, 3].find(x => x < 0)
undefined

Array.prototype.findLast(predicate, thisArg?) [ES2023 | Non-mutating]

Array<T>.prototype.findLast(
  predicate: (value: T, index: number, obj: Array<T>) => boolean,
  thisArg?: any
): T | undefined

• Traverses an Array from end to start.
• Returns the value of the first element for which predicate returns a truthy value.
• If there is no such element, it returns undefined.

> [-1, 2, -3].findLast(x => x < 0)
-3
> [1, 2, 3].findLast(x => x < 0)
undefined

Array.prototype.findIndex(predicate, thisArg?) [ES6 | Non-mutating]

Array<T>.prototype.findIndex(
  predicate: (value: T, index: number, obj: Array<T>) => boolean,
  thisArg?: any
): number

• Traverses an Array from start to end.
• Returns the index of the first element for which predicate returns a truthy value.
• If there is no such element, it returns -1.

> [-1, 2, -3].findIndex(x => x < 0)
0
> [1, 2, 3].findIndex(x => x < 0)
-1

Array.prototype.findLastIndex(predicate, thisArg?) [ES2023 | Non-mutating]

Array<T>.prototype.findLastIndex(
  predicate: (value: T, index: number, obj: Array<T>) => boolean,
  thisArg?: any
): number

• Traverses an Array from end to start.
• Returns the index of the first element for which predicate returns a truthy value.
• If there is no such element, it returns -1.

> [-1, 2, -3].findLastIndex(x => x < 0)
2
> [1, 2, 3].findLastIndex(x => x < 0)
-1

Array.prototype.filter(predicate, thisArg?) [ES5 | Non-mutating]

Array<T>.prototype.filter(
  predicate: (value: T, index: number, array: Array<T>) => boolean,
  thisArg?: any
): Array<T>

Returns an Array with only those elements for which predicate returns a truthy value.

> [1, -2, 3].filter(x => x > 0)
[ 1, 3 ]

Array.prototype.map(callback, thisArg?) [ES5 | Non-mutating]

Array<T>.prototype.map<U>(
  mapFunc: (value: T, index: number, array: Array<T>) => U,
  thisArg?: any
): Array<U>

Returns a new Array, in which every element is the result of mapFunc being applied to the corresponding element of the receiver.

> [1, 2, 3].map(x => x * 2)
[ 2, 4, 6 ]
> ['a', 'b', 'c'].map((x, i) => i)
[ 0, 1, 2 ]

Array.prototype.flatMap(callback, thisArg?) [ES2019 | Non-mutating]

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

The result is produced by invoking callback() for each element of the original Array and concatenating the Arrays it returns.

> ['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 => [])
[]

Array.prototype.flat(depth = 1) [ES2019 | Non-mutating]

“Flattens” an Array: It descends into the Arrays that are nested inside the input Array and creates a copy where all values it finds at level depth or lower are moved to the top level.

> [ 1,2, [3,4], [[5,6]] ].flat(0) // no change
[ 1, 2, [3,4], [[5,6]] ]

> [ 1,2, [3,4], [[5,6]] ].flat(1)
[1, 2, 3, 4, [5,6]]

> [ 1,2, [3,4], [[5,6]] ].flat(2)
[1, 2, 3, 4, 5, 6]

Array.prototype.every(predicate, thisArg?) [ES5 | Non-mutating]

Array<T>.prototype.every(
  predicate: (value: T, index: number, array: Array<T>) => boolean,
  thisArg?: any
): boolean

Returns true if predicate returns a truthy value for every element. Otherwise, it returns false:

> [1, 2, 3].every(x => x > 0)
true
> [1, -2, 3].every(x => x > 0)
false

• Stops traversing an Array if the predicate returns a falsy value (because then the result is guaranteed to be false).
• Corresponds to universal quantification (“for all”, ∀) in mathematics.
• Related method: .some() (“exists”).

Array.prototype.some(predicate, thisArg?) [ES5 | Non-mutating]

Array<T>.prototype.some(
  predicate: (value: T, index: number, array: Array<T>) => boolean,
  thisArg?: any
): boolean

Returns true if predicate returns a truthy value for at least one element. Otherwise, it returns false.

> [1, 2, 3].some(x => x < 0)
false
> [1, -2, 3].some(x => x < 0)
true

• Stops traversing an Array if the predicate returns a truthy value (because then the result is guaranteed to be true).
• Corresponds to existential quantification (“exists”, ∃) in mathematics.
• Related method: .every() (“for all”).

Array.prototype.reduce(callback, initialValue?) [ES5 | Non-mutating]

Array<T>.prototype.reduce<U>(
  callback: (accumulator: U, elem: T, idx: number, arr: Array<T>) => U,
  initialValue?: U
): U

This method produces a summary of the receiver: it feeds all Array elements to callback, which combines a current summary (in parameter accumulator) with the current Array element and returns the next accumulator:

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

The result of .reduce() is the last result of callback after it has visited all Array elements.

> [1, 2, 3].reduce((accu, x) => accu + x, 0)
6
> [1, 2, 3].reduce((accu, x) => accu + String(x), '')
'123'

If no initialValue is provided, the Array element at index 0 is used and the element at index 1 is visited first. Therefore, the Array must have at least length 1.

Array.prototype.reduceRight(callback, initialValue?) [ES5 | Non-mutating]

Array<T>.prototype.reduceRight<U>(
  callback: (accumulator: U, elem: T, idx: number, arr: Array<T>) => U,
  initialValue?: U
): U

Works like .reduce(), but visits the Array elements backward, starting with the last element.

> [1, 2, 3].reduceRight((accu, x) => accu + String(x), '')
'321'

Array.prototype.join(separator = ',') [ES1 | Non-mutating]

Creates a string by concatenating string representations of all elements, separating them with separator.

> ['a', 'b', 'c'].join('##')
'a##b##c'
> ['a', 'b', 'c'].join()
'a,b,c'

Array.prototype.toString() [ES1 | Non-mutating]

Converts all elements to strings via String(), concatenates them while separating them with commas, and returns the result.

> [1, 2, 3].toString()
'1,2,3'
> ['1', '2', '3'].toString()
'1,2,3'
> [].toString()
''

Array.prototype.toLocaleString() [ES3 | Non-mutating]

Works like .toString() but converts its elements to strings via .toLocaleString() (not via .toString()) before separating them via commas and concatenating them to a single string – that it returns.

Array.prototype.sort(compareFunc?) [ES1 | Mutating]

Array<T>.prototype.sort(
  compareFunc?: (a: T, b: T) => number
): this

• Sorts the receiver and returns it.
• The non-destructive version of this method is .toSorted().
• Sorts string representations of the elements lexicographically.

Sorting numbers:

// Default: lexicographical sorting
assert.deepEqual(
  [200, 3, 10].sort(),
  [10, 200, 3]
);

// Ascending numerical sorting (“from a to z”)
assert.deepEqual(
  [200, 3, 10].sort((a, z) => a - z),
  [3, 10, 200]
);

Sorting strings: By default, strings are sorted by code unit values (char codes), where, e.g., all unaccented uppercase letters come before all unaccented lowercase letters:

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

For human languages, we can use Intl.Collator:

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

Array.prototype.toSorted(compareFunc?) [ES2023 | Non-mutating]

Array<T>.prototype.toSorted.toSorted(
  compareFunc?: (a: T, b: T) => number
): Array<T>

• Returns a sorted copy of the current Array.
• The destructive version of this method is .sort().

const original = ['y', 'z', 'x'];
const sorted = original.toSorted();
assert.deepEqual(
  // The original is unchanged
  original, ['y', 'z', 'x']
);
assert.deepEqual(
  // The copy is sorted
  sorted, ['x', 'y', 'z']
);

See the description of .sort() for more information on how to use this method.

Array.prototype.reverse() [ES1 | Mutating]

Rearranges the elements of the receiver so that they are in reverse order and then returns the receiver.

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

The non-destructive version of this method is .toReversed().

Array.prototype.toReversed() [ES2023 | Non-mutating]

• Returns a reversed copy of the current Array.
• The destructive version of this method is .reverse().

const original = ['x', 'y', 'z'];
const reversed = original.toReversed();
assert.deepEqual(
  // The original is unchanged
  original, ['x', 'y', 'z']
);
assert.deepEqual(
  // The copy is reversed
  reversed, ['z', 'y', 'x']
);