typia

Superfast runtime validators with only one line

weekly downloads239K

versionv11.0.3

licenseMIT

categoryvalidation

fastjsonstringifytypescripttransformajvio-tszodschemajson-schemageneratorassertcloneisvalidateequalruntimetypetypeboxcheckervalidatorsafeparseprunerandomprotobufllmllm-function-callingstructured-outputopenaichatgptclaudegeminillama

Overview

Typia is a TypeScript transformer that converts native TypeScript type definitions into highly optimized runtime validation functions through Ahead-of-Time (AOT) compilation. Unlike schema-based validation libraries that interpret type definitions at runtime, typia analyzes your TypeScript interfaces and types during compilation to generate dedicated, inline validation code tailored specifically to each type. This eliminates the overhead of runtime schema traversal and produces validation functions that execute type checks directly.

The library addresses a fundamental inefficiency in the TypeScript ecosystem: the need to maintain separate type definitions, validation schemas, and runtime decorators for the same data structures. With typia, you write standard TypeScript types once, and the compiler generates everything else automatically. The transformation happens via ts-patch, which intercepts TypeScript compilation to inject optimized validation logic wherever typia functions are called.

Typia supports complex type scenarios including discriminated unions, template literals, branded types, and validation constraints expressed through JSDoc tags like @minimum, @maxLength, and @format email. The library has gained adoption in backend APIs where validation performance is critical, particularly in high-throughput Node.js services. With over 238,000 weekly downloads, it's become a viable alternative to traditional runtime validators when compile-time transformation is acceptable in your build pipeline.

The library extends beyond validation to include JSON serialization (claiming 200x performance improvements), Protocol Buffers encoding without .proto files, JSON Schema generation, and LLM function calling schema composition. These features share the same AOT philosophy: analyze types at compile time, generate optimized runtime code, avoid reflection and runtime interpretation.

Quick Start

typescript

import typia from 'typia';

// Define types with validation constraints via JSDoc
interface CreateUserRequest {
  /** @format email */
  email: string;
  /** @minLength 3 @maxLength 50 */
  username: string;
  /** @minimum 18 @maximum 120 */
  age: number;
  /** @format uuid */
  organizationId?: string;
  role: 'admin' | 'user' | 'guest';
}

// Compile-time transformed validation functions
export const validateUser = typia.createValidate<CreateUserRequest>();
export const assertUser = (input: unknown): CreateUserRequest => 
  typia.assert<CreateUserRequest>(input);

// Express route example
import express from 'express';
const app = express();

app.post('/users', (req, res) => {
  const validation = validateUser(req.body);
  
  if (!validation.success) {
    return res.status(400).json({
      errors: validation.errors.map(e => ({
        path: e.path,
        expected: e.expected,
        value: e.value
      }))
    });
  }
  
  const user = validation.data;
  // user is now fully typed as CreateUserRequest
  console.log(`Creating user ${user.username} with role ${user.role}`);
  res.json({ id: 'generated-id', ...user });
});

// Fast JSON serialization
interface ApiResponse {
  users: CreateUserRequest[];
  total: number;
}

const response: ApiResponse = {
  users: [/* ... */],
  total: 150
};

const json = typia.json.stringify<ApiResponse>(response);
// 200x faster than JSON.stringify for complex objects

Use Cases

API Request Validation: Express or Fastify endpoints can validate incoming request bodies with type safety and minimal runtime overhead. Using typia.assert(req.body) validates and throws detailed error messages if validation fails, replacing manual checks or decorator-heavy class-validator patterns.

High-Performance JSON APIs: Services that serialize large datasets to JSON benefit from typia.json.stringify(), which generates optimized stringification code that skips unnecessary runtime checks. This is particularly useful in data pipelines or analytics endpoints returning thousands of records.

Type-Safe Configuration Loading: Validating environment variables or config files against TypeScript interfaces ensures configuration type safety at application startup. Using typia.assert(loadedConfig) catches misconfigurations before they cause runtime errors deep in application logic.

OpenAI/Claude Function Calling: The typia.llm.application() feature generates function schemas for LLM APIs directly from TypeScript class methods. This eliminates manual JSON Schema writing for AI agent function definitions, keeping schemas synchronized with implementation types.

Protocol Buffers Without .proto Files: Microservices using protobuf can encode/decode messages using native TypeScript types with typia.protobuf.encode(data), avoiding the complexity of maintaining separate .proto definitions and code generation steps.

Pros & Cons

Pros

+Exceptional runtime performance through AOT compilation — benchmarks show 20,000x improvements over decorator-based validators and orders of magnitude faster than schema interpreters
+Single source of truth for types — no need to maintain separate TypeScript interfaces, validation schemas, and runtime decorators, reducing maintenance burden and type drift
+Comprehensive feature set beyond validation including optimized JSON serialization, protobuf encoding, JSON Schema generation, and LLM function schema composition
+Supports advanced TypeScript constructs including discriminated unions, template literals, branded types, and validation constraints via JSDoc tags
+Type-safe output — validation functions retain full TypeScript type information, providing excellent IDE autocomplete and compile-time safety

Cons

−Requires ts-patch to modify TypeScript compilation process, adding build complexity and potential compatibility issues with some toolchains (Nx, certain bundlers)
−Compilation errors can be cryptic when unsupported type constructs are encountered, and transforms may silently fail in misconfigured environments
−Generated code size increases bundle size compared to runtime schema validators, though this is often acceptable given performance gains
−Transformation mode locks you into specific build tooling — switching between development and production setups requires careful configuration
−Smaller ecosystem and community compared to established validators like Zod, meaning fewer third-party integrations and Stack Overflow answers

Alternatives

class-validatorv0.14.3

Decorator-based property validation for classes.

validation

6.3M / week

zodv4.3.6

TypeScript-first schema declaration and validation library with static type inference

validationtypescriptschema

85.3M / week

Comparisons

zod vs typia

validation

Install

bash

npm install typia

bash

pnpm add typia

bash

bun add typia

Overview

Quick Start

typescript

import typia from 'typia';

// Define types with validation constraints via JSDoc
interface CreateUserRequest {
  /** @format email */
  email: string;
  /** @minLength 3 @maxLength 50 */
  username: string;
  /** @minimum 18 @maximum 120 */
  age: number;
  /** @format uuid */
  organizationId?: string;
  role: 'admin' | 'user' | 'guest';
}

// Compile-time transformed validation functions
export const validateUser = typia.createValidate<CreateUserRequest>();
export const assertUser = (input: unknown): CreateUserRequest => 
  typia.assert<CreateUserRequest>(input);

// Express route example
import express from 'express';
const app = express();

app.post('/users', (req, res) => {
  const validation = validateUser(req.body);
  
  if (!validation.success) {
    return res.status(400).json({
      errors: validation.errors.map(e => ({
        path: e.path,
        expected: e.expected,
        value: e.value
      }))
    });
  }
  
  const user = validation.data;
  // user is now fully typed as CreateUserRequest
  console.log(`Creating user ${user.username} with role ${user.role}`);
  res.json({ id: 'generated-id', ...user });
});

// Fast JSON serialization
interface ApiResponse {
  users: CreateUserRequest[];
  total: number;
}

const response: ApiResponse = {
  users: [/* ... */],
  total: 150
};

const json = typia.json.stringify<ApiResponse>(response);
// 200x faster than JSON.stringify for complex objects

Use Cases

Pros & Cons

Pros

+Exceptional runtime performance through AOT compilation — benchmarks show 20,000x improvements over decorator-based validators and orders of magnitude faster than schema interpreters
+Single source of truth for types — no need to maintain separate TypeScript interfaces, validation schemas, and runtime decorators, reducing maintenance burden and type drift
+Comprehensive feature set beyond validation including optimized JSON serialization, protobuf encoding, JSON Schema generation, and LLM function schema composition
+Supports advanced TypeScript constructs including discriminated unions, template literals, branded types, and validation constraints via JSDoc tags
+Type-safe output — validation functions retain full TypeScript type information, providing excellent IDE autocomplete and compile-time safety

Cons

−Requires ts-patch to modify TypeScript compilation process, adding build complexity and potential compatibility issues with some toolchains (Nx, certain bundlers)
−Compilation errors can be cryptic when unsupported type constructs are encountered, and transforms may silently fail in misconfigured environments
−Generated code size increases bundle size compared to runtime schema validators, though this is often acceptable given performance gains
−Transformation mode locks you into specific build tooling — switching between development and production setups requires careful configuration
−Smaller ecosystem and community compared to established validators like Zod, meaning fewer third-party integrations and Stack Overflow answers