tuple-ts 0.4.6 → 0.5.0

package/README.md

@@ -15,7 +15,7 @@ JavaScript normally compares arrays and objects by reference:
 ```ts
 tuple(1, 2) === tuple(1, 2) // true
 
-struct({ x: 1 }) === struct({ x: 1 }) // true
+record({ x: 1 }) === record({ x: 1 }) // true
 ```
 
 Equal values are **interned to the same object**.
@@ -163,19 +163,19 @@ a === b; // true
 
 The result retains the tuple's TypeScript type while gaining the same runtime identity semantics.
 
-## Structs
+## Records
 
-`struct` provides the same semantics for objects:
+`record` provides the same value-based identity semantics for objects:
 
 ```ts
-import { struct } from "tuple-ts";
+import { record } from "tuple-ts";
 
-const a = struct({
+const a = record({
   id: 1,
   role: "admin",
 });
 
-const b = struct({
+const b = record({
   role: "admin",
   id: 1,
 });
@@ -185,7 +185,7 @@ a === b; // true
 
 Property order does not matter.
 
-Structs are frozen:
+Records are frozen:
 
 ```ts
 Object.isFrozen(a); // true
@@ -197,18 +197,18 @@ And they work naturally as `Map` keys:
 const users = new Map();
 
 users.set(
-  struct({ id: 42, role: "admin" }),
+  record({ id: 42, role: "admin" }),
   "Alice",
 );
 
 users.get(
-  struct({ role: "admin", id: 42 }),
+  record({ role: "admin", id: 42 }),
 ); // "Alice"
 ```
 
-### Typed structs
+### Typed records
 
-As with tuples, you can define a reusable typed constructor:
+As with tuples, you can define a reusable typed constructor by passing a type argument:
 
 ```ts
 interface User {
@@ -217,7 +217,7 @@ interface User {
   updatedAt: number;
 }
 
-const User = struct<User>;
+const User = record<User>;
 
 const a = User({
   id: "alice",
@@ -234,6 +234,34 @@ const b = User({
 a === b; // true
 ```
 
+## Structs
+
+`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`.
+
+`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.
+
+```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
+```
+
+Because the schema is fixed at construction time, equality is always based on precisely those keys — no more, no less:
+
+```ts
+const a = Point({ x: 1, y: 2 });
+const b = Point({ x: 1, y: 3 });
+
+a === b; // false — y differs
+```
+
+All keys passed to `struct` must be distinct strings. Passing duplicate keys throws a `DuplicateKeyError`.
+
 ## Equality semantics
 
 Primitive values are compared using [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is):
@@ -286,7 +314,7 @@ In other words, you don't have to manually maintain a global cache of every tupl
 
 ## TypeScript first
 
-`tuple` and `struct` are designed to preserve TypeScript's inference:
+`tuple`, `record`, and `struct` are designed to preserve TypeScript's inference:
 
 ```ts
 const value = tuple(
@@ -298,10 +326,10 @@ const value = tuple(
 // readonly ["hello", 42, true]
 ```
 
-The library is deliberately small: the runtime API consists of the two constructors you actually need:
+The library is deliberately small: the runtime API consists of three constructors:
 
 ```ts
-import { tuple, struct } from "tuple-ts";
+import { tuple, record, struct } from "tuple-ts";
 ```
 
 ## When should I use it?

package/dist/hash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AAgHA,eAAO,MAAM,UAAU,GAAI,QAAQ,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,MAAM,KAAG,MACtB,CAAC"}
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AA4GA,eAAO,MAAM,UAAU,GAAI,QAAQ,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,MAAM,KAAG,MACtB,CAAC"}

package/dist/hash.js

@@ -26,8 +26,6 @@ function linearCongruentialGenerator(seed = Date.now()) {
     };
 }
 const randomUint32 = linearCongruentialGenerator();
-// const tupleSeed = randomUint32();
-// const structSeed = randomUint32();
 const nullHash = randomUint32();
 const undefinedHash = randomUint32();
 const falseHash = randomUint32();
@@ -75,18 +73,18 @@ function bigintToUint32s(value) {
 function valueHash(value) {
     switch (typeof value) {
         case "string":
-            return mixHashes(stringToUint32s(value), stringSeed);
+            return hashMixFn(stringToUint32s(value), stringSeed);
         case "number":
-            return mixHashes(numberToUint32s(value), numberSeed);
+            return hashMixFn(numberToUint32s(value), numberSeed);
         case "bigint":
-            return mixHashes(bigintToUint32s(value), bigIntSeed);
+            return hashMixFn(bigintToUint32s(value), bigIntSeed);
         case "boolean":
             return value ? trueHash : falseHash;
         case "symbol":
             const k = Symbol.keyFor(value);
             return k === undefined
                 ? stableRandomHash(symbolHashMap, value)
-                : mixHashes(stringToUint32s(k), registeredSymbolSeed);
+                : hashMixFn(stringToUint32s(k), registeredSymbolSeed);
         case "undefined":
             return undefinedHash;
         case "object":
@@ -95,23 +93,5 @@ function valueHash(value) {
             return stableRandomHash(objectHashMap, value);
     }
 }
-const mixHashes = murmurHash3Mix_32bit;
-export const valuesHash = (values, seed) => mixHashes(Array.from(values, valueHash), seed);
-// function valueHashes(values: Iterable<unknown>): Array<number> {
-//   return Array.from(values, valueHash);
-// }
-// export function tupleHash(elements: readonly unknown[]): number {
-//     return mixHashes(valueHashes(elements), tupleSeed);
-// }
-// function keyAndValueHashes(struct: Record<string, unknown>): Array<number> {
-//     return Object.keys(struct).sort().flatMap(key => [
-//         valueHash(key),
-//         valueHash(struct[key])
-//     ]);
-// }
-// export function structHash(struct: Record<string, unknown>): number {
-//   return mixHashes(
-//     keyAndValueHashes(struct),
-//     structSeed
-//   );
-// }
+export const valuesHash = (values, seed) => hashMixFn(Array.from(values, valueHash), seed);
+const hashMixFn = murmurHash3Mix_32bit;

package/dist/index.d.ts

@@ -1,6 +1,11 @@
 import InternCache from "./intern-cache";
 export declare const _tupleCache: InternCache<number, readonly unknown[]>;
-export declare const _structCache: InternCache<number, Record<string, unknown>>;
-export declare const tuple: <const T extends readonly unknown[]>(...t: T) => Readonly<T>;
-export declare const struct: <const T extends Record<string, unknown>>({ ...r }: T) => Readonly<T>;
+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]>;
 //# 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;AAgCzC,eAAO,MAAM,WAAW,yCAGvB,CAAC;AAEF,eAAO,MAAM,YAAY,8CAGxB,CAAC;AAEF,eAAO,MAAM,KAAK,GAAI,KAAK,CAAC,CAAC,SAAS,SAAS,OAAO,EAAE,EAAE,GAAG,GAAG,CAAC,gBAC9B,CAAC;AAEpC,eAAO,MAAM,MAAM,GAAI,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,CAAC,gBACvC,CAAC"}
+{"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"}

package/dist/index.js

@@ -1,7 +1,5 @@
 import InternCache from "./intern-cache";
 import * as hash from "./hash";
-const TUPLE_SEED = 0x7A3F91C2;
-const STRUCT_SEED = 0xE84B26D7;
 function arrayEquivalent(a1, a2) {
     if (a2.length !== a1.length)
         return false;
@@ -11,7 +9,7 @@ function arrayEquivalent(a1, a2) {
     }
     return true;
 }
-function structEquivalent(r1, r2) {
+function recordEquivalent(r1, r2) {
     const r1Keys = Object.keys(r1);
     const r2Keys = Object.keys(r2);
     if (r2Keys.length !== r1Keys.length)
@@ -25,7 +23,27 @@ function structEquivalent(r1, r2) {
     }
     return true;
 }
-export const _tupleCache = new InternCache(hash.valuesHash, arrayEquivalent);
-export const _structCache = new InternCache((r) => hash.valuesHash(Object.entries(r).flat()), structEquivalent);
-export const tuple = (...t) => Object.freeze(_tupleCache.get(t));
-export const struct = ({ ...r }) => Object.freeze(_structCache.get(r));
+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]])));
+};

package/dist/intern-cache.d.ts

@@ -1,11 +1,12 @@
 export default class<H, T extends object> {
-    private readonly map;
     private readonly hashFn;
-    private readonly identityFn;
+    private readonly matchFn;
+    private readonly injestFn;
+    private readonly map;
     private cleanupRegistry;
-    constructor(hashFn: (obj: T) => H, identityFn: (obj1: T, obj2: T) => boolean);
+    constructor(hashFn: (value: T) => H, matchFn: (key: T, target: T) => boolean, injestFn: <T_ extends T>(value: T_) => T_);
     private remove;
-    get<U extends T>(obj: U): U;
+    get<T_ extends T>(key: T_): T_;
     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;IACtC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAsC;IAC1D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAgC;IAC3D,OAAO,CAAC,eAAe,CAErB;gBAGA,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,EACrB,UAAU,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,OAAO;IAM3C,OAAO,CAAC,MAAM;IAWd,GAAG,CAAC,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC;IAqB3B,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,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"}

package/dist/intern-cache.js

@@ -1,9 +1,10 @@
 export default class {
-    constructor(hashFn, identityFn) {
+    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));
-        this.hashFn = hashFn;
-        this.identityFn = identityFn;
     }
     remove([hash, ref]) {
         const hashBucket = this.map.get(hash);
@@ -15,13 +16,13 @@ export default class {
             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.identityFn(o, obj))
+                if (o && this.matchFn(key, o))
                     return o;
             }
         }
@@ -31,6 +32,7 @@ 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]);

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "tuple-ts",
-  "version": "0.4.6",
+  "version": "0.5.0",
   "description": "Tuples and structs for TypeScript and JavaScript with equality and identity semantics.",
   "keywords": [
     "tuple",