recursive-set 7.0.0 → 8.0.0

package/README.md

@@ -3,18 +3,18 @@
 [![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”.
+High-performance collection library for TypeScript supporting **value semantics** (deep equality) and recursive structures. Version 8 introduces a new hash-based architecture optimized for high-throughput workloads like SAT solvers and graph algorithms.
 
 ## 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}`).
+`RecursiveSet` provides mathematical sets and maps where equality is determined by structure/content rather than object reference (e.g., `{1, 2}` is equal to `{2, 1}`).
 
-Key design points:
+**Key Architectural Features:**
 
-- 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.
+- **Open Addressing:** Uses linear probing with a load factor of 0.75 for cache-efficient lookups.
+- **Backshift Deletion:** Maintains probe chain integrity without "tombstones," preventing performance degradation over time.
+- **Zero-Allocation Hashing:** Uses static buffers and raw bitwise operations to hash numbers without triggering the Garbage Collector.
+- **Structure of Arrays (SoA):** Data is stored in flat arrays to maximize CPU cache locality.
 
 ## Installation
 
@@ -22,186 +22,157 @@ Key design points:
 npm install recursive-set
 ```
 
-
 ## Quickstart
 
-### Efficient Construction (Bulk Loading)
+### Working with Sets
 
-Instead of adding elements one by one, use `fromArray` for maximum performance:
+Sets automatically deduplicate elements based on their value or structure.
 
 ```ts
-import { RecursiveSet, Tuple } from "recursive-set";
+import { RecursiveSet } from "recursive-set";
+
+// Primitive values
+const numbers = new RecursiveSet(1, 2, 3);
+numbers.add(1); // No effect, 1 is already present
 
-// Fast: Bulk load sorts and deduplicates in one go
-const states = RecursiveSet.fromArray(["q0", "q1", "q2"]);
+// Recursive structures (Sets of Sets)
+const setA = new RecursiveSet(1, 2);
+const setB = new RecursiveSet(2, 1);
+const metaSet = new RecursiveSet<RecursiveSet<number>>();
 
-// Sets of Sets (partitioning)
-const partition = new RecursiveSet<RecursiveSet<string>>();
-partition.add(states); // {{q0, q1, q2}}
+metaSet.add(setA);
+metaSet.add(setB);
 
-console.log(partition.toString()); // {{q0, q1, q2}}
+console.log(metaSet.size); // 1, because setA equals setB
 ```
 
+### Working with Maps
 
-### Working with Tuples \& Structures
+`RecursiveMap` allows using complex objects (like Tuples or Sets) as keys.
 
 ```ts
-// Tuples (ordered pairs / edges) represent structural values
-// They are immutable and cached by default.
+import { RecursiveMap, Tuple } from "recursive-set";
+
+const transitions = new RecursiveMap<Tuple<[string, string]>, number>();
 const edge = new Tuple("q0", "q1");
 
-const transitions = new RecursiveSet<Tuple<[string, string]>>();
-transitions.add(edge);
-```
+transitions.set(edge, 1);
 
+// Retrieval using a new, structurally identical key
+console.log(transitions.get(new Tuple("q0", "q1"))); // 1
+```
 
-### Lifecycle (mutable → frozen)
+### Lifecycle (Mutable → Frozen)
 
-Accessing `hashCode` freezes the set to prevent hash corruption.
+To guarantee hash stability, collections become **immutable** (frozen) once their hash code is computed or they are inserted into another collection.
 
 ```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
+const A = new RecursiveSet(1);
+const B = new RecursiveSet(A); // Accessing A's hash to store it in B freezes A.
 
 try {
-  A.add(3); // throws after A is frozen
-} catch {
-  console.log("A is frozen and cannot be mutated.");
+  A.add(2); // Throws Error: Frozen Set modified.
+} catch (e) {
+  // Expected behavior
 }
 
-// “Fork” for mutation
+// Use mutableCopy to continue editing
 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>;
+C.add(2);
 ```
 
+## Contracts & Invariants
 
-### Construction
+This library optimizes for raw speed and assumes strict adherence to the following contracts. Violating them leads to undefined behavior.
 
-```ts
-new RecursiveSet<T>(...elements: T[])
-```
+1. **Finite Numbers Only:** `NaN` and `Infinity` are **strictly forbidden**. They break strict equality checks and integer optimization paths.
+2. **Strict Value Semantics:** Plain JavaScript objects (`{}`) are **not supported**. Keys must implement the `Structural` interface (provide `equals`, `hashCode`, and `toString`).
+3. **Hash Quality:** The $O(1)$ performance guarantee relies on a good distribution. Returning a constant `hashCode` (e.g., `42`) forces all elements into a single bucket, degrading performance to $O(N)$.
+4. **Deterministic Visualization:** Custom `toString()` implementations **must** utilize `compareVisualLogic` for nested structures. Failing to do so results in unstable string output.
+5. **Immutability:** Once an object is added to a collection, its `hashCode` **must not change**.
+6. **No Circular Dependencies:** A `RecursiveSet` cannot contain itself, directly or indirectly. Runtime checks are omitted for performance; creating a cycle will cause a Stack Overflow during hashing.
 
-Elements are sorted and deduplicated on construction.
+## API Reference
 
-### Bulk loading
+### Core Types
 
 ```ts
-RecursiveSet.fromArray<T>(elements: T[]): RecursiveSet<T>
-```
-
-Sorts once and deduplicates (typically much faster than many `.add()` calls).
+type Primitive = number | string;
+type Value = Primitive | Structural;
 
-### Unsafe creation
-
-```ts
-RecursiveSet.fromSortedUnsafe<T>(sortedUnique: T[]): RecursiveSet<T>
+interface Structural {
+  readonly hashCode: number;
+  equals(other: unknown): boolean;
+  toString(): string;
+}
 ```
 
-**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)
+### RecursiveSet
 
-- `add(element: T): this`
-- `remove(element: T): this`
-- `clear(): this`
+#### Construction
 
+- `new RecursiveSet<T>(...elements: T[])`: Creates a set from the given arguments.
 
-### Copying
+#### Mutation (Unfrozen state only)
 
-- `mutableCopy(): RecursiveSet<T>` – mutable shallow copy (use after freezing)
-- `clone(): RecursiveSet<T>` – alias for `mutableCopy()`
+- `add(element: T): void`: Adds an element ($O(1)$ amortized).
+- `remove(element: T): void`: Removes an element ($O(1)$ amortized).
 
+#### Set Operations
 
-### Set operations (return new sets)
+All operations return a new `RecursiveSet` instance.
 
-All operations below return new `RecursiveSet` instances:
-
-- `union(other): RecursiveSet<T | U>`
+- `union(other): RecursiveSet<T>`
 - `intersection(other): RecursiveSet<T>`
-- `difference(other): RecursiveSet<T>`
+- `difference(other): RecursiveSet<T>` ($A \setminus B$)
 - `symmetricDifference(other): RecursiveSet<T>`
-- `powerset(): RecursiveSet<RecursiveSet<T>>` (guarded; throws if too large)
 - `cartesianProduct<U>(other): RecursiveSet<Tuple<[T, U]>>`
+- `powerset(): RecursiveSet<RecursiveSet<T>>` (Throws if size > 20)
 
-
-### Predicates \& properties
+#### Properties
 
 - `has(element: T): boolean`
-- `equals(other: RecursiveSet<Value>): boolean`
-- `compare(other: RecursiveSet<Value>): number`
+- `equals(other: unknown): boolean`
 - `isSubset(other): boolean`
 - `isSuperset(other): boolean`
-- `isEmpty(): boolean`
+- `mutableCopy(): RecursiveSet<T>`: Returns a shallow mutable clone.
 - `size: number`
-- `hashCode: number` – computes and caches hash; freezes the set
-- `isFrozen: boolean`
+- `hashCode: number`: Computes hash and freezes the set.
 
+### RecursiveMap
 
-### Ordering rules
+A hash map supporting `Value` keys.
 
-Internal ordering is deterministic by design:
+- `set(key: K, value: V): void`
+- `get(key: K): V | undefined`
+- `delete(key: K): boolean`
+- `has(key: K): boolean`
+- `mutableCopy(): RecursiveMap<K, V>`
 
-- 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.
+### Tuple
 
+An immutable, hashable sequence of values. Useful for composite keys.
+
+- `new Tuple(...elements: T[])`
+- `get(index: number): T[index]`
+- `length: number`
 
 ## 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.
+Special thanks for his architectural guidance on homogeneous sets and the theoretical foundations required for high-performance set engines.
 
 ## Contributing
 
 ```bash
-git clone https://github.com/cstrerath/recursive-set.git
+git clone [https://github.com/cstrerath/recursive-set.git](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`
+MIT License © 2025 Christian Strerath. See `LICENSE`.