recursive-set 3.0.0 → 4.0.0

package/dist/esm/index.js

@@ -1,278 +1,494 @@
-import createTree from 'functional-red-black-tree';
 /**
  * @module recursive-set
- * A mutable recursive set implementation.
- * 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 ===
 /**
- * A lightweight wrapper for Tuples to enable Value-Equality in RecursiveSet.
- * Immutable by design.
+ * FNV-1a Hash implementation for strings.
+ * Constants inlined for V8 optimization.
  */
-export class Tuple {
-    values;
-    constructor(...values) {
-        this.values = values;
+function hashString(str) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < str.length; i++) {
+        hash ^= str.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
     }
-    get length() {
-        return this.values.length;
+    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;
     }
-    get(index) {
-        return this.values[index];
+    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);
     }
-    *[Symbol.iterator]() {
-        for (const val of this.values) {
-            yield val;
-        }
+    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;
     }
-    toString() {
-        return `(${this.values.map(v => String(v)).join(', ')})`;
+    // 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;
     }
-    [Symbol.for('nodejs.util.inspect.custom')]() {
-        return this.toString();
+    // 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 {
-    _tree;
     /**
-     * Static comparator for Red-Black Tree ordering.
-     * Supports Primitives, RecursiveSets and Tuples.
-     * REJECTS plain JS Objects and Arrays to enforce strict semantics.
+     * Internal storage. Public for inlining access within the module, but treated as private API.
      */
-    static compare(a, b) {
-        if (a === b)
-            return 0;
-        const isSetA = a instanceof RecursiveSet;
-        const isSetB = b instanceof RecursiveSet;
-        const isTupA = a instanceof Tuple;
-        const isTupB = b instanceof Tuple;
-        // Sort Order: Primitives (0) < Tuples (1) < Sets (2)
-        const getTypeScore = (isSet, isTup) => {
-            if (isSet)
-                return 2;
-            if (isTup)
-                return 1;
-            return 0;
-        };
-        const scoreA = getTypeScore(isSetA, isTupA);
-        const scoreB = getTypeScore(isSetB, isTupB);
-        if (scoreA !== scoreB)
-            return scoreA < scoreB ? -1 : 1;
-        // 1. Sets
-        if (isSetA && isSetB) {
-            const setA = a;
-            const setB = b;
-            if (setA.size !== setB.size)
-                return setA.size < setB.size ? -1 : 1;
-            let iterA = setA._tree.begin;
-            let iterB = setB._tree.begin;
-            while (iterA.valid && iterB.valid) {
-                const cmp = RecursiveSet.compare(iterA.key, iterB.key);
-                if (cmp !== 0)
-                    return cmp;
-                iterA.next();
-                iterB.next();
-            }
-            return 0;
+    _elements;
+    _hashCode = null;
+    static compare(a, b) { return compare(a, b); }
+    constructor(...elements) {
+        if (elements.length === 0) {
+            this._elements = [];
+            this._hashCode = 0;
         }
-        // 2. Tuples
-        if (isTupA && isTupB) {
-            const tupA = a;
-            const tupB = b;
-            if (tupA.length !== tupB.length)
-                return tupA.length < tupB.length ? -1 : 1;
-            for (let i = 0; i < tupA.length; i++) {
-                const cmp = RecursiveSet.compare(tupA.get(i), tupB.get(i));
-                if (cmp !== 0)
-                    return cmp;
-            }
-            return 0;
+        else {
+            this._elements = elements;
+            this._elements.sort(compare);
+            this._unique();
         }
-        // 3. Primitives (guaranteed by add() validation)
-        const tA = typeof a;
-        const tB = typeof b;
-        if (tA !== tB)
-            return tA > tB ? 1 : -1;
-        // @ts-ignore
-        if (a < b)
-            return -1;
-        // @ts-ignore
-        if (a > b)
-            return 1;
-        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.
+     * 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;
-        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) {
-        // Validation
-        if (typeof element === "number" && Number.isNaN(element)) {
+        // --- 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");
         }
-        const isSet = element instanceof RecursiveSet;
-        const isTup = element instanceof Tuple;
-        const isObject = element !== null && typeof element === 'object' && !isSet && !isTup;
-        if (isObject) {
-            throw new Error("Plain Objects and Arrays are not supported. " +
-                "Use Tuple for sequences or RecursiveSet for nested structures.");
+        // --- 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
-        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;
-        this._tree = this._tree.insert(element, true);
+        }
+        // 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;
+            }
+        }
+        arr.splice(idx, 0, element);
+        this._hashCode = null;
         return this;
     }
     remove(element) {
-        this._tree = this._tree.remove(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;
+        }
+        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._elements = [];
+        this._hashCode = 0;
         return this;
     }
-    // === Set Operations ===
+    clone() {
+        const s = new RecursiveSet();
+        s._elements = this._elements.slice();
+        s._hashCode = this._hashCode;
+        return s;
+    }
     union(other) {
-        const result = this.clone();
-        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();
-        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) {
-        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); });
+        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);
     }
-    /**
-     * Returns the Cartesian product as a set of Tuples.
-     * Uses the Tuple class to ensure structural equality.
-     */
     cartesianProduct(other) {
         const result = new RecursiveSet();
-        for (const x of this) {
-            for (const y of other) {
-                result.add(new Tuple(x, y));
+        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 result;
     }
-    // === Predicates ===
-    has(element) {
-        return this._tree.get(element) !== undefined;
-    }
+    // 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;
-    }
-    // === Utility ===
-    get size() {
-        return this._tree.length;
-    }
-    toSet() {
-        const result = new Set();
-        this._tree.forEach((key) => { result.add(key); });
-        return result;
-    }
-    // Lazy Iterator
-    *[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 if (key instanceof Tuple) {
-                elements.push(key.toString());
-            }
-            else {
-                elements.push(String(key));
-            }
+        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