sort
Problem
You need to sort an array by one or multiple fields without mutating the original, and with clear asc/desc control per field.
Solution
Use an ordered criteria array when column paths or priority come from a data grid. Each criterion accepts a property key or a dotted/bracketed path, and omitted directions default to ascending.
ts
import { sort } from '@vielzeug/arsenal';
const users = [
{ address: { city: 'Berlin' }, age: 27, name: 'Linus' },
{ address: { city: 'Aachen' }, age: 30, name: 'Grace' },
{ address: { city: 'Berlin' }, age: 41, name: 'Ada' },
];
const ordered = sort(users, [{ key: 'address.city' }, { key: 'age', direction: 'desc' }]);
ordered.map((user) => `${user.name} (${user.address.city})`);
// [
// 'Grace (Aachen)',
// 'Ada (Berlin)',
// 'Linus (Berlin)',
// ]Single-field and keyed-field sorts
ts
import { sort } from '@vielzeug/arsenal';
sort(users, (user) => user.name); // one extracted value
sort(users, { name: 'asc', age: 'desc' }); // keyed fields in property orderPitfalls
- Returns a new array; the original is never mutated.
- Criteria are evaluated in order; the first non-equal value decides the order, and ties keep input order.
- Criteria paths use safe path lookup; prototype-access segments do not expose inherited properties.
- A column mixing unsupported value types (for example, a number and a string) throws
TypeError. - String comparison uses
localeCompare: results may differ from</>comparisons.