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

npm install vssort

Basic example

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

Multiple comparators (fallback sorting)

Comparators are applied in order.

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

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

// => Alice, Charlotte, Liam, Frank

Non-mutating

sort does not mutate the input array.

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

// people remains unchanged

Inline usage (mutating)

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

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

API

sort(input, comparators)

Returns a new sorted array.

sort<T>(input: T[], comparators: Comparator<T>[]): T[]

compare(comparators)

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

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