recursive-set 5.0.2 → 6.0.0

package/dist/esm/index.js

@@ -1,30 +1,64 @@
 /**
  * @module recursive-set
  * High-Performance Recursive Set with "Freeze-on-Hash" semantics.
+ * Version: 6.0.0
  */
-// === HASHING ENGINE (FNV-1a) ===
+// ============================================================================
+// HASHING ENGINE (FNV-1a with DataView & Safe Integer Split)
+// ============================================================================
 const FNV_PRIME = 16777619;
 const FNV_OFFSET = 2166136261;
+// Shared buffer to avoid allocation overhead (reused for all number hashing)
+const floatBuffer = new ArrayBuffer(8);
+const view = new DataView(floatBuffer);
+/**
+ * Hashes a number using FNV-1a.
+ * Handles both safe integers (via high/low split) and floats (via IEEE 754 bits).
+ * Ensures platform consistency by enforcing Little Endian byte order.
+ */
+function hashNumber(val) {
+    // Integer Path: Handle Safe Integers correctly (up to 2^53)
+    if (Number.isSafeInteger(val)) {
+        let h = FNV_OFFSET;
+        const lowU = val >>> 0;
+        const high = ((val - lowU) / 4294967296) | 0;
+        h ^= lowU;
+        h = Math.imul(h, FNV_PRIME);
+        h ^= high;
+        h = Math.imul(h, FNV_PRIME);
+        return h >>> 0;
+    }
+    // Float Path: IEEE 754 Bit Pattern (Little Endian Enforced)
+    view.setFloat64(0, val, true);
+    let h = FNV_OFFSET;
+    const low = view.getInt32(0, true);
+    const high = view.getInt32(4, true);
+    h ^= low;
+    h = Math.imul(h, FNV_PRIME);
+    h ^= high;
+    h = Math.imul(h, FNV_PRIME);
+    return h >>> 0;
+}
 function hashString(str) {
-    let hash = FNV_OFFSET;
+    let h = FNV_OFFSET;
     const len = str.length;
     for (let i = 0; i < len; i++) {
-        hash ^= str.charCodeAt(i);
-        hash = Math.imul(hash, FNV_PRIME);
+        h ^= str.charCodeAt(i);
+        h = Math.imul(h, FNV_PRIME);
     }
-    return hash >>> 0;
+    return h >>> 0;
 }
+/**
+ * Computes a 32-bit hash code for a supported value.
+ * @param val The value to hash (number, string, Tuple, RecursiveSet, or Array)
+ */
 function hashValue(val) {
     if (typeof val === 'string')
         return hashString(val);
-    if (typeof val === 'number') {
-        let hash = FNV_OFFSET;
-        hash ^= (val | 0);
-        hash = Math.imul(hash, FNV_PRIME);
-        return hash >>> 0;
-    }
-    // Fast Path: Objects with cached hash
-    if (val && typeof val === 'object' && 'hashCode' in val) {
+    if (typeof val === 'number')
+        return hashNumber(val);
+    // Strict Fast-Path: Only trust our own Primitives
+    if (val instanceof RecursiveSet || val instanceof Tuple) {
         return val.hashCode;
     }
     if (Array.isArray(val)) {
@@ -38,92 +72,167 @@ function hashValue(val) {
     }
     return 0;
 }
-// === COMPARATOR ===
+// ============================================================================
+// STRICT COMPARATOR (Total Order)
+// ============================================================================
+/**
+ * Determines the sort priority of a type.
+ * Order: number (1) < string (2) < Sequence (3) < Set (4)
+ */
+function getTypeScore(a) {
+    if (typeof a === 'number')
+        return 1;
+    if (typeof a === 'string')
+        return 2;
+    if (Array.isArray(a) || a instanceof Tuple)
+        return 3;
+    if (a instanceof RecursiveSet)
+        return 4;
+    return 0;
+}
+/**
+ * Compares two values for sorting.
+ * Implements a strict total order:
+ * 1. Semantic Type Score (Number < String < Seq < Set)
+ * 2. Hash Code (Short-Circuit)
+ * 3. Deep Structural Comparison
+ */
 function compare(a, b) {
     if (a === b)
         return 0;
-    // 1. Hash Short-Circuit (Optimization)
-    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. Structural Type Check
-    const typeA = typeof a;
-    const typeB = typeof b;
-    if (typeA === 'string' && typeB === 'string')
+    // 1. Semantic Grouping
+    const scoreA = getTypeScore(a);
+    const scoreB = getTypeScore(b);
+    if (scoreA !== scoreB) {
+        return scoreA < scoreB ? -1 : 1;
+    }
+    // 2. PRIMITIVES: Value Sort (Human readable & Fast)
+    if (scoreA === 1)
         return a < b ? -1 : 1;
-    if (typeA === 'number' && typeB === 'number')
+    if (scoreA === 2)
         return a < b ? -1 : 1;
-    const isSetA = a instanceof RecursiveSet;
-    const isSetB = b instanceof RecursiveSet;
-    if (isSetA && isSetB) {
+    // 3. OBJECTS: Hash Optimization (Performance Protection)
+    const ha = hashValue(a);
+    const hb = hashValue(b);
+    if (ha !== hb)
+        return ha < hb ? -1 : 1;
+    // 3. Fallback / Structural Comparison
+    if (scoreA === 4) {
         return a.compare(b);
     }
-    const isSeqA = Array.isArray(a) || a instanceof Tuple;
-    const isSeqB = Array.isArray(b) || b instanceof Tuple;
-    // Sort Order: Primitives (0) < Sequences (1) < Sets (2)
-    if (isSetA !== isSetB || isSeqA !== isSeqB) {
-        const scoreA = isSetA ? 2 : isSeqA ? 1 : 0;
-        const scoreB = isSetB ? 2 : isSeqB ? 1 : 0;
-        return scoreA - scoreB;
+    // Sequence Comparison (Arrays & Tuples)
+    const valA = (a instanceof Tuple) ? a.values : a;
+    const valB = (b instanceof Tuple) ? 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;
     }
-    // 3. Sequence Comparison
-    if (isSeqA && isSeqB) {
-        const valA = (a instanceof Tuple) ? a.values : a;
-        const valB = (b instanceof Tuple) ? 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;
+}
+// ============================================================================
+// VALIDATION
+// ============================================================================
+/**
+ * Validates that an element is of a supported immutable-compatible type.
+ * Throws if the type is mutable (plain object) or unsupported (function, symbol).
+ * @throws {Error} if element type is invalid.
+ */
+function validateType(element) {
+    if (typeof element === 'number') {
+        if (Number.isNaN(element))
+            throw new Error("NaN is not supported");
+        return;
+    }
+    if (typeof element === 'string')
+        return;
+    if (Array.isArray(element)) {
+        for (const item of element)
+            validateType(item);
+        return;
+    }
+    if (typeof element === 'object' && element !== null) {
+        if (element instanceof RecursiveSet || element instanceof Tuple) {
+            return;
         }
-        return 0;
     }
-    return a < b ? -1 : 1;
+    throw new Error("Unsupported Type: Use number, string, Tuple, Array or RecursiveSet.");
 }
-// === CLASSES ===
+// ============================================================================
+// CLASSES
+// ============================================================================
+/**
+ * Immutable Tuple container.
+ * * Guarantees structural immutability by freezing the internal array storage.
+ * Note: Immutability is shallow. If you store mutable Arrays inside a Tuple,
+ * the Tuple logic remains correct, but the content inside the Array might change.
+ * For strict value semantics, use Tuple<Primitive | RecursiveSet | Tuple>.
+ * * @template T The tuple type.
+ */
 export class Tuple {
-    values;
+    #values;
     hashCode;
+    /**
+     * Creates a new Tuple.
+     * @param values Elements of the tuple.
+     */
     constructor(...values) {
-        this.values = values;
-        this.hashCode = hashValue(values);
+        for (const v of values)
+            validateType(v);
+        this.#values = [...values];
+        Object.freeze(this.#values);
+        this.hashCode = hashValue(this.#values);
     }
-    get length() { return this.values.length; }
-    get(i) { return this.values[i]; }
-    *[Symbol.iterator]() { yield* this.values; }
-    toString() { return `(${this.values.join(', ')})`; }
+    /** Returns the read-only backing array. */
+    get values() { return this.#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 mathematical Set with Value Semantics.
+ * * Features:
+ * - **Strict Typing:** Supports number, string, Tuple, Array, RecursiveSet.
+ * - **Sorted Storage:** Elements are internally sorted for O(1) equality checks via hash.
+ * - **Freeze-on-Hash:** Once the hash code is accessed (e.g. when added to another Set),
+ * this Set becomes immutable to prevent hash corruption.
+ * * @template T The type of elements in the set.
+ */
 export class RecursiveSet {
-    _elements;
-    _hashCode = null;
-    _isFrozen = false;
+    #elements = [];
+    #hashCode = null;
+    #isFrozen = false;
+    /**
+     * Exposes the static compare function used internally.
+     */
     static compare(a, b) { return compare(a, b); }
+    /**
+     * Creates a new RecursiveSet.
+     * @param elements Initial elements (will be sorted and deduplicated).
+     */
     constructor(...elements) {
-        if (elements.length === 0) {
-            this._elements = [];
-            this._hashCode = 0;
-        }
-        else {
-            this._elements = elements;
-            this._elements.sort(compare);
-            this._unique();
+        if (elements.length > 0) {
+            for (const el of elements)
+                validateType(el);
+            this.#elements = elements;
+            this.#elements.sort(compare);
+            this.#unique();
         }
     }
-    _checkFrozen(op) {
-        if (this._isFrozen) {
+    #checkFrozen(op) {
+        if (this.#isFrozen) {
             throw new Error(`InvalidOperation: Cannot ${op} a frozen RecursiveSet.\n` +
                 `This Set has been hashed or used in a collection (Value Semantics).\n` +
                 `Use .mutableCopy() to create a modifiable copy.`);
         }
     }
-    _unique() {
-        const arr = this._elements;
+    #unique() {
+        const arr = this.#elements;
         const len = arr.length;
         if (len < 2)
             return;
@@ -136,22 +245,28 @@ export class RecursiveSet {
         arr.length = write;
     }
     /**
-     * Calculates/Caches hash code and FREEZES the set.
+     * Calculates and caches the hash code.
+     * Freezes the set to ensure the hash remains valid.
      */
     get hashCode() {
-        if (this._hashCode !== null)
-            return this._hashCode;
+        if (this.#hashCode !== null)
+            return this.#hashCode;
         let h = 0;
-        const arr = this._elements;
+        const arr = this.#elements;
         const len = arr.length;
         for (let i = 0; i < len; i++) {
-            h = Math.imul(31, h) + hashValue(arr[i]);
+            // Wrap to 32-bit at each step for consistency
+            h = (Math.imul(31, h) + hashValue(arr[i])) | 0;
         }
-        this._hashCode = h | 0;
-        this._isFrozen = true;
-        return this._hashCode;
+        this.#hashCode = h | 0;
+        this.#isFrozen = true;
+        return this.#hashCode;
     }
-    get isFrozen() { return this._isFrozen; }
+    /** Returns true if the set is frozen (hashed). */
+    get isFrozen() { return this.#isFrozen; }
+    /**
+     * Compares this set with another for sorting.
+     */
     compare(other) {
         if (this === other)
             return 0;
@@ -159,8 +274,8 @@ export class RecursiveSet {
         const h2 = other.hashCode;
         if (h1 !== h2)
             return h1 < h2 ? -1 : 1;
-        const arrA = this._elements;
-        const arrB = other._elements;
+        const arrA = this.#elements;
+        const arrB = other.#elements;
         const len = arrA.length;
         if (len !== arrB.length)
             return len - arrB.length;
@@ -171,12 +286,15 @@ export class RecursiveSet {
         }
         return 0;
     }
-    get size() { return this._elements.length; }
-    isEmpty() { return this._elements.length === 0; }
+    get size() { return this.#elements.length; }
+    isEmpty() { return this.#elements.length === 0; }
+    /**
+     * Checks if the set contains the given element.
+     * Uses binary search for sets > 16 elements.
+     */
     has(element) {
-        const arr = this._elements;
+        const arr = this.#elements;
         const len = arr.length;
-        // Linear Scan (Prefetch-friendly for small sets)
         if (len < 16) {
             for (let i = 0; i < len; i++) {
                 if (compare(arr[i], element) === 0)
@@ -184,7 +302,6 @@ export class RecursiveSet {
             }
             return false;
         }
-        // Binary Search
         let low = 0, high = len - 1;
         while (low <= high) {
             const mid = (low + high) >>> 1;
@@ -198,25 +315,21 @@ export class RecursiveSet {
         }
         return false;
     }
+    /**
+     * Adds an element to the set.
+     * Throws if the set is frozen.
+     */
     add(element) {
-        this._checkFrozen('add() to');
-        // Validation (Inlined for Performance)
-        if (typeof element === 'object' && element !== null) {
-            if (!(element instanceof RecursiveSet || element instanceof Tuple || Array.isArray(element))) {
-                throw new Error("Unsupported Type: Use Tuple, Array or RecursiveSet.");
-            }
-        }
-        else if (Number.isNaN(element)) {
-            throw new Error("NaN is not supported");
-        }
-        const arr = this._elements;
+        this.#checkFrozen('add() to');
+        validateType(element);
+        const arr = this.#elements;
         const len = arr.length;
-        // Optimization: Append to end (common in construction)
+        // Optimization: Append to end (common pattern)
         if (len > 0) {
             const lastCmp = compare(arr[len - 1], element);
             if (lastCmp < 0) {
                 arr.push(element);
-                this._hashCode = null;
+                this.#hashCode = null;
                 return this;
             }
             if (lastCmp === 0)
@@ -224,10 +337,10 @@ export class RecursiveSet {
         }
         else {
             arr.push(element);
-            this._hashCode = null;
+            this.#hashCode = null;
             return this;
         }
-        // Small Array Strategy
+        // Small Array: Linear Insert
         if (len < 16) {
             for (let i = 0; i < len; i++) {
                 const cmp = compare(arr[i], element);
@@ -235,14 +348,14 @@ export class RecursiveSet {
                     return this;
                 if (cmp > 0) {
                     arr.splice(i, 0, element);
-                    this._hashCode = null;
+                    this.#hashCode = null;
                     return this;
                 }
             }
-            arr.push(element); // Should be unreachable given append check, but safe fallback
+            arr.push(element);
             return this;
         }
-        // Large Array Strategy
+        // Large Array: Binary Search Insert
         let low = 0, high = len - 1, idx = 0;
         while (low <= high) {
             const mid = (low + high) >>> 1;
@@ -259,18 +372,22 @@ export class RecursiveSet {
             }
         }
         arr.splice(idx, 0, element);
-        this._hashCode = null;
+        this.#hashCode = null;
         return this;
     }
+    /**
+     * Removes an element from the set.
+     * Throws if the set is frozen.
+     */
     remove(element) {
-        this._checkFrozen('remove() from');
-        const arr = this._elements;
+        this.#checkFrozen('remove() from');
+        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;
+                    this.#hashCode = null;
                     return this;
                 }
             }
@@ -282,7 +399,7 @@ export class RecursiveSet {
             const cmp = compare(arr[mid], element);
             if (cmp === 0) {
                 arr.splice(mid, 1);
-                this._hashCode = null;
+                this.#hashCode = null;
                 return this;
             }
             if (cmp < 0)
@@ -293,21 +410,25 @@ export class RecursiveSet {
         return this;
     }
     clear() {
-        this._checkFrozen('clear()');
-        this._elements = [];
-        this._hashCode = 0;
+        this.#checkFrozen('clear()');
+        this.#elements = [];
+        this.#hashCode = 0;
         return this;
     }
+    /**
+     * Creates a mutable shallow copy of this set.
+     * Useful for modifying a set after it has been frozen.
+     */
     mutableCopy() {
         const s = new RecursiveSet();
-        s._elements = this._elements.slice();
+        s.#elements = this.#elements.slice();
         return s;
     }
     clone() { return this.mutableCopy(); }
     union(other) {
         const s = new RecursiveSet();
-        const arrA = this._elements;
-        const arrB = other._elements;
+        const arrA = this.#elements;
+        const arrB = other.#elements;
         if (arrA.length === 0)
             return other.clone();
         if (arrB.length === 0)
@@ -330,13 +451,13 @@ export class RecursiveSet {
             res.push(arrA[i++]);
         while (j < lenB)
             res.push(arrB[j++]);
-        s._elements = res;
+        s.#elements = res;
         return s;
     }
     intersection(other) {
         const s = new RecursiveSet();
-        const arrA = this._elements;
-        const arrB = other._elements;
+        const arrA = this.#elements;
+        const arrB = other.#elements;
         const res = [];
         let i = 0, j = 0;
         const lenA = arrA.length, lenB = arrB.length;
@@ -351,13 +472,13 @@ export class RecursiveSet {
                 j++;
             }
         }
-        s._elements = res;
+        s.#elements = res;
         return s;
     }
     difference(other) {
         const s = new RecursiveSet();
-        const arrA = this._elements;
-        const arrB = other._elements;
+        const arrA = this.#elements;
+        const arrB = other.#elements;
         const res = [];
         let i = 0, j = 0;
         const lenA = arrA.length, lenB = arrB.length;
@@ -374,13 +495,13 @@ export class RecursiveSet {
         }
         while (i < lenA)
             res.push(arrA[i++]);
-        s._elements = res;
+        s.#elements = res;
         return s;
     }
     symmetricDifference(other) {
         const s = new RecursiveSet();
-        const arrA = this._elements;
-        const arrB = other._elements;
+        const arrA = this.#elements;
+        const arrB = other.#elements;
         const res = [];
         let i = 0, j = 0;
         const lenA = arrA.length, lenB = arrB.length;
@@ -399,7 +520,7 @@ export class RecursiveSet {
             res.push(arrA[i++]);
         while (j < lenB)
             res.push(arrB[j++]);
-        s._elements = res;
+        s.#elements = res;
         return s;
     }
     powerset() {
@@ -412,7 +533,7 @@ export class RecursiveSet {
             const subset = new RecursiveSet();
             for (let j = 0; j < n; j++) {
                 if (i & (1 << j))
-                    subset._elements.push(this._elements[j]);
+                    subset.#elements.push(this.#elements[j]);
             }
             subsets.push(subset);
         }
@@ -420,20 +541,23 @@ export class RecursiveSet {
     }
     cartesianProduct(other) {
         const result = new RecursiveSet();
-        const arrA = this._elements;
-        const arrB = other._elements;
+        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));
+                result.#elements.push(new Tuple(x, y));
             }
         }
+        // Hash ordering is not monotonic, so we must resort
+        result.#elements.sort(compare);
+        result.#unique();
         return result;
     }
     isSubset(other) {
         if (this.size > other.size)
             return false;
         let i = 0, j = 0;
-        const arrA = this._elements, arrB = other._elements;
+        const arrA = this.#elements, arrB = other.#elements;
         while (i < arrA.length && j < arrB.length) {
             const cmp = compare(arrA[i], arrB[j]);
             if (cmp < 0)
@@ -450,12 +574,12 @@ export class RecursiveSet {
     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; }
+    toSet() { return new Set(this.#elements); }
+    *[Symbol.iterator]() { yield* this.#elements; }
     toString() {
         if (this.isEmpty())
             return "∅";
-        const elementsStr = this._elements.map(el => {
+        const elementsStr = this.#elements.map(el => {
             if (Array.isArray(el))
                 return `[${el.join(', ')}]`;
             return String(el);
@@ -464,6 +588,9 @@ export class RecursiveSet {
     }
     [Symbol.for('nodejs.util.inspect.custom')]() { return this.toString(); }
 }
+// ============================================================================
+// EXPORTS
+// ============================================================================
 export function emptySet() { return new RecursiveSet(); }
 export function singleton(element) { return new RecursiveSet(element); }
 export function fromIterable(iterable) { return new RecursiveSet(...iterable); }