js-natural-sort

GitHub package.json version GitHub Actions Workflow Status GitHub License

NPM Downloads

js-natural-sort is a JavaScript package that provides a natural sorting function for strings and numbers, handling various types of data such as dates, IPs, hexadecimal numbers, and regular strings. It offers a more intuitive sorting order compared to default lexicographical sorting.

Features

Natural sorting (e.g. '10' < '100')
Date-aware comparisons
IP address sorting
Hexadecimal value support
Case-insensitive mode
Handles leading zeroes correctly
Object support via key or accessor
ESM, CommonJS, and AMD build support

Installation

You can install the package via npm:

npm install @andreasnicolaou/js-natural-sort

Usage

import { naturalSort } from '@andreasnicolaou/js-natural-sort';

const arrFloats = ['10.0401', 10.022, 10.042, '10.021999'].sort(naturalSort());
console.log(arrFloats); // ['10.021999', 10.022, '10.0401', 10.042]

import { naturalSort } from '@andreasnicolaou/js-natural-sort';

const arrDates = ['2022-01-02', '2021-12-31', '2020-11-11', '2021-01-01'].sort(naturalSort());
console.log(arrDates); // ['2020-11-11', '2021-01-01', '2021-12-31', '2022-01-02']

import { naturalSort } from '@andreasnicolaou/js-natural-sort';

const arrObj = [
  { name: 'John', age: 30 },
  { name: 'Alice', age: 25 },
  { name: 'Bob', age: 35 },
].sort(naturalSort({ key: (x) => `${x.name}${x.age}` }));
console.log(arrObj); // [{ name: 'Alice', age: 25 }, { name: 'Bob', age: 35 }, { name: 'John', age: 30 }]

import { naturalSort } from '@andreasnicolaou/js-natural-sort';

const arrObj2 = [{ id: 10 }, { id: 2 }, { id: 1 }].sort(naturalSort({ key: 'id', order: 'desc' }));
console.log(arrObj2); // [{ id: 10 }, { id: 2 }, { id: 1 }]

Parameters

The function accepts a single optional options object with the following properties:

Parameter	Type	Description	Default
`insensitive`	`boolean`	Whether the sorting should be case-insensitive.	`false`
`order`	`'asc'` \| `'desc'`	Sorting order. Can be `'asc'` or `'desc'`.	`'asc'`
`key`	`'keyof T'` \| `'(obj: T) => value'`	Key or accessor function to extract sortable value from item.	`'undefined'`

Contributing

Contributions are welcome! If you encounter issues or have ideas to enhance the library, feel free to submit an issue or pull request.