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


/**
 * Custom error class thrown when runtime assertion fails in `typia.assert<T>()`
 * function.
 *
 * This error is thrown by the `typia.assert<T>()` function when the input value
 * doesn't match the expected type.
 *
 * The error provides detailed information about the first assertion failure
 * encountered, including the access path where the error occurred, the expected
 * type, and the actual value.
 *
 * @author Jeongho Nam - https://github.com/samchon
 * @example
 *   ```typescript
 *   interface IMember {
 *     name: string;
 *     age: number & ExclusiveMinimum<19>;
 *   }
 *
 *   try {
 *     typia.assert<IMember>({ name: "John", age: 18 });
 *   } catch (error) {
 *     if (error instanceof TypeGuardError) {
 *       console.log(error.method);   // "typia.assert"
 *       console.log(error.path);     // "input.age"
 *       console.log(error.expected); // "number & ExclusiveMinimum<19>"
 *       console.log(error.value);    // 18
 *     }
 *   }
 *   ```;
 *
 * @template T - The expected type (generic for type safety)
 */
export class TypeGuardError<T = any> extends Error {
  /**
   * The name of the typia method that threw this error.
   *
   * @example
   *   typia.assert;
   */
  public readonly method: string;
 
  /**
   * The access path to the property where the assertion error occurred.
   *
   * Uses dot notation to indicate the path for nested object properties. May be
   * `undefined` if the error occurred at the root level.
   *
   * @example
   *   - `"input.age"` - Error in the age property of the object
   *   - `"input.profile.email"` - Error in the email property of a nested object
   *   - `"input[0].name"` - Error in the name property of the first array element
   *   - `undefined` - Error occurred at the root level
   */
  public readonly path: string | undefined;
 
  /**
   * String representation of the expected type at the error location.
   *
   * Represents TypeScript types as strings, including detailed type information
   * for complex types.
   *
   * @example
   *   - `"string"` - Expected string type
   *   - `"number & ExclusiveMinimum<19>"` - Expected number greater than 19
   *   - `"undefined"` - Expected undefined (when superfluous property found in assertion)
   *   - `"{ name: string; age: number }"` - Expected object type
   */
  public readonly expected: string;
 
  /**
   * The actual value that failed assertion.
   *
   * Stores the actual value at the error path as-is. Useful for debugging by
   * comparing the expected type with the actual value.
   *
   * @example
   *   - `18` - Numeric value
   *   - `"invalid"` - String value
   *   - `{ name: "John", age: 18, sex: 1 }` - Object value
   */
  public readonly value: unknown;
 
  /**
   * Optional human-readable description of the type guard error
   *
   * This field is rarely populated in standard typia type assertion and is
   * primarily intended for specialized AI agent libraries or custom validation
   * scenarios that require additional context beyond the technical type
   * information. Most assertion errors rely solely on the path, expected, and
   * value fields for comprehensive error reporting.
   */
  public readonly description?: string | undefined;
 
  /**
   * Phantom property for type safety purposes.
   *
   * This property is not actually used and exists only to maintain the generic
   * type T in TypeScript's type system. Always has an `undefined` value at
   * runtime.
   *
   * @internal
   */
  protected readonly fake_expected_typed_value_?: T | undefined;
 
  /**
   * Creates a new TypeGuardError instance.
   *
   * @example
   *   ```typescript
   *   const error = new TypeGuardError({
   *     method: "typia.assert",
   *     path: "input.age",
   *     expected: "number & ExclusiveMinimum<19>",
   *     value: 18
   *   });
   *   ```;
   *
   * @param props - Object containing the properties needed to create the error
   */
  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 {
  /**
   * Interface for properties passed to the TypeGuardError constructor.
   *
   * @example
   *   ```typescript
   *   const props: TypeGuardError.IProps = {
   *     method: "typia.assertEquals",
   *     path: "input.sex",
   *     expected: "undefined",
   *     value: 1,
   *     message: "Custom error message" // optional
   *   };
   *   ```;
   */
  export interface IProps {
    /**
     * The name of the typia method that threw the error.
     *
     * @example
     *   typia.assert, "typia.assertEquals";
     */
    method: string;
 
    /**
     * The access path to the property where the assertion error occurred
     * (optional).
     *
     * @example
     *   input.age, "input.profile.email";
     */
    path?: undefined | string;
 
    /**
     * String representation of the expected type at the error location.
     *
     * @example
     *   string, "number & ExclusiveMinimum<19>";
     */
    expected: string;
 
    /** The actual value that failed assertion. */
    value: unknown;
 
    /**
     * Optional human-readable description of the type guard error
     *
     * This field is rarely populated in standard typia type assertion and is
     * primarily intended for specialized AI agent libraries or custom
     * validation scenarios that require additional context beyond the technical
     * type information. Most assertion errors rely solely on the path,
     * expected, and value fields for comprehensive error reporting.
     */
    description?: string;
 
    /**
     * Custom error message (optional).
     *
     * If not provided, a default format message will be automatically
     * generated.
     */
    message?: undefined | string;
  }
}

undefined

@samchon/openapi


/**
 * Union type representing the result of type validation
 *
 * This is the return type of {@link typia.validate} functions, returning
 * {@link IValidation.ISuccess} on validation success and
 * {@link IValidation.IFailure} on validation failure. When validation fails, it
 * provides detailed, granular error information that precisely describes what
 * went wrong, where it went wrong, and what was expected.
 *
 * This comprehensive error reporting makes `IValidation` particularly valuable
 * for AI function calling scenarios, where Large Language Models (LLMs) need
 * specific feedback to correct their parameter generation. The detailed error
 * information is used by ILlmFunction.validate() to provide validation feedback
 * to AI agents, enabling iterative correction and improvement of function
 * calling accuracy.
 *
 * This type uses the Discriminated Union pattern, allowing type specification
 * through the success property:
 *
 * ```typescript
 * const result = typia.validate<string>(input);
 * if (result.success) {
 *   // IValidation.ISuccess<string> type
 *   console.log(result.data); // validated data accessible
 * } else {
 *   // IValidation.IFailure type
 *   console.log(result.errors); // detailed error information accessible
 * }
 * ```
 *
 * @author Jeongho Nam - https://github.com/samchon
 * @template T The type to validate
 */
export type IValidation<T = unknown> =
  | IValidation.ISuccess<T>
  | IValidation.IFailure;
 
export namespace IValidation {
  /**
   * Interface returned when type validation succeeds
   *
   * Returned when the input value perfectly conforms to the specified type T.
   * Since success is true, TypeScript's type guard allows safe access to the
   * validated data through the data property.
   *
   * @template T The validated type
   */
  export interface ISuccess<T = unknown> {
    /** Indicates validation success */
    success: true;
 
    /** The validated data of type T */
    data: T;
  }
 
  /**
   * Interface returned when type validation fails
   *
   * Returned when the input value does not conform to the expected type.
   * Contains comprehensive error information designed to be easily understood
   * by both humans and AI systems. Each error in the errors array provides
   * precise details about validation failures, including the exact path to the
   * problematic property, what type was expected, and what value was actually
   * provided.
   *
   * This detailed error structure is specifically optimized for AI function
   * calling validation feedback. When LLMs make type errors during function
   * calling, these granular error reports enable the AI to understand exactly
   * what went wrong and how to fix it, improving success rates in subsequent
   * attempts.
   *
   * Example error scenarios:
   *
   * - Type mismatch: expected "string" but got number 5
   * - Format violation: expected "string & Format<'uuid'>" but got
   *   "invalid-format"
   * - Missing properties: expected "required property 'name'" but got undefined
   * - Array type errors: expected "Array<string>" but got single string value
   *
   * The errors are used by ILlmFunction.validate() to provide structured
   * feedback to AI agents, enabling them to correct their parameter generation
   * and achieve improved function calling accuracy.
   */
  export interface IFailure {
    /** Indicates validation failure */
    success: false;
 
    /** The original input data that failed validation */
    data: unknown;
 
    /** Array of detailed validation errors */
    errors: IError[];
  }
 
  /**
   * Detailed information about a specific validation error
   *
   * Each error provides granular, actionable information about validation
   * failures, designed to be immediately useful for both human developers and
   * AI systems. The error structure follows a consistent format that enables
   * precise identification and correction of type mismatches.
   *
   * This error format is particularly valuable for AI function calling
   * scenarios, where LLMs need to understand exactly what went wrong to
   * generate correct parameters. The combination of path, expected type name,
   * actual value, and optional human-readable description provides the AI with
   * comprehensive context to make accurate corrections, which is why
   * ILlmFunction.validate() can achieve such high success rates in validation
   * feedback loops.
   *
   * The value field can contain any type of data, including `undefined` when
   * dealing with missing required properties or null/undefined validation
   * scenarios. This allows for precise error reporting in cases where the AI
   * agent omits required fields or provides null/undefined values
   * inappropriately.
   *
   * Real-world examples from AI function calling:
   *
   *     {
   *       path: "$input.member.age",
   *       expected: "number",
   *       value: "25"  // AI provided string instead of number
   *     }
   *
   *     {
   *       path: "$input.count",
   *       expected: "number & Type<'uint32'>",
   *       value: 20.75  // AI provided float instead of uint32
   *     }
   *
   *     {
   *       path: "$input.categories",
   *       expected: "Array<string>",
   *       value: "technology"  // AI provided string instead of array
   *     }
   *
   *     {
   *       path: "$input.id",
   *       expected: "string & Format<'uuid'>",
   *       value: "invalid-uuid-format"  // AI provided malformed UUID
   *     }
   *
   *     {
   *       path: "$input.user.name",
   *       expected: "string",
   *       value: undefined  // AI omitted required property
   *     }
   */
  export interface IError {
    /**
     * The path to the property that failed validation
     *
     * Dot-notation path using $input prefix indicating the exact location of
     * the validation failure within the input object structure. Examples
     * include "$input.member.age", "$input.categories[0]",
     * "$input.user.profile.email"
     */
    path: string;
 
    /**
     * The expected type name or type expression
     *
     * Technical type specification that describes what type was expected at
     * this path. This follows TypeScript-like syntax with embedded constraint
     * information, such as "string", "number & Type<'uint32'>",
     * "Array<string>", "string & Format<'uuid'> & MinLength<8>", etc.
     */
    expected: string;
 
    /**
     * The actual value that caused the validation failure
     *
     * This field contains the actual value that was provided but failed
     * validation. Note that this value can be `undefined` in cases where a
     * required property is missing or when validating against undefined
     * values.
     */
    value: unknown;
 
    /**
     * Optional human-readable description of the validation error
     *
     * This field is rarely populated in standard typia validation and is
     * primarily intended for specialized AI agent libraries or custom
     * validation scenarios that require additional context beyond the technical
     * type information. Most validation errors rely solely on the path,
     * expected, and value fields for comprehensive error reporting.
     */
    description?: string;
  }
}

undefined

typia/Primitive.ts


import { Equal } from "./typings/Equal";
import { IsTuple } from "./typings/IsTuple";
import { NativeClass } from "./typings/NativeClass";
import { ValueOf } from "./typings/ValueOf";
 
import { Format } from "./tags";
 
/**
 * Primitive type of JSON.
 *
 * `Primitive<T>` is a TMP (Type Meta Programming) type which converts its
 * argument as a primitive type within the framework JSON.
 *
 * If the target argument is a built-in class which returns its origin primitive
 * type through the `valueOf()` method like the `String` or `Number`, its return
 * type will be the `string` or `number`. Otherwise, if the built-in class does
 * not have the `valueOf()` method, the return type will be an empty object
 * (`{}`).
 *
 * Otherwise, if the target argument is a type of custom class, all of its
 * custom methods will be erased and its prototype will be changed to the
 * primitive `object`. Therefore, the return type of the TMP type will finally
 * be the primitive object.
 *
 * In addition, if the target argument is a type of custom class and it has a
 * special method `toJSON()`, the return type of this `Primitive` will be not
 * `Primitive<Instance>` but `Primitive<ReturnType<Instance.toJSON>>`.
 *
 * Before | After
 * ------------------------|---------------------------------------- `Boolean` |
 * `boolean` `Number` | `number` `String` | `string` `Class` | `object` `Class`
 * with `toJSON()` | `Primitive<ReturnType<Class.toJSON>>` Native Class | never
 * Others | No change
 *
 * @author Jeongho Nam - https://github.com/samchon
 * @author Kyungsu Kang - https://github.com/kakasoo
 * @author Michael - https://github.com/8471919
 * @template T Target argument type.
 */
export type Primitive<T> =
  Equal<T, PrimitiveMain<T>> extends true ? T : PrimitiveMain<T>;
 
type PrimitiveMain<Instance> = Instance extends [never]
  ? never // (special trick for jsonable | null) type
  : ValueOf<Instance> extends bigint
    ? never
    : ValueOf<Instance> extends boolean | number | string
      ? ValueOf<Instance>
      : Instance extends Function
        ? never
        : ValueOf<Instance> extends object
          ? Instance extends object
            ? Instance extends Date
              ? string & Format<"date-time">
              : Instance extends IJsonable<infer Raw>
                ? ValueOf<Raw> extends object
                  ? Raw extends object
                    ? PrimitiveObject<Raw> // object would be primitified
                    : never // cannot be
                  : ValueOf<Raw> // atomic value
                : Instance extends Exclude<NativeClass, Date>
                  ? never
                  : PrimitiveObject<Instance> // object would be primitified
            : never // cannot be
          : ValueOf<Instance>;
 
type PrimitiveObject<Instance extends object> =
  Instance extends Array<infer T>
    ? IsTuple<Instance> extends true
      ? PrimitiveTuple<Instance>
      : PrimitiveMain<T>[]
    : {
        [P in keyof Instance]: PrimitiveMain<Instance[P]>;
      };
 
type PrimitiveTuple<T extends readonly any[]> = T extends []
  ? []
  : T extends [infer F]
    ? [PrimitiveMain<F>]
    : T extends [infer F, ...infer Rest extends readonly any[]]
      ? [PrimitiveMain<F>, ...PrimitiveTuple<Rest>]
      : T extends [(infer F)?]
        ? [PrimitiveMain<F>?]
        : T extends [(infer F)?, ...infer Rest extends readonly any[]]
          ? [PrimitiveMain<F>?, ...PrimitiveTuple<Rest>]
          : [];
 
interface IJsonable<T> {
  toJSON(): T;
}

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.js";
import * as __typia_transform__isFormatEmail from "typia/lib/internal/_isFormatEmail.js";
import * as __typia_transform__isFormatUuid from "typia/lib/internal/_isFormatUuid.js";
import * as __typia_transform__isTypeUint32 from "typia/lib/internal/_isTypeUint32.js";
import * as __typia_transform__randomFormatEmail from "typia/lib/internal/_randomFormatEmail.js";
import * as __typia_transform__randomFormatUuid from "typia/lib/internal/_randomFormatUuid.js";
import * as __typia_transform__randomInteger from "typia/lib/internal/_randomInteger.js";
 
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


/**
 * Custom error class thrown when runtime assertion fails in `typia.assert<T>()`
 * function.
 *
 * This error is thrown by the `typia.assert<T>()` function when the input value
 * doesn't match the expected type.
 *
 * The error provides detailed information about the first assertion failure
 * encountered, including the access path where the error occurred, the expected
 * type, and the actual value.
 *
 * @author Jeongho Nam - https://github.com/samchon
 * @example
 *   ```typescript
 *   interface IMember {
 *     name: string;
 *     age: number & ExclusiveMinimum<19>;
 *   }
 *
 *   try {
 *     typia.assert<IMember>({ name: "John", age: 18 });
 *   } catch (error) {
 *     if (error instanceof TypeGuardError) {
 *       console.log(error.method);   // "typia.assert"
 *       console.log(error.path);     // "input.age"
 *       console.log(error.expected); // "number & ExclusiveMinimum<19>"
 *       console.log(error.value);    // 18
 *     }
 *   }
 *   ```;
 *
 * @template T - The expected type (generic for type safety)
 */
export class TypeGuardError<T = any> extends Error {
  /**
   * The name of the typia method that threw this error.
   *
   * @example
   *   typia.assert;
   */
  public readonly method: string;
 
  /**
   * The access path to the property where the assertion error occurred.
   *
   * Uses dot notation to indicate the path for nested object properties. May be
   * `undefined` if the error occurred at the root level.
   *
   * @example
   *   - `"input.age"` - Error in the age property of the object
   *   - `"input.profile.email"` - Error in the email property of a nested object
   *   - `"input[0].name"` - Error in the name property of the first array element
   *   - `undefined` - Error occurred at the root level
   */
  public readonly path: string | undefined;
 
  /**
   * String representation of the expected type at the error location.
   *
   * Represents TypeScript types as strings, including detailed type information
   * for complex types.
   *
   * @example
   *   - `"string"` - Expected string type
   *   - `"number & ExclusiveMinimum<19>"` - Expected number greater than 19
   *   - `"undefined"` - Expected undefined (when superfluous property found in assertion)
   *   - `"{ name: string; age: number }"` - Expected object type
   */
  public readonly expected: string;
 
  /**
   * The actual value that failed assertion.
   *
   * Stores the actual value at the error path as-is. Useful for debugging by
   * comparing the expected type with the actual value.
   *
   * @example
   *   - `18` - Numeric value
   *   - `"invalid"` - String value
   *   - `{ name: "John", age: 18, sex: 1 }` - Object value
   */
  public readonly value: unknown;
 
  /**
   * Optional human-readable description of the type guard error
   *
   * This field is rarely populated in standard typia type assertion and is
   * primarily intended for specialized AI agent libraries or custom validation
   * scenarios that require additional context beyond the technical type
   * information. Most assertion errors rely solely on the path, expected, and
   * value fields for comprehensive error reporting.
   */
  public readonly description?: string | undefined;
 
  /**
   * Phantom property for type safety purposes.
   *
   * This property is not actually used and exists only to maintain the generic
   * type T in TypeScript's type system. Always has an `undefined` value at
   * runtime.
   *
   * @internal
   */
  protected readonly fake_expected_typed_value_?: T | undefined;
 
  /**
   * Creates a new TypeGuardError instance.
   *
   * @example
   *   ```typescript
   *   const error = new TypeGuardError({
   *     method: "typia.assert",
   *     path: "input.age",
   *     expected: "number & ExclusiveMinimum<19>",
   *     value: 18
   *   });
   *   ```;
   *
   * @param props - Object containing the properties needed to create the error
   */
  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 {
  /**
   * Interface for properties passed to the TypeGuardError constructor.
   *
   * @example
   *   ```typescript
   *   const props: TypeGuardError.IProps = {
   *     method: "typia.assertEquals",
   *     path: "input.sex",
   *     expected: "undefined",
   *     value: 1,
   *     message: "Custom error message" // optional
   *   };
   *   ```;
   */
  export interface IProps {
    /**
     * The name of the typia method that threw the error.
     *
     * @example
     *   typia.assert, "typia.assertEquals";
     */
    method: string;
 
    /**
     * The access path to the property where the assertion error occurred
     * (optional).
     *
     * @example
     *   input.age, "input.profile.email";
     */
    path?: undefined | string;
 
    /**
     * String representation of the expected type at the error location.
     *
     * @example
     *   string, "number & ExclusiveMinimum<19>";
     */
    expected: string;
 
    /** The actual value that failed assertion. */
    value: unknown;
 
    /**
     * Optional human-readable description of the type guard error
     *
     * This field is rarely populated in standard typia type assertion and is
     * primarily intended for specialized AI agent libraries or custom
     * validation scenarios that require additional context beyond the technical
     * type information. Most assertion errors rely solely on the path,
     * expected, and value fields for comprehensive error reporting.
     */
    description?: string;
 
    /**
     * Custom error message (optional).
     *
     * If not provided, a default format message will be automatically
     * generated.
     */
    message?: undefined | string;
  }
}

undefined

@samchon/openapi


/**
 * Union type representing the result of type validation
 *
 * This is the return type of {@link typia.validate} functions, returning
 * {@link IValidation.ISuccess} on validation success and
 * {@link IValidation.IFailure} on validation failure. When validation fails, it
 * provides detailed, granular error information that precisely describes what
 * went wrong, where it went wrong, and what was expected.
 *
 * This comprehensive error reporting makes `IValidation` particularly valuable
 * for AI function calling scenarios, where Large Language Models (LLMs) need
 * specific feedback to correct their parameter generation. The detailed error
 * information is used by ILlmFunction.validate() to provide validation feedback
 * to AI agents, enabling iterative correction and improvement of function
 * calling accuracy.
 *
 * This type uses the Discriminated Union pattern, allowing type specification
 * through the success property:
 *
 * ```typescript
 * const result = typia.validate<string>(input);
 * if (result.success) {
 *   // IValidation.ISuccess<string> type
 *   console.log(result.data); // validated data accessible
 * } else {
 *   // IValidation.IFailure type
 *   console.log(result.errors); // detailed error information accessible
 * }
 * ```
 *
 * @author Jeongho Nam - https://github.com/samchon
 * @template T The type to validate
 */
export type IValidation<T = unknown> =
  | IValidation.ISuccess<T>
  | IValidation.IFailure;
 
export namespace IValidation {
  /**
   * Interface returned when type validation succeeds
   *
   * Returned when the input value perfectly conforms to the specified type T.
   * Since success is true, TypeScript's type guard allows safe access to the
   * validated data through the data property.
   *
   * @template T The validated type
   */
  export interface ISuccess<T = unknown> {
    /** Indicates validation success */
    success: true;
 
    /** The validated data of type T */
    data: T;
  }
 
  /**
   * Interface returned when type validation fails
   *
   * Returned when the input value does not conform to the expected type.
   * Contains comprehensive error information designed to be easily understood
   * by both humans and AI systems. Each error in the errors array provides
   * precise details about validation failures, including the exact path to the
   * problematic property, what type was expected, and what value was actually
   * provided.
   *
   * This detailed error structure is specifically optimized for AI function
   * calling validation feedback. When LLMs make type errors during function
   * calling, these granular error reports enable the AI to understand exactly
   * what went wrong and how to fix it, improving success rates in subsequent
   * attempts.
   *
   * Example error scenarios:
   *
   * - Type mismatch: expected "string" but got number 5
   * - Format violation: expected "string & Format<'uuid'>" but got
   *   "invalid-format"
   * - Missing properties: expected "required property 'name'" but got undefined
   * - Array type errors: expected "Array<string>" but got single string value
   *
   * The errors are used by ILlmFunction.validate() to provide structured
   * feedback to AI agents, enabling them to correct their parameter generation
   * and achieve improved function calling accuracy.
   */
  export interface IFailure {
    /** Indicates validation failure */
    success: false;
 
    /** The original input data that failed validation */
    data: unknown;
 
    /** Array of detailed validation errors */
    errors: IError[];
  }
 
  /**
   * Detailed information about a specific validation error
   *
   * Each error provides granular, actionable information about validation
   * failures, designed to be immediately useful for both human developers and
   * AI systems. The error structure follows a consistent format that enables
   * precise identification and correction of type mismatches.
   *
   * This error format is particularly valuable for AI function calling
   * scenarios, where LLMs need to understand exactly what went wrong to
   * generate correct parameters. The combination of path, expected type name,
   * actual value, and optional human-readable description provides the AI with
   * comprehensive context to make accurate corrections, which is why
   * ILlmFunction.validate() can achieve such high success rates in validation
   * feedback loops.
   *
   * The value field can contain any type of data, including `undefined` when
   * dealing with missing required properties or null/undefined validation
   * scenarios. This allows for precise error reporting in cases where the AI
   * agent omits required fields or provides null/undefined values
   * inappropriately.
   *
   * Real-world examples from AI function calling:
   *
   *     {
   *       path: "$input.member.age",
   *       expected: "number",
   *       value: "25"  // AI provided string instead of number
   *     }
   *
   *     {
   *       path: "$input.count",
   *       expected: "number & Type<'uint32'>",
   *       value: 20.75  // AI provided float instead of uint32
   *     }
   *
   *     {
   *       path: "$input.categories",
   *       expected: "Array<string>",
   *       value: "technology"  // AI provided string instead of array
   *     }
   *
   *     {
   *       path: "$input.id",
   *       expected: "string & Format<'uuid'>",
   *       value: "invalid-uuid-format"  // AI provided malformed UUID
   *     }
   *
   *     {
   *       path: "$input.user.name",
   *       expected: "string",
   *       value: undefined  // AI omitted required property
   *     }
   */
  export interface IError {
    /**
     * The path to the property that failed validation
     *
     * Dot-notation path using $input prefix indicating the exact location of
     * the validation failure within the input object structure. Examples
     * include "$input.member.age", "$input.categories[0]",
     * "$input.user.profile.email"
     */
    path: string;
 
    /**
     * The expected type name or type expression
     *
     * Technical type specification that describes what type was expected at
     * this path. This follows TypeScript-like syntax with embedded constraint
     * information, such as "string", "number & Type<'uint32'>",
     * "Array<string>", "string & Format<'uuid'> & MinLength<8>", etc.
     */
    expected: string;
 
    /**
     * The actual value that caused the validation failure
     *
     * This field contains the actual value that was provided but failed
     * validation. Note that this value can be `undefined` in cases where a
     * required property is missing or when validating against undefined
     * values.
     */
    value: unknown;
 
    /**
     * Optional human-readable description of the validation error
     *
     * This field is rarely populated in standard typia validation and is
     * primarily intended for specialized AI agent libraries or custom
     * validation scenarios that require additional context beyond the technical
     * type information. Most validation errors rely solely on the path,
     * expected, and value fields for comprehensive error reporting.
     */
    description?: string;
  }
}

undefined

typia/Primitive.ts


import { Equal } from "./typings/Equal";
import { IsTuple } from "./typings/IsTuple";
import { NativeClass } from "./typings/NativeClass";
import { ValueOf } from "./typings/ValueOf";
 
import { Format } from "./tags";
 
/**
 * Primitive type of JSON.
 *
 * `Primitive<T>` is a TMP (Type Meta Programming) type which converts its
 * argument as a primitive type within the framework JSON.
 *
 * If the target argument is a built-in class which returns its origin primitive
 * type through the `valueOf()` method like the `String` or `Number`, its return
 * type will be the `string` or `number`. Otherwise, if the built-in class does
 * not have the `valueOf()` method, the return type will be an empty object
 * (`{}`).
 *
 * Otherwise, if the target argument is a type of custom class, all of its
 * custom methods will be erased and its prototype will be changed to the
 * primitive `object`. Therefore, the return type of the TMP type will finally
 * be the primitive object.
 *
 * In addition, if the target argument is a type of custom class and it has a
 * special method `toJSON()`, the return type of this `Primitive` will be not
 * `Primitive<Instance>` but `Primitive<ReturnType<Instance.toJSON>>`.
 *
 * Before | After
 * ------------------------|---------------------------------------- `Boolean` |
 * `boolean` `Number` | `number` `String` | `string` `Class` | `object` `Class`
 * with `toJSON()` | `Primitive<ReturnType<Class.toJSON>>` Native Class | never
 * Others | No change
 *
 * @author Jeongho Nam - https://github.com/samchon
 * @author Kyungsu Kang - https://github.com/kakasoo
 * @author Michael - https://github.com/8471919
 * @template T Target argument type.
 */
export type Primitive<T> =
  Equal<T, PrimitiveMain<T>> extends true ? T : PrimitiveMain<T>;
 
type PrimitiveMain<Instance> = Instance extends [never]
  ? never // (special trick for jsonable | null) type
  : ValueOf<Instance> extends bigint
    ? never
    : ValueOf<Instance> extends boolean | number | string
      ? ValueOf<Instance>
      : Instance extends Function
        ? never
        : ValueOf<Instance> extends object
          ? Instance extends object
            ? Instance extends Date
              ? string & Format<"date-time">
              : Instance extends IJsonable<infer Raw>
                ? ValueOf<Raw> extends object
                  ? Raw extends object
                    ? PrimitiveObject<Raw> // object would be primitified
                    : never // cannot be
                  : ValueOf<Raw> // atomic value
                : Instance extends Exclude<NativeClass, Date>
                  ? never
                  : PrimitiveObject<Instance> // object would be primitified
            : never // cannot be
          : ValueOf<Instance>;
 
type PrimitiveObject<Instance extends object> =
  Instance extends Array<infer T>
    ? IsTuple<Instance> extends true
      ? PrimitiveTuple<Instance>
      : PrimitiveMain<T>[]
    : {
        [P in keyof Instance]: PrimitiveMain<Instance[P]>;
      };
 
type PrimitiveTuple<T extends readonly any[]> = T extends []
  ? []
  : T extends [infer F]
    ? [PrimitiveMain<F>]
    : T extends [infer F, ...infer Rest extends readonly any[]]
      ? [PrimitiveMain<F>, ...PrimitiveTuple<Rest>]
      : T extends [(infer F)?]
        ? [PrimitiveMain<F>?]
        : T extends [(infer F)?, ...infer Rest extends readonly any[]]
          ? [PrimitiveMain<F>?, ...PrimitiveTuple<Rest>]
          : [];
 
interface IJsonable<T> {
  toJSON(): T;
}

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