Module order

Composable comparison functions.

Provides ready-made comparators, factories deriving them from keys or locales, and combinators that reverse, extend or chain them. Factories and combinators return a Comparator, so results compose freely and plug into Array.sort().

Basic Sorting

Sort arrays using ascending or descending order:

import { ascending, descending } from '@metreeca/core/order';

const numbers = [3, 1, 4, 1, 5];
numbers.sort(ascending);  // [1, 1, 3, 4, 5]
numbers.sort(descending); // [5, 4, 3, 1, 1]
Copy

Sorting by Property

Extract and compare specific properties from objects:

import { by, descending } from '@metreeca/core/order';

const users = [
  { name: 'Bob', age: 25 },
  { name: 'Alice', age: 30 }
];

users.sort(by(user => user.name));            // Sort by name ascending
users.sort(by(user => user.age, descending)); // Sort by age descending
Copy

Sorting by Locale

Order strings according to the collation rules of a locale:

import { by, locale } from '@metreeca/core/order';

const users = [
  { name: 'Émile' },
  { name: 'adam' }
];

users.sort(by(user => user.name, locale())); // Sort by name with the runtime locale
Copy

Handling Nullish Values

Place null and undefined keys first or last. Array.prototype.sort moves undefined array elements to the end without ever consulting the comparator, so the placement of undefined values holds for keys extracted with by:

import { by, absent, present, ascending } from '@metreeca/core/order';

const items = [{ rank: 3 }, { rank: null }, { rank: 1 }, { rank: undefined }, { rank: 2 }];

items.sort(by(item => item.rank, absent(ascending)));  // ranks: undefined, null, 1, 2, 3
items.sort(by(item => item.rank, present(ascending))); // ranks: 1, 2, 3, null, undefined
Copy

Reversing Order

Invert an existing comparator:

import { reverse, ascending } from '@metreeca/core/order';

const numbers = [3, 1, 4, 1, 5];
numbers.sort(reverse(ascending)); // [5, 4, 3, 1, 1]
Copy

Combining Multiple Criteria

Sort by multiple properties with priority order:

import { by, compound } from '@metreeca/core/order';

const data = [
  { category: 'B', priority: 2 },
  { category: 'A', priority: 1 },
  { category: 'A', priority: 3 }
];

data.sort(compound(
  by(item => item.category),    // First by category
  by(item => item.priority)     // Then by priority
));
Copy