tuple-ts 0.6.0 → 0.7.1

package/README.md

@@ -1,608 +1,306 @@
 # tuple-ts
 
-**Immutable tuples, records and structs with value-based identity for JavaScript and TypeScript.**
+**TypeScript-first tuples and structs with value-based identity.**
 
-JavaScript normally compares arrays and objects by reference:
+JavaScript normally compares arrays by reference: 
 
 ```ts
-[1, 2] === [1, 2] // false
-
-({ x: 1 }) === ({ x: 1 }) // false
-```
-
-`tuple-ts` gives you a different model:
-
-```ts
-tuple(1, 2) === tuple(1, 2) // true
-
-record({ x: 1 }) === record({ x: 1 }) // true
-```
-
-Equal values are **interned to the same object**.
-
-That makes tuples, records and structs immutable, naturally usable as composite `Map` keys and `Set` values, and particularly pleasant to use in functional TypeScript.
-
-**Zero dependencies · Less than 1 KB gzipped**
-
-## Install
-
-```bash
-npm install tuple-ts
+[1, "foo"] === [1, "foo"]; // false!
 ```
 
-## Tuples
-
-Create an immutable tuple with full TypeScript inference:
+`tuple-ts` provides opt-in _value-based identity_:
 
 ```ts
 import { tuple } from "tuple-ts";
 
-const point = tuple(10, 20);
-//    ^? readonly [10, 20]
-
-console.log(point[0]); // 10
-console.log(point[1]); // 20
+tuple(1, "foo") === tuple(1, "foo");  // true
 ```
 
-Calling `tuple` again with the same values gives you the **same object**:
+with optional slot labels:
 
 ```ts
-const a = tuple(10, 20);
-const b = tuple(10, 20);
+import { struct } from "tuple-ts";
 
-a === b; // true
-Object.is(a, b); // true
-```
+const Person = struct(["name", "age"]);
 
-Different values give you different objects:
+const person1 = Person("Bob", 25);
 
-```ts
-tuple(10, 20) === tuple(10, 21); // false
-tuple(10, 20) === tuple(20, 10); // false
+person1[0] === "Bob";   // true
+person1.name === "Bob"; // true
 ```
 
-Tuples are ordinary frozen arrays, so there is no special API to learn:
+and support for label-based construction:
 
 ```ts
-const t = tuple("hello", 42, true);
+const person2 = Person.from({ name: "Bob", age: 25 });
 
-t.length;           // 3
-t[0];               // "hello"
-[...t];             // ["hello", 42, true]
-Object.isFrozen(t); // true
+person1 === person2;    // true
 ```
 
-## Why is this useful?
+`tuple-ts` is useful when you want small immutable values with stable identity:
 
-### Composite `Map` keys
+- 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
 
-JavaScript doesn't have value-based arrays, so this doesn't work:
+`tuple-ts` has zero dependencies and is less than 1 KB gzipped.
 
-```ts
-const map = new Map();
-
-map.set([10, 20], "visited");
+## Install
 
-map.get([10, 20]); // undefined
+```bash
+npm install tuple-ts
 ```
 
-With `tuple-ts`:
+## Tuples
 
-```ts
-const map = new Map();
+The values returned by `tuple(...)` are regular frozen JavaScript arrays:
 
-map.set(tuple(10, 20), "visited");
+```ts
+const tuple1 = tuple(1, "foo");
 
-map.get(tuple(10, 20)); // "visited"
+Array.isArray(tuple1);   // true
+tuple1.length === 2;     // true
+tuple1[0] === 1;         // true
+tuple1[1] === "foo";     // true
+Object.isFrozen(tuple1); // true
+[ ...tuple1 ];           // [1, "foo"]
 ```
 
-The tuple constructed during the lookup is the same canonical object as the tuple used as the key.
-
-This is particularly useful for things like coordinates, memoization keys, graph nodes, dynamic-programming states, and other composite values.
-
-### `Set` of values
-
-The same applies to `Set`:
+...with automatically inferred literal types:
 
 ```ts
-const visited = new Set();
-
-visited.add(tuple(10, 20));
-
-visited.has(tuple(10, 20)); // true
-visited.has(tuple(10, 21)); // false
+type Tuple1 = typeof tuple1; // readonly [1, "foo"]
 ```
 
-No serialization, stringification, or custom hashing is required.
-
-## Nested tuples
-
-Tuples can be nested:
+Type-narrowed tuple factories are also supported:
 
 ```ts
-const a = tuple(
-  "matrix",
-  tuple(1, 0),
-  tuple(0, 1),
-);
-
-const b = tuple(
-  "matrix",
-  tuple(1, 0),
-  tuple(0, 1),
-);
+type Point = [number, number];
+const Point = tuple.narrow<Point>();
+// Or equivalently, using an exemplar:
+// const Point = tuple.narrow(0, 0);
 
-a === b; // true
+type P = Parameters<typeof Point>; // [number, number];
 ```
 
-Because nested tuples themselves have value-based identity, the resulting structures are canonicalised naturally.
+Calling `tuple()` again with the same values returns the same canonical object:
 
 ```ts
-const a = tuple("a", tuple("b", "c"));
-const b = tuple("a", tuple("b", "c"));
-const c = tuple("a", tuple("b", "d"));
+const a = tuple(10, 20);
+const b = tuple(10, 20);
 
 a === b; // true
-a === c; // false
+Object.is(a, b); // true
 ```
 
-## Typed tuples
-
-Use `tuple.like()` to create a reusable constructor for a particular tuple type.
-
-### Inferring the type from an exemplar
+Different values or a different element order produce different tuples:
 
 ```ts
-const Point = tuple.like(0, 0);
-
-const a = Point(10, 20);
-const b = Point(10, 20);
-
-a === b; // true
+tuple(10, 20) === tuple(10, 21); // false!
+tuple(10, 20) === tuple(20, 10); // false!
 ```
 
-The exemplar determines the TypeScript type expected by the resulting factory. Its values are not used as defaults.
+### Constraining a tuple factory with `.narrow()`
 
-By default, TypeScript widens the exemplar's literal types, so `tuple.like(0, 0)` produces a factory accepting two numbers.
+Use `.narrow()` to make a reusable tuple factory whose arguments must satisfy a nominated tuple type.
 
-### Explicit type arguments
-
-Alternatively, specify the type directly:
+Specify the type explicitly:
 
 ```ts
-type Point = [x: number, y: number];
-
-const Point = tuple.like<Point>();
-
-const a = Point(10, 20);
-const b = Point(10, 20);
+const Point = tuple.narrow<[number, number]>();
 
-a === b; // true
+Point(10, 20);   // OK
+Point(10, "20"); // TypeScript error
 ```
 
-No exemplar is required when the type argument is provided explicitly.
-
-### Preserving literal types
-
-To preserve literal types rather than widen them, use `as const`:
+You can alternatively provide an exemplar from which the type constraint will be inferred:
 
 ```ts
-const Direction = tuple.like("north" as const, 1 as const);
+const NumberPair = tuple.narrow(0, 0);
 
-Direction("north", 1); // OK
-Direction("south", 1); // TypeScript error
+NumberPair(10, 20);   // OK
+NumberPair(10, "20"); // TypeScript error
 ```
 
-In all cases, the resulting tuples are frozen and interned using the same shared cache as ordinary tuples.
 
-## Records
+### Nesting tuples
 
-`record` provides the same value-based identity semantics for objects:
+Tuples can contain other interned tuples:
 
 ```ts
-import { record } from "tuple-ts";
-
-const a = record({
-  id: 1,
-  role: "admin",
-});
-
-const b = record({
-  role: "admin",
-  id: 1,
-});
+const a = tuple("a", tuple("b", "c"));
+const b = tuple("a", tuple("b", "c"));
+const c = tuple("a", tuple("b", "d"));
 
 a === b; // true
-```
-
-Property order does not matter.
+a === c; // false!
 
-Records are frozen:
+const mat1 = tuple("matrix", tuple(1, 0), tuple(0, 1));
+const mat2 = tuple("matrix", tuple(1, 0), tuple(0, 1));
 
-```ts
-Object.isFrozen(a); // true
+mat1 === mat2; // true
 ```
 
-And they work naturally as `Map` keys:
-
-```ts
-const users = new Map();
-
-users.set(
-  record({ id: 42, role: "admin" }),
-  "Alice",
-);
+## Structs
 
-users.get(
-  record({ role: "admin", id: 42 }),
-); // "Alice"
-```
+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.
 
-### Record identity
+```ts
+import { struct } from "tuple-ts";
 
-A record's identity is determined by its own, enumerable, string-keyed properties and their values.
+const Point = struct(["x", "y"]);
 
-Two records are equivalent if they contain exactly the same keys, with equivalent values, regardless of property order.
+const p = Point(10, 20);
 
-```ts
-record({ x: 1, y: 2 }) ===
-record({ y: 2, x: 1 }); // true
+p[0]; // 10
+p[1]; // 20
+p.x;  // 10
+p.y;  // 20
 
-record({ x: 1 }) ===
-record({ x: 1, y: 2 }); // false
+Array.isArray(p);   // true!
+Object.isFrozen(p); // true
+[ ...p ];           // [10, 20]
+{ ...p };           // { 0: 10, 1: 20, x: 10, y: 20 }
 ```
 
-Symbol-keyed, inherited and non-enumerable properties are not copied into records.
+### Constructing from an object with `.from()`
 
-Numeric property keys are supported and follow JavaScript's normal conversion to string keys.
-
-### Typed records
-
-Use `record.like()` to create a reusable typed record constructor:
+`.from()` accepts an object with the declared labels and creates the corresponding positional tuple:
 
 ```ts
-interface User {
-  id: string;
-  name: string;
-  updatedAt: number;
-}
-
-const User = record.like<User>();
-
-const a = User({
-  id: "alice",
-  name: "Alice",
-  updatedAt: 1000,
-});
-
-const b = User({
-  name: "Alice",
-  id: "alice",
-  updatedAt: 1000,
-});
-
-a === b; // true
-```
+const Point = struct(["x", "y"]);
 
-Alternatively, infer the type from an exemplar:
+const point1 = Point.from({ x: 10, y: 20 });
 
-```ts
-const User = record.like({
-  id: "",
-  name: "",
-  updatedAt: 0,
-});
+point1 === Point(10, 20); // true
+point1[0] === 10;         // true
+point1.x === 10;          // true
 ```
 
-As with `tuple.like()`, the exemplar defines the type; it does not supply default values.
-
-The resulting factory requires the properties established by `like()`, but may also accept additional properties.
-
-Unlike `struct`, `record` preserves those additional properties, and they contribute to identity.
+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:
 
 ```ts
-const User = record.like({ id: "" });
+const p = Point.from({ x: 10, y: 20, altitude: 100 });
 
-const a = User({ id: "alice" });
-const b = User({ id: "alice", role: "admin" });
-
-a === b; // false
+p.x; // 10
+p.y; // 20
 ```
 
-## Structs
+The returned value contains the tuple slots and the schema's named properties, not the unrelated input properties.
 
-`record` interns whatever properties you give it. If you want a fixed set of keys to define identity, use `struct`.
+### Constraining a struct factory
 
-`struct` takes key names as arguments and returns a factory. The factory accepts any object with at least those keys, extracts **exactly the declared keys**, and interns the result.
+Just like `tuple`, structs support `.narrow()` to specify the struct's value types positionally:
 
 ```ts
-import { struct } from "tuple-ts";
-
-const Point = struct("x", "y");
-
-const a = Point({ x: 1, y: 2 });
-const b = Point({ x: 1, y: 2 });
+const Point = struct(["x", "y"]).narrow<[number, number]>();
 
-a === b; // true
+Point(10, 20);   // OK
+Point(10, "20"); // TypeScript error
 ```
 
-### Additional properties are discarded
-
-Unlike `record`, a struct factory ignores properties that are not part of its declared structure:
+Use `.narrowFrom()` when you want to express the value types by label instead:
 
 ```ts
-const Point = struct("x", "y");
+type Coordinates = { x: number; y: number };
 
-const a = Point({ x: 1, y: 2 });
-const b = Point({ x: 1, y: 2, z: 3 });
+const Point = struct(["x", "y"]).narrowFrom<Coordinates>();
 
-a === b; // true
+Point(10, 20);    // OK
+Point(10, "20");  // TypeScript error
+Point.from({ x: 10, y: 20 }); // OK
 ```
 
-The resulting objects contain only `x` and `y`:
+You can also provide a typed exemplar to `.narrowFrom()`:
 
 ```ts
-Object.keys(b); // ["x", "y"]
-
-b.z; // TypeScript error
+const Point = struct(["x", "y"]).narrowFrom({ x: 0, y: 0 });
 ```
 
-This makes structs useful for projecting larger objects into canonical values with a precisely defined shape.
+### Struct schemas and identity
 
-```ts
-const Position = struct("x", "y");
+Each call to `struct(labels)` creates its own cache. Factories narrowed from that schema share the cache, but separate calls to `struct()` create separate caches, even when given identical labels:
 
-const location = {
-  x: 10,
-  y: 20,
-  altitude: 100,
-  timestamp: Date.now(),
-};
+```ts
+const PointA = struct(["x", "y"]).narrow<[number, number]>();
+const PointB = struct(["x", "y"]).narrow<[number, number]>();
 
-const position = Position(location);
-// { x: 10, y: 20 }
+PointA(1, 2) === PointA(1, 2); // true
+PointA(1, 2) === PointB(1, 2); // false
 ```
 
-The factory is deliberately permissive about additional input properties, but strict about which properties appear in its output.
+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.
 
-### Typed structs
+## Tuples and structs as composite keys for `Map` and `Set`
 
-Use `struct(...keys).like()` to constrain the types of the declared properties.
+`tuple` and `struct` let you use composite keys with JavaScript's built-in `Map` and `Set`, without serialization or stringification.
 
-The type can be inferred from an exemplar:
+JavaScript's `Map` and `Set` treat separately constructed arrays as distinct keys, even when their contents are equal:
 
 ```ts
-const Point = struct("x", "y").like({
-  x: 0,
-  y: 0,
-});
-
-Point({ x: 10, y: 20 });    // OK
-Point({ x: "10", y: 20 });  // TypeScript error
-```
+const myMap = new Map();
+myMap.set([10, 20], "visited");
 
-Or provided explicitly:
+myMap.has([10, 20]);  // false!
+myMap.get([10, 20]);  // undefined!
 
-```ts
-type Coordinates = {
-  x: number;
-  y: number;
-};
-
-const Point = struct("x", "y").like<Coordinates>();
+const mySet = new Set();
+mySet.add([10, 20]);
 
-Point({ x: 10, y: 20 }); // OK
+mySet.has([10, 20]);  // false!
 ```
 
-As with the other factories, `like()` defines types, not default values.
-
-### Strict definitions, flexible construction
-
-There is an intentional distinction between defining a struct and constructing one.
-
-A `like()` exemplar must contain only the keys declared by `struct`:
+With `tuple-ts`:
 
 ```ts
-const Point = struct("x", "y");
+const myMap = new Map();
+myMap.set(tuple(10, 20), "visited");
 
-Point.like({
-  x: 0,
-  y: 0,
-  z: 0, // TypeScript error: unexpected property
-});
-```
-
-But the resulting factory accepts extra properties and discards them:
+myMap.has(tuple(10, 20)); // true
+myMap.get(tuple(10, 20)); // "visited"
 
-```ts
-const Point = struct("x", "y").like({
-  x: 0,
-  y: 0,
-});
+const Point = struct(["x", "y"]);
+const mySet = new Set();
+mySet.add(Point(1, 2));
 
-Point({ x: 10, y: 20, z: 30 }); // OK
-// { x: 10, y: 20 }
+mySet.has(Point(1, 2)); // true
 ```
 
-This keeps struct definitions precise without making callers manually remove unrelated properties from their input objects.
-
 ## Equality semantics
 
-Values are compared using [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is):
+Tuple elements are compared shallowly using `Object.is`:
 
 ```ts
 tuple(NaN) === tuple(NaN); // true
-
 tuple(+0) === tuple(-0);   // false
 ```
 
-Object values retain JavaScript's normal identity semantics.
-
-The same object is the same value:
+Object-valued elements retain JavaScript's normal reference identity:
 
 ```ts
 const value = { x: 1 };
-
 tuple(value) === tuple(value); // true
-```
 
-Two separately created objects are different values:
-
-```ts
 tuple({ x: 1 }) === tuple({ x: 1 }); // false
 ```
 
-This is **shallow equality**. `tuple-ts` does not recursively compare arbitrary JavaScript objects.
-
-Nested tuples, records and structs work particularly well because they are themselves canonical values:
+`tuple-ts` does not recursively compare arbitrary JavaScript objects. Nested tuples work well because the values are themselves tuples:
 
 ```ts
-const a = record({
-  position: tuple(10, 20),
-});
-
-const b = record({
-  position: tuple(10, 20),
-});
+const a = tuple(tuple(1, 2));
+const b = tuple(tuple(1, 2));
 
 a === b; // true
 ```
 
-The outer records compare equal because the inner tuples have already been interned to the same object.
-
-All three constructors share this model of identity.
-
-## Immutable by design
-
-Tuples, records and structs returned by `tuple-ts` are frozen:
-
-```ts
-const point = tuple(10, 20);
-const user = record({ id: 1 });
-const position = struct("x", "y")({ x: 1, y: 2 });
-
-Object.isFrozen(point);    // true
-Object.isFrozen(user);     // true
-Object.isFrozen(position); // true
-```
-
-This is important to the identity semantics: once a value has been interned, its own properties cannot subsequently change while it is being used as a `Map` key or `Set` member.
-
-Freezing is shallow. If an interned value contains a reference to an ordinary mutable object, that nested object is not automatically frozen.
-
-For example:
-
-```ts
-const details = { name: "Alice" };
-const user = record({ details });
-
-details.name = "Bob"; // Allowed
-```
-
-The reference to `details` remains unchanged, so the interned record retains its identity.
-
-If you need immutable nested values, construct them using `tuple`, `record` or `struct` as well.
-
-## Garbage-collection friendly
-
-Interning values creates a natural question: *doesn't the cache grow forever?*
-
-`tuple-ts` uses `WeakRef` and `FinalizationRegistry` internally. Cached values are weakly referenced, allowing the JavaScript garbage collector to reclaim values that are no longer referenced by the application.
-
-In other words, you don't have to manually maintain a global cache of every tuple, record or struct you've ever created.
-
-## TypeScript first
-
-`tuple`, `record` and `struct` are designed to preserve TypeScript's inference.
-
-### Literal inference
-
-By default, constructors preserve literal types:
-
-```ts
-const t = tuple("hello", 42, true);
-// readonly ["hello", 42, true]
-
-const r = record({ x: 1, y: 2 });
-// readonly properties x: 1, y: 2
-```
-
-### Reusable typed factories
-
-Use `.like()` to define reusable constructors:
-
-```ts
-const Pair = tuple.like("", 0);
-
-const User = record.like({
-  id: "",
-  name: "",
-});
-
-const Point = struct("x", "y").like({
-  x: 0,
-  y: 0,
-});
-```
-
-Or specify types explicitly:
-
-```ts
-const Pair = tuple.like<[string, number]>();
-
-const User = record.like<{
-  id: string;
-  name: string;
-}>();
-
-const Point = struct("x", "y").like<{
-  x: number;
-  y: number;
-}>();
-```
-
-In either form, TypeScript checks arguments to the resulting factories.
-
-### Readonly results
-
-All constructors return readonly types, reflecting the frozen runtime objects.
-
-The readonly typing is shallow, just like `Object.freeze()`.
-
-## When should I use it?
-
-`tuple-ts` is particularly useful when you want **small immutable values with stable identity**:
-
-- Composite `Map` keys
-- `Set` membership
-- Memoization keys
-- Graph/search states
-- Coordinates and other multi-dimensional values
-- Functional programming
-- Immutable application state
-- Canonical representations of frequently repeated values
-
-Choose between the three constructors according to your data:
-
-| Constructor | Shape | Identity |
-|---|---|---|
-| `tuple` | Ordered sequence | Position and value of each element |
-| `record` | Arbitrary object properties | Complete set of keys and values |
-| `struct` | Fixed declared keys | Values of the declared keys only |
-
-If you just need an ordinary mutable array or object, use one. `tuple-ts` is for when you want the thing to behave more like a **value**.
-
-## Design
-
-The implementation uses hashing to locate candidate values and then performs an exact shallow equality check before reusing an existing value. Hash collisions therefore do not determine equality.
-
-Property order is ignored for records and structs, but element order matters for tuples.
-
-The intern cache uses weak references, so canonical values do not need to be kept alive solely because they have previously been created.
+## Garbage Collection
 
-Constructed records and structs are copied before interning, so callers cannot alter an interned value by modifying the source object.
+`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