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

npm i runtypex

Quick Start

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

Runtime vs Build-Time Behavior

makeValidate<T>() and makeAssert<T>() need the Vite plugin or TypeScript transformer to become real validation functions. makeMapper<TDto, TDomain>() also benefits from the transformer, but it still has a runtime fallback that can interpret the mapper spec directly.

| Execution path | makeValidate<T>() / makeAssert<T>() | makeMapper<TDto, TDomain>() | Docs generation | | --- | --- | --- | --- | | npm run dev with the Vite plugin | Works. Validation usually runs. | Works with validation. | Can generate when the dev server starts. | | npm run build with the Vite plugin | Works. | Works. | Generates docs. | | npm run build + NODE_ENV=production + removeInProd: true | Replaced with no-op validation. | Mapping still works; validation is removed. | Unaffected. | | No Vite plugin or transformer | Placeholder runtime fallback; does not inspect T. | Runtime fallback mapping still works. | Not generated. |

Vite Setup

// 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:

export default defineConfig({
  plugins: [runtypex({ removeInProd: true })],
});

To generate mapper documentation by convention:

export default defineConfig({
  plugins: [
    runtypex({
      docs: {
        include: "src/features/**/*.mapper.ts",
      },
    }),
  ],
});

The docs generator finds defineMap<TDto, TDomainSource>()(...) calls under the included files, removes the Source suffix, and writes generated interfaces to runtypex.generated.ts next to the mapper file.

Feature Docs

| Feature | Description | | --- | --- | | Runtime validation | Generate makeValidate<T>() and makeAssert<T>() implementations from TypeScript types. | | Mapper | Convert DTO shapes into domain shapes with typed mapping specs. | | Mapping policy | Keep DTO path to domain field names consistent across multiple mappers. | | JSDoc generation | Generate field documentation from domain JSDoc and mapper metadata. | | Build integrations | Configure Vite, ts-loader, ESM exports, and build behavior. |

Mapper Example

import { defineMap, makeMapper, source, transform } from "runtypex/mapper";

interface UserDto {
  user_id: string;
  profile: { name: string };
  status: "ACTIVE" | "INACTIVE";
}

interface UserSource {
  /** User id */
  id: string;
  displayName: string;
  isActive: boolean;
}

const userMap = defineMap<UserDto, UserSource>()({
  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, UserSource>(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 shows TypeScript types being transformed into runtime guards during build.