Type-safe Order utility for delarative, composable, and immutable multi-key ordering logic
npm install ts-orderA tiny (968 B), type-safe sorting utility for JavaScript/TypeScript that gives you declarative, composable, and immutable multi-key ordering logic.
- Declarative key-based sorting
- Composable chaining with .by(), .map(), .when()
- Immutable API: methods return a new Order
- Type-safe with full inference
- DSU-optimized for costly key computations
- Zero dependencies
``bashnpm
npm install ts-order
Quickstart
ts
import { Order } from 'ts-order';interface User {
id: number;
isActive: boolean;
firstName: string;
lastName: string;
age: number | null;
createdAt: Date;
}
const users: User[] = [
/ ... /
];
// Sort by isActive DESC, lastName ASC, then firstName ASC, then id ASC (tiebreaker)
const byActiveAndName = new Order()
.by((u) => u.isActive, { direction: 'desc' }) // active users first
.by((u) => u.lastName)
.by((u) => u.firstName)
.by((u) => u.id); // tiebreaker stable sort on id
// Use order's .sort() method for DSU (decorate-sort-undecorate) optimized sorting (ensure's keys are computed only once per step)
const sorted = byActiveAndName.sort(users);
// Or use the comparator directly with native Array.prototype.sort
users.sort(byActiveAndName.compare);
`API
$3
####
Signature
ts
class Order {
static by(
selector: (value: T) => K,
options?: {
direction?: 'asc' | 'desc';
compare?: Comparator;
predicate?: (value: T) => boolean;
},
): Order;
by(
selector: (value: T) => K,
options?: {
direction?: 'asc' | 'desc';
compare?: Comparator;
predicate?: (value: T) => boolean;
},
): Order;
}
`Create a new order with a single sort step. Defaults to an ascending direction and natural three-way comparison (i.e.
, a > b).`ts
const byAgeAsc = Order.by((u: User) => u.age);
`You can optionally provide a custom
and direction property.
Note: The compare property expects a comparator that sorts in an ascending direction; the direction property will flip the compare result when set to 'desc'.`ts
import { nullsLast } from 'ts-order/comparator';const byNameDesc = Order.by((u: User) => u.name, {
direction: 'desc',
compare: (a, b) => a.localeCompare(b),
});
const byExpiryAsc = Order.by((i: Item) => i.expiresAt, {
compare: (a, b) => a.getTime() - b.getTime(),
});
const byAgeAscNullsLast = Order.by((u: User) => u.age, {
compare: nullsLast((a, b) => a - b),
});
`You may also optionally pass
to run a step only when both values satisfy the guard function.`ts
const activeUsersFirst = Order.by((u: User) => u.isActive, {
direction: 'desc',
predicate: (u) => u.isActive,
});
`Every Order instance also exposes a chainable
method to append additional sort steps.`ts
const byCreatedThenId = new Order()
.by((u) => u.createdAt)
.by((u) => u.id);
`####
and reverse()
Signature
ts
class Order {
static reverse(order: Order): Order;
reverse(): Order;
}
`Flip all step directions.
ts
const newestFirst = Order.by((u: User) => u.createdAt).reverse();
`####
Signature
ts
class Order {
static map(outer: (t: T) => K, sub: Order): Order;
map(outer: (t: T) => K, sub: Order): Order;
}
`Lift an order defined for a nested value into the parent domain.
ts
interface Address {
city: string;
postcode: string;
}
interface Customer {
id: number;
address: Address;
}const byAddress = Order.by((a: Address) => a.city).by((a) => a.postcode);
const byCustomerAddress = Order.map((c: Customer) => c.address, byAddress);
// Or chain onto an existing order
const byIdThenAddress = new Order()
.by((c) => c.id)
.map((c) => c.address, byAddress);
`####
Signature
ts
class Order {
static when(predicate: (value: T) => boolean, order: Order): Order;
when(predicate: (value: T) => boolean, order: Order): Order;
}
`Wrap an order with a guard so every step only runs when both values pass the predicate. This is handy for enabling blocks of steps conditionally or combining with per-step predicates.
ts
const byRegion = new Order()
.by((u) => u.region)
// EU region users get their own Order logic
.when(
(u) => u.region === 'eu',
Order.by((u) => u.score, {
direction: 'desc',
}),
)
.by((u) => u.id); // tiebreak id sort for all users
`####
Signature
ts
class Order {
get compare(): (a: T, b: T) => number;
}
`Retrieve a native comparator compatible with
.`ts
items.sort(Order.by((i: Item) => i.score, { direction: 'desc' }).compare);
`####
and sort(array)
Signature
ts
class Order {
static sort(array: readonly T[], order: Order): T[];
sort(array: readonly T[]): T[];
}
`Sort an array and return a new array.
This method implements the Schwartzian Transform or DSU (decorate-sort-undecorate) technique, which ensures that each key selector is only invoked once per element per step. For larger arrays or costly key computations, this can yield significant performance improvements over repeatedly calling the selector during comparisons.
ts
const out = Order.sort(users, byName);
// or
const out2 = byName.sort(users);
`---
subpackageThe comparator subpackage offers a collection of standalone utilities you can use directly with native array sorting, or alongside
Order when you need fine-grained control.`ts
import {
boolean,
by,
compare,
date,
localeString,
nansFirst,
nansLast,
nullsFirst,
nullsLast,
number,
order,
reverse,
string,
when,
} from 'ts-order/comparator';
`$3
####
Signature
ts
function compare(a: T, b: T): number;
`Natural three-way comparator that relies on
/> checks. Also exported as string.`ts
['b', 'a', 'c'].sort(compare); // ['a', 'b', 'c']
`####
and nullsLast
Signature
ts
function nullsFirst(compareFn: Comparator): Comparator;
function nullsLast(compareFn: Comparator): Comparator;
`Decorate a comparator to move
/undefined values to the beginning or end of the ordering.`ts
scores.sort(nullsLast(number)); // [1, 2, null]
`####
and nansLast
Signature
ts
function nansFirst(compareFn: Comparator): Comparator;
function nansLast(compareFn: Comparator): Comparator;
`Handle
explicitly while delegating other values to the base comparator.`ts
[Number.NaN, 2, 1].sort(nansLast(number)); // [1, 2, NaN]
`####
, boolean, date, localeString
Signature
ts
function number(a: number, b: number): number;
function boolean(a: boolean, b: boolean): number;
function date(a: Date, b: Date): number;
function localeString(a: string, b: string): number;
`Ready-to-use comparators for common primitives.
uses Intl.Collator under the hood.`ts
scores.sort(number); // numeric sort asc (NaN's first)
users.sort(localeString); // locale-aware string sort asc
flags.sort(boolean); // boolean sort asc (false first)
createdAt.sort(date); // chronological date sort asc (invalid dates first)
`$3
These functions let you build, adapt, and compose comparators for flexible multi-key or conditional sorting. Similar to the
class methods, but working directly on comparator functions instead of Order instances.####
by(key, options?)
Signature
ts
function by(
key: (value: T) => K,
options?: KeyOptions,
): Comparator;
`Project values before comparing them. Accepts
, compare, and predicate just like Order.by.`ts
items.sort(by((item) => item.label));
`####
Signature
ts
function order(...comparators: Comparator[]): Comparator;
`Chain comparators from most to least significant.
ts
users.sort(
order(
by((u) => u.lastName),
by((u) => u.firstName),
),
);
`####
Signature
ts
function map(
mapper: (value: T) => U,
comparator?: Comparator,
): Comparator;
`Adapt a comparator to operate on mapped values.
ts
// Sort items by their nested score property
items.sort(map((item) => item.nested.score));
`####
Signature
ts
function reverse(compareFn: Comparator): Comparator;
`Flip the direction of a comparator.
ts
events.sort(reverse(date)); // most recent first
`####
Signature
ts
function when(
predicate: (value: T) => boolean,
comparator: Comparator,
): Comparator;
`Run a comparator only when both values pass a guard.
ts
const evenNumbersFirst = order(
when((value) => value % 2 === 0, number),
number,
);
``MIT