Skip to content

Commit 5dec83e

Browse files
author
bjvickers
committed
feat: first draft of new docs
1 parent c906e5b commit 5dec83e

File tree

3 files changed

+98
-76
lines changed

3 files changed

+98
-76
lines changed

README.md

Lines changed: 41 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -7,22 +7,25 @@
77
<a name="module_sort-array"></a>
88

99
## sort-array
10-
Sort an array of objects by any property value, at any depth, in any custom order.
10+
Sort an array of objects or primitives, by any property value, in any combindation of ascending, descending, custom or calculated order.
1111

1212
**Example**
1313
```js
1414
const sortBy = require('sort-array')
1515
```
1616
<a name="exp_module_sort-array--sortBy"></a>
1717

18-
### sortBy(recordset, sortBy, [customOrder]) ⇒ <code>Array</code> ⏏
18+
### sortBy(recordset, sortBy, sortTypes, [namedConfigs]) ⇒ <code>Array</code> ⏏
1919
**Kind**: Exported function
2020

2121
| Param | Type | Description |
2222
| --- | --- | --- |
23-
| recordset | <code>Array.&lt;object&gt;</code> | Input array of objects |
24-
| sortBy | <code>string</code> \| <code>Array.&lt;string&gt;</code> | One or more property expressions to sort by, e.g. `'name'` or `'name.first'`. |
25-
| [customOrder] | <code>object</code> | Custom sort order definitions. An object where each key is the property expression and the value is an array specifying the sort order. Example: <br> `{ importance: [ 'speed', 'strength', 'intelligence' ]}` |
23+
| recordset | <code>Array</code> | Input array of objects or primitive values. |
24+
| sortBy | <code>Array.&lt;(string\|function())&gt;</code> | One or more property expressions to sort by. Expressions may be strings which refer to properties in the input array; they may be strings which refer to properties in the optional `namedConfigs.namedComputedProps` parameter; or they may be inline functions which dynamically calculate values for each property in the input array. |
25+
| sortTypes | <code>Array.&lt;(string\|Array.&lt;\*&gt;)&gt;</code> | The sort types for each of the sortBy expressions. Values may be 'asc', 'desc', an array of custom values, and strings which refer to properties in the optional `namedConfigs.namedCustomOrders` parameter. |
26+
| [namedConfigs] | <code>object</code> | Provides a means of reusing computed property functions and custom sort types. |
27+
| [namedConfigs.namedComputedProps] | <code>object</code> | Key/value pairs, where the keys correspond to strings given in the sortBy property list, and the values are functions which will dynamically calculated values for each property in the input array. |
28+
| [namedConfigs.namedCustomOrders] | <code>object</code> | Key/value pairs, where the keys correspond to strings given in the sortTypes list, and the values are arrays of custom values which define the sort type. |
2629

2730
**Example**
2831
with this data
@@ -37,9 +40,9 @@ with this data
3740
]
3841
```
3942

40-
sort by `slot` using the default sort order (alphabetical)
43+
sort by `slot` using an ascending sort type
4144
```js
42-
> sortBy(DJs, 'slot')
45+
> sortBy(DJs, [ 'slot' ], [ 'asc' ])
4346
[ { name: 'Mike', slot: 'afternoon' },
4447
{ name: 'Zane', slot: 'evening' },
4548
{ name: 'Chris', slot: 'morning' },
@@ -48,10 +51,36 @@ sort by `slot` using the default sort order (alphabetical)
4851
{ name: 'Trevor', slot: 'twilight' } ]
4952
```
5053

51-
specify a custom sort order for `slot`
54+
sort by `slot` using a descending sort type
5255
```js
53-
> const slotOrder = [ 'morning', 'afternoon', 'evening', 'twilight' ]
54-
> sortBy(DJs, 'slot', { slot: slotOrder })
56+
> sortBy(DJs, [ 'slot' ], [ 'desc' ])
57+
[ { name: 'Chris', slot: 'twilight' },
58+
{ name: 'Trevor', slot: 'twilight' },
59+
{ name: 'Chris', slot: 'morning' },
60+
{ name: 'Rodney', slot: 'morning' },
61+
{ name: 'Zane', slot: 'evening' },
62+
{ name: 'Mike', slot: 'afternoon' }]
63+
```
64+
65+
sort by `slot` using an 'inline' custom sort type
66+
```js
67+
> sortBy(DJs, [ 'slot' ], [ 'morning', 'afternoon', 'evening', 'twilight' ])
68+
[ { name: 'Rodney', slot: 'morning' },
69+
{ name: 'Chris', slot: 'morning' },
70+
{ name: 'Mike', slot: 'afternoon' },
71+
{ name: 'Zane', slot: 'evening' },
72+
{ name: 'Trevor', slot: 'twilight' },
73+
{ name: 'Chris', slot: 'twilight' } ]
74+
```
75+
76+
sort by `slot` using an 'named' custom sort type
77+
```js
78+
> let namedConfigs = {
79+
namedCustomOrders: {
80+
custOrder1: [ 'morning', 'afternoon', 'evening', 'twilight' ]
81+
}
82+
}
83+
> sortBy(DJs, [ 'slot' ], [ 'custOrder1' ], namedConfigs)
5584
[ { name: 'Rodney', slot: 'morning' },
5685
{ name: 'Chris', slot: 'morning' },
5786
{ name: 'Mike', slot: 'afternoon' },
@@ -60,9 +89,9 @@ specify a custom sort order for `slot`
6089
{ name: 'Chris', slot: 'twilight' } ]
6190
```
6291

63-
sort by `slot` then `name`
92+
sort by `slot` (with a custom sort type) then `name` (with an ascending sort type)
6493
```js
65-
> sortBy(DJs, ['slot', 'name'], { slot: slotOrder })
94+
> sortBy(DJs, ['slot', 'name'], [ [ 'morning', 'afternoon', 'evening', 'twilight' ], 'asc' ])
6695
[ { name: 'Chris', slot: 'morning' },
6796
{ name: 'Rodney', slot: 'morning' },
6897
{ name: 'Mike', slot: 'afternoon' },
@@ -71,31 +100,6 @@ sort by `slot` then `name`
71100
{ name: 'Trevor', slot: 'twilight' } ]
72101
```
73102

74-
sort by nested property values (at any depth) using dot notation (e.g. `'inner.number'`)
75-
```js
76-
> input = [
77-
{ inner: { number: 5 } },
78-
{ inner: { number: 2 } },
79-
{ inner: { number: 3 } },
80-
{ inner: { number: 1 } },
81-
{ inner: { number: 4 } }
82-
]
83-
84-
> sortBy(input, 'inner.number')
85-
[ { inner: { number: 1 } },
86-
{ inner: { number: 2 } },
87-
{ inner: { number: 3 } },
88-
{ inner: { number: 4 } },
89-
{ inner: { number: 5 } } ]
90-
```
91-
92-
a custom order for a nested property looks like this:
93-
```js
94-
const customOrder = {
95-
'inner.number': [ 1, 2, 4, 3, 5 ]
96-
}
97-
```
98-
99103
* * *
100104

101105
&copy; 2015-18 Lloyd Brookes \<75pound@gmail.com\>. Documented by [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown).

index.js

Lines changed: 56 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/**
2-
* Sort an array of objects by any property value, at any depth, in any custom order.
2+
* Sort an array of objects or primitives, by any property value, in any combindation of ascending, descending, custom or calculated order.
33
*
44
* @module sort-array
55
* @typicalname sortBy
@@ -9,12 +9,30 @@
99
module.exports = sortBy
1010

1111
/**
12-
* @param {object[]} - Input array of objects
13-
* @param {string|string[]} - One or more property expressions to sort by, e.g. `'name'` or `'name.first'`.
14-
* @param [customOrder] {object} - Custom sort order definitions. An object where each key is the property expression and the value is an array specifying the sort order. Example: <br>
15-
* `{ importance: [ 'speed', 'strength', 'intelligence' ]}`
12+
* @param {Array} recordset - Input array of objects or primitive values.
13+
*
14+
* @param {Array.<(string|function)>} sortBy - One or more property expressions to sort by. Expressions
15+
* may be strings which refer to properties in the input array; they may be strings which refer to
16+
* properties in the optional `namedConfigs.namedComputedProps` parameter; or they may be inline
17+
* functions which dynamically calculate values for each property in the input array.
18+
*
19+
* @param {Array.<(string|Array.<*>)>} sortTypes - The sort types for each of the sortBy expressions.
20+
* Values may be 'asc', 'desc', an array of custom values, and strings which refer to properties in
21+
* the optional `namedConfigs.namedCustomOrders` parameter.
22+
*
23+
* @param {object} [namedConfigs] - Provides a means of reusing computed property functions and custom sort types.
24+
*
25+
* @param {object} [namedConfigs.namedComputedProps] - Key/value pairs, where the keys correspond to strings
26+
* given in the sortBy property list, and the values are functions which will dynamically calculated values
27+
* for each property in the input array.
28+
*
29+
* @param {object} [namedConfigs.namedCustomOrders] - Key/value pairs, where the keys correspond to strings
30+
* given in the sortTypes list, and the values are arrays of custom values which define the sort type.
31+
*
1632
* @returns {Array}
33+
*
1734
* @alias module:sort-array
35+
*
1836
* @example
1937
* with this data
2038
* ```js
@@ -28,9 +46,9 @@ module.exports = sortBy
2846
* ]
2947
* ```
3048
*
31-
* sort by `slot` using the default sort order (alphabetical)
49+
* sort by `slot` using an ascending sort type
3250
* ```js
33-
* > sortBy(DJs, 'slot')
51+
* > sortBy(DJs, [ 'slot' ], [ 'asc' ])
3452
* [ { name: 'Mike', slot: 'afternoon' },
3553
* { name: 'Zane', slot: 'evening' },
3654
* { name: 'Chris', slot: 'morning' },
@@ -39,10 +57,36 @@ module.exports = sortBy
3957
* { name: 'Trevor', slot: 'twilight' } ]
4058
* ```
4159
*
42-
* specify a custom sort order for `slot`
60+
* sort by `slot` using a descending sort type
61+
* ```js
62+
* > sortBy(DJs, [ 'slot' ], [ 'desc' ])
63+
* [ { name: 'Chris', slot: 'twilight' },
64+
* { name: 'Trevor', slot: 'twilight' },
65+
* { name: 'Chris', slot: 'morning' },
66+
* { name: 'Rodney', slot: 'morning' },
67+
* { name: 'Zane', slot: 'evening' },
68+
* { name: 'Mike', slot: 'afternoon' }]
69+
* ```
70+
*
71+
* sort by `slot` using an 'inline' custom sort type
72+
* ```js
73+
* > sortBy(DJs, [ 'slot' ], [ 'morning', 'afternoon', 'evening', 'twilight' ])
74+
* [ { name: 'Rodney', slot: 'morning' },
75+
* { name: 'Chris', slot: 'morning' },
76+
* { name: 'Mike', slot: 'afternoon' },
77+
* { name: 'Zane', slot: 'evening' },
78+
* { name: 'Trevor', slot: 'twilight' },
79+
* { name: 'Chris', slot: 'twilight' } ]
80+
* ```
81+
*
82+
* sort by `slot` using an 'named' custom sort type
4383
* ```js
44-
* > const slotOrder = [ 'morning', 'afternoon', 'evening', 'twilight' ]
45-
* > sortBy(DJs, 'slot', { slot: slotOrder })
84+
* > let namedConfigs = {
85+
* namedCustomOrders: {
86+
* custOrder1: [ 'morning', 'afternoon', 'evening', 'twilight' ]
87+
* }
88+
* }
89+
* > sortBy(DJs, [ 'slot' ], [ 'custOrder1' ], namedConfigs)
4690
* [ { name: 'Rodney', slot: 'morning' },
4791
* { name: 'Chris', slot: 'morning' },
4892
* { name: 'Mike', slot: 'afternoon' },
@@ -51,41 +95,16 @@ module.exports = sortBy
5195
* { name: 'Chris', slot: 'twilight' } ]
5296
* ```
5397
*
54-
* sort by `slot` then `name`
98+
* sort by `slot` (with a custom sort type) then `name` (with an ascending sort type)
5599
* ```js
56-
* > sortBy(DJs, ['slot', 'name'], { slot: slotOrder })
100+
* > sortBy(DJs, ['slot', 'name'], [ [ 'morning', 'afternoon', 'evening', 'twilight' ], 'asc' ])
57101
* [ { name: 'Chris', slot: 'morning' },
58102
* { name: 'Rodney', slot: 'morning' },
59103
* { name: 'Mike', slot: 'afternoon' },
60104
* { name: 'Zane', slot: 'evening' },
61105
* { name: 'Chris', slot: 'twilight' },
62106
* { name: 'Trevor', slot: 'twilight' } ]
63107
* ```
64-
*
65-
* sort by nested property values (at any depth) using dot notation (e.g. `'inner.number'`)
66-
* ```js
67-
* > input = [
68-
* { inner: { number: 5 } },
69-
* { inner: { number: 2 } },
70-
* { inner: { number: 3 } },
71-
* { inner: { number: 1 } },
72-
* { inner: { number: 4 } }
73-
* ]
74-
*
75-
* > sortBy(input, 'inner.number')
76-
* [ { inner: { number: 1 } },
77-
* { inner: { number: 2 } },
78-
* { inner: { number: 3 } },
79-
* { inner: { number: 4 } },
80-
* { inner: { number: 5 } } ]
81-
* ```
82-
*
83-
* a custom order for a nested property looks like this:
84-
* ```js
85-
* const customOrder = {
86-
* 'inner.number': [ 1, 2, 4, 3, 5 ]
87-
* }
88-
* ```
89108
*/
90109
function sortBy (recordset, sortBy, sortTypes, namedConfigs) {
91110
// First stage data preparation

package.json

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,7 @@
2222
"node": ">=6"
2323
},
2424
"scripts": {
25-
"lint": "standard \"*.js\" \"test/**.js\"",
26-
"lint:fix": "standard --fix \"*.js\" \"test/**.js\"",
25+
"lint": "standard --fix \"*.js\" \"test/**.js\"",
2726
"test": "test-runner test/*.js",
2827
"docs": "jsdoc2md -t README.hbs index.js > README.md; echo"
2928
},

0 commit comments

Comments
 (0)