attention-manifest-protocol 0.4.0 → 0.4.2

package/lib/structure/avlTree.js

@@ -0,0 +1,369 @@
+/**
+ * Height-balanced AVL search tree.
+ *
+ * Every node stores its subtree height, and each insertion or deletion walks
+ * back up the affected path applying LL/RR/LR/RL rotations until every balance
+ * factor is in `[-1, 1]`. The tree therefore keeps its height O(log n) even for
+ * sorted insertion sequences, and `insert`, `has`, `delete`, `min`, `max`,
+ * `floor` and `ceil` are O(log n) worst case.
+ */
+import { compareNatural } from "./compare.js";
+/**
+ * A self-balancing AVL binary search tree.
+ *
+ * Duplicate values (comparator result 0) are rejected. The stored
+ * representative is never replaced by an equivalent insert; deleting with an
+ * equivalent value removes the stored representative.
+ */
+export class AVLTree {
+    rootNode = null;
+    count = 0;
+    compare;
+    /**
+     * Create an empty AVL 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;
+    }
+    /**
+     * Height of the tree in nodes: 0 when empty, 1 for a leaf.
+     */
+    get height() {
+        return this.rootNode === null ? 0 : this.rootNode.height;
+    }
+    /**
+     * Whether the tree contains no values.
+     */
+    get isEmpty() {
+        return this.count === 0;
+    }
+    /**
+     * Insert a value unless an equivalent one is already stored.
+     *
+     * @param value - Value to insert.
+     * @returns `true` if a node was added, `false` for an equivalent duplicate.
+     */
+    insert(value) {
+        const previous = this.count;
+        this.rootNode = this.insertNode(this.rootNode, value);
+        return this.count > previous;
+    }
+    /**
+     * 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` and rebalance the path to the root.
+     *
+     * A two-child node is replaced by its in-order successor. Rotation is applied
+     * on every ancestor whose balance factor leaves `[-1, 1]`.
+     *
+     * @param value - Value to remove.
+     * @returns `true` if a value was removed, `false` when none is equivalent.
+     */
+    delete(value) {
+        const previous = this.count;
+        this.rootNode = this.deleteNode(this.rootNode, value);
+        return this.count < previous;
+    }
+    /**
+     * Minimum stored value according to the comparator, or `undefined` when
+     * empty.
+     */
+    min() {
+        if (this.rootNode === null) {
+            return undefined;
+        }
+        return AVLTree.minimumNode(this.rootNode).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 and reset the height to 0.
+     */
+    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, the maintained size, every node's stored
+     * height against the actual subtree height, and the AVL balance condition
+     * `|balanceFactor| <= 1`. An empty array means the tree is valid.
+     */
+    validate() {
+        const errors = [];
+        if (this.rootNode === null) {
+            if (this.count !== 0) {
+                errors.push(`size mismatch: expected ${this.count}, found an empty tree`);
+            }
+            return 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}`);
+            }
+        }
+        const actualHeights = new Map();
+        const stack = [{ node: this.rootNode, visited: false }];
+        let seen = 0;
+        while (stack.length > 0) {
+            const frame = stack.pop();
+            if (frame === (void 0)) {
+                break;
+            }
+            if (!frame.visited) {
+                stack.push({ node: frame.node, visited: true });
+                if (frame.node.right !== null) {
+                    stack.push({ node: frame.node.right, visited: false });
+                }
+                if (frame.node.left !== null) {
+                    stack.push({ node: frame.node.left, visited: false });
+                }
+                continue;
+            }
+            seen += 1;
+            const node = frame.node;
+            const leftHeight = node.left === null ? 0 : actualHeights.get(node.left);
+            const rightHeight = node.right === null ? 0 : actualHeights.get(node.right);
+            if (leftHeight === (void 0) || rightHeight === (void 0)) {
+                errors.push("height metadata is missing for a child subtree");
+                actualHeights.set(node, 1);
+                continue;
+            }
+            const actualHeight = 1 + Math.max(leftHeight, rightHeight);
+            actualHeights.set(node, actualHeight);
+            if (node.height !== actualHeight) {
+                errors.push(`height mismatch: stored ${node.height}, actual ${actualHeight}`);
+            }
+            const balance = leftHeight - rightHeight;
+            if (Math.abs(balance) > 1) {
+                errors.push(`balance violation: balance factor ${balance}`);
+            }
+        }
+        if (seen !== this.count) {
+            errors.push(`size mismatch: expected ${this.count}, reached ${seen} nodes`);
+        }
+        return errors;
+    }
+    insertNode(node, value) {
+        if (node === null) {
+            this.count += 1;
+            return { value, left: null, right: null, height: 1 };
+        }
+        const order = this.compare(value, node.value);
+        if (order === 0) {
+            return node;
+        }
+        if (order < 0) {
+            node.left = this.insertNode(node.left, value);
+        }
+        else {
+            node.right = this.insertNode(node.right, value);
+        }
+        return this.rebalance(node);
+    }
+    deleteNode(node, value) {
+        if (node === null) {
+            return null;
+        }
+        const order = this.compare(value, node.value);
+        if (order < 0) {
+            node.left = this.deleteNode(node.left, value);
+        }
+        else if (order > 0) {
+            node.right = this.deleteNode(node.right, value);
+        }
+        else {
+            if (node.left === null) {
+                this.count -= 1;
+                return node.right;
+            }
+            if (node.right === null) {
+                this.count -= 1;
+                return node.left;
+            }
+            const successor = AVLTree.minimumNode(node.right);
+            node.value = successor.value;
+            node.right = this.deleteNode(node.right, successor.value);
+        }
+        return this.rebalance(node);
+    }
+    /**
+     * Recompute this node's height and repair its subtree with rotations.
+     */
+    rebalance(node) {
+        this.updateHeight(node);
+        const balance = this.balanceFactor(node);
+        if (balance > 1) {
+            const left = node.left;
+            if (left !== null && this.balanceFactor(left) < 0) {
+                node.left = this.rotateLeft(left);
+            }
+            return this.rotateRight(node);
+        }
+        if (balance < -1) {
+            const right = node.right;
+            if (right !== null && this.balanceFactor(right) > 0) {
+                node.right = this.rotateRight(right);
+            }
+            return this.rotateLeft(node);
+        }
+        return node;
+    }
+    /**
+     * Right rotation; returns the new subtree root.
+     */
+    rotateRight(node) {
+        const pivot = node.left;
+        if (pivot === null) {
+            return node;
+        }
+        node.left = pivot.right;
+        pivot.right = node;
+        this.updateHeight(node);
+        this.updateHeight(pivot);
+        return pivot;
+    }
+    /**
+     * Left rotation; returns the new subtree root.
+     */
+    rotateLeft(node) {
+        const pivot = node.right;
+        if (pivot === null) {
+            return node;
+        }
+        node.right = pivot.left;
+        pivot.left = node;
+        this.updateHeight(node);
+        this.updateHeight(pivot);
+        return pivot;
+    }
+    updateHeight(node) {
+        node.height = 1 + Math.max(AVLTree.heightOf(node.left), AVLTree.heightOf(node.right));
+    }
+    balanceFactor(node) {
+        return AVLTree.heightOf(node.left) - AVLTree.heightOf(node.right);
+    }
+    static heightOf(node) {
+        return node === null ? 0 : node.height;
+    }
+    static minimumNode(node) {
+        let current = node;
+        while (current.left !== null) {
+            current = current.left;
+        }
+        return current;
+    }
+    *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/binarySearchTree.d.ts

@@ -0,0 +1,125 @@
+/**
+ * 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 type { Comparator } from "./compare.js";
+/**
+ * Options shared by the ordered search trees.
+ */
+export interface TreeOptions<T> {
+    /**
+     * Total-preorder comparator. Defaults to {@link compareNatural}, which
+     * supports numbers, bigints, strings, booleans and Dates and throws for other
+     * values.
+     */
+    compare?: Comparator<T>;
+}
+/**
+ * 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 declare class BinarySearchTree<T> implements Iterable<T> {
+    private rootNode;
+    private count;
+    private readonly compare;
+    /**
+     * Create an empty search tree.
+     *
+     * @param options - Comparator override; defaults to natural ordering.
+     */
+    constructor(options?: TreeOptions<T>);
+    /**
+     * Number of stored values.
+     */
+    get size(): number;
+    /**
+     * 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(): number;
+    /**
+     * Whether the tree contains no values.
+     */
+    get isEmpty(): boolean;
+    /**
+     * 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: T): boolean;
+    /**
+     * Test whether an equivalent value is stored.
+     *
+     * @param value - Value to look up.
+     */
+    has(value: T): boolean;
+    /**
+     * 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: T): boolean;
+    /**
+     * Minimum stored value according to the comparator, or `undefined` when
+     * empty.
+     */
+    min(): T | undefined;
+    /**
+     * Maximum stored value according to the comparator, or `undefined` when
+     * empty.
+     */
+    max(): T | undefined;
+    /**
+     * Greatest stored value that is less than or equal to `value` in comparator
+     * order, or `undefined` when there is none.
+     */
+    floor(value: T): T | undefined;
+    /**
+     * Least stored value that is greater than or equal to `value` in comparator
+     * order, or `undefined` when there is none.
+     */
+    ceil(value: T): T | undefined;
+    /**
+     * Remove every value.
+     */
+    clear(): void;
+    /**
+     * Collect values in ascending comparator order.
+     */
+    toArray(): T[];
+    /**
+     * Iterate values in ascending comparator order.
+     *
+     * Mutating the tree while iterating is not supported.
+     */
+    [Symbol.iterator](): Generator<T>;
+    /**
+     * 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(): string[];
+    private inorderValues;
+}