treenode.ts 0.6.0 → 0.8.0

package/dist/index.d.mts

@@ -0,0 +1,170 @@
+/**
+ * @public
+ */
+interface IParseable<T> {
+    model: T;
+    children: IParseable<T>[];
+}
+
+/**
+ * Search callback passed to `.pre`, `.post`, and `.breadth`.
+ * @public
+ */
+type SearchCallback<T> = (node: TreeNode<T>) => boolean | void;
+/**
+ * Search methods on TreeNode, passed to `.flatten`.
+ * @public
+ */
+type SearchStrategy = "pre" | "post" | "breadth";
+/**
+ * Nested array representation of a tree.
+ * @public
+ */
+type NestedArray<T> = T | [T, ...(NestedArray<T> | T[])[]];
+/**
+ * @public
+ */
+declare class TreeNode<T> {
+    model: T;
+    parent: TreeNode<T> | null;
+    private _index;
+    private _children;
+    constructor(model: T, parent?: TreeNode<T> | null, children?: TreeNode<T>[]);
+    /**
+     * Returns the children of the node as a readonly array.
+     * Use add(), drop(), or swap() to modify children.
+     */
+    get children(): readonly TreeNode<T>[];
+    /**
+     * Parses object into a tree and returns the root node.
+     */
+    static parse<T>(tree: IParseable<T>): TreeNode<T>;
+    /**
+     * Index of the node among its siblings.
+     */
+    get index(): number;
+    /**
+     * Indices from the root to the node.
+     */
+    get indices(): number[];
+    /**
+     * Compressed path key: positive = run of first-children, negative = child index.
+     * e.g. [0,0,0,1,0,0] -> "3,-1,2"
+     */
+    get pathKey(): string;
+    /**
+     * Returns true if the node has children.
+     */
+    get hasChildren(): boolean;
+    /**
+     * Returns true if the node is the root (has no parent).
+     */
+    get isRoot(): boolean;
+    /**
+     * Returns true if the node is a leaf (has no children).
+     */
+    get isLeaf(): boolean;
+    /**
+     * Returns the root node of the tree.
+     */
+    get root(): TreeNode<T>;
+    /**
+     * Returns the depth of the node (root is 0).
+     */
+    get depth(): number;
+    /**
+     * Returns siblings of this node (excluding self).
+     */
+    get siblings(): TreeNode<T>[];
+    /**
+     * Add node as a child.
+     * @param child - The node to add
+     * @param index - Optional index to insert at. If omitted, appends to end.
+     * @throws RangeError if index is out of bounds (negative or > children.length)
+     */
+    add(child: TreeNode<T>, index?: number): TreeNode<T>;
+    /**
+     * Swap children at indices i and j.
+     * @param i - First index
+     * @param j - Second index
+     */
+    swap(i: number, j: number): void;
+    /**
+     * Add model as a child.
+     * @param model - The model to add
+     * @param index - Optional index to insert at. If omitted, appends to end.
+     */
+    addModel(model: T, index?: number): TreeNode<T>;
+    /**
+     * Remove current node and its children from the tree and return.
+     */
+    drop(): TreeNode<T>;
+    /**
+     * Returns a deep copy of structure, shallow copy of model.
+     */
+    clone(): TreeNode<T>;
+    /**
+     * Returns a node given a list of indices
+     */
+    fetch(indices: number[]): TreeNode<T> | null;
+    /**
+     * Returns a node given a pathKey string.
+     * @see pathKey
+     */
+    fetchByPathKey(pathKey: string): TreeNode<T> | null;
+    /**
+     * Returns list of nodes to the root.
+     */
+    path(): TreeNode<T>[];
+    /**
+     * Iterates over a node's children and returns a new root node.
+     */
+    map<U>(callback: (node: TreeNode<T>) => U): TreeNode<U>;
+    /**
+     * Iterates over a node's children and returns a new root node.
+     */
+    mapAsync<U>(callback: (node: TreeNode<T>, parent: TreeNode<U> | undefined) => Promise<U>, parent?: TreeNode<U>): Promise<TreeNode<U>>;
+    /**
+     * Breadth-first search, return true in the callback to end iteration.
+     */
+    breadth(callback: SearchCallback<T>): TreeNode<T> | null;
+    /**
+     * Depth-first pre-order search, return true in the callback to end iteration.
+     */
+    pre(callback: SearchCallback<T>): TreeNode<T> | null;
+    /**
+     * Depth-first post-order search, return true in the callback to end iteration.
+     */
+    post(callback: SearchCallback<T>): TreeNode<T> | null;
+    /**
+     * Find the first node matching the predicate.
+     */
+    find(predicate: (node: TreeNode<T>) => boolean, method?: SearchStrategy): TreeNode<T> | null;
+    /**
+     * Find all nodes matching the predicate.
+     */
+    findAll(predicate: (node: TreeNode<T>) => boolean, method?: SearchStrategy): TreeNode<T>[];
+    /**
+     * Returns a list of nodes.
+     */
+    flatten(method: SearchStrategy): TreeNode<T>[];
+    /**
+     * Returns a nested array representation of the tree.
+     * - Leaf -> value
+     * - Single child -> [model, ...childResult]
+     * - Multiple leaf children -> [model, [leaves...]]
+     * - Multiple mixed children -> [model, child1Result, child2Result, ...]
+     */
+    toNestedArray(): NestedArray<T>;
+    /**
+     * Creates a tree from a nested array representation.
+     * @see toNestedArray
+     */
+    static fromNestedArray<T>(input: NestedArray<T>): TreeNode<T>;
+    /**
+     * Returns an object representation of the tree.
+     */
+    toObject(): IParseable<T>;
+}
+
+export { type IParseable, type NestedArray, type SearchCallback, type SearchStrategy, TreeNode };

package/dist/index.d.ts

@@ -1,3 +1,170 @@
-export { TreeNode, SearchCallback, SearchStrategy } from './TreeNode';
-export { IParseable } from './IParseable';
-//# sourceMappingURL=index.d.ts.map
+/**
+ * @public
+ */
+interface IParseable<T> {
+    model: T;
+    children: IParseable<T>[];
+}
+
+/**
+ * Search callback passed to `.pre`, `.post`, and `.breadth`.
+ * @public
+ */
+type SearchCallback<T> = (node: TreeNode<T>) => boolean | void;
+/**
+ * Search methods on TreeNode, passed to `.flatten`.
+ * @public
+ */
+type SearchStrategy = "pre" | "post" | "breadth";
+/**
+ * Nested array representation of a tree.
+ * @public
+ */
+type NestedArray<T> = T | [T, ...(NestedArray<T> | T[])[]];
+/**
+ * @public
+ */
+declare class TreeNode<T> {
+    model: T;
+    parent: TreeNode<T> | null;
+    private _index;
+    private _children;
+    constructor(model: T, parent?: TreeNode<T> | null, children?: TreeNode<T>[]);
+    /**
+     * Returns the children of the node as a readonly array.
+     * Use add(), drop(), or swap() to modify children.
+     */
+    get children(): readonly TreeNode<T>[];
+    /**
+     * Parses object into a tree and returns the root node.
+     */
+    static parse<T>(tree: IParseable<T>): TreeNode<T>;
+    /**
+     * Index of the node among its siblings.
+     */
+    get index(): number;
+    /**
+     * Indices from the root to the node.
+     */
+    get indices(): number[];
+    /**
+     * Compressed path key: positive = run of first-children, negative = child index.
+     * e.g. [0,0,0,1,0,0] -> "3,-1,2"
+     */
+    get pathKey(): string;
+    /**
+     * Returns true if the node has children.
+     */
+    get hasChildren(): boolean;
+    /**
+     * Returns true if the node is the root (has no parent).
+     */
+    get isRoot(): boolean;
+    /**
+     * Returns true if the node is a leaf (has no children).
+     */
+    get isLeaf(): boolean;
+    /**
+     * Returns the root node of the tree.
+     */
+    get root(): TreeNode<T>;
+    /**
+     * Returns the depth of the node (root is 0).
+     */
+    get depth(): number;
+    /**
+     * Returns siblings of this node (excluding self).
+     */
+    get siblings(): TreeNode<T>[];
+    /**
+     * Add node as a child.
+     * @param child - The node to add
+     * @param index - Optional index to insert at. If omitted, appends to end.
+     * @throws RangeError if index is out of bounds (negative or > children.length)
+     */
+    add(child: TreeNode<T>, index?: number): TreeNode<T>;
+    /**
+     * Swap children at indices i and j.
+     * @param i - First index
+     * @param j - Second index
+     */
+    swap(i: number, j: number): void;
+    /**
+     * Add model as a child.
+     * @param model - The model to add
+     * @param index - Optional index to insert at. If omitted, appends to end.
+     */
+    addModel(model: T, index?: number): TreeNode<T>;
+    /**
+     * Remove current node and its children from the tree and return.
+     */
+    drop(): TreeNode<T>;
+    /**
+     * Returns a deep copy of structure, shallow copy of model.
+     */
+    clone(): TreeNode<T>;
+    /**
+     * Returns a node given a list of indices
+     */
+    fetch(indices: number[]): TreeNode<T> | null;
+    /**
+     * Returns a node given a pathKey string.
+     * @see pathKey
+     */
+    fetchByPathKey(pathKey: string): TreeNode<T> | null;
+    /**
+     * Returns list of nodes to the root.
+     */
+    path(): TreeNode<T>[];
+    /**
+     * Iterates over a node's children and returns a new root node.
+     */
+    map<U>(callback: (node: TreeNode<T>) => U): TreeNode<U>;
+    /**
+     * Iterates over a node's children and returns a new root node.
+     */
+    mapAsync<U>(callback: (node: TreeNode<T>, parent: TreeNode<U> | undefined) => Promise<U>, parent?: TreeNode<U>): Promise<TreeNode<U>>;
+    /**
+     * Breadth-first search, return true in the callback to end iteration.
+     */
+    breadth(callback: SearchCallback<T>): TreeNode<T> | null;
+    /**
+     * Depth-first pre-order search, return true in the callback to end iteration.
+     */
+    pre(callback: SearchCallback<T>): TreeNode<T> | null;
+    /**
+     * Depth-first post-order search, return true in the callback to end iteration.
+     */
+    post(callback: SearchCallback<T>): TreeNode<T> | null;
+    /**
+     * Find the first node matching the predicate.
+     */
+    find(predicate: (node: TreeNode<T>) => boolean, method?: SearchStrategy): TreeNode<T> | null;
+    /**
+     * Find all nodes matching the predicate.
+     */
+    findAll(predicate: (node: TreeNode<T>) => boolean, method?: SearchStrategy): TreeNode<T>[];
+    /**
+     * Returns a list of nodes.
+     */
+    flatten(method: SearchStrategy): TreeNode<T>[];
+    /**
+     * Returns a nested array representation of the tree.
+     * - Leaf -> value
+     * - Single child -> [model, ...childResult]
+     * - Multiple leaf children -> [model, [leaves...]]
+     * - Multiple mixed children -> [model, child1Result, child2Result, ...]
+     */
+    toNestedArray(): NestedArray<T>;
+    /**
+     * Creates a tree from a nested array representation.
+     * @see toNestedArray
+     */
+    static fromNestedArray<T>(input: NestedArray<T>): TreeNode<T>;
+    /**
+     * Returns an object representation of the tree.
+     */
+    toObject(): IParseable<T>;
+}
+
+export { type IParseable, type NestedArray, type SearchCallback, type SearchStrategy, TreeNode };