Fast Array Sorting Utility Library – sort-es

Preview:

Description:

sort-es is a high-performance JavaScript utility library for sorting arrays of any type or size.

Features:

• Sort strings, numbers, booleans, objects, dates, and more
• Define single or multi-property sort orders
• Sort asynchronously with Promise support
• Tree-shake to eliminate unused code
• Leverage type-safety for robustness

How to use it:

1. Install and import the sort-es.

# Yarn
$ yarn add sort-es
# NPM
$ npm i sort-es

import {
  byString,
  byNumber,
  byBoolean,
  byDate,
  byValue,
  byValues
} from 'sort-es';

// OR
import {byString, ...} from 'https://cdn.jsdelivr.net/npm/sort-es/dist/index.mjs'

2. Sort a simple array by string.

const unsorted = ["CSS", "Script", "Com"];
const sorted = unsorted.sort(byString({
      // options
      desc: false,
      lowercase: false,
}));
// ['Com', 'CSS', 'Script']

3. Sort the number type.

const unsorted = [1, 3, 2];
const sorted = unsorted.sort(byNumber({
      // option
      desc: false
}));
// [1, 2, 3]

4. Sort the boolean type.

const unsorted = [false, true, false];
const sorted = unsorted.sort(byBoolean({
      // option
      desc: false,
}));
// [true, false, false]

5. Sort the date type.

const unsorted: Date[] = []; //[today, tomorrow, yesterday]; 
const sorted = unsorted.sort(byDate({
      // option
      desc: false,
}));
// [yesterday, today, tomorrow];

6. Sort a specific property (or function that return a value) of a complex object or class.

const arrayUnsorted = [
    {prop: "xxx", foo: 34},
    {prop: "aaa", foo: 325},
    {prop: "zzz", foo: 15},
    {prop: "ccc", foo: 340},
    {prop: "bbb", foo: 0}
];
// this sort by the foo property ascending
const sortedByFoo = arrayUnsorted.sort(byValue(i => i.foo, byNumber()));
// [{prop: "bbb", foo : 0}, {prop: "zzz", foo: 15}, .....];
// this sort by the prop property descending
const sortedByProp = arrayUnsorted.sort(byValue(i => i.prop, byString({desc: true})));
// [{prop: "zzz", foo : 15}, {prop: "xxx", foo: 34}, .....];

7. Sort an array of complex object by multiple properties.

const objsToSort = [
    {id: 2, name: 'teresa'},
    {id: 3, name: 'roberto'},
    {id: 2, name: 'roberto'}
];
// i sort by THEIR NAMES and THEN by their ids
const sortedObject = objsToSort.sort(byValues([
    [x => x.name, byString()],
    [x => x.id, byNumber()]
]));
// [{roberto, 2}, {roberto, 3}, {teresa, 2}];
// i sort by THEIR IDS and THEN by their names
const sortedObject2 = objsToSort.sort(byValues([
    [x => x.id, byNumber()],
    [x => x.name, byString()]
]));
// [{roberto, 2}, {teresa, 2}, {roberto, 3}];
// i sort by THEIR IDS and THEN by their names DESCENDING
const sortedObject3 = objsToSort.sort(byValues([
    [x => x.id, byNumber()],
    [x => x.name, byString({desc: true})]
]));
// [{teresa, 2}, {roberto, 2}, {roberto, 3}];

8. Async sorting.

import {sortAsync, byValue, byNumber} from 'sort-es'
(async () => {
  // the unsorted array,  this type is for demonstration purposes only
  const asyncArray: Promise<{ id: number }>[] = []; //[promise, promise, promise];
  const sortedArray = await sortAsync(asyncArray, byValue(x => x.id, byNumber()));
  // [{id: 0}, {id: 3}, ...]
})();

9. The AsyncHandler is a class that extends the standard array class and add a method sortAsync.

import {AsyncHandler, byValue, byNumber} from 'sort-es'
(async () => {
  // the unsorted array,  this type is for demonstration purposes only
  const asyncArray: Promise<{ id: number }>[] = []; //[promise, promise, promise];
  const asyncHandler = new AsyncHandler(asyncArray);
  const sortedArray = await asyncHandler.sortAsync(byValue(x => x.id, byNumber()));
  // [{id: 0}, {id: 3}, ...]
})();

Changelog:

v1.6.16 (08/13/2023)

• fix(byNumber): added proper fallback for sorting multiple Infinity values