0
# Lodash Partition
1

2
Lodash Partition provides the `_.partition` utility function as a standalone module for splitting arrays or objects into two groups based on a predicate function. This is part of the modular lodash build system that enables tree-shaking and reduced bundle sizes.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
const partition = require('lodash.partition');
15
```
16

17
ES modules:
18

19
```javascript
20
import partition from 'lodash.partition';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const partition = require('lodash.partition');
27

28
// Basic numeric predicate
29
const numbers = [1, 2, 3, 4, 5, 6];
30
const [odds, evens] = partition(numbers, function(n) {
31
  return n % 2;
32
});
33
// Result: [[1, 3, 5], [2, 4, 6]]
34

35
// Object partitioning with property shorthand
36
const users = [
37
  { name: 'Alice', active: true },
38
  { name: 'Bob', active: false },
39
  { name: 'Charlie', active: true }
40
];
41
const [activeUsers, inactiveUsers] = partition(users, 'active');
42
// Result: [[{name: 'Alice', active: true}, {name: 'Charlie', active: true}], [{name: 'Bob', active: false}]]
43
```
44

45
## Capabilities
46

47
### Array and Object Partitioning
48

49
Splits a collection into two groups based on a predicate function or property-based criteria.
50

51
```javascript { .api }
52
/**
53
 * Creates an array of elements split into two groups, the first of which
54
 * contains elements predicate returns truthy for, while the second of which
55
 * contains elements predicate returns falsey for. The predicate is bound
56
 * to thisArg and invoked with three arguments: (value, index|key, collection).
57
 * 
58
 * @param {Array|Object|string} collection - The collection to iterate over
59
 * @param {Function|Object|string} [predicate=_.identity] - The function invoked per iteration
60
 * @param {*} [thisArg] - The this binding of predicate
61
 * @returns {Array} Returns the array of grouped elements (two arrays)
62
 */
63
function partition(collection, predicate, thisArg);
64
```
65

66
### Predicate Callback Styles
67

68
The `partition` function supports multiple callback styles for maximum flexibility:
69

70
#### Function Callback
71

72
Custom function with optional `thisArg` binding:
73

74
```javascript
75
// With thisArg binding
76
const decimals = [1.2, 2.3, 3.4];
77
const [group1, group2] = partition(decimals, function(n) {
78
  return this.floor(n) % 2;
79
}, Math);
80
// Result: [[1.2, 3.4], [2.3]]
81

82
// Using all three arguments (value, index, collection)
83
const items = ['a', 'b', 'c', 'd'];
84
const [firstHalf, secondHalf] = partition(items, function(value, index, collection) {
85
  return index < collection.length / 2;
86
});
87
// Result: [['a', 'b'], ['c', 'd']]
88
```
89

90
#### Property Shorthand (`_.property` style)
91

92
String property name creates a property accessor:
93

94
```javascript
95
const users = [
96
  { name: 'Alice', active: true },
97
  { name: 'Bob', active: false }
98
];
99
const [active, inactive] = partition(users, 'active');
100
// Result: [[{name: 'Alice', active: true}], [{name: 'Bob', active: false}]]
101
```
102

103
#### MatchesProperty Shorthand (`_.matchesProperty` style)
104

105
Property name with value for exact matching using `thisArg`:
106

107
```javascript
108
const users = [
109
  { name: 'Alice', age: 25, active: true },
110
  { name: 'Bob', age: 30, active: false },
111
  { name: 'Charlie', age: 25, active: true }
112
];
113
// Using matchesProperty style - thisArg becomes the value to match
114
const [activeUsers, inactiveUsers] = partition(users, 'active', true);
115
// Groups users by whether their 'active' property equals true
116
```
117

118
#### Matches Shorthand (`_.matches` style)
119

120
Object for partial property matching:
121

122
```javascript
123
const users = [
124
  { name: 'Alice', age: 25, active: false },
125
  { name: 'Bob', age: 40, active: true },
126
  { name: 'Charlie', age: 1, active: false }
127
];
128
const [matchingUsers, nonMatchingUsers] = partition(users, { age: 1, active: false });
129
// Result: [[{name: 'Charlie', age: 1, active: false}], [{name: 'Alice', age: 25, active: false}, {name: 'Bob', age: 40, active: true}]]
130
```
131

132
## Return Value
133

134
The `partition` function always returns an array containing exactly two arrays:
135
- **First array**: Elements where the predicate returns truthy values
136
- **Second array**: Elements where the predicate returns falsey values
137

138
Both arrays maintain the original order of elements from the input collection.
139

140
## Supported Collection Types
141

142
- **Arrays**: Most common use case for data partitioning
143
- **Objects**: Iterates over object values (not keys)  
144
- **Strings**: Treats each character as an element to partition
145

146
## Implementation Details
147

148
This module uses `lodash._createaggregator` internally, which provides the iteratee callback handling and collection iteration logic. The predicate function supports lodash's standard callback styles:
149

150
- Function callbacks with optional `thisArg` binding
151
- String property names (_.property style)
152
- String property names with thisArg value (_.matchesProperty style) 
153
- Object pattern matching (_.matches style)
154

155
The partition function is built as an aggregator that creates two arrays and assigns elements to index 0 or 1 based on the truthy/falsy result of the predicate.