0
# Data Extraction
1

2
Utility methods for extracting information from objects including all possible paths, all node values, and deep cloning with comprehensive type handling and circular reference detection.
3

4
## Capabilities
5

6
### paths Method
7

8
Returns an array of all possible non-cyclic paths in the object. Each path is represented as an array of property keys leading from the root to a specific node.
9

10
```javascript { .api }
11
/**
12
 * Get all possible non-cyclic paths in the object
13
 * @returns {Array<Array>} Array of path arrays, each representing a route to a node
14
 */
15
traverse(obj).paths()
16

17
// Functional version
18
traverse.paths(obj)
19
```
20

21
**Usage Examples:**
22

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

26
const obj = { 
27
    a: [1, 2], 
28
    b: { c: 3 } 
29
};
30

31
const allPaths = traverse(obj).paths();
32
// Result: [
33
//   [],           // root path
34
//   ['a'],        // array property
35
//   ['a', 0],     // first array element
36
//   ['a', 1],     // second array element  
37
//   ['b'],        // object property
38
//   ['b', 'c']    // nested property
39
// ]
40

41
// Complex nested structure
42
const complex = {
43
    users: [
44
        { name: 'Alice', tags: ['admin'] },
45
        { name: 'Bob', tags: ['user', 'guest'] }
46
    ]
47
};
48

49
const paths = traverse(complex).paths();
50
// Includes paths like: ['users', 0, 'name'], ['users', 1, 'tags', 0], etc.
51
```
52

53
### nodes Method
54

55
Returns an array of all node values in the object in the order they are visited during traversal.
56

57
```javascript { .api }
58
/**
59
 * Get all node values in traversal order
60
 * @returns {Array} Array of all node values encountered during traversal
61
 */
62
traverse(obj).nodes()
63

64
// Functional version
65
traverse.nodes(obj)
66
```
67

68
**Usage Examples:**
69

70
```javascript
71
const traverse = require('traverse');
72

73
const obj = { 
74
    a: [1, 2], 
75
    b: { c: 3 } 
76
};
77

78
const allNodes = traverse(obj).nodes();
79
// Result: [
80
//   { a: [1, 2], b: { c: 3 } },  // root object
81
//   [1, 2],                      // array value
82
//   1,                           // first number
83
//   2,                           // second number
84
//   { c: 3 },                    // nested object
85
//   3                            // nested number
86
// ]
87

88
// Extract specific types of nodes
89
const data = { name: 'test', values: [1, 'two', 3], flag: true };
90
const nodes = traverse(data).nodes();
91
const strings = nodes.filter(node => typeof node === 'string');
92
const numbers = nodes.filter(node => typeof node === 'number');
93
```
94

95
### clone Method
96

97
Creates a deep clone of the object with proper handling of circular references, special object types, and prototype chains.
98

99
```javascript { .api }
100
/**
101
 * Create a deep clone of the object with circular reference handling
102
 * @returns {*} Deep cloned copy of the object
103
 */
104
traverse(obj).clone()
105

106
// Functional version with options
107
traverse.clone(obj, options)
108
```
109

110
**Usage Examples:**
111

112
```javascript
113
const traverse = require('traverse');
114

115
// Basic cloning
116
const original = { 
117
    a: 1, 
118
    b: [2, 3], 
119
    c: { d: 4 } 
120
};
121
const cloned = traverse(original).clone();
122
// cloned is a completely separate object
123

124
// Circular reference handling
125
const circular = { name: 'parent' };
126
circular.self = circular;
127
circular.children = [{ parent: circular }];
128

129
const clonedCircular = traverse(circular).clone();
130
// Circular references are preserved in the clone
131

132
// Special type handling
133
const complex = {
134
    date: new Date(),
135
    regex: /test/gi,
136
    error: new Error('message'),
137
    typedArray: new Uint8Array([1, 2, 3]),
138
    custom: Object.create({ proto: 'value' })
139
};
140

141
const clonedComplex = traverse(complex).clone();
142
// All special types are properly cloned
143
```
144

145
## Type Handling
146

147
The clone method provides comprehensive support for JavaScript's built-in types:
148

149
### Arrays
150
```javascript
151
const arr = [1, [2, 3], { a: 4 }];
152
const cloned = traverse(arr).clone();
153
// Creates new array with deeply cloned elements
154
```
155

156
### Dates
157
```javascript
158
const obj = { created: new Date() };
159
const cloned = traverse(obj).clone();
160
// Date object is cloned with same timestamp
161
```
162

163
### Regular Expressions
164
```javascript
165
const obj = { pattern: /hello/gi };
166
const cloned = traverse(obj).clone();
167
// RegExp is cloned with same pattern and flags
168
```
169

170
### Error Objects
171
```javascript
172
const obj = { error: new Error('Something went wrong') };
173
const cloned = traverse(obj).clone();
174
// Error is cloned with message property preserved
175
```
176

177
### Typed Arrays
178
```javascript
179
const obj = { 
180
    buffer: new Uint8Array([1, 2, 3]),
181
    floats: new Float32Array([1.1, 2.2])
182
};
183
const cloned = traverse(obj).clone();
184
// Typed arrays are properly sliced and cloned
185
```
186

187
### Objects with Custom Prototypes
188
```javascript
189
function CustomClass() { this.value = 42; }
190
CustomClass.prototype.method = function() { return this.value; };
191

192
const obj = { instance: new CustomClass() };
193
const cloned = traverse(obj).clone();
194
// Prototype chain is preserved in the clone
195
```
196

197
### Boolean, Number, String Objects
198
```javascript
199
const obj = {
200
    bool: new Boolean(true),
201
    num: new Number(42), 
202
    str: new String('hello')
203
};
204
const cloned = traverse(obj).clone();
205
// Object wrappers are properly cloned
206
```
207

208
## Symbol Support
209

210
When using the `includeSymbols` option, symbol properties are included in extraction operations:
211

212
```javascript
213
const sym1 = Symbol('key1');
214
const sym2 = Symbol('key2');
215
const obj = { 
216
    normal: 'value',
217
    [sym1]: { [sym2]: 'hidden' }
218
};
219

220
// Default behavior
221
traverse(obj).paths();  // Excludes symbol paths
222
traverse(obj).nodes();  // Excludes symbol property values
223

224
// With symbol support
225
traverse(obj, { includeSymbols: true }).paths();  // Includes symbol paths
226
traverse(obj, { includeSymbols: true }).nodes();  // Includes symbol values
227
traverse(obj, { includeSymbols: true }).clone();  // Clones symbol properties
228
```
229

230
## Circular Reference Detection
231

232
All extraction methods handle circular references appropriately:
233

234
- **paths()**: Stops at circular references, doesn't include cyclic paths
235
- **nodes()**: Includes each unique object only once, stops at cycles  
236
- **clone()**: Preserves circular structure in the cloned object
237

238
```javascript
239
const obj = { name: 'root' };
240
obj.circular = obj;
241
obj.nested = { back: obj };
242

243
const paths = traverse(obj).paths();
244
// Stops at circular references, doesn't create infinite paths
245

246
const cloned = traverse(obj).clone();
247
// cloned.circular === cloned (circular structure preserved)
248
// cloned.nested.back === cloned (maintains relationships)
249
```