Array sortBy

Sorts an array and allows specify multiple sorting criteria. It has support for accented characters, and also ignore case sensitive.

Content

1. Getting started
2. Including the library
3. Examples
4. Polyfills
5. Running the project

Getting started

To include this library into your package manager with npm or yarn

# with npm
$ npm install array-sort-by --save

# with yarn
$ yarn add array-sort-by

The sortBy function has the following signature:

/**
 * @param  {Array} array: the collection of elements to sort
 * @param  {Function} parser: transforms each item and specifies the sorting order
 * @return {Array}
 */
sortBy(array: Array, parser: Function) : Array
sortBy(array: Array) : Array

The optional parameter parser is a function that transforms each element being iterated and sets the sorting rules: ascending or descending, and the option to specify multiple fields for sorting.

The parser callback has the following signature:

/**
 * @param  {Any} item: the element being iterated over the list
 * @param  {Number} index: the index of the element in the list
 * @return {Any}
 */
parser(item: Any, index: Number) : Any
parser(item: Any) : Any

☗ Back to Index

Including the library

array-sort-by can be included directly from a CDN in your site:

<!-- from unpkg.com -->
<script src="https://unpkg.com/array-sort-by/dist/sort-by.min.js"></script>

<!-- or from rawgit.com -->
<script src="https://cdn.rawgit.com/jherax/array-sort-by/1.1.0/dist/sort-by.min.js"></script>

In the above case, the function sortBy is included as global object in the browser.

As sortBy is built as UMD (Universal Module Definition), it can be included from module loaders such as CommonJS, ES2015 Export or AMD RequireJS.

CommonJS

var sortBy = require('array-sort-by');

ES2015 Export

import sortBy from 'array-sort-by';

AMD

// using RequireJS
requirejs.config({
  paths: {
    // remove the extension .js
    'array-sort-by': '<PATH>/sort-by.min'
  }
});
require(['array-sort-by'], function(sortBy) {
  sortBy(someArray);
});

See an example with RequireJS here: http://jsfiddle.net/FdKTn/73/

☗ Back to Index

Examples

Default sorting (ASC)

let arr = [10, 8, 5, 3, 0, 7, 4, 5, 1];
sortBy(arr);

/**
 * expected:
 * [0, 1, 3, 4, 5, 5, 7, 8, 10]
 */

Sorting DESC

let arr = [5, 1, 8, 0, 3, 7, 10, 4, 3, 8];
sortBy(arr, n => -n);

/**
 * expected:
 * [10, 8, 8, 7, 5, 4, 3, 3, 1, 0]
 */

Sorting DESC date-strings as Date

let arr = ["1983/03/06", "1980/12/24", "1985/08/31", "1983/03/05"];
sortBy(arr, (s) => -new Date(s));

/**
 * expected:
 * ["1985/08/31", "1983/03/06", "1983/03/05", "1980/12/24"]
 */

Sorting DESC strings

Because we use the minus (-) symbol to specify a descending order, it will produce a NaN value when is used with a String element. That's why the flag "desc:" is prefixed to the string items in the parser callback.

let arr = ["1983/03/06", "1980/12/24", "1985/08/31", "1983/03/05"];
sortBy(arr, (s) => "desc:" + s);

/**
 * expected:
 * ["1985/08/31", "1983/03/06", "1983/03/05", "1980/12/24"]
 */

Sorting accented words

var arr = ['único', 'cosas', 'Árbol', 'fútbol', 'algo'];
sortBy(arr);
/**
 * expected:
 * ["algo", "Árbol", "cosas", "fútbol", "único"]
 */

sortBy(arr, item => 'desc:' + item);
/**
 * expected:
 * ["único", "fútbol", "cosas", "Árbol", "algo"]
 */

Sorting accented words by @n

var arr = [
  { n: 'Woche' },
  { n: 'wöchentlich' },
  { n: 'wäre' }
];

sortBy(arr, item => item.n);

/**
 * expected:
 * [
 *   { n: "wäre" },
 *   { n: "Woche" },
 *   { n: "wöchentlich" }
 * ]
 */

Sorting DESC by @a, after ASC by @d (as Date)

let arr = [
  { a: 8, d: "1985/08/31" },
  { a: 2, d: "1980/12/24" },
  { a: 5, d: "1983/03/06" },
  { a: 8, d: "1983/03/06" }
];

sortBy(arr, (o) => [-o.a, new Date(o.d)]);

/**
 * expected:
 * [
 *   { a: 8, d: "1983/03/06" },
 *   { a: 8, d: "1985/08/31" },
 *   { a: 5, d: "1983/03/06" },
 *   { a: 2, d: "1980/12/24" }
 * ]
 */

Sorting DESC by @name

let arr = [
  { id: 4, name: "Pedro" },
  { id: 6, name: "Lucía" },
  { id: 7, name: "paco" },
  { id: 3, name: "luis" }
];

sortBy(arr, item => "DESC:" + item.name);

/**
 * expected:
 * [
 *   { id: 4, name: "Pedro" },
 *   { id: 7, name: "paco" },
 *   { id: 3, name: "luis" },
 *   { id: 6, name: "Lucía" }
 * ]
 */

Sorting ASC by @name, after DESC by @age, after ASC by @a

let arr = [
  { a: 4, age: 26, name: "pedro" },
  { a: 6, age: 32, name: "Pedro" },
  { a: 7, age: 26, name: "Maria" },
  { a: 2, age: 26, name: "maría" }
];

sortBy(arr, item => [item.name, -item.age, item.a]);

/**
 * expected:
 * [
 *   { a: 2, age: 26, name: "maría" },
 *   { a: 7, age: 26, name: "Maria" },
 *   { a: 6, age: 32, name: "Pedro" },
 *   { a: 4, age: 26, name: "pedro" }
 * ]
 */

☗ Back to Index

Polyfills

This library is written using some of the new ES5/ES6 features. If you have to support Non-standard-compliant browsers like Internet Explorer, you can polyfill some of the missing features with the following alternatives:

Using es6-shim

<!-- put this script FIRST, before all other scripts -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/es6-shim/0.35.3/es6-shim.min.js"></script>

Using polyfill.io

<!-- put this script FIRST, before all other scripts -->
<script src="https://cdn.polyfill.io/v2/polyfill.min.js"></script>

Polyfill.io reads the User-Agent header of each request and returns the polyfills that are suitable for the requesting browser.

If you want to request specific polyfills, you can pass a query parameter to the url, for example:

<!--[if IE]>
<script src="https://polyfill.io/v2/polyfill.min.js?features=default-3.3&flags=always"></script>
<![endif]-->

Read the list of available features: Features and Browsers Supported.

☗ Back to Index

Running the project

If you want to fork or build your own, you must run this project.

Requirements

1. Git on linux or windows.
2. Node.js (latest stable version v6+).
   It is preferable install nvm (node version manager).
3. Yarn installed as global package.

NOTE: Consider install Node Version Manager (nvm) to upgrade easily the Node version.
Go to https://github.com/creationix/nvm and check the installation process for your OS.

If you are running Windows, you can install nvm-windows. Follow every step mentioned here so that nvm will be correctly installed to manage multiple installations of Node (with npm) on a Windows computer.

Building the project

Clone the repository:

$ git https://github.com/jherax/array-sort-by.git

If you don't have installed yarn as a global package, run this command:

$ npm install -g yarn

Now yarn will install dependencies in package.json:

$ yarn

And finally execute the webpack task:

$ yarn run build

This command will lint the code with ESLint and transpile the source files from src/ to dist/ as an UMD with Babel. It also generates the minified and source map files.

☗ Back to Index

Versioning

This projects adopts the Semantic Versioning (SemVer) guidelines:

<MAJOR>.<MINOR>.<PATCH>

Given a version number MAJOR.MINOR.PATCH, increment the:

1. MAJOR version when you make incompatible API changes.
2. MINOR version when you add functionality in a backwards-compatible manner.
3. PATCH version when you make backwards-compatible bug fixes.

Issues

To report an issue and keep traceability of bug-fixes, please report to:

• https://github.com/jherax/array-sort-by/issues

License

This project has been released under the ISC license. This license applies ONLY to the source of this repository and does not extend to any other distribution, or any other 3rd party libraries used in a repository. See LICENSE file for more information.