runtypex 0.1.13 → 0.2.1

package/README.md

@@ -1,278 +1,112 @@
-# 🛡️ runtypex
-
-TypeScript 타입으로부터 **런타임 타입 가드(runtime type guard)** 를 자동 생성합니다.  
-스키마도, 데코레이터도 필요 없습니다.  
-**빌드 시 타입 정보를 분석해 최적화된 검증 함수를 자동 생성하며**,  
-타입만으로 → **런타임 검증**을 수행합니다.
-
-> Generate **runtime type guards** automatically from your TypeScript types.  
-> No schemas. No decorators.  
-> **Analyzes types at build time to generate optimized validation functions**,  
-> enabling **blazing-fast runtime validation** powered purely by TypeScript.
-
-
-<br/><br/>
-
-## ⚙️ 사용법 (Usage)
-```bash
-npm i runtypex
-```
-
-```ts
-import { makeValidate, makeAssert } from "runtypex";
-
-interface User {
-  id: number;
-  name: string;
-  active: boolean;
-}
-
-const isUser = makeValidate<User>();
-const assertUser: ReturnType<typeof makeAssert<User>> = makeAssert<User>();
-
-isUser({ id: 1, name: "Lux", active: true });  // ✅ true
-assertUser({ id: "bad" });                      // ❌ throws
-```
-
-<br/><br/>
-
-### Vite 예시 (Vite Example)
-
-```ts
-// vite.config.ts
-import { defineConfig } from "vite";
-import { vitePlugin as runtypex } from "runtypex";
-
-export default defineConfig({
-  plugins: [runtypex()],
-});
-```
-
-<br/>
-
-프로덕션 빌드 시 런타임 검증 코드를 제거하려면 옵션 `{ removeInProd: true }`를 전달하세요.  
-To remove validation code in production builds, pass `{ removeInProd: true }`.
-
-```ts
-export default defineConfig({
-  plugins: [runtypex({ removeInProd: true })],
-});
-```
-
-<br/>
-
-### Webpack (ts-loader) 예시 (Webpack Example)
-
-```js
-// webpack.config.js
-const { tsTransformer } = require("runtypex");
-
-module.exports = {
-  module: {
-    rules: [
-      {
-        test: /\.tsx?$/,
-        loader: "ts-loader",
-        options: {
-          getCustomTransformers: (program) => ({
-            before: [ tsTransformer({ program }) ]
-          })
-        }
-      }
-    ]
-  }
-}
-```
-
-<br/><br/>
-
-## ⚡ runtypex의 특징 (Features)
-
-| 항목 | 설명 | Description |
-|------|------|-------------|
-| ⚡ **빠름 (Fast)** | AST로 컴파일된 검증 코드, 런타임 스키마 파싱 없음 | Compiled guards, no runtime schema parsing |
-| 🧩 **단순함 (Simple)** | 타입만 정의, 스키마 중복 선언 불필요 | Define once, no schema duplication |
-| 🧱 **유연함 (Flexible)** | Vite, Webpack 모두 지원 | Works with both Vite and Webpack |
-| 🛠️ **API** | `makeValidate`, `makeAssert` 제공 | Clean runtime API |
-
-<br/><br/>
-
-## 🧪 데모 (Demo)
-
-🔗 [runtypex-demo (GitHub)](https://github.com/KumJungMin/runtypex-demo)  
-TypeScript 타입이 **빌드 시 자동으로 런타임 검증 코드로 변환되는 과정**을 확인할 수 있습니다.  
-See how TypeScript types are transformed into real runtime guards at build time.
-
-<br/><br/>
-
-## 🧭 만들게 된 이유 (Background)
-
-TypeScript의 타입 시스템 덕분에 코드 상에서는 안전했지만,  
-결정적인 한계를 마주했습니다.
-
-> TypeScript의 타입은 **런타임에 존재하지 않는다.**  
-> TypeScript types **do not exist at runtime.**
-
-<br/>
-
-
-즉, 빌드 타임에는 안전하지만 실제 실행 환경(JS)에서는  
-모든 타입 정보가 사라집니다.  
-결국 **API나 외부 모듈에서 잘못된 타입의 데이터가 들어와도 검증할 방법이 없었습니다.**
-
-> In short, TypeScript ensures type safety at build time,  
-> but once the code is compiled, all type information disappears.  
-> This means that even if invalid data comes from an API or an external source,  
-> there’s no way to detect it at runtime.
-
-<br/>
-
-### 💡 기존의 시도 (Existing Approach): Zod 등 스키마 기반 검증 <br/>(Previous Approach: Schema-Based Validators (e.g., Zod, Yup))
-
-Zod, Yup 같은 **스키마 기반 검증기**를 먼저 시도했습니다.  
-하지만 다음 세 가지 문제에 부딪혔습니다:  
-
-> We first tried schema-based validators like **Zod** and **Yup**,  
-> but encountered three main problems:
-
-| 문제 | 설명 | Problem | Description |
-|------|------|----------|-------------|
-| ⚡ 성능 | 매번 스키마를 해석하며 검증 → 반복 비용 발생 | Performance | Every validation re-parses schema, causing overhead |
-| ⚠️ 안정성 | 타입 정의와 스키마 불일치 가능 | Safety | Schema can desync from TypeScript type definitions |
-| 🧑‍💻 DX | 타입이 중복 선언됨 (`interface` + `z.object`) | DX | Requires writing both `interface` and `z.object` |
-
----
-
-### 🧠 새로운 접근 (New Approach): AST로 검증 코드 생성<br/>(A New Approach: Compile-Time Guard Generation via AST)
-
-runtypex는 **TypeScript AST(Abstract Syntax Tree)** 를 분석해  
-**빌드 시점에 자동으로 검증 함수를 생성합니다.**
-
-> runtypex analyzes the **TypeScript AST (Abstract Syntax Tree)**  
-> and automatically generates runtime validation functions **at build time**.
-
-이 방식은 다음과 같은 장점을 가집니다 👇  
-This approach provides several key advantages 👇
-
-- 타입 정의 한 번으로 런타임 검증 자동화  
-  → **Single source of truth** for type + validation  
-- 타입 불일치 문제 제거  
-  → Eliminates schema desync between TS and runtime  
-- 런타임 오버헤드 최소화  
-  → No dynamic schema parsing during execution  
-
-<br/><br/>
-
-## 📘 개념 요약 (Concept Overview)
-
-| 항목 | 내용 | Concept | Description |
-|------|------|----------|-------------|
-| **문제** | TypeScript 타입은 런타임에서 사라진다 | Problem | TypeScript types vanish at runtime |
-| **결과** | 외부 데이터 불일치 시 에러 발생 안 함 | Result | Type mismatches aren’t caught at runtime |
-| **해결** | AST로 타입 분석 → 검증 코드 자동 생성 | Solution | Parse TS AST → Generate guard functions |
-
-> Simply put: runtypex bridges the gap between TypeScript’s compile-time safety  
-> and JavaScript’s runtime uncertainty — automatically.
-
-<br/>
-
-### 🧩 예시 (Example)
-
-```ts
-// Before: manual type guard
-function isUser(value: unknown): value is User {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    typeof (value as any).id === "number" &&
-    typeof (value as any).name === "string"
-  );
-}
-
-// After: runtypex auto-generated
-const isUser = makeValidate<User>();
-```
-
-<br/>
-
-빌드 시 `makeValidate<User>()`는  
-AST를 기반으로 아래와 같은 함수로 **자동 변환됩니다.**
-
-> At build time, `makeValidate<User>()`  
-> is replaced with the following optimized validation code:
-
-```js
-const isUser = (v) =>
-  typeof v === "object" &&
-  v !== null &&
-  typeof v.id === "number" &&
-  typeof v.name === "string";
-```
-
-> ✅ Zero runtime parsing  
-> ✅ Fully type-synced  
-> ✅ Generated during build — not executed dynamically  
-
-<br/>
-
-### 📚 더 읽어보기 (Further Reading)
-
-📖 [TS × 클린 아키텍처 2편 — 타입스크립트 한계와 Mapper, AST로 타입 검증하기](https://mong-blog.tistory.com/entry/TS-×-클린-아키텍처-2편-—-타입스크립트-한계와-Mapper-AST로-타입-검증하기)  
-> AST 기반 타입 검증 자동화의 원리와 빌드 타임 최적화 과정을 자세히 다룹니다.  
-> A deep dive into how AST-based type parsing enables build-time validation generation and optimization.
-
-<br/>
-
-### ✅ 요약 (Summary)
-
-| 핵심 포인트 | English Summary |
-|--------------|-----------------|
-| TypeScript 타입은 런타임에 존재하지 않는다 | TypeScript types vanish at runtime |
-| 외부 API로부터의 데이터는 신뢰할 수 없다 | External data can’t be trusted blindly |
-| AST로 타입을 분석해 검증 함수를 생성한다 | Parse TS AST → generate guards at build time |
-| 런타임 오버헤드 없이 타입 안전성을 확보한다 | Provides runtime safety with zero runtime cost |
-| DX, 안정성, 성능 모두 강화된다 | Improves DX, safety, and performance |
-
-
-<br/><br/>
-
-## 🆕 v0.2.0 업데이트 예정 (Upcoming in v0.2.0)
-
-### 🚀 새로운 기능 (New Features)
-
-| 항목 | 설명 | Description |
-|------|------|-------------|
-| ⚙️ **mode 옵션 추가** | 런타임 동작 모드 설정 (`"development"`, `"production"`, `"test"`) | Define runtime behavior mode (`"development"`, `"production"`, `"test"`) |
-| 🧹 **strip 옵션 추가** | 빌드 시 모든 `makeAssert`, `makeValidate` 호출을 제거하여 파일 크기 최소화 | Removes all runtime validators from build output for minimal bundle size |
-| 🪶 **logLevel 옵션 추가** | 플러그인 로깅 레벨 설정 (`"silent"`, `"info"`, `"debug"`) | Controls plugin log verbosity (`"silent"`, `"info"`, `"debug"`) |
-| 🏷️ **`/* @runtypex:keep */` 주석 지원** | 특정 검증 함수는 제거하지 않고 유지 (`strip` 활성화 시 예외 처리용) | Preserve marked validators even when `strip` is enabled |
-
-<br/>
-
-### ⚙️ 예시 (Example)
-
-```ts
-// vite.config.ts
-import { defineConfig } from "vite";
-import { vitePlugin as runtypex } from "runtypex";
-
-export default defineConfig({
-  plugins: [
-    runtypex({
-      mode: "development",   // 런타임 검증 유지
-      strip: false,          // 검증 코드 제거 비활성화
-      logLevel: "info",      // 일반 로그 출력
-    }),
-  ],
-});
-```
-
-
-```ts
-/* @runtypex:keep */
-const assertUser = makeAssert<User>();
-```
-
-> `/* @runtypex:keep */` 주석을 붙이면 `strip` 옵션이 활성화되어도  
-> 해당 검증 함수는 빌드 결과물에서 제거되지 않습니다.  
-> Add `/* @runtypex:keep */` above a validator to keep it even when `strip` is enabled.
+# runtypex
+
+`runtypex` generates runtime validation and mapping code from TypeScript types.
+It keeps TypeScript types as the source of truth, so you do not need to maintain
+a separate schema just to validate data at runtime.
+
+## What It Solves
+
+TypeScript types disappear after compilation. That means data from APIs,
+databases, files, or external modules can still be invalid at runtime even when
+the consuming code is type-safe at build time.
+
+`runtypex` closes that gap by using the TypeScript compiler API to generate
+runtime guards and mappers during build.
+
+## Install
+
+```bash
+npm i runtypex
+```
+
+## Quick Start
+
+```ts
+import { makeAssert, makeValidate } from "runtypex";
+
+interface User {
+  id: number;
+  name: string;
+  active: boolean;
+}
+
+const isUser = makeValidate<User>();
+const assertUser = makeAssert<User>();
+
+isUser({ id: 1, name: "Lux", active: true }); // true
+assertUser({ id: "bad" }); // throws
+```
+
+## Vite Setup
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { vitePlugin as runtypex } from "runtypex";
+
+export default defineConfig({
+  plugins: [runtypex()],
+});
+```
+
+To replace validators with no-op functions in production builds:
+
+```ts
+export default defineConfig({
+  plugins: [runtypex({ removeInProd: true })],
+});
+```
+
+## Feature Docs
+
+| Feature | Description |
+| --- | --- |
+| [Runtime validation](docs/runtime-validation.md) | Generate `makeValidate<T>()` and `makeAssert<T>()` implementations from TypeScript types. |
+| [Mapper](docs/mapper.md) | Convert DTO shapes into domain shapes with typed mapping specs. |
+| [Mapping policy](docs/mapping-policy.md) | Keep DTO path to domain field names consistent across multiple mappers. |
+| [JSDoc generation](docs/jsdoc-generation.md) | Generate field documentation from mapper metadata. |
+| [Build integrations](docs/build-integrations.md) | Configure Vite, ts-loader, ESM exports, and build behavior. |
+
+## Mapper Example
+
+```ts
+import { defineMap, makeMapper, source, transform } from "runtypex/mapper";
+
+interface UserDto {
+  user_id: string;
+  profile: { name: string };
+  status: "ACTIVE" | "INACTIVE";
+}
+
+interface User {
+  /** User id */
+  id: string;
+  displayName: string;
+  isActive: boolean;
+}
+
+const userMap = defineMap<UserDto, User>()({
+  id: source("user_id", {
+    db: "users.user_id",
+    dtoDescription: "User identifier from the user DTO.",
+  }),
+  displayName: source("profile.name"),
+  isActive: transform("status", (value) => value === "ACTIVE"),
+});
+
+const toUser = makeMapper<UserDto, User>(userMap);
+```
+
+## Why runtypex?
+
+| Goal | How runtypex handles it |
+| --- | --- |
+| Avoid schema duplication | Runtime code is generated from TypeScript types. |
+| Validate external data | Generated guards check values after compilation. |
+| Keep DTO and domain mapping explicit | Mapper specs make field movement visible and typed. |
+| Reduce runtime overhead | Build-time generation avoids dynamic schema parsing. |
+
+## Demo
+
+[runtypex-demo](https://github.com/KumJungMin/runtypex-demo) shows TypeScript
+types being transformed into runtime guards during build.

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

@@ -0,0 +1,6 @@
+import ts from "typescript";
+import type { GenContext } from "./index.js";
+/**
+ * Handles array (T[]) and tuple ([A, B]) types.
+ */
+export declare function emitArrayOrTuple(ctx: GenContext, expr: string, t: ts.Type): string | null;

package/dist/cjs/core/emitArrayOrTuple.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitArrayOrTuple = emitArrayOrTuple;
+/**
+ * Handles array (T[]) and tuple ([A, B]) types.
+ */
+function emitArrayOrTuple(ctx, expr, t) {
+    if (ctx.checker.isTupleType(t)) {
+        return _emitTuple(t, expr, ctx);
+    }
+    if (ctx.checker.isArrayType(t)) {
+        return _emitArray(ctx, expr, t);
+    }
+    return null;
+}
+/**
+ * Generate validation for Array<T>
+ */
+function _emitArray(ctx, expr, t) {
+    const arrayCheck = `Array.isArray(${expr})`;
+    // Try extracting element type
+    const element = ctx.checker.getElementTypeOfArrayType?.(t) ||
+        t.typeArguments?.[0] ||
+        t.getNumberIndexType?.();
+    if (!element)
+        return arrayCheck;
+    const eachCheck = `${expr}.every(e=>${ctx.emit("e", element)})`;
+    return `(${arrayCheck}&&${eachCheck})`;
+}
+/**
+ * Generate validation for Tuple [A, B, ...]
+ */
+function _emitTuple(ref, expr, ctx) {
+    const elements = ref.typeArguments ?? ctx.checker.getTypeArguments?.(ref) ?? [];
+    const arrayCheck = `Array.isArray(${expr})`;
+    const lenCheck = `${expr}.length===${elements.length}`;
+    const elementChecks = elements.map((el, i) => ctx.emit(`${expr}[${i}]`, el));
+    const parts = [arrayCheck, lenCheck, ...elementChecks];
+    return `(${parts.join("&&")})`;
+}

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

@@ -0,0 +1,4 @@
+import ts from "typescript";
+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/cjs/core/emitLiteralOrEnum.js

@@ -0,0 +1,47 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitLiteralOrEnum = emitLiteralOrEnum;
+const typescript_1 = __importDefault(require("typescript"));
+/** Handles literal types and enum-like types. */
+function emitLiteralOrEnum(_, expr, t) {
+    if (t.isLiteral()) {
+        const value = t.value;
+        const isString = typeof value === "string";
+        const newValue = isString ? JSON.stringify(value) : String(value);
+        return `${expr}===${newValue}`;
+    }
+    const isEnum = t.flags & typescript_1.default.TypeFlags.EnumLike;
+    if (isEnum) {
+        const enumValues = _extractEnumValues(t);
+        if (enumValues.length) {
+            return `(${enumValues.map(v => `${expr}===${v}`).join("||")})`;
+        }
+    }
+    return null;
+}
+// Extracts numeric or string values from an Enum declaration.
+function _extractEnumValues(t) {
+    const symbol = t.getSymbol();
+    if (!symbol)
+        return [];
+    const values = [];
+    const declarations = symbol.getDeclarations() ?? [];
+    for (const declaration of declarations) {
+        const isEnum = typescript_1.default.isEnumDeclaration(declaration);
+        if (!isEnum)
+            continue;
+        for (const member of declaration.members) {
+            const init = member.initializer;
+            if (!init)
+                continue;
+            if (typescript_1.default.isStringLiteral(init) || typescript_1.default.isNumericLiteral(init)) {
+                const value = typescript_1.default.isStringLiteral(init) ? JSON.stringify(init.text) : init.text;
+                values.push(value);
+            }
+        }
+    }
+    return values;
+}

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

@@ -0,0 +1,33 @@
+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;
+    /** @deprecated Prefer domain property JSDoc for domain field descriptions. */
+    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;