0
# Path Operations
1

2
Methods for accessing and modifying object properties using path arrays. Paths are arrays of property keys that describe the route to a specific value in nested object structures.
3

4
## Capabilities
5

6
### get Method
7

8
Retrieves the value at the specified path in the object.
9

10
```javascript { .api }
11
/**
12
 * Get value at the specified path
13
 * @param {Array} path - Array of property keys representing the path
14
 * @returns {*} Value at the path, or undefined if path doesn't exist
15
 */
16
traverse(obj).get(path)
17

18
// Functional version
19
traverse.get(obj, path)
20
```
21

22
**Usage Examples:**
23

24
```javascript
25
const traverse = require('traverse');
26

27
const obj = { 
28
    a: { 
29
        b: [1, 2, { c: 'hello' }] 
30
    } 
31
};
32

33
// Get nested values
34
const value1 = traverse(obj).get(['a', 'b', 2, 'c']); // 'hello'
35
const value2 = traverse(obj).get(['a', 'b', 0]);      // 1
36
const value3 = traverse(obj).get(['a', 'b']);         // [1, 2, { c: 'hello' }]
37
const value4 = traverse(obj).get(['nonexistent']);    // undefined
38

39
// Empty path returns the root object
40
const root = traverse(obj).get([]);                   // obj
41

42
// Functional approach
43
const value = traverse.get(obj, ['a', 'b', 2, 'c']); // 'hello'
44
```
45

46
### set Method
47

48
Sets a value at the specified path, creating intermediate objects as needed.
49

50
```javascript { .api }
51
/**
52
 * Set value at the specified path, creating intermediate objects as needed
53
 * @param {Array} path - Array of property keys representing the path
54
 * @param {*} value - Value to set at the path
55
 * @returns {*} The value that was set
56
 */
57
traverse(obj).set(path, value)
58

59
// Functional version
60
traverse.set(obj, path, value)
61
```
62

63
**Usage Examples:**
64

65
```javascript
66
const traverse = require('traverse');
67

68
const obj = { a: { b: 1 } };
69

70
// Set existing path
71
traverse(obj).set(['a', 'b'], 42);
72
// obj is now: { a: { b: 42 } }
73

74
// Create new nested path
75
traverse(obj).set(['a', 'c', 'd'], 'hello');
76
// obj is now: { a: { b: 42, c: { d: 'hello' } } }
77

78
// Set array index
79
const arr = { items: [1, 2, 3] };
80
traverse(arr).set(['items', 1], 'modified');
81
// arr is now: { items: [1, 'modified', 3] }
82

83
// Functional approach
84
traverse.set(obj, ['x', 'y', 'z'], 'deep value');
85
```
86

87
### has Method
88

89
Checks whether a path exists in the object.
90

91
```javascript { .api }
92
/**
93
 * Check if the specified path exists in the object
94
 * @param {Array} path - Array of property keys representing the path
95
 * @returns {boolean} True if path exists, false otherwise
96
 */
97
traverse(obj).has(path)
98

99
// Functional version
100
traverse.has(obj, path)
101
```
102

103
**Usage Examples:**
104

105
```javascript
106
const traverse = require('traverse');
107

108
const obj = { 
109
    a: { 
110
        b: [1, 2, { c: null }] 
111
    } 
112
};
113

114
// Check existing paths
115
traverse(obj).has(['a']);                    // true
116
traverse(obj).has(['a', 'b']);               // true  
117
traverse(obj).has(['a', 'b', 2, 'c']);      // true (even though value is null)
118
traverse(obj).has(['a', 'b', 0]);           // true
119

120
// Check non-existent paths
121
traverse(obj).has(['a', 'b', 'nonexistent']); // false
122
traverse(obj).has(['x']);                     // false
123
traverse(obj).has(['a', 'b', 5]);            // false (array index out of bounds)
124

125
// Empty path
126
traverse(obj).has([]);                        // true (root always exists)
127

128
// Functional approach
129
const exists = traverse.has(obj, ['a', 'b', 2, 'c']); // true
130
```
131

132
## Path Format
133

134
Paths are arrays containing property keys that can be strings, numbers, or symbols:
135

136
```javascript
137
// String keys for object properties
138
['property', 'nested', 'key']
139

140
// Number keys for array indices  
141
['items', 0, 'name']
142

143
// Mixed keys for complex structures
144
['users', 1, 'addresses', 0, 'street']
145

146
// Symbol keys (when includeSymbols: true)
147
const sym = Symbol('key');
148
[sym, 'property']
149
```
150

151
## Symbol Support
152

153
By default, symbol properties are not included in path operations. Use the `includeSymbols` option to enable symbol support:
154

155
```javascript
156
const sym = Symbol('hidden');
157
const obj = { 
158
    normal: 'value',
159
    [sym]: { data: 'secret' }
160
};
161

162
// Default behavior - symbols ignored
163
traverse(obj).has([sym]); // false
164

165
// With symbol support
166
traverse(obj, { includeSymbols: true }).has([sym]); // true
167
traverse(obj, { includeSymbols: true }).get([sym, 'data']); // 'secret'
168
```
169

170
## Error Handling
171

172
Path operations handle edge cases gracefully:
173

174
- **Non-existent paths**: `get()` returns `undefined`, `has()` returns `false`
175
- **Invalid intermediate objects**: `set()` creates objects as needed
176
- **Array bounds**: Out-of-bounds indices are treated as non-existent
177
- **Null/undefined intermediate values**: Treated as non-traversable, causing path lookup to fail
178
- **Symbol properties**: Ignored unless `includeSymbols: true` is used