sort-object-array-by-property

Table of contents

• Description
• Test it on a browser (runkit.com)
• Install
• Import
  • CommonJs
  • ES
  • TypeScript
• Usage
  • Single property
  • Multiple properties
  • Nested properties
  • Reversing
• Dealing with the output
• Examples

Description

sort-object-array-by-property sorts an array of objects or an array of arrays according to a single property (objects) or index (arrays), or by multiple properties / indices, through an array of properties or indices, including thelength property (for arrays and strings).

• It supports properties from nested objects and indices from nested arrays.

• Each set of values (the values that correspond to each property) can be sorted independently, in ascending or descending order.

• It supports sorting of texts with accents (fiancée comes after fiancee and before fiancf, as a text editor would normally behave), making it more useful for latin language users, for example.

⚠️ Warning: be aware that dealing with accentuation uses a lot of resources, so if you don't need to handle this problem, it's strongly recommended to use the previous version:

npm install @nighly/[email protected]

Test it on a browser (runkit)

sort-object-array-by-property

---

1) Install package via npm

    npm install @nighly/sort-object-array-by-property

---

2) Import package

Import function sortObjectArrByProps by adding one of the lines below to a Javascript or Typescript file:

2.1) CommonJs

How to import:

    const sortObjs = require( '@nighly/sort-object-array-by-property' );

How to call:

//  using a single property as sorting parameter:
    sortObjs.sortObjectArrByProps( object_array, prop_1 );

//  using three properties as sorting parameters:
    sortObjs.sortObjectArrByProps( object_array, [ prop_1, prop_2, prop_3 ] );

2.1.1) CommonJs with destructuring (shorter call):

How to import:

    const { sortObjectArrByProps } = require( '@nighly/sort-object-array-by-property' );

How to call:

//  using a single property as sorting parameter:
    sortObjectArrByProps( object_array, prop_1 );

//  using three properties as sorting parameters:
    sortObjectArrByProps( object_array, [ prop_1, prop_2, prop_3 ] );

2.2) ES

How to import:

    import { sortObjectArrByProps } from '@nighly/sort-object-array-by-property/dist/sortObjArrByProps.js';

How to call:

Add "type": "module" to package.json or change the file extension from .js to .mjs.

//  using a single property as sorting parameter:
    sortObjectArrByProps( object_array, prop_1 );

//  using three properties as sorting parameters:
    sortObjectArrByProps( object_array, [ prop_1, prop_2, prop_3 ] );

2.3) Typescript

How to import:

    import { sortObjectArrByProps } from '@nighly/sort-object-array-by-property';

How to call:

//  using a single property as sorting parameter:
    sortObjectArrByProps( object_array, prop_1 );

//  using three properties as sorting parameters:
    sortObjectArrByProps( object_array, [ prop_1, prop_2, prop_3 ] );

---

3) Usage

sortObjectArrByProps sorts objArr, an array containing objects or other arrays according to objProps value(s).

//  using a single property as sorting parameter:
    sortObjectArrByProps( objArr, objProps );

//  using a single property, reversing as sorting parameter:
    sortObjectArrByProps( objArr, objProps, reverse );

//  using multiple properties as sorting parameter:
    sortObjectArrByProps( objArr, [ ...objProps ] );

//  using multiple properties, reversing as sorting parameter:
    sortObjectArrByProps( objArr, [ ...objProps ], reverse );

The arrays can be sorted according to:

3.1) a single property

//  an object's property
    'name'  /* or */  'id'

//  an array's index
    0  /* or */  2

3.2) two, more or all properties

//  an array of objects' properties
    [ 'name', 'age' ]  /* or */  [ 'type', 'price' ]

//  an array of arrays' indices
    [0, 1]  /* or */  [2, 5]

3.3) Using nested objects' properties or nested arrays' indices to sort

To use nested objects' properties or nested arrays' indices, use the syntax below for objProps:

    'a.b.c'  //  ->  { a: { b: { c: 1 } } }  ->  1
    '0.0.0'  //  ->      [ [ [ 2 ] ] ]       ->  2

Also works with combinations of objects and arrays:

    'a.0.b'  //  ->   { a: [ { b: 3 } ] }    ->  3
    '0.a.0'  //  ->    [ { a: [ 4 ] } ]      ->  4

Examples:

    sorbObjectArrByProps( objArr, 'a.b.c' );
    sortObjectArrByProps( arrArr, '0.0.0' );

---

3.4) Reversing all or some values

The third and optional parameter, reverse, can receive as argument a string:

• a single r (or R) will reverse the whole list;
• if only one set of values or some of the sets of values need to be reversed, a string with length greater than 1 containg r or R must be passed;
• only a r or a R matters: any other character will just be used to determine which set of values will be reversed, according to the properties or indices passed in array format to objProps.

Examples:

//  the whole list will be reversed
    sortObjectArrByProps( peopleArr, [ 'country', 'age', 'first_name' ], 'r' )

//  (            s           )(           r         )(              s             )
//  by country standard order > by age reverse order > by first_name standard order
    sortObjectArrByProps( peopleArr, [ 'country', 'age', 'first_name' ], 'srs' )

3.4.1) reverse alternative notations:

As aforementioned (3.4), while s is the standard notation, any string value different from r or R will be accepted:

//  (            r          )(               .            )(            .           )
//  by year descending order > by platform ascending order > by title ascending order
    sortObjectArrByProps( gamesArr, [ 'year', 'platform', 'title' ], 'r..' )

Similarly, the snippet below ...

    sortObjectArrByProps( objList, [ 'prop1', 'prop2' ], 's' );
//  or
    sortObjectArrByProps( arrList, [ 1, 2 ], 's' );

    sortObjectArrByProps( objList, [ 'prop1', 'prop2' ] );
//  or
    sortObjectArrByProps( arrList, [ 1, 2 ] );

... produces the same output as the snippet above.

---

4) Dealing with the output

sortObjectArrByProps returns a new array, leaving the source array untouched, so reattribute the ouput to the same variable to update the values, or attribute it to a new variable, to store the values:

Updating:

    usersList = sortObjectArrByProps(         // <- the variable IS NOT being declared;
        usersList, [                          // <- the list to be sorted IS the same variable that will store the result;
            'birth_date',                     // <- 1st order by, then;
            'last_name',                      // <- 2nd order by, then;
            'first_name',                     // <- 3rd order by, then;
            'email',                          // <- 4th order by, end;
        ], '..R'                              // <- reverse string.
    );

Storing:

    let sortedList = sortObjectArrByProps(    // <- the variable IS being declared;
        list, [                               // <- the list to be sorted IS NOT the same variable that will store the result;
            'date.year',                      // <- 1st order by, then;
            'date.month',                     // <- 2nd order by, then;
            'date.day',                       // <- 3rd order by, then;
            'date.time',                      // <- 4th order by, then;
            'id'                              // <- 5th order by, end;
       ], 'RrRr.'                             // <- reverse string.
    );

---

5) Examples

The comments represent the outputs:

sortObjectArrByProps([
  [ 4, 2 ],                             // ->    [ 1, 4 ],
  [ 3, 5 ],                             // ->    [ 2, 3 ],
  [ 1, 4 ],                             // ->    [ 3, 5 ],
  [ 5, 1 ],                             // ->    [ 4, 2 ],
  [ 2, 3 ]                              // ->    [ 5, 1 ]
], 0 );

sortObjectArrByProps([
  [ 4, 2 ],                             // ->    [ 5, 1 ],
  [ 3, 5 ],                             // ->    [ 4, 2 ],
  [ 1, 4 ],                             // ->    [ 3, 5 ],
  [ 5, 1 ],                             // ->    [ 2, 3 ],
  [ 2, 3 ]                              // ->    [ 1, 4 ]
], 0, 'r' );

sortObjectArrByProps([
  { a: 4, b: 2 },                       // ->    { a: 5, b: 1 },
  { a: 3, b: 5 },                       // ->    { a: 4, b: 2 },
  { a: 1, b: 4 },                       // ->    { a: 2, b: 3 },
  { a: 5, b: 1 },                       // ->    { a: 1, b: 4 },
  { a: 2, b: 3 }                        // ->    { a: 3, b: 5 }
], 'b' );

sortObjectArrByProps([
  { a: 4, b: 2 },                       // ->    { a: 3, b: 5 },
  { a: 3, b: 5 },                       // ->    { a: 1, b: 4 },
  { a: 1, b: 4 },                       // ->    { a: 2, b: 3 },
  { a: 5, b: 1 },                       // ->    { a: 4, b: 2 },
  { a: 2, b: 3 }                        // ->    { a: 5, b: 1 }
], 'b', 'r' );

sortObjectArrByProps([
  { a: 1, b: 2 },                       // ->    { a: 1, b: 1 },
  { a: 2, b: 2 },                       // ->    { a: 1, b: 2 },
  { a: 2, b: 1 },                       // ->    { a: 2, b: 1 },
  { a: 1, b: 1 },                       // ->    { a: 2, b: 2 },
  { a: 3, b: 3 }                        // ->    { a: 3, b: 3 }
], [ 'a', 'b' ] );

sortObjectArrByProps([
  { a: 1, b: 2 },                       // ->    { a: 3, b: 3 },
  { a: 2, b: 2 },                       // ->    { a: 2, b: 2 },
  { a: 2, b: 1 },                       // ->    { a: 2, b: 1 },
  { a: 1, b: 1 },                       // ->    { a: 1, b: 2 },
  { a: 3, b: 3 }                        // ->    { a: 1, b: 1 }
], [ 'a', 'b' ], 'r' );

sortObjectArrByProps([
  { a: 1, b: 2 },                       // ->    { a: 1, b: 1 },
  { a: 2, b: 2 },                       // ->    { a: 2, b: 1 },
  { a: 2, b: 1 },                       // ->    { a: 1, b: 2 },
  { a: 1, b: 1 },                       // ->    { a: 2, b: 2 },
  { a: 3, b: 3 }                        // ->    { a: 3, b: 3 }
], [ 'b', 'a' ] );

sortObjectArrByProps([
  { a: 1, b: 2 },                       // ->    { a: 3, b: 3 },
  { a: 2, b: 2 },                       // ->    { a: 2, b: 2 },
  { a: 2, b: 1 },                       // ->    { a: 1, b: 2 },
  { a: 1, b: 1 },                       // ->    { a: 2, b: 1 },
  { a: 3, b: 3 }                        // ->    { a: 1, b: 1 }
], [ 'b', 'a' ], 'r' );

sortObjectArrByProps([
  { c: '2', d: 5 },                     // ->     { a: { b: false }, c: '2', d: 5 },
  { a: { b: true }, c: '11', d: 11 },   // ->     { a: { b: false }, c: '20', d: 3 },
  { a: { b: false }, c: '3', d: 10 },   // ->     { a: { b: false }, c: '3', d: 10 },
  { a: { b: true }, c: '11', d: 6 },    // ->     { a: { b: true }, c: '11', d: 6 },
  { a: { b: false }, c: '20', d: 3 },   // ->     { a: { b: true }, c: '11', d: 11 },
  { a: { b: false }, c: '2', d: 5 },    // ->     { c: '2', d: 5 },
  { c: '2', d: 10 }                     // ->     { c: '2', d: 10 }
], [ 'a.b', 'c', 'd' ] );

sortObjectArrByProps([
  { c: '2', d: 5 },                     // ->     { a: { b: false }, c: '3', d: 10 },
  { a: { b: true }, c: '11', d: 11 },   // ->     { a: { b: false }, c: '20', d: 3 },
  { a: { b: false }, c: '3', d: 10 },   // ->     { a: { b: false }, c: '2', d: 5 },
  { a: { b: true }, c: '11', d: 6 },    // ->     { a: { b: true }, c: '11', d: 11 },
  { a: { b: false }, c: '20', d: 3 },   // ->     { a: { b: true }, c: '11', d: 6 },
  { a: { b: false }, c: '2', d: 5 },    // ->     { c: '2', d: 10 },
  { c: '2', d: 10 }                     // ->     { c: '2', d: 5 }
], [ 'a.b', 'c', 'd' ], '.rr' );

sortObjectArrByProps([
  [[],[],[],[],[]],                     // ->     [[]],
  [[]],                                 // ->     [[],[]],
  [[],[],[],[],[],[]],                  // ->     [[],[],[]],
  [[],[],[]],                           // ->     [[],[],[],[]],
  [[],[]],                              // ->     [[],[],[],[],[]],
  [[],[],[],[]]                         // ->     [[],[],[],[],[],[]]
], 'length' );

sortObjectArrByProps([
  [[],[],[],[],[]],                     // ->     [[],[],[],[],[],[]],
  [[]],                                 // ->     [[],[],[],[],[]],
  [[],[],[],[],[],[]],                  // ->     [[],[],[],[]],
  [[],[],[]],                           // ->     [[],[],[]],
  [[],[]],                              // ->     [[],[]],
  [[],[],[],[]]                         // ->     [[]]
], 'length', 'r' );