0
# lodash.defaults
1

2
The lodash method `_.defaults` exported as a standalone module. This utility function fills in `undefined` properties in an object with the first value present in a list of defaults objects, providing a safe way to assign default values without overwriting existing meaningful data.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
const defaults = require("lodash.defaults");
15
```
16

17
For ES6+ environments:
18

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

23
## Basic Usage
24

25
```javascript
26
const defaults = require("lodash.defaults");
27

28
// Basic property defaulting
29
const result = defaults({ 'user': 'barney' }, { 'age': 36 }, { 'user': 'fred' });
30
// => { 'user': 'barney', 'age': 36 }
31

32
// Null vs undefined handling
33
const withNull = defaults({ 'a': null }, { 'a': 1 });
34
// => { 'a': null } (null is preserved)
35

36
const withUndefined = defaults({ 'a': undefined }, { 'a': 1 });  
37
// => { 'a': 1 } (undefined is filled)
38

39
// Multiple source objects
40
const multiple = defaults(
41
  { name: 'Alice' }, 
42
  { name: 'Bob', age: 25 }, 
43
  { age: 30, city: 'NYC' }
44
);
45
// => { name: 'Alice', age: 25, city: 'NYC' }
46
```
47

48
## Capabilities
49

50
### Default Property Assignment
51

52
Assigns default values to undefined properties in objects, with support for multiple source objects and prototype-aware property handling.
53

54
```javascript { .api }
55
/**
56
 * Assigns own and inherited enumerable properties of source objects to the
57
 * destination object for all destination properties that resolve to `undefined`.
58
 * Source objects are applied from left to right. Once a property is set,
59
 * additional values of the same property are ignored.
60
 *
61
 * Note: This method mutates `object`.
62
 *
63
 * @param {Object} object The destination object.
64
 * @param {...Object} [sources] The source objects.
65
 * @returns {Object} Returns `object`.
66
 */
67
function defaults(object, ...sources);
68
```
69

70
**Key Behaviors:**
71

72
- **Mutates first argument**: The `object` parameter is modified and returned
73
- **Undefined-only assignment**: Only fills properties that are `undefined` in the destination
74
- **Preserves null values**: `null` is treated as a valid value and won't be overwritten
75
- **Left-to-right precedence**: Earlier source objects take priority over later ones
76
- **Prototype awareness**: Correctly handles properties that shadow Object.prototype
77
- **Variable arguments**: Accepts unlimited source objects
78

79
**Usage Examples:**
80

81
```javascript
82
const defaults = require("lodash.defaults");
83

84
// Configuration object with defaults
85
const config = defaults(
86
  userOptions,
87
  { timeout: 5000, retries: 3, verbose: false }
88
);
89

90
// API parameter defaulting
91
function processUser(userData) {
92
  return defaults(userData, {
93
    active: true,
94
    role: 'user',
95
    preferences: {}
96
  });
97
}
98

99
// Prototype property handling
100
const obj = Object.create({ inherited: 'parent' });
101
obj.own = 'child';
102
defaults(obj, { inherited: 'default', new: 'value' });
103
// obj.inherited remains 'parent' (not overwritten)
104
// obj.new becomes 'value' (filled in)
105

106
// Handling constructor and other prototype properties
107
const target = {};
108
defaults(target, { constructor: MyConstructor, toString: customToString });
109
// Fills in constructor and toString if they're undefined on target
110
```
111

112
**Common Use Cases:**
113

114
- Setting default configuration options
115
- Merging user preferences with application defaults  
116
- Filling in missing API response fields
117
- Creating objects with fallback values
118
- Safe property initialization without data loss
119

120
**Important Notes:**
121

122
- Returns the same object reference as the first parameter (mutates input)
123
- Only processes enumerable properties
124
- Source objects are processed left-to-right, first match wins
125
- Undefined properties are filled, but null, 0, false, and "" are preserved
126
- Works correctly with prototype chain properties