Sorting & copying safely

Put a list in order

Lists often come in the wrong order. Messages may come newest first. Prices may be mixed up. Names from a form come in the order people typed them.

To sort a list means to put its items in order. JavaScript arrays have methods that sort. Each time you sort, ask two questions:

• What rule decides the order? For example, smallest number first.
• Should the original array change? Or should you get a new, sorted array and keep the original as it was?

This lesson uses three things from earlier lessons:

• From Comparisons: text is compared one character at a time, using each character's code. Capital letters come before small letters, so "Zebra" < "apple" is true. And "10" < "9" is true too, because 1 comes before 9.
• From Objects & references: two variables can point at the same array. A change made through one variable shows up through the other.
• From Arrow functions: short functions such as (a, b) => a - b.

const prices = [30, 10, 20];
const sortedPrices = prices.toSorted((a, b) => a - b);
console.log(sortedPrices.join(", "));

Line 1 makes a short list of prices. Line 2 calls toSorted. It makes a new array, sorts it, and returns it. The original array is not touched. The function (a, b) => a - b is the rule: smaller numbers first. Line 3 prints 10, 20, 30. The prices array still holds 30, 10, 20.

The lesson goes in this order:

1. The default sort rule, and why it surprises people with numbers.
2. Your own rules, for numbers and for objects.
3. Methods that change the original array: sort and reverse.
4. Newer methods that return a changed copy instead: toSorted, toReversed, toSpliced, and with.
5. Stable sorting, which keeps tied items in their first order.

array.sort() puts the items of an array in order. It changes the original array: the items move around inside it.

If you call sort() with nothing in the brackets, it uses the default rule:

• Each item is turned into text. The number 100 becomes the text "100".
• The texts are compared one character at a time, from the left.
• undefined items are not turned into text. They always go to the end.

This rule works for simple words. For numbers it is a trap: the text "100" starts with 1, so it comes before "9".

Step through the code below to see this happen. Then pick another rule: smallest number first, largest number first, or one example with localeCompare.

localeCompare compares words the way people expect in a language, such as English. It has its own lesson in the next module, Comparing & sorting text. For now, remember one thing: for words that people read, the default rule is not the right tool.

1const numbers = [10, 9, 1, 100];Run2const sorted = numbers.sort();3console.log(sorted.join(", "));

To use your own rule, pass a function to sort. This function is called a comparator. sort calls it with two items, a and b. The comparator returns a number:

• A negative number (below 0) means a goes first.
• A positive number (above 0) means b goes first.
• 0 means a tie, so the two keep their order.

For numbers, the usual rule for smallest first is (a, b) => a - b. If a is smaller, a - b is negative, so a goes first. For largest first, swap the two: (a, b) => b - a.

For objects, compare the property you care about, such as a.age - b.age. To break a tie, add a second comparison after ||. The second comparison is used only when the first one gives 0. You can try this in the playground below.

const prices = [3, 1, 2];
const sorted = prices.toSorted((a, b) => a - b);

console.log(sorted.join(", "));
console.log(prices.join(", "));

A comparator must be consistent. That means the same two items must always give the same answer, every time sort asks. So inside a comparator, don't:

• read values that can change while the sort runs,
• use random numbers,
• change the array.

This code prints 1, 2, 3 and then 3, 1, 2. toSorted sorted a copy, so prices kept its first order.

1const sorted = [...people].sort((a, b) => {2  return a.age - b.age;3});

reverse() flips the order of an array: the last item becomes the first. It is simpler than sort(), but it has the same risk:

• It changes the original array.
• It returns that same array, not a new one.

Changing the original array is called mutating it. That is fine for an array that only one small piece of code uses. It is risky for an array that other code also reads later, such as a list of products shared across your app.

1const numbers = [3, 1, 2];Run2const sortedReturn = numbers.sort((a, b) => a - b);3console.log(numbers.join(", "));4console.log(numbers === sortedReturn);5const reversedReturn = numbers.reverse();6console.log(numbers.join(", "));7console.log(numbers === reversedReturn);

Here is the bug this causes. Say you have two variables, visibleProducts and allProducts. Both point at the same array. You sort visibleProducts with sort(). Now allProducts is in the new order too, with no warning.

You saw this rule in Objects & references: a change made through one variable shows up through every variable that points at the same object. Arrays are objects, so they follow the same rule.

1const prices = [30, 10, 20];2const lowToHigh = [...prices].sort((a, b) => a - b);3const highToLow = prices.slice().sort((a, b) => b - a);4 5console.log(prices);    // [30, 10, 20]6console.log(lowToHigh); // [10, 20, 30]

Line 2 copies the array with spread, [...prices]. Line 3 copies it with slice(). Each line then sorts its own copy, so prices keeps its order.

These are shallow copies. You get a new array, but the items inside are not copied. If the items are objects, both arrays hold the same objects.

const rows = [{ product: "Tea", price: 3 }];
const copy = [...rows];
copy[0].price = 4;

console.log(rows[0].price);
console.log(rows === copy);

Line 1 makes an array with one object in it, a row. Line 2 copies the array. Line 3 changes the price through the copy. The output is 4 and then false:

• 4: the original row changed too, because both arrays hold the same row object.
• false: the two arrays themselves are different arrays.

If you need to change the objects inside, copy those objects too.

Newer JavaScript has a copying partner for each method that changes the array. The copying partner returns a new, changed array. The original array stays as it was.

For example, sort() moves the items inside the original array. toSorted() makes a new array, sorts that, and returns it.

Each row of the table below is one change you might want. The middle column changes the original array. The last column gives you a changed copy instead.

1const letters = ["A", "B", "C", "D"];2console.log(letters.toReversed().join(""));3console.log(letters.toSpliced(1, 2, "X").join(""));4console.log(letters.with(1, "Z").join(""));5console.log(letters.join(""));

with(index, value) is the copying partner of arr[i] = value. It returns a copy where the item at index is now value.

• A negative index counts from the end, as it does with at(). So arr.with(-1, "done") replaces the last item.
• An index outside the array throws a RangeError, so your code stops with an error right away. Writing arr[i] = value there would instead leave empty slots in the array, with no warning.

Two items are tied when the comparator returns 0 for them. A stable sort keeps tied items in the order they had before the sort.

In JavaScript, array sorting is always stable. This has been a rule of the language since the 2019 edition, ES2019.

1const queue = [2  { name: "Mia", age: 30 },3  { name: "Noah", age: 20 },4  { name: "Ava", age: 30 },5  { name: "Leo", age: 20 },6];7const byAge = queue.toSorted((a, b) => a.age - b.age);8console.log(byAge.map((person) => person.name).join(", "));

Line 7 sorts a copy by age only. Line 8 prints the names: Noah, Leo, Mia, Ava.

• Noah and Leo both have age 20. Noah came first in the list, so he stays before Leo.
• Mia and Ava both have age 30. Mia came first, so she stays before Ava.

A sort key is the property you sort by, such as age or name. Because sorting is stable, you can sort in two steps: first by the less important key, then by the main key. Ties on the main key keep the order from the first step.

One comparator with a tie-breaker is often easier to read, though: a.age - b.age || a.name.localeCompare(b.name).

Where you'll use this

Sorting and copying show up wherever the order on screen is different from the order the data was stored in. For example:

• A shop page keeps the products in the order the server sent them, and shows them by price, lowest first.
• A table lets people click Name, Age, or Joined date to sort, without changing the data that was loaded.
• A shopping cart replaces one item and keeps the old cart, so the user can undo.

• Sortable tables
• Leaderboards
• Search results
• Shopping carts
• Undo and redo
• Reports in groups

1function sortRows(rows, sortKey) {2  return rows.toSorted((a, b) => {3    if (sortKey === "name") return a.name.localeCompare(b.name);4    if (sortKey === "score") return b.score - a.score;5    return 0;6  });7}

sortRows takes the table rows and a sort key:

• Line 3 sorts by name.
• Line 4 sorts by score, highest score first.
• Line 5 returns 0 for any other key. Every pair is then a tie, so the rows keep their order.

Because it uses toSorted, sortRows returns a new array every time. The rows passed in never change. That makes it easy to test, and safe to use when you keep old versions for undo.

const rows = [
  { product: "Tea", price: 3 },
  { product: "Bread", price: 2 },
];
const byPrice = rows.toSorted((a, b) => a.price - b.price);
console.log(byPrice.map((row) => row.product).join(", "));
console.log(rows.map((row) => row.product).join(", "));

The first line printed is Bread, Tea: the rows in price order, for the screen. The second is Tea, Bread: the rows in the order the server sent them. A sortable table needs exactly this. Make a sorted copy to show, and keep the loaded data as it was.

Common misconceptions

const tasks = ["email", undefined, "call"];
tasks.sort();
console.log(tasks.join(" | "));

Line 2 sorts the tasks. The two texts come first, in order: call, then email. The undefined task goes last. Line 3 joins the items with " | " between them, and join shows undefined as nothing. So the output is call | email | .

If you want a missing value to show a word, such as "none", change it to that word before you join or show the list.

Read each explanation, even when you got the answer right. Sorting mistakes often look correct on short lists.

Key takeaways

• Default sort() compares items as text. To sort numbers, give it a comparator.
• A comparator returns a negative number to put a first, a positive number to put b first, and 0 for a tie.
• sort, reverse, splice, and array[index] = value change the original array.
• toSorted, toReversed, toSpliced, and with return a changed copy and leave the original alone.
• JavaScript sorting is stable: tied items keep the order they had before.

Up next: Iterating arrays & array-likes.