typia

repository·master·Indexed 27 days ago

https://github.com/samchon/typia

A high-performance TypeScript transformer library that converts TypeScript types into optimized runtime validators, JSON schema generators, LLM function calling harnesses, and Protocol Buffer encoders/decoders.

Tokens
68.9K
Snippets
155
Records
307
Agent score
88%

What's inside typia

  1. Overview of Typia features and API

    master

    Typia is a TypeScript transformer library that provides super-fast runtime validators, safe JSON parsing/stringifying, and JSON schema generation. It uses AOT (Ahead of Time) compilation to achieve high performance.

    Key features include:

    • Super-fast Runtime Validators: Validates data against TypeScript types at runtime.
    • Strict Validators: Performs deep equality checks.
    • JSON Utilities: Safe parsing and fast stringification.
    • JSON Schema: Generates schemas directly from TypeScript types.

    All Typia functions are designed to be used with a single line of code, requiring no manual JSON schema definitions or decorators.

    // RUNTIME VALIDATORS
    export function is<T>(input: unknown | T): input is T; // returns boolean
    export function assert<T>(input: unknown | T): T; // throws TypeGuardError
    export function validate<T>(input: unknown | T): IValidation<T>; // detailed
    
    // STRICT VALIDATORS
    export function equals<T>(input: unknown | T): input is T;
    export function assertEquals<T>(input: unknown | T): T;
    export function validateEquals<T>(input: unknown | T): IValidation<T>;
    
    // JSON
    export function application<T>(): IJsonApplication; // JSON schema
    export function assertParse<T>(input: string): T; // type safe parser
    export function assertStringify<T>(input: T): string; // safe and faster
  2. What is typia?

    master

    typia is a TypeScript compiler transformer. It hooks into tsc (the TypeScript compiler) to transform TypeScript types into specialized runtime code at compile time. This generated code can be used for:

    • Runtime Validation: Creating high-performance validators (e.g., typia.createIs<T>()).
    • JSON Serialization: Specialized serializers/deserializers.
    • LLM Schemas: Generating schemas for Large Language Models.
    • Random Generators: Generating random data based on types.

    Because it is a transformer, it relies on the TypeScript compiler's AST (Abstract Syntax Tree) during the build process.

    // Input
    typia.createIs<IPoint3d>();
    
    // What ends up in your dist/
    const _io0 = (input) =>
      "number" === typeof input.x &&
      "number" === typeof input.y &&
      "number" === typeof input.z;
    const check = (input) =>
      "object" === typeof input && null !== input && _io0(input);
  3. Overview of Nestia for NestJS

    master

    Nestia is an integration layer for NestJS built on top of typia. It replaces the traditional class-validator and @nestjs/swagger pattern with decorators that read TypeScript interfaces directly. This eliminates the need for DTO classes and reduces boilerplate.

    Key packages include:

    • @nestia/core: Provides high-performance NestJS decorators like @TypedBody, @TypedRoute, and @TypedQuery.
    • @nestia/sdk: Generates type-safe client SDKs and Swagger documentation by reading NestJS controllers.
    • @nestia/migrate: Provides scaffolding for migrating from Swagger to NestJS.
    • nestia: The CLI tool for the above packages.
  4. Introduction to typia

    master
    typia is a compile-time transformation library that turns TypeScript types into highly optimized runtime code. Unlike other libraries that require you to maintain separate schemas or decorators, typia reads your existing TypeScript types and automatically generates validators, JSON serializers, schemas, and decoders. This eliminates type duplication and ensures your runtime checks are always in sync with your TypeScript definitions.
  5. Overview of typia features and performance

    master

    typia is a TypeScript transformer library that uses Ahead-of-Time (AoT) compilation to generate optimal validation and serialization code based on pure TypeScript types. It does not require extra schema definitions (like ajv or class-validator).

    Key features include:

    • Super-fast Runtime Validators: Up to 20,000x faster than class-validator.
    • Enhanced JSON functions: Up to 200x faster than class-transformer.
    • Protocol Buffer support: Encoder and decoder.
    • Random data generator.
  6. Understand where Typia tags are applied

    master

    Tags defined in your types are utilized across multiple Typia features:

    • Runtime Validation: Used by is, assert, and validate to check data at runtime.
    • Data Generation: The random function generates values that respect the constraints defined by the tags.
    • Schema Export: Tags are exported as standard fields in json.schemas (e.g., format, minimum) and llm.parameters.
    • Protobuf Serialization: tags.Type<"uint32"> selects specific scalar types, and tags.Sequence<N> defines field numbers in protobuf.message.
  7. Understand the relationship between typia, typescript-is, and nestia

    master

    The typia library is the successor to typescript-is. While typescript-is provided AoT (Ahead of Time) compilation for runtime validation, it has been unified into typia.

    nestia is a high-level framework helper (specifically for NestJS) that leverages typia for:

    • Runtime validation (via typia's validation features)
    • Swagger/OpenAPI document generation
    • SDK and Mockup Simulator generation

    If you are looking for the modern, maintained version of the validation patterns found in typescript-is, you should use typia.

  8. Interpret Typia Benchmark Results

    master

    This document provides performance benchmarks for typia across various data validation and transformation tasks, measured in Megabytes/sec.

    Important Note on Data Integrity: Rows for optimizer, AJV validate, and express class-transformer (server-performance) were produced before workload-integrity fixes in #2049. These specific rows are historical artifacts and should not be used for comparison until replaced by a fresh quiet-host run.

  9. Understand the AutoBe AI Backend Generation Pipeline

    master

    AutoBe is an AI agent that generates production-grade backends (requirements, database schemas, API specs, tests, and implementation) from natural language. It uses a 5-phase waterfall pipeline where the LLM fills predefined JSON Schema structures instead of writing free-form code. These structures are then validated and transformed by specialized compilers.

    The 5-Phase Pipeline:

    1. Analyze: Generates structured SRS using AutoBeAnalyze.
    2. Database: Generates DB schema AST using AutoBeDatabase.
    3. Interface: Generates OpenAPI v3.2 specs using AutoBeOpenApi.
    4. Test: Generates E2E test code using AutoBeTest (supporting 30+ expression types).
    5. Realize: Generates implementation code via modularized collectors and transformers.

    Key Concept: The LLM fills structures; compilers write code. This approach uses schema specs as unambiguous, model-independent prompts.

  10. Performance Benefits of Typia's Pure TypeScript Approach

    master

    Because Typia generates specialized, hand-rolled JavaScript instead of using dynamic schema interpretation, it offers significant performance advantages over traditional validation libraries:

    • Runtime validation: Up to 20,000× faster than class-validator.
    • JSON serialization: Up to 200× faster than class-transformer.
  11. Understand Typia Benchmark Categories

    master

    Typia's performance is measured across several functional categories. Use these categories to understand how Typia compares to other libraries like zod, ajv, or class-validator in your specific use case:

    • is: Type checking (returns boolean).
    • assert: Type assertion (throws error if invalid).
    • validate: Type validation (returns boolean and error details).
    • assert-error: Asserting that a value should fail validation.
    • validate-error: Validating that a value should fail validation.
    • optimizer: Performance optimization of types.
    • stringify: Converting objects to JSON strings.
    • server-assert/stringify/performance: Performance metrics specifically for server-side integration (e.g., Fastify or Express).
  12. Review Typia performance benchmarks

    master

    Typia provides benchmark results comparing its performance against other libraries like typebox, ajv, io-ts, zod, and class-validator. Benchmarks are categorized by operation type:

    • Type Checking: is (boolean check), assert (throws on failure), and validate (returns result object).
    • Error Handling: assert-error and validate-error (performance when handling invalid data).
    • Optimization: optimizer performance.
    • Serialization: stringify (JSON serialization).
    • Server Integration: server-assert, server-stringify, and server-performance (comparing fastify-typia and express-typia against pure implementations and class-transformer).

    Note on Data Integrity: Results for optimizer, AJV validate, and express server-performance in this specific benchmark set were produced before workload-integrity fixes in #2049 and should be treated as historical artifacts rather than current performance indicators.