is() function

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.

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

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.

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

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.

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

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:

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.

{
  "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.

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
  • Outline
  • Type Tags
  • Comment Tags
  • Customization

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.

Measured on Intel i5-1135g7, Surface Pro 8 (opens in a new tab)

C.V. means class-validator