Typia Guide Documents

`parse()` functions

undefined


export namespace json {
  export function isParse<T>(input: string): Primitive<T> | null;
  export function assertParse<T>(input: string): Primitive<T>;
  export function validateParse<T>(input: string): IValidation<Primitive<T>>;
}

undefined

typia/TypeGuardError.ts


/**
 * Error thrown when type assertion fails.
 *
 * Thrown by {@link assert}, {@link assertGuard}, and other assert-family
 * functions when input doesn't match expected type `T`. Contains detailed
 * information about the first assertion failure:
 *
 * - `method`: Which typia function threw (e.g., `"typia.assert"`)
 * - `path`: Property path where error occurred (e.g., `"input.user.age"`)
 * - `expected`: Expected type string (e.g., `"number & ExclusiveMinimum<19>"`)
 * - `value`: Actual value that failed validation
 *
 * @template T Expected type (for type safety)
 */
export class TypeGuardError<T = any> extends Error {
  /**
   * Name of the typia method that threw this error.
   *
   * E.g., `"typia.assert"`, `"typia.assertEquals"`, `"typia.assertGuard"`.
   */
  public readonly method: string;
 
  /**
   * Property path where assertion failed.
   *
   * Uses dot notation for nested properties. `undefined` if error occurred at
   * root level.
   *
   * E.g., `"input.age"`, `"input.profile.email"`, `"input[0].name"`.
   */
  public readonly path: string | undefined;
 
  /**
   * String representation of expected type.
   *
   * E.g., `"string"`, `"number & ExclusiveMinimum<19>"`, `"{ name: string; age:
   * number }"`.
   */
  public readonly expected: string;
 
  /**
   * Actual value that failed assertion.
   *
   * The raw value at the error path, useful for debugging.
   */
  public readonly value: unknown;
 
  /**
   * Optional human-readable error description.
   *
   * Primarily for AI agent libraries or custom validation scenarios needing
   * additional context. Standard assertions rely on `path`, `expected`, and
   * `value` for error reporting.
   */
  public readonly description?: string | undefined;
 
  /**
   * Phantom property for TypeScript type safety.
   *
   * Not used at runtime—exists only to preserve generic type `T` in the type
   * system. Always `undefined`.
   *
   * @internal
   */
  protected readonly fake_expected_typed_value_?: T | undefined;
 
  /**
   * Creates a new TypeGuardError instance.
   *
   * @param props Error properties
   */
  public constructor(props: TypeGuardError.IProps) {
    // MESSAGE CONSTRUCTION
    // Use custom message if provided, otherwise generate default format
    super(
      props.message ||
        `Error on ${props.method}(): invalid type${
          props.path ? ` on ${props.path}` : ""
        }, expect to be ${props.expected}`,
    );
 
    // INHERITANCE POLYFILL
    // Set up prototype for compatibility across different JavaScript environments
    const proto = new.target.prototype;
    if (Object.setPrototypeOf) Object.setPrototypeOf(this, proto);
    else (this as any).__proto__ = proto;
 
    // ASSIGN MEMBERS
    this.method = props.method;
    this.path = props.path;
    this.expected = props.expected;
    this.value = props.value;
    if (props.description || props.value === undefined)
      this.description =
        props.description ??
        [
          "The value at this path is `undefined`.",
          "",
          `Please fill the \`${props.expected}\` typed value next time.`,
        ].join("\n");
  }
}
 
export namespace TypeGuardError {
  /** Properties for constructing a TypeGuardError. */
  export interface IProps {
    /**
     * Name of the typia method that threw the error.
     *
     * E.g., `"typia.assert"`, `"typia.assertEquals"`.
     */
    method: string;
 
    /**
     * Property path where assertion failed (optional).
     *
     * E.g., `"input.age"`, `"input.profile.email"`.
     */
    path?: undefined | string;
 
    /**
     * String representation of expected type.
     *
     * E.g., `"string"`, `"number & ExclusiveMinimum<19>"`.
     */
    expected: string;
 
    /** Actual value that failed assertion. */
    value: unknown;
 
    /**
     * Optional human-readable error description.
     *
     * For AI agent libraries or custom validation needing additional context.
     */
    description?: string;
 
    /**
     * Custom error message (optional).
     *
     * If not provided, a default message is generated from other properties.
     */
    message?: undefined | string;
  }
}

undefined

@typia/interface/IValidation.ts


/**
 * Validation result type with detailed error information.
 *
 * `IValidation<T>` is the return type of `typia.validate<T>()` and related
 * validation functions. Unlike `typia.is<T>()` which returns a boolean, or
 * `typia.assert<T>()` which throws exceptions, `typia.validate<T>()` returns
 * this structured result with full error details.
 *
 * Check the {@link IValidation.success | success} discriminator:
 *
 * - `true` → {@link IValidation.ISuccess} with validated
 *   {@link IValidation.ISuccess.data | data}
 * - `false` → {@link IValidation.IFailure} with
 *   {@link IValidation.IFailure.errors | errors} array
 *
 * This is the recommended validation function when you need to report
 * validation errors to users or log them for debugging.
 *
 * @author Jeongho Nam - https://github.com/samchon
 * @example
 *   const result = typia.validate<User>(input);
 *   if (result.success) {
 *     return result.data; // User type
 *   } else {
 *     result.errors.forEach((e) => console.log(e.path, e.expected));
 *   }
 *
 * @template T The expected type after successful validation
 */
export type IValidation<T = unknown> =
  | IValidation.ISuccess<T>
  | IValidation.IFailure;
 
export namespace IValidation {
  /**
   * Successful validation result.
   *
   * Indicates the input matches the expected type. The validated data is
   * available in {@link data} with full type information.
   *
   * @template T The validated type
   */
  export interface ISuccess<T = unknown> {
    /**
     * Success discriminator.
     *
     * Always `true` for successful validations. Use this to narrow the type
     * before accessing {@link data}.
     */
    success: true;
 
    /**
     * The validated data with correct type.
     *
     * The original input after successful validation. TypeScript will narrow
     * this to type `T` when {@link success} is `true`.
     */
    data: T;
  }
 
  /**
   * Failed validation result with error details.
   *
   * Indicates the input did not match the expected type. Contains the original
   * data and an array of all validation errors found.
   */
  export interface IFailure {
    /**
     * Success discriminator.
     *
     * Always `false` for failed validations. Use this to narrow the type before
     * accessing {@link errors}.
     */
    success: false;
 
    /**
     * The original input that failed validation.
     *
     * Preserved as `unknown` type since it didn't match the expected type.
     * Useful for debugging or logging the actual value.
     */
    data: unknown;
 
    /**
     * Array of validation errors.
     *
     * Contains one entry for each validation failure found. Multiple errors may
     * exist if the input has multiple type mismatches.
     */
    errors: IError[];
  }
 
  /**
   * Detailed information about a single validation error.
   *
   * Describes exactly what went wrong during validation, including the
   * location, expected type, and actual value.
   */
  export interface IError {
    /**
     * Property path to the error location.
     *
     * A dot-notation path from the root input to the failing property. Uses
     * `$input` as the root. Example: `"$input.user.email"` or
     * `"$input.items[0].price"`.
     */
    path: string;
 
    /**
     * Expected type expression.
     *
     * A human-readable description of what type was expected at this location.
     * Examples: `"string"`, `"number & ExclusiveMinimum<0>"`, `"(\"active\" |
     * \"inactive\")"`.
     */
    expected: string;
 
    /**
     * The actual value that failed validation.
     *
     * The value found at the error path. May be `undefined` if the property was
     * missing. Useful for debugging type mismatches.
     */
    value: unknown;
 
    /**
     * Human-readable error description.
     *
     * Optional additional context about the validation failure, such as
     * constraint violations or custom error messages.
     */
    description?: string;
  }
}

undefined

typia/Primitive.ts


file not found: src/Primitive.ts

Type safe JSON parser.

Unlike native JSON.parse() function which returns any typed instance without type checking, typia.json.assertParse<T>() function validates instance type after the parsing. If the parsed value is not following the promised type T, it throws TypeGuardError with the first type error info.

If you want to know every type error infos detaily, you can use typia.json.validateParse<T>() function instead. Otherwise, you just only want to know whether the parsed value is following the type T or not, just call typia.json.isParse<T>() function.

typia.json.isParse<T>(): JSON.parse() + typia.is<T>()
typia.json.assertParse<T>(): JSON.parse() + typia.assert<T>()
typia.json.validateParse<T>(): JSON.parse() + typia.validate<T>()

Look at the below code, then you may understand how the typia.json.assertParse<T>() function works.

TypeScript Source Code

examples/src/json/assertParse.ts


import typia, { tags } from "typia";
 
const json: string = JSON.stringify(typia.random<IMember>());
const parsed: IMember = typia.json.assertParse<IMember>(json);
 
console.log(json === JSON.stringify(parsed)); // true
 
interface IMember {
  id: string & tags.Format<"uuid">;
  email: string & tags.Format<"email">;
  age: number &
    tags.Type<"uint32"> &
    tags.ExclusiveMinimum<19> &
    tags.Maximum<100>;
}

Compiled JavaScript File

examples/bin/json/assertParse.js


import typia from "typia";
import * as __typia_transform__assertGuard from "typia/lib/internal/_assertGuard";
import * as __typia_transform__isFormatEmail from "typia/lib/internal/_isFormatEmail";
import * as __typia_transform__isFormatUuid from "typia/lib/internal/_isFormatUuid";
import * as __typia_transform__isTypeUint32 from "typia/lib/internal/_isTypeUint32";
import * as __typia_transform__randomFormatEmail from "typia/lib/internal/_randomFormatEmail";
import * as __typia_transform__randomFormatUuid from "typia/lib/internal/_randomFormatUuid";
import * as __typia_transform__randomInteger from "typia/lib/internal/_randomInteger";
 
const json = JSON.stringify(
  (() => {
    const _ro0 = (_recursive = false, _depth = 0) => ({
      id: (
        _generator?.uuid ??
        __typia_transform__randomFormatUuid._randomFormatUuid
      )(),
      email: (
        _generator?.email ??
        __typia_transform__randomFormatEmail._randomFormatEmail
      )(),
      age: (
        _generator?.integer ?? __typia_transform__randomInteger._randomInteger
      )({
        type: "integer",
        minimum: 0,
        exclusiveMinimum: 19,
        maximum: 100,
      }),
    });
    let _generator;
    return (generator) => {
      _generator = generator;
      return _ro0();
    };
  })()(),
);
const parsed = (() => {
  const _io0 = (input) =>
    "string" === typeof input.id &&
    __typia_transform__isFormatUuid._isFormatUuid(input.id) &&
    "string" === typeof input.email &&
    __typia_transform__isFormatEmail._isFormatEmail(input.email) &&
    "number" === typeof input.age &&
    __typia_transform__isTypeUint32._isTypeUint32(input.age) &&
    19 < input.age &&
    input.age <= 100;
  const _ao0 = (input, _path, _exceptionable = true) =>
    (("string" === typeof input.id &&
      (__typia_transform__isFormatUuid._isFormatUuid(input.id) ||
        __typia_transform__assertGuard._assertGuard(
          _exceptionable,
          {
            method: "typia.json.assertParse",
            path: _path + ".id",
            expected: 'string & Format<"uuid">',
            value: input.id,
          },
          _errorFactory,
        ))) ||
      __typia_transform__assertGuard._assertGuard(
        _exceptionable,
        {
          method: "typia.json.assertParse",
          path: _path + ".id",
          expected: '(string & Format<"uuid">)',
          value: input.id,
        },
        _errorFactory,
      )) &&
    (("string" === typeof input.email &&
      (__typia_transform__isFormatEmail._isFormatEmail(input.email) ||
        __typia_transform__assertGuard._assertGuard(
          _exceptionable,
          {
            method: "typia.json.assertParse",
            path: _path + ".email",
            expected: 'string & Format<"email">',
            value: input.email,
          },
          _errorFactory,
        ))) ||
      __typia_transform__assertGuard._assertGuard(
        _exceptionable,
        {
          method: "typia.json.assertParse",
          path: _path + ".email",
          expected: '(string & Format<"email">)',
          value: input.email,
        },
        _errorFactory,
      )) &&
    (("number" === typeof input.age &&
      (__typia_transform__isTypeUint32._isTypeUint32(input.age) ||
        __typia_transform__assertGuard._assertGuard(
          _exceptionable,
          {
            method: "typia.json.assertParse",
            path: _path + ".age",
            expected: 'number & Type<"uint32">',
            value: input.age,
          },
          _errorFactory,
        )) &&
      (19 < input.age ||
        __typia_transform__assertGuard._assertGuard(
          _exceptionable,
          {
            method: "typia.json.assertParse",
            path: _path + ".age",
            expected: "number & ExclusiveMinimum<19>",
            value: input.age,
          },
          _errorFactory,
        )) &&
      (input.age <= 100 ||
        __typia_transform__assertGuard._assertGuard(
          _exceptionable,
          {
            method: "typia.json.assertParse",
            path: _path + ".age",
            expected: "number & Maximum<100>",
            value: input.age,
          },
          _errorFactory,
        ))) ||
      __typia_transform__assertGuard._assertGuard(
        _exceptionable,
        {
          method: "typia.json.assertParse",
          path: _path + ".age",
          expected:
            '(number & Type<"uint32"> & ExclusiveMinimum<19> & Maximum<100>)',
          value: input.age,
        },
        _errorFactory,
      ));
  const __is = (input) =>
    "object" === typeof input && null !== input && _io0(input);
  let _errorFactory;
  const __assert = (input, errorFactory) => {
    if (false === __is(input)) {
      _errorFactory = errorFactory;
      ((input, _path, _exceptionable = true) =>
        ((("object" === typeof input && null !== input) ||
          __typia_transform__assertGuard._assertGuard(
            true,
            {
              method: "typia.json.assertParse",
              path: _path + "",
              expected: "IMember",
              value: input,
            },
            _errorFactory,
          )) &&
          _ao0(input, _path + "", true)) ||
        __typia_transform__assertGuard._assertGuard(
          true,
          {
            method: "typia.json.assertParse",
            path: _path + "",
            expected: "IMember",
            value: input,
          },
          _errorFactory,
        ))(input, "$input", true);
    }
    return input;
  };
  return (input, errorFactory) => __assert(JSON.parse(input), errorFactory);
})()(json);
console.log(json === JSON.stringify(parsed)); // true

Reusable functions

undefined


export namespace json {
  export function createIsParse<T>(): (input: string) => Primitive<T> | null;
  export function createAssertParse<T>(): (input: string) => Primitive<T>;
  export function createValidateParse<T>(): (
    input: string,
  ) => IValidation<Primitive<T>>;
}

undefined

typia/TypeGuardError.ts


/**
 * Error thrown when type assertion fails.
 *
 * Thrown by {@link assert}, {@link assertGuard}, and other assert-family
 * functions when input doesn't match expected type `T`. Contains detailed
 * information about the first assertion failure:
 *
 * - `method`: Which typia function threw (e.g., `"typia.assert"`)
 * - `path`: Property path where error occurred (e.g., `"input.user.age"`)
 * - `expected`: Expected type string (e.g., `"number & ExclusiveMinimum<19>"`)
 * - `value`: Actual value that failed validation
 *
 * @template T Expected type (for type safety)
 */
export class TypeGuardError<T = any> extends Error {
  /**
   * Name of the typia method that threw this error.
   *
   * E.g., `"typia.assert"`, `"typia.assertEquals"`, `"typia.assertGuard"`.
   */
  public readonly method: string;
 
  /**
   * Property path where assertion failed.
   *
   * Uses dot notation for nested properties. `undefined` if error occurred at
   * root level.
   *
   * E.g., `"input.age"`, `"input.profile.email"`, `"input[0].name"`.
   */
  public readonly path: string | undefined;
 
  /**
   * String representation of expected type.
   *
   * E.g., `"string"`, `"number & ExclusiveMinimum<19>"`, `"{ name: string; age:
   * number }"`.
   */
  public readonly expected: string;
 
  /**
   * Actual value that failed assertion.
   *
   * The raw value at the error path, useful for debugging.
   */
  public readonly value: unknown;
 
  /**
   * Optional human-readable error description.
   *
   * Primarily for AI agent libraries or custom validation scenarios needing
   * additional context. Standard assertions rely on `path`, `expected`, and
   * `value` for error reporting.
   */
  public readonly description?: string | undefined;
 
  /**
   * Phantom property for TypeScript type safety.
   *
   * Not used at runtime—exists only to preserve generic type `T` in the type
   * system. Always `undefined`.
   *
   * @internal
   */
  protected readonly fake_expected_typed_value_?: T | undefined;
 
  /**
   * Creates a new TypeGuardError instance.
   *
   * @param props Error properties
   */
  public constructor(props: TypeGuardError.IProps) {
    // MESSAGE CONSTRUCTION
    // Use custom message if provided, otherwise generate default format
    super(
      props.message ||
        `Error on ${props.method}(): invalid type${
          props.path ? ` on ${props.path}` : ""
        }, expect to be ${props.expected}`,
    );
 
    // INHERITANCE POLYFILL
    // Set up prototype for compatibility across different JavaScript environments
    const proto = new.target.prototype;
    if (Object.setPrototypeOf) Object.setPrototypeOf(this, proto);
    else (this as any).__proto__ = proto;
 
    // ASSIGN MEMBERS
    this.method = props.method;
    this.path = props.path;
    this.expected = props.expected;
    this.value = props.value;
    if (props.description || props.value === undefined)
      this.description =
        props.description ??
        [
          "The value at this path is `undefined`.",
          "",
          `Please fill the \`${props.expected}\` typed value next time.`,
        ].join("\n");
  }
}
 
export namespace TypeGuardError {
  /** Properties for constructing a TypeGuardError. */
  export interface IProps {
    /**
     * Name of the typia method that threw the error.
     *
     * E.g., `"typia.assert"`, `"typia.assertEquals"`.
     */
    method: string;
 
    /**
     * Property path where assertion failed (optional).
     *
     * E.g., `"input.age"`, `"input.profile.email"`.
     */
    path?: undefined | string;
 
    /**
     * String representation of expected type.
     *
     * E.g., `"string"`, `"number & ExclusiveMinimum<19>"`.
     */
    expected: string;
 
    /** Actual value that failed assertion. */
    value: unknown;
 
    /**
     * Optional human-readable error description.
     *
     * For AI agent libraries or custom validation needing additional context.
     */
    description?: string;
 
    /**
     * Custom error message (optional).
     *
     * If not provided, a default message is generated from other properties.
     */
    message?: undefined | string;
  }
}

undefined

@typia/interface/IValidation.ts


/**
 * Validation result type with detailed error information.
 *
 * `IValidation<T>` is the return type of `typia.validate<T>()` and related
 * validation functions. Unlike `typia.is<T>()` which returns a boolean, or
 * `typia.assert<T>()` which throws exceptions, `typia.validate<T>()` returns
 * this structured result with full error details.
 *
 * Check the {@link IValidation.success | success} discriminator:
 *
 * - `true` → {@link IValidation.ISuccess} with validated
 *   {@link IValidation.ISuccess.data | data}
 * - `false` → {@link IValidation.IFailure} with
 *   {@link IValidation.IFailure.errors | errors} array
 *
 * This is the recommended validation function when you need to report
 * validation errors to users or log them for debugging.
 *
 * @author Jeongho Nam - https://github.com/samchon
 * @example
 *   const result = typia.validate<User>(input);
 *   if (result.success) {
 *     return result.data; // User type
 *   } else {
 *     result.errors.forEach((e) => console.log(e.path, e.expected));
 *   }
 *
 * @template T The expected type after successful validation
 */
export type IValidation<T = unknown> =
  | IValidation.ISuccess<T>
  | IValidation.IFailure;
 
export namespace IValidation {
  /**
   * Successful validation result.
   *
   * Indicates the input matches the expected type. The validated data is
   * available in {@link data} with full type information.
   *
   * @template T The validated type
   */
  export interface ISuccess<T = unknown> {
    /**
     * Success discriminator.
     *
     * Always `true` for successful validations. Use this to narrow the type
     * before accessing {@link data}.
     */
    success: true;
 
    /**
     * The validated data with correct type.
     *
     * The original input after successful validation. TypeScript will narrow
     * this to type `T` when {@link success} is `true`.
     */
    data: T;
  }
 
  /**
   * Failed validation result with error details.
   *
   * Indicates the input did not match the expected type. Contains the original
   * data and an array of all validation errors found.
   */
  export interface IFailure {
    /**
     * Success discriminator.
     *
     * Always `false` for failed validations. Use this to narrow the type before
     * accessing {@link errors}.
     */
    success: false;
 
    /**
     * The original input that failed validation.
     *
     * Preserved as `unknown` type since it didn't match the expected type.
     * Useful for debugging or logging the actual value.
     */
    data: unknown;
 
    /**
     * Array of validation errors.
     *
     * Contains one entry for each validation failure found. Multiple errors may
     * exist if the input has multiple type mismatches.
     */
    errors: IError[];
  }
 
  /**
   * Detailed information about a single validation error.
   *
   * Describes exactly what went wrong during validation, including the
   * location, expected type, and actual value.
   */
  export interface IError {
    /**
     * Property path to the error location.
     *
     * A dot-notation path from the root input to the failing property. Uses
     * `$input` as the root. Example: `"$input.user.email"` or
     * `"$input.items[0].price"`.
     */
    path: string;
 
    /**
     * Expected type expression.
     *
     * A human-readable description of what type was expected at this location.
     * Examples: `"string"`, `"number & ExclusiveMinimum<0>"`, `"(\"active\" |
     * \"inactive\")"`.
     */
    expected: string;
 
    /**
     * The actual value that failed validation.
     *
     * The value found at the error path. May be `undefined` if the property was
     * missing. Useful for debugging type mismatches.
     */
    value: unknown;
 
    /**
     * Human-readable error description.
     *
     * Optional additional context about the validation failure, such as
     * constraint violations or custom error messages.
     */
    description?: string;
  }
}

undefined

typia/Primitive.ts


file not found: src/Primitive.ts

Reusable typia.json.isParse<T>() function generators.

If you repeat to call typia.json.isParse<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.createIsParse<T>() function.

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

TypeScript Source Code

examples/src/json/createIsParse.ts


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

parse() functions

undefined

undefined

undefined

undefined

TypeScript Source Code

Compiled JavaScript File

Reusable functions

undefined

undefined

undefined

undefined

TypeScript Source Code

Compiled JavaScript File

`parse()` functions