← Back to glossary

toSorted / toReversed / with — Immutable Array Methods

javascript ES2023 Beginner

Also Known As

toSorted toReversed Array.with immutable array methods ES2023 arrays

TL;DR

JavaScript ES2023 adds immutable counterparts to mutating array methods: toSorted() returns a sorted copy, toReversed() returns a reversed copy, and with(index, value) returns a copy with one element replaced — none mutate the original array.

Explanation

JavaScript's sort(), reverse(), and direct index assignment mutate arrays in place — a common source of bugs when arrays are shared across components or passed to functions. ES2023 standardises immutable alternatives: Array.prototype.toSorted() returns a new sorted array without touching the original. Array.prototype.toReversed() returns a new reversed array. Array.prototype.with(index, value) returns a copy with the element at index replaced with value — equivalent to the spread pattern '[...arr.slice(0, i), value, ...arr.slice(i+1)]' but readable. Array.prototype.toSpliced() is the immutable splice(). These also work on TypedArrays.

Common Misconception

✗ toSorted() is slower because it copies the array. The copy overhead is O(n) — the same cost you pay manually with [...arr].sort(). The clarity and safety benefit is free.

Why It Matters

Accidental mutation of a shared array is one of the most common JS bugs — sort() on a React state array mutates it before the re-render, causing unpredictable behaviour. toSorted() makes immutability the default for these operations. The with() method is particularly valuable in state management: updating one item in an array without spread syntax.

Common Mistakes

Using toSorted() in environments that don't support ES2023 — check browser compatibility or add a polyfill; Node.js 20+ supports all four methods.
Confusing with() with a setter — arr.with(2, 99) returns a new array; arr[2] = 99 mutates in place. They are not interchangeable.
Not using toSorted() in React or similar frameworks where prop mutation causes silent bugs — this is the primary use case for these methods.
Forgetting toSpliced() — toSorted, toReversed, and with() are well-known, but toSpliced() (immutable splice) is less remembered and equally useful.

Code Examples

✗ Vulnerable

// ❌ sort() mutates the original — React state bug
function ProductList({ products }) {
    const sorted = products.sort((a, b) => a.price - b.price);
    // products (the prop) is now mutated!
    // Parent component's state changed without a setState call
    return sorted.map(p => <Product key={p.id} {...p} />);
}

// ❌ Verbose immutable update
const updated = [
    ...items.slice(0, index),
    newItem,
    ...items.slice(index + 1),
];

✓ Fixed

// ✅ toSorted() — original unchanged
function ProductList({ products }) {
    const sorted = products.toSorted((a, b) => a.price - b.price);
    // products is untouched
    return sorted.map(p => <Product key={p.id} {...p} />);
}

// ✅ with() — readable single-item update
const updated = items.with(index, newItem);

// ✅ Full set of ES2023 immutable methods
const arr = [3, 1, 4, 1, 5];
const sorted   = arr.toSorted();          // [1, 1, 3, 4, 5]
const reversed = arr.toReversed();        // [5, 1, 4, 1, 3]
const replaced = arr.with(2, 99);         // [3, 1, 99, 1, 5]
const spliced  = arr.toSpliced(1, 2, 9); // [3, 9, 1, 5]
// arr is still [3, 1, 4, 1, 5] throughout

References

↗ https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toSorted