đź”§ The Sort That Agreed on the Order, Just Not Which Order
Calling sort with a comparator that returns 0 for elements considered equal reads as though those equal elements will simply stay in whatever order they started in – and for years, that assumption was only sometimes true, because the specification didn’t always require a stable sort, leaving engines free to reorder equal elements however their particular sorting algorithm happened to. Modern engines have standardized on stability, but code still running in older browsers, older Node versions, or against array-like objects handled by a different code path can quietly reorder items that a comparator called equal, which is invisible for a short list and very visible for a long one shown to a user who expects a secondary, implicit ordering (like insertion order) to be preserved.
🔎 The Problem
const tasks = [
{ name: "Write report", priority: 2, addedOrder: 1 },
{ name: "Fix bug", priority: 1, addedOrder: 2 },
{ name: "Review PR", priority: 2, addedOrder: 3 },
{ name: "Reply to email", priority: 1, addedOrder: 4 }
];
// Sorting only by priority - the comparator returns 0 for tasks
// that share a priority, silently relying on the engine to leave
// those tied tasks in their original relative order.
tasks.sort((a, b) => a.priority - b.priority);
// On an engine (or a code path) that doesn't guarantee a stable
// sort for ties, "Write report" and "Review PR" - both priority 2 -
// are not guaranteed to come out in the order they went in, even
// though every modern mainstream engine happens to get this right
// today, which is exactly what makes relying on it implicitly risky.
âś… Fix: Make the Secondary Order Explicit in the Comparator
- Adding addedOrder (or any explicit tiebreaker field) as a second comparison inside the same comparator function – returning the priority difference first, falling back to the addedOrder difference when priorities are equal – removes any dependency on sort stability entirely, since the order is now fully determined by the comparator itself.
- Checking which JavaScript engines and versions the code actually needs to support, and confirming the ECMAScript specification version they implement guarantees stable sort (true for all current mainstream engines following ES2019 and later), clarifies whether this is a real risk for a given deployment target or a theoretical one.
- Writing a quick test with a list long enough and tied enough to make a reordering obvious (rather than trusting a three-item example that happens to look fine) is the fastest way to confirm a comparator’s actual behavior on the engines that matter, rather than relying on assumption.
⚠️ Why This Is Easy to Overlook Today
- Every current major browser engine and Node.js version has implemented a stable Array.prototype.sort for a while now, so code that implicitly relies on stability for ties genuinely works correctly in virtually every environment it’s likely to run in today – right up until it runs somewhere older, or against a library’s custom array-like structure with its own sort implementation.
- A comparator that returns 0 for ‘equal’ elements is making an implicit claim that it doesn’t care about their relative order – when that claim isn’t actually true (the UI does show an implicit secondary order to the user), the bug isn’t really in the sort engine at all, it’s in the comparator not saying what it actually means.
Returning 0 from a comparator isn’t saying ‘don’t move these’ – it’s saying ‘I don’t care where these end up,’ and sooner or later something takes that literally.
