JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 1088421
  • Score
    100M100P100Q187060F
  • License MIT

Fast and powerful array sorting. Sort an array of objects by one or more properties. Any number of nested properties or custom comparison functions may be used.

Package Exports

  • array-sort

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (array-sort) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

array-sort NPM version

Fast and powerful array sorting. Sort an array of objects by one or more properties. Any number of nested properties or custom comparison functions may be used.

Install

Install with npm

$ npm i array-sort --save

Usage

Sort an array by the given object property:

var arraySort = require('array-sort');

arraySort([{foo: 'y'}, {foo: 'z'}, {foo: 'x'}], 'foo');
//=> [{foo: 'x'}, {foo: 'y'}, {foo: 'z'}]

Reverse order

arraySort([{foo: 'y'}, {foo: 'z'}, {foo: 'x'}], 'foo', {reverse: true});
//=> [{foo: 'z'}, {foo: 'y'}, {foo: 'x'}]

Table of contents

(Table of contents generated by verb)

Params

arraySort(array, comparisonArgs);
  • array: {Array} The array to sort
  • comparisonArgs: {Function|String|Array}: Any number of functions, object paths, or arrays or objects paths and functions may be passed.

Examples

Object paths

Say you have the following blog posts:

var collection = [
  { path: 'a.md', locals: { date: '2014-01-09' } },
  { path: 'f.md', locals: { date: '2014-01-02' } },
  { path: 'd.md', locals: { date: '2013-05-06' } },
  { path: 'e.md', locals: { date: '2015-01-02' } },
  { path: 'b.md', locals: { date: '2012-01-02' } },
  { path: 'f.md', locals: { date: '2014-06-01' } },
  { path: 'c.md', locals: { date: '2015-04-12' } },
  { path: 'g.md', locals: { date: '2014-02-02' } },
];

and you want to sort them by locals.date:

arraySort(collection, 'locals.date');

Result

[
  { path: 'b.md', locals: { date: '2012-01-02' } },
  { path: 'd.md', locals: { date: '2013-05-06' } },
  { path: 'f.md', locals: { date: '2014-01-02' } },
  { path: 'a.md', locals: { date: '2014-01-09' } },
  { path: 'g.md', locals: { date: '2014-02-02' } },
  { path: 'f.md', locals: { date: '2014-06-01' } },
  { path: 'e.md', locals: { date: '2015-01-02' } },
  { path: 'c.md', locals: { date: '2015-04-12' } }
];

Sort by multiple properties and functions

Here are the "posts" we want to sort:

var posts = [
  { path: 'a.md', locals: { date: '2014-01-01', foo: 'zzz', bar: 1 } },
  { path: 'f.md', locals: { date: '2014-01-01', foo: 'mmm', bar: 2 } },
  { path: 'd.md', locals: { date: '2014-01-01', foo: 'xxx', bar: 3 } },
  { path: 'i.md', locals: { date: '2014-01-01', foo: 'xxx', bar: 5 } },
  { path: 'k.md', locals: { date: '2014-01-01', foo: 'xxx', bar: 1 } },
  { path: 'j.md', locals: { date: '2014-01-01', foo: 'xxx', bar: 4 } },
  { path: 'h.md', locals: { date: '2014-01-01', foo: 'xxx', bar: 6 } },
  { path: 'l.md', locals: { date: '2014-01-01', foo: 'xxx', bar: 7 } },
  { path: 'e.md', locals: { date: '2015-01-02', foo: 'aaa', bar: 8 } },
  { path: 'b.md', locals: { date: '2012-01-02', foo: 'ccc', bar: 9 } },
  { path: 'f.md', locals: { date: '2014-06-01', foo: 'rrr', bar: 10 } },
  { path: 'c.md', locals: { date: '2015-04-12', foo: 'ttt', bar: 11 } },
  { path: 'g.md', locals: { date: '2014-02-02', foo: 'yyy', bar: 12 } },
];

The goal

Sort "posts" by the following:

  • locals.date: our first choice
  • locals.foo: Use this when mulitiple posts have the same locals.date value
  • locals.bar: Use this when mulitiple posts have the same locals.foo value
// let's create a reusable comparison function
var compare = function(prop) { 
  // the last arg, `fn` is the internal comparison function
  // used by the lib. it's exposed here for convenience
  return function (a, b, fn) {
    var valA = get(a, prop);
    var valB = get(b, prop);
    return fn(valA, valB);
  };
};

Time to sort!

// the comparison args can be an array or a list, makes no difference
arraySort(posts, ['locals.date', compare('locals.foo'), compare('locals.bar')]);

Result

[
  { path: 'b.md', locals: { date: '2012-01-02', foo: 'ccc', bar: 9 } },
  { path: 'f.md', locals: { date: '2014-01-01', foo: 'mmm', bar: 2 } },
  { path: 'k.md', locals: { date: '2014-01-01', foo: 'xxx', bar: 1 } },
  { path: 'd.md', locals: { date: '2014-01-01', foo: 'xxx', bar: 3 } },
  { path: 'j.md', locals: { date: '2014-01-01', foo: 'xxx', bar: 4 } },
  { path: 'i.md', locals: { date: '2014-01-01', foo: 'xxx', bar: 5 } },
  { path: 'h.md', locals: { date: '2014-01-01', foo: 'xxx', bar: 6 } },
  { path: 'l.md', locals: { date: '2014-01-01', foo: 'xxx', bar: 7 } },
  { path: 'a.md', locals: { date: '2014-01-01', foo: 'zzz', bar: 1 } },
  { path: 'g.md', locals: { date: '2014-02-02', foo: 'yyy', bar: 12 } },
  { path: 'f.md', locals: { date: '2014-06-01', foo: 'rrr', bar: 10 } },
  { path: 'e.md', locals: { date: '2015-01-02', foo: 'aaa', bar: 8 } },
  { path: 'c.md', locals: { date: '2015-04-12', foo: 'ttt', bar: 11 } }
]);

Custom functions

If custom functions are supplied, array elements are sorted according to the return value of the compare function. See the docs for Array.sort().

  • get-value: Use property paths ( a.b.c) to get a nested value from an object.
  • sort-asc: Sort array elements in ascending order.
  • sort-desc: Sort array elements in descending order.
  • set-value: Create nested values and any intermediaries using dot notation ('a.b.c') paths.
  • sort-object: Sort the keys in an object.

Running tests

Install dev dependencies:

$ npm i -d && npm test

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue

Author

Jon Schlinkert

License

Copyright © 2015 Jon Schlinkert Released under the MIT license.

This file was generated by verb-cli on July 18, 2015.