Lightweight (< 1.6kB gzipped) and performant natural sorting of arrays and collections by differentiating between unicode characters, numbers, dates, etc.
People sort strings containing numbers differently than most sorting algorithms, which sort values by comparing strings in Unicode code point order. This produces an ordering that is inconsistent with human logic.
natural-orderby sorts the primitive values of Boolean, Null, Undefined, Number or String type as well as objects. When comparing strings it differentiates between unicode characters, integer, floating as well as hexadecimal numbers, various date formats, etc. You may sort flat or nested arrays or arrays of objects in a natural sorting order using .
In addition to the efficient and fast orderBy() method natural-orderby also provides the method compare(), which may be passed to Array.prototype.sort().
If you´re not using a module bundler or package manager there´s also a global ("IIFE") build hosted on the unpkg CDN. Simply add the following <script> tag to the bottom of your HTML file:
Creates an array of elements, natural sorted by specified identifiers and the corresponding sort orders. This method implements a stable sort algorithm, which means the original sort order of equal elements is preserved.
It also avoids the high overhead caused by Array.prototype.sort() invoking a compare function multiple times per element within the array.
'asc' | 'desc' | (valueA: unknown, valueB: unknown) => number
Description
orderBy() sorts the elements of an array by specified identifiers and the corresponding sort orders in a natural order and returns a new array containing the sorted elements.
If collection is an array of primitives, identifiers may be unspecified. Otherwise, you should specify identifiers to sort by or collection will be returned unsorted. An identifier can be expressed by:
an index position, if collection is a nested array,
a property name, if collection is an array of objects,
a function which returns a particular value from an element of a nested array or an array of objects. This function will be invoked by passing one element of collection.
If orders is unspecified, all values are sorted in ascending order. Otherwise, specify an order of 'desc' for descending or 'asc' for ascending sort order of corresponding values. You may also specify a compare function for an order, which will be invoked by two arguments: (valueA, valueB). It must return a number representing the sort order.
If you want to sort unicode strings according to a specific locale, please provide a string value for locale with a BCP 47 language tag. If the argument is unspecified, the host locale setting will be used.
Note: orderBy() always returns a new array, even if the original was already sorted.
Creates a compare function that defines the natural sort order and which may be passed to Array.prototype.sort().
Syntax
compare(options?: CompareOptions): CompareFn
Type
Value
CompareOptions
{ order?: 'asc' | 'desc', locale?: string }
CompareFn
(valueA: unknown, valueB: unknown) => number
Description
compare() returns a compare function that defines the natural sort order and which may be passed to Array.prototype.sort().
If options or its property order is unspecified, values are sorted in ascending sort order. Otherwise, specify an order of 'desc' for descending or 'asc' for ascending sort order of values.
If unicode strings should be ordered corresponding to a specific locale setting, specify the according value for the options property locale. It must be a string with a BCP 47 language tag. If the argument is unspecified, the host locale setting will be used.