tuple-ts 0.6.0 → 0.7.0

package/README.md

@@ -1,26 +1,24 @@
 # tuple-ts
 
-**Immutable tuples, records and structs with value-based identity for JavaScript and TypeScript.**
+**Immutable interned tuples and named tuples for JavaScript and TypeScript.**
 
-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
+[1, 2] === [1, 2]; // false
 ```
 
-`tuple-ts` gives you a different model:
+`tuple-ts` gives tuples value-based identity through *interning*:
 
 ```ts
-tuple(1, 2) === tuple(1, 2) // true
+import { tuple } from "tuple-ts";
 
-record({ x: 1 }) === record({ x: 1 }) // true
+tuple(1, 2) === tuple(1, 2); // true
 ```
 
-Equal values are **interned to the same object**.
+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.
 
-That makes tuples, records and structs immutable, naturally usable as composite `Map` keys and `Set` values, and particularly pleasant to use in functional TypeScript.
+`tuple-ts` also supports **named tuples** through `struct()`: values remain arrays with positional slots, while the declared labels are available as named properties.
 
 **Zero dependencies · Less than 1 KB gzipped**
 
@@ -32,7 +30,7 @@ npm install tuple-ts
 
 ## Tuples
 
-Create an immutable tuple with full TypeScript inference:
+Create a tuple with narrow TypeScript inference:
 
 ```ts
 import { tuple } from "tuple-ts";
@@ -40,11 +38,12 @@ import { tuple } from "tuple-ts";
 const point = tuple(10, 20);
 //    ^? readonly [10, 20]
 
-console.log(point[0]); // 10
-console.log(point[1]); // 20
+point[0]; // 10
+point[1]; // 20
+Object.isFrozen(point); // true
 ```
 
-Calling `tuple` again with the same values gives you the **same object**:
+Calling `tuple()` again with the same values returns the same canonical object:
 
 ```ts
 const a = tuple(10, 20);
@@ -54,14 +53,14 @@ a === b; // true
 Object.is(a, b); // true
 ```
 
-Different values give you different objects:
+Different values or a different element order produce different tuples:
 
 ```ts
 tuple(10, 20) === tuple(10, 21); // false
 tuple(10, 20) === tuple(20, 10); // false
 ```
 
-Tuples are ordinary frozen arrays, so there is no special API to learn:
+Tuples are ordinary frozen arrays:
 
 ```ts
 const t = tuple("hello", 42, true);
@@ -69,20 +68,48 @@ const t = tuple("hello", 42, true);
 t.length;           // 3
 t[0];               // "hello"
 [...t];             // ["hello", 42, true]
+Array.isArray(t);   // true
 Object.isFrozen(t); // true
 ```
 
+### Constraining a tuple factory with `.narrow()`
+
+Use `.narrow()` to make a reusable factory whose arguments must satisfy a tuple type.
+
+Specify the type explicitly:
+
+```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
+```
+
+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:
+
+```ts
+const Pair = tuple.narrow<[unknown, unknown]>();
+const NumberPair = Pair.narrow([0, 0]);
+
+NumberPair(10, 20); // OK
+NumberPair(10, "20"); // TypeScript error
+```
+
+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
 
-JavaScript doesn't have value-based arrays, so this doesn't work:
+Without interning, separately constructed arrays don't work as value-based keys:
 
 ```ts
 const map = new Map();
 
 map.set([10, 20], "visited");
-
 map.get([10, 20]); // undefined
 ```
 
@@ -92,18 +119,13 @@ With `tuple-ts`:
 const map = new Map();
 
 map.set(tuple(10, 20), "visited");
-
 map.get(tuple(10, 20)); // "visited"
 ```
 
-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.
+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.
 
 ### `Set` of values
 
-The same applies to `Set`:
-
 ```ts
 const visited = new Set();
 
@@ -117,25 +139,16 @@ No serialization, stringification, or custom hashing is required.
 
 ## Nested tuples
 
-Tuples can be nested:
+Tuples can contain other interned tuples:
 
 ```ts
-const a = tuple(
-  "matrix",
-  tuple(1, 0),
-  tuple(0, 1),
-);
-
-const b = tuple(
-  "matrix",
-  tuple(1, 0),
-  tuple(0, 1),
-);
+const a = tuple("matrix", tuple(1, 0), tuple(0, 1));
+const b = tuple("matrix", tuple(1, 0), tuple(0, 1));
 
 a === b; // true
 ```
 
-Because nested tuples themselves have value-based identity, the resulting structures are canonicalised naturally.
+Because the inner tuples are themselves canonicalised, the outer tuples can be interned as well.
 
 ```ts
 const a = tuple("a", tuple("b", "c"));
@@ -146,461 +159,171 @@ a === b; // true
 a === c; // false
 ```
 
-## Typed tuples
-
-Use `tuple.like()` to create a reusable constructor for a particular tuple type.
-
-### Inferring the type from an exemplar
-
-```ts
-const Point = tuple.like(0, 0);
-
-const a = Point(10, 20);
-const b = Point(10, 20);
-
-a === b; // true
-```
-
-The exemplar determines the TypeScript type expected by the resulting factory. Its values are not used as defaults.
-
-By default, TypeScript widens the exemplar's literal types, so `tuple.like(0, 0)` produces a factory accepting two numbers.
-
-### Explicit type arguments
+## Named tuples with `struct()`
 
-Alternatively, specify the type directly:
+Use `struct()` when you want positional tuple storage with meaningful labels. Pass a readonly label list to create a reusable factory:
 
 ```ts
-type Point = [x: number, y: number];
-
-const Point = tuple.like<Point>();
-
-const a = Point(10, 20);
-const b = Point(10, 20);
-
-a === b; // true
-```
-
-No exemplar is required when the type argument is provided explicitly.
+import { struct } from "tuple-ts";
 
-### Preserving literal types
+const Point = struct(["x", "y"]).narrow<[number, number]>();
 
-To preserve literal types rather than widen them, use `as const`:
+const p = Point(10, 20);
 
-```ts
-const Direction = tuple.like("north" as const, 1 as const);
+p[0]; // 10
+p[1]; // 20
+p.x;  // 10
+p.y;  // 20
 
-Direction("north", 1); // OK
-Direction("south", 1); // TypeScript error
+Array.isArray(p);   // true
+Object.isFrozen(p); // true
 ```
 
-In all cases, the resulting tuples are frozen and interned using the same shared cache as ordinary tuples.
+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.
 
-## Records
+### Constructing from a named object with `.from()`
 
-`record` provides the same value-based identity semantics for objects:
+`.from()` accepts an object with the declared labels and creates the corresponding positional tuple:
 
 ```ts
-import { record } from "tuple-ts";
+const Point = struct(["x", "y"]).narrow<[number, number]>();
 
-const a = record({
-  id: 1,
-  role: "admin",
-});
-
-const b = record({
-  role: "admin",
-  id: 1,
-});
+const a = Point.from({ x: 10, y: 20 });
+const b = Point.from({ y: 20, x: 10 });
 
 a === b; // true
-```
-
-Property order does not matter.
-
-Records are frozen:
-
-```ts
-Object.isFrozen(a); // true
-```
-
-And they work naturally as `Map` keys:
-
-```ts
-const users = new Map();
 
-users.set(
-  record({ id: 42, role: "admin" }),
-  "Alice",
-);
-
-users.get(
-  record({ role: "admin", id: 42 }),
-); // "Alice"
+a[0]; // 10
+a.x;  // 10
 ```
 
-### Record identity
-
-A record's identity is determined by its own, enumerable, string-keyed properties and their values.
-
-Two records are equivalent if they contain exactly the same keys, with equivalent values, regardless of property order.
+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
-record({ x: 1, y: 2 }) ===
-record({ y: 2, x: 1 }); // true
+const p = Point.from({ x: 10, y: 20, altitude: 100 });
 
-record({ x: 1 }) ===
-record({ x: 1, y: 2 }); // false
+p.x; // 10
+p.y; // 20
 ```
 
-Symbol-keyed, inherited and non-enumerable properties are not copied into records.
+The returned value contains the tuple slots and the schema's named properties, not the unrelated input properties.
 
-Numeric property keys are supported and follow JavaScript's normal conversion to string keys.
+### Constraining a struct factory
 
-### Typed records
-
-Use `record.like()` to create a reusable typed record constructor:
+Use `.narrow()` to specify the tuple's positional types:
 
 ```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
-```
-
-Alternatively, infer the type from an exemplar:
+const Point = struct(["x", "y"]).narrow<[number, number]>();
 
-```ts
-const User = record.like({
-  id: "",
-  name: "",
-  updatedAt: 0,
-});
+Point(10, 20);   // OK
+Point(10, "20"); // TypeScript error
 ```
 
-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.
+Use `.narrowFrom()` when you want to express the value types by label instead:
 
 ```ts
-const User = record.like({ id: "" });
+type Coordinates = { x: number; y: number };
 
-const a = User({ id: "alice" });
-const b = User({ id: "alice", role: "admin" });
+const Point = struct(["x", "y"]).narrowFrom<Coordinates>();
 
-a === b; // false
+Point(10, 20);    // OK
+Point(10, "20"); // TypeScript error
+Point.from({ x: 10, y: 20 }); // OK
 ```
 
-## Structs
-
-`record` interns whatever properties you give it. If you want a fixed set of keys to define identity, use `struct`.
-
-`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.
+You can also provide a typed exemplar to `.narrowFrom()`:
 
 ```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 });
-
-a === b; // true
+const coordinateExample: Coordinates = { x: 0, y: 0 };
+const Point = struct(["x", "y"]).narrowFrom(coordinateExample);
 ```
 
-### Additional properties are discarded
-
-Unlike `record`, a struct factory ignores properties that are not part of its declared structure:
-
-```ts
-const Point = struct("x", "y");
+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`.
 
-const a = Point({ x: 1, y: 2 });
-const b = Point({ x: 1, y: 2, z: 3 });
+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.
 
-a === b; // true
-```
+### Struct schemas and identity
 
-The resulting objects contain only `x` and `y`:
+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:
 
 ```ts
-Object.keys(b); // ["x", "y"]
+const PointA = struct(["x", "y"]).narrow<[number, number]>();
+const PointB = struct(["x", "y"]).narrow<[number, number]>();
 
-b.z; // TypeScript error
+PointA(1, 2) === PointA(1, 2); // true
+PointA(1, 2) === PointB(1, 2); // false
 ```
 
-This makes structs useful for projecting larger objects into canonical values with a precisely defined shape.
+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.
 
-```ts
-const Position = struct("x", "y");
+### Choosing labels
 
-const location = {
-  x: 10,
-  y: 20,
-  altitude: 100,
-  timestamp: Date.now(),
-};
-
-const position = Position(location);
-// { x: 10, y: 20 }
-```
-
-The factory is deliberately permissive about additional input properties, but strict about which properties appear in its output.
-
-### Typed structs
-
-Use `struct(...keys).like()` to constrain the types of the declared properties.
-
-The type can be inferred from an exemplar:
-
-```ts
-const Point = struct("x", "y").like({
-  x: 0,
-  y: 0,
-});
-
-Point({ x: 10, y: 20 });    // OK
-Point({ x: "10", y: 20 });  // TypeScript error
-```
-
-Or provided explicitly:
-
-```ts
-type Coordinates = {
-  x: number;
-  y: number;
-};
-
-const Point = struct("x", "y").like<Coordinates>();
-
-Point({ x: 10, y: 20 }); // OK
-```
-
-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`:
-
-```ts
-const Point = struct("x", "y");
-
-Point.like({
-  x: 0,
-  y: 0,
-  z: 0, // TypeScript error: unexpected property
-});
-```
-
-But the resulting factory accepts extra properties and discards them:
-
-```ts
-const Point = struct("x", "y").like({
-  x: 0,
-  y: 0,
-});
-
-Point({ x: 10, y: 20, z: 30 }); // OK
-// { x: 10, y: 20 }
-```
-
-This keeps struct definitions precise without making callers manually remove unrelated properties from their input objects.
+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.
 
 ## 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 they are themselves interned:
 
 ```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.
+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, 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:
+Tuples and structs returned by `tuple-ts` are frozen. Freezing is shallow, just like `Object.freeze()`:
 
 ```ts
 const details = { name: "Alice" };
-const user = record({ details });
+const value = tuple(details);
 
-details.name = "Bob"; // Allowed
+details.name = "Bob"; // Allowed: the nested object itself is not frozen
 ```
 
-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.
+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 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()`.
+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 particularly useful when you want **small immutable values with stable identity**:
+`tuple-ts` is useful when you want small immutable values with stable identity:
 
 - Composite `Map` keys
 - `Set` membership
 - Memoization keys
-- Graph/search states
+- Graph and search states
 - Coordinates and other multi-dimensional values
 - Functional programming
 - Immutable application state
-- Canonical representations of frequently repeated values
+- Named, slot-based values such as points or pairs
 
-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**.
+Use `tuple()` for positional values and `struct()` when the same kind of value benefits from stable field labels.
 
 ## 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.
-
-Constructed records and structs are copied before interning, so callers cannot alter an interned value by modifying the source object.
+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.
 
 There are no runtime dependencies.
 

package/dist/index.d.ts

@@ -1,68 +1,33 @@
 import InternCache from "./intern-cache";
-type NoExtraKeys<T, K extends PropertyKey> = T & Record<Exclude<keyof T, K>, never>;
-type BaseKey = string | number;
 type BaseTuple = readonly unknown[];
-type BaseRecord<K extends BaseKey> = Record<K, unknown>;
-export declare const _tupleCache: InternCache<number, readonly unknown[]>;
-export declare const _recordCache: InternCache<number, Record<BaseKey, unknown>>;
-export declare const tuple: (<const T_ extends BaseTuple>(...t: T_) => Readonly<T_>) & {
-    like: <T_ extends BaseTuple>(...exemplar: [] | T_) => (<const T__1 extends T_>(...t: T__1) => Readonly<T__1>) & {
-        like: <T__1 extends T_>(...exemplar: [] | T__1) => (<const T__2 extends T__1>(...t: T__2) => Readonly<T__2>) & {
-            like: <T__2 extends T__1>(...exemplar: [] | T__2) => (<const T__3 extends T__2>(...t: T__3) => Readonly<T__3>) & {
-                like: <T__3 extends T__2>(...exemplar: [] | T__3) => (<const T__4 extends T__3>(...t: T__4) => Readonly<T__4>) & {
-                    like: <T__4 extends T__3>(...exemplar: [] | T__4) => (<const T__5 extends T__4>(...t: T__5) => Readonly<T__5>) & {
-                        like: <T__5 extends T__4>(...exemplar: [] | T__5) => (<const T__6 extends T__5>(...t: T__6) => Readonly<T__6>) & {
-                            like: <T__6 extends T__5>(...exemplar: [] | T__6) => (<const T__7 extends T__6>(...t: T__7) => Readonly<T__7>) & {
-                                like: <T__7 extends T__6>(...exemplar: [] | T__7) => (<const T__8 extends T__7>(...t: T__8) => Readonly<T__8>) & {
-                                    like: <T__8 extends T__7>(...exemplar: [] | T__8) => (<const T__9 extends T__8>(...t: T__9) => Readonly<T__9>) & {
-                                        like: <T__9 extends T__8>(...exemplar: [] | T__9) => (<const T__10 extends T__9>(...t: T__10) => Readonly<T__10>) & {
-                                            like: <T__10 extends T__9>(...exemplar: [] | T__10) => (<const T__11 extends T__10>(...t: T__11) => Readonly<T__11>) & /*elided*/ any;
-                                        };
-                                    };
-                                };
-                            };
-                        };
-                    };
-                };
-            };
-        };
-    };
+type BaseLabels = readonly string[];
+type ObjectOf<T extends BaseTuple, L extends BaseLabels> = {
+    [I in Extract<keyof L, `${number}`> as L[I]]: T[I extends `${infer N extends number}` ? N : never];
 };
-export declare const record: (<const R_ extends BaseRecord<BaseKey>>(r: R_) => Readonly<Pick<R_, Extract<keyof R_, BaseKey>>>) & {
-    like: <R_ extends BaseRecord<BaseKey>>(exemplar?: NoExtraKeys<R_, BaseKey> | undefined) => (<const R__1 extends R_>(r: R__1) => Readonly<Pick<R__1, Extract<keyof R__1, BaseKey>>>) & {
-        like: <R__1 extends R_>(exemplar?: NoExtraKeys<R__1, BaseKey> | undefined) => (<const R__2 extends R__1>(r: R__2) => Readonly<Pick<R__2, Extract<keyof R__2, BaseKey>>>) & {
-            like: <R__2 extends R__1>(exemplar?: NoExtraKeys<R__2, BaseKey> | undefined) => (<const R__3 extends R__2>(r: R__3) => Readonly<Pick<R__3, Extract<keyof R__3, BaseKey>>>) & {
-                like: <R__3 extends R__2>(exemplar?: NoExtraKeys<R__3, BaseKey> | undefined) => (<const R__4 extends R__3>(r: R__4) => Readonly<Pick<R__4, Extract<keyof R__4, BaseKey>>>) & {
-                    like: <R__4 extends R__3>(exemplar?: NoExtraKeys<R__4, BaseKey> | undefined) => (<const R__5 extends R__4>(r: R__5) => Readonly<Pick<R__5, Extract<keyof R__5, BaseKey>>>) & {
-                        like: <R__5 extends R__4>(exemplar?: NoExtraKeys<R__5, BaseKey> | undefined) => (<const R__6 extends R__5>(r: R__6) => Readonly<Pick<R__6, Extract<keyof R__6, BaseKey>>>) & {
-                            like: <R__6 extends R__5>(exemplar?: NoExtraKeys<R__6, BaseKey> | undefined) => (<const R__7 extends R__6>(r: R__7) => Readonly<Pick<R__7, Extract<keyof R__7, BaseKey>>>) & {
-                                like: <R__7 extends R__6>(exemplar?: NoExtraKeys<R__7, BaseKey> | undefined) => (<const R__8 extends R__7>(r: R__8) => Readonly<Pick<R__8, Extract<keyof R__8, BaseKey>>>) & {
-                                    like: <R__8 extends R__7>(exemplar?: NoExtraKeys<R__8, BaseKey> | undefined) => (<const R__9 extends R__8>(r: R__9) => Readonly<Pick<R__9, Extract<keyof R__9, BaseKey>>>) & {
-                                        like: <R__9 extends R__8>(exemplar?: NoExtraKeys<R__9, BaseKey> | undefined) => (<const R__10 extends R__9>(r: R__10) => Readonly<Pick<R__10, Extract<keyof R__10, BaseKey>>>) & {
-                                            like: <R__10 extends R__9>(exemplar?: NoExtraKeys<R__10, BaseKey> | undefined) => (<const R__11 extends R__10>(r: R__11) => Readonly<Pick<R__11, Extract<keyof R__11, BaseKey>>>) & /*elided*/ any;
-                                        };
-                                    };
-                                };
-                            };
-                        };
-                    };
-                };
-            };
-        };
-    };
+type StructOf<T extends BaseTuple, L extends BaseLabels> = Readonly<T & ObjectOf<T, L>>;
+type TupleFromObject<T extends BaseTuple, L extends BaseLabels, O extends ObjectOf<T, L>> = T & {
+    [I in keyof L]: O[L[I]];
+};
+type StructFactory<T extends BaseTuple, L extends BaseLabels> = (<const T_ extends T>(...args: T_) => StructOf<T_, L>) & {
+    from: <const O extends ObjectOf<T, L>>(arg: O) => Readonly<O & TupleFromObject<T, L, O>>;
+    narrow: <const T_ extends T>() => StructFactory<T_, L>;
+    narrowFrom: <const O extends ObjectOf<T, L>>(..._args: [exemplar: O] | []) => StructFactory<{
+        [I in keyof L]: O[L[I]];
+    }, L>;
 };
-export declare const struct: <const K extends string>(...keys: readonly K[]) => (<const R_ extends BaseRecord<K>>(r: R_) => Readonly<Pick<R_, Extract<keyof R_, K>>>) & {
-    like: <R_ extends BaseRecord<K>>(exemplar?: NoExtraKeys<R_, K> | undefined) => (<const R__1 extends R_>(r: R__1) => Readonly<Pick<R__1, Extract<keyof R__1, K>>>) & {
-        like: <R__1 extends R_>(exemplar?: NoExtraKeys<R__1, K> | undefined) => (<const R__2 extends R__1>(r: R__2) => Readonly<Pick<R__2, Extract<keyof R__2, K>>>) & {
-            like: <R__2 extends R__1>(exemplar?: NoExtraKeys<R__2, K> | undefined) => (<const R__3 extends R__2>(r: R__3) => Readonly<Pick<R__3, Extract<keyof R__3, K>>>) & {
-                like: <R__3 extends R__2>(exemplar?: NoExtraKeys<R__3, K> | undefined) => (<const R__4 extends R__3>(r: R__4) => Readonly<Pick<R__4, Extract<keyof R__4, K>>>) & {
-                    like: <R__4 extends R__3>(exemplar?: NoExtraKeys<R__4, K> | undefined) => (<const R__5 extends R__4>(r: R__5) => Readonly<Pick<R__5, Extract<keyof R__5, K>>>) & {
-                        like: <R__5 extends R__4>(exemplar?: NoExtraKeys<R__5, K> | undefined) => (<const R__6 extends R__5>(r: R__6) => Readonly<Pick<R__6, Extract<keyof R__6, K>>>) & {
-                            like: <R__6 extends R__5>(exemplar?: NoExtraKeys<R__6, K> | undefined) => (<const R__7 extends R__6>(r: R__7) => Readonly<Pick<R__7, Extract<keyof R__7, K>>>) & {
-                                like: <R__7 extends R__6>(exemplar?: NoExtraKeys<R__7, K> | undefined) => (<const R__8 extends R__7>(r: R__8) => Readonly<Pick<R__8, Extract<keyof R__8, K>>>) & {
-                                    like: <R__8 extends R__7>(exemplar?: NoExtraKeys<R__8, K> | undefined) => (<const R__9 extends R__8>(r: R__9) => Readonly<Pick<R__9, Extract<keyof R__9, K>>>) & {
-                                        like: <R__9 extends R__8>(exemplar?: NoExtraKeys<R__9, K> | undefined) => (<const R__10 extends R__9>(r: R__10) => Readonly<Pick<R__10, Extract<keyof R__10, K>>>) & {
-                                            like: <R__10 extends R__9>(exemplar?: NoExtraKeys<R__10, K> | undefined) => (<const R__11 extends R__10>(r: R__11) => Readonly<Pick<R__11, Extract<keyof R__11, K>>>) & /*elided*/ any;
+export declare const _tupleCache: InternCache<number, readonly unknown[], readonly unknown[]>;
+export declare const tuple: (<const T_ extends BaseTuple>(...args: T_) => T_) & {
+    narrow: <T_ extends BaseTuple>(..._args: [] | [exemplar: T_]) => (<const T__1 extends T_>(...args: T__1) => T__1) & {
+        narrow: <T__1 extends T_>(..._args: [] | [exemplar: T__1]) => (<const T__2 extends T__1>(...args: T__2) => T__2) & {
+            narrow: <T__2 extends T__1>(..._args: [] | [exemplar: T__2]) => (<const T__3 extends T__2>(...args: T__3) => T__3) & {
+                narrow: <T__3 extends T__2>(..._args: [] | [exemplar: T__3]) => (<const T__4 extends T__3>(...args: T__4) => T__4) & {
+                    narrow: <T__4 extends T__3>(..._args: [] | [exemplar: T__4]) => (<const T__5 extends T__4>(...args: T__5) => T__5) & {
+                        narrow: <T__5 extends T__4>(..._args: [] | [exemplar: T__5]) => (<const T__6 extends T__5>(...args: T__6) => T__6) & {
+                            narrow: <T__6 extends T__5>(..._args: [] | [exemplar: T__6]) => (<const T__7 extends T__6>(...args: T__7) => T__7) & {
+                                narrow: <T__7 extends T__6>(..._args: [] | [exemplar: T__7]) => (<const T__8 extends T__7>(...args: T__8) => T__8) & {
+                                    narrow: <T__8 extends T__7>(..._args: [] | [exemplar: T__8]) => (<const T__9 extends T__8>(...args: T__9) => T__9) & {
+                                        narrow: <T__9 extends T__8>(..._args: [] | [exemplar: T__9]) => (<const T__10 extends T__9>(...args: T__10) => T__10) & {
+                                            narrow: <T__10 extends T__9>(..._args: [] | [exemplar: T__10]) => (<const T__11 extends T__10>(...args: T__11) => T__11) & /*elided*/ any;
                                         };
                                     };
                                 };
@@ -74,5 +39,6 @@ export declare const struct: <const K extends string>(...keys: readonly K[]) =>
         };
     };
 };
+export declare const struct: <const L extends readonly string[]>(labels: L) => StructFactory<BaseTuple, L>;
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,WAAW,MAAM,gBAAgB,CAAC;AAGzC,KAAK,WAAW,CAAC,CAAC,EAAE,CAAC,SAAS,WAAW,IAAI,CAAC,GAC5C,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AAErC,KAAK,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAC/B,KAAK,SAAS,GAAG,SAAS,OAAO,EAAE,CAAC;AACpC,KAAK,UAAU,CAAC,CAAC,SAAS,OAAO,IAAI,MAAM,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AA+CxD,eAAO,MAAM,WAAW,yCAAoD,CAAC;AAE7E,eAAO,MAAM,YAAY,+CAQxB,CAAC;AAEF,eAAO,MAAM,KAAK,UAhCP,EAAE;WAEA,EAAE;;;;;;;;;;;;;;;;;;;;;CA8BmB,CAAC;AAEnC,eAAO,MAAM,MAAM,UAxBR,EAAE;WAKA,EAAE;;;;;;;;;;;;;;;;;;;;;CAmBqB,CAAC;AAErC,eAAO,MAAM,MAAM,GAAI,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,MAAM,SAAS,CAAC,EAAE,aA1BzD,EAAE;WAKA,EAAE;;;;;;;;;;;;;;;;;;;;;CAsBK,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,WAAW,MAAM,gBAAgB,CAAC;AAGzC,KAAK,SAAS,GAAG,SAAS,OAAO,EAAE,CAAC;AACpC,KAAK,UAAU,GAAG,SAAS,MAAM,EAAE,CAAC;AAqBpC,KAAK,QAAQ,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,SAAS,UAAU,IAAI;KACxD,CAAC,IAAI,OAAO,CACX,MAAM,CAAC,EACP,GAAG,MAAM,EAAE,CACZ,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,MAAM,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC;CACjE,CAAC;AACF,KAAK,QAAQ,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,SAAS,UAAU,IAAI,QAAQ,CACjE,CAAC,GAAG,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CACnB,CAAC;AACF,KAAK,eAAe,CAClB,CAAC,SAAS,SAAS,EACnB,CAAC,SAAS,UAAU,EACpB,CAAC,SAAS,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,IACtB,CAAC,GAAG;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC;AAEpC,KAAK,aAAa,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,SAAS,UAAU,IAAI,CAAC,CAC/D,KAAK,CAAC,EAAE,SAAS,CAAC,EAElB,GAAG,IAAI,EAAE,EAAE,KACR,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG;IACtB,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,SAAS,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,EACnC,GAAG,EAAE,CAAC,KACH,QAAQ,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC5C,MAAM,EAAE,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,OAAO,aAAa,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IACvD,UAAU,EAAE,CACV,KAAK,CAAC,CAAC,SAAS,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,EAG9B,GAAG,KAAK,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,GAAG,EAAE,KACzB,aAAa,CAAC;SAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KAAE,EAAE,CAAC,CAAC,CAAC;CACpD,CAAC;AA4CF,eAAO,MAAM,WAAW,6DAIvB,CAAC;AAEF,eAAO,MAAM,KAAK,UAvFS,EAAE;aAEX,EAAE;;;;;;;;;;;;;;;;;;;;;CAqFyB,CAAC;AAE9C,eAAO,MAAM,MAAM,GAAI,KAAK,CAAC,CAAC,SAAS,SAAS,MAAM,EAAE,EAAE,QAAQ,CAAC,gCAelE,CAAC"}

package/dist/index.js

@@ -9,23 +9,36 @@ function arrayEquivalent(a1, a2) {
     }
     return true;
 }
-function recordEquivalent(r1, r2) {
-    const r1Keys = Object.keys(r1);
-    const r2Keys = Object.keys(r2);
-    if (r2Keys.length !== r1Keys.length)
-        return false;
-    return r1Keys.every(k => Object.hasOwn(r2, k) && Object.is(r1[k], r2[k]));
-}
-const defineTuple = () => Object.assign((...t) => _tupleCache.get(t), {
-    like: (...exemplar) => defineTuple(),
-});
-const defineRecord = (keys) => Object.assign((r) => _recordCache.get(Object.fromEntries(keys ? keys.map((k) => [k, r[k]]) : Object.entries(r))), {
-    like: (exemplar) => defineRecord(keys),
-});
-export const _tupleCache = new InternCache(hash.valuesHash, arrayEquivalent);
-export const _recordCache = new InternCache((r) => hash.valuesHash(Object.keys(r)
-    .sort()
-    .flatMap((k) => [k, r[k]])), recordEquivalent);
+const defineTuple = () => {
+    const construct = (...args) => _tupleCache.get(args);
+    const narrow = (..._args) => defineTuple();
+    return Object.assign(construct, { narrow });
+};
+const defineStruct = (cache, labels) => {
+    const construct = (...args) => {
+        return cache.get(args);
+    };
+    const fromTuple = (...args) => {
+        return construct(...args);
+    };
+    const fromObject = (arg) => {
+        const args = labels.map((label) => arg[label]);
+        return construct(...args);
+    };
+    const narrow = (..._args) => defineStruct(cache, labels);
+    const narrowFrom = (..._args) => defineStruct(cache, labels);
+    return Object.assign(fromTuple, { from: fromObject, narrow, narrowFrom });
+};
+export const _tupleCache = new InternCache(hash.valuesHash, arrayEquivalent, Object.freeze);
 export const tuple = defineTuple();
-export const record = defineRecord();
-export const struct = (...keys) => defineRecord(keys);
+export const struct = (labels) => {
+    const cacheInjestFn = (tuple) => {
+        const labeledTuple = tuple;
+        labels.forEach((label, index) => {
+            labeledTuple[label] = tuple[index];
+        });
+        return Object.freeze(labeledTuple);
+    };
+    const cache = new InternCache(hash.valuesHash, arrayEquivalent, cacheInjestFn);
+    return defineStruct(cache, labels);
+};

package/dist/intern-cache.d.ts

@@ -1,11 +1,12 @@
-export default class<H, T extends object> {
+export default class<H, K, V extends object> {
     private readonly hashFn;
     private readonly matchFn;
+    private readonly injestFn;
     private readonly map;
-    private cleanupRegistry;
-    constructor(hashFn: (value: T) => H, matchFn: (a: T, b: T) => boolean);
+    private readonly cleanupRegistry;
+    constructor(hashFn: (key: K) => H, matchFn: (key: K, value: V) => boolean, injestFn: (key: K) => V);
     private remove;
-    get<T_ extends T>(obj: T_): Readonly<T_>;
+    get<K_ extends K, V_ extends V>(key: K_): V_;
     get size(): number;
     reset(): void;
 }

package/dist/intern-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"intern-cache.d.ts","sourceRoot":"","sources":["../src/intern-cache.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,OAAO,CAAC,EAAE,CAAC,SAAS,MAAM;IAOpC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAP1B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAsC;IAC1D,OAAO,CAAC,eAAe,CAErB;gBAGiB,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,EACvB,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO;IAGnD,OAAO,CAAC,MAAM;IAWd,GAAG,CAAC,EAAE,SAAS,CAAC,EAAE,GAAG,EAAE,EAAE,GAAG,QAAQ,CAAC,EAAE,CAAC;IAsBxC,IAAI,IAAI,IAAI,MAAM,CAKjB;IAED,KAAK,IAAI,IAAI;CAId"}
+{"version":3,"file":"intern-cache.d.ts","sourceRoot":"","sources":["../src/intern-cache.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,SAAS,MAAM;IAOvC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAR3B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAsC;IAC1D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAE9B;gBAGiB,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,EACrB,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,OAAO,EACtC,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC;IAG1C,OAAO,CAAC,MAAM;IAWd,GAAG,CAAC,EAAE,SAAS,CAAC,EAAE,EAAE,SAAS,CAAC,EAAE,GAAG,EAAE,EAAE,GAAG,EAAE;IAsB5C,IAAI,IAAI,IAAI,MAAM,CAKjB;IAED,KAAK,IAAI,IAAI;CAId"}

package/dist/intern-cache.js

@@ -1,27 +1,28 @@
 export default class {
-    constructor(hashFn, matchFn) {
+    constructor(hashFn, matchFn, injestFn) {
         this.hashFn = hashFn;
         this.matchFn = matchFn;
+        this.injestFn = injestFn;
         this.map = new Map();
         this.cleanupRegistry = new FinalizationRegistry((x) => this.remove(x));
     }
-    remove([hash, ref]) {
+    remove([hash, valueRef]) {
         const hashBucket = this.map.get(hash);
         if (!hashBucket) {
             return;
         }
-        hashBucket.delete(ref);
+        hashBucket.delete(valueRef);
         if (hashBucket.size === 0) {
             this.map.delete(hash);
         }
     }
-    get(obj) {
-        const hash = this.hashFn(obj);
+    get(key) {
+        const hash = this.hashFn(key);
         let hashBucket = this.map.get(hash);
         if (hashBucket !== undefined) {
             for (const ref of hashBucket) {
                 const o = ref.deref();
-                if (o && this.matchFn(obj, o))
+                if (o && this.matchFn(key, o))
                     return o;
             }
         }
@@ -31,17 +32,17 @@ export default class {
             this.map.set(hash, hashBucket);
         }
         // Object is not in the cache. Add it and return it.
-        Object.freeze(obj);
-        const ref = new WeakRef(obj);
-        hashBucket.add(ref);
-        this.cleanupRegistry.register(obj, [hash, ref]);
-        return obj;
+        const value = this.injestFn(key);
+        const valueRef = new WeakRef(value);
+        hashBucket.add(valueRef);
+        this.cleanupRegistry.register(value, [hash, valueRef], this);
+        return value;
     }
     get size() {
         return Array.from(this.map.entries(), ([_, b]) => b.size).reduce((acc, x) => acc + x, 0);
     }
     reset() {
+        this.cleanupRegistry.unregister(this);
         this.map.clear();
-        this.cleanupRegistry = new FinalizationRegistry((x) => this.remove(x));
     }
 }

package/package.json

@@ -1,11 +1,18 @@
 {
   "type": "module",
   "name": "tuple-ts",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Tuples and structs for TypeScript and JavaScript with equality and identity semantics.",
   "keywords": [
     "tuple",
     "struct",
+    "labeled",
+    "labelled",
+    "labels",
+    "names",
+    "namedtuple",
+    "named-tuple",
+    "python",
     "equality",
     "identity",
     "shallow-equality",