recursive-set 2.2.1 → 4.0.0

package/README.md

@@ -1,60 +1,65 @@
 # RecursiveSet
 
-> Mutable, recursive set implementation for TypeScript – inspired by Cantor's and ZFC set theory.
-
-Supports arbitrary nesting, detects cycles (Foundation axiom), and includes all classic set operations (union, intersection, difference, powerset etc.).
+> **High-Performance ZFC Set Implementation for TypeScript**
+> 
+> Mutable, strictly typed, and optimized for cache locality.
 
 [![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)
 
 ---
 
-## Features
+## 🚀 What is this?
 
-**Mutable, recursive sets** with arbitrary depth  
-**Extensional equality** (two sets are equal iff their elements are equal)  
-**Cycle detection** (Foundation Axiom): prevents self-containing sets  
-**Copy-on-Write**: O(1) cloning via structural sharing  
-**Classic set operations**: union, intersection, difference, symmetric difference  
-**Power set and Cartesian product**  
-**TypeScript generics**: works with strings, numbers, objects, states, even sets of sets  
-**Ready for FSM**, mathematical, symbolic and practical use cases
+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.
 
----
+**v4.0.0 Update:** Now powered by **Sorted Arrays** instead of Red-Black Trees.
+*   **5x-10x Faster** than v3.0 (cache locality vs. pointer chasing).
+*   **O(1) Equality Checks** via aggressive hash caching.
+*   **Native Array Support** included.
 
-## Implementation Details
+---
 
-This library enforces strict **ZFC Set Theory** semantics, differing from native JavaScript `Set`s:
+## Features
 
-- **Extensionality:** Two sets are considered equal if they contain the same elements, regardless of object reference identity.
-  - Example: `new RecursiveSet(1).equals(new RecursiveSet(1))` is `true`.
-  - Native `Set` would treat them as distinct objects.
-- **Foundation Axiom:** The library performs cycle detection to prevent sets from containing themselves (recursively).
-- **NaN Handling:** In strict ZFC semantics, `NaN` is not a valid element. Adding `NaN` will explicitly throw an error.
-- **Performance:** Internally powered by **Functional Red-Black Trees** (via `functional-red-black-tree`).
-  - Operations like insertion, deletion, and lookup are **O(log n)**.
-  - **Cloning is O(1)** (Copy-on-Write), making it ideal for backtracking algorithms.
+*   **🔢 Strict Structural Equality:** `{1, 2}` is equal to `{2, 1}`.
+*   **📦 Deeply Recursive:** Sets can contain Sets. Ideal for Power Sets.
+*   **⚡ High Performance:** Optimized for V8 (Chrome/Node) using flat memory layouts and binary search.
+*   **📐 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.
 
 ---
 
 ## Installation
 
-```
+```bash
 npm install recursive-set
 ```
 
 ---
 ## Quickstart
-```
-import { RecursiveSet } from "recursive-set";
+```typescript
+import { RecursiveSet, Tuple } from "recursive-set";
+
+// 1. Sets of primitives
+const states = new RecursiveSet<string>();
+states.add("q0").add("q1");
 
-const q0 = "q0", q1 = "q1";
-const eqClass = new RecursiveSet(q0, q1);    // {q0, q1}
-const classes = new RecursiveSet(eqClass);
+// 2. Sets of Sets (Partitioning)
+// Recursion requires explicit typing!
+const partition = new RecursiveSet<RecursiveSet<string>>();
+partition.add(states); // {{q0, q1}}
 
-classes.add(new RecursiveSet("q2", "q3"));   // {{q0, q1}, {q2, q3}}
+// 3. Tuples (Ordered Pairs / Edges)
+const edge = new Tuple("q0", "q1"); // (q0, q1)
+// or simply: const edge = ["q0", "q1"];
 
-console.log(classes.toString());             // {{q0, q1}, {q2, q3}}
+const transitions = new RecursiveSet<Tuple<[string, string]>>();
+transitions.add(edge);
+
+console.log(partition.toString()); // {{q0, q1}}
+console.log(transitions.toString()); // {(q0, q1)}
 ```
 
 ---
@@ -63,136 +68,79 @@ console.log(classes.toString());             // {{q0, q1}, {q2, q3}}
 
 ### Constructor
 
-```
-new RecursiveSet<T>(...elements: Array<T | RecursiveSet<T>>)
+```typescript
+// Create empty or with initial elements
+// Elements are automatically sorted and deduplicated.
+new RecursiveSet<T>(...elements: T[])
 ```
 
+
 ### Methods
 
 **Mutation:**
-- `add(element: T | RecursiveSet<T>): this` – Add element (chainable). **Throws if element is NaN.**
-- `remove(element: T | RecursiveSet<T>): this` – Remove element (chainable)
-- `clear(): this` – Remove all elements (chainable)
-
-**Snapshot:**
-- `clone(): RecursiveSet<T>` – Creates a shallow copy in **O(1)** time (Copy-on-Write).
-
-**Set Operations:**
-- `union(other: RecursiveSet<T>): RecursiveSet<T>` – A ∪ B
-- `intersection(other: RecursiveSet<T>): RecursiveSet<T>` – A ∩ B
-- `difference(other: RecursiveSet<T>): RecursiveSet<T>` – A \ B
-- `symmetricDifference(other: RecursiveSet<T>): RecursiveSet<T>` – A △ B
-
-**Advanced Operations:**
-- `powerset(): RecursiveSet<RecursiveSet<T>>` – 𝒫(A)
-- `cartesianProduct<U>(other: RecursiveSet<U>): RecursiveSet<RecursiveSet<T | U>>` – A × B
-
-**Predicates:**
-- `has(element: T | RecursiveSet<T>): boolean` – Check membership
-- `isSubset(other: RecursiveSet<T>): boolean` – Check if ⊆
-- `isSuperset(other: RecursiveSet<T>): boolean` – Check if ⊇
-- `equals(other: RecursiveSet<T>): boolean` – Structural equality
-- `isEmpty(): boolean` – Check if set is empty
+*   `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$
+
+**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$.
 
 **Properties:**
-- `size: number` – Cardinality |A|
-- `toString(): string` – Pretty print with ∅ and {}
+*   `size: number` – Cardinality.
+*   `hashCode: number` – The cached hash of the set.
 
 ---
 
-## Examples
-
-### Basic Usage
-
-```
-const s1 = new RecursiveSet(1, 2, 3);
-const s2 = new RecursiveSet(2, 3, 4);
-
-console.log(s1.union(s2));        // {1, 2, 3, 4}
-console.log(s1.intersection(s2)); // {2, 3}
-console.log(s1.difference(s2));   // {1}
-```
-
-### Backtracking with O(1) Clone
+## Performance Notes (v4.0)
 
-```
-const state = new RecursiveSet("init");
-// ... perform some operations ...
+**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**.
 
-// Create a checkpoint (O(1))
-const checkpoint = state.clone();
-
-state.add("newState");
-// If this path fails, simply revert:
-// state = checkpoint; (conceptually)
-```
+| 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 |
 
-### Power Set
-
-```
-const set = new RecursiveSet(1, 2);
-const power = set.powerset();
-
-console.log(power.toString()); // {∅, {1}, {2}, {1, 2}}
-```
-
-### Strictness: NaN and Cycles
-
-```
-const s = new RecursiveSet(1, 2);
-
-// Cycle Detection
-try {
-s.add(s);
-} catch (e) {
-console.error(e.message); // "Foundation axiom violated..."
-}
-
-// NaN Rejection
-try {
-s.add(NaN);
-} catch (e) {
-console.error(e.message); // "NaN is not supported..."
-}
-```
+*\*Equality is O(1) if hashes differ (99% case), O(N) if hash collision occurs.*
 
 ---
 
-## Use Cases
+## Breaking Changes in v4.0
 
-- **Finite State Machine (FSM) minimization**: Equivalence classes of states
-- **Set theory algorithms**: Implement mathematical proofs and algorithms
-- **Graph algorithms**: Represent node sets and partitions
-- **Compiler design**: Symbol tables, scope analysis
-- **Type systems**: Type inference and unification
+1.  **Engine Switch (Array Backend):** Iterators are now **live**. Modifying the set while iterating over it will reflect changes immediately (Standard JS Array behavior). In v3 (RBT), iterators were snapshots.
+2.  **Arrays Supported:** Adding `[1, 2]` is now natively supported and treated as a `Tuple`.
+3.  **Strict Generics (Maintained from v3):** `add()` requires explicit generic types for recursion.
+4.  **Plain Objects Rejected (Maintained from v3):** `{a: 1}` throws an Error. Use `Tuple` or `RecursiveSet`.
 
 ---
 
-## Development
+## Contributing
 
-```
-# Clone repository
-git clone https://github.com/cstrerath/recursive-set.git
-cd recursive-set
+Contributions are welcome!
 
-# Install dependencies
+```bash
+git clone https://github.com/cstrerath/recursive-set.git
 npm install
-
-# Build
 npm run build
-
-# Run tests
-npx tsx test.ts
+npx tsx test/test.ts
 ```
 
 ---
 
-## Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.
-
----
-
 ## License
 
 MIT License  
@@ -205,7 +153,5 @@ See [LICENSE](LICENSE) for details.
 ## Acknowledgments
 
 Inspired by:
-- Cantor's set theory
-- Zermelo-Fraenkel set theory with the Axiom of Choice (ZFC)
-- Practical needs in FSM algorithms and formal language theory
-- Powered by [functional-red-black-tree](https://github.com/mikolalysenko/functional-red-black-tree) for O(log n) persistence
+* Zermelo-Fraenkel set theory (ZFC)
+* Formal Language Theory requirements