@bemoje/arr-sort-comparator

Create array comparator function.

Version

Travis CI

Dependencies

Stats

Donate

Installation

1npm install @bemoje/arr-sort-comparator
2npm install --save @bemoje/arr-sort-comparator
3npm install --save-dev @bemoje/arr-sort-comparator

Usage

1
2import compare from '@bemoje/arr-sort-comparator'
3
4let arr
5
6/**
7 * DATA: STRINGS
8 * --------------
9 */
10
11arr = ['5', '2', '4', '30', '1', '3']
12
13/**
14 * SORT ALPHABETICALLY BY DEFAULT
15 * ------------------------------
16 */
17
18arr.sort(compare())
19//=> ['1', '2', '3', '30', '4', '5']
20
21/**
22 * DATA: NUMERIC VALUES
23 * ----------------------
24 */
25
26arr = [5, 2, 4, 30, 1, 3]
27
28/**
29 * SORT NUMERICALLY
30 * ----------------
31 */
32
33arr.sort(
34  compare({
35    numeric: true,
36  }),
37)
38//=> [1, 2, 3, 4, 5, 30]
39
40/**
41 * SORT DESCENDING
42 * ---------------
43 */
44
45arr.sort(
46  compare({
47    numeric: true,
48    descending: true,
49  }),
50)
51//=> [30, 5, 4, 3, 2, 1]
52
53/**
54 * DATA: PERSON OBJECTS
55 * --------------------
56 */
57
58arr = [
59  { name: 'john', age: 4 },
60  { name: 'bill', age: 8 },
61]
62
63/**
64 * SORT OBJECTS BY PROPERTY
65 * ------------------------
66 */
67
68arr.sort(
69  compare({
70    by: 'name',
71  }),
72)
73
74/* =>
75  [
76    { name: 'bill', age: 8 },
77    { name: 'john', age: 4 },
78  ]
79*/
80
81arr.sort(
82  compare({
83    numeric: true,
84    by: 'age',
85  }),
86)
87
88/* =>
89  [
90    { name: 'john', age: 4 },
91    { name: 'bill', age: 8 },
92  ]
93*/
94
95/**
96 * DATA: PERSON OBJECTS WITH NESTED NAME OBJECTS
97 * ---------------------------------------------
98 */
99
100arr = [
101  { id: 0, name: { first: 'snoop', last: 'doggy' } },
102  { id: 1, name: { first: 'kurt', last: 'qobain' } },
103]
104
105/**
106 * SORT OBJECTS BY NESTED PROPERTY WITH DOT NOTATION
107 * -------------------------------------------------
108 */
109
110arr.sort(
111  compare({
112    by: 'name.first',
113  }),
114)
115
116/* =>
117  [
118    { id: 1, name: { first: 'kurt', last: 'qobain' } },
119    { id: 0, name: { first: 'snoop', last: 'doggy' } },
120  ]
121*/
122
123arr.sort(
124  compare({
125    by: 'name.last',
126  }),
127)
128
129/* =>
130  [
131    { id: 0, name: { first: 'snoop', last: 'doggy' } },
132    { id: 1, name: { first: 'kurt', last: 'qobain' } },
133  ]
134*/
135
136/**
137 * DATA: STRING DIRECTORY PATHS SPLIT IN ARRAYS
138 * --------------------------------------------
139 */
140
141arr = [
142  ['repo', 'src', 'compare.js'],
143  ['repo', 'docs', 'index.html'],
144]
145
146/**
147 * SORT BY ARRAY INDEX
148 * -------------------
149 */
150
151arr.sort(
152  compare({
153    by: 2,
154  }),
155)
156
157/* =>
158  [
159    ['repo', 'src', 'compare.js'],
160    ['repo', 'docs', 'index.html'],
161  ]
162*/
163
164arr.sort(
165  compare({
166    by: 1,
167  }),
168)
169
170/* =>
171  [
172    ['repo', 'docs', 'index.html' ],
173    ['repo', 'src', 'compare.js'],
174  ]
175*/
176
177/**
178 * DATA: DIRECTORY PATHS ARRAYS WITH SUB-ARRAYS
179 * --------------------------------------------
180 */
181
182arr = [
183  ['repo', 'src', ['compare', 'json']],
184  ['repo', 'src', ['compare', 'ts']],
185  ['repo', 'src', ['compare', 'js']],
186]
187
188/**
189 * SORT ARRAYS AND SUB-ARRAYS RECURSIVELY
190 * ------------------------------------
191 */
192
193arr.sort(
194  compare({
195    arrays: true,
196  }),
197)
198
199/* =>
200  [
201    ['repo', 'src', ['compare', 'js']],
202    ['repo', 'src', ['compare', 'json']],
203    ['repo', 'src', ['compare', 'ts']],
204  ]
205*/
206
207/**
208 * DATA: IP ADDRESSES AS ARRAYS
209 * ----------------------------
210 */
211
212arr = [
213  [192, 168, 0, 1],
214  [192, 168, 0, 101],
215  [172, 0, 0, 1],
216]
217
218/**
219 * SORT NUMERIC IP-ADDRESSES AS ARRAYS
220 * -----------------------------------
221 */
222
223arr.sort(
224  compare({
225    numeric: true,
226    arrays: true,
227  }),
228)
229
230/* =>
231  [
232    [172, 0, 0, 1],
233    [192, 168, 0, 1],
234    [192, 168, 0, 101],
235  ]
236*/
237
238/**
239 * DATA: USER CLASS INSTANCES
240 * --------------------------
241 */
242
243class User {
244  constructor(firstName, lastName) {
245    this.firstName = firstName
246    this.lastName = lastName
247  }
248  get fullName() {
249    return this.firstName + ' ' + this.lastName
250  }
251}
252
253arr = [
254  new User('john', 'doe'),
255  new User('peter', 'wick'),
256  new User('peter', 'johnson'),
257  new User('les', 'paul'),
258]
259
260/**
261 * SORT BY GETTER-FUNCTION
262 * ------------------------
263 */
264
265arr.sort(
266  compare({
267    by: (user) => {
268      return user.fullName
269    },
270  }),
271)
272
273/* =>
274  [
275    { firstName: 'john', lastName: 'doe'},
276    { firstName: 'les', lastName: 'paul'},
277    { firstName: 'peter', lastName: 'johnson'},
278    { firstName: 'peter', lastName: 'wick'},
279  ]
280*/
281

Tests

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

1npm run test

API

Table of Contents

• • Parameters

• comparator

  • Parameters

• getter

  • Parameters

• sortNumeric

  • Parameters

• sortAlpha

  • Parameters

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.

Parameters

• a (number | object) First item to compare.

• b (number | object) Second item to compare.

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

sortAlpha

Alphabetical comparison of items.

Parameters

• a (string | object | number) First element to compare.

• b (string | object | number) Second element to compare.

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