tuple-ts 0.4.0 → 0.4.1

package/README.md

@@ -1,161 +1,330 @@
-# TupleTS
+# tuple-ts
 
-TupleTS implements tuples and structs with shallow equality and identity semantics in TypeScript/JavaScript. It is designed to be tiny, fast, and memory-safe.
+**Immutable tuples and structs with value-based identity for JavaScript and TypeScript.**
 
-- **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.
+JavaScript normally compares arrays and objects by reference:
 
----
+```ts
+[1, 2] === [1, 2] // false
+
+{ x: 1 } === { x: 1 } // false
+```
+
+`tuple-ts` gives you a different model:
 
-## Installation
+```ts
+tuple(1, 2) === tuple(1, 2) // true
+
+struct({ x: 1 }) === struct({ x: 1 }) // true
+```
+
+Equal values are **interned to the same object**.
+
+That makes tuples and structs immutable, naturally usable as composite `Map` keys and `Set` values, and particularly pleasant to use in functional TypeScript.
+
+## Install
 
 ```bash
 npm install tuple-ts
 ```
 
----
+## Tuples
+
+Create an immutable tuple with full TypeScript inference:
+
+```ts
+import { tuple } from "tuple-ts";
+
+const point = tuple(10, 20);
+//    ^? readonly [10, 20]
+
+console.log(point[0]); // 10
+console.log(point[1]); // 20
+```
+
+Calling `tuple` again with the same values gives you the **same object**:
 
-## Usage Examples
+```ts
+const a = tuple(10, 20);
+const b = tuple(10, 20);
 
-### 1. Basic Tuples, Identity and Equality
+a === b; // true
+Object.is(a, b); // true
+```
 
-Tuples with the same elements evaluate to the exact same object reference:
+Different values give you different objects:
 
 ```ts
-import { tuple } from "tuple-ts";
+tuple(10, 20) === tuple(10, 21); // false
+tuple(10, 20) === tuple(20, 10); // false
+```
 
-const a = tuple(1, "hello", true);
-const b = tuple(1, "hello", true);
+Tuples are ordinary frozen arrays, so there is no special API to learn:
 
-console.log(a === b); // true
-console.log(Object.is(a, b)); // true
+```ts
+const t = tuple("hello", 42, true);
 
-// Tuples are standard frozen arrays:
-console.log(a[0]);  // 1
-console.log(a.length);  // 3
-console.log([...a]);  // [1, "hello", true]
-console.log(Object.isFrozen(a));  // true
+t.length;       // 3
+t[0];            // "hello"
+[...t];          // ["hello", 42, true]
+Object.isFrozen(t); // true
 ```
 
-### 2. Nested Tuples
+## Why is this useful?
 
-Tuples can be nested arbitrarily and maintain referential equality across structures:
+### Composite `Map` keys
+
+JavaScript doesn't have value-based arrays, so this doesn't work:
 
 ```ts
-import { tuple } from "tuple-ts";
+const map = new Map();
 
-const t1 = tuple("matrix", tuple(1, 0), tuple(0, 1));
-const t2 = tuple("matrix", tuple(1, 0), tuple(0, 1));
-const t3 = tuple("matrix", tuple(1, 1), tuple(0, 1));
+map.set([10, 20], "visited");
 
-console.log(t1 === t2); // true
-console.log(t1 === t3); // false
+map.get([10, 20]); // undefined
 ```
 
-### 3. Composite Keys in `Map` and `Set`
-
-In standard JavaScript, arrays and objects compare by reference, preventing them from being used as composite keys in `Map` or values in `Set`. With `tuple`, structural equality makes composite keys work seamlessly:
+With `tuple-ts`:
 
 ```ts
-import { tuple } from "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.
+
+### `Set` of values
 
-// Set: Deduplicating coordinate pairs
+The same applies to `Set`:
+
+```ts
 const visited = new Set();
+
 visited.add(tuple(10, 20));
 
-console.log(visited.has(tuple(10, 20))); // true!
-console.log(visited.has(tuple(10, 21))); // false
+visited.has(tuple(10, 20)); // true
+visited.has(tuple(10, 21)); // false
+```
+
+No serialization, stringification, or custom hashing is required.
+
+## Nested tuples
 
-// Map: Multi-argument function memoization / 2D grid
-const grid = new Map();
-grid.set(tuple(0, 0), "Origin");
-grid.set(tuple(3, 4), "Target");
+Tuples can be nested:
 
-console.log(grid.get(tuple(0, 0))); // "Origin"
-console.log(grid.get(tuple(3, 4))); // "Target"
+```ts
+const a = tuple(
+  "matrix",
+  tuple(1, 0),
+  tuple(0, 1),
+);
+
+const b = tuple(
+  "matrix",
+  tuple(1, 0),
+  tuple(0, 1),
+);
+
+a === b; // true
 ```
 
-### 4. Custom Typed Tuples
+Because nested tuples themselves have value-based identity, the resulting structures are canonicalised naturally.
+
+```ts
+const a = tuple("a", tuple("b", "c"));
+const b = tuple("a", tuple("b", "c"));
+const c = tuple("a", tuple("b", "d"));
 
-You can easily create custom tuple sub-types:
+a === b; // true
+a === c; // false
+```
+
+## Typed tuples
+
+You can create a reusable constructor for a particular tuple type:
 
 ```ts
-import { tuple } from "tuple-ts";
+type Point = [x: number, y: number];
 
-type Point2D = [x: number, y: number];
-const Point2D = tuple<Point2D>;
+const Point = tuple<Point>;
 
-const p1 = Point2D(12, 34);
-const p2 = Point2D(12, 34);
+const a = Point(10, 20);
+const b = Point(10, 20);
 
-console.log(p1 === p2); // true
-console.log(Object.is(p1, p2)); // true
+a === b; // true
 ```
 
-### 5. Structs
+The result retains the tuple's TypeScript type while gaining the same runtime identity semantics.
 
-Structs with the same keys and values evaluate to the exact same frozen object reference:
+## Structs
+
+`struct` provides the same semantics for objects:
 
 ```ts
 import { struct } from "tuple-ts";
 
-const userA = struct({ id: 1, role: "admin" });
-const userB = struct({ role: "admin", id: 1 }); // different key order
+const a = struct({
+  id: 1,
+  role: "admin",
+});
+
+const b = struct({
+  role: "admin",
+  id: 1,
+});
 
-console.log(userA === userB); // true
-console.log(Object.is(userA, userB)); // true
-console.log(userA.role); // "admin"
-console.log(Object.isFrozen(userA)); // true
+a === b; // true
 ```
 
-### 6. Custom Typed Structs
+Property order does not matter.
 
-As with tuples, you can easily create custom struct sub-types:
+Structs are frozen:
 
 ```ts
-import { struct } from "tuple-ts";
+Object.isFrozen(a); // true
+```
+
+And they work naturally as `Map` keys:
 
+```ts
+const users = new Map();
+
+users.set(
+  struct({ id: 42, role: "admin" }),
+  "Alice",
+);
+
+users.get(
+  struct({ role: "admin", id: 42 }),
+); // "Alice"
+```
+
+### Typed structs
+
+As with tuples, you can define a reusable typed constructor:
+
+```ts
 interface User {
   id: string;
   name: string;
   updatedAt: number;
 }
+
 const User = struct<User>;
 
-const user1 = User({ id: "alice", name: "Alice", updatedAt: 1000 });
-const user2 = User({ name: "Alice", id: "alice", updatedAt: 1000 });
+const a = User({
+  id: "alice",
+  name: "Alice",
+  updatedAt: 1000,
+});
+
+const b = User({
+  name: "Alice",
+  id: "alice",
+  updatedAt: 1000,
+});
 
-console.log(user1 === user2); // true
-console.log(user1.name); // "Alice"
+a === b; // true
 ```
 
-### 7. Memory Safety & Garbage Collection
+## Equality semantics
 
-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.
+Primitive values are compared using [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is):
 
 ```ts
-// No need to manually clear caches or worry about memory leaks.
-{
-  const temp = tuple("transient", 123);
-  // once 'temp' leaves scope and GC runs, the intern cache entry is freed.
-}
+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:
+
+```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:
+
+```ts
+const point = tuple(10, 20);
+
+Object.isFrozen(point); // 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?*
+
+`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
+
+`tuple` and `struct` are designed to preserve TypeScript's inference:
+
+```ts
+const value = tuple(
+  "hello",
+  42,
+  true,
+);
+
+// readonly ["hello", 42, true]
+```
+
+The library is deliberately small: the runtime API consists of the two constructors you actually need:
+
+```ts
+import { tuple, struct } from "tuple-ts";
+```
+
+## When should I use it?
+
+`tuple-ts` is particularly useful when you want **small immutable values with stable identity**:
+
+* composite `Map` keys
+* `Set` membership
+* memoization keys
+* graph/search states
+* coordinates and other multi-dimensional values
+* functional programming
+* immutable application state
+* canonical representations of frequently repeated values
+
+If you just need an ordinary mutable array or object, use one. `tuple-ts` is for when you want the thing to behave more like a **value**.
+
+## Design
+
+The implementation uses hashing to locate candidate values and then performs an exact shallow equality check before reusing an existing value. Hash collisions therefore do not determine equality.
+
+The intern cache uses weak references, so canonical values do not need to be kept alive solely because they have previously been created.
+
+There are no runtime dependencies.
 
-## Equality Semantics
+## License
 
-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 compared by object instance identity:
-  ```ts
-  const shared = { value: 1 };
-  tuple(shared) === tuple(shared); // true
-  tuple({}) !== tuple({});         // true (different object instances)
-  ```
+ISC

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,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"}
+{"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;AA6BvB,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"}

package/dist/index.js

@@ -1,8 +1,6 @@
 import InternCache from "./intern-cache";
 export { InternCache };
 import * as hash from "./hash";
-export const _tupleCache = new InternCache(hash.tupleHash, arrayEquivalent);
-export const _structCache = new InternCache(hash.structHash, structEquivalent);
 function arrayEquivalent(a1, a2) {
     if (a2.length !== a1.length)
         return false;
@@ -26,5 +24,7 @@ function structEquivalent(r1, r2) {
     }
     return true;
 }
+export const _tupleCache = new InternCache(hash.tupleHash, arrayEquivalent);
+export const _structCache = new InternCache(hash.structHash, structEquivalent);
 export const tuple = (...t) => Object.freeze(_tupleCache.get(t));
 export const struct = ({ ...r }) => Object.freeze(_structCache.get(r));

package/dist/struct.spec.js

@@ -25,4 +25,11 @@ describe("struct", () => {
         const b = geocode({ lat: 1, long: 2 });
         expect(a).toBe(b);
     });
+    it("returns frozen instances", () => {
+        const s = struct({ x: 1, y: 2 });
+        expect(Object.isFrozen(s)).toBe(true);
+        expect(() => {
+            s.x = 42;
+        }).toThrow();
+    });
 });

package/dist/tuple.spec.js

@@ -93,3 +93,10 @@ test("Tuple cache entry is cleared when tuple is garbage-collected", async () =>
     await waitForGC();
     expect(_tupleCache.size).toBe(0);
 });
+test("Tuples are frozen", () => {
+    const t = tuple(1, 2, 3);
+    expect(Object.isFrozen(t)).toBe(true);
+    expect(() => {
+        t[0] = 42;
+    }).toThrow();
+});

package/package.json

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