runtypex 0.1.13 → 0.2.0

package/dist/esm/transformer/ts-transformer.js

@@ -1,6 +1,6 @@
 import ts from "typescript";
 import { emitGuardFromType } from "../core/index.js";
-import { resolveTypeByName } from "./helper.js";
+import { emitMapperFromSpec } from "../core/emitMapperFromSpec.js";
 /**
  * 🧩 tsTransformer
  * TypeScript custom transformer (BEFORE) factory.
@@ -22,7 +22,6 @@ import { resolveTypeByName } from "./helper.js";
  *   ✅ Optionally removed in production builds
  */
 export default function tsTransformer(options) {
-    const { program } = options;
     const checker = options.program.getTypeChecker();
     const removeInProd = !!options.removeInProd;
     const prod = process.env.NODE_ENV === "production";
@@ -30,13 +29,8 @@ export default function tsTransformer(options) {
         const visit = (node) => {
             if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
                 const name = node.expression.text;
-                const targetFunctions = ["makeValidate", "makeAssert"];
-                if (targetFunctions.includes(name) && node.typeArguments?.length) {
-                    const typeNode = node.typeArguments[0];
-                    const typeName = typeNode.getText();
-                    const type = resolveTypeByName(program, node.getSourceFile(), checker, typeName);
-                    if (!type)
-                        return node;
+                if ((name === "makeValidate" || name === "makeAssert") && node.typeArguments?.length) {
+                    const type = checker.getTypeFromTypeNode(node.typeArguments[0]);
                     const isRemovedInProd = removeInProd && prod;
                     switch (name) {
                         case "makeValidate":
@@ -45,18 +39,65 @@ export default function tsTransformer(options) {
                             return _emitMakeAssert(checker, type, isRemovedInProd);
                     }
                 }
+                // makeMapper<TDto, TDomain>(spec) becomes an inline validating mapper.
+                if (name === "makeMapper" && node.typeArguments?.length === 2 && node.arguments[0]) {
+                    const mapperCallOptions = _readMapperCallOptions(node.arguments[1]);
+                    const mapper = emitMapperFromSpec({
+                        checker,
+                        dtoType: checker.getTypeFromTypeNode(node.typeArguments[0]),
+                        domainType: checker.getTypeFromTypeNode(node.typeArguments[1]),
+                        specNode: node.arguments[0],
+                        sourceFile: node.getSourceFile(),
+                        options: {
+                            validateDto: !(removeInProd && prod) && options.validateDto !== false,
+                            validateDomain: !(removeInProd && prod) && options.validateDomain !== false,
+                            mappingPolicy: mapperCallOptions.policy,
+                            policyMode: mapperCallOptions.policyMode,
+                        },
+                    });
+                    if (mapper)
+                        return ts.factory.createIdentifier(mapper);
+                }
             }
             return ts.visitEachChild(node, visit, context);
         };
         return (sf) => ts.visitNode(sf, visit);
     };
 }
+function _readMapperCallOptions(node) {
+    if (!node)
+        return {};
+    const expr = ts.isAsExpression(node) || ts.isParenthesizedExpression(node) ? node.expression : node;
+    if (!ts.isObjectLiteralExpression(expr))
+        return {};
+    return {
+        policy: _readExpressionProperty(expr, "policy"),
+        policyMode: _readPolicyMode(expr),
+    };
+}
+function _readExpressionProperty(object, name) {
+    for (const item of object.properties) {
+        if (ts.isPropertyAssignment(item) && ts.isIdentifier(item.name) && item.name.text === name) {
+            return item.initializer;
+        }
+        if (ts.isShorthandPropertyAssignment(item) && item.name.text === name) {
+            return item.name;
+        }
+    }
+    return undefined;
+}
+function _readPolicyMode(object) {
+    const mode = _readExpressionProperty(object, "policyMode");
+    return mode && ts.isStringLiteral(mode) && (mode.text === "warn" || mode.text === "error") ? mode.text : undefined;
+}
 function _emitMakeValidate(checker, type, isRemovedInProd) {
     const guard = isRemovedInProd ? "((_)=>true)" : emitGuardFromType(checker, type);
     return ts.factory.createIdentifier(guard);
 }
 function _emitMakeAssert(checker, type, isRemovedInProd) {
-    const guard = isRemovedInProd ? "((_)=>{})" : emitGuardFromType(checker, type);
+    if (isRemovedInProd)
+        return ts.factory.createIdentifier("((_)=>{})");
+    const guard = emitGuardFromType(checker, type);
     const txt = `(function(){const G=${guard};return(i)=>{if(!G(i))throw new TypeError("[runtypex] Validation failed.");};})()`;
     return ts.factory.createIdentifier(txt);
 }

package/dist/esm/transformer/vite-plugin.js

@@ -1,7 +1,6 @@
 import ts from "typescript";
 import path from "node:path";
-import { emitGuardFromType } from "../core/index.js";
-import { resolveTypeByName } from "./helper.js";
+import tsTransformer from "./ts-transformer.js";
 /**
  * 🧩 vitePluginRuntypex
  * A Vite plugin that performs build-time type → runtime validation transformation.
@@ -18,24 +17,21 @@ import { resolveTypeByName } from "./helper.js";
  */
 export default function vitePluginRuntypex(options) {
     const removeInProd = !!options?.removeInProd;
-    const prod = process.env.NODE_ENV === "production";
     return {
         name: "vite-plugin-runtypex",
         enforce: "pre",
         transform(code, id) {
             const isTS = id.endsWith(".ts") || id.endsWith(".tsx");
-            const isTargetFunction = /make(?:Validate|Assert)</.test(code);
+            const isTargetFunction = /make(?:Validate|Assert|Mapper)</.test(code);
             if (!isTS || !isTargetFunction)
                 return;
-            const { program, checker } = _createProgramFor(id);
+            const { program } = _createProgramFor(id);
             const sf = program.getSourceFile(id);
             if (!sf)
                 return;
-            let mutated = code;
-            // ① makeAssert<T>()
-            mutated = mutated.replace(/makeAssert<\s*([^>]+)\s*>\s*\(\s*\)/g, (_m, typeName) => _emitMakeAssert({ program, checker, sf, typeName, prod, removeInProd }) ?? _m);
-            // ② makeValidate<T>()
-            mutated = mutated.replace(/makeValidate<\s*([^>]+)\s*>\s*\(\s*\)/g, (_m, typeName) => _emitMakeValidate({ program, checker, sf, typeName, prod, removeInProd }) ?? _m);
+            const result = ts.transform(sf, [tsTransformer({ program, removeInProd })]);
+            const mutated = ts.createPrinter().printFile(result.transformed[0]);
+            result.dispose();
             return mutated === code ? null : { code: mutated, map: null };
         },
     };
@@ -50,8 +46,7 @@ function _createProgramFor(file) {
         throw new Error(ts.flattenDiagnosticMessageText(cfg.error.messageText, "\n"));
     const parsed = ts.parseJsonConfigFileContent(cfg.config, ts.sys, path.dirname(tsconfig));
     const program = ts.createProgram({ rootNames: parsed.fileNames, options: parsed.options });
-    const checker = program.getTypeChecker();
-    return { program, checker };
+    return { program };
 }
 function _findNearestTsconfig(start) {
     let dir = start;
@@ -69,23 +64,3 @@ function _findNearestTsconfig(start) {
         return fallback;
     throw new Error("tsconfig.json not found");
 }
-// ──────────────────────────────────────────────
-// ② Emit Helpers
-// ──────────────────────────────────────────────
-function _emitMakeValidate({ program, checker, sf, typeName, prod, removeInProd, }) {
-    if (removeInProd && prod)
-        return `((_)=>true)`;
-    const type = resolveTypeByName(program, sf, checker, typeName.trim());
-    if (!type)
-        return null;
-    return emitGuardFromType(checker, type);
-}
-function _emitMakeAssert({ program, checker, sf, typeName, prod, removeInProd, }) {
-    if (removeInProd && prod)
-        return `((_)=>{})`;
-    const type = resolveTypeByName(program, sf, checker, typeName.trim());
-    if (!type)
-        return null;
-    const guard = emitGuardFromType(checker, type);
-    return `(function(){const G=${guard};return(i)=>{if(!G(i))throw new TypeError("[runtypex] Validation failed.");};})()`;
-}

package/docs/build-integrations.md

@@ -0,0 +1,89 @@
+# Build Integrations
+
+`runtypex` relies on the TypeScript compiler API, so its full value comes from
+running the transformer during build.
+
+## Vite
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { vitePlugin as runtypex } from "runtypex";
+
+export default defineConfig({
+  plugins: [runtypex()],
+});
+```
+
+The Vite plugin scans TypeScript files for:
+
+- `makeValidate<T>()`
+- `makeAssert<T>()`
+- `makeMapper<TDto, TDomain>()`
+
+When a target call is found, the plugin creates a TypeScript program for the
+nearest `tsconfig.json`, runs the transformer, and returns the transformed code
+to Vite.
+
+## ts-loader
+
+```js
+// webpack.config.js
+const { tsTransformer } = require("runtypex");
+
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.tsx?$/,
+        loader: "ts-loader",
+        options: {
+          getCustomTransformers: (program) => ({
+            before: [tsTransformer({ program })],
+          }),
+        },
+      },
+    ],
+  },
+};
+```
+
+## Transformer Options
+
+```ts
+tsTransformer({
+  program,
+  removeInProd: true,
+  validateDto: true,
+  validateDomain: true,
+});
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `program` | required | TypeScript program used to resolve types. |
+| `removeInProd` | `false` | Replaces generated validation with no-op functions in production. |
+| `validateDto` | `true` | Enables DTO input validation for generated mappers. |
+| `validateDomain` | `true` | Enables domain output validation for generated mappers. |
+
+## Package Entry Points
+
+```ts
+import { makeValidate } from "runtypex";
+import { makeMapper } from "runtypex/mapper";
+import { generateJSDocFromSpec } from "runtypex/generator";
+import { tsTransformer } from "runtypex/transformer";
+import { vitePlugin } from "runtypex/transformer/vite-plugin";
+```
+
+The package exports ESM and CommonJS builds from `dist/esm` and `dist/cjs`.
+
+## Local Verification
+
+Useful verification commands:
+
+```bash
+npm run build
+npx jest --runInBand --watchman=false
+npm run test:esm
+```

package/docs/jsdoc-generation.md

@@ -0,0 +1,88 @@
+# JSDoc Generation
+
+JSDoc generation creates interface documentation from mapper metadata. It helps
+editors show where a domain field came from and which DTO or database field it
+represents.
+
+## API
+
+```ts
+import { generateJSDocFromSpec } from "runtypex/generator";
+
+const source = generateJSDocFromSpec({
+  checker,
+  dtoType,
+  domainType,
+  specNode,
+});
+```
+
+This API is intended for build tooling that already has access to the TypeScript
+program, checker, DTO type, domain type, and mapper spec node.
+
+## Metadata Fields
+
+Mapper metadata can include:
+
+```ts
+source("user_id", {
+  db: "users.user_id",
+  description: "User id",
+  dtoDescription: "Identifier returned by the user API.",
+});
+```
+
+Field meanings:
+
+| Field | Meaning |
+| --- | --- |
+| `description` | Domain field description. Usually used as the first JSDoc sentence. |
+| `dtoDescription` | Optional explanation attached to the DTO path line. |
+| `db` | Optional database table and column reference. |
+
+## Generated Output
+
+Given this domain field:
+
+```ts
+id: source("user_id", {
+  db: "users.user_id",
+  description: "User id",
+  dtoDescription: "Identifier returned by the user API.",
+});
+```
+
+the generated documentation can look like this:
+
+```ts
+/**
+ * User id
+ *
+ * DTO: UserDto.user_id Identifier returned by the user API.
+ * DTO type: string
+ * DB: users.user_id
+ * Domain type: string
+ */
+id: string;
+```
+
+## Policy Integration
+
+JSDoc generation can also receive mapper policy options. This lets documentation
+generation fail or warn when the spec violates canonical DTO path naming:
+
+```ts
+generateJSDocFromSpec({
+  checker,
+  dtoType,
+  domainType,
+  specNode,
+  options: {
+    policy,
+    policyMode: "error",
+  },
+});
+```
+
+Use this when generated docs should reflect the same naming rules as runtime and
+build-time mapper generation.

package/docs/mapper.md

@@ -0,0 +1,104 @@
+# Mapper
+
+The mapper feature converts DTO objects into domain objects with a typed mapping
+spec. It is useful when API or database field names do not match the names used
+inside application code.
+
+## Basic Example
+
+```ts
+import { defineMap, makeMapper, source, transform } from "runtypex/mapper";
+
+interface UserDto {
+  user_id: string;
+  profile: { name: string };
+  status: "ACTIVE" | "INACTIVE";
+}
+
+interface User {
+  id: string;
+  displayName: string;
+  isActive: boolean;
+}
+
+const userMap = defineMap<UserDto, User>()({
+  id: source("user_id"),
+  displayName: source("profile.name"),
+  isActive: transform("status", (value) => value === "ACTIVE"),
+});
+
+const toUser = makeMapper<UserDto, User>(userMap);
+```
+
+## Type-Level Guarantees
+
+`defineMap<TDto, TDomain>()` checks the mapping spec at compile time:
+
+- every domain field must be present in the mapping spec
+- every `source()` or `transform()` path must exist on the DTO type
+- transform callbacks can return the final domain field value
+
+This keeps DTO changes visible at compile time instead of letting a rename fail
+silently at runtime.
+
+## Runtime Behavior
+
+Without the transformer, `makeMapper()` interprets the mapping spec at runtime:
+
+```ts
+const user = toUser(dto);
+```
+
+For each domain key, the mapper:
+
+1. reads the DTO value from the configured path
+2. applies a default when the source value is missing and a default exists
+3. runs the transform callback when one is provided
+4. writes the result to the domain output object
+
+## Transformer Behavior
+
+With the transformer enabled, this call:
+
+```ts
+const toUser = makeMapper<UserDto, User>(userMap);
+```
+
+is replaced with an inline mapper function. The generated function can validate
+the DTO input before mapping and validate the domain output after mapping.
+
+This gives you one mapping declaration while still allowing build-time optimized
+runtime code.
+
+## Metadata
+
+Mapping rules can include metadata:
+
+```ts
+id: source("user_id", {
+  db: "users.user_id",
+  description: "User id",
+  dtoDescription: "Identifier returned by the user API.",
+});
+```
+
+Metadata is not required for mapping. It is mainly used by JSDoc generation and
+documentation tooling.
+
+## Typed Helpers
+
+Use `mapperHelpers<TDto>()` when helper callbacks need DTO-aware typing:
+
+```ts
+import { mapperHelpers } from "runtypex/mapper";
+
+const h = mapperHelpers<UserDto>();
+
+const userMap = defineMap<UserDto, User>()({
+  id: h.source("user_id"),
+  displayName: h.source("profile.name"),
+  isActive: h.transform("status", (value, dto) => {
+    return dto.status === "ACTIVE";
+  }),
+});
+```

package/docs/mapping-policy.md

@@ -0,0 +1,78 @@
+# Mapping Policy
+
+Mapping policy keeps DTO path to domain field naming consistent across mappers.
+It is useful when the same DTO field appears in multiple domain shapes.
+
+## Problem
+
+Without a policy, different mappers can rename the same DTO path differently:
+
+```ts
+const userMap = defineMap<UserDto, User>()({
+  userId: source("user_id"),
+});
+
+const auditMap = defineMap<UserDto, AuditUser>()({
+  realMemberID: source("user_id"),
+});
+```
+
+Both mappings are technically valid, but they make the domain language
+inconsistent.
+
+## Policy Declaration
+
+Declare the canonical name once:
+
+```ts
+import { defineMappingPolicy, source } from "runtypex/mapper";
+
+const userPolicy = defineMappingPolicy<UserDto>()({
+  userId: source("user_id"),
+});
+```
+
+Then pass the policy into a mapper:
+
+```ts
+const toAuditUser = makeMapper<UserDto, AuditUser>(auditMap, {
+  policy: userPolicy,
+  policyMode: "error",
+});
+```
+
+## Modes
+
+`policyMode` controls how violations are handled:
+
+```ts
+policyMode: "warn";  // default, logs a warning
+policyMode: "error"; // throws an error
+```
+
+Use `"warn"` while introducing a policy into existing code. Use `"error"` when
+the naming convention should be enforced.
+
+## Runtime And Transformer Checks
+
+Policy validation runs in both paths:
+
+- runtime `makeMapper()` fallback
+- build-time `makeMapper<TDto, TDomain>()` transformer emission
+
+That means the policy protects code whether or not the transformer is currently
+configured.
+
+## Duplicate Policy Entries
+
+The policy itself must not map the same DTO path to multiple domain names:
+
+```ts
+const invalidPolicy = defineMappingPolicy<UserDto>()({
+  userId: source("user_id"),
+  realMemberID: source("user_id"),
+});
+```
+
+This is treated as a policy violation because there is no single canonical
+domain name for `user_id`.

package/docs/runtime-validation.md

@@ -0,0 +1,84 @@
+# Runtime Validation
+
+Runtime validation is the core `runtypex` feature. It turns TypeScript types into
+runtime guard functions during build.
+
+## APIs
+
+```ts
+import { makeAssert, makeValidate } from "runtypex";
+```
+
+`makeValidate<T>()` returns a predicate:
+
+```ts
+const isUser = makeValidate<User>();
+
+if (isUser(input)) {
+  input.id;
+}
+```
+
+`makeAssert<T>()` returns an assertion function:
+
+```ts
+const assertUser = makeAssert<User>();
+
+assertUser(input);
+input.id;
+```
+
+## How It Works
+
+You write this:
+
+```ts
+interface User {
+  id: number;
+  name: string;
+}
+
+const isUser = makeValidate<User>();
+```
+
+The transformer reads the `User` type through the TypeScript type checker and
+replaces the call with generated JavaScript:
+
+```js
+const isUser = (v) =>
+  typeof v === "object" &&
+  v !== null &&
+  typeof v.id === "number" &&
+  typeof v.name === "string";
+```
+
+No runtime reflection is required. The generated code is plain JavaScript.
+
+## Production Removal
+
+When `removeInProd: true` is enabled and `NODE_ENV` is `production`,
+validators are replaced with no-op equivalents:
+
+```ts
+makeValidate<T>(); // (_) => true
+makeAssert<T>(); // (_) => {}
+```
+
+Use this only when runtime validation is a development-time safety net and not a
+production boundary.
+
+## Supported Shape Examples
+
+The current emitter covers common TypeScript shapes:
+
+- primitives
+- object and interface properties
+- optional properties
+- arrays
+- tuples
+- unions
+- intersections
+- literal types
+- enums
+
+See the emitter tests for exact behavior around edge cases.