0
# Lodash Set
1

2
Lodash Set provides a standalone implementation of lodash's `set` function for setting property values at deep object paths using string or array notation. It automatically creates nested objects and arrays as needed when the path doesn't exist, making it ideal for safe deep property assignment without manually checking for intermediate object existence.
3

4
## Package Information
5

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

11
## Core Imports
12

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

17
Note: This package uses CommonJS module format and does not provide native ES module support.
18

19
## Basic Usage
20

21
```javascript
22
var set = require('lodash.set');
23

24
// Basic deep property setting
25
var object = { 'a': [{ 'b': { 'c': 3 } }] };
26
set(object, 'a[0].b.c', 4);
27
console.log(object.a[0].b.c);
28
// => 4
29

30
// Creating new nested paths
31
var object = {};
32
set(object, 'x[0].y.z', 5);
33
console.log(object.x[0].y.z);
34
// => 5
35

36
// String path with dot notation
37
var object = {};
38
set(object, 'a.b.c', 'value');
39
console.log(object.a.b.c);
40
// => 'value'
41

42
// Array path notation
43
var object = {};
44
set(object, ['a', 'b', 'c'], 'value');
45
console.log(object.a.b.c);
46
// => 'value'
47
```
48

49
## Capabilities
50

51
### Set Function
52

53
Sets the property value of `path` on `object`. If a portion of `path` does not exist it's created. Supports both dot notation and bracket notation for property paths.
54

55
```javascript { .api }
56
/**
57
 * Sets the property value of `path` on `object`. If a portion of `path`
58
 * does not exist it's created.
59
 *
60
 * @param {Object} object The object to augment.
61
 * @param {Array|string} path The path of the property to set.
62
 * @param {*} value The value to set.
63
 * @returns {Object} Returns `object`.
64
 */
65
function set(object, path, value);
66
```
67

68
**Parameters:**
69
- `object` (Object): The object to augment. If null or undefined, the function returns the object unchanged.
70
- `path` (Array|string): The path of the property to set. Can be a string using dot notation (`'a.b.c'`), bracket notation (`'a[0].b.c'`), or an array of property names (`['a', 'b', 'c']`).
71
- `value` (*): The value to set at the specified path.
72

73
**Returns:**
74
- (Object): Returns the original `object` with the property set.
75

76
**Behavior:**
77
- Creates intermediate objects (`{}`) for non-numeric path segments
78
- Creates intermediate arrays (`[]`) for numeric path segments (array indices)
79
- Handles mixed object/array paths automatically
80
- Returns the original object unchanged if object is null or undefined
81
- Does not throw errors for invalid paths
82

83
**Usage Examples:**
84

85
```javascript
86
var set = require('lodash.set');
87

88
// Setting nested object properties
89
var obj = {};
90
set(obj, 'user.profile.name', 'John');
91
// obj is now { user: { profile: { name: 'John' } } }
92

93
// Setting array elements
94
var obj = {};
95
set(obj, 'users[0].name', 'Alice');
96
// obj is now { users: [{ name: 'Alice' }] }
97

98
// Mixed object and array paths
99
var obj = {};
100
set(obj, 'data.items[1].tags[0]', 'important');
101
// obj is now { data: { items: [undefined, { tags: ['important'] }] } }
102

103
// Using array path format
104
var obj = {};
105
set(obj, ['config', 'database', 'host'], 'localhost');
106
// obj is now { config: { database: { host: 'localhost' } } }
107

108
// Overwriting existing values
109
var obj = { a: { b: { c: 1 } } };
110
set(obj, 'a.b.c', 999);
111
// obj.a.b.c is now 999
112

113
// Handling null/undefined objects
114
var result = set(null, 'a.b.c', 'value');
115
// result is null (unchanged)
116
```
117

118

119
## Path Format Support
120

121
### String Paths
122

123
**Dot Notation:**
124
- `'a.b.c'` - Simple nested object properties
125
- `'user.profile.settings.theme'` - Deep nested properties
126

127
**Bracket Notation:**
128
- `'a[0]'` - Array index access
129
- `'a[0].b'` - Mixed array and object access
130
- `'users[1].profile.name'` - Complex nested structures
131
- `'a["property with spaces"]'` - Properties with special characters
132
- `'a[\'quoted-property\']'` - Single-quoted properties
133

134
**Mixed Notation:**
135
- `'users[0].profile.settings.theme'` - Combining both notations
136
- `'data.items[1].tags[0]'` - Multiple arrays in path
137

138
### Array Paths
139

140
```javascript
141
// Equivalent path representations
142
set(obj, 'a.b.c', value);           // String notation
143
set(obj, ['a', 'b', 'c'], value);  // Array notation
144
```
145

146
## Error Handling
147

148
The `set` function is designed to be robust and does not throw errors:
149

150
- **Null/undefined objects**: Returns the input unchanged
151
- **Invalid paths**: Attempts to process but may not achieve desired result
152
- **Type conflicts**: Overwrites existing values when setting new paths
153
- **Array index gaps**: Creates sparse arrays with undefined elements
154

155
## Type Coercion and Path Resolution
156

157
- **Numeric strings**: Path segments that are numeric strings (e.g., `'0'`, `'123'`) create array indices
158
- **Non-numeric strings**: Create object properties
159
- **Automatic conversion**: Objects are created as `{}` and arrays as `[]` based on the next path segment
160
- **Path normalization**: String paths are converted to array format internally for processing