0
# Traverse
1

2
Traverse is a JavaScript library for recursively walking and transforming objects by visiting every node. It provides both immutable transformations and in-place modifications, with comprehensive support for circular reference detection, deep cloning, and path-based operations on complex nested data structures.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
const traverse = require('traverse');
15
```
16

17
For ES modules (if supported by environment):
18

19
```javascript
20
import traverse from 'traverse';
21
```
22

23
## Basic Usage
24

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

28
// Transform negative numbers in-place
29
const obj = [5, 6, -3, [7, 8, -2, 1], { f: 10, g: -13 }];
30
traverse(obj).forEach(function (x) {
31
    if (x < 0) this.update(x + 128);
32
});
33
// obj is now: [5, 6, 125, [7, 8, 126, 1], { f: 10, g: 115 }]
34

35
// Collect leaf nodes using reduce
36
const data = { a: [1,2,3], b: 4, c: [5,6], d: { e: [7,8], f: 9 } };
37
const leaves = traverse(data).reduce(function (acc, x) {
38
    if (this.isLeaf) acc.push(x);
39
    return acc;
40
}, []);
41
// Result: [1, 2, 3, 4, 5, 6, 7, 8, 9]
42
```
43

44
## Architecture
45

46
Traverse uses a unified approach with both functional and constructor patterns:
47

48
- **Constructor Pattern**: `new traverse(obj)` or `traverse(obj)` returns a Traverse instance
49
- **Functional Pattern**: All instance methods are available as static functions (e.g., `traverse.map(obj, fn)`)
50
- **Traversal Context**: Callbacks receive rich context via `this` object with navigation and modification methods
51
- **Immutable Operations**: Methods like `map()` and `clone()` preserve original objects
52
- **In-place Operations**: Methods like `forEach()` modify objects directly
53
- **Type Handling**: Special support for Arrays, Dates, RegExp, Errors, typed arrays, and circular references
54

55
## Capabilities
56

57
### Object Traversal
58

59
Core traversal methods for iterating through object structures with callback functions that receive rich context information.
60

61
```javascript { .api }
62
// Constructor approach
63
function traverse(obj, options) // Returns Traverse instance
64

65
// Instance methods
66
traverse(obj).forEach(callback)     // In-place modification
67
traverse(obj).map(callback)         // Immutable transformation  
68
traverse(obj).reduce(callback, init) // Reduce to single value
69

70
// Functional approach  
71
traverse.forEach(obj, callback, options)
72
traverse.map(obj, callback, options)
73
traverse.reduce(obj, callback, init)
74
```
75

76
[Object Traversal](./traversal.md)
77

78
### Path Operations
79

80
Methods for accessing and modifying object properties using path arrays, enabling programmatic navigation of nested structures.
81

82
```javascript { .api }
83
traverse(obj).get(path)        // Get value at path
84
traverse(obj).set(path, value) // Set value at path  
85
traverse(obj).has(path)        // Check if path exists
86

87
// Functional versions
88
traverse.get(obj, path)
89
traverse.set(obj, path, value)  
90
traverse.has(obj, path)
91
```
92

93
[Path Operations](./paths.md)
94

95
### Data Extraction
96

97
Utility methods for extracting information from objects including all paths, all node values, and deep cloning with circular reference handling.
98

99
```javascript { .api }
100
traverse(obj).paths()  // Get all non-cyclic paths
101
traverse(obj).nodes()  // Get all node values
102
traverse(obj).clone()  // Deep clone with circular reference handling
103

104
// Functional versions
105
traverse.paths(obj)
106
traverse.nodes(obj)
107
traverse.clone(obj, options)
108
```
109

110
[Data Extraction](./extraction.md)
111

112
## Types
113

114
```javascript { .api }
115
// Options for traversal operations
116
interface TraverseOptions {
117
  immutable?: boolean;      // Create immutable copies during traversal
118
  includeSymbols?: boolean; // Include symbol properties in traversal
119
}
120

121
// Path type - array of property keys
122
type Path = (string | number | symbol)[];
123
```
124

125
## Context API
126

127
When using callback functions with traversal methods, the `this` context provides extensive information and control methods. The context includes navigation properties, state flags, and modification methods.
128

129
[Traversal Context](./context.md)