0
# Symbol Tree
1

2
Symbol Tree is an efficient tree and linked list data structure library that uses ES6 Symbols to store metadata directly on objects without interference. Designed specifically for DOM tree implementations, it provides constant-time insertion and deletion operations while maintaining tree relationships through Symbol-based metadata storage.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
const SymbolTree = require("symbol-tree");
15
```
16

17
For ES modules:
18

19
```javascript
20
import SymbolTree from "symbol-tree";
21
```
22

23
## Basic Usage
24

25
```javascript
26
const SymbolTree = require("symbol-tree");
27
const tree = new SymbolTree();
28

29
// Create objects - any objects work
30
let parent = { name: "parent" };
31
let child1 = { name: "child1" };
32
let child2 = { name: "child2" };
33

34
// Build a tree structure
35
tree.appendChild(parent, child1);
36
tree.appendChild(parent, child2);
37

38
// Navigate the tree
39
console.log(tree.firstChild(parent) === child1); // true
40
console.log(tree.nextSibling(child1) === child2); // true
41
console.log(tree.parent(child1) === parent); // true
42

43
// Create a linked list
44
let a = { value: "a" };
45
let b = { value: "b" };
46
let c = { value: "c" };
47

48
tree.insertBefore(b, a); // a comes before b
49
tree.insertAfter(b, c);  // c comes after b
50

51
console.log(tree.nextSibling(a) === b); // true
52
console.log(tree.nextSibling(b) === c); // true
53
```
54

55
## Architecture
56

57
Symbol Tree is built around several key components:
58

59
- **SymbolTree Class**: Main interface providing all tree operations using a private Symbol for metadata storage
60
- **Constant-Time Operations**: Most basic operations (navigation, modification) are O(1)
61
- **Symbol-Based Metadata**: Uses ES6 Symbols to store tree relationships without interfering with object properties
62
- **Iterator Support**: Full ES6 iterator compatibility for all traversal patterns
63
- **Position Comparison**: DOM-compatible position comparison with detailed relationship flags
64

65
## Capabilities
66

67
### Tree Construction and Object Initialization
68

69
Initialize objects for optimal performance and create new tree instances.
70

71
```javascript { .api }
72
/**
73
 * Create a new SymbolTree instance
74
 * @param {string} [description='SymbolTree data'] - Description for the internal Symbol
75
 */
76
class SymbolTree {
77
  constructor(description?: string);
78
}
79

80
/**
81
 * Initialize an object for tree operations (optional optimization)
82
 * @param {Object} object - Object to initialize
83
 * @returns {Object} The same object
84
 */
85
initialize(object: Object): Object;
86
```
87

88
[Tree Construction](./tree-construction.md)
89

90
### Tree Navigation
91

92
Navigate between parents, children, and siblings with constant-time operations.
93

94
```javascript { .api }
95
/**
96
 * Check if object has children
97
 * @param {Object} object - Object to check
98
 * @returns {boolean} True if object has children
99
 */
100
hasChildren(object: Object): boolean;
101

102
/**
103
 * Get first child of object
104
 * @param {Object} object - Parent object
105
 * @returns {Object|null} First child or null
106
 */
107
firstChild(object: Object): Object | null;
108

109
/**
110
 * Get parent of object
111
 * @param {Object} object - Child object
112
 * @returns {Object|null} Parent object or null
113
 */
114
parent(object: Object): Object | null;
115
```
116

117
[Tree Navigation](./tree-navigation.md)
118

119
### Tree Modification
120

121
Insert, append, and remove objects with constant-time operations.
122

123
```javascript { .api }
124
/**
125
 * Insert object as last child of parent
126
 * @param {Object} referenceObject - Parent object
127
 * @param {Object} newObject - Object to insert
128
 * @returns {Object} The inserted object
129
 * @throws {Error} If newObject is already in tree
130
 */
131
appendChild(referenceObject: Object, newObject: Object): Object;
132

133
/**
134
 * Remove object from tree
135
 * @param {Object} removeObject - Object to remove
136
 * @returns {Object} The removed object
137
 */
138
remove(removeObject: Object): Object;
139
```
140

141
[Tree Modification](./tree-modification.md)
142

143
### Tree Traversal
144

145
Advanced traversal operations for finding preceding/following objects and tree boundaries.
146

147
```javascript { .api }
148
/**
149
 * Find preceding object in tree order
150
 * @param {Object} object - Reference object
151
 * @param {Object} [options] - Traversal options
152
 * @param {Object} [options.root] - Root boundary for traversal
153
 * @returns {Object|null} Preceding object or null
154
 */
155
preceding(object: Object, options?: { root?: Object }): Object | null;
156

157
/**
158
 * Find last inclusive descendant
159
 * @param {Object} object - Starting object
160
 * @returns {Object} Last descendant in tree order
161
 */
162
lastInclusiveDescendant(object: Object): Object;
163
```
164

165
[Tree Traversal](./tree-traversal.md)
166

167
### Array Conversion
168

169
Convert tree structures to arrays with optional filtering.
170

171
```javascript { .api }
172
/**
173
 * Convert children to array
174
 * @param {Object} parent - Parent object
175
 * @param {Object} [options] - Conversion options
176
 * @param {Array} [options.array] - Target array
177
 * @param {Function} [options.filter] - Filter function
178
 * @returns {Object[]} Array of children
179
 */
180
childrenToArray(parent: Object, options?: {
181
  array?: Object[];
182
  filter?: (object: Object) => boolean;
183
  thisArg?: any;
184
}): Object[];
185
```
186

187
[Array Conversion](./array-conversion.md)
188

189
### Tree Iterators
190

191
ES6-compatible iterators for all traversal patterns.
192

193
```javascript { .api }
194
/**
195
 * Iterate over children
196
 * @param {Object} parent - Parent object
197
 * @param {Object} [options] - Iterator options
198
 * @param {boolean} [options.reverse] - Iterate in reverse
199
 * @returns {Iterator} ES6 iterator
200
 */
201
childrenIterator(parent: Object, options?: { reverse?: boolean }): Iterator<Object>;
202

203
/**
204
 * Iterate over entire tree
205
 * @param {Object} root - Root object
206
 * @param {Object} [options] - Iterator options
207
 * @param {boolean} [options.reverse] - Iterate in reverse
208
 * @returns {Iterator} ES6 iterator
209
 */
210
treeIterator(root: Object, options?: { reverse?: boolean }): Iterator<Object>;
211
```
212

213
[Tree Iterators](./tree-iterators.md)
214

215
### Tree Analysis
216

217
Index calculation, counting, and position comparison operations.
218

219
```javascript { .api }
220
/**
221
 * Get index position among siblings
222
 * @param {Object} child - Child object
223
 * @returns {number} Index position or -1 if no parent
224
 */
225
index(child: Object): number;
226

227
/**
228
 * Compare positions of two objects
229
 * @param {Object} left - Left object
230
 * @param {Object} right - Right object
231
 * @returns {number} Position bitmask
232
 */
233
compareTreePosition(left: Object, right: Object): number;
234
```
235

236
[Tree Analysis](./tree-analysis.md)
237

238
## Constants
239

240
### TreePosition Constants
241

242
Position relationship constants for `compareTreePosition` results.
243

244
```javascript { .api }
245
// Access via SymbolTree.TreePosition
246
const TreePosition = {
247
  DISCONNECTED: 1,    // Objects are in different trees
248
  PRECEDING: 2,       // Left object precedes right object
249
  FOLLOWING: 4,       // Left object follows right object
250
  CONTAINS: 8,        // Left object contains right object
251
  CONTAINED_BY: 16    // Left object is contained by right object
252
};
253
```
254

255
## Error Handling
256

257
- **Insertion Methods**: Throw `Error` if the object being inserted is already present in the tree
258
- **Index Method**: Returns `-1` if the object has no parent
259
- **Navigation Methods**: Return `null` for non-existent relationships
260
- **Position Comparison**: Returns `TreePosition.DISCONNECTED` for objects in different trees