Every array method, what it returns, what it mutates

The mutation rule, and the immutable four

Nine methods mutate the array they are called on: push, pop, shift, unshift, splice, sort, reverse, fill, and copyWithin. Everything else returns something new. Memorize that list and the rest of this page is reference rather than trivia.

Since ES2023 there are non-mutating twins for the awkward ones, and they are the right default in React, Redux, Zustand, or anywhere else state is compared by reference.

const a = [3, 1, 2];

a.sort();          // MUTATES a, returns the same array
a.toSorted();      // [1, 2, 3] - a is untouched
a.toReversed();    // [2, 1, 3] - a is untouched
a.toSpliced(1, 1); // [3, 2]    - a is untouched
a.with(0, 99);     // [99, 1, 2] - a is untouched

// The old workaround, still fine and still common:
const sorted = [...a].sort();

Gotcha: the four immutable methods are copies, not deep clones. Objects inside the new array are still the same objects. For a real deep copy use structuredClone(arr).

Add and remove elements

This group is where almost all of the mutation lives.

Gotcha: push returns a number, so const next = arr.push(x) gives you a length, not the array. Chaining after push is almost always a bug.

Transform

Gotcha: reduce without an initial value uses element 0 as the seed and throws on an empty array. Always pass the second argument; it also gives TypeScript something to infer from.

Sort and order

Gotcha: a bare sort() converts every element to a string first, so [10, 9, 1].sort() gives [1, 10, 9]. Numbers always need a comparator.

Async patterns over arrays

There is no async version of map or filter. You combine map with a promise combinator, and the combinator you choose is the whole decision.

// Parallel, all must succeed. First rejection wins and the rest keep running.
const users = await Promise.all(ids.map(id => fetchUser(id)));

// Parallel, collect every outcome. Never rejects.
const results = await Promise.allSettled(ids.map(fetchUser));
const ok = results.filter(r => r.status === "fulfilled").map(r => r.value);

// First success wins; rejects only if every one fails.
const fastest = await Promise.any(mirrors.map(fetchFrom));

// First settled outcome wins, success or failure. Usually a timeout race.
const raced = await Promise.race([fetchUser(id), timeout(3000)]);

// Sequential, because order or rate limits matter.
const out = [];
for (const id of ids) out.push(await fetchUser(id));

// Async filter: map to predicates in parallel, then zip.
const flags = await Promise.all(items.map(isValid));
const valid = items.filter((_, i) => flags[i]);

// Bounded concurrency without a library: chunk, then run each chunk in parallel.
const chunk = (a, n) =>
  Array.from({ length: Math.ceil(a.length / n) }, (_, i) => a.slice(i * n, i * n + n));
for (const batch of chunk(ids, 5)) await Promise.all(batch.map(fetchUser));

// Drain an async iterable straight into an array.
const lines = await Array.fromAsync(readLines(file));

Gotcha: ids.map(async id => ...) returns an array of promises, not values. Forgetting the await Promise.all(...) around it produces an array full of Promise { pending }, which usually surfaces much later as a rendering bug.

Gotcha: callbacks receive three arguments. ["1","7","11"].map(parseInt) gives [1, NaN, 3] because the index is passed as the radix. Wrap it: .map(s => parseInt(s, 10)), or use .map(Number).