recursive-set 2.2.1 → 4.0.0

package/dist/esm/index.js

@@ -1,274 +1,494 @@
-import createTree from 'functional-red-black-tree';
 /**
  * @module recursive-set
- * A mutable recursive set implementation enforcing Cantor's ZFC axioms.
- * Powered by functional Red-Black Trees for O(log n) operations and O(1) cloning.
+ * High-Performance Mutable Recursive Set backed by Sorted Arrays.
+ * Optimized for small sets, structural equality, and deterministic hashing.
+ */
+// === HASHING ENGINE ===
+/**
+ * FNV-1a Hash implementation for strings.
+ * Constants inlined for V8 optimization.
+ */
+function hashString(str) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < str.length; i++) {
+        hash ^= str.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 0;
+}
+/**
+ * Universal Hash Function.
+ * Calculates deterministic hashes for Primitives, Sequences (Order Dependent), and Sets.
+ */
+function hashValue(val) {
+    if (typeof val === 'string')
+        return hashString(val);
+    if (typeof val === 'number')
+        return val | 0;
+    // Fast Path: Objects with cached hash
+    if (val instanceof RecursiveSet)
+        return val.hashCode;
+    if (val instanceof Tuple)
+        return val.hashCode;
+    // Arrays: Treated as sequences (Rolling Hash)
+    if (Array.isArray(val)) {
+        let h = 0;
+        for (let i = 0; i < val.length; i++) {
+            let v = val[i];
+            let vh = 0;
+            if (typeof v === 'string')
+                vh = hashString(v);
+            else
+                vh = hashValue(v);
+            h = Math.imul(31, h) + vh;
+        }
+        return h >>> 0;
+    }
+    return 0;
+}
+// === COMPARATOR ===
+/**
+ * High-performance comparator with hash short-circuiting.
+ * Order: Primitives (0) < Sequences (1) < Sets (2)
+ */
+function compare(a, b) {
+    if (a === b)
+        return 0;
+    // 1. Hash Short-Circuit
+    // Using interface casting avoids runtime overhead of 'in' operator checks
+    const aH = a?.hashCode;
+    const bH = b?.hashCode;
+    const ha = (aH !== undefined) ? aH : hashValue(a);
+    const hb = (bH !== undefined) ? bH : hashValue(b);
+    if (ha !== hb)
+        return ha < hb ? -1 : 1;
+    // 2. Primitive Value Check
+    const typeA = typeof a;
+    const typeB = typeof b;
+    if (typeA === 'string' && typeB === 'string')
+        return a < b ? -1 : 1;
+    if (typeA === 'number' && typeB === 'number')
+        return a < b ? -1 : 1;
+    // 3. Structural Type Check
+    const isSetA = a instanceof RecursiveSet;
+    const isSetB = b instanceof RecursiveSet;
+    if (isSetA && isSetB) {
+        return a.compare(b);
+    }
+    const isArrA = Array.isArray(a);
+    const isArrB = Array.isArray(b);
+    const isTupA = a instanceof Tuple;
+    const isTupB = b instanceof Tuple;
+    const isSeqA = isArrA || isTupA;
+    const isSeqB = isArrB || isTupB;
+    // Sort by Type Group if types differ
+    if (isSetA !== isSetB || isSeqA !== isSeqB) {
+        const scoreA = isSetA ? 2 : isSeqA ? 1 : 0;
+        const scoreB = isSetB ? 2 : isSeqB ? 1 : 0;
+        return scoreA - scoreB;
+    }
+    // 4. Sequence Comparison (Array/Tuple)
+    if (isSeqA && isSeqB) {
+        const valA = isTupA ? a.values : a;
+        const valB = isTupB ? b.values : b;
+        const len = valA.length;
+        if (len !== valB.length)
+            return len - valB.length;
+        for (let i = 0; i < len; i++) {
+            const diff = compare(valA[i], valB[i]);
+            if (diff !== 0)
+                return diff;
+        }
+        return 0;
+    }
+    // Fallback for safe types
+    return a < b ? -1 : 1;
+}
+// === CLASSES ===
+/**
+ * Immutable wrapper for sequence values.
+ * Useful when strict typing for sequences is required.
+ */
+export class Tuple {
+    values;
+    hashCode;
+    constructor(...values) {
+        this.values = values;
+        this.hashCode = hashValue(values);
+    }
+    get length() { return this.values.length; }
+    get(i) { return this.values[i]; }
+    *[Symbol.iterator]() { yield* this.values; }
+    toString() { return `(${this.values.join(', ')})`; }
+    [Symbol.for('nodejs.util.inspect.custom')]() { return this.toString(); }
+}
+/**
+ * A Set implementation that supports deep structural equality and efficient hashing.
+ * Internally backed by a sorted array for optimal CPU cache locality on small sets.
  */
 export class RecursiveSet {
-    // Underlying persistent data structure
-    _tree;
-    // Internal XOR-based hash for O(1) inequality checks
-    _hash = 0;
     /**
-     * Static comparator for Red-Black Tree ordering.
-     * Handles primitives, RecursiveSets, and deep structural equality.
+     * Internal storage. Public for inlining access within the module, but treated as private API.
      */
-    static compare(a, b) {
-        // 1. Identity optimization
-        if (a === b)
-            return 0;
-        // 2. Type separation
-        const isSetA = a instanceof RecursiveSet;
-        const isSetB = b instanceof RecursiveSet;
-        if (isSetA !== isSetB)
-            return isSetA ? 1 : -1;
-        // 3. Primitives
-        if (!isSetA) {
-            if (typeof a !== typeof b)
-                return typeof a > typeof b ? 1 : -1;
-            if (a < b)
-                return -1;
-            if (a > b)
-                return 1;
-            return 0;
+    _elements;
+    _hashCode = null;
+    static compare(a, b) { return compare(a, b); }
+    constructor(...elements) {
+        if (elements.length === 0) {
+            this._elements = [];
+            this._hashCode = 0;
         }
-        // 4. Recursive Sets
-        const sizeA = a.size;
-        const sizeB = b.size;
-        if (sizeA !== sizeB)
-            return sizeA < sizeB ? -1 : 1;
-        // Hash mismatch implies inequality (O(1))
-        if (a._hash !== b._hash)
-            return a._hash < b._hash ? -1 : 1;
-        // Deep structural comparison using internal iterators (low-level optimization)
-        let iterA = a._tree.begin;
-        let iterB = b._tree.begin;
-        while (iterA.valid && iterB.valid) {
-            const cmp = RecursiveSet.compare(iterA.key, iterB.key);
-            if (cmp !== 0)
-                return cmp;
-            iterA.next();
-            iterB.next();
+        else {
+            this._elements = elements;
+            this._elements.sort(compare);
+            this._unique();
         }
-        return 0;
     }
-    constructor(...elements) {
-        this._tree = createTree(RecursiveSet.compare);
-        for (const el of elements) {
-            this.add(el);
+    _unique() {
+        const arr = this._elements;
+        const len = arr.length;
+        if (len < 2)
+            return;
+        let write = 1;
+        for (let read = 1; read < len; read++) {
+            if (compare(arr[read], arr[read - 1]) !== 0) {
+                arr[write++] = arr[read];
+            }
         }
+        arr.length = write;
     }
-    // === Copy-on-Write Support ===
     /**
-     * Creates a shallow copy of the set in O(1) time.
-     * Leveraging the persistent nature of the underlying tree.
+     * Calculates the hash code for the set.
+     * Uses a rolling hash over sorted elements, ensuring determinstic results for equal sets.
      */
-    clone() {
-        const clone = new RecursiveSet();
-        clone._tree = this._tree;
-        clone._hash = this._hash;
-        return clone;
+    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]);
+        }
+        this._hashCode = h | 0;
+        return this._hashCode;
+    }
+    // Backward compatibility alias
+    getHashCode() { return this.hashCode; }
+    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 cmp = compare(arrA[i], arrB[i]);
+            if (cmp !== 0)
+                return cmp;
+        }
+        return 0;
+    }
+    get size() { return this._elements.length; }
+    isEmpty() { return this._elements.length === 0; }
+    has(element) {
+        const arr = this._elements;
+        const len = arr.length;
+        // Small Array Optimization: Linear Scan is faster than Binary Search overhead for N < 16
+        if (len < 16) {
+            for (let i = 0; i < len; i++) {
+                if (compare(arr[i], element) === 0)
+                    return true;
+            }
+            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 false;
     }
-    // === Mutable Operations ===
     add(element) {
-        if (typeof element === "number" && Number.isNaN(element)) {
-            throw new Error("NaN is not supported as an element of RecursiveSet");
+        // --- Validation Check ---
+        if (typeof element === 'object' && element !== null) {
+            const isSet = element instanceof RecursiveSet;
+            const isTup = element instanceof Tuple;
+            const isArr = Array.isArray(element);
+            if (!isSet && !isTup && !isArr) {
+                throw new Error("Plain Objects are not supported. Use Tuple, Array or RecursiveSet.");
+            }
+        }
+        else if (typeof element === "number" && Number.isNaN(element)) {
+            throw new Error("NaN is not supported");
+        }
+        // --- End Validation ---
+        const arr = this._elements;
+        const len = arr.length;
+        // Common Case: Appending a larger element (during ordered construction)
+        if (len > 0) {
+            const lastCmp = compare(arr[len - 1], element);
+            if (lastCmp < 0) {
+                arr.push(element);
+                this._hashCode = null;
+                return this;
+            }
+            if (lastCmp === 0)
+                return this;
+        }
+        else {
+            arr.push(element);
+            this._hashCode = null;
+            return this;
         }
-        // Idempotency check prevents redundant hash updates and tree operations
-        if (this.has(element)) {
+        // Small Array Strategy: Linear Scan + Splice
+        if (len < 16) {
+            for (let i = 0; i < len; i++) {
+                const cmp = compare(arr[i], element);
+                if (cmp === 0)
+                    return this;
+                if (cmp > 0) {
+                    arr.splice(i, 0, element);
+                    this._hashCode = null;
+                    return this;
+                }
+            }
             return this;
         }
-        // Enforce Foundation Axiom (prevent cycles)
-        if (element instanceof RecursiveSet) {
-            if (this._wouldCreateCycle(element)) {
-                throw new Error("Foundation axiom violated: membership cycle detected");
+        // Large Array Strategy: Binary Search
+        let low = 0, high = len - 1, idx = 0;
+        while (low <= high) {
+            const mid = (low + high) >>> 1;
+            const cmp = compare(arr[mid], element);
+            if (cmp === 0)
+                return this;
+            if (cmp < 0) {
+                idx = mid + 1;
+                low = mid + 1;
+            }
+            else {
+                idx = mid;
+                high = mid - 1;
             }
         }
-        // Update Hash (XOR)
-        this._hash = (this._hash ^ this._computeHash(element)) | 0;
-        // Insert into persistent tree
-        this._tree = this._tree.insert(element, true);
+        arr.splice(idx, 0, element);
+        this._hashCode = null;
         return this;
     }
     remove(element) {
-        if (!this.has(element)) {
+        const arr = this._elements;
+        const len = arr.length;
+        if (len < 16) {
+            for (let i = 0; i < len; i++) {
+                if (compare(arr[i], element) === 0) {
+                    arr.splice(i, 1);
+                    this._hashCode = null;
+                    return this;
+                }
+            }
             return this;
         }
-        // Update Hash (XOR removes the element from hash)
-        this._hash = (this._hash ^ this._computeHash(element)) | 0;
-        this._tree = this._tree.remove(element);
+        let low = 0, high = len - 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;
+            }
+            if (cmp < 0)
+                low = mid + 1;
+            else
+                high = mid - 1;
+        }
         return this;
     }
     clear() {
-        this._tree = createTree(RecursiveSet.compare);
-        this._hash = 0;
+        this._elements = [];
+        this._hashCode = 0;
         return this;
     }
-    _computeHash(element) {
-        if (element instanceof RecursiveSet)
-            return element._hash;
-        if (typeof element === 'number')
-            return element | 0;
-        if (typeof element === 'string') {
-            let h = 0;
-            for (let i = 0; i < element.length; i++)
-                h = Math.imul(31, h) + element.charCodeAt(i) | 0;
-            return h;
-        }
-        return 0;
+    clone() {
+        const s = new RecursiveSet();
+        s._elements = this._elements.slice();
+        s._hashCode = this._hashCode;
+        return s;
     }
-    // === Immutable Operations ===
     union(other) {
-        const result = this.clone(); // Optimization: Start with clone of this
-        for (const el of other)
-            result.add(el);
-        return result;
+        const s = new RecursiveSet();
+        const arrA = this._elements;
+        const arrB = other._elements;
+        if (arrA.length === 0)
+            return other.clone();
+        if (arrB.length === 0)
+            return this.clone();
+        const res = [];
+        let i = 0, j = 0;
+        const lenA = arrA.length, lenB = arrB.length;
+        // Merge Sort Algorithm O(N + M)
+        while (i < lenA && j < lenB) {
+            const cmp = compare(arrA[i], arrB[j]);
+            if (cmp < 0)
+                res.push(arrA[i++]);
+            else if (cmp > 0)
+                res.push(arrB[j++]);
+            else {
+                res.push(arrA[i++]);
+                j++;
+            }
+        }
+        while (i < lenA)
+            res.push(arrA[i++]);
+        while (j < lenB)
+            res.push(arrB[j++]);
+        s._elements = res;
+        return s;
     }
     intersection(other) {
-        const result = new RecursiveSet();
-        // Iterate over smaller set for performance optimization
-        const [smaller, larger] = this.size < other.size ? [this, other] : [other, this];
-        for (const el of smaller) {
-            if (larger.has(el)) {
-                result.add(el);
+        const s = new RecursiveSet();
+        const arrA = this._elements;
+        const arrB = other._elements;
+        const res = [];
+        let i = 0, j = 0;
+        const lenA = arrA.length, lenB = arrB.length;
+        while (i < lenA && j < lenB) {
+            const cmp = compare(arrA[i], arrB[j]);
+            if (cmp < 0)
+                i++;
+            else if (cmp > 0)
+                j++;
+            else {
+                res.push(arrA[i++]);
+                j++;
             }
         }
-        return result;
+        s._elements = res;
+        return s;
     }
     difference(other) {
-        const result = new RecursiveSet();
-        for (const el of this) {
-            if (!other.has(el)) {
-                result.add(el);
+        const s = new RecursiveSet();
+        const arrA = this._elements;
+        const arrB = other._elements;
+        const res = [];
+        let i = 0, j = 0;
+        const lenA = arrA.length, lenB = arrB.length;
+        while (i < lenA && j < lenB) {
+            const cmp = compare(arrA[i], arrB[j]);
+            if (cmp < 0)
+                res.push(arrA[i++]);
+            else if (cmp > 0)
+                j++;
+            else {
+                i++;
+                j++;
             }
         }
-        return result;
+        while (i < lenA)
+            res.push(arrA[i++]);
+        s._elements = res;
+        return s;
     }
     symmetricDifference(other) {
-        // (A \ B) U (B \ A)
-        return this.difference(other).union(other.difference(this));
+        const s = new RecursiveSet();
+        const arrA = this._elements;
+        const arrB = other._elements;
+        const res = [];
+        let i = 0, j = 0;
+        const lenA = arrA.length, lenB = arrB.length;
+        while (i < lenA && j < lenB) {
+            const cmp = compare(arrA[i], arrB[j]);
+            if (cmp < 0)
+                res.push(arrA[i++]);
+            else if (cmp > 0)
+                res.push(arrB[j++]);
+            else {
+                i++;
+                j++;
+            }
+        }
+        while (i < lenA)
+            res.push(arrA[i++]);
+        while (j < lenB)
+            res.push(arrB[j++]);
+        s._elements = res;
+        return s;
     }
     powerset() {
         const n = this.size;
-        if (n > 30)
-            throw new Error("Powerset size exceeds 32-bit integer limit");
-        const elements = [];
-        this._tree.forEach((key) => { elements.push(key); return undefined; });
+        if (n > 20)
+            throw new Error("Powerset too large");
         const subsets = [];
-        for (let i = 0; i < (1 << n); i++) {
+        const max = 1 << n;
+        for (let i = 0; i < max; i++) {
             const subset = new RecursiveSet();
             for (let j = 0; j < n; j++) {
-                if (i & (1 << j)) {
-                    subset.add(elements[j]);
-                }
+                if (i & (1 << j))
+                    subset._elements.push(this._elements[j]);
             }
             subsets.push(subset);
         }
         return new RecursiveSet(...subsets);
     }
     cartesianProduct(other) {
-        const pairs = [];
-        for (const x of this) {
-            for (const y of other) {
-                const valX = x;
-                const valY = y;
-                // Kuratowski pair: (x, y) = {{x}, {x, y}}
-                const pair = new RecursiveSet(new RecursiveSet(valX), new RecursiveSet(valX, valY));
-                pairs.push(pair);
+        const result = new RecursiveSet();
+        const arrA = this._elements;
+        const arrB = other._elements;
+        for (const x of arrA) {
+            for (const y of arrB) {
+                result._elements.push(new Tuple(x, y));
             }
         }
-        return new RecursiveSet(...pairs);
-    }
-    // === Predicates ===
-    has(element) {
-        return this._tree.get(element) !== undefined;
+        return result;
     }
+    // Standard Set methods
     isSubset(other) {
         if (this.size > other.size)
             return false;
-        for (const el of this) {
-            if (!other.has(el))
+        let i = 0, j = 0;
+        const arrA = this._elements, arrB = other._elements;
+        while (i < arrA.length && j < arrB.length) {
+            const cmp = compare(arrA[i], arrB[j]);
+            if (cmp < 0)
                 return false;
+            if (cmp > 0)
+                j++;
+            else {
+                i++;
+                j++;
+            }
         }
-        return true;
-    }
-    isSuperset(other) {
-        return other.isSubset(this);
-    }
-    isProperSubset(other) {
-        return this.isSubset(other) && !this.equals(other);
-    }
-    isEmpty() {
-        return this.size === 0;
-    }
-    equals(other) {
-        return RecursiveSet.compare(this, other) === 0;
-    }
-    // === Internals ===
-    _wouldCreateCycle(element) {
-        const visited = new Set();
-        const stack = [element];
-        while (stack.length > 0) {
-            const current = stack.pop();
-            if (current === this)
-                return true;
-            if (visited.has(current))
-                continue;
-            visited.add(current);
-            // Optimization: Direct internal tree traversal avoids iterator overhead
-            current._tree.forEach((key) => {
-                if (key instanceof RecursiveSet) {
-                    stack.push(key);
-                }
-                return undefined;
-            });
-        }
-        return false;
-    }
-    // === Utility ===
-    get size() {
-        return this._tree.length;
-    }
-    toSet() {
-        const result = new Set();
-        this._tree.forEach((key) => { result.add(key); return undefined; });
-        return result;
-    }
-    // Lazy Iterator (Critical for performance)
-    *[Symbol.iterator]() {
-        let iter = this._tree.begin;
-        while (iter.valid) {
-            yield iter.key;
-            iter.next();
-        }
+        return i === arrA.length;
     }
+    isSuperset(other) { return other.isSubset(this); }
+    isProperSubset(other) { return this.isSubset(other) && this.size < other.size; }
+    equals(other) { return this.compare(other) === 0; }
+    toSet() { return new Set(this._elements); }
+    *[Symbol.iterator]() { yield* this._elements; }
     toString() {
         if (this.isEmpty())
             return "∅";
-        const elements = [];
-        this._tree.forEach((key) => {
-            if (key instanceof RecursiveSet) {
-                elements.push(key.toString());
-            }
-            else {
-                elements.push(String(key));
-            }
-            return undefined;
+        const elementsStr = this._elements.map(el => {
+            if (Array.isArray(el))
+                return `[${el.join(', ')}]`;
+            return String(el);
         });
-        return `{${elements.join(", ")}}`;
-    }
-    [Symbol.for('nodejs.util.inspect.custom')]() {
-        return this.toString();
+        return `{${elementsStr.join(', ')}}`;
     }
+    [Symbol.for('nodejs.util.inspect.custom')]() { return this.toString(); }
 }
-// === Helpers ===
-export function emptySet() {
-    return new RecursiveSet();
-}
-export function singleton(element) {
-    return new RecursiveSet(element);
-}
-export function fromIterable(iterable) {
-    return new RecursiveSet(...iterable);
-}
+export function emptySet() { return new RecursiveSet(); }
+export function singleton(element) { return new RecursiveSet(element); }
+export function fromIterable(iterable) { return new RecursiveSet(...iterable); }
 //# sourceMappingURL=index.js.map