rtt 1.0.2 → 1.1.1

package/README.md

@@ -1,54 +1,178 @@
-# rtt
+# rtt — Runtime Types for TypeScript
 
-Runtime Typescript Types
+[![npm version](https://img.shields.io/npm/v/rtt.svg)](https://www.npmjs.com/package/rtt)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-## Overview
+> **TypeScript types vanish at runtime.** `rtt` brings them back — with zero dependencies and a tiny footprint.
 
-This package provides a way to store type information in objects and check types at runtime in TypeScript. It is useful for scenarios where you need runtime type introspection, such as serialization, validation, or building type-safe APIs.
+---
+
+## The Problem
+
+When TypeScript compiles to JavaScript, all type information is stripped away. This creates a frustrating gap:
+
+```ts
+// ✅ At compile time — TypeScript knows this is a Dog
+const dog: Dog = { name: 'Rover', breed: 'Labrador' };
+
+// ❌ At runtime — it's just a plain object. No type info remains.
+JSON.parse('{"name":"Rover","breed":"Labrador"}') // what IS this?
+```
+
+Without runtime type information, you're forced into fragile workarounds: manual `type` strings, `instanceof` checks that don't survive serialization, or heavy validation libraries like Zod for every use case.
+
+## The Solution
+
+`rtt` lets you define **first-class type descriptors** that carry both runtime identity and compile-time TypeScript types — enabling inheritance-aware runtime type checking with a single function call:
+
+```ts
+import {$type, is} from 'rtt';
+
+// 1️⃣ Define your type hierarchy
+const $Animal = $type<Animal>('app.Animal');
+const $Dog    = $type<Dog>('app.Dog', $Animal);
+const $Cat    = $type<Cat>('app.Cat', $Animal);
+
+export type Animal = {$type: $Type; name: string};
+export type Dog  = Animal & { breed: string };
+export type Cat  = Animal & { lives: number };
+
+// 2️⃣ Create typed objects
+const rover: Dog    = {$type: $Dog, name: 'Rover', breed: 'Labrador'};
+const whiskers: Cat = {$type: $Cat, name: 'Whiskers', lives: 9};
+
+// 3️⃣ Check types at runtime
+is(rover, $Dog);       // ✅ true
+is(rover, $Animal);    // ✅ true — inheritance works!
+is(whiskers, $Dog);    // ❌ false
+```
 
 ## Features
 
-- Attach type metadata to objects.
-- Check if an object is of a specific type at runtime using the `is` function.
-- Support for type hierarchies and generics.
+| Feature | Description |
+|---|---|
+| 🏗️ **Type Hierarchies** | Define parent-child relationships and check them at runtime |
+| 🔍 **Runtime Introspection** | Know exactly what type an object is, even after JSON round-trips |
+| ⚡ **Zero Dependencies** | No bloat — just two functions and a lightweight interface |
+| 📦 **Tiny Footprint** | Minimal bundle size, tree-shakeable ESM exports |
+| 🔒 **Type Narrowing** | `is()` returns a TypeScript type guard for safe downstream access |
+| 🧬 **Generic Type Support** | Compare parameterized types with their arguments |
+| 🏷️ **Branded Types** | Optional structural branding for compile-time + runtime safety |
+
+## Quick Start
 
-## Installation
+### Installation
 
 ```sh
 npm install rtt
+# or yarn add rtt / pnpm add rtt
 ```
 
-## Usage
+### Type Narrowing
+
+The `is()` function is a **type guard** — TypeScript narrows the type automatically:
+
+```ts
+const unknownUser: unknown = {$type: $User, name: 'John'};
+
+if (is(unknownUser, $User)) {
+  // ✅ TypeScript knows user has 'name'
+  console.log(`Hello, ${unknownUser.name}`);
+}
+```
+
+### Generic Types
+
+Type descriptors work with generic types too — pass the inner type as a `generics` argument:
 
-```typescript
-import {$NewType, is, Model} from 'rtt';
+```ts
+import {$type, is} from 'rtt';
 
-// Define types
-const $A = () => $NewType('MyPackage', 'A');
-const $B = () => $NewType('MyPackage', 'B', $A());
+// Define base types
+const $User = $type<User>('app.User');
+const $List = <T>($generic: $Type<T>) => $type<List<T>>('app.List', undefined, [$generic]);
 
-// Create a model instance
-const model: Model = {
-  $type: $B(),
-};
+export type User = {$type: $Type; name: string};
+export type List<T> = {$type: $Type; items: T[]};
 
-// Runtime type checks
-is(model, $B()); // true
-is(model, $A()); // true (because B extends A)
+// Tag objects
+const user: User    = {$type: $User, name: 'John'};
+const userList: List<User> = {$type: $List($User), items: [user]};
+
+// Runtime checks preserve generic types
+const unknownUser: unknown = user;
+const unknownList: unknown = userList;
+
+if (is(unknownUser, $User)) {
+  console.log(unknownUser.name); // ✅ ok
+}
+
+if (is(unknownList, $UserList)) {
+  console.log(unknownList.items[0].name); // ✅ ok — generic preserved!
+}
 ```
 
-## API
+## API Reference
 
-### `$NewType(packageName: string, typeName: string, parent?, generics?)`
+### `$type<T>(name, parent?, generics?)` → `$Type<T>`
 
-Creates a new runtime type.
+Creates a named type descriptor that can be composed into hierarchies. The generic parameter `T` connects the runtime descriptor to your TypeScript type.
 
-### `is(model: any, type: $Type): boolean`
+```ts
+const $Animal = $type<Animal>('app.Animal');
+const $Dog    = $type<Dog>('app.Dog', $Animal);
+```
 
-Checks if the given model is of the specified type (or its parent).
+| Param | Type | Description |
+|---|---|---|
+| `name` | `string` | Unique type identifier (e.g. `'app.Dog'`) |
+| `parent?` | `$Type \| null` | Parent type for inheritance chains |
+| `generics?` | `$Type[]` | Generic type arguments to compare |
 
-### `Model`
+### `is<T>(value, type)` → `value is T`
 
-Interface for objects with runtime type information.
+Runtime type guard. Returns `true` if `value.$type` matches `type` or any of its ancestors in the hierarchy.
 
----
+```ts
+if (is(rover, $Dog)) {
+  // TypeScript narrows: rover is now typed as Dog
+  console.log(rover.name); // ✅ safe
+}
+```
+
+### `isType(a, b)` → `boolean`
+
+Low-level comparison between two `$Type` descriptors. Handles inheritance chains and generic type matching internally.
+
+### `$Type<T>` Interface
+
+```ts
+interface $Type<T = unknown> {
+  name: string;
+  type?: T;
+  parent?: $Type | null;
+  generics?: $Type[] | null;
+}
+```
+
+### `Brand<T>` Type
+
+A structural branding utility for compile-time + runtime safety:
+
+```ts
+import {Brand} from 'rtt';
+
+type UserId = Brand<'UserId'> & number;
+```
+
+## Development
+
+```bash
+npm install
+npm test        # Run vitest suite
+npm run build   # Build with Vite + dts (generates dist/)
+```
+
+## License
+
+[MIT](LICENSE) — © [Nizami](https://github.com/nizami)

package/dist/index.js

@@ -1,34 +1,25 @@
-function is(model, type) {
-  return "$type" in model && isType(model?.$type, type);
+//#region src/is/is.ts
+function is(value, type) {
+	return "$type" in value && isType(value?.$type, type);
 }
 function isType(a, b) {
-  if (nameEquals(b, $Model()) || a.parent && isType(a.parent, b)) {
-    return true;
-  }
-  if (b.generics && b.generics.length > 0) {
-    if (a.generics && a.generics.length === b.generics.length) {
-      return a.generics.every((x, i) => isType(x, b.generics[i]));
-    }
-    return false;
-  }
-  return nameEquals(a, b);
+	if (a.parent && isType(a.parent, b)) return true;
+	if (b.generics && b.generics.length > 0) {
+		if (a.generics && a.generics.length === b.generics.length) return a.generics.every((x, i) => isType(x, b.generics[i]));
+		return false;
+	}
+	return a.name === b.name;
 }
-function nameEquals(a, b) {
-  return a.typeName === b.typeName && a.packageName == b.packageName;
+//#endregion
+//#region src/type/type.ts
+function $type(name, parent, generics) {
+	return {
+		name,
+		parent,
+		generics
+	};
 }
-const $Model = () => $NewType("RuntimeType", "Model");
-function $NewType(packageName, typeName, parent, generics) {
-  return {
-    packageName,
-    typeName,
-    parent,
-    generics
-  };
-}
-export {
-  $Model,
-  $NewType,
-  is,
-  isType
-};
-//# sourceMappingURL=index.js.map
+//#endregion
+export { $type, is, isType };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../src/is/is.ts","../src/model.ts","../src/type/type.factory.ts"],"sourcesContent":["import {$Model, $Type} from '#lib';\n\nexport function is<T extends $Type>(model: any, type: T): model is Exclude<T['type'], undefined> {\n  return '$type' in model && isType(model?.$type, type);\n}\n\nexport function isType(a: $Type, b: $Type): boolean {\n  if ( nameEquals(b, $Model()) || (a.parent && isType(a.parent, b))) {\n    return true;\n  }\n\n  if (b.generics && b.generics.length > 0) {\n    if (a.generics && a.generics.length === b.generics.length) {\n      // todo Covariance and Contravariance ???\n      return a.generics.every((x, i) => isType(x, b.generics![i]));\n    }\n\n    return false;\n  }\n\n  return nameEquals(a, b);\n}\n\nfunction nameEquals(a: $Type, b: $Type): boolean {\n  return a.typeName === b.typeName && a.packageName == b.packageName;\n}\n","import {$NewType, $Type} from '#lib';\n\nexport interface Model {\n  $type: $Type;\n}\n\nexport const $Model = () => $NewType<Model>('RuntimeType', 'Model');\n","import {$Type, Model} from '#lib';\n\nexport function $NewType<T extends Model>(\n  packageName: string,\n  typeName: string,\n  parent?: $Type | null | undefined,\n  generics?: $Type[] | null | undefined,\n): $Type<T> {\n  return {\n    packageName,\n    typeName,\n    parent,\n    generics,\n  };\n}\n"],"names":[],"mappings":"AAEO,SAAS,GAAoB,OAAY,MAAiD;AAC/F,SAAO,WAAW,SAAS,OAAO,OAAO,OAAO,IAAI;AACtD;AAEO,SAAS,OAAO,GAAU,GAAmB;AAClD,MAAK,WAAW,GAAG,OAAA,CAAQ,KAAM,EAAE,UAAU,OAAO,EAAE,QAAQ,CAAC,GAAI;AACjE,WAAO;AAAA,EACT;AAEA,MAAI,EAAE,YAAY,EAAE,SAAS,SAAS,GAAG;AACvC,QAAI,EAAE,YAAY,EAAE,SAAS,WAAW,EAAE,SAAS,QAAQ;AAEzD,aAAO,EAAE,SAAS,MAAM,CAAC,GAAG,MAAM,OAAO,GAAG,EAAE,SAAU,CAAC,CAAC,CAAC;AAAA,IAC7D;AAEA,WAAO;AAAA,EACT;AAEA,SAAO,WAAW,GAAG,CAAC;AACxB;AAEA,SAAS,WAAW,GAAU,GAAmB;AAC/C,SAAO,EAAE,aAAa,EAAE,YAAY,EAAE,eAAe,EAAE;AACzD;ACnBO,MAAM,SAAS,MAAM,SAAgB,eAAe,OAAO;ACJ3D,SAAS,SACd,aACA,UACA,QACA,UACU;AACV,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EAAA;AAEJ;"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/is/is.ts","../src/type/type.ts"],"sourcesContent":["import {$Type} from '../type/type';\n\nexport function is<T extends $Type>(value: any, type: T): value is Exclude<T['type'], undefined> {\n  return '$type' in value && isType(value?.$type, type);\n}\n\nexport function isType(a: $Type, b: $Type): boolean {\n  if (a.parent && isType(a.parent, b)) {\n    return true;\n  }\n\n  if (b.generics && b.generics.length > 0) {\n    if (a.generics && a.generics.length === b.generics.length) {\n      // todo Covariance and Contravariance ???\n      return a.generics.every((x, i) => isType(x, b.generics![i]));\n    }\n\n    return false;\n  }\n\n  return a.name === b.name;\n}\n","export interface $Type<T = unknown> {\n  name: string;\n  type?: T;\n  parent?: $Type | null | undefined;\n  generics?: $Type[] | null | undefined;\n}\n\nexport function $type<T = unknown>(\n  name: string,\n  parent?: $Type | null | undefined,\n  generics?: $Type[] | null | undefined,\n): $Type<T> {\n  return {name, parent, generics};\n}\n"],"mappings":";AAEA,SAAgB,GAAoB,OAAY,MAAiD;CAC/F,OAAO,WAAW,SAAS,OAAO,OAAO,OAAO,IAAI;AACtD;AAEA,SAAgB,OAAO,GAAU,GAAmB;CAClD,IAAI,EAAE,UAAU,OAAO,EAAE,QAAQ,CAAC,GAChC,OAAO;CAGT,IAAI,EAAE,YAAY,EAAE,SAAS,SAAS,GAAG;EACvC,IAAI,EAAE,YAAY,EAAE,SAAS,WAAW,EAAE,SAAS,QAEjD,OAAO,EAAE,SAAS,OAAO,GAAG,MAAM,OAAO,GAAG,EAAE,SAAU,EAAE,CAAC;EAG7D,OAAO;CACT;CAEA,OAAO,EAAE,SAAS,EAAE;AACtB;;;ACdA,SAAgB,MACd,MACA,QACA,UACU;CACV,OAAO;EAAC;EAAM;EAAQ;CAAQ;AAChC"}

package/dist/{brand.d.ts → src/brand.d.ts}

@@ -1,5 +1,5 @@
 declare const brand: unique symbol;
-export type Brand<T extends `${string}.${string}`> = {
+export type Brand<T extends string> = {
     [brand]?: T;
 };
 export {};

package/dist/{index.d.ts → src/index.d.ts}

@@ -1,5 +1,3 @@
 export * from './brand';
 export * from './is/is';
-export * from './model';
-export * from './type/type.factory';
 export * from './type/type';

package/dist/src/is/is.d.ts

@@ -0,0 +1,3 @@
+import { $Type } from '../type/type';
+export declare function is<T extends $Type>(value: any, type: T): value is Exclude<T['type'], undefined>;
+export declare function isType(a: $Type, b: $Type): boolean;

package/dist/src/type/type.d.ts

@@ -0,0 +1,7 @@
+export interface $Type<T = unknown> {
+    name: string;
+    type?: T;
+    parent?: $Type | null | undefined;
+    generics?: $Type[] | null | undefined;
+}
+export declare function $type<T = unknown>(name: string, parent?: $Type | null | undefined, generics?: $Type[] | null | undefined): $Type<T>;

package/package.json

@@ -1,44 +1,47 @@
 {
-  "name": "rtt",
-  "version": "1.0.2",
+  "author": "Nizami",
+  "bugs": {
+    "url": "https://github.com/nizami/rtt/issues"
+  },
   "description": "Runtime Typescript Types",
-  "main": "index.js",
-  "scripts": {
-    "build": "barrelize && vite build",
-    "test": "vitest run"
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "barrelize": "^1.8.1",
+    "typescript": "~6.0.3",
+    "vite": "^8.0.16",
+    "vite-plugin-dts": "^5.0.2",
+    "vitest": "^4.1.8"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/nizami/rtt.git"
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
   },
+  "files": [
+    "dist"
+  ],
+  "homepage": "https://github.com/nizami/rtt#readme",
   "keywords": [
     "Typescript",
     "Runtime Types"
   ],
-  "author": "Nizami",
   "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/nizami/rtt/issues"
+  "main": "index.js",
+  "name": "rtt",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nizami/rtt.git"
   },
-  "homepage": "https://github.com/nizami/rtt#readme",
-  "devDependencies": {
-    "@types/node": "^24.0.10",
-    "barrelize": "^1.6.2",
-    "typescript": "~5.8.3",
-    "vite": "^7.0.2",
-    "vite-plugin-dts": "^4.5.4",
-    "vitest": "^3.2.4"
+  "scripts": {
+    "build": "barrelize && vite build",
+    "test": "vitest run"
   },
-  "type": "module",
   "sideEffects": false,
-  "files": [
-    "dist"
-  ],
+  "type": "module",
   "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
+  "version": "1.1.1",
+  "allowScripts": {
+    "fsevents@2.3.3": true
   }
 }

package/dist/is/is.d.ts

@@ -1,3 +0,0 @@
-import { $Type } from '../index.ts';
-export declare function is<T extends $Type>(model: any, type: T): model is Exclude<T['type'], undefined>;
-export declare function isType(a: $Type, b: $Type): boolean;

package/dist/model.d.ts

@@ -1,5 +0,0 @@
-import { $Type } from './index.ts';
-export interface Model {
-    $type: $Type;
-}
-export declare const $Model: () => $Type<Model>;

package/dist/type/type.d.ts

@@ -1,7 +0,0 @@
-export interface $Type<T = unknown> {
-    packageName: string;
-    typeName: string;
-    type?: T;
-    parent?: $Type | null | undefined;
-    generics?: $Type[] | null | undefined;
-}

package/dist/type/type.factory.d.ts

@@ -1,2 +0,0 @@
-import { $Type, Model } from '../index.ts';
-export declare function $NewType<T extends Model>(packageName: string, typeName: string, parent?: $Type | null | undefined, generics?: $Type[] | null | undefined): $Type<T>;