tuple-ts 0.3.1 → 0.4.0

package/README.md

@@ -1,13 +1,14 @@
 # TupleTS
 
-TupleTS is an implementation of tuples and records intended to be memory-safe, performant, and tiny.
+TupleTS implements tuples and structs with shallow equality and identity semantics in TypeScript/JavaScript. It is designed to be tiny, fast, and memory-safe.
 
-- **Referential Equality (`===`)**: Identical tuples and records return the same instance in memory.
-- **Composite Keys for `Set` & `Map`**: Use tuples or records as keys without custom serialization or hashing workarounds.
-- **Memory-Safe**: Uses `WeakRef` and `FinalizationRegistry` to automatically purge entries upon garbage collection.
-- **Deeply Nestable & Immutable**: Tuples can contain other tuples; all created tuples and records are `Object.freeze`'d.
-- **TypeScript First**: Full type inference and type-safe factories.
-- **Zero Dependencies**: Lightweight implementation with fast MurmurHash3-based hashing.
+- **Equality and Identity Semantics (`===` & `Object.is()`)**: Identical tuples and structs map to the same instance in memory.
+- **Composite Keys for `Set` and `Map`**: Use tuples or structs as keys without serialization or hashing workarounds.
+- **Memory-Safe**: No memory leaks ever due to advanced integration with garbage collection.
+- **Deeply Nestable & Immutable**: Tuples and structs can contain other tuples and structs.
+- **TypeScript First**: Full type inference.
+- **Customisable Sub-types**: Easily create your own custom tuple and struct sub-types.
+- **Zero Dependencies**: Lightweight implementation with fast hashing and no dependencies.
 
 ---
 
@@ -21,9 +22,9 @@ npm install tuple-ts
 
 ## Usage Examples
 
-### 1. Basic Tuples & Referential Equality
+### 1. Basic Tuples, Identity and Equality
 
-Tuples with the same elements evaluate to the exact same object reference (`===`):
+Tuples with the same elements evaluate to the exact same object reference:
 
 ```ts
 import { tuple } from "tuple-ts";
@@ -32,11 +33,13 @@ const a = tuple(1, "hello", true);
 const b = tuple(1, "hello", true);
 
 console.log(a === b); // true
+console.log(Object.is(a, b)); // true
 
 // Tuples are standard frozen arrays:
-console.log(a[0]);        // 1
-console.log(a.length);    // 3
-console.log([...a]);      // [1, "hello", true]
+console.log(a[0]);  // 1
+console.log(a.length);  // 3
+console.log([...a]);  // [1, "hello", true]
+console.log(Object.isFrozen(a));  // true
 ```
 
 ### 2. Nested Tuples
@@ -77,61 +80,63 @@ console.log(grid.get(tuple(0, 0))); // "Origin"
 console.log(grid.get(tuple(3, 4))); // "Target"
 ```
 
-### 4. Custom Typed Tuples (`defineTupleType`)
+### 4. Custom Typed Tuples
 
-You can create strictly-typed tuple factories:
+You can easily create custom tuple sub-types:
 
 ```ts
-import { defineTupleType } from "tuple-ts";
+import { tuple } from "tuple-ts";
 
 type Point2D = [x: number, y: number];
-const Point = defineTupleType<Point2D>();
+const Point2D = tuple<Point2D>;
 
-const p1 = Point(12, 34);
-const p2 = Point(12, 34);
+const p1 = Point2D(12, 34);
+const p2 = Point2D(12, 34);
 
 console.log(p1 === p2); // true
+console.log(Object.is(p1, p2)); // true
 ```
 
-### 5. Interned Records (`record`)
+### 5. Structs
 
-Just like tuples, `record` interns shallow objects. Property key insertion order does not affect equality:
+Structs with the same keys and values evaluate to the exact same frozen object reference:
 
 ```ts
-import { record } from "tuple-ts";
+import { struct } from "tuple-ts";
 
-const userA = record({ id: 1, role: "admin" });
-const userB = record({ role: "admin", id: 1 }); // different key order
+const userA = struct({ id: 1, role: "admin" });
+const userB = struct({ role: "admin", id: 1 }); // different key order
 
 console.log(userA === userB); // true
-console.log(userA.role);      // "admin"
+console.log(Object.is(userA, userB)); // true
+console.log(userA.role); // "admin"
+console.log(Object.isFrozen(userA)); // true
 ```
 
-### 6. Custom Typed Records (`defineRecordType`)
+### 6. Custom Typed Structs
 
-As with tuples, you can also create strictly-typed record factories:
+As with tuples, you can easily create custom struct sub-types:
 
 ```ts
-import { defineRecordType } from "tuple-ts";
+import { struct } from "tuple-ts";
 
-interface UserProfile {
+interface User {
   id: string;
   name: string;
   updatedAt: number;
 }
-
-const User = defineRecordType<UserProfile>();
+const User = struct<User>;
 
 const user1 = User({ id: "alice", name: "Alice", updatedAt: 1000 });
 const user2 = User({ name: "Alice", id: "alice", updatedAt: 1000 });
 
 console.log(user1 === user2); // true
-console.log(user1["name"]); // "Alice"
+console.log(user1.name); // "Alice"
 ```
 
 ### 7. Memory Safety & Garbage Collection
 
-TupleTS uses `WeakRef` and `FinalizationRegistry` under the hood. When a tuple or record is no longer referenced anywhere in your program, the JavaScript runtime garbage-collects it, and its entry in the intern cache is automatically pruned.
+TupleTS uses `WeakRef` and `FinalizationRegistry` under the hood. When a tuple or struct is no longer referenced anywhere in your program, the JavaScript runtime garbage-collects it, and its entry in the intern cache is automatically pruned.
 
 ```ts
 // No need to manually clear caches or worry about memory leaks.
@@ -148,9 +153,9 @@ TupleTS uses `WeakRef` and `FinalizationRegistry` under the hood. When a tuple o
 TupleTS compares primitives via `Object.is`:
 - `NaN` is equivalent to `NaN` (`tuple(NaN) === tuple(NaN)`).
 - `+0` and `-0` are treated as distinct values (`tuple(+0) !== tuple(-0)`).
-- Object elements are interned by object identity:
+- Object elements are compared by object instance identity:
   ```ts
   const shared = { value: 1 };
   tuple(shared) === tuple(shared); // true
-  tuple({}) === tuple({});         // false (different object references)
+  tuple({}) !== tuple({});         // true (different object instances)
   ```

package/dist/hash.d.ts

@@ -1,3 +1,3 @@
 export declare function tupleHash(elements: readonly unknown[]): number;
-export declare function recordHash(record: Record<string, unknown>): number;
+export declare function structHash(struct: Record<string, unknown>): number;
 //# sourceMappingURL=hash.d.ts.map

package/dist/hash.js

@@ -27,7 +27,7 @@ function linearCongruentialGenerator(seed = Date.now()) {
 }
 const randomUint32 = linearCongruentialGenerator();
 const tupleSeed = randomUint32();
-const recordSeed = randomUint32();
+const structSeed = randomUint32();
 const nullHash = randomUint32();
 const undefinedHash = randomUint32();
 const falseHash = randomUint32();
@@ -102,12 +102,12 @@ function valueHashes(values) {
 export function tupleHash(elements) {
     return mixHashes(valueHashes(elements), tupleSeed);
 }
-function keyAndValueHashes(record) {
-    return Object.keys(record).sort().flatMap(key => [
+function keyAndValueHashes(struct) {
+    return Object.keys(struct).sort().flatMap(key => [
         valueHash(key),
-        valueHash(record[key])
+        valueHash(struct[key])
     ]);
 }
-export function recordHash(record) {
-    return mixHashes(keyAndValueHashes(record), recordSeed);
+export function structHash(struct) {
+    return mixHashes(keyAndValueHashes(struct), structSeed);
 }

package/dist/index.d.ts

@@ -1,11 +1,7 @@
 import InternCache from "./intern-cache";
 export { InternCache };
-export type TupleType<T extends readonly unknown[]> = (...t: T) => Readonly<T>;
-export type RecordType<T extends Record<string, unknown>> = (r: T) => Readonly<T>;
 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_) => Readonly<T_>;
-export declare const record: <const T_ extends Record<string, unknown>>({ ...r }: T_) => T_;
-export declare const defineTupleType: <T extends readonly unknown[]>() => TupleType<T>;
-export declare const defineRecordType: <T extends Record<string, unknown>>() => RecordType<T>;
+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>;
 //# 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;AACzC,OAAO,EAAE,WAAW,EAAE,CAAC;AAGvB,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,SAAS,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC;AAC/E,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAC1D,CAAC,EAAE,CAAC,KACD,QAAQ,CAAC,CAAC,CAAC,CAAC;AAEjB,eAAO,MAAM,WAAW,yCAGvB,CAAC;AACF,eAAO,MAAM,YAAY,8CAGxB,CAAC;AA4BF,eAAO,MAAM,KAAK,GAAI,KAAK,CAAC,EAAE,SAAS,SAAS,OAAO,EAAE,EAAE,GAAG,GAAG,EAAE,iBAChC,CAAC;AAEpC,eAAO,MAAM,MAAM,GAAI,KAAK,CAAC,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,UAE9D,EAAE,KAAG,EAAwC,CAAC;AAEjD,eAAO,MAAM,eAAe,GACzB,CAAC,SAAS,SAAS,OAAO,EAAE,OAAK,SAAS,CAAC,CAAC,CAEjB,CAAC;AAE/B,eAAO,MAAM,gBAAgB,GAC1B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,OAAK,UAAU,CAAC,CAAC,CAExC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,WAAW,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,CAAC;AAGvB,eAAO,MAAM,WAAW,yCAGvB,CAAC;AACF,eAAO,MAAM,YAAY,8CAGxB,CAAC;AA4BF,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,UAE7D,CAAC,gBAAuC,CAAC"}

package/dist/index.js

@@ -2,7 +2,7 @@ import InternCache from "./intern-cache";
 export { InternCache };
 import * as hash from "./hash";
 export const _tupleCache = new InternCache(hash.tupleHash, arrayEquivalent);
-export const _recordCache = new InternCache(hash.recordHash, recordEquivalent);
+export const _structCache = new InternCache(hash.structHash, structEquivalent);
 function arrayEquivalent(a1, a2) {
     if (a2.length !== a1.length)
         return false;
@@ -12,7 +12,7 @@ function arrayEquivalent(a1, a2) {
     }
     return true;
 }
-function recordEquivalent(r1, r2) {
+function structEquivalent(r1, r2) {
     const r1Keys = Object.keys(r1);
     const r2Keys = Object.keys(r2);
     if (r2Keys.length !== r1Keys.length)
@@ -27,6 +27,4 @@ function recordEquivalent(r1, r2) {
     return true;
 }
 export const tuple = (...t) => Object.freeze(_tupleCache.get(t));
-export const record = ({ ...r }) => Object.freeze(_recordCache.get(r));
-export const defineTupleType = () => (...t) => tuple(...t);
-export const defineRecordType = () => (r) => record(r);
+export const struct = ({ ...r }) => Object.freeze(_structCache.get(r));

package/dist/record.spec.js

@@ -1,18 +1,24 @@
-import { record } from ".";
-describe("record", () => {
+import { struct } from ".";
+describe("struct", () => {
     it("preserves keys and values", () => {
-        const a = record({ x: 1, y: 2 });
+        const a = struct({ x: 1, y: 2 });
         expect(a).toEqual({ x: 1, y: 2 });
     });
     it("returns the same object for shallow-equal input objects", () => {
-        const a = record({ x: 1, y: 2 });
-        const b = record({ x: 1, y: 2 });
+        const a = struct({ x: 1, y: 2 });
+        const b = struct({ x: 1, y: 2 });
         expect(a).toBe(b);
     });
     it("returns different object if keys or values differ", () => {
-        const r = record({ x: 1, y: 2 });
-        expect(record({ x: 1, y: 3 })).not.toBe(r);
-        expect(record({ x: 1, y: 3 })).not.toBe(r);
-        expect(record({ x: 1, y: 2, z: 3 })).not.toBe(r);
+        const r = struct({ x: 1, y: 2 });
+        expect(struct({ x: 1, y: 3 })).not.toBe(r);
+        expect(struct({ x: 1, y: 3 })).not.toBe(r);
+        expect(struct({ x: 1, y: 2, z: 3 })).not.toBe(r);
+    });
+    it("can be customised", () => {
+        const geocode = (struct);
+        const a = geocode({ lat: 1, long: 2 });
+        const b = geocode({ lat: 1, long: 2 });
+        expect(a).toBe(b);
     });
 });

package/dist/struct.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=struct.spec.d.ts.map

package/dist/struct.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"struct.spec.d.ts","sourceRoot":"","sources":["../src/struct.spec.ts"],"names":[],"mappings":""}

package/dist/struct.spec.js

@@ -0,0 +1,28 @@
+import { struct } from ".";
+describe("struct", () => {
+    it("preserves keys and values", () => {
+        const obj = { x: 1, y: 2 };
+        const s = struct(obj);
+        expect(s).toEqual(obj);
+    });
+    it("returns the same object for shallow-equal input objects", () => {
+        const a = struct({ x: 1, y: 2 });
+        const b = struct({ x: 1, y: 2 });
+        expect(a).toBe(b);
+        expect(a === b).toBe(true);
+    });
+    it("returns different object if keys or values differ", () => {
+        const s1 = struct({ x: 1, y: 2 });
+        const s2 = struct({ x: 1, y: 3 });
+        const s3 = struct({ x: 1, y: 2, z: 3 });
+        expect(s1).not.toBe(s2);
+        expect(s1).not.toBe(s3);
+        expect(s1 === s3).toBe(false);
+    });
+    it("can be customised", () => {
+        const geocode = (struct);
+        const a = geocode({ lat: 1, long: 2 });
+        const b = geocode({ lat: 1, long: 2 });
+        expect(a).toBe(b);
+    });
+});

package/dist/tuple.spec.js

@@ -1,4 +1,4 @@
-import { tuple, defineTupleType, _tupleCache } from ".";
+import { tuple, _tupleCache } from ".";
 async function waitForGC() {
     await new Promise((res) => setTimeout(res, 0));
     global.gc(); // requires node --expose-gc
@@ -7,7 +7,8 @@ async function waitForGC() {
 test("Empty tuples", () => {
     const a = tuple();
     const b = tuple();
-    expect(b).toBe(a);
+    expect(b).toBe(a); // identity
+    expect(a === b).toBe(true); // equality
 });
 test("Indexability", () => {
     const a = {};
@@ -27,12 +28,14 @@ test("Basic interned equality (if same input, same object)", () => {
     const f = () => { };
     const t1 = tuple(a, f, 42, "hi", undefined, true, null, 7839278492n);
     const t2 = tuple(a, f, 42, "hi", undefined, true, null, 7839278492n);
-    expect(t1).toBe(t2); // same object reference
+    expect(t1).toBe(t2); // identity
+    expect(t1 === t2).toBe(true); // equality
 });
 test("Referential inequality (same structure, different references)", () => {
     const t1 = tuple({}, 42);
     const t2 = tuple({}, 42);
-    expect(t1).not.toBe(t2); // different objects
+    expect(t1).not.toBe(t2); // non-identity
+    expect(t1 === t2).toBe(false); // non-equality
 });
 test("Different-length tuples are different tuples", () => {
     const t1 = tuple(1, 2);
@@ -46,10 +49,12 @@ test("Nestable", () => {
     const t2 = tuple("a", tuple("b1", "b2"), "c");
     const t3 = tuple("a", tuple("b1", "b3"), "c");
     expect(t2).toBe(t1);
+    expect(t1 === t2).toBe(true);
     expect(t3).not.toBe(t1);
 });
 test("NaN is equivalent to itself", () => {
     expect(tuple(NaN)).toBe(tuple(NaN));
+    expect(tuple(NaN) === tuple(NaN)).toBe(true);
 });
 test("NaN values with different bit representations are interned as identical", () => {
     // Construct NaN with payload 1
@@ -69,14 +74,20 @@ test("NaN values with different bit representations are interned as identical",
     // If NaNs were not canonicalized in numberToUint32s, this would fail (.not.toBe)
     // because nan1 and nan2 would hash to different buckets:
     expect(tuple(nan1)).toBe(tuple(nan2));
+    expect(tuple(nan1) === tuple(nan2)).toBe(true);
 });
 test("Positive and negative zero are distinct", () => {
+    const t1 = tuple(+0);
+    const t2 = tuple(-0);
+    expect(t1).not.toBe(t2);
+    expect(t1 === t2).toBe(false);
     expect(tuple(+0)).not.toBe(tuple(-0));
+    expect(tuple(+0) === tuple(-0)).toBe(false);
 });
 test("Tuple cache entry is cleared when tuple is garbage-collected", async () => {
     _tupleCache.reset();
     expect(_tupleCache.size).toBe(0);
-    const Point = defineTupleType();
+    const Point = (tuple);
     Point(15, 42);
     expect(_tupleCache.size).toBe(1);
     await waitForGC();

package/package.json

@@ -1,21 +1,14 @@
 {
   "type": "module",
   "name": "tuple-ts",
-  "version": "0.3.1",
-  "description": "Python-like tuples for JavaScript/TypeScript",
+  "version": "0.4.0",
+  "description": "Tuples and structs for TypeScript and JavaScript with equality and identity semantics.",
   "keywords": [
     "tuple",
-    "tuples",
-    "record",
-    "records",
-    "interning",
-    "hash-consing",
-    "value-equality",
-    "structural-equality",
-    "composite-key",
-    "immutable",
-    "immutability",
-    "weakref",
+    "struct",
+    "equality",
+    "identity",
+    "shallow-equality",
     "typescript"
   ],
   "main": "./dist/index.js",