tuple-ts 0.9.1 → 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.1",
+  "version": "0.9.2",
   "description": "TypeScript-first tuples and structs with value-based identity",
   "keywords": [
     "tuple",