0
# lodash.mergewith
1

2
The Lodash method `_.mergeWith` exported as a Node.js module. This package provides deep object merging capabilities with customizable merge behavior through a customizer function.
3

4
## Package Information
5

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

11
## Core Imports
12

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

17
For ES6 environments:
18

19
```javascript
20
const mergeWith = require('lodash.mergewith');
21
```
22

23
ES6 import:
24

25
```javascript
26
import mergeWith from 'lodash.mergewith';
27
```
28

29
## Basic Usage
30

31
```javascript
32
var mergeWith = require('lodash.mergewith');
33

34
// Simple object merging with custom array concatenation
35
function customizer(objValue, srcValue) {
36
  if (Array.isArray(objValue)) {
37
    return objValue.concat(srcValue);
38
  }
39
}
40

41
var object = { 'a': [1], 'b': [2] };
42
var other = { 'a': [3], 'b': [4] };
43

44
mergeWith(object, other, customizer);
45
// => { 'a': [1, 3], 'b': [2, 4] }
46

47
// Multiple source objects
48
var target = { users: ['alice'] };
49
var source1 = { users: ['bob'], roles: ['admin'] };
50
var source2 = { users: ['charlie'], permissions: ['read'] };
51

52
mergeWith(target, source1, source2, customizer);
53
// => { users: ['alice', 'bob', 'charlie'], roles: ['admin'], permissions: ['read'] }
54
```
55

56
## Capabilities
57

58
### Object Merging with Customizer
59

60
Recursively merges objects with customizable merge behavior via a customizer function.
61

62
```javascript { .api }
63
/**
64
 * This method is like _.merge except that it accepts customizer which
65
 * is invoked to produce the merged values of the destination and source
66
 * properties. If customizer returns undefined, merging is handled by the
67
 * method instead. The customizer is invoked with six arguments:
68
 * (objValue, srcValue, key, object, source, stack).
69
 * 
70
 * Note: This method mutates object.
71
 * 
72
 * @param {Object} object The destination object.
73
 * @param {...Object} sources The source objects (customizer is the last argument).
74
 * @returns {Object} Returns object.
75
 */
76
function mergeWith(object, source1, source2, ..., customizer);
77
```
78

79
**Parameters:**
80

81
- `object` (Object): The destination object to merge into (mutated)
82
- `sources` (Object...): The source objects to merge from, with the customizer function as the last argument
83
- `customizer` (Function): Custom function to control merge behavior (last argument in sources)
84

85
**Customizer Function:**
86

87
The customizer function is called with six arguments and determines how values are merged:
88

89
```javascript { .api }
90
/**
91
 * @param {*} objValue The destination value
92
 * @param {*} srcValue The source value
93
 * @param {string} key The key being merged
94
 * @param {Object} object The destination object
95
 * @param {Object} source The source object
96
 * @param {Object} stack Internal stack for handling circular references
97
 * @returns {*} The merged value, or undefined to use default merge behavior
98
 */
99
function customizer(objValue, srcValue, key, object, source, stack);
100
```
101

102
**Returns:**
103

104
- `Object`: Returns the mutated destination object
105

106
**Behavior:**
107

108
- **Mutates** the destination object
109
- Performs **deep/recursive** merging of nested objects
110
- If customizer returns `undefined`, default merge behavior is used
111
- If customizer returns any other value, that value is used for the merge
112
- Supports merging of complex objects, arrays, and primitive values
113
- Handles circular references through internal stack mechanism
114
- Optimized with caching and type checking for performance
115

116
**Usage Examples:**
117

118
```javascript
119
var mergeWith = require('lodash.mergewith');
120

121
// Custom array handling - concatenate instead of replace
122
function arrayCustomizer(objValue, srcValue) {
123
  if (Array.isArray(objValue)) {
124
    return objValue.concat(srcValue);
125
  }
126
}
127

128
var obj1 = { a: [1, 2], b: { x: 1 } };
129
var obj2 = { a: [3, 4], b: { y: 2 } };
130

131
mergeWith(obj1, obj2, arrayCustomizer);
132
// => { a: [1, 2, 3, 4], b: { x: 1, y: 2 } }
133

134
// Custom numeric handling - sum numbers instead of replace
135
function sumCustomizer(objValue, srcValue) {
136
  if (typeof objValue === 'number' && typeof srcValue === 'number') {
137
    return objValue + srcValue;
138
  }
139
}
140

141
var scores = { alice: 10, bob: 5 };
142
var bonuses = { alice: 2, charlie: 8 };
143

144
mergeWith(scores, bonuses, sumCustomizer);
145
// => { alice: 12, bob: 5, charlie: 8 }
146

147
// Conditional merging based on key
148
function conditionalCustomizer(objValue, srcValue, key) {
149
  if (key === 'protected') {
150
    return objValue; // Keep original value for protected keys
151
  }
152
}
153

154
var config = { debug: false, protected: 'secret' };
155
var updates = { debug: true, protected: 'hacked', version: '2.0' };
156

157
mergeWith(config, updates, conditionalCustomizer);
158
// => { debug: true, protected: 'secret', version: '2.0' }
159
```