Very Simple Sort

A tiny, type-safe utility for sorting arrays using multiple fallback comparators.

vssort is a small wrapper around native sorting that makes multi-key sorting explicit,
readable, and intentional — whether you want a new array or an in-place sort.

Installation

``bash
npm install vssort
`

$3

`ts
import { sort } from "vssort";

type Person = {
id: number;
name: string;
age: number;
};

const people: Person[] = [
{ id: 1, name: "Liam", age: 29 },
{ id: 2, name: "Charlotte", age: 28 },
{ id: 3, name: "Frank", age: 52 },
{ id: 4, name: "Alice", age: 28 },
];

const result = sort(people, [
(a, b) => a.age - b.age,
]);

// => Charlotte, Alice, Liam, Frank
`

$3

Comparators are applied in order.

If two items compare as equal (0), the next comparator is used as a fallback.

`ts
const result = sort(people, [
(a, b) => a.age - b.age,
(a, b) => a.name.localeCompare(b.name),
]);

// => Alice, Charlotte, Liam, Frank
`

$3

sort does not mutate the input array.

`ts
const sorted = sort(people, [
(a, b) => a.age - b.age,
]);

// people remains unchanged
`

$3


If you want to sort inline using Array.prototype.sort, use compare.

`ts
import { compare } from "vssort";

people.sort(
compare([
(a, b) => a.age - b.age,
(a, b) => a.name.localeCompare(b.name),
])
);

// people is now sorted in place
`

Why not just Array.prototype.sort?

Array.sort
- mutates the array
- makes multi-key sorting harder to read
- hides fallback behaviour inside a single comparator

vssort
- makes fallback ordering explicit
- lets you choose mutating or non-mutating behaviour
- stays close to native JavaScript semantics

$3

sort(input, comparators)

Returns a new sorted array.

`ts
sort(input: T[], comparators: Comparator[]): T[]
`

compare(comparators)

Returns a comparator function for use with Array.prototype.sort.

`ts
compare(comparators: Comparator[]): (a: T, b: T) => number
``