runtypex 0.1.12 → 0.2.0

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

@@ -0,0 +1,109 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = tsTransformer;
+const typescript_1 = __importDefault(require("typescript"));
+const index_js_1 = require("../core/index.js");
+const emitMapperFromSpec_js_1 = require("../core/emitMapperFromSpec.js");
+/**
+ * 🧩 tsTransformer
+ * TypeScript custom transformer (BEFORE) factory.
+ *
+ * 📘 Usage (ts-loader / ttypescript):
+ * ```ts
+ * getCustomTransformers: (program) => ({
+ *   before: [ tsTransformer({ program, removeInProd: true }) ]
+ * })
+ * ```
+ *
+ * 🧠 Purpose:
+ *  - Replace makeValidate<T>(), makeAssert<T>() calls
+ *    with *pre-generated runtime validation code* derived from T.
+ *
+ * 💡 Effect:
+ *   ✅ No reflection or runtime type parsing
+ *   ✅ Validation logic embedded at build-time
+ *   ✅ Optionally removed in production builds
+ */
+function tsTransformer(options) {
+    const checker = options.program.getTypeChecker();
+    const removeInProd = !!options.removeInProd;
+    const prod = process.env.NODE_ENV === "production";
+    return (context) => {
+        const visit = (node) => {
+            if (typescript_1.default.isCallExpression(node) && typescript_1.default.isIdentifier(node.expression)) {
+                const name = node.expression.text;
+                if ((name === "makeValidate" || name === "makeAssert") && node.typeArguments?.length) {
+                    const type = checker.getTypeFromTypeNode(node.typeArguments[0]);
+                    const isRemovedInProd = removeInProd && prod;
+                    switch (name) {
+                        case "makeValidate":
+                            return _emitMakeValidate(checker, type, isRemovedInProd);
+                        case "makeAssert":
+                            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 = (0, emitMapperFromSpec_js_1.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 typescript_1.default.factory.createIdentifier(mapper);
+                }
+            }
+            return typescript_1.default.visitEachChild(node, visit, context);
+        };
+        return (sf) => typescript_1.default.visitNode(sf, visit);
+    };
+}
+function _readMapperCallOptions(node) {
+    if (!node)
+        return {};
+    const expr = typescript_1.default.isAsExpression(node) || typescript_1.default.isParenthesizedExpression(node) ? node.expression : node;
+    if (!typescript_1.default.isObjectLiteralExpression(expr))
+        return {};
+    return {
+        policy: _readExpressionProperty(expr, "policy"),
+        policyMode: _readPolicyMode(expr),
+    };
+}
+function _readExpressionProperty(object, name) {
+    for (const item of object.properties) {
+        if (typescript_1.default.isPropertyAssignment(item) && typescript_1.default.isIdentifier(item.name) && item.name.text === name) {
+            return item.initializer;
+        }
+        if (typescript_1.default.isShorthandPropertyAssignment(item) && item.name.text === name) {
+            return item.name;
+        }
+    }
+    return undefined;
+}
+function _readPolicyMode(object) {
+    const mode = _readExpressionProperty(object, "policyMode");
+    return mode && typescript_1.default.isStringLiteral(mode) && (mode.text === "warn" || mode.text === "error") ? mode.text : undefined;
+}
+function _emitMakeValidate(checker, type, isRemovedInProd) {
+    const guard = isRemovedInProd ? "((_)=>true)" : (0, index_js_1.emitGuardFromType)(checker, type);
+    return typescript_1.default.factory.createIdentifier(guard);
+}
+function _emitMakeAssert(checker, type, isRemovedInProd) {
+    if (isRemovedInProd)
+        return typescript_1.default.factory.createIdentifier("((_)=>{})");
+    const guard = (0, index_js_1.emitGuardFromType)(checker, type);
+    const txt = `(function(){const G=${guard};return(i)=>{if(!G(i))throw new TypeError("[runtypex] Validation failed.");};})()`;
+    return typescript_1.default.factory.createIdentifier(txt);
+}

package/dist/cjs/transformer/vite-plugin.d.ts

@@ -0,0 +1,18 @@
+import type { Plugin } from "vite";
+/**
+ * 🧩 vitePluginRuntypex
+ * A Vite plugin that performs build-time type → runtime validation transformation.
+ *
+ * 📘 Purpose
+ *  - Replace calls like:
+ *      makeValidate<T>(), makeAssert<T>()
+ *    with *inline JavaScript guard functions* derived from TypeScript types.
+ *
+ * 💡 Features
+ *  - Works in both dev & build mode
+ *  - Optional: remove validation code in production (`removeInProd`)
+ *  - Compatible with Rollup / Webpack (via Vite plugin API)
+ */
+export default function vitePluginRuntypex(options?: {
+    removeInProd?: boolean;
+}): Plugin;

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

@@ -0,0 +1,72 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = vitePluginRuntypex;
+const typescript_1 = __importDefault(require("typescript"));
+const node_path_1 = __importDefault(require("node:path"));
+const ts_transformer_js_1 = __importDefault(require("./ts-transformer.js"));
+/**
+ * 🧩 vitePluginRuntypex
+ * A Vite plugin that performs build-time type → runtime validation transformation.
+ *
+ * 📘 Purpose
+ *  - Replace calls like:
+ *      makeValidate<T>(), makeAssert<T>()
+ *    with *inline JavaScript guard functions* derived from TypeScript types.
+ *
+ * 💡 Features
+ *  - Works in both dev & build mode
+ *  - Optional: remove validation code in production (`removeInProd`)
+ *  - Compatible with Rollup / Webpack (via Vite plugin API)
+ */
+function vitePluginRuntypex(options) {
+    const removeInProd = !!options?.removeInProd;
+    return {
+        name: "vite-plugin-runtypex",
+        enforce: "pre",
+        transform(code, id) {
+            const isTS = id.endsWith(".ts") || id.endsWith(".tsx");
+            const isTargetFunction = /make(?:Validate|Assert|Mapper)</.test(code);
+            if (!isTS || !isTargetFunction)
+                return;
+            const { program } = _createProgramFor(id);
+            const sf = program.getSourceFile(id);
+            if (!sf)
+                return;
+            const result = typescript_1.default.transform(sf, [(0, ts_transformer_js_1.default)({ program, removeInProd })]);
+            const mutated = typescript_1.default.createPrinter().printFile(result.transformed[0]);
+            result.dispose();
+            return mutated === code ? null : { code: mutated, map: null };
+        },
+    };
+}
+// ──────────────────────────────────────────────
+// ① createProgram & TypeChecker
+// ──────────────────────────────────────────────
+function _createProgramFor(file) {
+    const tsconfig = _findNearestTsconfig(node_path_1.default.dirname(file));
+    const cfg = typescript_1.default.readConfigFile(tsconfig, typescript_1.default.sys.readFile);
+    if (cfg.error)
+        throw new Error(typescript_1.default.flattenDiagnosticMessageText(cfg.error.messageText, "\n"));
+    const parsed = typescript_1.default.parseJsonConfigFileContent(cfg.config, typescript_1.default.sys, node_path_1.default.dirname(tsconfig));
+    const program = typescript_1.default.createProgram({ rootNames: parsed.fileNames, options: parsed.options });
+    return { program };
+}
+function _findNearestTsconfig(start) {
+    let dir = start;
+    while (true) {
+        const candidate = node_path_1.default.join(dir, "tsconfig.json");
+        if (typescript_1.default.sys.fileExists(candidate))
+            return candidate;
+        const parent = node_path_1.default.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    const fallback = node_path_1.default.join(process.cwd(), "tsconfig.json");
+    if (typescript_1.default.sys.fileExists(fallback))
+        return fallback;
+    throw new Error("tsconfig.json not found");
+}

package/dist/esm/core/emitArrayOrTuple.d.ts

@@ -1,5 +1,5 @@
 import ts from "typescript";
-import type { GenContext } from "./index";
+import type { GenContext } from "./index.js";
 /**
  * Handles array (T[]) and tuple ([A, B]) types.
  */

package/dist/esm/core/emitLiteralOrEnum.d.ts

@@ -1,4 +1,4 @@
 import ts from "typescript";
-import type { GenContext } from "./index";
+import type { GenContext } from "./index.js";
 /** Handles literal types and enum-like types. */
 export declare function emitLiteralOrEnum(_: GenContext, expr: string, t: ts.Type): string | null;

package/dist/esm/core/emitMapperFromSpec.d.ts

@@ -0,0 +1,32 @@
+import ts from "typescript";
+export type MapperEmitOptions = {
+    validateDto?: boolean;
+    validateDomain?: boolean;
+    mappingPolicy?: ts.Expression;
+    policyMode?: "warn" | "error";
+};
+export type MapRuleInfo = {
+    key: string;
+    from: string;
+    db?: string;
+    description?: string;
+    dtoDescription?: string;
+};
+export declare function emitMapperFromSpec(params: {
+    checker: ts.TypeChecker;
+    dtoType: ts.Type;
+    domainType: ts.Type;
+    specNode: ts.Expression;
+    sourceFile: ts.SourceFile;
+    options?: MapperEmitOptions;
+}): string | null;
+export declare function readMapRules(checker: ts.TypeChecker, specNode: ts.Expression): Map<string, MapRuleInfo>;
+export type MapPolicyViolation = {
+    from: string;
+    expectedKey: string;
+    actualKey: string;
+};
+export declare function findMapPolicyViolations(checker: ts.TypeChecker, specNode: ts.Expression, policyNode: ts.Expression | undefined): MapPolicyViolation[];
+export declare function handleMapPolicyViolations(violations: MapPolicyViolation[], mode: "warn" | "error"): void;
+/** Finds the mapping object behind inline, defineMap-wrapped, or identifier specs. */
+export declare function resolveMapSpecObject(checker: ts.TypeChecker, node: ts.Expression): ts.ObjectLiteralExpression | null;

package/dist/esm/core/emitMapperFromSpec.js

@@ -0,0 +1,189 @@
+import ts from "typescript";
+import { emitGuardFromType } from "./index.js";
+import { emitPathAccess } from "./path.js";
+export function emitMapperFromSpec(params) {
+    // Resolve the concrete object literal so generated code does not retain DSL calls.
+    const specObject = resolveMapSpecObject(params.checker, params.specNode);
+    if (!specObject)
+        return null;
+    handleMapPolicyViolations(findMapPolicyViolations(params.checker, specObject, params.options?.mappingPolicy), params.options?.policyMode ?? "warn");
+    const rules = readMapRules(params.checker, specObject);
+    const props = params.checker.getPropertiesOfType(params.domainType);
+    const fields = [];
+    for (const prop of props) {
+        const rule = rules.get(prop.name);
+        if (!rule)
+            return null;
+        fields.push(`${JSON.stringify(prop.name)}:R(${JSON.stringify(prop.name)},${emitPathAccess("input", rule.from)})`);
+    }
+    const specText = _emitRuntimeSpecText(specObject, params.sourceFile);
+    const dtoGuard = params.options?.validateDto === false ? null : emitGuardFromType(params.checker, params.dtoType);
+    const domainGuard = params.options?.validateDomain === false ? null : emitGuardFromType(params.checker, params.domainType);
+    return [
+        `(function(){const S=${specText};`,
+        dtoGuard ? `const VD=${dtoGuard};` : "",
+        domainGuard ? `const VO=${domainGuard};` : "",
+        `return(input)=>{`,
+        dtoGuard ? `if(!VD(input))throw new TypeError("[runtypex] DTO validation failed.");` : "",
+        `const R=(key,raw)=>{const rule=S[key];const value=raw===undefined&&Object.prototype.hasOwnProperty.call(rule,"default")?rule.default:raw;return typeof rule.transform==="function"?rule.transform(value,input):value;};`,
+        `const output={${fields.join(",")}};`,
+        domainGuard ? `if(!VO(output))throw new TypeError("[runtypex] Domain validation failed.");` : "",
+        `return output;};})()`,
+    ].join("");
+}
+export function readMapRules(checker, specNode) {
+    const object = resolveMapSpecObject(checker, specNode);
+    const rules = new Map();
+    if (!object)
+        return rules;
+    for (const prop of object.properties) {
+        if (!ts.isPropertyAssignment(prop))
+            continue;
+        const key = _propertyName(prop.name);
+        const rule = _readRule(prop.initializer);
+        if (key && rule)
+            rules.set(key, { key, ...rule });
+    }
+    return rules;
+}
+export function findMapPolicyViolations(checker, specNode, policyNode) {
+    if (!policyNode)
+        return [];
+    const rules = readMapRules(checker, specNode);
+    const policyRules = readMapRules(checker, policyNode);
+    const canonicalByPath = new Map();
+    const violations = [];
+    for (const rule of policyRules.values()) {
+        const existing = canonicalByPath.get(rule.from);
+        if (existing && existing !== rule.key) {
+            violations.push({ from: rule.from, expectedKey: existing, actualKey: rule.key });
+            continue;
+        }
+        canonicalByPath.set(rule.from, rule.key);
+    }
+    violations.push(...Array.from(rules.values()).flatMap((rule) => {
+        const expected = canonicalByPath.get(rule.from);
+        return expected && expected !== rule.key
+            ? [{ from: rule.from, expectedKey: expected, actualKey: rule.key }]
+            : [];
+    }));
+    return violations;
+}
+export function handleMapPolicyViolations(violations, mode) {
+    if (!violations.length)
+        return;
+    const details = violations
+        .map((item) => `DTO path "${item.from}" is canonically mapped as "${item.expectedKey}", but this map uses "${item.actualKey}".`)
+        .join("\n");
+    const message = `[runtypex/mapper] Mapping policy violation:\n${details}`;
+    if (mode === "error")
+        throw new Error(message);
+    console.warn(message);
+}
+/** Finds the mapping object behind inline, defineMap-wrapped, or identifier specs. */
+export function resolveMapSpecObject(checker, node) {
+    const expr = _skip(node);
+    if (ts.isObjectLiteralExpression(expr))
+        return expr;
+    if (ts.isCallExpression(expr) && expr.arguments[0]) {
+        const arg = _skip(expr.arguments[0]);
+        if (ts.isObjectLiteralExpression(arg))
+            return arg;
+    }
+    if (ts.isCallExpression(expr) && ts.isCallExpression(expr.expression)) {
+        return resolveMapSpecObject(checker, expr.expression);
+    }
+    if (ts.isIdentifier(expr)) {
+        const symbol = checker.getShorthandAssignmentValueSymbol?.(expr) ?? checker.getSymbolAtLocation(expr);
+        const declaration = symbol?.valueDeclaration ?? symbol?.declarations?.[0];
+        if (declaration && ts.isVariableDeclaration(declaration) && declaration.initializer) {
+            return resolveMapSpecObject(checker, declaration.initializer);
+        }
+        const variable = _findVariableDeclaration(expr.getSourceFile(), expr.text, expr.getStart(expr.getSourceFile()));
+        if (variable?.initializer)
+            return resolveMapSpecObject(checker, variable.initializer);
+    }
+    return null;
+}
+function _readRule(node) {
+    const expr = _skip(node);
+    if (ts.isObjectLiteralExpression(expr)) {
+        return _readRuleObject(expr);
+    }
+    if (ts.isCallExpression(expr) && expr.arguments[0]) {
+        const from = _stringValue(expr.arguments[0]);
+        const metadata = expr.arguments.length > 2 ? expr.arguments[2] : expr.arguments[1];
+        if (!from)
+            return null;
+        return { from, ..._readMetadata(metadata) };
+    }
+    return null;
+}
+function _readRuleObject(object) {
+    const from = _readStringProperty(object, "from");
+    if (!from)
+        return null;
+    return {
+        from,
+        db: _readStringProperty(object, "db") ?? undefined,
+        description: _readStringProperty(object, "description") ?? undefined,
+        dtoDescription: _readStringProperty(object, "dtoDescription") ?? undefined,
+    };
+}
+function _readMetadata(node) {
+    const expr = node ? _skip(node) : null;
+    if (!expr || !ts.isObjectLiteralExpression(expr))
+        return {};
+    return {
+        db: _readStringProperty(expr, "db") ?? undefined,
+        description: _readStringProperty(expr, "description") ?? undefined,
+        dtoDescription: _readStringProperty(expr, "dtoDescription") ?? undefined,
+    };
+}
+function _readStringProperty(object, name) {
+    const prop = object.properties.find((item) => ts.isPropertyAssignment(item) && _propertyName(item.name) === name);
+    return prop ? _stringValue(prop.initializer) : null;
+}
+function _skip(node) {
+    let expr = node;
+    while (ts.isParenthesizedExpression(expr) || ts.isAsExpression(expr) || ts.isTypeAssertionExpression(expr)) {
+        expr = expr.expression;
+    }
+    return expr;
+}
+function _propertyName(name) {
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name))
+        return name.text;
+    return null;
+}
+function _stringValue(node) {
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
+        return node.text;
+    return null;
+}
+function _findVariableDeclaration(sourceFile, name, before) {
+    let found = null;
+    const visit = (node) => {
+        if (ts.isVariableDeclaration(node) &&
+            ts.isIdentifier(node.name) &&
+            node.name.text === name &&
+            node.getStart(sourceFile) < before) {
+            found = node;
+        }
+        node.forEachChild(visit);
+    };
+    visit(sourceFile);
+    return found;
+}
+function _emitRuntimeSpecText(specObject, sourceFile) {
+    // Remove TypeScript-only syntax from inline transform callbacks before embedding.
+    const marker = "__runtypexSpec";
+    const output = ts.transpileModule(`const ${marker} = ${specObject.getText(sourceFile)};`, {
+        compilerOptions: {
+            module: ts.ModuleKind.ESNext,
+            target: ts.ScriptTarget.ESNext,
+        },
+    }).outputText.trim();
+    const prefix = `const ${marker} = `;
+    return output.startsWith(prefix) ? output.slice(prefix.length).replace(/;$/, "") : specObject.getText(sourceFile);
+}

package/dist/esm/core/emitObject.d.ts

@@ -1,5 +1,5 @@
 import ts from "typescript";
-import type { GenContext } from "./index";
+import type { GenContext } from "./index.js";
 /**
  * Handles interfaces, classes, and object-like structures.
  */

package/dist/esm/core/emitObject.js

@@ -1,4 +1,5 @@
 import ts from "typescript";
+import { emitPropertyAccess } from "./path.js";
 /**
  * Handles interfaces, classes, and object-like structures.
  */
@@ -14,8 +15,9 @@ export function emitObject(ctx, expr, t) {
             continue;
         const propType = ctx.checker.getTypeOfSymbolAtLocation(prop, declaration);
         const isOptional = (prop.getFlags() & ts.SymbolFlags.Optional) !== 0;
-        const condition = ctx.emit(`${expr}.${prop.name}`, propType);
-        const checkExpr = isOptional ? `(${expr}.${prop.name}===undefined||${condition})` : condition;
+        const propExpr = emitPropertyAccess(expr, prop.name);
+        const condition = ctx.emit(propExpr, propType);
+        const checkExpr = isOptional ? `(${propExpr}===undefined||${condition})` : condition;
         parts.push(checkExpr);
     }
     return `(${parts.join("&&")})`;

package/dist/esm/core/emitPrimitive.d.ts

@@ -1,5 +1,5 @@
 import ts from "typescript";
-import type { GenContext } from "./index";
+import type { GenContext } from "./index.js";
 /**
  * Handles primitive types like number, string, boolean...
  */

package/dist/esm/core/emitUnionOrIntersection.d.ts

@@ -1,5 +1,5 @@
 import ts from "typescript";
-import type { GenContext } from "./index";
+import type { GenContext } from "./index.js";
 /**
  * Handles union (A | B) and intersection (A & B) types.
  */

package/dist/esm/core/path.d.ts

@@ -0,0 +1,9 @@
+export type PathSegment = string | number;
+/** Splits a mapper path into object keys and numeric array indexes. */
+export declare function parsePath(path: string): PathSegment[];
+/** Runtime fallback reader used when mapper calls are not transformed. */
+export declare function getByPath(value: unknown, path: string): unknown;
+/** Emits bracket-only access for user-authored DTO paths. */
+export declare function emitPathAccess(root: string, path: string): string;
+/** Emits compact dot access when safe, with bracket fallback for quoted keys. */
+export declare function emitPropertyAccess(root: string, property: string | number): string;

package/dist/esm/core/path.js

@@ -0,0 +1,36 @@
+/** Splits a mapper path into object keys and numeric array indexes. */
+export function parsePath(path) {
+    if (!path)
+        return [];
+    return path.split(".").map((segment) => {
+        if (/^(0|[1-9]\d*)$/.test(segment))
+            return Number(segment);
+        return segment;
+    });
+}
+/** Runtime fallback reader used when mapper calls are not transformed. */
+export function getByPath(value, path) {
+    let current = value;
+    for (const segment of parsePath(path)) {
+        if (current == null)
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+/** Emits bracket-only access for user-authored DTO paths. */
+export function emitPathAccess(root, path) {
+    return parsePath(path).reduce((expr, segment) => {
+        if (typeof segment === "number")
+            return `${expr}[${segment}]`;
+        return `${expr}[${JSON.stringify(segment)}]`;
+    }, root);
+}
+/** Emits compact dot access when safe, with bracket fallback for quoted keys. */
+export function emitPropertyAccess(root, property) {
+    if (typeof property === "number")
+        return `${root}[${property}]`;
+    if (/^[A-Za-z_$][\w$]*$/.test(property))
+        return `${root}.${property}`;
+    return `${root}[${JSON.stringify(property)}]`;
+}

package/dist/esm/generator/generate-jsdoc.d.ts

@@ -0,0 +1,13 @@
+import ts from "typescript";
+export type GenerateJSDocOptions = {
+    name?: string;
+    mappingPolicy?: ts.Expression;
+    policyMode?: "warn" | "error";
+};
+export declare function generateJSDocFromSpec(params: {
+    checker: ts.TypeChecker;
+    dtoType: ts.Type;
+    domainType: ts.Type;
+    specNode: ts.Expression;
+    options?: GenerateJSDocOptions;
+}): string;

package/dist/esm/generator/generate-jsdoc.js

@@ -0,0 +1,63 @@
+import ts from "typescript";
+import { parsePath } from "../core/path.js";
+import { findMapPolicyViolations, handleMapPolicyViolations, readMapRules } from "../core/emitMapperFromSpec.js";
+export function generateJSDocFromSpec(params) {
+    const checker = params.checker;
+    const dtoName = params.dtoType.symbol?.name ?? "Dto";
+    const name = params.options?.name ?? params.domainType.symbol?.name ?? "GeneratedDomain";
+    const rules = readMapRules(checker, params.specNode);
+    const lines = [`export interface ${name} {`];
+    handleMapPolicyViolations(findMapPolicyViolations(checker, params.specNode, params.options?.mappingPolicy), params.options?.policyMode ?? "warn");
+    // Each domain property gets source metadata that editors can show on hover.
+    for (const prop of checker.getPropertiesOfType(params.domainType)) {
+        const rule = rules.get(prop.name);
+        if (!rule)
+            throw new Error(`[runtypex/generator] ${name}.${prop.name} is not mapped.`);
+        const declaration = prop.valueDeclaration ?? prop.declarations?.[0];
+        const domainType = declaration ? checker.getTypeOfSymbolAtLocation(prop, declaration) : checker.getAnyType();
+        const dtoPathType = _getTypeAtPath(checker, params.dtoType, rule.from);
+        const optional = (prop.getFlags() & ts.SymbolFlags.Optional) !== 0 ? "?" : "";
+        lines.push("  /**");
+        if (rule.description) {
+            lines.push(`   * ${_escapeComment(rule.description)}`);
+            lines.push("   *");
+        }
+        const dtoDescription = rule.dtoDescription ? ` ${_escapeComment(rule.dtoDescription)}` : "";
+        lines.push(`   * DTO: ${dtoName}.${rule.from}${dtoDescription}`);
+        lines.push(`   * DTO type: ${dtoPathType ? checker.typeToString(dtoPathType) : "unknown"}`);
+        if (rule.db)
+            lines.push(`   * DB: ${_escapeComment(rule.db)}`);
+        lines.push(`   * Domain type: ${checker.typeToString(domainType)}`);
+        lines.push("   */");
+        lines.push(`  ${_propertyName(prop.name)}${optional}: ${checker.typeToString(domainType)};`);
+        lines.push("");
+    }
+    lines.push("}");
+    return lines.join("\n");
+}
+/** Resolves the DTO type reached by a mapping path such as profile.name or items.0.id. */
+function _getTypeAtPath(checker, root, path) {
+    let current = root;
+    for (const segment of parsePath(path)) {
+        if (!current)
+            return null;
+        if (typeof segment === "number") {
+            current =
+                checker.getElementTypeOfArrayType?.(current) ??
+                    current.typeArguments?.[segment] ??
+                    current.getNumberIndexType?.() ??
+                    null;
+            continue;
+        }
+        const prop = checker.getPropertyOfType(current, segment);
+        const declaration = prop?.valueDeclaration ?? prop?.declarations?.[0];
+        current = prop && declaration ? checker.getTypeOfSymbolAtLocation(prop, declaration) : null;
+    }
+    return current;
+}
+function _propertyName(name) {
+    return /^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name);
+}
+function _escapeComment(value) {
+    return value.replace(/\*\//g, "* /");
+}

package/dist/esm/generator/index.d.ts

@@ -0,0 +1 @@
+export * from "./generate-jsdoc.js";

package/dist/esm/generator/index.js

@@ -0,0 +1 @@
+export * from "./generate-jsdoc.js";

package/dist/esm/index.d.ts

@@ -1,3 +1,4 @@
-export { makeValidate, makeAssert, type ValidateFn, type AssertFn } from "./runtime/validate";
-export { default as vitePlugin } from "./transformer/vite-plugin";
-export { default as tsTransformer } from "./transformer/ts-transformer";
+export { makeValidate, makeAssert, type ValidateFn, type AssertFn } from "./runtime/validate.js";
+export { defineMap, defineMappingPolicy, mapperHelpers, makeMapper, source, transform, type DefinedMap, type Mapper, type MapperOptions, type MapperMetadata, type MapRule, type MapSpec, type MappingPolicy, type MappingPolicyMode, type PathOf, } from "./runtime/mapper.js";
+export { default as vitePlugin } from "./transformer/vite-plugin.js";
+export { default as tsTransformer } from "./transformer/ts-transformer.js";

package/dist/esm/index.js

@@ -1,3 +1,4 @@
 export { makeValidate, makeAssert } from "./runtime/validate.js";
+export { defineMap, defineMappingPolicy, mapperHelpers, makeMapper, source, transform, } from "./runtime/mapper.js";
 export { default as vitePlugin } from "./transformer/vite-plugin.js";
 export { default as tsTransformer } from "./transformer/ts-transformer.js";

package/dist/esm/mapper/index.d.ts

@@ -0,0 +1 @@
+export * from "../runtime/mapper.js";

package/dist/esm/mapper/index.js

@@ -0,0 +1 @@
+export * from "../runtime/mapper.js";

package/dist/esm/runtime/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./validate.js";
+export * from "./mapper.js";

package/dist/esm/runtime/index.js

@@ -0,0 +1,2 @@
+export * from "./validate.js";
+export * from "./mapper.js";