attention-manifest-protocol 0.4.0 → 0.4.2

package/lib/structure/binarySearchTree.js

@@ -0,0 +1,306 @@
+/**
+ * Unbalanced binary search tree.
+ *
+ * Values are ordered by a supplied {@link Comparator}, defaulting to
+ * {@link compareNatural}. Duplicate values (comparator result 0) are rejected.
+ * The tree is deliberately not balanced: a sorted insertion sequence degenerates
+ * it into a linked list, so `insert`, `has`, and `delete` are O(n) in the worst
+ * case and O(log n) only when the insertion order happens to keep the tree
+ * shallow. Use {@link AVLTree} or {@link RedBlackTree} when worst-case bounds
+ * matter.
+ */
+import { compareNatural } from "./compare.js";
+/**
+ * An unbalanced binary search tree.
+ *
+ * In-order iteration is sorted according to the configured comparator. The
+ * tree keeps exactly one representative for each comparator equivalence class,
+ * so inserting an equivalent value returns `false` and leaves the stored
+ * representative unchanged.
+ */
+export class BinarySearchTree {
+    rootNode = null;
+    count = 0;
+    compare;
+    /**
+     * Create an empty search tree.
+     *
+     * @param options - Comparator override; defaults to natural ordering.
+     */
+    constructor(options) {
+        this.compare = options?.compare ?? ((left, right) => compareNatural(left, right));
+    }
+    /**
+     * Number of stored values.
+     */
+    get size() {
+        return this.count;
+    }
+    /**
+     * Number of nodes on the longest root-to-leaf path.
+     *
+     * Empty trees have height 0 and leaves have height 1. Computed in O(n) time.
+     */
+    get height() {
+        if (this.rootNode === null) {
+            return 0;
+        }
+        let maximum = 0;
+        const stack = [{ node: this.rootNode, depth: 1 }];
+        while (stack.length > 0) {
+            const frame = stack.pop();
+            if (frame === (void 0)) {
+                break;
+            }
+            if (frame.depth > maximum) {
+                maximum = frame.depth;
+            }
+            if (frame.node.left !== null) {
+                stack.push({ node: frame.node.left, depth: frame.depth + 1 });
+            }
+            if (frame.node.right !== null) {
+                stack.push({ node: frame.node.right, depth: frame.depth + 1 });
+            }
+        }
+        return maximum;
+    }
+    /**
+     * Whether the tree contains no values.
+     */
+    get isEmpty() {
+        return this.count === 0;
+    }
+    /**
+     * Insert a value unless an equivalent one is already stored.
+     *
+     * O(h) where `h` is the current height; O(n) worst case. The first value
+     * inserted into an empty tree does not invoke the comparator.
+     *
+     * @param value - Value to insert.
+     * @returns `true` if a node was added, `false` for an equivalent duplicate.
+     */
+    insert(value) {
+        if (this.rootNode === null) {
+            this.rootNode = { value, left: null, right: null };
+            this.count = 1;
+            return true;
+        }
+        let node = this.rootNode;
+        while (true) {
+            const order = this.compare(value, node.value);
+            if (order === 0) {
+                return false;
+            }
+            if (order < 0) {
+                if (node.left === null) {
+                    node.left = { value, left: null, right: null };
+                    this.count += 1;
+                    return true;
+                }
+                node = node.left;
+            }
+            else {
+                if (node.right === null) {
+                    node.right = { value, left: null, right: null };
+                    this.count += 1;
+                    return true;
+                }
+                node = node.right;
+            }
+        }
+    }
+    /**
+     * Test whether an equivalent value is stored.
+     *
+     * @param value - Value to look up.
+     */
+    has(value) {
+        let node = this.rootNode;
+        while (node !== null) {
+            const order = this.compare(value, node.value);
+            if (order === 0) {
+                return true;
+            }
+            node = order < 0 ? node.left : node.right;
+        }
+        return false;
+    }
+    /**
+     * Delete the value equivalent to `value`.
+     *
+     * Handles the zero-, one- and two-child cases; a two-child node is replaced by
+     * its in-order successor. O(h), O(n) worst case.
+     *
+     * @param value - Value to remove.
+     * @returns `true` if a value was removed, `false` when none is equivalent.
+     */
+    delete(value) {
+        let node = this.rootNode;
+        let parent = null;
+        while (node !== null) {
+            const order = this.compare(value, node.value);
+            if (order === 0) {
+                break;
+            }
+            parent = node;
+            node = order < 0 ? node.left : node.right;
+        }
+        if (node === null) {
+            return false;
+        }
+        let target = node;
+        let targetParent = parent;
+        if (target.left !== null && target.right !== null) {
+            let successorParent = target;
+            let successor = target.right;
+            while (successor.left !== null) {
+                successorParent = successor;
+                successor = successor.left;
+            }
+            target.value = successor.value;
+            target = successor;
+            targetParent = successorParent;
+        }
+        const child = target.left !== null ? target.left : target.right;
+        if (targetParent === null) {
+            this.rootNode = child;
+        }
+        else if (targetParent.left === target) {
+            targetParent.left = child;
+        }
+        else {
+            targetParent.right = child;
+        }
+        this.count -= 1;
+        return true;
+    }
+    /**
+     * Minimum stored value according to the comparator, or `undefined` when
+     * empty.
+     */
+    min() {
+        let node = this.rootNode;
+        if (node === null) {
+            return undefined;
+        }
+        while (node.left !== null) {
+            node = node.left;
+        }
+        return node.value;
+    }
+    /**
+     * Maximum stored value according to the comparator, or `undefined` when
+     * empty.
+     */
+    max() {
+        let node = this.rootNode;
+        if (node === null) {
+            return undefined;
+        }
+        while (node.right !== null) {
+            node = node.right;
+        }
+        return node.value;
+    }
+    /**
+     * Greatest stored value that is less than or equal to `value` in comparator
+     * order, or `undefined` when there is none.
+     */
+    floor(value) {
+        let node = this.rootNode;
+        let result;
+        while (node !== null) {
+            const order = this.compare(node.value, value);
+            if (order === 0) {
+                return node.value;
+            }
+            if (order < 0) {
+                result = node.value;
+                node = node.right;
+            }
+            else {
+                node = node.left;
+            }
+        }
+        return result;
+    }
+    /**
+     * Least stored value that is greater than or equal to `value` in comparator
+     * order, or `undefined` when there is none.
+     */
+    ceil(value) {
+        let node = this.rootNode;
+        let result;
+        while (node !== null) {
+            const order = this.compare(node.value, value);
+            if (order === 0) {
+                return node.value;
+            }
+            if (order < 0) {
+                node = node.right;
+            }
+            else {
+                result = node.value;
+                node = node.left;
+            }
+        }
+        return result;
+    }
+    /**
+     * Remove every value.
+     */
+    clear() {
+        this.rootNode = null;
+        this.count = 0;
+    }
+    /**
+     * Collect values in ascending comparator order.
+     */
+    toArray() {
+        return Array.from(this.inorderValues());
+    }
+    /**
+     * Iterate values in ascending comparator order.
+     *
+     * Mutating the tree while iterating is not supported.
+     */
+    [Symbol.iterator]() {
+        return this.inorderValues();
+    }
+    /**
+     * Check the tree's invariants.
+     *
+     * Verifies strict in-order ordering and that the maintained `size` matches the
+     * number of reachable nodes. Returns an empty array for a valid tree; each
+     * string describes one violation.
+     */
+    validate() {
+        const errors = [];
+        const values = this.toArray();
+        if (values.length !== this.count) {
+            errors.push(`size mismatch: expected ${this.count}, traversed ${values.length}`);
+        }
+        for (let index = 1; index < values.length; index += 1) {
+            if (this.compare(values[index - 1], values[index]) >= 0) {
+                errors.push(`ordering violation between in-order positions ${index - 1} and ${index}`);
+            }
+        }
+        return errors;
+    }
+    *inorderValues() {
+        const stack = [];
+        let node = this.rootNode;
+        while (node !== null || stack.length > 0) {
+            while (node !== null) {
+                stack.push(node);
+                node = node.left;
+            }
+            const current = stack.pop();
+            if (current === (void 0)) {
+                break;
+            }
+            yield current.value;
+            node = current.right;
+        }
+    }
+}

package/lib/structure/binaryTree.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Unordered binary tree.
+ *
+ * The tree is shape-oriented rather than search-oriented: values have no
+ * ordering, `insert` fills the first missing child in level order, and the
+ * four traversal orders are available for inspection. Node objects are
+ * deliberately exposed through {@link BinaryTree.root}; a tree assembled by
+ * hand should be passed to the constructor so its `size` is computed from the
+ * existing nodes.
+ *
+ * `size` is maintained by {@link BinaryTree.insert} and
+ * {@link BinaryTree.clear}. Mutating the exposed nodes directly is not tracked
+ * by `size`; construct a new tree after manual restructuring.
+ */
+/**
+ * A binary-tree node. Missing children are represented by `null`.
+ */
+export declare class BinaryTreeNode<T> {
+    /**
+     * Stored value.
+     */
+    value: T;
+    /**
+     * Left child, or `null` when absent.
+     */
+    left: BinaryTreeNode<T> | null;
+    /**
+     * Right child, or `null` when absent.
+     */
+    right: BinaryTreeNode<T> | null;
+    /**
+     * Create a node.
+     *
+     * @param value - Stored value.
+     * @param left - Left child; defaults to `null`.
+     * @param right - Right child; defaults to `null`.
+     */
+    constructor(value: T, left?: BinaryTreeNode<T> | null, right?: BinaryTreeNode<T> | null);
+}
+/**
+ * Traversal orders supported by {@link BinaryTree.traverse}.
+ */
+export type BinaryTreeOrder = "preorder" | "inorder" | "postorder" | "levelorder";
+/**
+ * A binary tree with level-order construction, insertion and traversal.
+ *
+ * An empty tree has `size` 0 and `height` 0; a single node has height 1. A tree
+ * built from an existing root computes its size once in the constructor. All
+ * traversals are iterative, so unusually deep manual trees do not consume the
+ * call stack.
+ */
+export declare class BinaryTree<T> implements Iterable<T> {
+    private rootNode;
+    private count;
+    /**
+     * Create a tree from an existing node graph.
+     *
+     * `size` is computed by walking the supplied graph. Passing `null` creates an
+     * empty tree.
+     *
+     * @param root - Root node, or `null` for an empty tree.
+     */
+    constructor(root?: BinaryTreeNode<T> | null);
+    /**
+     * Build a tree from a level-order array.
+     *
+     * Index 0 is the root; the children of index `i` are at `2i + 1` and
+     * `2i + 2`. `null` entries are holes. Trailing `null` entries are ignored, and
+     * entries below a hole are unreachable and therefore omitted.
+     *
+     * @param values - Level-order values, with `null` marking a missing node.
+     */
+    static fromLevelOrder<T>(values: ReadonlyArray<T | null>): BinaryTree<T>;
+    /**
+     * Build a complete tree from values in level order.
+     *
+     * Every position is filled, so the result is always complete. An empty
+     * iterable produces an empty tree.
+     *
+     * @param values - Values to place in level order.
+     */
+    static fromArray<T>(values: Iterable<T>): BinaryTree<T>;
+    /**
+     * Root node, or `null` for an empty tree.
+     */
+    get root(): BinaryTreeNode<T> | null;
+    /**
+     * Number of reachable nodes.
+     *
+     * Maintained by {@link insert} and {@link clear}. A tree built with the
+     * constructor starts from a traversal count; direct edits to exposed nodes are
+     * not reflected here.
+     */
+    get size(): number;
+    /**
+     * Number of nodes on the longest root-to-leaf path.
+     *
+     * Empty trees have height 0 and leaves have height 1. Computed on demand in
+     * O(n) time.
+     */
+    get height(): number;
+    /**
+     * Whether the tree contains no nodes.
+     */
+    get isEmpty(): boolean;
+    /**
+     * Insert a value at the first missing child in level order.
+     *
+     * The tree therefore keeps its complete shape when it started complete; for a
+     * manually built tree the search is still breadth-first, so the shallowest
+     * available slot is filled first. `size` is incremented.
+     *
+     * @param value - Value to store.
+     * @returns The newly created node.
+     */
+    insert(value: T): BinaryTreeNode<T>;
+    /**
+     * Remove every node and reset `size` to 0.
+     */
+    clear(): void;
+    /**
+     * Iterate values in the requested order.
+     *
+     * `null` holes are skipped. The tree is traversed iteratively, so the caller
+     * does not consume call-stack depth. Mutating the tree while iterating is not
+     * supported.
+     *
+     * @param order - Traversal order; defaults to `levelorder`.
+     */
+    traverse(order?: BinaryTreeOrder): Generator<T>;
+    /**
+     * Collect values in the requested traversal order.
+     *
+     * @param order - Traversal order; defaults to `levelorder`.
+     */
+    toArray(order?: BinaryTreeOrder): T[];
+    /**
+     * Mirror the tree by swapping every left and right child.
+     *
+     * The shape is unchanged, so `size` and `height` stay the same. Returns the
+     * tree itself for chaining.
+     */
+    invert(): this;
+    /**
+     * Whether all levels except possibly the last are full and the last level is
+     * filled from the left. An empty tree is complete.
+     */
+    isComplete(): boolean;
+    /**
+     * Whether every node has either zero or two children. An empty tree is full.
+     */
+    isFull(): boolean;
+    /**
+     * Deep-copy the tree.
+     *
+     * Every node is recreated, so the copy shares no nodes with the original.
+     * The copy's size is computed from the cloned shape.
+     */
+    clone(): BinaryTree<T>;
+    /**
+     * Iterate values in preorder (node, left, right).
+     *
+     * Equivalent to `traverse('preorder')`.
+     */
+    [Symbol.iterator](): Generator<T>;
+    /**
+     * Count reachable nodes without recursion.
+     */
+    private static countNodes;
+    private preorderValues;
+    private inorderValues;
+    private postorderValues;
+    private levelOrderValues;
+}