tuple-ts 0.9.0 → 0.9.2

package/README.md

@@ -45,7 +45,9 @@ person1 === person2;    // true
 - Coordinates and other multi-dimensional values
 - Named, slot-based values such as points or pairs
 
-`tuple-ts` has zero dependencies and is just a few kilobytes gzipped.
+`tuple-ts` supports tuples containing any values, including only primitives, without sacrificing garbage-collection safety.
+
+`tuple-ts` has zero dependencies and is tiny at around 1 KB when minified and gzipped.
 
 ## Install
 
@@ -60,12 +62,13 @@ The values returned by `tuple(...)` are regular frozen JavaScript arrays:
 ```ts
 const tuple1 = tuple(1, "foo");
 
-Array.isArray(tuple1);   // true
-tuple1.length === 2;     // true
-tuple1[0] === 1;         // true
-tuple1[1] === "foo";     // true
-Object.isFrozen(tuple1); // true
-[ ...tuple1 ];           // [1, "foo"]
+Array.isArray(tuple1);    // true
+tuple1.length === 2;      // true
+tuple1[0] === 1;          // true
+tuple1[1] === "foo";      // true
+Object.isFrozen(tuple1);  // true
+[ ...tuple1 ];            // [1, "foo"]
+tuple.isInstance(tuple1); // true
 ```
 
 ...with automatically inferred literal types:
@@ -113,6 +116,8 @@ const Point = tuple.typed<[number, number]>();
 
 Point(10, 20);   // OK
 Point(10, "20"); // TypeScript error
+
+tuple.isInstance(Point(1, 2)); // true;
 ```
 
 You can alternatively provide an exemplar from which the type constraint will be inferred:
@@ -160,10 +165,11 @@ p[1]; // 20
 p.x;  // 10
 p.y;  // 20
 
-Array.isArray(p);   // true!
-Object.isFrozen(p); // true
-[ ...p ];           // [10, 20]
-{ ...p };           // { 0: 10, 1: 20, x: 10, y: 20 }
+Array.isArray(p);    // true!
+Object.isFrozen(p);  // true
+Point.isInstance(p); // true
+[ ...p ];            // [10, 20]
+{ ...p };            // { 0: 10, 1: 20, x: 10, y: 20 }
 ```
 
 ### Constructing from an object with `.from()`
@@ -196,10 +202,13 @@ The returned value contains the tuple slots and the schema's named properties, n
 Just like `tuple`, structs support `.typed()` to specify the struct's value types positionally:
 
 ```ts
-const Point = struct("x", "y").typed<[number, number]>();
+const XY = struct("x", "y");
+const Point = XY.typed<[number, number]>();
 
 Point(10, 20);   // OK
 Point(10, "20"); // TypeScript error
+
+XY.isInstance(Point(1, 2)); // true!
 ```
 
 Use `.typedFrom()` when you want to express the value types by label instead:

package/dist/index.d.ts

@@ -1,27 +1,32 @@
 import InternCache from "./intern-cache.js";
-type Tuple = readonly unknown[];
-type Labels = readonly string[];
-type NumericKeyOf<T> = keyof T & (number | `${number}`);
 type ToNumber<K> = K extends `${infer N extends number}` ? N : never;
+type Labels = readonly string[];
+type ValidLabels<L extends Labels> = L[number] & keyof (readonly unknown[]) extends never ? L : never;
+type Tuple = readonly unknown[];
+type TupleOfLabels<L extends Labels> = {
+    [I in keyof L]: unknown;
+};
+type ObjectOf<L extends Labels, T extends TupleOfLabels<L>> = {
+    [I in Extract<keyof L, `${number}`> as L[I]]: T[ToNumber<I>];
+};
+type TupleFromObject<L extends Labels, O extends object> = {
+    [I in keyof L]: O[L[I] & keyof O];
+};
 export type TupleFactory<T extends Tuple = Tuple> = {
     <const T_ extends T>(...args: T_): T_;
+    isInstance: (value: unknown) => boolean;
     typed<T_ extends T>(...exemplar: T_ | []): TupleFactory<Readonly<T_>>;
 };
-type ObjectOf<T extends Tuple, L extends Labels> = {
-    [I in NumericKeyOf<L> as L[I]]: T[ToNumber<I>];
-};
-type TupleFromObject<T extends Tuple, L extends Labels, O extends ObjectOf<T, L>> = T & {
-    [I in keyof L]: O[L[I]];
-};
-export type StructFactory<T extends Tuple, L extends Labels> = {
-    <const T_ extends T>(...args: T_): Readonly<T_ & ObjectOf<T_, L>>;
-    from<const O extends ObjectOf<T, L>, const T_ extends TupleFromObject<T, L, O>>(arg: O): Readonly<ObjectOf<T_, L> & T_>;
-    typed<T_ extends T>(...exemplar: T_ | []): StructFactory<Readonly<T_>, L>;
-    typedFrom<O extends ObjectOf<T, L>>(...args: [exemplar: O] | []): StructFactory<{
+export type StructFactory<L extends Labels, T extends TupleOfLabels<L>> = {
+    <const T_ extends T>(...args: T_): Readonly<T_ & ObjectOf<L, T_>>;
+    isInstance: (value: unknown) => boolean;
+    from<const O extends ObjectOf<L, T>, const T_ extends T & TupleFromObject<L, O>>(arg: O): Readonly<ObjectOf<L, T_> & T_>;
+    typed<T_ extends T>(...exemplar: T_ | []): StructFactory<L, Readonly<T_>>;
+    typedFrom<O extends ObjectOf<L, T>>(...args: [exemplar: O] | []): StructFactory<L, {
         [I in keyof L]: O[L[I]];
-    }, L>;
+    }>;
 };
-export declare const _tupleCache: InternCache<number, readonly unknown[], readonly unknown[]>;
+export declare const _tupleCache: InternCache<number, Tuple, Tuple>;
 export declare const tuple: TupleFactory<Tuple>;
-export declare const struct: <const L extends readonly string[]>(...labels: L) => StructFactory<Tuple, L>;
+export declare const struct: <const L extends readonly string[]>(...labels: ValidLabels<L>) => StructFactory<ValidLabels<L>, TupleOfLabels<ValidLabels<L>>>;
 export {};

package/dist/index.js

@@ -1,6 +1,6 @@
 import InternCache from "./intern-cache.js";
 import * as hash from "./hash.js";
-function arrayEquivalent(a1, a2) {
+function tuplesEquivalent(a1, a2) {
     if (a2.length !== a1.length)
         return false;
     for (let i = 0; i < a1.length; i++) {
@@ -9,14 +9,20 @@ function arrayEquivalent(a1, a2) {
     }
     return true;
 }
-const defineTuple = () => {
-    const construct = (...args) => _tupleCache.get(args);
-    const typed = (..._exemplar) => defineTuple();
-    return Object.assign(construct, { typed });
+const defineTuple = (brand) => {
+    const construct = (...args) => _tupleCache.getOrSet(args);
+    const typed = (..._exemplar) => defineTuple(brand);
+    const isInstance = (value) => {
+        return value?.[tupleBrand] === true;
+    };
+    return Object.assign(construct, { typed, isInstance });
 };
-const defineStruct = (cache, labels) => {
+const defineStruct = (cache, labels, brand) => {
+    const isInstance = (value) => {
+        return value?.[brand] === true;
+    };
     const construct = (...args) => {
-        return cache.get(args);
+        return cache.getOrSet(args);
     };
     const fromTuple = (...args) => {
         return construct(...args);
@@ -25,19 +31,25 @@ const defineStruct = (cache, labels) => {
         const args = labels.map((label) => arg[label]);
         return construct(...args);
     };
-    const typed = (..._exemplar) => defineStruct(cache, labels);
-    const typedFrom = (..._args) => defineStruct(cache, labels);
-    return Object.assign(fromTuple, { from: fromObject, typed, typedFrom });
+    const typed = (..._exemplar) => defineStruct(cache, labels, brand);
+    const typedFrom = (..._args) => defineStruct(cache, labels, brand);
+    return Object.assign(fromTuple, { from: fromObject, typed, typedFrom, isInstance });
 };
-export const _tupleCache = new InternCache(hash.valuesHash, arrayEquivalent, Object.freeze);
-export const tuple = defineTuple();
+const tupleBrand = Symbol();
+export const _tupleCache = new InternCache(hash.valuesHash, tuplesEquivalent, (tuple) => {
+    Object.defineProperty(tuple, tupleBrand, { value: true });
+    return Object.freeze(tuple);
+});
+export const tuple = defineTuple(tupleBrand);
 export const struct = (...labels) => {
+    const brand = Symbol();
     const cacheInjestFn = (tuple) => {
         labels.forEach((label, index) => {
             tuple[label] = tuple[index];
         });
+        Object.defineProperty(tuple, brand, { value: true });
         return Object.freeze(tuple);
     };
-    const cache = new InternCache(hash.valuesHash, arrayEquivalent, cacheInjestFn);
-    return defineStruct(cache, labels);
+    const cache = new InternCache(hash.valuesHash, tuplesEquivalent, cacheInjestFn);
+    return defineStruct(cache, labels, brand);
 };

package/dist/intern-cache.d.ts

@@ -1,4 +1,5 @@
-export default class<H, K, V extends object> {
+type Value = symbol | object;
+export default class<H, K, V extends Value> {
     private readonly hashFn;
     private readonly matchFn;
     private readonly injestFn;
@@ -6,7 +7,8 @@ export default class<H, K, V extends object> {
     private readonly cleanupRegistry;
     constructor(hashFn: (key: K) => H, matchFn: (key: K, value: V) => boolean, injestFn: (key: K) => V);
     private remove;
-    get<K_ extends K, V_ extends V>(key: K_): V_;
+    getOrSet<K_ extends K, V_ extends V>(key: K_): V_;
     get size(): number;
     reset(): void;
 }
+export {};

package/dist/intern-cache.js

@@ -19,7 +19,7 @@ export default class {
             this.map.delete(hash);
         }
     }
-    get(key) {
+    getOrSet(key) {
         const hash = this.hashFn(key);
         let hashBucket = this.map.get(hash);
         if (hashBucket !== undefined) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "tuple-ts",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "TypeScript-first tuples and structs with value-based identity",
   "keywords": [
     "tuple",
@@ -33,7 +33,7 @@
     "node": ">=20.0.0"
   },
   "scripts": {
-    "build": "rm -r dist/ && tsc && esbuild src/index.ts --bundle --minify --format=esm --platform=browser --target=es2023 --outfile=dist/tuple-ts.min.js",
+    "build": "rm -r dist/ && tsc",
     "test": "tsc -p tsconfig.test.json --noEmit && vitest run src/",
     "prepare": "npm run build",
     "prepublishOnly": "npm test"
@@ -42,7 +42,6 @@
   "license": "ISC",
   "devDependencies": {
     "@types/node": "^26.6.5",
-    "esbuild": "^0.28.2",
     "typescript": "^7.0.2",
     "vitest": "^4.1.12"
   },

package/dist/tuple-ts.min.js

@@ -1 +0,0 @@
-var u=class{constructor(e,n,t){this.hashFn=e;this.matchFn=n;this.injestFn=t}hashFn;matchFn;injestFn;map=new Map;cleanupRegistry=new FinalizationRegistry(e=>this.remove(e));remove([e,n]){let t=this.map.get(e);t&&(t.delete(n),t.size===0&&this.map.delete(e))}get(e){let n=this.hashFn(e),t=this.map.get(n);if(t!==void 0)for(let s of t){let T=s.deref();if(T&&this.matchFn(e,T))return T}else t=new Set,this.map.set(n,t);let r=this.injestFn(e),o=new WeakRef(r);return t.add(o),this.cleanupRegistry.register(r,[n,o],this),r}get size(){return Array.from(this.map.entries(),([e,n])=>n.size).reduce((e,n)=>e+n,0)}reset(){this.cleanupRegistry.unregister(this),this.map.clear()}};var g=0xffffffffn,m=new Float64Array(1),p=new Uint32Array(m.buffer);function j(e,n=0){let t=n,r=0;for(let o of e){r++;let s=Math.imul(o,3432918353);s=s<<15|s>>>17,s=Math.imul(s,461845907),t^=s,t=t<<13|t>>>19,t=Math.imul(t,5)+3864292196|0}return t^=r*4,t>>>0}function k(e=Date.now()){let n=e>>>0;return()=>(n=n*1664525+1013904223>>>0,n)}var a=k(),h=a(),F=a(),w=a(),R=a(),H=a(),I=a(),N=a(),K=a(),y=new WeakMap,M=new WeakMap;function l(e,n){if(n===null)return h;let t=e.get(n);if(t!==void 0)return t;let r=a();return e.set(n,r),r}function b(e){let n=Array(Math.ceil(e.length/2)+1);n[0]=e.length;for(let t=0;t<e.length/2;t+=1){let r=e.charCodeAt(2*t),o=e.charCodeAt(2*t+1);n[t+1]=o<<16|r}return n}function S(e){return m[0]=Number.isNaN(e)?NaN:e,[p[0],p[1]]}function V(e){let n=e<0n,t=n?-e:e,r=[n?1:0];for(;t!==0n;)r.push(Number(t&g)),t>>=32n;return r}function A(e){switch(typeof e){case"string":return i(b(e),N);case"number":return i(S(e),H);case"bigint":return i(V(e),I);case"boolean":return e?R:w;case"symbol":let n=Symbol.keyFor(e);return n===void 0?l(M,e):i(b(n),K);case"undefined":return F;case"object":return e===null?h:l(y,e);case"function":return l(y,e)}}var d=(e,n)=>i(Array.from(e,A),n),i=j;function O(e,n){if(n.length!==e.length)return!1;for(let t=0;t<e.length;t++)if(!Object.is(n[t],e[t]))return!1;return!0}var x=()=>Object.assign((...t)=>W.get(t),{typed:(...t)=>x()}),f=(e,n)=>{let t=(...c)=>e.get(c);return Object.assign((...c)=>t(...c),{from:c=>{let _=n.map(L=>c[L]);return t(..._)},typed:(...c)=>f(e,n),typedFrom:(...c)=>f(e,n)})},W=new u(d,O,Object.freeze),v=x(),E=(...e)=>{let n=r=>(e.forEach((o,s)=>{r[o]=r[s]}),Object.freeze(r)),t=new u(d,O,n);return f(t,e)};export{W as _tupleCache,E as struct,v as tuple};