JavaScript .sort(), "Why b - a, Not a - b"

interface FinancialRecord {
  id: string;
  amount: number;
  timestamp: number;
  category: string;
}

const transactions: FinancialRecord[] = [
  { id: "TXN-001", amount: 150.75, timestamp: 1715000000, category: "revenue" },
  { id: "TXN-002", amount: 89.20, timestamp: 1715000100, category: "expense" },
  { id: "TXN-003", amount: 210.00, timestamp: 1715000200, category: "revenue" },
];

// Ascending by amount
const sortedAsc = transactions.toSorted((a, b) => a.amount - b.amount);

// Descending by amount
const sortedDesc = transactions.toSorted((a, b) => b.amount - a.amount);

cycles.

Step 3: Abstract Multi-Field Sorting

Real-world data rarely sorts on a single primitive. A comparator factory pattern centralizes logic and prevents repetition:

type SortDirection = "asc" | "desc";

function createNumericSorter<T>(
  key: keyof T,
  direction: SortDirection = "asc"
): (a: T, b: T) => number {
  const multiplier = direction === "asc" ? 1 : -1;
  return (a: T, b: T) => multiplier * (Number(a[key]) - Number(b[key]));
}

// Usage
const byAmountDesc = createNumericSorter<FinancialRecord>("amount", "desc");
const sortedByAmount = transactions.toSorted(byAmountDesc);

Rationale: The factory encapsulates direction logic, enforces type safety via generics, and guarantees antisymmetry (swapping arguments flips the sign). This eliminates inline arithmetic errors and makes unit testing deterministic.

Step 4: Handle String Collation Correctly

Subtraction fails on strings because JavaScript coerces operands to NaN. The specification mandates String.prototype.localeCompare() for textual ordering. It returns -1, 0, or 1 based on Unicode collation rules, respecting locale-specific sorting (e.g., accented characters, case sensitivity).

const sortedByCategory = transactions.toSorted((a, b) => 
  a.category.localeCompare(b.category)
);

Architecture Decision: localeCompare is slower than subtraction but necessary for correctness. It handles edge cases like "é" vs "e" and "Z" vs "a" according to ICU standards. Never use < or > operators for string sorting in production.

Step 5: Compose Multi-Level Sorters

When primary keys tie, secondary keys determine order. Chain comparators using short-circuit evaluation:

const multiSorter = (a: FinancialRecord, b: FinancialRecord) => {
  const amountDiff = b.amount - a.amount; // Primary: descending
  if (amountDiff !== 0) return amountDiff;
  return a.timestamp - b.timestamp;       // Secondary: ascending
};

const sortedMulti = transactions.toSorted(multiSorter);

This pattern ensures deterministic ordering without nested conditionals or unstable algorithm behavior.

Pitfall Guide

1. The Lexicographic Trap

Explanation: Calling .sort() without arguments triggers implicit toString() conversion. [10, 2, 100] becomes ["10", "2", "100"], sorting alphabetically. Fix: Always provide a comparator for numeric data. Use toSorted((a, b) => a - b) for explicit mathematical ordering.

2. Boolean Return Values

Explanation: Returning true or false violates the contract. JavaScript coerces true to 1 and false to 0, but this breaks antisymmetry and produces unstable sorts. Fix: Return explicit numbers. Replace (a, b) => a > b with (a, b) => a - b or (a, b) => (a > b ? 1 : a < b ? -1 : 0).

3. Floating-Point Precision Loss

Explanation: Subtraction with decimals can yield results like 0.0000000000000002 due to IEEE 754 representation. While the sign remains correct, extreme precision differences may cause unexpected ordering in edge cases. Fix: Round or scale values before subtraction, or use a tolerance threshold: (a, b) => Math.sign(a - b).

4. Silent Mutation in State Management

Explanation: sort() modifies the original array. In React/Vue, this breaks shallow equality checks, causing missed updates or unnecessary re-renders. Fix: Use toSorted() or spread syntax [...arr].sort(). Never mutate source arrays in functional components or Redux reducers.

5. Inconsistent Comparator Logic

Explanation: A comparator must satisfy compare(a, b) === -compare(b, a). Returning constants like -1 or using non-deterministic logic (e.g., Math.random()) violates this, causing engine-dependent ordering. Fix: Ensure the return value depends solely on a and b. Use pure functions with no external state or randomness.

6. BigInt/NaN Incompatibility

Explanation: Subtraction throws a TypeError for BigInt values and returns NaN for invalid numbers, breaking the sort contract. Fix: Use explicit comparison for BigInt: (a, b) => (a > b ? 1 : a < b ? -1 : 0). Filter or coerce NaN values before sorting.

7. Ignoring Locale in String Sorting

Explanation: Using < or > for strings sorts by code point, not linguistic rules. "ä" may sort after "z" depending on the engine. Fix: Always use localeCompare() for user-facing text. Pass locale options when needed: a.localeCompare(b, "de-DE").

Production Bundle

Action Checklist

• Audit all .sort() calls for missing comparators on numeric or object arrays
• Replace in-place .sort() with .toSorted() or spread copies in state-driven code
• Validate comparator antisymmetry: fn(a, b) must equal -fn(b, a)
• Use localeCompare() for all string sorting; avoid </> operators
• Implement a comparator factory for repeated sorting patterns
• Add unit tests covering edge cases: ties, negatives, decimals, empty arrays
• Profile sorting hot paths; avoid heavy computation inside comparators
• Document sorting direction explicitly in TypeScript types or JSDoc

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Sorting primitive numbers	(a, b) => a - b with toSorted()	Mathematically precise, zero allocation overhead	Low
Sorting objects by numeric field	Comparator factory with toSorted()	Reusable, type-safe, prevents mutation bugs	Low
Sorting user-facing strings	localeCompare() with toSorted()	Handles Unicode, case, and locale rules correctly	Moderate
Multi-level sorting	Chained comparator with early returns	Deterministic, avoids unstable algorithm behavior	Low
Legacy environment (Node < 20)	[...arr].sort()	Polyfills immutability without native toSorted()	Low
High-frequency real-time sorting	Pre-sorted data structures or Web Workers	Avoids main thread blocking on large datasets	High

Configuration Template

// sort.utils.ts
export type SortDirection = "asc" | "desc";
export type SortablePrimitive = number | string;

export interface SortConfig<T> {
  key: keyof T;
  direction?: SortDirection;
  locale?: string;
}

export function createSorter<T extends Record<string, SortablePrimitive>>(
  config: SortConfig<T>
): (a: T, b: T) => number {
  const { key, direction = "asc", locale } = config;
  const multiplier = direction === "asc" ? 1 : -1;

  return (a: T, b: T) => {
    const valA = a[key];
    const valB = b[key];

    if (typeof valA === "string" && typeof valB === "string") {
      return multiplier * valA.localeCompare(valB, locale);
    }

    if (typeof valA === "number" && typeof valB === "number") {
      return multiplier * (valA - valB);
    }

    return 0;
  };
}

// Usage example
const users = [
  { name: "Zoe", score: 88 },
  { name: "Alice", score: 92 },
  { name: "Bob", score: 88 },
];

const byScoreDesc = createSorter<typeof users[0]>({ key: "score", direction: "desc" });
const sortedUsers = users.toSorted(byScoreDesc);

Quick Start Guide

1. Identify Sort Targets: Locate all array sorting operations in your codebase. Flag any missing comparators or in-place mutations.
2. Replace with Immutable Pattern: Swap .sort() for .toSorted() or [...arr].sort(). Verify state updates reflect the new array reference.
3. Implement Type-Safe Comparators: Use the provided createSorter utility for numeric and string fields. Pass locale options for user-facing text.
4. Validate Edge Cases: Test with negative numbers, decimals, ties, and empty arrays. Confirm antisymmetry holds.
5. Profile and Optimize: If sorting >10,000 elements frequently, consider pre-sorting on the server, using Web Workers, or switching to indexed data structures.

Mastering JavaScript sorting requires treating the comparator as a strict contract, enforcing immutability by default, and abstracting repetitive logic into reusable utilities. When applied consistently, these patterns eliminate silent bugs, improve framework compatibility, and ensure deterministic ordering across all data types.