tuple-ts 0.7.0 → 0.8.0

package/README.md

@@ -1,154 +1,133 @@
 # tuple-ts
 
-**Immutable interned tuples and named tuples for JavaScript and TypeScript.**
+**TypeScript-first tuples and structs with value-based identity.**
 
-JavaScript normally compares arrays by reference:
+JavaScript normally compares arrays by reference: 
 
 ```ts
-[1, 2] === [1, 2]; // false
+[1, "foo"] === [1, "foo"]; // false!
 ```
 
-`tuple-ts` gives tuples value-based identity through *interning*:
+`tuple-ts` provides opt-in _value-based identity_:
 
 ```ts
 import { tuple } from "tuple-ts";
 
-tuple(1, 2) === tuple(1, 2); // true
+tuple(1, "foo") === tuple(1, "foo");  // true
 ```
 
-Equivalent tuples created through the same tuple cache are canonicalised to the same object. Values are frozen, so their contents cannot change after interning. This makes tuples useful as composite `Map` keys, `Set` members, memoization keys, and immutable values in functional TypeScript.
+with optional slot labels:
 
-`tuple-ts` also supports **named tuples** through `struct()`: values remain arrays with positional slots, while the declared labels are available as named properties.
+```ts
+import { struct } from "tuple-ts";
 
-**Zero dependencies · Less than 1 KB gzipped**
+const Person = struct(["name", "age"]);
 
-## Install
+const person1 = Person("Bob", 25);
 
-```bash
-npm install tuple-ts
+person1[0] === "Bob";   // true
+person1.name === "Bob"; // true
 ```
 
-## Tuples
-
-Create a tuple with narrow TypeScript inference:
+and support for label-based construction:
 
 ```ts
-import { tuple } from "tuple-ts";
-
-const point = tuple(10, 20);
-//    ^? readonly [10, 20]
+const person2 = Person.from({ name: "Bob", age: 25 });
 
-point[0]; // 10
-point[1]; // 20
-Object.isFrozen(point); // true
+person1 === person2;    // true
 ```
 
-Calling `tuple()` again with the same values returns the same canonical object:
+`tuple-ts` is useful when you want small immutable values with stable identity:
 
-```ts
-const a = tuple(10, 20);
-const b = tuple(10, 20);
+- Composite `Map` and `Set` keys
+- Memoization keys
+- Graph and search states
+- Coordinates and other multi-dimensional values
+- Named, slot-based values such as points or pairs
 
-a === b; // true
-Object.is(a, b); // true
-```
+`tuple-ts` has zero dependencies and is less than 1 KB gzipped.
 
-Different values or a different element order produce different tuples:
+## Install
 
-```ts
-tuple(10, 20) === tuple(10, 21); // false
-tuple(10, 20) === tuple(20, 10); // false
+```bash
+npm install tuple-ts
 ```
 
-Tuples are ordinary frozen arrays:
+## Tuples
 
-```ts
-const t = tuple("hello", 42, true);
+The values returned by `tuple(...)` are regular frozen JavaScript arrays:
 
-t.length;           // 3
-t[0];               // "hello"
-[...t];             // ["hello", 42, true]
-Array.isArray(t);   // true
-Object.isFrozen(t); // true
+```ts
+const tuple1 = tuple(1, "foo");
+
+Array.isArray(tuple1);   // true
+tuple1.length === 2;     // true
+tuple1[0] === 1;         // true
+tuple1[1] === "foo";     // true
+Object.isFrozen(tuple1); // true
+[ ...tuple1 ];           // [1, "foo"]
 ```
 
-### Constraining a tuple factory with `.narrow()`
-
-Use `.narrow()` to make a reusable factory whose arguments must satisfy a tuple type.
-
-Specify the type explicitly:
+...with automatically inferred literal types:
 
 ```ts
-const Point = tuple.narrow<[number, number]>();
-
-const a = Point(10, 20);
-const b = Point(10, 20);
-
-a === b; // true
-Point(10, "20"); // TypeScript error
+type Tuple1 = typeof tuple1; // readonly [1, "foo"]
 ```
 
-You can also refine an existing fixed-length tuple factory using an exemplar. The exemplar is used to infer the constraint, not as a default value:
+Type-narrowed tuple factories are also supported:
 
 ```ts
-const Pair = tuple.narrow<[unknown, unknown]>();
-const NumberPair = Pair.narrow([0, 0]);
+type Point = [number, number];
+const Point = tuple.typed<Point>();
+// Or equivalently, using an exemplar:
+// const Point = tuple.typed(0, 0);
 
-NumberPair(10, 20); // OK
-NumberPair(10, "20"); // TypeScript error
+type P = Parameters<typeof Point>; // [number, number];
 ```
 
-In this example, the parent factory establishes the two-slot shape, and the exemplar narrows the element types to numbers. `.narrow()` is a TypeScript constraint; it does not create a new cache. Narrowed factories continue to use the shared tuple cache, so equal tuple values are interned together regardless of which narrowed factory constructs them.
-
-## Why is this useful?
-
-### Composite `Map` keys
-
-Without interning, separately constructed arrays don't work as value-based keys:
+Calling `tuple()` again with the same values returns the same canonical object:
 
 ```ts
-const map = new Map();
+const a = tuple(10, 20);
+const b = tuple(10, 20);
 
-map.set([10, 20], "visited");
-map.get([10, 20]); // undefined
+a === b; // true
+Object.is(a, b); // true
 ```
 
-With `tuple-ts`:
+Different values or a different element order produce different tuples:
 
 ```ts
-const map = new Map();
-
-map.set(tuple(10, 20), "visited");
-map.get(tuple(10, 20)); // "visited"
+tuple(10, 20) === tuple(10, 21); // false!
+tuple(10, 20) === tuple(20, 10); // false!
 ```
 
-The tuple used for lookup is the same canonical object as the tuple used as the key. This is useful for coordinates, memoization keys, graph nodes, dynamic-programming states, and other composite values.
+### Constraining a tuple factory with `.typed()`
 
-### `Set` of values
+Use `.typed()` to make a reusable tuple factory whose arguments must satisfy a nominated tuple type.
 
-```ts
-const visited = new Set();
+Specify the type explicitly:
 
-visited.add(tuple(10, 20));
+```ts
+const Point = tuple.typed<[number, number]>();
 
-visited.has(tuple(10, 20)); // true
-visited.has(tuple(10, 21)); // false
+Point(10, 20);   // OK
+Point(10, "20"); // TypeScript error
 ```
 
-No serialization, stringification, or custom hashing is required.
-
-## Nested tuples
-
-Tuples can contain other interned tuples:
+You can alternatively provide an exemplar from which the type constraint will be inferred:
 
 ```ts
-const a = tuple("matrix", tuple(1, 0), tuple(0, 1));
-const b = tuple("matrix", tuple(1, 0), tuple(0, 1));
+const NumberPair = tuple.typed(0, 0);
 
-a === b; // true
+NumberPair(10, 20);   // OK
+NumberPair(10, "20"); // TypeScript error
 ```
 
-Because the inner tuples are themselves canonicalised, the outer tuples can be interned as well.
+
+### Nesting tuples
+
+Tuples can contain other interned tuples:
 
 ```ts
 const a = tuple("a", tuple("b", "c"));
@@ -156,17 +135,23 @@ const b = tuple("a", tuple("b", "c"));
 const c = tuple("a", tuple("b", "d"));
 
 a === b; // true
-a === c; // false
+a === c; // false!
+
+const mat1 = tuple("matrix", tuple(1, 0), tuple(0, 1));
+const mat2 = tuple("matrix", tuple(1, 0), tuple(0, 1));
+
+mat1 === mat2; // true
 ```
 
-## Named tuples with `struct()`
+## Structs
 
-Use `struct()` when you want positional tuple storage with meaningful labels. Pass a readonly label list to create a reusable factory:
+Use `struct()` when you want a tuple with meaningful labels.
+Provide a list of labels to create a reusable factory that produces tuples with additional named properties.
 
 ```ts
 import { struct } from "tuple-ts";
 
-const Point = struct(["x", "y"]).narrow<[number, number]>();
+const Point = struct(["x", "y"]);
 
 const p = Point(10, 20);
 
@@ -175,26 +160,24 @@ p[1]; // 20
 p.x;  // 10
 p.y;  // 20
 
-Array.isArray(p);   // true
+Array.isArray(p);   // true!
 Object.isFrozen(p); // true
+[ ...p ];           // [10, 20]
+{ ...p };           // { 0: 10, 1: 20, x: 10, y: 20 }
 ```
 
-The label order corresponds to the tuple slot order: the first label names slot `0`, the second names slot `1`, and so on. The named properties are added to the array when it is interned. They are own, enumerable properties and are frozen along with the array.
-
-### Constructing from a named object with `.from()`
+### Constructing from an object with `.from()`
 
 `.from()` accepts an object with the declared labels and creates the corresponding positional tuple:
 
 ```ts
-const Point = struct(["x", "y"]).narrow<[number, number]>();
-
-const a = Point.from({ x: 10, y: 20 });
-const b = Point.from({ y: 20, x: 10 });
+const Point = struct(["x", "y"]);
 
-a === b; // true
+const point1 = Point.from({ x: 10, y: 20 });
 
-a[0]; // 10
-a.x;  // 10
+point1 === Point(10, 20); // true
+point1[0] === 10;         // true
+point1.x === 10;          // true
 ```
 
 The values are read in the schema's label order, regardless of the input object's property order. Extra properties on the input object are ignored:
@@ -210,45 +193,40 @@ The returned value contains the tuple slots and the schema's named properties, n
 
 ### Constraining a struct factory
 
-Use `.narrow()` to specify the tuple's positional types:
+Just like `tuple`, structs support `.typed()` to specify the struct's value types positionally:
 
 ```ts
-const Point = struct(["x", "y"]).narrow<[number, number]>();
+const Point = struct(["x", "y"]).typed<[number, number]>();
 
 Point(10, 20);   // OK
 Point(10, "20"); // TypeScript error
 ```
 
-Use `.narrowFrom()` when you want to express the value types by label instead:
+Use `.typedFrom()` when you want to express the value types by label instead:
 
 ```ts
 type Coordinates = { x: number; y: number };
 
-const Point = struct(["x", "y"]).narrowFrom<Coordinates>();
+const Point = struct(["x", "y"]).typedFrom<Coordinates>();
 
 Point(10, 20);    // OK
-Point(10, "20"); // TypeScript error
+Point(10, "20");  // TypeScript error
 Point.from({ x: 10, y: 20 }); // OK
 ```
 
-You can also provide a typed exemplar to `.narrowFrom()`:
+You can also provide a typed exemplar to `.typedFrom()`:
 
 ```ts
-const coordinateExample: Coordinates = { x: 0, y: 0 };
-const Point = struct(["x", "y"]).narrowFrom(coordinateExample);
+const Point = struct(["x", "y"]).typedFrom({ x: 0, y: 0 });
 ```
 
-The exemplar establishes types; its values are not used as defaults. If you pass an inline `const` exemplar whose properties are literal values, those literal types may be preserved. Give the exemplar a widened type, or use an explicit generic argument, when you want types such as `number` rather than the literal type `0`.
-
-Both `.narrow()` and `.narrowFrom()` preserve the cache associated with the original `struct()` schema. They refine the factory's TypeScript constraints rather than creating a new interning domain.
-
 ### Struct schemas and identity
 
-Each call to `struct(labels)` creates a schema with its own intern cache. Factories narrowed from that schema share the cache, but separate calls to `struct()` create separate caches, even when given identical labels:
+Each call to `struct(labels)` creates its own cache. Factories narrowed from that schema with `.typed()` share the cache, but separate calls to `struct()` create separate caches, even when given identical labels:
 
 ```ts
-const PointA = struct(["x", "y"]).narrow<[number, number]>();
-const PointB = struct(["x", "y"]).narrow<[number, number]>();
+const PointA = struct(["x", "y"]).typed<[number, number]>();
+const PointB = struct(["x", "y"]).typed<[number, number]>();
 
 PointA(1, 2) === PointA(1, 2); // true
 PointA(1, 2) === PointB(1, 2); // false
@@ -256,9 +234,40 @@ PointA(1, 2) === PointB(1, 2); // false
 
 Struct identity is therefore scoped to the schema factory. Ordinary `tuple()` values use a separate, shared tuple cache and do not share identity with struct values, even when their indexed elements are equal.
 
-### Choosing labels
+## Tuples and structs as composite keys for `Map` and `Set`
 
-Use distinct labels, and avoid labels that collide with array properties or indices. In particular, `"length"`, numeric-looking labels such as `"0"`, and method names such as `"map"` can conflict with normal array behaviour. The current implementation does not validate label names or duplicate labels, so callers should ensure labels are unique and suitable for named properties.
+`tuple` and `struct` let you use composite keys with JavaScript's built-in `Map` and `Set`, without serialization or stringification.
+
+JavaScript's `Map` and `Set` treat separately constructed arrays as distinct keys, even when their contents are equal:
+
+```ts
+const myMap = new Map();
+myMap.set([10, 20], "visited");
+
+myMap.has([10, 20]);  // false!
+myMap.get([10, 20]);  // undefined!
+
+const mySet = new Set();
+mySet.add([10, 20]);
+
+mySet.has([10, 20]);  // false!
+```
+
+With `tuple-ts`:
+
+```ts
+const myMap = new Map();
+myMap.set(tuple(10, 20), "visited");
+
+myMap.has(tuple(10, 20)); // true
+myMap.get(tuple(10, 20)); // "visited"
+
+const Point = struct(["x", "y"]);
+const mySet = new Set();
+mySet.add(Point(1, 2));
+
+mySet.has(Point(1, 2)); // true
+```
 
 ## Equality semantics
 
@@ -278,7 +287,7 @@ tuple(value) === tuple(value); // true
 tuple({ x: 1 }) === tuple({ x: 1 }); // false
 ```
 
-`tuple-ts` does not recursively compare arbitrary JavaScript objects. Nested tuples work well because they are themselves interned:
+`tuple-ts` does not recursively compare arbitrary JavaScript objects. Nested tuples work well because the values are themselves tuples:
 
 ```ts
 const a = tuple(tuple(1, 2));
@@ -287,45 +296,11 @@ const b = tuple(tuple(1, 2));
 a === b; // true
 ```
 
-Struct caches use the same shallow slot-value comparison, but each struct schema has its own cache. Within a schema, the label properties are determined by the schema; the indexed slot values determine which canonical tuple is returned.
-
-## Immutable by design
-
-Tuples and structs returned by `tuple-ts` are frozen. Freezing is shallow, just like `Object.freeze()`:
-
-```ts
-const details = { name: "Alice" };
-const value = tuple(details);
-
-details.name = "Bob"; // Allowed: the nested object itself is not frozen
-```
-
-The tuple's reference to `details` is unchanged, so its interned identity remains the same. If you need immutable nested values, construct those values with `tuple()` or `struct()` too.
-
-## Garbage-collection friendly
-
-Interning raises a natural question: *doesn't the cache grow forever?* The cache implementation uses weak references and finalization support so that values no longer referenced by the application can be reclaimed by the JavaScript garbage collector. Values are not intended to be kept alive forever simply because they were once constructed.
-
-## When should I use it?
-
-`tuple-ts` is useful when you want small immutable values with stable identity:
-
-- Composite `Map` keys
-- `Set` membership
-- Memoization keys
-- Graph and search states
-- Coordinates and other multi-dimensional values
-- Functional programming
-- Immutable application state
-- Named, slot-based values such as points or pairs
-
-Use `tuple()` for positional values and `struct()` when the same kind of value benefits from stable field labels.
-
-## Design
+## Garbage Collection
 
-The intern cache uses hashing to find candidates, then checks exact shallow equality before reusing an existing value. Hash collisions therefore do not determine equality. Tuple element order matters. Struct label order defines the mapping between slots and names, and each schema has its own cache.
+`tuple-ts` works by maintaining internal caches of tuple/struct objects. This raises a natural question: *doesn't the cache grow forever?*
 
-There are no runtime dependencies.
+The cache uses `WeakRef` to avoid keeping interned objects alive solely because they are cached. A `FinalizationRegistry` is used to clean up cache entries after objects are garbage-collected. This allows unreferenced values to be reclaimed without the cache retaining them indefinitely.
 
 ## License