0
# Lodash DefaultsDeep
1

2
The Lodash method `defaultsDeep` exported as a standalone module for recursive assignment of default properties. This method is like `_.defaults` except that it recursively assigns default properties from source objects to a destination object, providing deep merging capabilities with preservation of existing values.
3

4
## Package Information
5

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

11
## Core Imports
12

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

17
For ES modules:
18

19
```javascript
20
import defaultsDeep from "lodash.defaultsdeep";
21
```
22

23
## Basic Usage
24

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

28
// Basic deep merging
29
const result = defaultsDeep(
30
  { user: { name: 'barney' } }, 
31
  { user: { name: 'fred', age: 36 } }
32
);
33
// => { user: { name: 'barney', age: 36 } }
34

35
// Multiple sources
36
const config = defaultsDeep(
37
  { database: { host: 'localhost' } },
38
  { database: { host: 'remote', port: 5432, ssl: true } },
39
  { database: { timeout: 30000 } }
40
);
41
// => { database: { host: 'localhost', port: 5432, ssl: true, timeout: 30000 } }
42
```
43

44
## Capabilities
45

46
### Deep Default Assignment
47

48
Recursively assigns default properties from source objects to a destination object. Only assigns properties that are `undefined` in the destination, preserving existing values including `null`.
49

50
```javascript { .api }
51
/**
52
 * Recursively assigns default properties from source objects to destination object.
53
 * This method mutates the destination object and returns it.
54
 * 
55
 * @param {Object} object - The destination object (mutated and returned)
56
 * @param {...Object} sources - The source objects (variable number of arguments)
57
 * @returns {Object} Returns the mutated destination object
58
 */
59
function defaultsDeep(object, ...sources);
60
```
61

62
**Behavior:**
63
- Recursively merges properties from source objects into the destination object
64
- Only assigns properties that are `undefined` in the destination
65
- Does not overwrite existing properties (including `null` values)
66
- Overwrites `undefined` values with source values
67
- Handles nested objects recursively
68
- Preserves function properties without converting them to objects
69
- Handles circular references safely
70
- Does not modify source objects
71
- Prevents merging strings into arrays
72

73
**Usage Examples:**
74

75
```javascript
76
// Preserves existing values
77
const target = { a: { b: null } };
78
const source = { a: { b: 2, c: 3 } };
79
defaultsDeep(target, source);
80
// => { a: { b: null, c: 3 } }
81

82
// Overwrites undefined values
83
const target2 = { a: { b: undefined } };
84
const source2 = { a: { b: 2 } };
85
defaultsDeep(target2, source2);
86
// => { a: { b: 2 } }
87

88
// Handles functions correctly
89
const target3 = {};
90
const source3 = { a: { b: function() { return 'hello'; } } };
91
defaultsDeep(target3, source3);
92
// => { a: { b: [Function] } }
93

94
// Multiple sources (left-to-right precedence)
95
const result = defaultsDeep(
96
  { a: { b: 2 } }, 
97
  { a: { b: 3, c: 3 } }, 
98
  { a: { c: 4, d: 4 } }
99
);
100
// => { a: { b: 2, c: 3, d: 4 } }
101

102
// Prevents string-to-array merging
103
const target4 = { a: ['abc'] };
104
const source4 = { a: 'abc' };
105
defaultsDeep(target4, source4);
106
// => { a: ['abc'] }
107
```
108

109
## Edge Cases and Special Behaviors
110

111
### Null Value Preservation
112
```javascript
113
const object = { a: { b: null } };
114
const source = { a: { b: 2 } };
115
defaultsDeep(object, source);
116
// => { a: { b: null } } - null values are preserved
117
```
118

119
### Undefined Value Override
120
```javascript
121
const object = { a: { b: undefined } };
122
const source = { a: { b: 2 } };
123
defaultsDeep(object, source);
124
// => { a: { b: 2 } } - undefined values are overwritten
125
```
126

127
### Function Property Handling
128
```javascript
129
const fn = function() { return 'test'; };
130
const object = {};
131
const source = { a: fn };
132
defaultsDeep(object, source);
133
// => { a: [Function] } - functions are preserved as-is
134
```
135

136
### Circular Reference Safety
137
```javascript
138
const object = { foo: { b: { c: {} } } };
139
const source = { foo: { b: { c: {} } } };
140
object.foo.b.c.d = object;
141
source.foo.b.c.d = source;
142

143
const result = defaultsDeep(object, source);
144
// Handles circular references without infinite recursion
145
```
146

147
### Source Object Immutability
148
```javascript
149
const source1 = { a: 1, b: { c: 2 } };
150
const source2 = { b: { c: 3, d: 3 } };
151
const result = defaultsDeep({}, source1, source2);
152

153
// Source objects remain unchanged
154
console.log(source1); // => { a: 1, b: { c: 2 } }
155
console.log(source2); // => { b: { c: 3, d: 3 } }
156
```