attention-manifest-protocol 0.4.0 → 0.4.2

package/lib/structure/queue.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Array-backed first-in, first-out queue.
+ *
+ * Values live in a circular buffer addressed by a head index and a count. Both
+ * ends of the logical sequence are therefore updated by index arithmetic:
+ * `enqueue` writes just past the current tail and `dequeue` advances the head
+ * without ever calling `Array.prototype.shift`. The buffer is not required to
+ * have a power-of-two length; it doubles when full and halves after a
+ * dequeue leaves it sparsely occupied. All operations are O(1) amortized.
+ */
+/**
+ * A first-in, first-out queue.
+ *
+ * `dequeue` and `peek` return `undefined` when the queue is empty rather than
+ * throwing. Since `undefined` is also a valid stored value, use {@link size} or
+ * {@link isEmpty} when presence must be distinguished from absence.
+ *
+ * Iteration is front-to-back.
+ *
+ * @example
+ * ```ts
+ * const queue = new Queue(["a", "b"]);
+ * queue.enqueue("c");
+ * queue.dequeue(); // "a"
+ * [...queue]; // ["b", "c"]
+ * ```
+ */
+export declare class Queue<T> implements Iterable<T> {
+    private items;
+    private head;
+    private count;
+    /**
+     * Create a queue, optionally seeded from `values`.
+     *
+     * Values are enqueued in iteration order, so the first value becomes the
+     * front.
+     *
+     * @param values - Values to enqueue, in order.
+     */
+    constructor(values?: Iterable<T>);
+    /**
+     * Number of values currently in the queue.
+     */
+    get size(): number;
+    /**
+     * Whether the queue contains no values.
+     */
+    get isEmpty(): boolean;
+    /**
+     * Add a value at the back of the queue.
+     *
+     * @param value - Value to enqueue.
+     * @returns This queue, for chaining.
+     */
+    enqueue(value: T): this;
+    /**
+     * Remove and return the value at the front of the queue.
+     *
+     * @returns The former front value, or `undefined` if the queue is empty.
+     */
+    dequeue(): T | undefined;
+    /**
+     * Return the value at the front of the queue without removing it.
+     *
+     * @returns The front value, or `undefined` if the queue is empty.
+     */
+    peek(): T | undefined;
+    /**
+     * Remove every value and reset the ring to its initial capacity.
+     */
+    clear(): void;
+    /**
+     * Snapshot the queue from front to back.
+     *
+     * @returns A new array whose first item is the front of the queue.
+     */
+    toArray(): T[];
+    /**
+     * Iterate front to back over a snapshot taken when the iterator is created.
+     */
+    [Symbol.iterator](): Generator<T, void, unknown>;
+    /**
+     * Copy the live values into a fresh ring, front to back.
+     */
+    private resize;
+    /**
+     * Halve an oversized ring after dequeueing leaves it at most quarter full.
+     */
+    private shrinkIfSparse;
+}

package/lib/structure/queue.js

@@ -0,0 +1,154 @@
+/**
+ * Array-backed first-in, first-out queue.
+ *
+ * Values live in a circular buffer addressed by a head index and a count. Both
+ * ends of the logical sequence are therefore updated by index arithmetic:
+ * `enqueue` writes just past the current tail and `dequeue` advances the head
+ * without ever calling `Array.prototype.shift`. The buffer is not required to
+ * have a power-of-two length; it doubles when full and halves after a
+ * dequeue leaves it sparsely occupied. All operations are O(1) amortized.
+ */
+import { generatorFrom } from "./iterator.js";
+const InitialCapacity = 8;
+/**
+ * A first-in, first-out queue.
+ *
+ * `dequeue` and `peek` return `undefined` when the queue is empty rather than
+ * throwing. Since `undefined` is also a valid stored value, use {@link size} or
+ * {@link isEmpty} when presence must be distinguished from absence.
+ *
+ * Iteration is front-to-back.
+ *
+ * @example
+ * ```ts
+ * const queue = new Queue(["a", "b"]);
+ * queue.enqueue("c");
+ * queue.dequeue(); // "a"
+ * [...queue]; // ["b", "c"]
+ * ```
+ */
+export class Queue {
+    items = new Array(InitialCapacity);
+    head = 0;
+    count = 0;
+    /**
+     * Create a queue, optionally seeded from `values`.
+     *
+     * Values are enqueued in iteration order, so the first value becomes the
+     * front.
+     *
+     * @param values - Values to enqueue, in order.
+     */
+    constructor(values) {
+        if (values === (void 0)) {
+            return;
+        }
+        const initialValues = [...values];
+        for (let index = 0; index < initialValues.length; index += 1) {
+            this.enqueue(initialValues[index]);
+        }
+    }
+    /**
+     * Number of values currently in the queue.
+     */
+    get size() {
+        return this.count;
+    }
+    /**
+     * Whether the queue contains no values.
+     */
+    get isEmpty() {
+        return this.count === 0;
+    }
+    /**
+     * Add a value at the back of the queue.
+     *
+     * @param value - Value to enqueue.
+     * @returns This queue, for chaining.
+     */
+    enqueue(value) {
+        if (this.count === this.items.length) {
+            this.resize(this.items.length * 2);
+        }
+        const tail = (this.head + this.count) % this.items.length;
+        this.items[tail] = value;
+        this.count += 1;
+        return this;
+    }
+    /**
+     * Remove and return the value at the front of the queue.
+     *
+     * @returns The former front value, or `undefined` if the queue is empty.
+     */
+    dequeue() {
+        if (this.count === 0) {
+            return undefined;
+        }
+        const value = this.items[this.head];
+        this.items[this.head] = undefined;
+        this.head = (this.head + 1) % this.items.length;
+        this.count -= 1;
+        this.shrinkIfSparse();
+        return value;
+    }
+    /**
+     * Return the value at the front of the queue without removing it.
+     *
+     * @returns The front value, or `undefined` if the queue is empty.
+     */
+    peek() {
+        if (this.count === 0) {
+            return undefined;
+        }
+        return this.items[this.head];
+    }
+    /**
+     * Remove every value and reset the ring to its initial capacity.
+     */
+    clear() {
+        this.items = new Array(InitialCapacity);
+        this.head = 0;
+        this.count = 0;
+    }
+    /**
+     * Snapshot the queue from front to back.
+     *
+     * @returns A new array whose first item is the front of the queue.
+     */
+    toArray() {
+        const values = new Array(this.count);
+        for (let index = 0; index < this.count; index += 1) {
+            values[index] = this.items[(this.head + index) % this.items.length];
+        }
+        return values;
+    }
+    /**
+     * Iterate front to back over a snapshot taken when the iterator is created.
+     */
+    [Symbol.iterator]() {
+        return generatorFrom(this.toArray());
+    }
+    /**
+     * Copy the live values into a fresh ring, front to back.
+     */
+    resize(capacity) {
+        const next = new Array(capacity);
+        for (let index = 0; index < this.count; index += 1) {
+            next[index] = this.items[(this.head + index) % this.items.length];
+        }
+        this.items = next;
+        this.head = 0;
+    }
+    /**
+     * Halve an oversized ring after dequeueing leaves it at most quarter full.
+     */
+    shrinkIfSparse() {
+        if (this.items.length <= InitialCapacity) {
+            return;
+        }
+        if (this.count > this.items.length / 4) {
+            return;
+        }
+        this.resize(this.items.length / 2);
+    }
+}

package/lib/structure/redBlackTree.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Red-black binary search tree.
+ *
+ * The tree uses explicit null leaves (no sentinel) and stores a parent pointer
+ * on every node. Insertion and full CLRS-style deletion fix-up maintain the
+ * red-black invariants: the root is black, red nodes have black children, and
+ * every root-to-null path contains the same number of black nodes. These
+ * invariants bound the height by `2 * log2(n + 1)`, so `insert`, `has`,
+ * `delete`, `min`, `max`, `floor` and `ceil` are O(log n) worst case.
+ */
+import type { TreeOptions } from "./binarySearchTree.js";
+export type { TreeOptions };
+/**
+ * A self-balancing red-black binary search tree.
+ *
+ * Duplicate values (comparator result 0) are rejected. In-order iteration is
+ * sorted according to the configured comparator.
+ */
+export declare class RedBlackTree<T> implements Iterable<T> {
+    private rootNode;
+    private count;
+    private readonly compare;
+    /**
+     * Create an empty red-black tree.
+     *
+     * @param options - Comparator override; defaults to natural ordering.
+     */
+    constructor(options?: TreeOptions<T>);
+    /**
+     * Number of stored values.
+     */
+    get size(): number;
+    /**
+     * Height of the tree in nodes: 0 when empty, 1 for a leaf.
+     *
+     * Computed on demand in O(n) time; the red-black invariants bound it to
+     * O(log n).
+     */
+    get height(): number;
+    /**
+     * Whether the tree contains no values.
+     */
+    get isEmpty(): boolean;
+    /**
+     * Insert a value unless an equivalent one is already stored.
+     *
+     * The new node starts red and is repaired by the standard CLRS insertion
+     * fix-up, including all LL/RR/LR/RL rotation shapes.
+     *
+     * @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 zero-, one- and two-child removals and runs the full CLRS deletion
+     * fix-up, so all red-black invariants are restored before returning. A
+     * two-child node is replaced by its in-order successor.
+     *
+     * @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 and reset the root to `null`.
+     */
+    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 that the root is black, that no red node has a red child, that
+     * every root-to-null path has the same black height, that in-order values are
+     * strictly increasing, that parent links are consistent, and that the
+     * maintained size matches the reachable node count. An empty array means the
+     * tree is valid.
+     */
+    validate(): string[];
+    /**
+     * Restore the red-black invariants after inserting a red leaf.
+     */
+    private insertFixup;
+    /**
+     * Remove a known node, preserving the tree shape until fix-up runs.
+     */
+    private deleteNode;
+    /**
+     * Replace the subtree rooted at `target` with the subtree `replacement`.
+     */
+    private transplant;
+    /**
+     * Restore the red-black invariants after deleting a black node.
+     */
+    private deleteFixup;
+    /**
+     * Left rotation around `node`; updates the root when needed.
+     */
+    private rotateLeft;
+    /**
+     * Right rotation around `node`; updates the root when needed.
+     */
+    private rotateRight;
+    private static isRed;
+    private static minimumNode;
+    private inorderValues;
+}