recursive-set 7.0.1 → 8.1.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,207 +1,201 @@
-# 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`
+# 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 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` 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 Architectural Features:**
+
+- **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
+
+```bash
+npm install recursive-set
+```
+
+## Quickstart
+
+### Working with Sets
+
+Sets automatically deduplicate elements based on their value or structure.
+
+```ts
+import { RecursiveSet } from "recursive-set";
+
+// Primitive values
+const numbers = new RecursiveSet(1, 2, 3);
+numbers.add(1); // No effect, 1 is already present
+
+// Recursive structures (Sets of Sets)
+const setA = new RecursiveSet(1, 2);
+const setB = new RecursiveSet(2, 1);
+const metaSet = new RecursiveSet<RecursiveSet<number>>();
+
+metaSet.add(setA);
+metaSet.add(setB);
+
+console.log(metaSet.size); // 1, because setA equals setB
+```
+
+### Working with Maps
+
+`RecursiveMap` allows using complex objects (like Tuples or Sets) as keys.
+
+```ts
+import { RecursiveMap, Tuple } from "recursive-set";
+
+const transitions = new RecursiveMap<Tuple<[string, string]>, number>();
+const edge = new Tuple("q0", "q1");
+
+transitions.set(edge, 1);
+
+// Retrieval using a new, structurally identical key
+console.log(transitions.get(new Tuple("q0", "q1"))); // 1
+```
+
+### Lifecycle (Mutable → Frozen)
+
+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);
+const B = new RecursiveSet(A); // Accessing A's hash to store it in B freezes A.
+
+try {
+  A.add(2); // Throws Error: Frozen Set modified.
+} catch (e) {
+  // Expected behavior
+}
+
+// Use mutableCopy to continue editing
+const C = A.mutableCopy();
+C.add(2);
+```
+
+## Contracts & Invariants
+
+This library optimizes for raw speed and assumes strict adherence to the following contracts. Violating them leads to undefined behavior.
+
+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.
+
+## API Reference
+
+### Core Types
+
+```ts
+type Primitive = number | string;
+type Value = Primitive | Structural;
+
+interface Structural {
+  readonly hashCode: number;
+  equals(other: unknown): boolean;
+  toString(): string;
+}
+```
+
+### RecursiveSet
+
+#### Construction
+
+- `new RecursiveSet<T>(...elements: T[])`: Creates a set from the given arguments.
+
+#### Mutation (Unfrozen state only)
+
+- `add(element: T): void`: Adds an element ($O(1)$ amortized).
+- `remove(element: T): void`: Removes an element ($O(1)$ amortized).
+
+#### Functional Methods (Zero-Allocation)
+
+*Added in v8.1.0* — These methods iterate directly over internal storage, avoiding the memory overhead of spreading into a temporary Array (`[...set]`).
+
+- `map<U>(fn: (v: T) => U): RecursiveSet<U>`
+  - Returns a new set. Pre-allocates storage to prevent resizing during mapping.
+- `filter(fn: (v: T) => boolean): RecursiveSet<T>`
+  - Returns a new set containing only elements that satisfy the predicate.
+- `reduce<U>(fn: (acc: U, v: T) => U, init: U): U`
+  - Aggregates values without intermediate allocations.
+- `every(fn: (v: T) => boolean): boolean`
+  - **Fail-Fast:** Returns `false` immediately upon the first mismatch ($O(1)$ best case).
+- `some(fn: (v: T) => boolean): boolean`
+  - **Fail-Fast:** Returns `true` immediately upon the first match ($O(1)$ best case).
+
+```typescript
+// Example: High-Performance Check
+const largeSet = new RecursiveSet(0, 1, 2, ...);
+
+// Instead of: [...largeSet].some(x => x === 0)  <-- Allocates Array(N)
+// Use:        largeSet.some(x => x === 0)       <-- Zero allocation, instant return
+```
+
+#### Set Operations
+
+All operations return a new `RecursiveSet` instance.
+
+- `union(other): RecursiveSet<T>`
+- `intersection(other): RecursiveSet<T>`
+- `difference(other): RecursiveSet<T>` ($A \setminus B$)
+- `symmetricDifference(other): RecursiveSet<T>`
+- `cartesianProduct<U>(other): RecursiveSet<Tuple<[T, U]>>`
+- `powerset(): RecursiveSet<RecursiveSet<T>>` (Throws if size > 20)
+
+#### Properties
+
+- `has(element: T): boolean`
+- `equals(other: unknown): boolean`
+- `isSubset(other): boolean`
+- `isSuperset(other): boolean`
+- `mutableCopy(): RecursiveSet<T>`: Returns a shallow mutable clone.
+- `size: number`
+- `hashCode: number`: Computes hash and freezes the set.
+
+### RecursiveMap
+
+A hash map supporting `Value` keys.
+
+- `set(key: K, value: V): void`
+- `get(key: K): V | undefined`
+- `delete(key: K): boolean`
+- `has(key: K): boolean`
+- `mutableCopy(): RecursiveMap<K, V>`
+
+### 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 on homogeneous sets and the theoretical foundations required for high-performance set engines.
+
+## Contributing
+
+```bash
+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`.