0
# Lodash Remove
1

2
Lodash Remove provides the `remove` function for mutating arrays by removing elements that match a predicate function. This standalone module exports the same functionality as lodash's `_.remove()` method, enabling selective array element removal while preserving the original array structure.
3

4
## Package Information
5

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

11
## Core Imports
12

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

17
For ES modules (if available):
18

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

23
## Basic Usage
24

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

28
const array = [1, 2, 3, 4, 5, 6];
29
const evens = remove(array, function(n) {
30
  return n % 2 === 0;
31
});
32

33
console.log(array);  // [1, 3, 5] - original array is mutated
34
console.log(evens);  // [2, 4, 6] - removed elements are returned
35
```
36

37
## Capabilities
38

39
### Array Element Removal
40

41
Removes all elements from an array that match a predicate function and returns the removed elements. The original array is mutated in place.
42

43
```javascript { .api }
44
/**
45
 * Removes all elements from array that predicate returns truthy for
46
 * and returns an array of the removed elements. The predicate is invoked
47
 * with three arguments: (value, index, array).
48
 * 
49
 * @param {Array} array - The array to modify
50
 * @param {Array|Function|Object|string} [predicate=_.identity] - The function invoked per iteration
51
 * @returns {Array} Returns the new array of removed elements
52
 */
53
function remove(array, predicate);
54
```
55

56
**Parameters:**
57

58
- `array` (Array): The array to modify. Must be an array-like object that will be mutated.
59
- `predicate` (Array|Function|Object|string, optional): The function invoked per iteration. Supports multiple formats:
60
  - **Function**: Custom predicate `(value, index, array) => boolean`
61
  - **Object**: Matches object properties (deep equal comparison)
62
  - **Array**: Property-value pair `[path, value]` for matching
63
  - **String**: Property path for truthy check
64

65
**Returns:**
66

67
- (Array): New array containing all removed elements in the order they were found
68

69
**Key Characteristics:**
70

71
- **Mutating Operation**: Modifies the original array in place
72
- **Safe Iteration**: Uses two-pass algorithm to avoid index shifting issues
73
- **Predicate Arguments**: Function predicates receive `(value, index, array)`
74
- **Shorthand Support**: Supports lodash iteratee shorthands for common patterns
75
- **Empty Array Handling**: Returns empty array if input is empty, null, or undefined
76

77
**Usage Examples:**
78

79
```javascript
80
const remove = require('lodash.remove');
81

82
// Function predicate
83
const numbers = [1, 2, 3, 4, 5];
84
const evens = remove(numbers, function(n) {
85
  return n % 2 === 0;
86
});
87
// numbers: [1, 3, 5], evens: [2, 4]
88

89
// Object matching shorthand
90
const users = [
91
  { name: 'Alice', active: true },
92
  { name: 'Bob', active: false },
93
  { name: 'Carol', active: true }
94
];
95
const inactive = remove(users, { active: false });
96
// users: [{ name: 'Alice', active: true }, { name: 'Carol', active: true }]
97
// inactive: [{ name: 'Bob', active: false }]
98

99
// Property path shorthand
100
const items = [
101
  { id: 1, archived: false },
102
  { id: 2, archived: true },
103
  { id: 3, archived: false }
104
];
105
const archived = remove(items, 'archived');
106
// items: [{ id: 1, archived: false }, { id: 3, archived: false }]
107
// archived: [{ id: 2, archived: true }]
108

109
// Array shorthand (property-value pair)
110
const products = [
111
  { name: 'Laptop', category: 'electronics' },
112
  { name: 'Book', category: 'books' },
113
  { name: 'Phone', category: 'electronics' }
114
];
115
const electronics = remove(products, ['category', 'electronics']);
116
// products: [{ name: 'Book', category: 'books' }]
117
// electronics: [{ name: 'Laptop', category: 'electronics' }, { name: 'Phone', category: 'electronics' }]
118

119
// Predicate with index and array arguments
120
const data = ['a', 'b', 'c', 'd'];
121
const removed = remove(data, function(value, index, array) {
122
  console.log(`Checking ${value} at index ${index} in array of length ${array.length}`);
123
  return index % 2 === 1; // Remove elements at odd indices
124
});
125
// data: ['a', 'c'], removed: ['b', 'd']
126
```
127

128
**Error Handling:**
129

130
The function handles edge cases gracefully:
131
- Returns empty array if input array is null, undefined, or empty
132
- Skips over array holes and sparse arrays
133
- Predicate functions that throw errors will propagate the error