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
####
by(selector, options?)
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, a > b).`ts
const byAgeAsc = Order.by((u: User) => u.age);
`You can optionally provide a custom
compare 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
predicate 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
.by() method to append additional sort steps.`ts
const byCreatedThenId = new Order()
.by((u) => u.createdAt)
.by((u) => u.id);
`####
reverse(order) 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();
`####
map(outer, order)
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);
`####
when(predicate, order)
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
`####
compare
Signature
`ts
class Order {
get compare(): (a: T, b: T) => number;
}
`Retrieve a native comparator compatible with
Array.prototype.sort.`ts
items.sort(Order.by((i: Item) => i.score, { direction: 'desc' }).compare);
`####
sort(array, order) 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);
`---
ts-order/comparator 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
####
compare(a, b)
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']
`####
nullsFirst and nullsLast
Signature
`ts
function nullsFirst(compareFn: Comparator): Comparator;
function nullsLast(compareFn: Comparator): Comparator;
`Decorate a comparator to move
null/undefined values to the beginning or end of the ordering.`ts
scores.sort(nullsLast(number)); // [1, 2, null]
`####
nansFirst and nansLast
Signature
`ts
function nansFirst(compareFn: Comparator): Comparator;
function nansLast(compareFn: Comparator): Comparator;
`Handle
NaN explicitly while delegating other values to the base comparator.`ts
[Number.NaN, 2, 1].sort(nansLast(number)); // [1, 2, NaN]
`####
number, 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.
localeString 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
Order 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
direction, compare, and predicate just like Order.by.`ts
items.sort(by((item) => item.label));
`####
order(...comparators)
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),
),
);
`####
map(mapper, comparator?)
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));
`####
reverse(compareFn)
Signature
`ts
function reverse(compareFn: Comparator): Comparator;
`Flip the direction of a comparator.
`ts
events.sort(reverse(date)); // most recent first
`####
when(predicate, comparator)
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