ordering

ordering is a library for manipulating, projecting, and combining comparison functions, which are used to sort an array. TypeScript definitions are included.

Motivation

Out of the box, calling the sort method on an array usually does not do what we want. For example, an array of numbers is coerced to strings and then sorted by code unit, giving surprising results. To solve this, the sort method takes a function that can compare two elements in an array, called a comparator.

This library provides a set of ready-to-use comparators for sorting most built-in JavaScript types, as well as a variety of utilities to make more comparators.

Installation

npm install @kourge/ordering

Broad Examples

Here is a quick overview of what it's like to use ordering.

Sorting numbers

import {byNumber} from '@kourge/ordering/comparators';

const a = [6, 3, 2, 8, 7, 6, 9, 4, 3, 8];
a.sort(byNumber);
// => [2, 3, 3, 4, 6, 6, 7, 8, 8, 9]

Sorting strings without case sensitivity

import {byStringWithoutCaseSensitivity} from '@kourge/ordering/comparators';

const a = ['Variks', 'judgment', 'Mithrax', 'light', 'Eramis', 'ship'];
a.sort(byStringWithoutCaseSensitivity);
// => ['Eramis', 'judgment', 'light', 'Mithrax', 'ship', 'Variks']

Sorting objects by their properties

import {ordering} from '@kourge/ordering';
import {byNumber, byString} from '@kourge/ordering/comparators';

interface Person {
  name: string;
  age: number;
}

const byName = ordering(byString).on<Person>(p => p.name);
const byAge = ordering(byNumber).on<Person>(p => p.age);
const byNameThenByAge = byName.join(byAge);

API Documentation

See the docs directory for a comprehensive documentation of the API.

Changelog

All changes that affect usage and behavior will be documented here.

v2.0.0

• All documentation is now automatically generated from JSDoc that lives alongside the source code.
• Split comparator into two modules:
  • comparator contains functions that create comparators.
  • comparators contains comparators that can be directly used to sort arrays.

comparator module

• Changed the join function. It no longer allows joining zero comparators. At least one must be provided. Otherwise a TypeError is thrown.
• Added the reversed function.
• Added the keyed function.

comparators module

• Removed the alwaysEqual comparator. It existed to support joining zero comparators, which is no longer allowed by join.
• Renamed the byString.caseInsensitive comparator to byStringWithoutCaseSensitivity.
  • Bug fix: it now tries to use your environment's locale, instead of always specifying en-US.

scoring module

• Renamed the scoringFromArrayByMap function to scoringFromArrayUsingMap.

ordering module

• An Ordering can now be directly used as a Comparator.
• Renamed the reverse method to reversed.
• Added the join method.

v1.0.0

• Initial release.