multisort/README.md

Sort an array using any number of separate, ranked criteria

Multitest
=========

A small library for sorting arrays by multiple criteria.

## Installation

  npm install multisort --save

  bower install multisort --save

## Basic Usage

  ```javascript
  var input = [
    {firstName: "Kate", lastName: "Bush"},
    {firstName: "George", lastName: "Bush", suffix: "Junior"},
    {firstName: "George", lastName: "Orwell"},
    {firstName: "George", lastName: "Bush", suffix: "Senior"},
  ];

  var criteria = [
    'firstName',
    '~lastName.length',
    'suffix.charAt(1)'
  ];

  multisort(inputArray, criteria)

  // input is now sorted by firstName (ascending), then lastName.length (descending),
  // and finally suffix.charAt, called with 1 as the argument:
  // [
  //  {firstName: "George", lastName: "Orwell"},
  //  {firstName: "George", lastName: "Bush", suffix: "Senior"},
  //  {firstName: "George", lastName: "Bush", suffix: "Junior"},
  //  {firstName: "Kate", lastName: "Bush"},
  // ];
  ```

  ```javascript
  var input = [8, 7, 6, 5, 4, 3, 2, 1];

  var criteria = [
    function(a) {return a % 2},
    function(a) {return a % 3},
    function(a) {return a}
  ];

  multisort(input, criteria);

  // input is now:
  // [6, 4, 2, 8, 3, 1, 7, 5]
  ```

## Partial Application

  ```javascript
  // Passing a single argument makes a sorting function that can then be applied to lists.
  var sortByMod2AndMod3 = multisort([
    function(a) {return a % 2},
    function(a) {return a % 3},
    function(a) {return a}
  ]);

  var input1 = [8, 7, 6, 5, 4, 3, 2, 1];
  sortByMod2AndMod3(input1);
  // input1 is [6, 4, 2, 8, 3, 1, 7, 5]

  var input2 = [1, 5, 10, 25, 50, 100];
  sortByMod2AndMod3(input2);
  // input2 is [10, 100, 50, 1, 25, 5]
  ```

## Features

  **Criteria types:**

  * __Function__: Applies the given function to each element, and the return values are sorted in ascending order, using < and >.
  * __String__: Picks out the property indicated by the string, and sorts in ascending order, using < and >.  Nested properties can be accessed with dot syntax, as in "property.subproperty.subsubproperty"
  * __!String__ or __~String__: As above, but sorted in descending order.  This works with the functional and existential operators below.
  * __String(arg1, arg2...)__: As above, but calls the indicated property as a function with the given arguments.  Arguments are split by commas, trimmed, and parsed with JSON.parse.
  * __String?__: As above, tests whether the property is null or undefined.  Items without the property are sorted before items with it.



## Tests

  npm test

## Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style.
Add unit tests for any new or changed functionality. Lint and test your code.

## Release History

* 0.1.0 Initial release