@nighly/sort-object-array-by-property
v1.5.0
Published
'sort-object-array-by-property' sorts an array of objects or arrays by one or all their properties, even if some objects don't have all the specified properties. Also works with deep objects and properties, using the syntax 'a.b.c' to access 'a', then 'b'
Downloads
59
Maintainers
tomasfn87Readme
sort-object-array-by-property
Table of contents
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 objectsand indices fromnested arrays.Each set of values (the values that correspond to each property) can be sorted independently, in
ascendingordescendingorder.It supports sorting of texts with accents (
fiancéecomes afterfianceeand beforefiancf, as a text editor would normally behave), making it more useful for latin language users, for example.
:warning: 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)
1) Install package via npm
npm install @nighly/sort-object-array-by-property2) 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 */ 23.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 ] ] ] -> 2Also works with combinations of objects and arrays:
'a.0.b' // -> { a: [ { b: 3 } ] } -> 3
'0.a.0' // -> [ { a: [ 4 ] } ] -> 4Examples:
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(orR) 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
lengthgreater than1containgrorRmust be passed; - only a
ror aRmatters: any other character will just be used to determine which set of values will be reversed, according to thepropertiesorindicespassed inarrayformat toobjProps.
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' );