doc

SortJS

A lightweight and convenient generator of sort functions for
arrays of objects and objects of objects that works both on
server (NodeJS) and client (browser) sides.

Written by Vladimir Neverov sanguini@gmail.com in 2013.

Homepage: https://github.com/vne/sortjs/wiki

Usage

SortJS can be used to sort arrays of objects and objects of objects
by multiple properties. An array may look like this:

var array = [
{ id: 1, surname: 'Smith', name: 'John', age: 30, income: 32000, percent: 55.3, birthday: new Date('09/18/2013'), strdate: "09/18/2013" },
{ id: 2, surname: 'smith', name: 'Susanne', age: 28, income: 40000, percent: 55.1, birthday: new Date('09/18/2012'), strdate: "09/18/2012" },
{ id: 3, surname: 'Bittey', name: 'Chris', age: 55, income: 20000, percent: 87.5, birthday: new Date('08/18/2011'), strdate: "08/18/2011" },
{ id: 4, surname: 'The Fourth', name: 'Jane', age: 387, income: 150000, percent: 15.8, birthday: new Date('07/18/2010'), strdate: "07/18/2010" },
{ id: 5, surname: 'Quinne', name: 'Stew', age: 5, income: 8500, percent: 31.7, birthday: new Date('09/18/2009'), strdate: "09/18/2009" },
{ id: 6, surname: 'augsburg', name: 'Theodor', age: 154, income: 210000, percent: 99.9, birthday: new Date('09/18/2009'), strdate: "09/18/2009" },
{ id: 7, surname: 'Zorro', name: 'Vasily', age: 30, income: 17000, percent: 7.3, birthday: new Date('12/18/2008'), strdate: "12/18/2008" }
]

An object may look like this:

var obj = {
    1: { surname: 'Smith', name: 'John', age: 30, income: 32000, percent: 55.3 },
    2: { surname: 'smith', name: 'Susanne', age: 28, income: 40000, percent: 55.1 },
    3: { surname: 'Bittey', name: 'Chris', age: 55, income: 20000, percent: 87.5 },
    4: { surname: 'The Fourth', name: 'Jane', age: 387, income: 150000, percent: 15.8 },
    5: { surname: 'Quinne', name: 'Stew', age: 5, income: 8500, percent: 31.7 },
    6: { surname: 'augsburg', name: 'Theodor', age: 154, income: 210000, percent: 99.9 },
    7: { surname: 'Zorro', name: 'Vasily', age: 30, income: 17000, percent: 7.3 }
};

Both can be sorted using SortJS. In case of an array you get a sorted array, in case of an
object you get a sorted array of object keys.

By default, SortJS returns a copy of a source array (as opposed to build-in Javascript method).
This behaviour can be altered.

As a module (default)

var sortjs = require('sortjs');
var sortedArray = sortjs.sort(array, ["surname", "name"]); // returns new array in requested order
var sortedObjKeys = sortjs.sort(obj, ["surname", "name"]); // returns array of object keys sorted in requested ordersortjs.sort(array, ["surname", "name"], true);             // perform an inplace sort like build-in Javascript method
sortjs.inplace(array, ["surname", "name"]);                // another way of doing inplace sorting

As an Array or Object method (includes mangling of native objects prototypes!)

var sortjs = require('sortjs');
sortjs.improve();                                      // add .sortjs method to Array and Object prototypes
var sortedArray = array.sortjs(["surname", "name"]); 
var sortedObjKeys = obj.sortjs(["surname", "name"]);   // be careful, this returns keys of the object
sortjs.clear()                                         // remove added .sortjs method from Array and Object prototypes 
sortjs.improve(true);                                  // add .sortjs method to prototypes performing inplace sorting for arrays
array.sortjs(["surname", "name"]);
sortjs.clear();array.isortjs(["surname", "name"]);                    // another way of doing inplace sorting

Simple get the sorter function

var sortjs = require('sortjs');
var sortFn = sortjs.getObjectSorter(["surname", "name"]);

List of sort fields

An array of property names should be specified to do the actual sort.
Property names are case-sensitive. They can have the following prefixes:

– (minus sign) means reverse sorting by this property

i: (letter 'i' followed by a colon) means case-insensitive string comparison by this property

s: (letter 's' followed by a colon) means case-sensitive string comparison by this property

n: (letter 'n' followed by a colon) means integer comparison by this property

f: (letter 'f' followed by a colon) means float comparison by this property

d: (letter 'd' followed by a colon) means date comparison by this property

Minus and one of the letters can be combined like this: '-i:property'. More than one letter prefix
is not allowed (and is not needed).

Examples:

['i:surname', 'i:name', 'i:midname'] - sort case-insensitevely by surname, then by name, then by midname

['-n:price', 'i:address'] - reverse numerical (integer) sort by price, then case-insensitevely by address

Sorters and hinting

sortjs.getObjectSorter returns different sorting functions for different field lists trying to avoid unnecessary
comparisons and type conversions during actual sort. There are the following sorters:
universal (U) - includes all checks and therefore works correctly with all kinds of data
with_flags (F) - includes flag checks (i, s, n, etc)
with_contexts (C) - includes callback/context access to fields that are compared
single (1) - the smallest function that is used for simple comparison by three fields or less (no cycle over fields)
* simple (S) - simple comparison by any number of fields (cycle over fields)
Sorter is chosen automatically during field list processing. It assumes two points:
a) the field list is correct
b) the data in the array that should be sorted correspond to the field list provided
You can disable automatic choice by specifying which sorter should be used. This is done
as follows:

sortjs.getObjectSorter(fieldList, { hint: 'U' });

This tells sortjs to return universal sorter regardless of its guesses about the data.

Tests and examples

More examples of library usage can be found in test.js file. To run tests you will
need Mocha, the tests themselves use built-in
NodeJS assert module. To run tests in browser
open test.html file.

Benchmarking

TODO: explain

Array size = 1000, average over 500 samples

Sparse data, single argument

        f |  0.85594 +/- 0.39481 ms | sorter 1 | rel( sortByF)  1.39450
      f:f |  1.23858 +/- 0.20522 ms | sorter F | rel( sortByF)  2.01788
  sortByF |  0.61380 +/- 0.08984 ms | sorter <fn:_>
        n |  0.81869 +/- 0.39290 ms | sorter 1 | rel( sortByN)  1.10172
      n:n |  1.93222 +/- 0.22229 ms | sorter F | rel( sortByN)  2.60019
      f:n |  1.24291 +/- 0.18595 ms | sorter F | rel( sortByN)  1.67258
  sortByN |  0.74311 +/- 1.03578 ms | sorter <fn:_>
        s |  1.02231 +/- 0.15645 ms | sorter 1 | rel( sortByS)  0.90074
      s:s |  2.23925 +/- 1.20828 ms | sorter F | rel( sortByS)  1.97296
  sortByS |  1.13497 +/- 1.14821 ms | sorter <fn:_>
        d |  6.97265 +/- 1.91867 ms | sorter 1 | rel( sortByD)  1.11903
      d:d | 13.62114 +/- 1.37493 ms | sorter F | rel( sortByD)  2.18604
  sortByD |  6.23096 +/- 0.41902 ms | sorter <fn:_>

Sparse data, four arguments

Dense data, four arguments

doc