typia

What is typia?

Typia is a TypeScript library that provides runtime type checking, validation, and serialization/deserialization capabilities. It aims to enhance type safety and runtime validation for TypeScript applications.

What are typia's main functionalities?

Runtime Type Checking

This feature allows you to perform runtime type checking to ensure that a value matches a specified TypeScript type. The code sample demonstrates how to check if a value is a string at runtime.

const isString = typia.is<string>(value);

Validation

Typia provides validation capabilities to ensure that data conforms to a specified type. The code sample shows how to validate an object against a TypeScript type, returning a result that indicates whether the data is valid.

const validationResult = typia.validate<MyType>(data);

Serialization/Deserialization

Typia can serialize TypeScript objects to JSON strings and deserialize JSON strings back to TypeScript objects, ensuring type safety throughout the process. The code sample demonstrates both serialization and deserialization.

const jsonString = typia.stringify<MyType>(data); const dataObject = typia.parse<MyType>(jsonString);

Other packages similar to typia

io-ts

io-ts is a runtime type system for IO decoding/encoding in TypeScript. It provides similar functionality to typia in terms of runtime type checking and validation. However, io-ts uses a functional programming approach and is more focused on decoding and encoding data.

zod

Zod is a TypeScript-first schema declaration and validation library. It offers similar validation and type-checking capabilities as typia but with a more declarative API for defining schemas. Zod is known for its simplicity and ease of use.

class-validator

Class-validator is a library for validating TypeScript class objects. It provides decorators for defining validation rules directly in class definitions. While it focuses on class-based validation, typia offers a broader range of type-related utilities.

README

Typia

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

// 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
    // +) isParse, validateParse 
    // +) stringify, isStringify, validateStringify

// PROTOCOL BUFFER
export function message<T>(): string; // Protocol Buffer message
export function assertDecode<T>(buffer: Buffer): T; // safe decoder
export function assertEncode<T>(input: T): Uint8Array; // safe encoder
    // +) decode, isDecode, validateDecode
    // +) encode, isEncode, validateEncode
    
// MISC
export function random<T>(): Primitive<T>; // generate random data
export function clone<T>(input: T): Primitive<T>; // deep clone
export function prune<T extends object>(input: T): void; // erase extra props
    // +) isClone, assertClone, validateClone
    // +) isPrune, assertPrune, validatePrune

typia is a transformer library of TypeScript, supporting below features:

• Super-fast Runtime Validators
• Safe JSON parse and fast stringify functions
• Protocol Buffer encoder and decoder
• Protobuf/JSON schema generator
• Random data generator

All functions in typia require only one line. You don't need any extra dedication like JSON schema definitions or decorator function calls. Just call typia function with only one line like typia.assert<T>(input).

Also, as typia performs AOT (Ahead of Time) compilation skill, its performance is much faster than other competitive libaries. For an example, when comparing validate function is() with other competitive libraries, typia is maximum 15,000x times faster than class-validator.

Measured on Intel i5-1135g7, Surface Pro 8

Sponsors

Thanks for your support.

Your donation would encourage typia development.

Setup

Transformation

npx typia setup

AOT (Ahead of Time) compilation mode.

When you write a TypeScript code calling typia.createIs<string | null>() function and compile it, typia will write optimal validation code like below, for the string | null type. This is the transform mode performing AOT (Ahead of Time) compilation.

// TYPESCRIPT CODE
import typia from "typia";
export const check = typia.createIs<string | null>();

// COMPILED JAVASCRIPT CODE
export const check = (input) => "string" === typeof input || null === input;

For reference, to use this transform mode, you've install one onf them; ttypescript or ts-patch.

If ttypescript, you should compile through ttsc command, instead of using tsc.

Otherwise, you've chosen ts-patch, you can use original tsc command. However, ts-patch hacks node_modules/typescript source code. Also, whenever update typescrtip version, you have to run npm run prepare command repeatedly.

By the way, when using @nest/cli, you must just choose ts-patch.

#--------
# TTYPESCRIPT
#--------
# COMPILE THROUGH TTYPESCRIPT
npx ttsc

# RUN TS-NODE WITH TTYPESCRIPT
npx ts-node -C ttypescript src/index.ts

#--------
# TS-PATCH
#--------
# USE ORIGINAL TSC COMMAND
tsc
npx ts-node src/index.ts

# WHENVER UPDATE
npm install --save-dev typescript@latest
npm run prepare

Generation

# INSTALL TYPIA
npm install --save typia

# GENERATE TRANSFORMED TYPESCRIPT CODES
npx typia generate \
    --input src/templates \
    --output src/generated \
    --project tsconfig.json

For frontend projects.

If you're using non-standard TypeScript compiler, you can't use transform mode.

• Non-standard TypeScript compilers:
  • swc in Next.JS
  • esbuild in Vite
  • babel in Create-React-App

Instead, you should utilize the generation mode.

Install typia through npm install command and run typia generate command. Then, generator of typia reads your TypeScript code of --input, and writes transformed TypeScript code into the --output directory, like below.

//--------
// src/templates/check.ts
//--------
import typia from "typia";
export const check = typia.createIs<string | null>();

//--------
// src/generated/check.ts
//--------
import typia from "typia";
export const check = 
    (input: unknown): input is string | null 
        => "string" === typeof input || null === input;

Features

In here README documents, only summarized informations are provided.

For more details, refer to the Guide Documents (wiki).

• Runtime Validators
  • powerful validator
  • is() function
  • assert() function
  • validate() function
  • strict validators
  • factory functions
  • comment tags
• Enhanced JSON
  • JSON schema
  • parse() functions
  • stringify() functions
  • comment tags
• Protocol Buffer
  • message() function
  • decode() function
  • encode() functions
  • comment tags
  • weaknesses
• Miscellaneous
  • random() function
  • clone() functions
  • prune() functions

Runtime Validators

// ALLOW SUPERFLUOUS PROPERTIES
export function is<T>(input: T | unknown): input is T; // returns boolean
export function assert<T>(input: T | unknown): T; // throws `TypeGuardError`
export function validate<T>(input: T | unknown): IValidation<T>; // detailed

// DO NOT ALLOW SUPERFLUOUS PROPERTIES
export function equals<T>(input: T | unknown): input is T;
export function assertEquals<T>(input: T | unknown): T;
export function validateEquals<T>(input: T | unknown): IValidation<T>;

// REUSABLE FACTORY FUNCTIONS
export function createIs<T>(): (input: unknown) => input is T;
export function createAssert<T>(): (input: unknown) => T;
export function createValidate<T>(): (input: unknown) => IValidation<T>;
export function createEquals<T>(): (input: unknown) => input is T;
export function createAssertEquals<T>(): (input: unknown) => T;
export function createValidateEquals<T>(): (input: unknown) => IValidation<T>;

typia supports three type of validator functions:

• is(): returns false if not matched with the type T
• assert(): throws a TypeGuardError when not matched
• validate()
  • when matched, returns IValidation.ISuccess<T> with value property
  • when not matched, returns IValidation.IFailure with errors property

Also, if you want more strict validator functions that even do not allowing superfluous properties not written in the type T, you can use those functions instead; equals(), assertEquals(), validateEquals(). Otherwise you want to create resuable validator functions, you can utilize factory functions like createIs() instead.

When you want to add special validation logics, like limiting range of numeric values, you can do it through comment tags. If you want to know about it, visit the Guide Documents (Features > Runtime Validators > Comment Tags).

Enhanced JSON

// JSON SCHEMA GENERATOR
export function application<
    Types extends unknown[],
    Purpose extends "swagger" | "ajv" = "swagger",
    Prefix extends string = Purpose extends "swagger"
        ? "#/components/schemas"
        : "components#/schemas",
>(): IJsonApplication;

// SAFE PARSER FUNCTIONS
export function isParse<T>(input: string): T | null;
export function assertParse<T>(input: string): T;
export function validateParse<T>(input: string): IValidation<T>;

// FASTER STRINGIFY FUNCTIONS
export function stringify<T>(input: T): string; // unsafe
export function isStringify<T>(input: T): string | null; // safe
export function assertStringify<T>(input: T): string;
export function validateStringify<T>(input: T): IValidation<string>;

// FACTORY FUNCTIONS
export function createAssertParse<T>(): (input: string) => T;
export function createAssertStringify<T>(): (input: T) => string;
    // +) createIsParse, createValidateParse
    // +) createStringify, createIsStringify, createValidateStringify

typia supports enhanced JSON functions.

• application(): generate JSON schema with only one line
  • you can complement JSON schema contents through comment tags
• assertParse(): parse JSON string safely with type validation
• isStringify(): maximum 10x faster JSON stringify fuction even type safe

Measured on AMD R7 6800HS

Protocol Buffer

// PROTOCOL BUFFER MESSAGE
export function message<T>(): string;

// ENCODE FUNCTIONS
export function encode<T>(input: T): Uint8Array;
export function isEncode<T>(input: T): Uint8Array | null;
export function assertEncode<T>(input: T): Uint8Array;
export function validateEncode<T>(input: T): IValidation<Uint8Array>;

// DECODE FUNCTIONS
export function decode<T>(buffer: Uint8Array): T;
export function isDecode<T>(buffer: Uint8Array): T | null;
export function assertDecode<T>(buffer: Uint8Array): T;
export function validateDecode<T>(buffer: Uint8Array): IValidation<T>;

// FACTORY FUNCTIONS
export function createDecode<T>(): (input: Uint8Array) => T;
export function createEncode<T>(): (input: T) => Uint8Array;
    // +) createIsDecode, createAssertDecode, createValidateDecode
    // +) createIsEncode, createAssertEncode, createValidateEncode

typia supports Protocol Buffer.

• message(): generate Protocol Buffer schema
• encode(): encode JavaScript object to Protocol Buffer
• decode(): decode Protocol Buffer to JavaScript object

Do not need to define any *.proto schema file. Just call above functions with generic argument T, then typia will generate the Protocol Buffer schema automatically, by analyzing your type T.

If you want to add special type like float32, you can do it through comment tags. If you want to know more about those comment tags, visit Guide Documents (Features > Protocol Buffer > Comment Tags).

Appendix

Nestia

Nestia is a set of helper libraries for NestJS, supporting below features:

• @nestia/core: 15,000x times faster validation decorators
• @nestia/sdk: evolved SDK and Swagger generators
  • SDK (Software Development Kit)
    • interaction library for client developers
    • almost same with tRPC
• nestia: just CLI (command line interface) tool

Reactia

Not published yet, but soon

Reactia is an automatic React components generator, just by analyzing TypeScript type.

• @reactia/core: Core Library analyzing TypeScript type
• @reactia/mui: Material UI Theme for core and nest
• @reactia/nest: Automatic Frontend Application Builder for NestJS

When you want to automate an individual component, just use @reactia/core.

import ReactDOM from "react-dom";

import typia from "typia";
import { ReactiaComponent } from "@reactia/core";
import { MuiInputTheme } from "@reactia/mui";

const RequestInput = ReactiaComponent<IRequestDto>(MuiInputTheme());
const input: IRequestDto = { ... };

ReactDOM.render(
    <RequestInput input={input} />,
    document.body
);

Otherwise, you can fully automate frontend application development through @reactia/nest.

import React from "react";
import ReactDOM from "react-dom";

import { ISwagger } "@nestia/swagger";
import { MuiApplicationTheme } from "@reactia/mui";
import { ReactiaApplication } from "@reactia/nest";

const swagger: ISwagger = await import("./swagger.json");
const App: React.FC = ReactiaApplication(MuiApplicationTheme())(swagger);

ReactDOM.render(
    <App />,
    document.body
);