Typia Guide Documents

`is()` function

typia

export function is<T>(input: T): input is T;
export function is<T>(input: unknown): input is T;

Tests a value type.

When you need to test an instance type, just call typia.is<T>() function.

If the input value is following type T, true value would be returned. Otherwise, false would be returned.

AOT compliation

If you’d used other competitive validator libraries like ajv or class-validator, you may found that typia does not require any extra schema definition. If you have not experienced them, I can sure that you may get shocked after reading below extra schema definition files.

ajv requires JSON schema definition.
class-validator requires DTO class with decorator function calls.

Yeah, typia needs only pure TypeScript type. As typia is a compiler library, it can analyze TypeScript type by itself, and possible to write the optimal validation code like below. This is the key principle of typia, which needs only one line with pure TypeScript type.

examples/src/is.ts

import typia, { tags } from "typia";
import { v4 } from "uuid";
 
const matched: boolean = typia.is<IMember>({
  id: v4(),
  email: "samchon.github@gmai19l.com",
  age: 30,
});
 
console.log(matched); // true
 
interface IMember {
  id: string & tags.Format<"uuid">;
  email: string & tags.Format<"email">;
  age: number &
    tags.Type<"uint32"> &
    tags.ExclusiveMinimum<19> &
    tags.Maximum<100>;
}

`equals()` function

typia

export function equals<T>(input: T): input is T;
export function equals<T>(input: unknown): input is T;

More strict checker prohibiting superfluous properties.

typia.is<T>() can test instance type, but it allows superfluous properties.

If you want to prohibit those superfluous properties, you can use typia.equals<T>() function instead.

examples/src/equals.ts

import typia, { tags } from "typia";
import { v4 } from "uuid";
 
const input: unknown = {
  id: v4(),
  email: "samchon.github@gmail.com",
  age: 30,
  extra: "superfluous property", // extra
};
const is: boolean = typia.is<IMember>(input);
const equals: boolean = typia.equals<IMember>(input);
 
console.log(is, equals); // true, false
 
interface IMember {
  id: string & tags.Format<"uuid">;
  email: string & tags.Format<"email">;
  age: number &
    tags.Type<"uint32"> &
    tags.ExclusiveMinimum<19> &
    tags.Maximum<100>;
}

Reusable functions

typia

export function createIs<T>(): (input: unknown) => input is T;
export function createEquals<T>(): (input: unknown) => input is T;

Reusable typia.is<T>() function generators.

If you repeat to call typia.is<T>() function on the same type, size of JavaScript files would be larger because of duplicated AOT compilation. To prevent it, you can generate reusable function through typia.createIs<T>() function.

Just look at the code below, then you may understand how to use it.

examples/src/createIs.ts

import typia, { tags } from "typia";
 
export const check = typia.createIs<IMember>();
 
interface IMember {
  id: string & tags.Format<"uuid">;
  email: string & tags.Format<"email">;
  age: number &
    tags.Type<"uint32"> &
    tags.ExclusiveMinimum<19> &
    tags.Maximum<100>;
}

Auto Type Casting

typia

export function is<T>(input: unknown): input is T;
export function equals<T>(input: unknown): input is T;
export function createIs<T>(): (input: unknown) => input is T;
export function createEquals<T>(): (input: unknown) => input is T;

typia.is<T>() function can be used for type casting.

When target input value is following the type T, therefore true value be returned, typia.is<T>() function automatically casts the input value to the type T. Therefore, you can utilize the typia.is<T>() function for safe type casting tool like below:

examples/src/is-cast.ts

const input: unknown = {
  id: v4(),
  email: "samchon.github@gmail.com",
  age: 30,
} as any;
 
if (typia.is<IMember>(input)) {
  // auto type casting
  console.log(input.id, input.email, input.age);
}

Restrictions

typia.is<T>() function does not check function and user-defined class types.

It validates only the primitive properties. Therefore, typia.is<T>() function does not perform the instanceof ClassName for user-defined classes. If you want to validate the user-defined class type in addition to the property types, do it by yourself. Also, typia.is<T>() function does not validate the function type either, unless configuring functional property of plugin option in the tsconfig.json file.

tsconfig.json

{
  "compilerOptions": {
    "plugins": [
      {
        "transform": "typia/lib/transform",
        "functional": true
      }
    ]
  }
}

By the way, there’re some exception cases.

If JS native class type like Date, Uint8Array, or Map<Key, T> being utilized, typia.is<T>() function validates them. Especially about the Set<T>, and Map<Key, T> class cases, typia.is<T>() function validates all of their contained element types, too.

Therefore, the instanceof statement does not be used only for the user-defined classes.

examples/src/is-map.ts

import typia from "typia";
 
typia.createIs<Map<string, boolean | number | string>>();

Customization

You can enhance validation logic by special tags.

Also, with those tags, you can add your custom validation logic, too.

If you want to know about such special tags detaily, read below article:

Special Tags

examples/src/is-custom-tags.ts

import typia, { tags } from "typia";
 
export const checkSomething = typia.createIs<Something>();
 
//----
// DEFINE CUSTOM TYPE TAGS
//----
type Dollar = tags.TagBase<{
  kind: "dollar";
  target: "string";
  value: undefined;
  validate: `$input[0] === "$" && !isNaN(Number($input.substring(1).split(",").join("")))`;
}>;
 
type Postfix<Value extends string> = tags.TagBase<{
  kind: "postfix";
  target: "string";
  value: Value;
  validate: `$input.endsWith("${Value}")`;
}>;
 
type IsEven<Value extends number | bigint> = tags.TagBase<{
  kind: "isEven";
  target: Value extends number ? "number" : "bigint";
  value: undefined;
  validate: `$input % ${Numeric<2>} === ${Numeric<0>}`;
}>;
 
type Numeric<Value extends number | bigint> = Value extends number
  ? Value
  : `BigInt(${Value})`;
 
//----
// VALIDATION
//----
interface Something {
  dollar: string & Dollar;
  postfix: string & Postfix<"!!!">;
  isEven: number & IsEven<number>;
}

Performance

Super-fast and super-safe.

Comparing typia.is<T>() function with other competitive libraries, maximum 20,000x faster.

Furthermore, only typia can validate complicate union types.

Is Function Benchmark

Measured on AMD Ryzen 9 7940HS, Rog Flow x13

Components	`typia`	`TypeBox`	`ajv`	`io-ts`	`zod`	`C.V.`
Easy to use	✅	❌	❌	❌	❌	❌
Object (simple)	✔	✔	✔	✔	✔	✔
Object (hierarchical)	✔	✔	✔	✔	✔	✔
Object (recursive)	✔	❌	✔	✔	✔	✔
Object (union, implicit)	✅	❌	❌	❌	❌	❌
Object (union, explicit)	✔	✔	✔	✔	✔	❌
Object (additional tags)	✔	✔	✔	✔	✔	✔
Object (template literal types)	✔	✔	✔	❌	❌	❌
Object (dynamic properties)	✔	✔	✔	❌	❌	❌
Array (rest tuple)	✅	❌	❌	❌	❌	❌
Array (hierarchical)	✔	✔	✔	✔	✔	✔
Array (recursive)	✔	✔	✔	✔	✔	❌
Array (recursive, union)	✔	✔	❌	✔	✔	❌
Array (R+U, implicit)	✅	❌	❌	❌	❌	❌
Array (repeated)	✅	❌	❌	❌	❌	❌
Array (repeated, union)	✅	❌	❌	❌	❌	❌
Ultimate Union Type	✅	❌	❌	❌	❌	❌

C.V. means class-validator

assert() function validate() function

is() function

equals() function

Reusable functions

Auto Type Casting

Restrictions

Customization

Performance

`is()` function

`equals()` function