0
# Lodash Partition
1

2
Lodash Partition provides the `partition` method from the lodash library as a standalone module. It creates an array of elements split into two groups based on the result of running each element through a predicate function. The first group contains elements for which the predicate returns truthy, and the second group contains elements for which the predicate returns falsey.
3

4
## Package Information
5

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

11
## Core Imports
12

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

17
For ES modules (if using a bundler):
18

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

23
## Basic Usage
24

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

28
var users = [
29
  { 'user': 'barney',  'age': 36, 'active': false },
30
  { 'user': 'fred',    'age': 40, 'active': true },
31
  { 'user': 'pebbles', 'age': 1,  'active': false }
32
];
33

34
// Function predicate
35
partition(users, function(o) { return o.active; });
36
// => [
37
//   [{ 'user': 'fred', 'age': 40, 'active': true }],
38
//   [{ 'user': 'barney', 'age': 36, 'active': false }, { 'user': 'pebbles', 'age': 1, 'active': false }]
39
// ]
40

41
// Property path shorthand
42
partition(users, 'active');
43
// => [
44
//   [{ 'user': 'fred', 'age': 40, 'active': true }],
45
//   [{ 'user': 'barney', 'age': 36, 'active': false }, { 'user': 'pebbles', 'age': 1, 'active': false }]
46
// ]
47
```
48

49
## Capabilities
50

51
### Partition Function
52

53
Creates an array of elements split into two groups based on the result of running each element through a predicate function.
54

55
```javascript { .api }
56
/**
57
 * Creates an array of elements split into two groups, the first of which
58
 * contains elements predicate returns truthy for, the second of which
59
 * contains elements predicate returns falsey for. The predicate is invoked
60
 * with one argument: (value).
61
 *
62
 * @param {Array|Object} collection The collection to iterate over.
63
 * @param {Function|Object|string} [predicate=_.identity] The function invoked per iteration.
64
 * @returns {Array} Returns the array of grouped elements.
65
 */
66
function partition(collection, predicate);
67
```
68

69
**Parameters:**
70
- `collection` *(Array|Object)*: The collection to iterate over
71
- `[predicate=_.identity]` *(Function|Object|string)*: The function invoked per iteration
72

73
**Returns:**
74
- *(Array)*: Returns the array of grouped elements - first group contains elements for which predicate returns truthy, second group contains elements for which predicate returns falsey
75

76
**Predicate Formats:**
77

78
The predicate parameter supports multiple formats for maximum flexibility:
79

80
1. **Function**: Custom predicate function
81
   ```javascript
82
   partition(users, function(o) { return o.active; });
83
   ```
84

85
2. **Object**: The `_.matches` iteratee shorthand
86
   ```javascript
87
   partition(users, { 'age': 1, 'active': false });
88
   ```
89

90
3. **Array**: The `_.matchesProperty` iteratee shorthand  
91
   ```javascript
92
   partition(users, ['active', false]);
93
   ```
94

95
4. **String**: The `_.property` iteratee shorthand
96
   ```javascript
97
   partition(users, 'active');
98
   ```
99

100
**Usage Examples:**
101

102
```javascript
103
var partition = require('lodash.partition');
104

105
var users = [
106
  { 'user': 'barney',  'age': 36, 'active': false },
107
  { 'user': 'fred',    'age': 40, 'active': true },
108
  { 'user': 'pebbles', 'age': 1,  'active': false }
109
];
110

111
// Using function predicate
112
var result1 = partition(users, function(o) { return o.active; });
113
// => [
114
//   [{ 'user': 'fred', 'age': 40, 'active': true }],
115
//   [{ 'user': 'barney', 'age': 36, 'active': false }, { 'user': 'pebbles', 'age': 1, 'active': false }]
116
// ]
117

118
// Using object predicate (matches properties)
119
var result2 = partition(users, { 'age': 1, 'active': false });
120
// => [
121
//   [{ 'user': 'pebbles', 'age': 1, 'active': false }],
122
//   [{ 'user': 'barney', 'age': 36, 'active': false }, { 'user': 'fred', 'age': 40, 'active': true }]
123
// ]
124

125
// Using array predicate (property-value pair)
126
var result3 = partition(users, ['active', false]);
127
// => [
128
//   [{ 'user': 'barney', 'age': 36, 'active': false }, { 'user': 'pebbles', 'age': 1, 'active': false }],
129
//   [{ 'user': 'fred', 'age': 40, 'active': true }]
130
// ]
131

132
// Using string predicate (property path)
133
var result4 = partition(users, 'active');
134
// => [
135
//   [{ 'user': 'fred', 'age': 40, 'active': true }],
136
//   [{ 'user': 'barney', 'age': 36, 'active': false }, { 'user': 'pebbles', 'age': 1, 'active': false }]
137
// ]
138

139
// Working with arrays
140
var numbers = [1, 2, 3, 4, 5, 6];
141
var evenOdd = partition(numbers, function(n) { return n % 2 === 0; });
142
// => [[2, 4, 6], [1, 3, 5]]
143

144
// Working with objects
145
var obj = { 'a': 1, 'b': 2, 'c': 3, 'd': 4 };
146
var objPartition = partition(obj, function(value) { return value > 2; });
147
// => [[3, 4], [1, 2]]
148
```
149

150
## Implementation Notes
151

152
- **Zero Dependencies**: The package is completely self-contained with no external dependencies
153
- **Collection Support**: Works with both arrays and objects
154
- **Immutable**: Does not modify the original collection
155
- **Performance**: Uses optimized internal utilities for efficient iteration
156
- **Compatibility**: Follows lodash v4.6.0 conventions and behavior
157
- **Module Format**: CommonJS export (`module.exports = partition`)