@elliots/typical 0.1.10 → 0.2.0

package/README.md

@@ -1,113 +1,129 @@
 # Typical
 
-Typical adds runtime validation to typescript, making TypeScript type-safe at runtime *with no changes to your code*. 
+Typical makes TypeScript type-safe at runtime _with no changes to your code_.
 
-It can be used as a TSC plugin, ESM loader for Node.js, or with bundlers like Vite, Webpack, and Rollup via unplugin.
+It transforms your code to inject runtime validation based on your existing type annotations. With source maps, so errors point to the right lines in your original code.
 
 ## Why?
 
-For some use cases it can mean you don't need to use zod, yup, ajv, or other runtime validation libraries, as your types are already validated automatically.
+- Less need for zod, yup, ajv, or other runtime validation libraries - your types are already validated automatically. If you can express it in TypeScript, Typical can validate it at runtime.
+- Protects against data leaks via `JSON.stringify` by ensuring only properties defined in your types are included
+- Catches type mismatches at runtime that TypeScript can't catch at compile time (API responses, JSON parsing, un-typed/badly-typed libraries, vibe-coding coworkers etc.)
 
-It protects you from leaking data via JSON.stringify by making sure only the properties defined in your types are included in the output.
+## Features
 
-Why not.
+- Validation of function parameters and return types
+- Safe `JSON.parse` with type validation
+- Safe `JSON.stringify` that only includes defined properties
+- Validation of type casts (`as Type`)
+- Configurable include/exclude patterns
 
-## Features
+## Example
 
-- ✅ Automatic validation of function parameters
-- ✅ Automatic validation of return types
-- ✅ Replace `JSON.stringify` with a custom stringifier (very fast!)
-- ✅ Replace `JSON.parse` with a custom parser and validator (very fast!)
-- ✅ Configurable include/exclude patterns
-- ✅ Optionally reuse validation logic for identical types to optimize performance (enabled by default)
-- ✅ TSC plugin
-- ✅ ESM loader for runtime transformation with `node --import @elliots/typical/esm` (or `node --loader @elliots/typical/esm-loader` for older Node versions)
-- ✅ tsx wrapper (ttsx) for easy use like `npx ttsx script.ts`
-- ✅ Unplugin for Vite, Webpack, Rollup, esbuild, and more
+This code runs without errors in normal TypeScript, but Typical catches the invalid data:
 
-## Installation
+```ts
+interface User {
+  name: string;
+  email: `${string}@${string}`;
+}
 
-```bash
-npm add typical
+// This will throw - email doesn't match the template literal type
+const user = JSON.parse('{"name":"Alice","email":"not-an-email"}') as User;
 ```
 
-## Configuration
+---
+
+## Usage Options
+
+Choose the integration that fits your workflow:
+
+| Method                                                    | Best For                        | Package                       |
+| --------------------------------------------------------- | ------------------------------- | ----------------------------- |
+| [ESM Loader](#nodejs-esm-loader)                          | Node.js scripts, development    | `@elliots/typical`            |
+| [ttsx](#ttsx-tsx-wrapper)                                 | Quick scripts with tsx          | `@elliots/typical` + `tsx`    |
+| [Bun Plugin](#bun)                                        | Bun projects                    | `@elliots/bun-plugin-typical` |
+| [Vite/Webpack/etc](#bundlers-vite-webpack-rollup-esbuild) | Frontend apps, bundled projects | `@elliots/unplugin-typical`   |
+| [tsc Plugin](#typescript-compiler-tsc)                    | Pure TypeScript compilation     | `@elliots/typical-tsc-plugin` |
+
+---
+
+## Node.js (ESM Loader)
 
-Optional: Create a `typical.json` file in your project root.
+The simplest way to run TypeScript with Typical validation.
 
-If not provided, these default settings will be used (optimized for development):
+```bash
+npm add @elliots/typical
+```
+
+```bash
+node --import @elliots/typical/esm src/index.ts
+```
+
+Add to `package.json` scripts:
 
 ```json
 {
-  "include": ["**/*.ts", "**/*.tsx"],
-  "exclude": ["node_modules/**", "**/*.d.ts", "dist/**", "build/**"],
-  "reusableValidators": false,
-  "validateFunctions": true,
-  "validateCasts": false,
-  "hoistRegex": true,
-  "ignoreDOMTypes": true,
-  "ignoreTypes": [],
-  "sourceMap": {
-    "enabled": true,
-    "includeContent": true,
-    "inline": false
+  "scripts": {
+    "start": "node --import @elliots/typical/esm src/index.ts"
   }
 }
 ```
 
-### Configuration Options
+---
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `include` | `["**/*.ts", "**/*.tsx"]` | Glob patterns for files to transform |
-| `exclude` | `["node_modules/**", "**/*.d.ts", "dist/**", "build/**"]` | Glob patterns for files to skip |
-| `reusableValidators` | `false` | Create shared validators for identical types (smaller output). Incompatible with source maps. |
-| `validateFunctions` | `true` | Validate function parameters and return types at runtime |
-| `validateCasts` | `false` | Validate type assertions (`as Type`) at runtime |
-| `hoistRegex` | `true` | Hoist regex patterns to top-level constants (improves performance) |
-| `ignoreDOMTypes` | `true` | Skip validation for DOM types (Document, Element, etc.) |
-| `ignoreTypes` | `[]` | Type patterns to skip validation for (supports wildcards, e.g., `["React.*"]`) |
-| `sourceMap.enabled` | `true` | Generate source maps for transformed code |
-| `sourceMap.includeContent` | `true` | Include original source content in source maps |
-| `sourceMap.inline` | `false` | Use inline source maps (data URL) instead of external files |
-| `debug.writeIntermediateFiles` | `false` | Write `.typical.ts` files showing code before typia transform |
+## ttsx (tsx wrapper)
 
-### Production Configuration
+A convenience wrapper that combines [tsx](https://github.com/privatenumber/tsx) with Typical.
 
-For production builds, disable source maps and enable reusable validators for smaller output:
+```bash
+npm add @elliots/typical tsx
+```
 
-```json
-{
-  "reusableValidators": true,
-  "sourceMap": {
-    "enabled": false
-  }
-}
+```bash
+npx ttsx script.ts
 ```
 
-Note: `reusableValidators` and `sourceMap.enabled` are mutually exclusive. Source maps require inline validators so each validation call can map back to its original type annotation. If both are enabled, `reusableValidators` will be automatically disabled with a warning.
+Or install globally:
+
+```bash
+npm add -g @elliots/typical tsx
+ttsx script.ts
+```
 
-## Usage
+> **Note:** `tsx` must be installed separately. The `ttsx` command is a thin wrapper that runs `tsx` with the Typical ESM loader.
 
-See ./samples/esm and ./samples/tsc and ./samples/ttsx
+---
 
-Quickest way to try it out is to use ttsx:
+## Bun
 
 ```bash
-npm add @elliots/typical
-npx ttsx your-script.ts
+bun add @elliots/bun-plugin-typical
+```
+
+Create `bunfig.toml`:
+
+```toml
+preload = ["./preload.ts"]
 ```
 
-or globally:
+Create `preload.ts`:
+
+```ts
+import { typicalPlugin } from "@elliots/bun-plugin-typical";
+
+Bun.plugin(typicalPlugin());
+```
+
+Then run:
 
 ```bash
-npm add -g @elliots/typical
-ttsx your-script.ts
+bun run src/index.ts
 ```
 
-## Vite / Webpack / Rollup (unplugin)
+---
 
-Install the unplugin:
+## Bundlers (Vite, Webpack, Rollup, esbuild)
 
 ```bash
 npm add @elliots/unplugin-typical
@@ -115,224 +131,242 @@ npm add @elliots/unplugin-typical
 
 ### Vite
 
-```typescript
+```ts
 // vite.config.ts
-import Typical from '@elliots/unplugin-typical/vite'
+import Typical from "@elliots/unplugin-typical/vite";
 
 export default defineConfig({
-  plugins: [
-    Typical(),
-  ],
-})
+  plugins: [Typical()],
+});
 ```
 
 ### Webpack
 
-```typescript
+```js
 // webpack.config.js
-const Typical = require('@elliots/unplugin-typical/webpack').default
+const Typical = require("@elliots/unplugin-typical/webpack").default;
 
 module.exports = {
-  plugins: [
-    Typical(),
-  ],
-}
+  plugins: [Typical()],
+};
 ```
 
 ### Rollup
 
-```typescript
+```js
 // rollup.config.js
-import Typical from '@elliots/unplugin-typical/rollup'
+import Typical from "@elliots/unplugin-typical/rollup";
 
 export default {
-  plugins: [
-    Typical(),
-  ],
-}
+  plugins: [Typical()],
+};
 ```
 
 ### esbuild
 
-```typescript
-import { build } from 'esbuild'
-import Typical from '@elliots/unplugin-typical/esbuild'
+```ts
+import { build } from "esbuild";
+import Typical from "@elliots/unplugin-typical/esbuild";
 
 build({
   plugins: [Typical()],
-})
+});
 ```
 
-### Plugin Configuration
+### Rolldown
 
-Pass options directly to the plugin:
+```ts
+// rolldown.config.ts
+import Typical from "@elliots/unplugin-typical/rolldown";
 
-```typescript
-Typical({
-  validateFunctions: true,
-  validateCasts: false,
-  // ... other options
-})
+export default {
+  plugins: [Typical()],
+};
 ```
 
-Or use a `typical.json` file in your project root (shared with other entry points like TSC plugin and ESM loader).
+### Farm
 
-## Example
+```ts
+// farm.config.ts
+import Typical from "@elliots/unplugin-typical/farm";
 
-This code will run without errors when compiled normally, but will throw an error when using Typical.
+export default {
+  plugins: [Typical()],
+};
+```
 
+### Rspack
 
 ```ts
-interface User {
-  name: string;
-  email: `${string}@${string}`;
-} 
-const u = JSON.parse('{"name":"Alice","email":"oops-not-an-email"}') as User;
+// rspack.config.ts
+import Typical from "@elliots/unplugin-typical/rspack";
+
+export default {
+  plugins: [Typical()],
+};
 ```
 
-## How it works
+---
 
-Typical uses the TypeScript Compiler API to parse and transform your TypeScript code. It analyzes function signatures, return types, and JSON operations to inject appropriate typia validation calls.
+## TypeScript Compiler (tsc)
 
-But basically you shouldn't need to care about how it works internally, it makes typescript strongly typed*. You can still use `any` and `unknown` if you want to opt out of type safety.
+For projects that compile with `tsc` directly using [ts-patch](https://github.com/nonara/ts-patch).
 
-* sort of. probably. something like it anyway.
+```bash
+npm add @elliots/typical-tsc-plugin ts-patch
+```
 
-## Flow Analysis
+### Option 1: ttsc (auto-injects plugin)
 
-Typical includes smart flow analysis to avoid redundant validations. When you return a value that was already validated (either as a parameter or via a type-annotated const), the return statement won't be wrapped in another validation call.
+The `ttsc` command automatically injects the plugin - no config needed:
 
-### When return validation is skipped:
+```bash
+npx ttsc
+```
 
-```typescript
-interface User { name: string; }
+Add to `package.json`:
 
-// Direct parameter return - no redundant validation
-function validate(user: User): User {
-  return user;  // Already validated on entry, skip return validation
+```json
+{
+  "scripts": {
+    "build": "ttsc"
+  }
 }
+```
 
-// Property access from validated parameter
-function getAddress(user: User): Address {
-  return user.address;  // user was validated, address is safe
-}
+### Option 2: Manual tsconfig.json
+
+Add to your `tsconfig.json`:
 
-// Type-annotated const
-function getUser(): User {
-  const user: User = fetchData();  // const is validated here
-  return user;  // skip redundant validation
+```json
+{
+  "compilerOptions": {
+    "plugins": [
+      {
+        "transform": "@elliots/typical-tsc-plugin",
+        "transformProgram": true
+      }
+    ]
+  }
 }
 ```
 
-### When return validation IS applied (tainting):
+Then run ts-patch's tsc:
 
-```typescript
-// After mutation
-function updateUser(user: User): User {
-  user.name = "modified";  // Mutation taints the value
-  return user;  // Must re-validate
-}
-
-// After passing to another function
-function processUser(user: User): User {
-  someFunction(user);  // Could have mutated user
-  return user;  // Must re-validate
-}
+```bash
+npx ts-patch install
+npx tsc
+```
 
-// After await (async boundary)
-async function asyncProcess(user: User): Promise<User> {
-  await delay();  // Async boundary taints values
-  return user;  // Must re-validate
-}
+Or add a prepare script:
 
-// Spread into new object
-function cloneUser(user: User): User {
-  return { ...user };  // New object, must validate
+```json
+{
+  "scripts": {
+    "prepare": "ts-patch install -s",
+    "build": "tsc"
+  }
 }
 ```
 
-## Debugging
+---
 
-### Intermediate Files
+## Configuration
 
-To see what code Typical generates before typia processes it, enable intermediate file output:
+Create a `typical.json` file in your project root (optional):
 
 ```json
 {
-  "debug": {
-    "writeIntermediateFiles": true
-  }
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules/**", "**/*.d.ts"],
+  "validateFunctions": true,
+  "validateCasts": false
 }
 ```
 
-This creates `.typical.ts` files alongside your output showing the code with typia calls injected but not yet transformed.
+### Options
 
-### Verbose Logging
+| Option                   | Default                                                   | Description                                                       |
+| ------------------------ | --------------------------------------------------------- | ----------------------------------------------------------------- |
+| `include`                | `["**/*.ts", "**/*.tsx"]`                                 | Files to transform                                                |
+| `exclude`                | `["node_modules/**", "**/*.d.ts", "dist/**", "build/**"]` | Files to skip                                                     |
+| `validateFunctions`      | `true`                                                    | Validate function parameters and return types                     |
+| `validateCasts`          | `false`                                                   | Validate type assertions (`as Type`)                              |
+| `transformJSONParse`     | `true`                                                    | Transform `JSON.parse` to validate and filter to typed properties |
+| `transformJSONStringify` | `true`                                                    | Transform `JSON.stringify` to only include typed properties       |
 
-Set `DEBUG=1` environment variable for detailed logging:
+---
 
-```bash
-DEBUG=1 npm run build
-```
+## JSON Transformations
 
-## Troubleshooting
+Typical automatically transforms `JSON.parse` and `JSON.stringify` calls when type information is available.
 
-### "Failed to transform the following types"
+### JSON.parse
 
-This error means typia couldn't generate validation code for certain types. Common causes:
+When you cast the result of `JSON.parse`, Typical validates the parsed data and filters it to only include properties defined in your type:
 
-1. **DOM types**: Types like `HTMLElement`, `Document`, etc. have complex intersections typia can't process.
-   - Solution: Enable `ignoreDOMTypes: true` (default) or add specific types to `ignoreTypes`
+```ts
+interface User {
+  name: string;
+  age: number;
+}
 
-2. **React types**: Event handlers, refs, and other React types often can't be validated.
-   - Solution: Add `"React.*"` to `ignoreTypes`
+// Input: '{"name":"Alice","age":30,"password":"secret"}'
+const user = JSON.parse(jsonString) as User;
+// Result: { name: "Alice", age: 30 } - password is filtered out!
+// Throws TypeError if name isn't a string or age isn't a number
+```
 
-3. **Third-party library types**: Some library types are too complex.
-   - Solution: Add the specific type patterns to `ignoreTypes`
+### JSON.stringify
 
-```json
-{
-  "ignoreTypes": ["React.*", "Express.Request", "Prisma.*"]
+When you use a type assertion with `JSON.stringify`, only properties defined in your type are included - preventing accidental data leaks:
+
+```ts
+interface PublicUser {
+  name: string;
+  age: number;
 }
+
+const user = { name: "Alice", age: 30, password: "secret", ssn: "123-45-6789" };
+const json = JSON.stringify(user as PublicUser);
+// Result: '{"name":"Alice","age":30}' - sensitive data excluded!
 ```
 
-### "Window & typeof globalThis" errors
+Both patterns detect type information from:
 
-This occurs when a type includes DOM globals. Enable `ignoreDOMTypes: true` or add the specific type to `ignoreTypes`.
+- Type assertions: `JSON.parse(str) as User` or `JSON.stringify(obj as User)`
+- Variable declarations: `const user: User = JSON.parse(str)`
+- Function return types: `function getUser(): User { return JSON.parse(str) }`
 
-### Generic type parameters not validated
+---
 
-Type parameters (`T`, `U`, etc.) cannot be validated at runtime because the actual type isn't known until the function is called. This is by design:
+## How It Works
 
-```typescript
-function identity<T>(value: T): T {
-  return value;  // T is not validated - no runtime type info
-}
-```
+Typical uses a Go-based compiler that leverages the TypeScript type checker to analyze your code. It generates runtime validators that check values against their declared types.
 
-Concrete types in the same function ARE validated:
+Types that can't be validated at runtime (like generic type parameters `T`) are skipped. You can still use `any` and `unknown` to opt out of validation.
 
-```typescript
-function process<T>(value: T, user: User): User {
-  return user;  // User IS validated
-}
-```
+## Compiler Optimizations
 
-### Constructor parameters not validated
+The generated validation code is optimized for runtime performance:
 
-Currently, class constructors are not transformed. This is a known limitation. Validate in the constructor body if needed:
+- **Skip redundant validation** - When returning a validated parameter directly, the return validation is skipped (e.g., `return x` where `x: string` was already validated)
+- **Subtype-aware skipping** - If a validated type is assignable to the return type, validation is skipped (e.g., `string` parameter returned as `string | null`)
+- **Property chain tracking** - Accessing properties of validated objects skips re-validation (e.g., `return user.name` when `user: User` was validated)
+- **Type-aware dirty tracking** - Primitives stay validated after being passed to functions (they're copied), but objects are re-validated (they could be mutated)
+- **Union early bail-out** - Union type checks use if-else chains so the first matching type succeeds immediately
 
-```typescript
-class Client {
-  constructor(options: Options) {
-    // Manual validation if needed
-    if (!options.timeout) throw new Error("timeout required");
-  }
-}
-```
+## Debugging
+
+Set `DEBUG=1` for verbose logging:
 
-## Credits
-The actual validation work is done by [typia](https://github.com/samchon/typia). This package just generates the necessary code to call typia's functions based on your TypeScript types.
+```bash
+DEBUG=1 npm run build
+```
 
-> NOTE: The whole package was all mostly LLM. Feel free to improve it without care for the author's feelings. 
+## Limitations
 
+- Generic type parameters (`T`) cannot be validated - no runtime type information
+- Type-only imports of classes aren't checked (can't do instanceof on type-only imports)
+- Validation of functions is just not done. Need to think about that one.
+- Some complex types may not be fully supported yet. If you find any that fail, please open an issue!