0
# Tree Navigation
1

2
Navigate between parents, children, and siblings with constant-time operations.
3

4
## Capabilities
5

6
### Check for Children
7

8
Determine if an object has any child objects.
9

10
```javascript { .api }
11
/**
12
 * Check if object has any children
13
 * Time Complexity: O(1)
14
 * @param {Object} object - Object to check
15
 * @returns {boolean} True if object has children, false otherwise
16
 */
17
hasChildren(object: Object): boolean;
18
```
19

20
### Child Navigation
21

22
Access first and last child objects.
23

24
```javascript { .api }
25
/**
26
 * Get the first child of an object
27
 * Time Complexity: O(1)
28
 * @param {Object} object - Parent object
29
 * @returns {Object|null} First child object or null if no children
30
 */
31
firstChild(object: Object): Object | null;
32

33
/**
34
 * Get the last child of an object
35
 * Time Complexity: O(1)
36
 * @param {Object} object - Parent object
37
 * @returns {Object|null} Last child object or null if no children
38
 */
39
lastChild(object: Object): Object | null;
40
```
41

42
### Sibling Navigation
43

44
Navigate between sibling objects.
45

46
```javascript { .api }
47
/**
48
 * Get the previous sibling of an object
49
 * Time Complexity: O(1)
50
 * @param {Object} object - Reference object
51
 * @returns {Object|null} Previous sibling object or null if none
52
 */
53
previousSibling(object: Object): Object | null;
54

55
/**
56
 * Get the next sibling of an object
57
 * Time Complexity: O(1)
58
 * @param {Object} object - Reference object
59
 * @returns {Object|null} Next sibling object or null if none
60
 */
61
nextSibling(object: Object): Object | null;
62
```
63

64
### Parent Navigation
65

66
Access the parent of an object.
67

68
```javascript { .api }
69
/**
70
 * Get the parent of an object
71
 * Time Complexity: O(1)
72
 * @param {Object} object - Child object
73
 * @returns {Object|null} Parent object or null if no parent
74
 */
75
parent(object: Object): Object | null;
76
```
77

78
## Usage Examples
79

80
```javascript
81
const SymbolTree = require("symbol-tree");
82
const tree = new SymbolTree();
83

84
// Create a tree structure
85
const parent = { name: "parent" };
86
const child1 = { name: "child1" };
87
const child2 = { name: "child2" };
88
const grandchild = { name: "grandchild" };
89

90
tree.appendChild(parent, child1);
91
tree.appendChild(parent, child2);
92
tree.appendChild(child1, grandchild);
93

94
// Navigate the tree
95
console.log(tree.hasChildren(parent)); // true
96
console.log(tree.hasChildren(child1)); // true
97
console.log(tree.hasChildren(child2)); // false
98

99
// Access children
100
console.log(tree.firstChild(parent) === child1); // true
101
console.log(tree.lastChild(parent) === child2); // true
102

103
// Navigate siblings
104
console.log(tree.nextSibling(child1) === child2); // true
105
console.log(tree.previousSibling(child2) === child1); // true
106
console.log(tree.nextSibling(child2)); // null (no next sibling)
107

108
// Access parents
109
console.log(tree.parent(child1) === parent); // true
110
console.log(tree.parent(grandchild) === child1); // true
111
console.log(tree.parent(parent)); // null (no parent)
112

113
// Traverse an entire branch
114
function printBranch(node, indent = 0) {
115
  const spaces = " ".repeat(indent);
116
  console.log(spaces + node.name);
117
  
118
  for (let child = tree.firstChild(node); child; child = tree.nextSibling(child)) {
119
    printBranch(child, indent + 2);
120
  }
121
}
122

123
printBranch(parent);
124
// Output:
125
// parent
126
//   child1
127
//     grandchild
128
//   child2
129
```
130

131
## Linked List Usage
132

133
```javascript
134
const tree = new SymbolTree();
135

136
// Create a linked list
137
const nodeA = { value: "A" };
138
const nodeB = { value: "B" };
139
const nodeC = { value: "C" };
140

141
tree.insertBefore(nodeB, nodeA); // A -> B
142
tree.insertAfter(nodeB, nodeC);  // A -> B -> C
143

144
// Navigate the linked list
145
let current = nodeA;
146
while (current) {
147
  console.log(current.value);
148
  current = tree.nextSibling(current);
149
}
150
// Output: A, B, C
151

152
// Navigate backwards
153
current = nodeC;
154
while (current) {
155
  console.log(current.value);
156
  current = tree.previousSibling(current);
157
}
158
// Output: C, B, A
159
```