recursive-set 7.0.1 → 8.1.0

package/dist/cjs/index.js

@@ -1,554 +1,782 @@
 "use strict";
 /**
  * @module recursive-set
- * @version 7.0.0
+ * @version 8.1.0
  * @description
- * **High-Performance ZFC Set Implementation.**
- * This library sacrifices runtime safety checks for raw speed.
- * * **Strict Contract:**
- * 1. **Finite Numbers Only:** No `NaN`, no `Infinity`.
- * 2. **No Mutation:** Do not mutate arrays/tuples/objects after insertion.
- * 3. **Type Consistency:** Avoid mixing distinct types (Array vs Tuple) that might hash collide.
+ * High-Performance collection library supporting **Value Semantics** (Deep Equality)
+ * and recursive structures.
+ * * **CONTRACTS & INVARIANTS:**
+ * 1. **Finite Numbers Only:** `NaN` and `Infinity` are **strictly forbidden**. They break strict equality checks and integer optimization paths.
+ * 2. **Strict Value Semantics:** Plain JavaScript objects (`{}`) are **not supported**. Objects must implement the `Structural` interface.
+ * 3. **Hash Quality:** The $O(1)$ performance guarantee relies on a good distribution. Returning a constant `hashCode` (e.g. `42`) forces all elements into a single bucket, degrading performance to $O(N)$.
+ * 4. **Deterministic Visualization:** Custom `toString()` implementations **must** utilize `compareVisualLogic` for nested structures. Failing to do so results in cut/unstable string output.
+ * 5. **Immutability:** Once an object is added to a collection, its `hashCode` **must not change**.
+ * 6. **No Circular Dependencies:** A `RecursiveSet` cannot contain itself, directly or indirectly (e.g. A ∈ B ∈ A). Runtime checks are omitted for performance. Creating a cycle will cause a **Stack Overflow** during hashing or visualization.
+ * * **Architecture:**
+ * - **Storage:** Open Addressing with Linear Probing.
+ * - **Hashing:** Zero-allocation FNV-1a / Murmur-inspired hybrid.
+ * - **Memory:** Flattened arrays for cache locality (SoA - Structure of Arrays).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RecursiveSet = exports.Tuple = void 0;
-exports.compare = compare;
+exports.hashValue = exports.Tuple = exports.RecursiveMap = exports.RecursiveSet = void 0;
 exports.emptySet = emptySet;
 exports.singleton = singleton;
+exports.getHashCode = getHashCode;
 // ============================================================================
-// FAST HASHING (Optimized FNV-1a)
+// 2. VISUAL HELPERS
 // ============================================================================
-const FNV_PRIME = 16777619;
-const FNV_OFFSET = 2166136261;
-const floatBuffer = new ArrayBuffer(8);
-const view = new DataView(floatBuffer);
 /**
- * Hashes a number using FNV-1a.
- * Optimizes for 32-bit integers to avoid Float64 processing overhead.
+ * Visual Comparator used strictly for deterministic .toString() output.
+ * * @remarks
+ * This does NOT define the logical order for the Set/Map (which are unordered).
+ * It ensures that `{a, b}` and `{b, a}` produce the same string output.
  */
-function hashNumber(val) {
-    // Integer optimization: Skip float logic if it's a 32-bit int
-    if ((val | 0) === val)
-        return val | 0;
-    view.setFloat64(0, val, true); // Little Endian
-    let h = FNV_OFFSET;
-    h ^= view.getInt32(0, true);
-    h = Math.imul(h, FNV_PRIME);
-    h ^= view.getInt32(4, true);
-    h = Math.imul(h, FNV_PRIME);
-    return h >>> 0;
-}
-function hashString(str) {
-    let h = FNV_OFFSET;
-    const len = str.length;
-    for (let i = 0; i < len; i++) {
-        h ^= str.charCodeAt(i);
-        h = Math.imul(h, FNV_PRIME);
-    }
-    return h >>> 0;
+function compareVisualLogic(a, b) {
+    if (a === b)
+        return 0;
+    // 1. Numbers: Mathematical sort
+    if (typeof a === 'number' && typeof b === 'number')
+        return a - b;
+    // 2. Strings: Lexicographic sort
+    if (typeof a === 'string' && typeof b === 'string')
+        return a < b ? -1 : 1;
+    // 3. Type separation (Numbers < Strings < Objects)
+    const typeA = getTypeId(a);
+    const typeB = getTypeId(b);
+    if (typeA !== typeB)
+        return typeA - typeB;
+    // 4. Recursive Fallback: Compare string representations
+    return String(a) < String(b) ? -1 : 1;
 }
-function hashValue(v) {
+function getTypeId(v) {
     if (typeof v === 'number')
-        return hashNumber(v);
+        return 1;
     if (typeof v === 'string')
-        return hashString(v);
-    if (v instanceof RecursiveSet || v instanceof Tuple)
-        return v.hashCode;
-    if (Array.isArray(v)) {
-        let h = FNV_OFFSET;
-        for (let i = 0; i < v.length; i++) {
-            h ^= hashValue(v[i]);
-            h = Math.imul(h, FNV_PRIME);
+        return 2;
+    return 3; // Objects / Structures
+}
+// ============================================================================
+// 3. HASH ENGINE (Optimized)
+// ============================================================================
+// Static allocation to prevent GC pauses during number hashing.
+// We treat numbers as raw bits to avoid FPU overhead.
+const _buffer = new ArrayBuffer(8);
+const _f64 = new Float64Array(_buffer);
+const _i32 = new Int32Array(_buffer);
+// Mixing constants (derived from MurmurHash3)
+const HASH_C1 = 0xcc9e2d51;
+const HASH_C2 = 0x1b873593;
+/**
+ * Computes a high-quality 32-bit hash code for any supported Value.
+ * Optimized for V8's internal number representation (Smis vs Doubles).
+ */
+function getHashCode(val) {
+    // --- CASE A: NUMBER ---
+    if (typeof val === 'number') {
+        // Fast Path: 32-Bit Integers (Smis)
+        // (val | 0) === val checks if it's a safe integer.
+        // This handles -0 correctly (converts to 0).
+        if ((val | 0) === val) {
+            let h = val | 0;
+            // Avalanche Mixer: Spreads bits to prevent collisions on sequential numbers
+            h = Math.imul(h ^ (h >>> 16), 0x85ebca6b);
+            h = Math.imul(h ^ (h >>> 13), 0xc2b2ae35);
+            return (h ^ (h >>> 16)) >>> 0;
+        }
+        // Slow Path: Floats (Doubles)
+        // Interpret the double's IEEE 754 bit pattern as two 32-bit integers.
+        _f64[0] = val;
+        const low = _i32[0];
+        const high = _i32[1];
+        return (Math.imul(low, HASH_C1) ^ Math.imul(high, HASH_C2)) >>> 0;
+    }
+    // --- CASE B: STRING ---
+    // Jenkins One-at-a-Time variant
+    if (typeof val === 'string') {
+        let h = 0x811c9dc5;
+        const len = val.length;
+        for (let i = 0; i < len; i++) {
+            h ^= val.charCodeAt(i);
+            h = Math.imul(h, 0x01000193);
         }
         return h >>> 0;
     }
+    // --- CASE C: STRUCTURAL ---
+    if (val && typeof val === 'object') {
+        return val.hashCode;
+    }
     return 0;
 }
-// ============================================================================
-// COMPARATOR (Optimized)
-// ============================================================================
 /**
- * Global comparator for Total Ordering.
- * * **WARNING: UNSAFE OPTIMIZATIONS**
- * - Uses `a - b` for numbers. **Precondition:** Only finite numbers allowed.
- * Inputting `NaN` or `Infinity` results in undefined sorting behavior.
- * - **Hash Collisions:** If two distinct object types (e.g. Array vs Tuple) have the
- * same hash, they may be treated as equal. Avoid mixing structure types in the same set.
+ * Deep equality check dispatcher.
  */
-function compare(a, b) {
+function areEqual(a, b) {
     if (a === b)
-        return 0;
-    // Fast path for primitives
-    if (typeof a === 'number' && typeof b === 'number')
-        return a - b;
-    if (typeof a === 'string' && typeof b === 'string')
-        return a < b ? -1 : 1;
-    const typeA = typeof a;
-    const typeB = typeof b;
-    // Type Score: Number(1) < String(2) < Array/Tuple(3) < Set(4)
-    if (typeA !== typeB) {
-        const scoreA = (typeA === 'number') ? 1 : (typeA === 'string' ? 2 : 3);
-        const scoreB = (typeB === 'number') ? 1 : (typeB === 'string' ? 2 : 3);
-        return scoreA - scoreB;
-    }
-    // Hash Short-Circuit
-    const h1 = hashValue(a);
-    const h2 = hashValue(b);
-    if (h1 !== h2)
-        return h1 < h2 ? -1 : 1;
-    // Deep Compare
-    if (a instanceof RecursiveSet && b instanceof RecursiveSet)
-        return a.compare(b);
-    if (a instanceof Tuple && b instanceof Tuple)
-        return compareSequences(a.raw, b.raw);
-    if (Array.isArray(a) && Array.isArray(b))
-        return compareSequences(a, b);
-    return 0;
-}
-function compareSequences(a, b) {
-    const len = a.length;
-    if (len !== b.length)
-        return len - b.length;
-    for (let i = 0; i < len; i++) {
-        const diff = compare(a[i], b[i]);
-        if (diff !== 0)
-            return diff;
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a === 'number' || typeof a === 'string')
+        return a === b;
+    if (typeof a === 'object' && a !== null && b !== null) {
+        return a.equals(b);
     }
-    return 0;
+    return false;
 }
 // ============================================================================
-// CLASSES
+// 4. TUPLE
 // ============================================================================
 /**
- * Immutable Tuple container.
- * * **Contract:**
- * - Creates a defensive copy of the input array.
- * - Freezes the internal storage (`Object.freeze`).
- * - **Note:** Freezing is **shallow**. Do not mutate nested elements.
- * @template T - Array type of the tuple elements.
+ * An immutable, hashable sequence of values.
+ * Useful as composite keys in Maps.
  */
 class Tuple {
-    #values;
-    hashCode;
-    constructor(...values) {
-        this.#values = values.slice(); // Defensive copy
-        Object.freeze(this.#values); // Freeze for safety
-        this.hashCode = hashValue(this.#values);
-    }
-    /** * Returns the readonly internal array.
-     * **Warning:** Readonly is only enforced by TypeScript.
-     * Mutating the underlying array via `as any` breaks invariants.
-     */
-    get raw() { return this.#values; }
-    get length() { return this.#values.length; }
-    /** Alias for compatibility. */
-    get values() { return this.#values; }
-    /** Iterates over tuple elements. */
-    *[Symbol.iterator]() { yield* this.#values; }
-    /** Returns string representation "(a, b)". */
-    toString() { return `(${this.#values.join(', ')})`; }
-    /** Custom inspection for Node.js console.log to print "(a, b)" cleanly. */
+    #elements;
+    #hashCode;
+    constructor(...elements) {
+        this.#elements = [...elements]; // Defensive copy
+        Object.freeze(this.#elements);
+        // Compute hash immediately (tuples are immutable)
+        let h = 1;
+        for (const e of this.#elements) {
+            h = Math.imul(h, 31) + getHashCode(e);
+        }
+        this.#hashCode = h;
+    }
+    get length() { return this.#elements.length; }
+    get hashCode() { return this.#hashCode; }
+    /** Typesafe access to elements */
+    get(index) {
+        return this.#elements[index];
+    }
+    equals(other) {
+        if (this === other)
+            return true;
+        if (!(other instanceof Tuple))
+            return false;
+        if (this.hashCode !== other.hashCode)
+            return false;
+        if (this.length !== other.length)
+            return false;
+        for (let i = 0; i < this.length; i++) {
+            if (!areEqual(this.#elements[i], other.#elements[i]))
+                return false;
+        }
+        return true;
+    }
+    [Symbol.iterator]() {
+        return this.#elements[Symbol.iterator]();
+    }
+    toString() {
+        return `(${this.#elements.map(e => String(e)).join(', ')})`;
+    }
     [Symbol.for('nodejs.util.inspect.custom')]() { return this.toString(); }
 }
 exports.Tuple = Tuple;
+// ============================================================================
+// 5. RECURSIVE MAP
+// ============================================================================
 /**
- * High-Performance Recursive Set.
- * * **Lifecycle & Safety:**
- * - **Freeze-on-Hash:** The set is effectively immutable once `hashCode` is accessed
- * (or it is added to another set/map).
- * - **Runtime Checks:** Mutation methods verify frozen state via a fast boolean check.
- * * @template T - Type of elements.
+ * A Hash Map implementation supporting complex keys (Value Semantics).
+ * * @template K Key Type
+ * @template V Value Type
  */
-class RecursiveSet {
-    #elements;
-    #hashCode = null;
-    #isFrozen = false;
-    // Static wrapper for compatibility
-    static compare(a, b) { return compare(a, b); }
+class RecursiveMap {
+    // Structure of Arrays (SoA) for cache locality
+    _keys = [];
+    _values = [];
+    _hashes = [];
+    // Open Addressing Index Table
+    // Maps (Hash & Mask) -> Index in _keys/_values + 1 (0 means empty)
+    _indices;
+    _bucketCount = 16;
+    _mask = 15;
+    _isFrozen = false;
+    _cachedHash = null;
+    constructor() {
+        this._indices = new Uint32Array(16);
+    }
+    get size() { return this._keys.length; }
+    get isFrozen() { return this._isFrozen; }
+    isEmpty() { return this._keys.length === 0; }
     /**
-     * Creates a new RecursiveSet.
-     * Elements are sorted and deduplicated ($O(N \log N)$).
-     * @param elements Initial elements.
+     * Creates a shallow mutable copy of the map.
+     * Useful when the current map is frozen.
      */
-    constructor(...elements) {
-        if (elements.length > 1) {
-            elements.sort(compare);
-            this.#elements = this.#unique(elements);
-        }
-        else {
-            this.#elements = elements;
+    mutableCopy() {
+        const copy = new RecursiveMap();
+        copy.ensureCapacity(this.size);
+        for (let i = 0; i < this._keys.length; i++) {
+            copy.set(this._keys[i], this._values[i]);
         }
+        return copy;
     }
-    // === CRITICAL PERFORMANCE METHODS ===
-    /** * **Bulk Load (O(N log N))**: Creates a set from a raw array.
-     * Sorts and deduplicates. Much faster than iterative insertion.
+    /**
+     * Computes the hash code of the map.
+     * Order-independent (XOR sum).
+     * @remarks ACCESSING THIS FREEZES THE MAP.
      */
-    static fromArray(elements) {
-        const s = new RecursiveSet();
-        if (elements.length > 1) {
-            elements.sort(compare);
-            s.#elements = s.#unique(elements);
-        }
-        else {
-            s.#elements = elements;
+    get hashCode() {
+        if (this._cachedHash !== null)
+            return this._cachedHash;
+        let h = 0;
+        for (let i = 0; i < this._keys.length; i++) {
+            const k = this._keys[i];
+            const hk = this._hashes[i]; // Use cached hash for speed
+            // Force freeze on the key if it's structural (nested freeze)
+            if (k && typeof k === 'object') {
+                k.hashCode;
+            }
+            // Calculate value hash (freezes value if structural)
+            const hv = getHashCode(this._values[i]);
+            // Mix key hash and value hash
+            h ^= Math.imul(hk, 31) ^ hv;
         }
-        return s;
+        this._cachedHash = h;
+        this._isFrozen = true;
+        return h;
     }
-    /** * **UNSAFE (O(1))**: Bypasses all checks.
-     * @param sortedUnique Input must be ALREADY sorted and deduplicated.
-     * Use only if you strictly guarantee invariants.
+    /**
+     * Resizes the internal lookup table if load factor > 0.75.
      */
-    static fromSortedUnsafe(sortedUnique) {
-        const s = new RecursiveSet();
-        s.#elements = sortedUnique;
-        return s;
+    ensureCapacity(capacity) {
+        if (capacity * 1.33 > this._bucketCount) {
+            let target = this._bucketCount;
+            while (target * 0.75 < capacity)
+                target *= 2;
+            this._bucketCount = target;
+            this._mask = this._bucketCount - 1;
+            // Rehash all entries into new index table
+            const oldKeys = this._keys;
+            const oldHashes = this._hashes;
+            this._indices = new Uint32Array(this._bucketCount);
+            for (let i = 0; i < oldKeys.length; i++) {
+                const h = oldHashes[i];
+                let idx = h & this._mask;
+                // Linear Probing
+                while (this._indices[idx] !== 0)
+                    idx = (idx + 1) & this._mask;
+                this._indices[idx] = i + 1;
+            }
+        }
+    }
+    resize() {
+        this.ensureCapacity(this._keys.length + 1);
     }
-    #unique(sorted) {
-        if (sorted.length < 2)
-            return sorted;
-        const out = [sorted[0]];
-        let last = sorted[0];
-        const len = sorted.length;
-        for (let i = 1; i < len; i++) {
-            const curr = sorted[i];
-            if (compare(curr, last) !== 0) {
-                out.push(curr);
-                last = curr;
+    /**
+     * Associates the specified value with the specified key.
+     * If the map previously contained a mapping for the key, the old value is replaced.
+     */
+    set(key, value) {
+        if (this._isFrozen)
+            throw new Error("Frozen Map");
+        if (this._keys.length >= this._bucketCount * 0.75)
+            this.resize();
+        const h = getHashCode(key);
+        let idx = h & this._mask;
+        while (true) {
+            const entry = this._indices[idx];
+            // Found empty slot -> Insert new
+            if (entry === 0) {
+                this._hashes.push(h);
+                this._keys.push(key);
+                this._values.push(value);
+                this._indices[idx] = this._keys.length; // Store 1-based index
+                this._cachedHash = null;
+                return;
+            }
+            // Found existing key -> Update value
+            const ptr = entry - 1;
+            if (this._hashes[ptr] === h && areEqual(this._keys[ptr], key)) {
+                this._values[ptr] = value;
+                this._cachedHash = null;
+                return;
             }
+            // Collision -> Next slot
+            idx = (idx + 1) & this._mask;
         }
-        return out;
     }
-    #checkFrozen(op) {
-        if (this.#isFrozen) {
-            throw new Error(`InvalidOperation: Cannot ${op} a frozen RecursiveSet. Use mutableCopy().`);
+    get(key) {
+        const h = getHashCode(key);
+        let idx = h & this._mask;
+        while (true) {
+            const entry = this._indices[idx];
+            if (entry === 0)
+                return undefined;
+            const ptr = entry - 1;
+            if (this._hashes[ptr] === h && areEqual(this._keys[ptr], key))
+                return this._values[ptr];
+            idx = (idx + 1) & this._mask;
         }
     }
-    /** * Returns the internal sorted array (readonly).
-     * **Warning:** Readonly is only enforced by TypeScript.
-     * Mutating the underlying array via `as any` breaks invariants (Binary Search/Sort rely on strict ordering).
-     */
-    get raw() { return this.#elements; }
-    /** * Computes the hash code.
-     * **Side Effect**: Freezes the set to prevent hash corruption.
-     */
-    get hashCode() {
-        if (this.#hashCode !== null)
-            return this.#hashCode;
-        let h = 0;
-        const arr = this.#elements;
-        const len = arr.length;
-        for (let i = 0; i < len; i++) {
-            h = (Math.imul(31, h) + hashValue(arr[i])) | 0;
+    delete(key) {
+        if (this._isFrozen)
+            throw new Error("Frozen Map");
+        if (this.size === 0)
+            return false;
+        const h = getHashCode(key);
+        let idx = h & this._mask;
+        while (true) {
+            const entry = this._indices[idx];
+            if (entry === 0)
+                return false;
+            const ptr = entry - 1;
+            if (this._hashes[ptr] === h && areEqual(this._keys[ptr], key)) {
+                this._cachedHash = null;
+                // 1. Remove from index table (Backshift Deletion)
+                this.removeIndex(idx);
+                // 2. Remove from dense arrays (Swap with last element to keep arrays packed)
+                const lastKey = this._keys.pop();
+                const lastVal = this._values.pop();
+                const lastHash = this._hashes.pop();
+                if (ptr < this._keys.length) {
+                    this._keys[ptr] = lastKey;
+                    this._values[ptr] = lastVal;
+                    this._hashes[ptr] = lastHash;
+                    // Update index table to point to new location of the swapped element
+                    this.updateIndexForKey(lastHash, this._keys.length + 1, ptr + 1);
+                }
+                return true;
+            }
+            idx = (idx + 1) & this._mask;
         }
-        this.#hashCode = h;
-        this.#isFrozen = true; // Freeze on hash access
-        return h;
     }
-    get isFrozen() { return this.#isFrozen; }
-    get size() { return this.#elements.length; }
-    isEmpty() { return this.#elements.length === 0; }
-    /**
-     * Compares this set with another set for ordering.
-     * Uses hash comparison first, then deep structural comparison.
-     */
-    compare(other) {
-        if (this === other)
-            return 0;
-        const h1 = this.hashCode;
-        const h2 = other.hashCode;
-        if (h1 !== h2)
-            return h1 < h2 ? -1 : 1;
-        const arrA = this.#elements;
-        const arrB = other.#elements;
-        const len = arrA.length;
-        if (len !== arrB.length)
-            return len - arrB.length;
-        for (let i = 0; i < len; i++) {
-            const diff = compare(arrA[i], arrB[i]);
-            if (diff !== 0)
-                return diff;
+    /** Updates the index table when an element is moved in the dense arrays. */
+    updateIndexForKey(hash, oldLoc, newLoc) {
+        let idx = hash & this._mask;
+        while (true) {
+            if (this._indices[idx] === oldLoc) {
+                this._indices[idx] = newLoc;
+                return;
+            }
+            idx = (idx + 1) & this._mask;
         }
-        return 0;
     }
-    equals(other) { return this.compare(other) === 0; }
     /**
-     * Checks if element exists.
-     * Uses Binary Search ($O(\log N)$) for larger sets, linear scan for small sets.
+     * Removes an entry from the hash table and repairs the probe chain.
+     * Uses "Backshift Deletion" (Robin Hood style) to fill the hole.
      */
-    has(element) {
-        const arr = this.#elements;
-        const len = arr.length;
-        if (len < 10) { // Linear scan optimization
-            for (let i = 0; i < len; i++) {
-                if (compare(arr[i], element) === 0)
-                    return true;
+    removeIndex(holeIdx) {
+        let i = (holeIdx + 1) & this._mask;
+        while (this._indices[i] !== 0) {
+            const entry = this._indices[i];
+            const ptr = entry - 1;
+            const h = this._hashes[ptr];
+            const ideal = h & this._mask;
+            const distHole = (holeIdx - ideal + this._bucketCount) & this._mask;
+            const distI = (i - ideal + this._bucketCount) & this._mask;
+            // If the element at 'i' belongs to a bucket logically before the hole,
+            // or is further away from its ideal slot than the hole is, move it back.
+            if (distHole < distI) {
+                this._indices[holeIdx] = entry;
+                holeIdx = i;
             }
+            i = (i + 1) & this._mask;
+        }
+        this._indices[holeIdx] = 0;
+    }
+    equals(other) {
+        if (this === other)
+            return true;
+        if (!(other instanceof RecursiveMap))
             return false;
+        if (this.size !== other.size)
+            return false;
+        if (this.hashCode !== other.hashCode)
+            return false;
+        for (let i = 0; i < this._keys.length; i++) {
+            const val = other.get(this._keys[i]);
+            if (val === undefined || !areEqual(this._values[i], val))
+                return false;
         }
-        let low = 0, high = len - 1;
-        while (low <= high) {
-            const mid = (low + high) >>> 1;
-            const cmp = compare(arr[mid], element);
-            if (cmp === 0)
-                return true;
-            if (cmp < 0)
-                low = mid + 1;
-            else
-                high = mid - 1;
+        return true;
+    }
+    *[Symbol.iterator]() {
+        for (let i = 0; i < this._keys.length; i++)
+            yield [this._keys[i], this._values[i]];
+    }
+    toString() {
+        if (this.isEmpty())
+            return `RecursiveMap(0) {}`;
+        // Sort only for visual output stability
+        const entries = this._keys.map((k, i) => ({ key: k, value: this._values[i] }));
+        entries.sort((a, b) => compareVisualLogic(a.key, b.key));
+        const body = entries
+            .map(e => `  ${String(e.key)} => ${String(e.value)}`)
+            .join(',\n');
+        return `RecursiveMap(${this.size}) {\n${body}\n}`;
+    }
+    [Symbol.for('nodejs.util.inspect.custom')]() { return this.toString(); }
+}
+exports.RecursiveMap = RecursiveMap;
+// ============================================================================
+// 6. RECURSIVE SET
+// ============================================================================
+/**
+ * A Hash Set implementation supporting Value Semantics.
+ * * Features:
+ * - O(1) amortized Add/Has/Remove.
+ * - Deep equality for recursive structures.
+ * - Frozen state protection after hashing.
+ */
+class RecursiveSet {
+    _values = [];
+    _hashes = [];
+    _indices;
+    _bucketCount;
+    _mask;
+    _xorHash = 0;
+    _isFrozen = false;
+    LOAD_FACTOR = 0.75;
+    MIN_BUCKETS = 16;
+    constructor(...initialData) {
+        this._bucketCount = this.MIN_BUCKETS;
+        if (initialData.length > 0) {
+            const target = Math.ceil(initialData.length / this.LOAD_FACTOR);
+            while (this._bucketCount < target)
+                this._bucketCount <<= 1;
         }
-        return false;
+        this._mask = this._bucketCount - 1;
+        this._indices = new Uint32Array(this._bucketCount);
+        for (const item of initialData)
+            this.add(item);
+    }
+    get size() { return this._values.length; }
+    get isFrozen() { return this._isFrozen; }
+    isEmpty() { return this._values.length === 0; }
+    get hashCode() {
+        if (this._isFrozen)
+            return this._xorHash;
+        // Deep-freeze trigger: touch child hashCodes once
+        for (let i = 0; i < this._values.length; i++) {
+            const v = this._values[i];
+            if (v && typeof v === 'object') {
+                v.hashCode; // triggers freeze of nested RecursiveSet/Map/Tuple/etc.
+            }
+        }
+        this._isFrozen = true;
+        return this._xorHash;
     }
     /**
-     * Adds an element.
-     * @throws if set is frozen.
-     * Complexity: $O(N)$ (Array splice).
+     * Ensures the hash table has enough buckets to hold `capacity` elements
+     * without exceeding the load factor.
      */
-    add(element) {
-        this.#checkFrozen('add() to');
-        const arr = this.#elements;
-        // Optimization: Check last element first (append is common)
-        if (arr.length > 0) {
-            const lastCmp = compare(arr[arr.length - 1], element);
-            if (lastCmp < 0) {
-                arr.push(element);
-                this.#hashCode = null;
-                return this;
+    ensureCapacity(capacity) {
+        if (capacity * 1.33 > this._bucketCount) {
+            let target = this._bucketCount;
+            while (target * 0.75 < capacity)
+                target *= 2;
+            this._bucketCount = target;
+            this._mask = this._bucketCount - 1;
+            const oldValues = this._values;
+            const oldHashes = this._hashes;
+            this._indices = new Uint32Array(this._bucketCount);
+            for (let i = 0; i < oldValues.length; i++) {
+                const h = oldHashes[i];
+                let idx = h & this._mask;
+                while (this._indices[idx] !== 0)
+                    idx = (idx + 1) & this._mask;
+                this._indices[idx] = i + 1;
             }
-            if (lastCmp === 0)
-                return this;
-        }
-        let low = 0, high = arr.length - 1, idx = arr.length;
-        while (low <= high) {
-            const mid = (low + high) >>> 1;
-            const cmp = compare(arr[mid], element);
-            if (cmp === 0)
-                return this;
-            if (cmp < 0)
-                low = mid + 1;
-            else {
-                idx = mid;
-                high = mid - 1;
+        }
+    }
+    resize() {
+        this.ensureCapacity(this._values.length + 1);
+    }
+    /** Updates the index table when a value moves in the dense array */
+    updateIndexForValue(hash, oldLoc, newLoc) {
+        let idx = hash & this._mask;
+        while (true) {
+            if (this._indices[idx] === oldLoc) {
+                this._indices[idx] = newLoc;
+                return;
+            }
+            idx = (idx + 1) & this._mask;
+        }
+    }
+    /** Repairs the probe chain after deletion (Backshifting) */
+    removeIndex(holeIdx) {
+        let i = (holeIdx + 1) & this._mask;
+        while (this._indices[i] !== 0) {
+            const entry = this._indices[i];
+            const valPtr = entry - 1;
+            const h = this._hashes[valPtr];
+            const idealIdx = h & this._mask;
+            const distToHole = (holeIdx - idealIdx + this._bucketCount) & this._mask;
+            const distToI = (i - idealIdx + this._bucketCount) & this._mask;
+            if (distToHole < distToI) {
+                this._indices[holeIdx] = entry;
+                holeIdx = i;
             }
+            i = (i + 1) & this._mask;
         }
-        arr.splice(idx, 0, element);
-        this.#hashCode = null;
-        return this;
+        this._indices[holeIdx] = 0;
+    }
+    static compareVisual(a, b) {
+        return compareVisualLogic(a, b);
     }
     /**
-     * Removes an element.
+     * Adds an element to the set.
+     * @returns void to signal no chaining (performance).
      * @throws if set is frozen.
-     * Complexity: $O(N)$.
      */
-    remove(element) {
-        this.#checkFrozen('remove() from');
-        const arr = this.#elements;
-        let low = 0, high = arr.length - 1;
-        while (low <= high) {
-            const mid = (low + high) >>> 1;
-            const cmp = compare(arr[mid], element);
-            if (cmp === 0) {
-                arr.splice(mid, 1);
-                this.#hashCode = null;
-                return this;
+    add(e) {
+        if (this._isFrozen)
+            throw new Error("Frozen Set modified.");
+        if (this._values.length >= this._bucketCount * this.LOAD_FACTOR)
+            this.resize();
+        const h = getHashCode(e);
+        let idx = h & this._mask;
+        while (true) {
+            const entry = this._indices[idx];
+            if (entry === 0) {
+                this._hashes.push(h);
+                this._values.push(e);
+                this._indices[idx] = this._values.length;
+                this._xorHash ^= h;
+                return;
             }
-            if (cmp < 0)
-                low = mid + 1;
-            else
-                high = mid - 1;
+            const valIndex = entry - 1;
+            if (this._hashes[valIndex] === h && areEqual(this._values[valIndex], e))
+                return;
+            idx = (idx + 1) & this._mask;
+        }
+    }
+    has(element) {
+        const h = getHashCode(element);
+        let idx = h & this._mask;
+        while (true) {
+            const entry = this._indices[idx];
+            if (entry === 0)
+                return false;
+            const valIndex = entry - 1;
+            if (this._hashes[valIndex] === h && areEqual(this._values[valIndex], element))
+                return true;
+            idx = (idx + 1) & this._mask;
         }
-        return this;
     }
-    clear() {
-        this.#checkFrozen('clear()');
-        this.#elements = [];
-        this.#hashCode = 0;
-        return this;
+    remove(e) {
+        if (this._isFrozen)
+            throw new Error("Frozen Set modified.");
+        if (this._values.length === 0)
+            return;
+        const h = getHashCode(e);
+        let idx = h & this._mask;
+        while (true) {
+            const entry = this._indices[idx];
+            if (entry === 0)
+                return;
+            const valIndex = entry - 1;
+            if (this._hashes[valIndex] === h && areEqual(this._values[valIndex], e)) {
+                this._xorHash ^= h;
+                this.removeIndex(idx);
+                const lastVal = this._values.pop();
+                const lastHash = this._hashes.pop();
+                if (valIndex < this._values.length) {
+                    this._values[valIndex] = lastVal;
+                    this._hashes[valIndex] = lastHash;
+                    this.updateIndexForValue(lastHash, this._values.length + 1, valIndex + 1);
+                }
+                return;
+            }
+            idx = (idx + 1) & this._mask;
+        }
     }
-    mutableCopy() {
+    clone() {
         const s = new RecursiveSet();
-        s.#elements = this.#elements.slice();
+        if (s._bucketCount !== this._bucketCount)
+            s.ensureCapacity(this.size);
+        if (s._bucketCount === this._bucketCount) {
+            s._indices.set(this._indices);
+            s._values = this._values.slice();
+            s._hashes = this._hashes.slice();
+            s._xorHash = this._xorHash;
+        }
+        else {
+            for (const v of this._values)
+                s.add(v);
+        }
         return s;
     }
-    clone() { return this.mutableCopy(); }
-    // === OPTIMIZED SET OPERATIONS (Merge Scan) ===
+    // ========================================================================
+    // === FUNCTIONAL METHODS (Optimized) ===
+    // ========================================================================
     /**
-     * Computes Union $A \cup B$.
-     * Implementation: Merge Scan.
-     * Complexity: $O(|A| + |B|)$.
+     * Tests whether all elements in the set pass the test implemented by the provided function.
+     * Uses internal iteration for max speed.
      */
-    union(other) {
-        const A = this.#elements;
-        const B = other.raw; // Efficient access via getter
-        const res = [];
-        let i = 0, j = 0;
-        const lenA = A.length, lenB = B.length;
-        while (i < lenA && j < lenB) {
-            const cmp = compare(A[i], B[j]);
-            if (cmp < 0)
-                res.push(A[i++]);
-            else if (cmp > 0)
-                res.push(B[j++]);
-            else {
-                res.push(A[i++]);
-                j++;
-            }
+    every(predicate) {
+        // Direct array access avoids iterator generator overhead
+        for (let i = 0; i < this._values.length; i++) {
+            if (!predicate(this._values[i]))
+                return false;
         }
-        while (i < lenA)
-            res.push(A[i++]);
-        while (j < lenB)
-            res.push(B[j++]);
-        return RecursiveSet.fromSortedUnsafe(res);
+        return true;
     }
     /**
-     * Computes Intersection $A \cap B$.
-     * Implementation: Synchronous Scan.
-     * Complexity: $O(|A| + |B|)$.
+     * Tests whether at least one element in the set passes the test.
      */
-    intersection(other) {
-        const A = this.#elements;
-        const B = other.raw;
-        const res = [];
-        let i = 0, j = 0;
-        const lenA = A.length, lenB = B.length;
-        while (i < lenA && j < lenB) {
-            const cmp = compare(A[i], B[j]);
-            if (cmp < 0)
-                i++;
-            else if (cmp > 0)
-                j++;
-            else {
-                res.push(A[i++]);
-                j++;
-            }
+    some(predicate) {
+        for (let i = 0; i < this._values.length; i++) {
+            if (predicate(this._values[i]))
+                return true;
         }
-        return RecursiveSet.fromSortedUnsafe(res);
+        return false;
     }
     /**
-     * Computes Difference $A \setminus B$.
-     * Complexity: $O(|A| + |B|)$.
+     * Creates a new RecursiveSet populated with the results of calling a provided function.
+     * Pre-allocates storage to prevent resizing.
      */
-    difference(other) {
-        const A = this.#elements;
-        const B = other.raw;
-        const res = [];
-        let i = 0, j = 0;
-        const lenA = A.length, lenB = B.length;
-        while (i < lenA && j < lenB) {
-            const cmp = compare(A[i], B[j]);
-            if (cmp < 0)
-                res.push(A[i++]);
-            else if (cmp > 0)
-                j++;
-            else {
-                i++;
-                j++;
-            }
+    map(callback) {
+        const result = new RecursiveSet();
+        result.ensureCapacity(this.size);
+        for (let i = 0; i < this._values.length; i++) {
+            result.add(callback(this._values[i]));
         }
-        while (i < lenA)
-            res.push(A[i++]);
-        return RecursiveSet.fromSortedUnsafe(res);
+        return result;
     }
     /**
-     * Computes Symmetric Difference $A \triangle B$.
-     * Complexity: $O(|A| + |B|)$.
+     * Creates a new RecursiveSet with all elements that pass the test.
      */
-    symmetricDifference(other) {
-        const A = this.#elements;
-        const B = other.raw;
-        const res = [];
-        let i = 0, j = 0;
-        const lenA = A.length, lenB = B.length;
-        while (i < lenA && j < lenB) {
-            const cmp = compare(A[i], B[j]);
-            if (cmp < 0)
-                res.push(A[i++]);
-            else if (cmp > 0)
-                res.push(B[j++]);
-            else {
-                i++;
-                j++;
-            }
+    filter(predicate) {
+        const result = new RecursiveSet();
+        for (let i = 0; i < this._values.length; i++) {
+            const v = this._values[i];
+            if (predicate(v))
+                result.add(v);
         }
-        while (i < lenA)
-            res.push(A[i++]);
-        while (j < lenB)
-            res.push(B[j++]);
-        return RecursiveSet.fromSortedUnsafe(res);
+        return result;
     }
     /**
-     * Computes Cartesian Product $A \times B$.
-     * Complexity: $O(|A| \cdot |B| \cdot \log(|A| \cdot |B|))$ (due to sorting).
+     * Executes a reducer function on each element.
      */
+    reduce(callback, initialValue) {
+        let accumulator = initialValue;
+        for (let i = 0; i < this._values.length; i++) {
+            accumulator = callback(accumulator, this._values[i]);
+        }
+        return accumulator;
+    }
+    // === SET OPERATIONS ===
+    union(other) {
+        const res = this.clone();
+        for (const v of other._values)
+            res.add(v);
+        return res;
+    }
+    intersection(other) {
+        const res = new RecursiveSet();
+        // Iterate over smaller set for O(min(N, M))
+        const [small, large] = this.size < other.size ? [this, other] : [other, this];
+        for (const v of small._values) {
+            if (large.has(v))
+                res.add(v);
+        }
+        return res;
+    }
+    difference(other) {
+        if (other.isEmpty())
+            return this.clone();
+        const res = new RecursiveSet();
+        for (const v of this._values) {
+            if (!other.has(v))
+                res.add(v);
+        }
+        return res;
+    }
+    symmetricDifference(other) {
+        const res = new RecursiveSet();
+        for (const v of this._values) {
+            if (!other.has(v))
+                res.add(v);
+        }
+        for (const v of other._values) {
+            if (!this.has(v))
+                res.add(v);
+        }
+        return res;
+    }
     cartesianProduct(other) {
-        const result = [];
-        const arrA = this.#elements;
-        const arrB = other.raw;
-        const lenA = arrA.length;
-        const lenB = arrB.length;
-        for (let i = 0; i < lenA; i++) {
-            const a = arrA[i];
-            for (let j = 0; j < lenB; j++) {
-                result.push(new Tuple(a, arrB[j]));
+        const result = new RecursiveSet();
+        result.ensureCapacity(this.size * other.size);
+        for (const a of this) {
+            for (const b of other) {
+                result.add(new Tuple(a, b));
             }
         }
-        // Hashes are not monotonic, so we MUST sort. 
-        result.sort(compare);
-        // But uniqueness is guaranteed mathematically, so use unsafe create
-        return RecursiveSet.fromSortedUnsafe(result);
+        return result;
     }
     /**
-     * Computes the Power Set $\mathcal{P}(A)$.
-     * Complexity: $O(2^N)$.
-     * @throws if size > 20.
+     * Computes the Power Set.
+     * Warning: Complexity is O(2^N). Use only for small N.
+     * @throws Error if size > 20 to prevent memory exhaustion and 32-bit shift overflow.
      */
     powerset() {
-        const n = this.size;
-        if (n > 20)
-            throw new Error("Powerset too large");
-        const subsets = [];
+        const n = this._values.length;
+        if (n > 20) {
+            throw new Error(`Powerset size too large (N=${n}). Max supported is 20.`);
+        }
         const max = 1 << n;
+        const result = new RecursiveSet();
+        result.ensureCapacity(max);
         for (let i = 0; i < max; i++) {
-            const subsetElements = [];
+            const subset = new RecursiveSet();
             for (let j = 0; j < n; j++) {
-                if (i & (1 << j))
-                    subsetElements.push(this.#elements[j]);
+                if ((i & (1 << j)) !== 0) {
+                    subset.add(this._values[j]);
+                }
             }
-            // Elements inside subset are already sorted -> Unsafe
-            subsets.push(RecursiveSet.fromSortedUnsafe(subsetElements));
+            result.add(subset);
         }
-        // Subsets themselves need sorting
-        return RecursiveSet.fromArray(subsets);
+        return result;
+    }
+    pickRandom() {
+        if (this._values.length === 0)
+            return undefined;
+        return this._values[Math.floor(Math.random() * this._values.length)];
     }
     isSubset(other) {
         if (this.size > other.size)
             return false;
-        let i = 0, j = 0;
-        const A = this.#elements, B = other.raw;
-        while (i < A.length && j < B.length) {
-            const cmp = compare(A[i], B[j]);
-            if (cmp < 0)
+        if (this === other)
+            return true;
+        for (const item of this._values) {
+            if (!other.has(item))
                 return false;
-            if (cmp > 0)
-                j++;
-            else {
-                i++;
-                j++;
-            }
         }
-        return i === A.length;
+        return true;
+    }
+    isSuperset(other) {
+        return other.isSubset(this);
+    }
+    [Symbol.iterator]() { return this._values[Symbol.iterator](); }
+    equals(other) {
+        if (this === other)
+            return true;
+        if (!(other instanceof RecursiveSet))
+            return false;
+        if (this.size !== other.size)
+            return false;
+        if (this.hashCode !== other.hashCode)
+            return false;
+        for (const v of this._values) {
+            if (!other.has(v))
+                return false;
+        }
+        return true;
+    }
+    toString() {
+        // Use compareVisual exclusively for user-facing output
+        const sorted = [...this._values].sort(compareVisualLogic);
+        return `{${sorted.map(String).join(', ')}}`;
     }
-    isSuperset(other) { return other.isSubset(this); }
-    /** Iterates over set elements in sorted order. */
-    *[Symbol.iterator]() { yield* this.#elements; }
-    /** Returns string representation e.g. "{1, 2, 3}". */
-    toString() { return `{${this.#elements.join(', ')}}`; }
-    /** Custom inspection for Node.js console to avoid printing internal state. */
     [Symbol.for('nodejs.util.inspect.custom')]() { return this.toString(); }
 }
 exports.RecursiveSet = RecursiveSet;
-// Exports
-/** Factory: Creates an empty RecursiveSet */
+// ============================================================================
+// 7. PUBLIC EXPORTS
+// ============================================================================
 function emptySet() { return new RecursiveSet(); }
-/** Factory: Creates a singleton RecursiveSet containing {element} */
-function singleton(element) { return new RecursiveSet(element); }
+function singleton(el) { return new RecursiveSet(el); }
+const hashValue = getHashCode;
+exports.hashValue = hashValue;
 //# sourceMappingURL=index.js.map