tuple-ts 0.5.0 → 0.7.0

package/README.md

@@ -1,26 +1,24 @@
 # tuple-ts
 
-**Immutable tuples 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 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,215 +159,174 @@ a === b; // true
 a === c; // false
 ```
 
-## Typed tuples
+## Named tuples with `struct()`
 
-You can create a reusable constructor for a particular tuple type:
+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];
+import { struct } from "tuple-ts";
 
-const Point = tuple<Point>;
+const Point = struct(["x", "y"]).narrow<[number, number]>();
 
-const a = Point(10, 20);
-const b = Point(10, 20);
+const p = Point(10, 20);
 
-a === b; // true
+p[0]; // 10
+p[1]; // 20
+p.x;  // 10
+p.y;  // 20
+
+Array.isArray(p);   // true
+Object.isFrozen(p); // true
 ```
 
-The result retains the tuple's TypeScript type while gaining the same runtime identity semantics.
+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 a = record({
-  id: 1,
-  role: "admin",
-});
+const Point = struct(["x", "y"]).narrow<[number, number]>();
 
-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
+a[0]; // 10
+a.x;  // 10
 ```
 
-And they work naturally as `Map` keys:
+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 users = new Map();
+const p = Point.from({ x: 10, y: 20, altitude: 100 });
 
-users.set(
-  record({ id: 42, role: "admin" }),
-  "Alice",
-);
-
-users.get(
-  record({ role: "admin", id: 42 }),
-); // "Alice"
+p.x; // 10
+p.y; // 20
 ```
 
-### Typed records
+The returned value contains the tuple slots and the schema's named properties, not the unrelated input properties.
+
+### Constraining a struct factory
 
-As with tuples, you can define a reusable typed constructor by passing a type argument:
+Use `.narrow()` to specify the tuple's positional types:
 
 ```ts
-interface User {
-  id: string;
-  name: string;
-  updatedAt: number;
-}
-
-const User = record<User>;
-
-const a = User({
-  id: "alice",
-  name: "Alice",
-  updatedAt: 1000,
-});
-
-const b = User({
-  name: "Alice",
-  id: "alice",
-  updatedAt: 1000,
-});
+const Point = struct(["x", "y"]).narrow<[number, number]>();
 
-a === b; // true
+Point(10, 20);   // OK
+Point(10, "20"); // TypeScript error
 ```
 
-## Structs
+Use `.narrowFrom()` when you want to express the value types by label instead:
+
+```ts
+type Coordinates = { x: number; y: number };
 
-`record` interns whatever shape you hand it — which means any difference in keys or values produces a different object. If you want something more locked-down, where a fixed declared set of keys defines identity, use `struct`.
+const Point = struct(["x", "y"]).narrowFrom<Coordinates>();
+
+Point(10, 20);    // OK
+Point(10, "20"); // TypeScript error
+Point.from({ x: 10, y: 20 }); // OK
+```
 
-`struct` takes key names as arguments and returns a factory. The factory accepts any object that has at least those keys, extracts exactly those keys, and interns the result.
+You can also provide a typed exemplar to `.narrowFrom()`:
 
 ```ts
-import { struct } from "tuple-ts";
+const coordinateExample: Coordinates = { x: 0, y: 0 };
+const Point = struct(["x", "y"]).narrowFrom(coordinateExample);
+```
 
-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 });
+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
 
-Because the schema is fixed at construction time, equality is always based on precisely those keys — no more, no less:
+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
-const a = Point({ x: 1, y: 2 });
-const b = Point({ x: 1, y: 3 });
+const PointA = struct(["x", "y"]).narrow<[number, number]>();
+const PointB = struct(["x", "y"]).narrow<[number, number]>();
 
-a === b; // false — y differs
+PointA(1, 2) === PointA(1, 2); // true
+PointA(1, 2) === PointB(1, 2); // false
 ```
 
-All keys passed to `struct` must be distinct strings. Passing duplicate keys throws a `DuplicateKeyError`.
+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
+
+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
 
-Primitive 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 and structs work particularly well because they are themselves canonical values.
-
-## Immutable by design
-
-Tuples and structs returned by `tuple-ts` are frozen:
+`tuple-ts` does not recursively compare arbitrary JavaScript objects. Nested tuples work well because they are themselves interned:
 
 ```ts
-const point = tuple(10, 20);
+const a = tuple(tuple(1, 2));
+const b = tuple(tuple(1, 2));
 
-Object.isFrozen(point); // true
+a === b; // true
 ```
 
-This is important to the identity semantics: once a value has been interned, its contents cannot subsequently change while it is being used as a `Map` key or `Set` member.
-
-## Garbage-collection friendly
-
-Interning values creates a natural question: *doesn't the cache grow forever?*
+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.
 
-`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 you've ever created.
-
-## TypeScript first
+## Immutable by design
 
-`tuple`, `record`, and `struct` are designed to preserve TypeScript's inference:
+Tuples and structs returned by `tuple-ts` are frozen. Freezing is shallow, just like `Object.freeze()`:
 
 ```ts
-const value = tuple(
-  "hello",
-  42,
-  true,
-);
+const details = { name: "Alice" };
+const value = tuple(details);
 
-// readonly ["hello", 42, true]
+details.name = "Bob"; // Allowed: the nested object itself is not frozen
 ```
 
-The library is deliberately small: the runtime API consists of three constructors:
+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.
 
-```ts
-import { tuple, record, struct } from "tuple-ts";
-```
+## 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 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
-* coordinates and other multi-dimensional values
-* functional programming
-* immutable application state
-* canonical representations of frequently repeated values
+- 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
 
-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.
-
-The intern cache uses weak references, so canonical values do not need to be kept alive solely because they have previously been created.
+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.
 
 ## License
 
-ISC
+ISC

package/dist/index.d.ts

@@ -1,11 +1,44 @@
 import InternCache from "./intern-cache";
-export declare const _tupleCache: InternCache<number, readonly unknown[]>;
-export declare const _recordCache: InternCache<number, Record<string, unknown>>;
-export declare const tuple: <const T extends readonly unknown[]>(...t: T) => T;
-export declare const record: <const T extends Record<string, unknown>>({ ...r }: T) => T;
-export declare class DuplicateKeyError extends Error {
-    readonly name = "DuplicateKeyError";
-    constructor();
-}
-export declare const struct: <const K extends Array<string>>(...keys: K) => <const T extends Record<K[number], unknown>>(s: T) => Pick<T, K[number]>;
+type BaseTuple = readonly unknown[];
+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];
+};
+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 _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;
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    };
+};
+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;AA6BzC,eAAO,MAAM,WAAW,yCAIvB,CAAC;AAEF,eAAO,MAAM,YAAY,8CASxB,CAAC;AAEF,eAAO,MAAM,KAAK,GAAI,KAAK,CAAC,CAAC,SAAS,SAAS,OAAO,EAAE,EAAE,GAAG,GAAG,CAAC,MAC7C,CAAC;AAErB,eAAO,MAAM,MAAM,GAAI,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,CAAC,MACtD,CAAC;AAEtB,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,SAAkB,IAAI,uBAAuB;;CAI9C;AAED,eAAO,MAAM,MAAM,GAAI,KAAK,CAAC,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,MAAM,CAAC,MAetD,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,uBAOzD,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,41 +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;
-    for (let i = 0; i < r1Keys.length; i++) {
-        const k = r1Keys[i];
-        if (!(k in r2))
-            return false;
-        if (!Object.is(r2[k], r1[k]))
-            return false;
-    }
-    return true;
-}
-export const _tupleCache = new InternCache(hash.valuesHash, arrayEquivalent, (x) => Object.freeze(x));
-export const _recordCache = new InternCache((r) => hash.valuesHash(Object.keys(r)
-    .sort()
-    .flatMap((k) => [k, r[k]])), recordEquivalent, (x) => Object.freeze(x));
-export const tuple = (...t) => _tupleCache.get(t);
-export const record = ({ ...r }) => _recordCache.get(r);
-export class DuplicateKeyError extends Error {
-    constructor() {
-        super("All keys must be distinct.");
-        this.name = "DuplicateKeyError";
-    }
-}
-export const struct = (...keys) => {
-    keys.forEach((k) => {
-        if (typeof k !== "string") {
-            throw new TypeError("All keys must be strings.");
-        }
-    });
-    if (new Set(keys).size !== keys.length) {
-        throw new DuplicateKeyError();
-    }
-    const cache = new InternCache((s) => hash.valuesHash(keys.map((k) => s[k])), (s1, s2) => keys.every((k) => Object.is(s1[k], s2[k])), (r) => Object.fromEntries(keys.map((k) => [k, r[k]])));
-    return (s) => cache.get(Object.fromEntries(keys.map((k) => [k, s[k]])));
+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 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,12 +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: (key: T, target: T) => boolean, injestFn: <T_ extends T>(value: T_) => T_);
+    private readonly cleanupRegistry;
+    constructor(hashFn: (key: K) => H, matchFn: (key: K, value: V) => boolean, injestFn: (key: K) => V);
     private remove;
-    get<T_ extends T>(key: T_): 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;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAR3B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAsC;IAC1D,OAAO,CAAC,eAAe,CAErB;gBAGiB,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,EACvB,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,OAAO,EACvC,QAAQ,EAAE,CAAC,EAAE,SAAS,CAAC,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE;IAG5D,OAAO,CAAC,MAAM;IAWd,GAAG,CAAC,EAAE,SAAS,CAAC,EAAE,GAAG,EAAE,EAAE,GAAG,EAAE;IAsB9B,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

@@ -6,12 +6,12 @@ export default class {
         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);
         }
@@ -32,17 +32,17 @@ export default class {
             this.map.set(hash, hashBucket);
         }
         // Object is not in the cache. Add it and return it.
-        const obj = this.injestFn(key);
-        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.5.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",