attention-manifest-protocol 0.4.0 → 0.4.2

package/lib/structure/segmentTree.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Iterative segment tree over an associative monoid.
+ *
+ * The class owns a power-of-two padded tree: every real leaf holds one value,
+ * padding leaves hold the identity, and every internal node combines its two
+ * children. Point updates rebuild the root path in O(log n); half-open range
+ * queries combine O(log n) canonical nodes while preserving left-to-right
+ * order, so non-commutative operations such as string concatenation work.
+ *
+ * Lazy range updates are deliberately not supported. Empty ranges return the
+ * identity, and `size: 0` is valid: the tree has no leaves but still answers
+ * empty queries and `queryAll()` with that identity.
+ */
+/**
+ * Construction options for {@link SegmentTree}.
+ */
+export interface SegmentTreeOptions<T> {
+    /**
+     * Number of leaves. Must be a non-negative safe integer.
+     */
+    size: number;
+    /**
+     * Associative operation applied left-to-right.
+     */
+    operation: (left: T, right: T) => T;
+    /**
+     * Neutral element for {@link SegmentTreeOptions.operation}.
+     */
+    identity: T;
+    /**
+     * Optional initial leaf values, in index order. If present, the iterable
+     * must contain exactly {@link SegmentTreeOptions.size} values.
+     */
+    values?: Iterable<T>;
+}
+/**
+ * A segment tree for an associative monoid.
+ *
+ * Values are stored by reference; the tree never clones them. The operation
+ * must be associative, and `identity` must be neutral for it. Commutativity is
+ * not required: range queries combine canonical nodes in index order.
+ *
+ * @typeParam T - Leaf value type.
+ */
+export declare class SegmentTree<T> {
+    private readonly operation;
+    private readonly identity;
+    private readonly count;
+    private readonly base;
+    private readonly tree;
+    /**
+     * Build a tree with `options.size` leaves.
+     *
+     * When `values` is omitted, every leaf starts as `identity`. When it is
+     * supplied, it is consumed once and must produce exactly `size` values.
+     *
+     * @param options - Size, operation, identity, and optional initial values.
+     * @throws RangeError if `size` is not a non-negative safe integer, or if
+     * `values` does not contain exactly `size` values.
+     * @throws TypeError if `operation` is not a function or `identity` is not
+     * supplied.
+     */
+    constructor(options: SegmentTreeOptions<T>);
+    /**
+     * Number of real leaves.
+     */
+    get size(): number;
+    /**
+     * Read the leaf at `index`.
+     *
+     * @throws RangeError if `index` is not a safe integer in `[0, size)`.
+     */
+    get(index: number): T;
+    /**
+     * Replace the leaf at `index`.
+     *
+     * @throws RangeError if `index` is not a safe integer in `[0, size)`.
+     */
+    set(index: number, value: T): void;
+    /**
+     * Transform the leaf at `index` from its current value.
+     *
+     * `update` is called once with the previous leaf value. If it throws, the
+     * tree is left unchanged.
+     *
+     * @throws RangeError if `index` is not a safe integer in `[0, size)`.
+     */
+    update(index: number, update: (previous: T) => T): void;
+    /**
+     * Query the half-open range `[left, right)`.
+     *
+     * Canonical nodes are combined in index order, so the result is correct for
+     * non-commutative operations. An empty range returns `identity`.
+     *
+     * @throws RangeError unless `left` and `right` are safe integers satisfying
+     * `0 <= left <= right <= size`.
+     */
+    query(left: number, right: number): T;
+    /**
+     * Query the whole stored range.
+     *
+     * This is O(1): the tree root already combines the leaves in order. It
+     * returns `identity` when the tree is empty.
+     */
+    queryAll(): T;
+    /**
+     * Return a fresh array of leaf values in index order.
+     */
+    toArray(): T[];
+    /**
+     * Reset every leaf to `identity`.
+     *
+     * All tree nodes are overwritten directly, so this is O(n) total rather than
+     * performing a separate rebuild path for each leaf.
+     */
+    clear(): void;
+    /**
+     * Recombine the root path after a leaf write.
+     */
+    private rebuild;
+    /**
+     * Validate a single-leaf index.
+     */
+    private assertIndex;
+    /**
+     * Validate a half-open query range.
+     */
+    private assertRange;
+}

package/lib/structure/segmentTree.js

@@ -0,0 +1,205 @@
+/**
+ * Iterative segment tree over an associative monoid.
+ *
+ * The class owns a power-of-two padded tree: every real leaf holds one value,
+ * padding leaves hold the identity, and every internal node combines its two
+ * children. Point updates rebuild the root path in O(log n); half-open range
+ * queries combine O(log n) canonical nodes while preserving left-to-right
+ * order, so non-commutative operations such as string concatenation work.
+ *
+ * Lazy range updates are deliberately not supported. Empty ranges return the
+ * identity, and `size: 0` is valid: the tree has no leaves but still answers
+ * empty queries and `queryAll()` with that identity.
+ */
+/**
+ * A segment tree for an associative monoid.
+ *
+ * Values are stored by reference; the tree never clones them. The operation
+ * must be associative, and `identity` must be neutral for it. Commutativity is
+ * not required: range queries combine canonical nodes in index order.
+ *
+ * @typeParam T - Leaf value type.
+ */
+export class SegmentTree {
+    operation;
+    identity;
+    count;
+    base;
+    tree;
+    /**
+     * Build a tree with `options.size` leaves.
+     *
+     * When `values` is omitted, every leaf starts as `identity`. When it is
+     * supplied, it is consumed once and must produce exactly `size` values.
+     *
+     * @param options - Size, operation, identity, and optional initial values.
+     * @throws RangeError if `size` is not a non-negative safe integer, or if
+     * `values` does not contain exactly `size` values.
+     * @throws TypeError if `operation` is not a function or `identity` is not
+     * supplied.
+     */
+    constructor(options) {
+        const input = options;
+        if (input === null || typeof (input) !== "object") {
+            throw new TypeError("options must be an object");
+        }
+        if (!Number.isSafeInteger(input.size) || input.size < 0) {
+            throw new RangeError(`size must be a non-negative safe integer, received ${`${input.size}`}`);
+        }
+        if (typeof (input.operation) !== "function") {
+            throw new TypeError("operation must be a function");
+        }
+        if (!("identity" in input)) {
+            throw new TypeError("identity is required");
+        }
+        this.operation = input.operation;
+        this.identity = input.identity;
+        this.count = input.size;
+        let base = 1;
+        while (base < this.count) {
+            base *= 2;
+        }
+        this.base = base;
+        const tree = new Array(base * 2).fill(this.identity);
+        if (input.values !== (void 0)) {
+            let index = 0;
+            for (const value of input.values) {
+                if (index === this.count) {
+                    throw new RangeError(`values must contain exactly ${this.count} values`);
+                }
+                tree[base + index] = value;
+                index += 1;
+            }
+            if (index !== this.count) {
+                throw new RangeError(`values must contain exactly ${this.count} values, received ${index}`);
+            }
+        }
+        for (let node = base - 1; node >= 1; node -= 1) {
+            tree[node] = this.operation(tree[node * 2], tree[node * 2 + 1]);
+        }
+        this.tree = tree;
+    }
+    /**
+     * Number of real leaves.
+     */
+    get size() {
+        return this.count;
+    }
+    /**
+     * Read the leaf at `index`.
+     *
+     * @throws RangeError if `index` is not a safe integer in `[0, size)`.
+     */
+    get(index) {
+        this.assertIndex(index);
+        return this.tree[this.base + index];
+    }
+    /**
+     * Replace the leaf at `index`.
+     *
+     * @throws RangeError if `index` is not a safe integer in `[0, size)`.
+     */
+    set(index, value) {
+        this.assertIndex(index);
+        const leaf = this.base + index;
+        this.tree[leaf] = value;
+        this.rebuild(leaf);
+    }
+    /**
+     * Transform the leaf at `index` from its current value.
+     *
+     * `update` is called once with the previous leaf value. If it throws, the
+     * tree is left unchanged.
+     *
+     * @throws RangeError if `index` is not a safe integer in `[0, size)`.
+     */
+    update(index, update) {
+        this.assertIndex(index);
+        const leaf = this.base + index;
+        const next = update(this.tree[leaf]);
+        this.tree[leaf] = next;
+        this.rebuild(leaf);
+    }
+    /**
+     * Query the half-open range `[left, right)`.
+     *
+     * Canonical nodes are combined in index order, so the result is correct for
+     * non-commutative operations. An empty range returns `identity`.
+     *
+     * @throws RangeError unless `left` and `right` are safe integers satisfying
+     * `0 <= left <= right <= size`.
+     */
+    query(left, right) {
+        this.assertRange(left, right);
+        if (left === right) {
+            return this.identity;
+        }
+        let leftNode = this.base + left;
+        let rightNode = this.base + right;
+        let leftResult = this.identity;
+        let rightResult = this.identity;
+        while (leftNode < rightNode) {
+            if (leftNode % 2 === 1) {
+                leftResult = this.operation(leftResult, this.tree[leftNode]);
+                leftNode += 1;
+            }
+            if (rightNode % 2 === 1) {
+                rightNode -= 1;
+                rightResult = this.operation(this.tree[rightNode], rightResult);
+            }
+            leftNode = Math.floor(leftNode / 2);
+            rightNode = Math.floor(rightNode / 2);
+        }
+        return this.operation(leftResult, rightResult);
+    }
+    /**
+     * Query the whole stored range.
+     *
+     * This is O(1): the tree root already combines the leaves in order. It
+     * returns `identity` when the tree is empty.
+     */
+    queryAll() {
+        return this.count === 0 ? this.identity : this.tree[1];
+    }
+    /**
+     * Return a fresh array of leaf values in index order.
+     */
+    toArray() {
+        return this.tree.slice(this.base, this.base + this.count);
+    }
+    /**
+     * Reset every leaf to `identity`.
+     *
+     * All tree nodes are overwritten directly, so this is O(n) total rather than
+     * performing a separate rebuild path for each leaf.
+     */
+    clear() {
+        this.tree.fill(this.identity);
+    }
+    /**
+     * Recombine the root path after a leaf write.
+     */
+    rebuild(leaf) {
+        let node = Math.floor(leaf / 2);
+        while (node >= 1) {
+            this.tree[node] = this.operation(this.tree[node * 2], this.tree[node * 2 + 1]);
+            node = Math.floor(node / 2);
+        }
+    }
+    /**
+     * Validate a single-leaf index.
+     */
+    assertIndex(index) {
+        if (!Number.isSafeInteger(index) || index < 0 || index >= this.count) {
+            throw new RangeError(`index must be a safe integer in [0, ${this.count}), received ${`${index}`}`);
+        }
+    }
+    /**
+     * Validate a half-open query range.
+     */
+    assertRange(left, right) {
+        if (!Number.isSafeInteger(left) || !Number.isSafeInteger(right) || left < 0 || right > this.count || left > right) {
+            throw new RangeError(`query range must satisfy 0 <= left <= right <= ${this.count}, received [${`${left}`}, ${`${right}`})`);
+        }
+    }
+}

package/lib/structure/stack.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Array-backed last-in, first-out stack.
+ *
+ * The implementation keeps its values in a native array, so `push` and `pop`
+ * are O(1) amortized. Iteration visits the top first and works from a snapshot
+ * taken when the iterator is created, so the traversal is not disturbed by
+ * later pushes or pops.
+ */
+/**
+ * A last-in, first-out stack.
+ *
+ * `pop` and `peek` return `undefined` when the stack 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 top-to-bottom.
+ *
+ * @example
+ * ```ts
+ * const stack = new Stack([1, 2, 3]);
+ * stack.peek(); // 3
+ * stack.pop(); // 3
+ * [...stack]; // [2, 1]
+ * ```
+ */
+export declare class Stack<T> implements Iterable<T> {
+    private readonly items;
+    /**
+     * Create a stack, optionally seeded from `values`.
+     *
+     * Values are pushed in iteration order, so the last value becomes the top.
+     *
+     * @param values - Values to push, in order.
+     */
+    constructor(values?: Iterable<T>);
+    /**
+     * Number of values currently on the stack.
+     */
+    get size(): number;
+    /**
+     * Whether the stack contains no values.
+     */
+    get isEmpty(): boolean;
+    /**
+     * Push a value onto the top.
+     *
+     * @param value - Value to push.
+     * @returns This stack, for chaining.
+     */
+    push(value: T): this;
+    /**
+     * Remove and return the top value.
+     *
+     * @returns The former top value, or `undefined` if the stack is empty.
+     */
+    pop(): T | undefined;
+    /**
+     * Return the top value without removing it.
+     *
+     * @returns The top value, or `undefined` if the stack is empty.
+     */
+    peek(): T | undefined;
+    /**
+     * Remove every value.
+     */
+    clear(): void;
+    /**
+     * Snapshot the stack from top to bottom.
+     *
+     * @returns A new array whose first item is the top of the stack.
+     */
+    toArray(): T[];
+    /**
+     * Iterate top to bottom over a snapshot taken when the iterator is created.
+     */
+    [Symbol.iterator](): Generator<T, void, unknown>;
+}

package/lib/structure/stack.js

@@ -0,0 +1,107 @@
+/**
+ * Array-backed last-in, first-out stack.
+ *
+ * The implementation keeps its values in a native array, so `push` and `pop`
+ * are O(1) amortized. Iteration visits the top first and works from a snapshot
+ * taken when the iterator is created, so the traversal is not disturbed by
+ * later pushes or pops.
+ */
+import { generatorFrom } from "./iterator.js";
+/**
+ * A last-in, first-out stack.
+ *
+ * `pop` and `peek` return `undefined` when the stack 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 top-to-bottom.
+ *
+ * @example
+ * ```ts
+ * const stack = new Stack([1, 2, 3]);
+ * stack.peek(); // 3
+ * stack.pop(); // 3
+ * [...stack]; // [2, 1]
+ * ```
+ */
+export class Stack {
+    items = [];
+    /**
+     * Create a stack, optionally seeded from `values`.
+     *
+     * Values are pushed in iteration order, so the last value becomes the top.
+     *
+     * @param values - Values to push, in order.
+     */
+    constructor(values) {
+        if (values === (void 0)) {
+            return;
+        }
+        const initialValues = [...values];
+        for (let index = 0; index < initialValues.length; index += 1) {
+            const value = initialValues[index];
+            this.items.push(value);
+        }
+    }
+    /**
+     * Number of values currently on the stack.
+     */
+    get size() {
+        return this.items.length;
+    }
+    /**
+     * Whether the stack contains no values.
+     */
+    get isEmpty() {
+        return this.items.length === 0;
+    }
+    /**
+     * Push a value onto the top.
+     *
+     * @param value - Value to push.
+     * @returns This stack, for chaining.
+     */
+    push(value) {
+        this.items.push(value);
+        return this;
+    }
+    /**
+     * Remove and return the top value.
+     *
+     * @returns The former top value, or `undefined` if the stack is empty.
+     */
+    pop() {
+        return this.items.pop();
+    }
+    /**
+     * Return the top value without removing it.
+     *
+     * @returns The top value, or `undefined` if the stack is empty.
+     */
+    peek() {
+        if (this.items.length === 0) {
+            return undefined;
+        }
+        return this.items[this.items.length - 1];
+    }
+    /**
+     * Remove every value.
+     */
+    clear() {
+        this.items.length = 0;
+    }
+    /**
+     * Snapshot the stack from top to bottom.
+     *
+     * @returns A new array whose first item is the top of the stack.
+     */
+    toArray() {
+        return this.items.slice().reverse();
+    }
+    /**
+     * Iterate top to bottom over a snapshot taken when the iterator is created.
+     */
+    [Symbol.iterator]() {
+        return generatorFrom(this.toArray());
+    }
+}

package/lib/structure/unordered.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Unordered hash set and map.
+ *
+ * Both containers are separate-chaining hash tables over a power-of-two bucket
+ * array, with a load factor of 0.75 and rehash-on-grow. The bucket index is
+ * taken from the low bits of a 64-bit hash from `./hash.ts`; collisions are
+ * walked as explicit chains and resolved with the equality strategy (never by
+ * hash equality alone). No insertion order is maintained: iteration order is
+ * unspecified bucket order and may change after a resize.
+ *
+ * Iteration is deliberately fail-fast: any structural mutation after an
+ * iterator is created (`add` of a new value, `set` of a new key, `delete`, or
+ * `clear`) makes the iterator throw on its next `next()` call, as does a
+ * rehash. Updating the value of an existing map key is not structural and does
+ * not invalidate iterators.
+ */
+import type { KeyStrategy } from "./hash.js";
+/**
+ * An unordered set backed by a separate-chaining hash table.
+ *
+ * Average O(1) membership, explicit collision chains, power-of-two buckets, a
+ * 0.75 load factor, and rehash-on-grow. Iteration order is unspecified (bucket
+ * order) and may change after a resize. The public API mirrors
+ * `OrderedSet`, including custom {@link KeyStrategy} support.
+ *
+ * Iteration is fail-fast: a structural mutation (`add` of a new value,
+ * `delete`, `clear`, or an internal rehash caused by growth) after an iterator
+ * is obtained makes that iterator throw on its next step. Mutating the set
+ * during `forEach` therefore also throws once the callback returns and the
+ * loop advances.
+ */
+export declare class UnorderedSet<T> implements Iterable<T> {
+    private readonly table;
+    constructor(values?: Iterable<T>, options?: KeyStrategy<T>);
+    get size(): number;
+    clear(): void;
+    add(value: T): this;
+    has(value: T): boolean;
+    delete(value: T): boolean;
+    /**
+     * Alias of {@link UnorderedSet.values}.
+     */
+    keys(): Generator<T>;
+    values(): Generator<T>;
+    entries(): Generator<[T, T]>;
+    [Symbol.iterator](): Generator<T>;
+    /**
+     * Call `callback` for each value; order is unspecified.
+     *
+     * The table generator is driven by hand so that the fail-fast version check
+     * keeps throwing between callback invocations, exactly as a `for…of` loop
+     * over `keys()` would.
+     *
+     * @param callback - Receives the value twice (matching the native `Set`
+     * shape) and the set itself.
+     * @param thisArg - Value used as `this` when invoking `callback`.
+     */
+    forEach(callback: (value: T, value2: T, set: this) => void, thisArg?: unknown): void;
+}
+/**
+ * An unordered map backed by a separate-chaining hash table.
+ *
+ * Average O(1) lookup, explicit collision chains, power-of-two buckets, a 0.75
+ * load factor, and rehash-on-grow. Iteration order is unspecified (bucket
+ * order) and may change after a resize. The public API mirrors `OrderedMap`,
+ * including custom {@link KeyStrategy} support. Membership is determined by
+ * {@link UnorderedMap.has}, so `undefined` is a perfectly valid value.
+ *
+ * Iteration is fail-fast: a structural mutation (`set` of a new key, `delete`,
+ * `clear`, or an internal rehash caused by growth) after an iterator is
+ * obtained makes that iterator throw on its next step; updating an existing
+ * key's value is allowed. Mutating the key set during `forEach` also throws
+ * once the callback returns and the loop advances.
+ */
+export declare class UnorderedMap<K, V> implements Iterable<[K, V]> {
+    private readonly table;
+    constructor(entries?: Iterable<readonly [K, V]>, options?: KeyStrategy<K>);
+    get size(): number;
+    clear(): void;
+    set(key: K, value: V): this;
+    get(key: K): V | undefined;
+    has(key: K): boolean;
+    delete(key: K): boolean;
+    keys(): Generator<K>;
+    values(): Generator<V>;
+    entries(): Generator<[K, V]>;
+    [Symbol.iterator](): Generator<[K, V]>;
+    /**
+     * Call `callback` for each entry; order is unspecified.
+     *
+     * The table generator is driven by hand so that the fail-fast version check
+     * keeps throwing between callback invocations, exactly as a `for…of` loop
+     * over `entries()` would.
+     *
+     * @param callback - Receives the value, the key, and the map itself.
+     * @param thisArg - Value used as `this` when invoking `callback`.
+     */
+    forEach(callback: (value: V, key: K, map: this) => void, thisArg?: unknown): void;
+}