npm-lodash

1
# Lodash
2

3
Lodash is a modern JavaScript utility library delivering modularity, performance, and extras. This Knowledge Tile focuses on the `_.sortBy` method, which creates an array of elements sorted in ascending order by the results of running each element in a collection through each iteratee. This method performs a stable sort, preserving the original sort order of equal elements.
4

5
## Package Information
6

7
- **Package Name**: lodash
8
- **Package Type**: npm  
9
- **Language**: JavaScript
10
- **Installation**: `npm install lodash`
11

12
## Core Imports
13

14
```javascript
15
const _ = require('lodash');
16
const sortBy = _.sortBy;
17
```
18

19
For ES modules:
20

21
```javascript
22
import _ from 'lodash';
23
import { sortBy } from 'lodash';
24
```
25

26
## Basic Usage
27

28
```javascript
29
const _ = require('lodash');
30

31
const users = [
32
  { 'user': 'fred',   'age': 48 },
33
  { 'user': 'barney', 'age': 36 },
34
  { 'user': 'fred',   'age': 40 },
35
  { 'user': 'barney', 'age': 34 }
36
];
37

38
// Sort by user name using function iteratee
39
const sortedByUser = _.sortBy(users, function(o) { return o.user; });
40
// => objects for [['barney', 36], ['barney', 34], ['fred', 48], ['fred', 40]]
41

42
// Sort by property name using string shorthand
43
const sortedByAge = _.sortBy(users, 'age');
44
// => objects for [['barney', 34], ['barney', 36], ['fred', 40], ['fred', 48]]
45

46
// Sort by multiple criteria
47
const sortedMultiple = _.sortBy(users, ['user', 'age']);
48
// => objects for [['barney', 34], ['barney', 36], ['fred', 40], ['fred', 48]]
49
```
50

51
## Capabilities
52

53
### Sort By Function
54

55
Creates an array of elements, sorted in ascending order by the results of running each element in a collection through each iteratee.
56

57
```javascript { .api }
58
/**
59
 * Creates an array of elements, sorted in ascending order by the results of
60
 * running each element in a collection through each iteratee. This method
61
 * performs a stable sort, that is, it preserves the original sort order of
62
 * equal elements. The iteratees are invoked with one argument: (value).
63
 *
64
 * @static
65
 * @memberOf _
66
 * @since 0.1.0
67
 * @category Collection
68
 * @param {Array|Object} collection The collection to iterate over.
69
 * @param {...(Array|Array[]|Function|Function[]|Object|Object[]|string|string[])} [iteratees=[_.identity]]
70
 *  The iteratees to sort by, specified individually or in arrays.
71
 * @returns {Array} Returns the new sorted array.
72
 */
73
function sortBy(collection, ...iteratees)
74
```
75

76
**Parameters:**
77

78
- `collection` *(Array|Object)*: The collection to iterate over
79
- `...iteratees` *(...(Array|Array[]|Function|Function[]|Object|Object[]|string|string[]))*: The iteratees to sort by, specified individually or in arrays
80

81
**Returns:**
82

83
*(Array)*: Returns the new sorted array
84

85
**Key Features:**
86

87
- **Stable Sort**: Preserves the original sort order of equal elements
88
- **Multiple Iteratees**: Supports sorting by multiple criteria
89
- **Flexible Iteratees**: Accepts functions, property shortcuts, or object matchers
90
- **Null/Undefined Handling**: Moves `null`, `undefined`, and `NaN` values to the end
91
- **Object Collections**: Works with both arrays and objects as collections
92
- **Empty Collection Handling**: Returns empty array for `null`, `undefined`, or numeric collections
93

94
**Usage Examples:**
95

96
```javascript
97
const _ = require('lodash');
98

99
// Function iteratee
100
_.sortBy(users, function(o) { return o.user; });
101

102
// Property shorthand
103
_.sortBy(users, 'age');
104

105
// Multiple criteria (array of iteratees)
106
_.sortBy(users, ['user', 'age']);
107

108
// Mixed iteratees
109
_.sortBy(users, 'user', function(o) {
110
  return Math.floor(o.age / 10);
111
});
112

113
// No iteratee (uses identity function)
114
_.sortBy([3, 2, 1]); // => [1, 2, 3]
115

116
// Object as collection
117
_.sortBy({ 'a': 1, 'b': 2, 'c': 3 }, Math.sin); // => [3, 1, 2]
118

119
// Handling special values
120
_.sortBy([NaN, undefined, null, 4, null, 1, undefined, 3, NaN, 2]);
121
// => [1, 2, 3, 4, null, null, undefined, undefined, NaN, NaN]
122

123
// Arrays returned from iteratee are coerced
124
const objects = [
125
  { 'a': 'x', 'b': 3 },
126
  { 'a': 'y', 'b': 4 },
127
  { 'a': 'x', 'b': 1 },
128
  { 'a': 'y', 'b': 2 }
129
];
130
_.sortBy(objects, function(object) {
131
  var result = [object.a, object.b];
132
  result.toString = function() { return String(this[0]); };
133
  return result;
134
});
135

136
// Works as iteratee for other methods
137
[[2, 1, 3], [3, 2, 1]].map(_.sortBy); // => [[1, 2, 3], [1, 2, 3]]
138
```
139

140
**Error Handling:**
141

142
- Returns `[]` when collection is `null` or `undefined`
143
- Treats numeric values for collection as empty and returns `[]`
144
- Places `null`, `undefined`, and `NaN` values at the end of sorted results
145
- Falls back to identity function when iteratee is nullish
146

147
**Performance Characteristics:**
148

149
- Time complexity: O(n log n) where n is the collection size
150
- Stable sort algorithm preserves relative order of equal elements
151
- Creates a new array rather than modifying the input collection
152
- Uses efficient internal sorting with compareMultiple for multiple criteria