Fast easy to use and flexible sorting with TypeScript support. For speed comparison of fast-sort vs other popular sort libraries check benchmark section. For list of all available features check highlights section.

Quick examples

import sort from ' fast-sort ' ; sort ( [ 1 , 4 , 2 ] ) . asc ( ) ; sort ( [ 1 , 4 , 2 ] ) . desc ( ) ; sort ( users ) . desc ( u => u . firstName ) ; sort ( users ) . asc ( [ u => u . firstName , u => u . lastName ] ) ; sort ( users ) . by ( [ { asc : u => u . firstName } , { desc : u => u . age } ] ) ;

Highlights

Sort flat arrays

Sort array of objects by one or more properties

Sort in multiple directions

Natural sort support

Support for custom sort instances

Easy to read syntax

Faster than other popular sort alternatives

Undefined and null values are always sorted to bottom (with default comparer)

TypeScript support

Small footprint with 0 dependencies (~ 750 bytes gzip)

Compatible with any JS environment as Node, Web, etc..

Under the hood sort is using native JavaScript sort. Usage of native sort implies that sorting is not necessarily stable and it also implies that input array is modified(sorted) same as it would be when applying native sort.

More examples

asc / desc sorters. Both asc and desc sorters have exactly the same API.

import sort from ' fast-sort ' ; sort ( [ 1 , 4 , 2 ] ) . asc ( ) ; sort ( users ) . asc ( u => u . firstName ) ; sort ( users ) . asc ( ' firstName ' ) ; sort ( users ) . asc ( u => u . address . city ) ; sort ( users ) . asc ( [ u => u . age , u => u . firstName , ] ) ; sort ( users ) . asc ( [ ' age ' , ' firstName ' ] ) ; sort ( repositories ) . desc ( r => r . openIssues + r . closedIssues ) ;

by sorter can do anything that asc / desc sorters can with addition to some more advance sort handling. With by sorter we can sort by multiple properties in different directions and we can override default comparer for e.g natural sort purposes.

import sort from ' fast-sort ' ; sort ( users ) . by ( [ { asc : u => u . firstName } , { desc : u => u . age } , ] ) ; sort ( users ) . by ( [ { asc : ' firstName ' } , { desc : ' age ' } ] ) ; sort ( users ) . by ( { asc : u => u . address . city , comparer : ( a , b ) => a . localeCompare ( b ) , } ) ; sort ( users ) . by ( [ { asc : ' age ' } , { asc : ' lastName ' , comparer : new Intl . Collator ( undefined , { numeric : true , sensitivity : ' base ' } ) . compare , } , ] ) ;

Fore even more examples check unit tests test/sort.spec.ts in the github repo.

Natural sorting / Language sensitive sorting

By default fast-sort is not doing language sensitive sorting of strings. e.g 'image-11.jpg' will be sorted before 'image-2.jpg' (in ascending sorting). We can provide custom Intl.Collator comparer to fast-sort for language sensitive sorting of strings. Keep in mind that natural sort is slower then default sorting so recommendation is to use it only when needed.

import sort from ' fast-sort ' ; const testArr = [ ' image-2.jpg ' , ' image-11.jpg ' , ' image-3.jpg ' ] ; sort ( testArr ) . desc ( ) ; sort ( testArr ) . by ( { desc : true , comparer : new Intl . Collator ( undefined , { numeric : true , sensitivity : ' base ' } ) . compare , } ) ; const naturalSort = sort . createNewInstance ( { comparer : new Intl . Collator ( undefined , { numeric : true , sensitivity : ' base ' } ) . compare , } ) ; naturalSort ( testArr ) . asc ( ) ; naturalSort ( testArr ) . desc ( ) ;

Custom sorting

Fast sort can be tailored to fit any sorting need or use case by:

creating custom sorting instances

overriding default comparer in by sorter

sorter custom handling in provided callback function

combination of any from above

For example we will sort tags by "custom" tag importance (e.g vip tag is of greater importance then captain tag).

import sort from ' fast-sort ' ; const tagsImportance = { vip : 3 , influencer : 2 , captain : 1 } ; const tags = [ ' influencer ' , ' unknown ' , ' vip ' , ' captain ' ] ; sort ( tags ) . asc ( tag => tagImportance [ tag ] || 0 ) ; sort ( tags ) . desc ( tag => tagImportance [ tag ] || 0 ) ; const tagSorter = sort . createNewInstance ( { comparer : ( a , b ) => ( tagImportance [ a ] || 0 ) - ( tagImportance [ b ] || 0 ) } ) ; tagSorter ( tags ) . asc ( ) ; tagSorter ( tags ) . desc ( ) ; sort ( tags ) . asc ( ) ;

Things to know

When using custom comparers as e.g Intl.Collator it's up to you to ensure those features are available in all the platforms you intend to support. (You can check browser compatibility for Intl.Collator by following link above). Same applies for any other custom comparer.

sort ( null ) . asc ( ) ; sort ( 33 ) . desc ( ) ; const arr = [ 1 , 4 , 2 ] ; const sortedArr = sort ( arr ) . asc ( ) ; console . log ( sortedArr ) ; console . log ( arr ) ; console . log ( sortedArr === arr ) , const arr = [ 1 , 4 , 2 ] ; const sortedArr = sort ( [ ... arr ] ) . asc ( ) ; console . log ( arr ) ; console . log ( sortedArr ) ; console . log ( sortedArr === arr ) , const addresses = [ { city : ' Split ' } , { city : undefined } , { city : ' Zagreb ' } ] ; sort ( addresses ) . asc ( a => a . city ) ; sort ( addresses ) . desc ( a => a . city ) ;

Usage with ts-node

In a nodeJS environment, when fast-sort is being imported with ts-node, you might see an error along the lines of:

TypeError { message: 'fast_sort_1.default is not a function', }

In this case just add this to your tsconfig.json :

{ " compilerOptions " : { " esModuleInterop " : true } }

Fast sort versions

v2 version

There is no breaking changes in API between v2 and v1 version of library. Some import files have been removed so if you haven't import it using default import you might need to update imports. For more info check v2 release notes

Features by version

sort ( users ) . by ( [ { asc : ' age ' } , { desc : ' firstName ' } ] ) ; sort ( testArr ) . by ( { desc : true , comparer : new Intl . Collator ( undefined , { numeric : true , sensitivity : ' base ' } ) . compare , } ) ; const naturalSort = sort . createNewInstance ( { comparer : new Intl . Collator ( undefined , { numeric : true , sensitivity : ' base ' } ) . compare , } ) ;

Benchmark

Five different benchmarks have been created to get better insight of how fast-sort perform under different scenarios. Each benchmark is run with different array sizes raging from small 100 items to large 100 000 items.

Every run of benchmark outputs different results but the results are constantly showing better scores compared to similar popular sorting libraries.

Benchmark scores

Benchmark has been run on:

16 GB Ram

Intel® Core™ i5-4570 CPU @ 3.20GHz × 4

Ubuntu 16.04

Node 8.9.1

Running benchmark

To run benchmark on your PC follow steps from below

git clone https://github.com/snovakovic/fast-sort.git cd fast-sort/benchmark npm install npm start

In case you notice any irregularities in benchmark or you want to add sort library to benchmark score please open issue here