sort

Custom compare functions for sorting arrays.

Installation

This package is distributed via npm:

npm install @antoniovdlc/sort

Motivation

Sorting arrays is a common operation in JavaScript, so this library provides some common custom compare functions to have a more declarative way of sorting arrays.

Usage

You can use this library either as an ES module or a CommonJS package:

import { alphabetically, chronologically, numerically } from "@antoniovdlc/sort";

- or -

const { alphabetically, chronologically, numerically } = require("@antoniovdlc/sort");

Examples

All compare functions can be used out of the box for sorting as follows:

import { numerically } from "@antoniovdlc/sort";

const arr = [1, 2, 2, 23, 30, 4];
arr.sort(numerically); // [1, 2, 2, 4, 23, 30]

By default, sorting is doing in an ascending fashion. All compare functions also provide utility fields for descending sorting as well as an explicit ascending sort.

import { numerically } from "@antoniovdlc/sort";

const arr = [1, 2, 2, 23, 30, 4];
arr.sort(numerically.asc); // [1, 2, 2, 4, 23, 30]

import { numerically } from "@antoniovdlc/sort";

const arr = [1, 2, 2, 23, 30, 4];
arr.sort(numerically.desc); // [30, 23, 4, 2, 2, 1]

Finally, all compare functions provide a .by("key") function which allows to sort arrays of objects by nested fields:

const arr = [
  { name: "Bob", age: 23 },
  { name: "Alice", age: 32 },
  { name: "Tom", age: 60 },
  { name: "Candice", age: 45 },
];
arr.sort(numerically.by("age"));
/*
[
  { name: "Bob", age: 23 },
  { name: "Alice", age: 32 },
  { name: "Candice", age: 45 },
  { name: "Tom", age: 60 },
]
*/

The same .asc and .desc functions can be used for sorting arrays of objects:

const arr = [
  { name: "Bob", age: 23 },
  { name: "Alice", age: 32 },
  { name: "Tom", age: 60 },
  { name: "Candice", age: 45 },
];
arr.sort(numerically.by("age").desc);
/*
[
  { name: "Tom", age: 60 },
  { name: "Candice", age: 45 },
  { name: "Alice", age: 32 },
  { name: "Bob", age: 23 },
]
*/

Compare functions

Here is a list of provided compare functions:

alphabetically

Sorts an array in alphabetical (string) order. Case sensitive.

alphabeticallyBase

Sorts an array in alphabetical (string) order. Case insensitive.

chronologically

Sorts an array in chronological (date) order.

numerically

Sorts an array in numerical (number) order.

Creating custom sorting functions

You can create your own sorting functions by using the createCompareFunction() function:

import { createCompareFunction } from "@antoniovdlc/sort";

const alphabeticallyLocale = createCompareFunction(String, (a, b) => a.localeCompare(b));

const arr = [
  { name: "Bob", age: 23 },
  { name: "Alice", age: 32 },
  { name: "Tom", age: 60 },
  { name: "Candice", age: 45 },
];
arr.sort(alphabeticallyLocale.by("name").desc);

Out of the box, your custom sorting functions have the same attributes and methods as the default sorting functions (such as .desc or .by())!

Combining sorting functions

You can also combine multiple sorting functions.

Let's say that for example, you need to sort an array of users first by name, and then by age (descending). You can achieve that as follows:

const arr = [
  { name: "Bob", age: 23 },
  { name: "Alice", age: 32 },
  { name: "Tom", age: 60 },
  { name: "Candice", age: 45 },
  { name: "Alice", age: 28 },
];
arr.sort(combine([alphabetically.by("name"), numerically.by("age").desc]));
/*
[
  { name: "Alice", age: 32 },
  { name: "Alice", age: 28 },
  { name: "Bob", age: 23 },
  { name: "Candice", age: 45 },
  { name: "Tom", age: 60 },
]
*/

License

MIT