RileSort

A small, typed collection of classic sorting algorithms implemented in TypeScript. Includes bubble, selection, insertion, merge, quick, and radix sort. Designed to be simple, predictable, and easy to use with numbers, strings, and custom objects.

• Pure functions (no mutations of your input array)
• Strong TypeScript types
• Pluggable comparator for custom ordering (except radix sort, which targets integers)
• ESM-friendly and tree-shakeable

Installation

Using npm:

npm install rilesort

If you’re consuming it locally (not published), import from your local path instead of the package name.

Quick start

TypeScript:

import { bubbleSort, quickSort } from "rilesort";

// Numbers (ascending by default)
const nums = [4, 2, 7, 1, 3];
const sorted = bubbleSort(nums); // [1, 2, 3, 4, 7]

// Numbers (descending with comparator)
const desc = quickSort(nums, (a, b) => b - a); // [7, 4, 3, 2, 1]

// Strings
const fruits = ["banana", "apple", "cherry"];
const alpha = bubbleSort(fruits); // ["apple", "banana", "cherry"]

// Objects (custom comparator)
type User = { id: number; name: string };
const users: User[] = [{ id: 2, name: "B" }, { id: 1, name: "A" }];
const byId = quickSort(users, (a, b) => a.id - b.id); // [{id:1,...},{id:2,...}]

JavaScript (ESM):

import { insertionSort, mergeSort } from "rilesort";

const values = [5, 1, 5, 3, 1];
console.log(insertionSort(values)); // [1, 1, 3, 5, 5]
console.log(mergeSort(values));     // [1, 1, 3, 5, 5]

CommonJS (Node) via dynamic import:

(async () => {
  const { selectionSort } = await import("rilesort");
  console.log(selectionSort([3, 2, 1]));
})();

API

All algorithms (except radixSort) share the same generic signature:

• sort (arr: T[], comparator?: (a: T, b: T) => number): T[]

Return value:

• A new array that is sorted. The input array is not modified.

Comparator contract:

• Return a negative number if a should come before b
• Return 0 if they are equal in order
• Return a positive number if a should come after b

Available functions:

• bubbleSort (arr, comparator?)
• selectionSort (arr, comparator?)
• insertionSort (arr, comparator?)
• mergeSort (arr, comparator?)
• quickSort (arr, comparator?)
• radixSort(arr: number[]): number[]
  • Targets integers (typically non-negative). Ignores custom comparators.

Algorithm characteristics

• bubbleSort

  • Stable: Yes
  • Time: O(n$^2$) average/worst, O(n) best (already sorted)
  • Space: O(1)

• selectionSort

  • Stable: No
  • Time: O(n$^2$)
  • Space: O(1)

• insertionSort

  • Stable: Yes
  • Time: O(n$^2$) average/worst, O(n) best (nearly/already sorted)
  • Space: O(1)

• mergeSort

  • Stable: Yes
  • Time: O(n log n)
  • Space: O(n)

• quickSort

  • Stable: No
  • Time: O(n log n) average, O(n^2) worst (depends on pivot strategy)
  • Space: O(log n) average (due to recursion)
  • Uses median of three to select a pivot.

• radixSort (integers)

  • Stable: Yes
  • Time: O(k·n) where k is the number of digit passes
  • Space: O(n + k)
  • Typically used for non-negative integers; behavior for negatives may require a separate pass/normalization.

Usage tips

• If you don’t provide a comparator, numbers and strings are sorted in ascending order.
• For custom objects, always supply a comparator that returns a number (negative/zero/positive).
• Functions are pure: they return a new array and do not mutate your original input.
• Stability matters if you rely on the relative order of items that compare equal. Prefer a stable algorithm ( bubbleSort, insertionSort, mergeSort, radixSort) for such cases.

Requirements

• Node.js that supports ESM. For CommonJS projects, use a bundler or dynamic import.
• TypeScript users benefit from bundled type declarations.

Development

• Install dependencies:

  npm install

• Build:

  npm run build

• Test:

  npm test

• Coverage:

  npm run coverage

License

MIT

Acknowledgements

Classic algorithms taught in most CS curricula, implemented in a modern TypeScript style for convenience and clarity.