recursive-set 5.0.2 → 6.0.0

package/README.md

@@ -1,35 +1,19 @@
 # RecursiveSet
 
-> **High-Performance ZFC Set Implementation for TypeScript**
-> 
-> Mutable, strictly typed, and optimized for cache locality.
+High-performance, strictly typed set implementation for TypeScript with **value semantics** (structural equality) and controlled mutability via “freeze-on-hash”.
 
-[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
-[![npm version](https://img.shields.io/npm/v/recursive-set.svg)](https://www.npmjs.com/package/recursive-set)
+## Overview
 
----
-
-## 🚀 What is this?
-
-A mathematical set implementation designed for **Theoretical Computer Science**, **SAT-Solvers**, and **Graph Theory**. Unlike native JavaScript `Set`, `RecursiveSet` enforces **Structural Equality** (ZFC semantics) and supports deep nesting.
-
-**v5.0.0 Update:** Now featuring **"Freeze-on-Hash"** lifecycle management.
-*   **Safety First**: Sets automatically become **immutable** (frozen) once used as a key or member of another set. No more corrupted hash codes!
-*   **High Performance**: Backed by **Sorted Arrays** and FNV-1a hashing. 5x - 10x faster than tree-based implementations for typical *N* < 1000.
-*   **O(1) Equality Checks**: Aggressive caching allows for instant comparisons of deep structures.
+`RecursiveSet` is a mathematical set designed for workloads in theoretical computer science (e.g., SAT solvers, graph algorithms, ZFC-style constructions) where deep nesting and structural equality matter (e.g., `{1,2} = {2,1}`).
 
----
-
-## Features
+Key design points:
 
-*   **🔢 Strict Structural Equality:** `{1, 2}` is equal to `{2, 1}`.
-*   **❄️ Freeze-on-Hash:** Mutable during construction, immutable during usage. Prevents subtle reference bugs.
-*   **📦 Deeply Recursive:** Sets can contain Sets. Ideal for Power Sets.
-*   **📐 Tuples & Arrays:** Native support for `Tuple` class or standard JS Arrays `[a, b]` as elements.
-*   **🔒 Type Safe:** Fully strict TypeScript implementation. No `any` casts.
-*   **🛡️ Deterministic:** Hashing is order-independent for Sets and order-dependent for Sequences.
-
----
+- Structural equality (ZFC-like semantics) for nested sets and sequences.
+- Mutable during construction; becomes immutable once hashed (“freeze-on-hash”).
+- Sorted-array backing for good cache locality on small to medium `N`.
+- Deterministic hashing:
+  - Numbers use safe-integer splitting and IEEE-754 bit hashing.
+  - Float hashing enforces little-endian byte order via `DataView` for platform consistency.
 
 ## Installation
 
@@ -64,101 +48,102 @@ console.log(partition.toString()); // {{q0, q1}}
 
 ### 2. The Lifecycle (Mutable -> Frozen)
 
-**New in v5:** To ensure mathematical correctness, a set cannot be modified once it has been hashed (e.g., added to another set).
+Accessing `hashCode` (directly or indirectly by inserting into another set) freezes the set to prevent hash corruption.
 
 ```typescript
 const A = new RecursiveSet(1, 2);
-const B = new RecursiveSet(A); 
-// B hashes A to store it. 
-// A is now FROZEN to ensure B's integrity.
+const B = new RecursiveSet(A); // hashing B may hash A -> A becomes frozen
 
 console.log(B.has(A)); // true
 
 try {
-    A.add(3); // 💥 Throws Error: Cannot add() to a frozen RecursiveSet
-} catch (e) {
-    console.log("A is immutable now!");
+A.add(3); // throws
+} catch {
+console.log("A is frozen and cannot be mutated.");
 }
 
-// Fix: Create a mutable copy ("Forking")
+// “Fork” for mutation
 const C = A.mutableCopy();
-C.add(3); // Works!
+C.add(3);
 ```
 
 ---
 
-## API Reference
+## Supported element types
 
-### Constructor
+To keep value semantics predictable and prevent accidental mutation via arbitrary objects, `RecursiveSet` validates inputs and supports:
 
-```typescript
-// Create empty or with initial elements
-// Elements are automatically sorted and deduplicated.
-new RecursiveSet<T>(...elements: T[])
-```
+- `number` (excluding `NaN`)
+- `string`
+- `Tuple`
+- plain `Array` (treated as an ordered sequence)
+- `RecursiveSet`
 
+## Tuple vs Array
 
-### Methods
+- `Tuple` is an immutable container: it makes a defensive copy and freezes its internal storage via `Object.freeze()` (shallow immutability).
+- Plain `Array` values are supported for performance and convenience, but they are not frozen by the library.
 
-**Lifecycle Management:**
-*   `mutableCopy(): RecursiveSet<T>` – Creates a fresh, mutable clone of the set (O(N)). Use this if you need to modify a frozen set.
-*   `clone(): RecursiveSet<T>` – Alias for mutableCopy.
+Recommendation for SAT / hot loops: represent frequently compared “small composite values” as `Tuple` to benefit from cached hashing and immutability.
 
-**Mutation:**
-*   `add(element: T): this` – Insert element (O(N) worst case, O(1) append).
-*   `remove(element: T): this` – Remove element.
-*   `clear(): this` – Reset set.
+---
 
-**Set Operations (Immutable results):**
-*   `union(other: RecursiveSet<T>): RecursiveSet<T>` – $A \cup B$
-*   `intersection(other: RecursiveSet<T>): RecursiveSet<T>` – $A \cap B$
-*   `difference(other: RecursiveSet<T>): RecursiveSet<T>` – $A \setminus B$
-*   `symmetricDifference(other: RecursiveSet<T>): RecursiveSet<T>` – $A \triangle B$
-*   `powerset(): RecursiveSet<RecursiveSet<T>>` – $\mathcal{P}(A)$
-*   `cartesianProduct<U>(other: RecursiveSet<U>): RecursiveSet<Tuple<[T, U]>>` – $A \times B$
+## API (selected)
 
-**Predicates (Fast):**
-*   `has(element: T): boolean` – **O(log N)** lookup (Binary Search).
-*   `equals(other: RecursiveSet<T>): boolean` – **O(1)** via Hash-Cache (usually).
-*   `isSubset(other: RecursiveSet<T>): boolean` – Check if $A \subseteq B$.
-*   `isSuperset(other: RecursiveSet<T>): boolean` – Check if $A \supseteq B$.
-*   `isEmpty(): boolean` – Check if $|A| = 0$.
+### Construction
 
-**Properties:**
-*   `size: number` – Cardinality.
-*   `hashCode: number` – The cached hash. Accessing this property freezes the set.
-*   `isFrozen: boolean` – Check if the set is read-only.
+```typescript
+new RecursiveSet<T>(...elements: T[])
+```
+Elements are sorted and deduplicated on construction.
 
----
+### Mutation (only while unfrozen)
 
-## Performance Notes
+- `add(element: T): this`
+- `remove(element: T): this`
+- `clear(): this`
 
-**Why Sorted Arrays?**
-For sets with $N < 1000$ (common in logic puzzles, N-Queens, graphs), the overhead of allocating tree nodes (v2/v3) dominates runtime. Sorted Arrays exploit **CPU Cache Lines**.
+### Copying
 
-| Operation | Complexity | Real World (Small N) |
-| :--- | :--- | :--- |
-| **Lookup** | $O(\log N)$ | 🚀 Instant |
-| **Equality** | $O(N)$ / $O(1)$* | ⚡ Instant (Hash Match) |
-| **Insert** | $O(N)$ | Fast (Native `splice` / `memmove`) |
-| **Iteration** | $O(N)$ | 🚀 Native Array Speed |
+- `mutableCopy(): RecursiveSet<T>` – mutable shallow copy (use after freezing)
+- `clone(): RecursiveSet<T>` – alias for `mutableCopy()`
 
-*\*Equality is O(1) if hashes differ (99% case), O(N) if hash collision occurs.*
+### Set operations (return new sets)
 
----
+- `union(other): RecursiveSet<T>`
+- `intersection(other): RecursiveSet<T>`
+- `difference(other): RecursiveSet<T>`
+- `symmetricDifference(other): RecursiveSet<T>`
+- `powerset(): RecursiveSet<RecursiveSet<T>>` (guarded; throws if too large)
+- `cartesianProduct<U>(other): RecursiveSet<Tuple<[T, U]>>`
 
-## Breaking Changes in v5.0
+### Predicates & properties
 
-1.  **Freeze-on-Hash Semantics:** To guarantee mathematical correctness, sets now transition to an **immutable state** once their `hashCode` is computed (which happens automatically when added to another `RecursiveSet` or used as a Map key).
-    *   *Old Behavior:* Modifying a hashed set was possible but resulted in corrupted hash codes and lookup failures.
-    *   *New Behavior:* Calling `add()`, `remove()` or `clear()` on a hashed set throws an `Error`.
-    *   *Migration:* Use `mutableCopy()` to create a modifiable clone if you need to evolve a state that has already been stored.
+- `has(element: T): boolean` – binary search for larger sets
+- `equals(other: RecursiveSet<T>): boolean`
+- `isSubset(other): boolean`
+- `isSuperset(other): boolean`
+- `isEmpty(): boolean`
+- `size: number`
+- `hashCode: number` – computes and caches hash; freezes the set
+- `isFrozen: boolean`
 
----
+## Determinism & ordering rules
 
-## Contributing
+The internal ordering is deterministic across platforms:
+
+- Type order: `number` < `string` < sequence (`Array`/`Tuple`) < `RecursiveSet`.
+- Sequences compare lexicographically (then by length).
+- Sets compare by cached hash first, then by structural comparison on collision.
+
+## Breaking changes in v6
+
+- Internal storage uses private class fields (no external access to internal arrays).
+- Hashing uses `DataView` little-endian float hashing; hashes are not compatible with older versions.
+- `Tuple` is immutable via defensive copy + `Object.freeze()` (shallow).
+- Comparator type ordering is now deterministic: number < string < sequence < set.
 
-Contributions are welcome!
+## Contributing
 
 ```bash
 git clone https://github.com/cstrerath/recursive-set.git
@@ -170,17 +155,7 @@ npx tsx test/nqueens.ts
 
 ---
 
-## License
-
-MIT License  
-© 2025 Christian Strerath
-
-See [LICENSE](LICENSE) for details.
 
----
-
-## Acknowledgments
+## License
 
-Inspired by:
-* Zermelo-Fraenkel set theory (ZFC)
-* Formal Language Theory requirements
+MIT License © 2025 Christian Strerath. See `LICENSE`.