recursive-set 5.0.3 → 7.0.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Christian Strerath
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+MIT License
+
+Copyright (c) 2025 Christian Strerath
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.

package/README.md

@@ -1,186 +1,207 @@
-# RecursiveSet
-
-> **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)
-
----
-
-## 🚀 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.
-
----
-
-## Features
-
-*   **🔢 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.
-
----
-
-## Installation
-
-```bash
-npm install recursive-set
-```
-
----
-## Quickstart
-
-### 1. Basic Usage
-```typescript
-import { RecursiveSet, Tuple } from "recursive-set";
-
-// Sets of primitives
-const states = new RecursiveSet<string>();
-states.add("q0").add("q1");
-
-// Sets of Sets (Partitioning)
-const partition = new RecursiveSet<RecursiveSet<string>>();
-partition.add(states); // {{q0, q1}}
-
-// Tuples (Ordered Pairs / Edges)
-const edge = new Tuple("q0", "q1"); 
-// or simply: const edge = ["q0", "q1"];
-
-const transitions = new RecursiveSet<Tuple<[string, string]>>();
-transitions.add(edge);
-
-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).
-
-```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.
-
-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!");
-}
-
-// Fix: Create a mutable copy ("Forking")
-const C = A.mutableCopy();
-C.add(3); // Works!
-```
-
----
-
-## API Reference
-
-### Constructor
-
-```typescript
-// Create empty or with initial elements
-// Elements are automatically sorted and deduplicated.
-new RecursiveSet<T>(...elements: T[])
-```
-
-
-### Methods
-
-**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.
-
-**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$
-
-**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.
-*   `hashCode: number` – The cached hash. Accessing this property freezes the set.
-*   `isFrozen: boolean` – Check if the set is read-only.
-
----
-
-## Performance Notes
-
-**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**.
-
-| 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 |
-
-*\*Equality is O(1) if hashes differ (99% case), O(N) if hash collision occurs.*
-
----
-
-## Breaking Changes in v5.0
-
-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.
-
----
-
-## Contributing
-
-Contributions are welcome!
-
-```bash
-git clone https://github.com/cstrerath/recursive-set.git
-npm install
-npm run build
-npx tsx test/test.ts
-npx tsx test/nqueens.ts
-```
-
----
-
-## License
-
-MIT License  
-© 2025 Christian Strerath
-
-See [LICENSE](LICENSE) for details.
-
----
-
-## Acknowledgments
-
-Inspired by:
-* Zermelo-Fraenkel set theory (ZFC)
-* Formal Language Theory requirements
+# RecursiveSet
+
+[![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)
+
+High-performance set implementation for TypeScript with **value semantics** (structural equality) and controlled mutability via “freeze-on-hash”.
+
+## Overview
+
+`RecursiveSet` is a mathematical set designed for workloads in theoretical computer science (SAT solvers, graph algorithms, ZFC-style constructions) where deep nesting and structural equality matter (e.g., `{1,2} = {2,1}`).
+
+Key design points:
+
+- 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`.
+- Bulk loading and merge-scan set operations for speed.
+
+## Installation
+
+```bash
+npm install recursive-set
+```
+
+
+## Quickstart
+
+### Efficient Construction (Bulk Loading)
+
+Instead of adding elements one by one, use `fromArray` for maximum performance:
+
+```ts
+import { RecursiveSet, Tuple } from "recursive-set";
+
+// Fast: Bulk load sorts and deduplicates in one go
+const states = RecursiveSet.fromArray(["q0", "q1", "q2"]);
+
+// Sets of Sets (partitioning)
+const partition = new RecursiveSet<RecursiveSet<string>>();
+partition.add(states); // {{q0, q1, q2}}
+
+console.log(partition.toString()); // {{q0, q1, q2}}
+```
+
+
+### Working with Tuples \& Structures
+
+```ts
+// Tuples (ordered pairs / edges) represent structural values
+// They are immutable and cached by default.
+const edge = new Tuple("q0", "q1");
+
+const transitions = new RecursiveSet<Tuple<[string, string]>>();
+transitions.add(edge);
+```
+
+
+### Lifecycle (mutable → frozen)
+
+Accessing `hashCode` freezes the set to prevent hash corruption.
+
+```ts
+const A = new RecursiveSet(1, 2);
+const B = new RecursiveSet(A); // hashing B may hash A -> A becomes frozen
+
+console.log(B.has(A)); // true
+
+try {
+  A.add(3); // throws after A is frozen
+} catch {
+  console.log("A is frozen and cannot be mutated.");
+}
+
+// “Fork” for mutation
+const C = A.mutableCopy();
+C.add(3);
+```
+
+
+## Contracts
+
+This library optimizes for raw throughput. Using it correctly requires strict adherence to these rules:
+
+1. **Finite numbers only:** Do not insert `NaN`, `Infinity`, or `-Infinity`. Comparison logic uses fast arithmetic (`a - b`).
+2. **No mutation:** Do not mutate arrays/tuples/objects after insertion.
+3. **Type consistency:** Avoid mixing distinct structure types (e.g., `Array` vs `Tuple`) in the same set for the same logical role, as hash-collision edge cases may treat them as equal for performance reasons.
+
+Violating the contract can break sorted order invariants, hashing assumptions, and equality semantics (garbage in → garbage out).
+
+### Freeze-on-hash rule
+
+- A set is mutable until `hashCode` is accessed.
+- After hashing, mutation methods throw; use `mutableCopy()` to continue editing.
+
+
+### Tuple vs Array
+
+- `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 as ordered sequences, but they are not frozen by the library.
+
+**Recommendation:** For hot loops (like SAT solvers), represent frequently compared “small composite values” as `Tuple` to benefit from cached hashing and immutability.
+
+## API
+
+### Types
+
+```ts
+export type Primitive = number | string;
+export type Value =
+  | Primitive
+  | RecursiveSet<any>
+  | Tuple<any>
+  | ReadonlyArray<Value>;
+```
+
+
+### Construction
+
+```ts
+new RecursiveSet<T>(...elements: T[])
+```
+
+Elements are sorted and deduplicated on construction.
+
+### Bulk loading
+
+```ts
+RecursiveSet.fromArray<T>(elements: T[]): RecursiveSet<T>
+```
+
+Sorts once and deduplicates (typically much faster than many `.add()` calls).
+
+### Unsafe creation
+
+```ts
+RecursiveSet.fromSortedUnsafe<T>(sortedUnique: T[]): RecursiveSet<T>
+```
+
+**Trusted bypass:** Assumes the input array is already strictly sorted (by internal `compare`) and contains no duplicates. Use only when you can guarantee invariants externally.
+
+### Mutation (only while unfrozen)
+
+- `add(element: T): this`
+- `remove(element: T): this`
+- `clear(): this`
+
+
+### Copying
+
+- `mutableCopy(): RecursiveSet<T>` – mutable shallow copy (use after freezing)
+- `clone(): RecursiveSet<T>` – alias for `mutableCopy()`
+
+
+### Set operations (return new sets)
+
+All operations below return new `RecursiveSet` instances:
+
+- `union(other): RecursiveSet<T | U>`
+- `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]>>`
+
+
+### Predicates \& properties
+
+- `has(element: T): boolean`
+- `equals(other: RecursiveSet<Value>): boolean`
+- `compare(other: RecursiveSet<Value>): number`
+- `isSubset(other): boolean`
+- `isSuperset(other): boolean`
+- `isEmpty(): boolean`
+- `size: number`
+- `hashCode: number` – computes and caches hash; freezes the set
+- `isFrozen: boolean`
+
+
+### Ordering rules
+
+Internal ordering is deterministic by design:
+
+- Type order: `number` < `string` < sequence (`Array`/`Tuple`) < `RecursiveSet`.
+- Sequences compare by length first, then lexicographically element-by-element.
+- Sets compare by cached hash first, then by structural comparison on collision.
+
+
+## Credits
+
+This library was developed as a student research project under the supervision of **[Karl Stroetmann](https://github.com/karlstroetmann/)**.
+
+Special thanks for his architectural guidance towards homogeneous sets and for contributing the "Merge Scan" & "Bulk Loading" optimization concepts that form the high-performance core of this engine.
+
+## Contributing
+
+```bash
+git clone https://github.com/cstrerath/recursive-set.git
+npm install
+npm run build
+npx tsx test/test.ts
+npx tsx test/nqueens.ts
+```
+
+
+## License
+
+MIT License © 2025 Christian Strerath. See `LICENSE`