@bemoje/arr-sort-comparator NPM

@bemoje/arr-sort-comparator

Create array comparator function.

Version

Travis CI

Dependencies

Stats

Donate

Installation

npm install @bemoje/arr-sort-comparator
npm install --save @bemoje/arr-sort-comparator
npm install --save-dev @bemoje/arr-sort-comparator

Usage

import compare from '@bemoje/arr-sort-comparator'

let arr

/**
 * DATA: STRINGS
 * --------------
 */

arr = ['5', '2', '4', '30', '1', '3']

/**
 * SORT ALPHABETICALLY BY DEFAULT
 * ------------------------------
 */

arr.sort(compare())
//=> ['1', '2', '3', '30', '4', '5']

/**
 * DATA: NUMERIC VALUES
 * ----------------------
 */

arr = [5, 2, 4, 30, 1, 3]

/**
 * SORT NUMERICALLY
 * ----------------
 */

arr.sort(
  compare({
    numeric: true,
  }),
)
//=> [1, 2, 3, 4, 5, 30]

/**
 * SORT DESCENDING
 * ---------------
 */

arr.sort(
  compare({
    numeric: true,
    descending: true,
  }),
)
//=> [30, 5, 4, 3, 2, 1]

/**
 * DATA: PERSON OBJECTS
 * --------------------
 */

arr = [
  { name: 'john', age: 4 },
  { name: 'bill', age: 8 },
]

/**
 * SORT OBJECTS BY PROPERTY
 * ------------------------
 */

arr.sort(
  compare({
    by: 'name',
  }),
)

/* =>
  [
    { name: 'bill', age: 8 },
    { name: 'john', age: 4 },
  ]
*/

arr.sort(
  compare({
    numeric: true,
    by: 'age',
  }),
)

/* =>
  [
    { name: 'john', age: 4 },
    { name: 'bill', age: 8 },
  ]
*/

/**
 * DATA: PERSON OBJECTS WITH NESTED NAME OBJECTS
 * ---------------------------------------------
 */

arr = [
  { id: 0, name: { first: 'snoop', last: 'doggy' } },
  { id: 1, name: { first: 'kurt', last: 'qobain' } },
]

/**
 * SORT OBJECTS BY NESTED PROPERTY WITH DOT NOTATION
 * -------------------------------------------------
 */

arr.sort(
  compare({
    by: 'name.first',
  }),
)

/* =>
  [
    { id: 1, name: { first: 'kurt', last: 'qobain' } },
    { id: 0, name: { first: 'snoop', last: 'doggy' } },
  ]
*/

arr.sort(
  compare({
    by: 'name.last',
  }),
)

/* =>
  [
    { id: 0, name: { first: 'snoop', last: 'doggy' } },
    { id: 1, name: { first: 'kurt', last: 'qobain' } },
  ]
*/

/**
 * DATA: STRING DIRECTORY PATHS SPLIT IN ARRAYS
 * --------------------------------------------
 */

arr = [
  ['repo', 'src', 'compare.js'],
  ['repo', 'docs', 'index.html'],
]

/**
 * SORT BY ARRAY INDEX
 * -------------------
 */

arr.sort(
  compare({
    by: 2,
  }),
)

/* =>
  [
    ['repo', 'src', 'compare.js'],
    ['repo', 'docs', 'index.html'],
  ]
*/

arr.sort(
  compare({
    by: 1,
  }),
)

/* =>
  [
    ['repo', 'docs', 'index.html' ],
    ['repo', 'src', 'compare.js'],
  ]
*/

/**
 * DATA: DIRECTORY PATHS ARRAYS WITH SUB-ARRAYS
 * --------------------------------------------
 */

arr = [
  ['repo', 'src', ['compare', 'json']],
  ['repo', 'src', ['compare', 'ts']],
  ['repo', 'src', ['compare', 'js']],
]

/**
 * SORT ARRAYS AND SUB-ARRAYS RECURSIVELY
 * ------------------------------------
 */

arr.sort(
  compare({
    arrays: true,
  }),
)

/* =>
  [
    ['repo', 'src', ['compare', 'js']],
    ['repo', 'src', ['compare', 'json']],
    ['repo', 'src', ['compare', 'ts']],
  ]
*/

/**
 * DATA: IP ADDRESSES AS ARRAYS
 * ----------------------------
 */

arr = [
  [192, 168, 0, 1],
  [192, 168, 0, 101],
  [172, 0, 0, 1],
]

/**
 * SORT NUMERIC IP-ADDRESSES AS ARRAYS
 * -----------------------------------
 */

arr.sort(
  compare({
    numeric: true,
    arrays: true,
  }),
)

/* =>
  [
    [172, 0, 0, 1],
    [192, 168, 0, 1],
    [192, 168, 0, 101],
  ]
*/

/**
 * DATA: USER CLASS INSTANCES
 * --------------------------
 */

class User {
  constructor(firstName, lastName) {
    this.firstName = firstName
    this.lastName = lastName
  }
  get fullName() {
    return this.firstName + ' ' + this.lastName
  }
}

arr = [
  new User('john', 'doe'),
  new User('peter', 'wick'),
  new User('peter', 'johnson'),
  new User('les', 'paul'),
]

/**
 * SORT BY GETTER-FUNCTION
 * ------------------------
 */

arr.sort(
  compare({
    by: (user) => {
      return user.fullName
    },
  }),
)

/* =>
  [
    { firstName: 'john', lastName: 'doe'},
    { firstName: 'les', lastName: 'paul'},
    { firstName: 'peter', lastName: 'johnson'},
    { firstName: 'peter', lastName: 'wick'},
  ]
*/

Tests

Uses Jest to test module functionality. Run tests to get coverage details.

npm run test

API

Create array comparator function.

Parameters

options object?
- options.numeric boolean Sort numerically. Defaults to lexicographic/alphabetic sort. (optional, default false)
- options.descending boolean Sort in descending order. Defaults to ascending order. (optional, default false)
- options.array boolean Sort arrays. Nested arrays are also compared recursively. (optional, default false)
- options.by (number | string | getter) Sort by either array index, a callback(element): any - or by object keys with dot-notation support. (optional, default undefined)

Returns comparator

comparator

Type: Function

Parameters

a any The first value to compare
b any The second value to compare

Returns number A negative number if a > b, a positive number if a < b, 0 otherwise.

getter

Type: Function

Parameters

a any The value

Returns any The value to be compared

sortNumeric

Numerical comparison of items. If the passed objects are not numbers, their .valueOf() methods are called to retrieve a numeric value representation of them.