recursive-set 6.0.0 → 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,161 +1,207 @@
-# RecursiveSet
-
-High-performance, strictly typed 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 (e.g., 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`.
-- 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
-
-```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)
-
-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); // hashing B may hash A -> A becomes frozen
-
-console.log(B.has(A)); // true
-
-try {
-A.add(3); // throws
-} catch {
-console.log("A is frozen and cannot be mutated.");
-}
-
-// “Fork” for mutation
-const C = A.mutableCopy();
-C.add(3);
-```
-
----
-
-## Supported element types
-
-To keep value semantics predictable and prevent accidental mutation via arbitrary objects, `RecursiveSet` validates inputs and supports:
-
-- `number` (excluding `NaN`)
-- `string`
-- `Tuple`
-- plain `Array` (treated as an ordered sequence)
-- `RecursiveSet`
-
-## 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 for performance and convenience, but they are not frozen by the library.
-
-Recommendation for SAT / hot loops: represent frequently compared “small composite values” as `Tuple` to benefit from cached hashing and immutability.
-
----
-
-## API (selected)
-
-### Construction
-
-```typescript
-new RecursiveSet<T>(...elements: T[])
-```
-Elements are sorted and deduplicated on construction.
-
-### 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)
-
-- `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]>>`
-
-### Predicates & properties
-
-- `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
-
-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.
-
-## 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 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`