array-sort

What is array-sort?

The array-sort npm package is a small, fast, and dependency-free library for sorting arrays of objects based on one or more properties. It allows for complex sorting mechanisms including sorting by nested properties, custom comparator functions, and multiple criteria.

What are array-sort's main functionalities?

Simple sorting

Sorts an array of objects by a single property. In this example, it sorts the array of users by their names in ascending order.

const sort = require('array-sort');
const users = [{ name: 'John' }, { name: 'Amy' }];
sort(users, 'name');

Descending order sorting

Sorts an array of objects by a property in descending order. Here, users are sorted by age in descending order using the '-' prefix.

const sort = require('array-sort');
const users = [{ age: 30 }, { age: 24 }];
sort(users, '-age');

Multiple criteria sorting

Sorts an array of objects by multiple properties. This example sorts users first by name and then by age in ascending order.

const sort = require('array-sort');
const users = [{ name: 'John', age: 25 }, { name: 'Amy', age: 22 }];
sort(users, ['name', 'age']);

Custom comparator function

Allows for custom sorting logic using a comparator function. This example sorts users by name using a locale-aware comparison.

const sort = require('array-sort');
const users = [{ name: 'John' }, { name: 'Amy' }];
sort(users, (a, b) => a.name.localeCompare(b.name));

Other packages similar to array-sort

lodash.orderby

Lodash's orderBy function offers similar functionality to array-sort, allowing sorting by multiple criteria and in different orders. It is part of the larger lodash library, which might not be ideal for projects looking to minimize dependencies.

sort-array

Sort-array is another npm package that provides sorting of arrays based on multiple fields. It is similar to array-sort but also includes additional options for case sensitivity and explicit ascending/descending orders.

README

array-sort

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

• Params
• Examples
• Related projects
• Running tests
• Contributing
• Author
• License

(Table of contents generated by verb)

Params

arraySort(array, comparisonArgs);

• array: {Array} The array to sort
• comparisonArgs: {Function|String|Array}: One or more functions or object paths to use for sorting.

Examples

Sort blog posts

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

var posts = [
  { path: 'c.md', locals: { date: '2014-01-09' } },
  { path: 'a.md', locals: { date: '2014-01-02' } },
  { path: 'b.md', locals: { date: '2013-05-06' } },
];

// sort by `locals.date`
console.log(arraySort(posts, 'locals.date'));

// sort by `path`
console.log(arraySort(posts, 'path'));

Sort by multiple properties

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

var posts = [
  { locals: { foo: 'bbb', date: '2013-05-06' }},
  { locals: { foo: 'aaa', date: '2012-01-02' }},
  { locals: { foo: 'ccc', date: '2014-01-02' }},
  { locals: { foo: 'ccc', date: '2015-01-02' }},
  { locals: { foo: 'bbb', date: '2014-06-01' }},
  { locals: { foo: 'aaa', date: '2014-02-02' }},
];

// sort by `locals.foo`, then `locals.date`
var result = arraySort(posts, ['locals.foo', 'locals.date']);

console.log(result);
// [ { locals: { foo: 'aaa', date: '2012-01-02' } },
//   { locals: { foo: 'aaa', date: '2014-02-02' } },
//   { locals: { foo: 'bbb', date: '2013-05-06' } },
//   { locals: { foo: 'bbb', date: '2014-06-01' } },
//   { locals: { foo: 'ccc', date: '2014-01-02' } },
//   { locals: { foo: 'ccc', date: '2015-01-02' } } ]

Custom function

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

var arr = [
  {one: 'w', two: 'b'},
  {one: 'z', two: 'a'},
  {one: 'x', two: 'c'},
  {one: 'y', two: 'd'},
];

function compare(prop) {
  return function (a, b) {
    return a[prop].localeCompare(b[prop]);
  };
}

var result = arraySort(arr, function (a, b) {
  return a.two.localeCompare(b.two);
});

console.log(result);
// [ { one: 'z', two: 'a' },
//   { one: 'w', two: 'b' },
//   { one: 'x', two: 'c' },
//   { one: 'y', two: 'd' } ]

Multiple custom functions

var arr = [
  {foo: 'w', bar: 'y', baz: 'w'},
  {foo: 'x', bar: 'y', baz: 'w'},
  {foo: 'x', bar: 'y', baz: 'z'},
  {foo: 'x', bar: 'x', baz: 'w'},
];

// reusable compare function
function compare(prop) {
  return function (a, b) {
    return a[prop].localeCompare(b[prop]);
  };
}

// the `compare` functions can be a list or array
var result = arraySort(arr, compare('foo'), compare('bar'), compare('baz'));

console.log(result);
// [ { foo: 'w', bar: 'y', baz: 'w' },
//   { foo: 'x', bar: 'x', baz: 'w' },
//   { foo: 'x', bar: 'y', baz: 'w' },
//   { foo: 'x', bar: 'y', baz: 'z' } ]

Related projects

• 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

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2015 Jon Schlinkert Released under the MIT license.

---

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