You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-**Object Identity**: Objects are compared by reference, not deep equality
210
210
-**Modern Environments**: Requires WeakRef support (Node.js 14.6+, modern browsers)
211
211
212
+
## Advanced Usage
213
+
214
+
For complex scenarios—such as custom traversal orders, subtree iteration, or post-order cleanup—js-tuple provides highly flexible traversal APIs for both `NestedMap` and `NestedSet`. You can choose between depth-first and breadth-first traversal, and between pre-order and post-order yielding, to match your algorithm's needs.
215
+
216
+
-**NestedMap:** See [Advanced NestedMap.entries](./docs/nestedmap-entries-advanced.md) for details on traversal modes, yield order, edge cases, and performance considerations.
217
+
-**NestedSet:** See [Advanced NestedSet](./docs/nestedset-advanced.md) for set-specific traversal, subtree operations, and advanced patterns.
218
+
219
+
These guides cover:
220
+
- How to use `basePath` for partial/subtree traversal
221
+
- Differences between DFS/BFS and pre/post order
222
+
- Edge cases (missing values, empty subtrees)
223
+
- Performance and memory tradeoffs
224
+
225
+
If you need to implement advanced algorithms, process hierarchical data, or optimize traversal, start with these docs!
`NestedMap.entries` provides powerful and flexible iteration over nested keys and values. It supports multiple traversal modes and orderings, making it suitable for advanced tree and graph algorithms.
5
+
6
+
## Traversal Modes
7
+
-**Depth-First (DFS):** Explores as deep as possible before backtracking. Use for recursive-like traversals.
8
+
-**Breadth-First (BFS):** Explores all nodes at the current level before moving deeper. Use for shortest-path or level-order traversals.
9
+
10
+
## Yield Modes
11
+
-**Pre-Order:** Yields a node before its children. Typical for copying or serializing trees.
12
+
-**Post-Order:** Yields a node after all its children. Useful for cleanup, deletion, or dependency resolution.
13
+
14
+
## API Example
15
+
```typescript
16
+
for (const [key, value] ofmap.entries({
17
+
traverseMode: TraverseMode.DepthFirst, // or BreadthFirst
18
+
yieldMode: YieldMode.PreOrder, // or PostOrder
19
+
})) {
20
+
// key: array representing the path
21
+
// value: stored value
22
+
}
23
+
```
24
+
25
+
## Particularities
26
+
-**Flexible Key Paths:** Keys are always arrays, representing the full path in the nested structure.
27
+
-**Partial Traversal:** You can start traversal from any subpath using `basePath`.
28
+
-**Custom Traversal:** Combine `traverseMode` and `yieldMode` for custom iteration order.
29
+
-**Performance:**
30
+
- DFS uses a stack (LIFO), BFS uses a queue (FIFO).
31
+
- BFS post-order requires temporary storage (O(N) memory) to yield nodes in reverse.
32
+
- DFS post-order is naturally recursive and memory-efficient.
33
+
-**Edge Cases:**
34
+
- If a node has no value but has children, only children are yielded.
35
+
- If `basePath` does not exist, iteration yields nothing.
36
+
37
+
## Advanced Patterns
38
+
-**Subtree Traversal:**
39
+
```typescript
40
+
for (const [key, value] ofmap.entries({ basePath: [1, 2] })) {
41
+
// Traverse only the subtree rooted at [1, 2]
42
+
}
43
+
```
44
+
-**Post-Order Cleanup:**
45
+
```typescript
46
+
for (const [key, value] ofmap.entries({ yieldMode: YieldMode.PostOrder })) {
47
+
// Safely delete or process children before parents
48
+
}
49
+
```
50
+
-**Level-Order Processing:**
51
+
```typescript
52
+
for (const [key, value] ofmap.entries({ traverseMode: TraverseMode.BreadthFirst })) {
53
+
// Process nodes level by level
54
+
}
55
+
```
56
+
57
+
## Summary
58
+
`NestedMap.entries` is highly customizable for advanced iteration needs. Choose traversal and yield modes based on your algorithm requirements, and be aware of memory/performance tradeoffs for post-order BFS.
`NestedSet` is a set-like structure for storing and traversing nested keys (arrays as paths). It supports advanced traversal options, making it ideal for hierarchical data, trees, and graphs.
5
+
6
+
## Traversal Modes
7
+
-**Depth-First (DFS):** Explores as deep as possible before backtracking. Use for recursive-like traversals.
8
+
-**Breadth-First (BFS):** Explores all nodes at the current level before moving deeper. Use for level-order or shortest-path traversals.
9
+
10
+
## Yield Modes
11
+
-**Pre-Order:** Yields a node before its children. Useful for copying, exporting, or visiting parents first.
12
+
-**Post-Order:** Yields a node after all its children. Useful for cleanup, deletion, or dependency resolution.
13
+
14
+
## API Example
15
+
```typescript
16
+
for (const [key] ofset.entries({
17
+
traverseMode: TraverseMode.DepthFirst, // or BreadthFirst
18
+
yieldMode: YieldMode.PreOrder, // or PostOrder
19
+
})) {
20
+
// key: array representing the path
21
+
}
22
+
```
23
+
24
+
## Particularities
25
+
-**Flexible Key Paths:** Keys are always arrays, representing the full path in the nested structure.
26
+
-**Partial Traversal:** You can start traversal from any subpath using `basePath`.
27
+
-**Custom Traversal:** Combine `traverseMode` and `yieldMode` for custom iteration order.
28
+
-**Performance:**
29
+
- DFS uses a stack (LIFO), BFS uses a queue (FIFO).
30
+
- BFS post-order requires temporary storage (O(N) memory) to yield nodes in reverse.
31
+
- DFS post-order is naturally recursive and memory-efficient.
32
+
-**Edge Cases:**
33
+
- If a node has no value but has children, only children are yielded.
34
+
- If `basePath` does not exist, iteration yields nothing.
35
+
36
+
## Advanced Patterns
37
+
-**Subtree Traversal:**
38
+
```typescript
39
+
for (const [key] ofset.entries({ basePath: [1, 2] })) {
40
+
// Traverse only the subtree rooted at [1, 2]
41
+
}
42
+
```
43
+
-**Post-Order Cleanup:**
44
+
```typescript
45
+
for (const [key] ofset.entries({ yieldMode: YieldMode.PostOrder })) {
46
+
// Safely delete or process children before parents
47
+
}
48
+
```
49
+
-**Level-Order Processing:**
50
+
```typescript
51
+
for (const [key] ofset.entries({ traverseMode: TraverseMode.BreadthFirst })) {
52
+
// Process nodes level by level
53
+
}
54
+
```
55
+
56
+
## Summary
57
+
`NestedSet` is highly customizable for advanced iteration needs. Choose traversal and yield modes based on your algorithm requirements, and be aware of memory/performance tradeoffs for post-order BFS.
0 commit comments