📖 Guide Documents
Miscellaneous

misc module

clone() functions

export namespace misc {
    export function clone<T>(input: T): T;
    export function assertClone<T>(input: T | unknown): Resolved<T>;
    export function isClone<T>(input: T | unknown): Resolved<T> | null;
    export function validateClone<T>(input: T | unknown): IValidation<Resolved<T>>;
 
    export function createClone<T>(): (input: T) => Resolved<T>;
    export function createAssertClone<T>(): (input: T | unknown) => Resolved<T>;
    export function createIsClone<T>(): (input: T | unknown) => Resolved<T> | null;
    export function createValidateClone<T>(): (
        input: T | unknown
    ) => IValidation<Resolved<T>>;
}

Deep copy functions.

When you want to copy an instance, just call typia.misc.clone() function. It would perform deep copy including nested objects, so you can get a new instance with same values. Also, if you want type safe deep copy function, you can use typia.misc.isClone(), typia.misc.assertClone() or typia.misc.validateClone() functions instead.

examples/src/assertClone.ts
import typia from "typia";
 
const department: IDepartment = typia.misc.random<IDepartment>();
const cloned: IDepartment = typia.misc.assertClone(department);
 
console.log(cloned);
 
interface IDepartment {
    /**
     * @format uuid
     */
    id: string;
 
    /**
     * @minLength 3
     */
    name: string;
 
    /**
     * @type int
     */
    limit: number;
 
    clerks: IClerk[];
}
interface IClerk {
    name: string;
 
    /**
     * @exclusiveMinimum 19
     * @maximum 100
     */
    age: number;
 
    authority: number;
 
    /**
     * @format date
     */
    joined_at: string;
}

prune() functions

export function prune<T>(input: T): void;
export function assertPrune<T>(input: T | unknown): T;
export function isPrune<T>(input: T | unknown): T | null;
export function validatePrune<T>(input: T | unknown): IValidation<T>;
 
export function createPrune<T>(): (input: T) => void;
export function createAssertPrune<T>(): (input: T | unknown) => T;
export function createIsPrune<T>(): (input: T | unknown) => T | null;
export function createValidatePrune<T>(): (input: T | unknown) => IValidation<T>;

Deep prune functions.

When you want to remove every extra properties that are not defined in the type including nested objects, you can use typia.misc.prune<T>() function. Also, if you want to perform type safe pruning, you can use typia.misc.isPrune<T>(), typia.misc.assertPrune<T>() or typia.misc.validatePrune<T>() functions instead.

examples/src/assertPrune.ts
import typia from "typia";
 
const department: IDepartment = typia.misc.random<IDepartment>();
const pruned: IDepartment = typia.misc.assertPrune(department);
console.log(pruned);
 
interface IDepartment {
    /**
     * @format uuid
     */
    id: string;
 
    /**
     * @minLength 3
     */
    name: string;
 
    /**
     * @type int
     */
    limit: number;
 
    clerks: IClerk[];
}
interface IClerk {
    name: string;
 
    /**
     * @exclusiveMinimum 19
     * @maximum 100
     */
    age: number;
 
    authority: number;
 
    /**
     * @format date
     */
    joined_at: string;
}

literals() function

export namespace misc {
    export function literals<
        T extends boolean | number | string | bigint | null
    >(): T[];
}

Union literal type to array.

When you call typia.misc.literals<T>() function with union literal type, it returns an array of literal values listed in the generic T argument. This typia.misc.literals<T> function is useful when you are developing test program, especially handling some discriminated union types.

examples/src/literals.ts
import typia from "typia";
 
typia.misc.literals<"A" | "B" | "C" | 1 | 2n>();

notations module

camel() functions

export namespace notations {
    export function camel<T>(input: T): CamelCase<T>;
    export function assertCamel<T>(input: T | unknown): CamelCase<T>;
    export function isCamel<T>(input: T | unknown): CamelCase<T> | null;
    export function validateCamel<T>(input: T | unknown): IValidation<CamelCase<T>>;
 
    export function createCamel<T>(): (input: T) => CamelCase<T>;
    export function createAssertCamel<T>(): (input: T | unknown) => CamelCase<T>;
    export function createIsCamel<T>(): (input: T | unknown) => CamelCase<T> | null;
    export function createValidateCamel<T>(): (
        input: T | unknown
    ) => IValidation<CamelCase<T>>;
}

Camel case converters.

Convert every property names of nested objects to be camel case notation.

When you need type safe functions, you can utilize below them.

examples/src/camel.ts
import typia from "typia";
 
interface IPerson {
    is_my_name_samchon?: boolean;
    HelloTheNewWorld: string;
    ToHTML: string;
}
typia.notations.createCamel<IPerson>();

pascal() functions

export namespace notations {
    export function pascal<T>(input: T): PascalCase<T>;
    export function assertPascal<T>(input: T | unknown): PascalCase<T>;
    export function isPascal<T>(input: T | unknown): PascalCase<T> | null;
    export function validatePascal<T>(input: T | unknown): IValidation<PascalCase<T>>;
 
    export function createPascal<T>(): (input: T) => PascalCase<T>;
    export function createAssertPascal<T>(): (input: T | unknown) => PascalCase<T>;
    export function createIsPascal<T>(): (input: T | unknown) => PascalCase<T> | null;
    export function createValidatePascal<T>(): (
        input: T | unknown
    ) => IValidation<PascalCase<T>>;
}

Pascal case converters.

Convert every property names of nested objects to be pascal case notation.

When you need type safe functions, you can utilize below them.

examples/src/pascal.ts
import typia from "typia";
 
interface IPerson {
    is_my_name_samchon?: boolean;
    helloTheNewWorld: string;
    toHTML: string;
}
typia.notations.createPascal<IPerson>();

snake() functions

export namespace notations {
    export function snake<T>(input: T): SnakeCase<T>;
    export function assertSnake<T>(input: T | unknown): SnakeCase<T>;
    export function isSnake<T>(input: T | unknown): SnakeCase<T> | null;
    export function validateSnake<T>(input: T | unknown): IValidation<SnakeCase<T>>;
 
    export function createSnake<T>(): (input: T) => SnakeCase<T>;
    export function createAssertSnake<T>(): (input: T | unknown) => SnakeCase<T>;
    export function createIsSnake<T>(): (input: T | unknown) => SnakeCase<T> | null;
    export function createValidateSnake<T>(): (
        input: T | unknown
    ) => IValidation<SnakeCase<T>>;
}

Snake case converters.

Convert every property names of nested objects to be snake case notation.

When you need type safe functions, you can utilize below them.

examples/src/snake.ts
import typia from "typia";
 
interface IPerson {
    isMyNameSamchon?: boolean;
    HelloTheNewWorld: string;
    ToHTML: string;
}
typia.notations.createSnake<IPerson>();

http module


query() functions

export namespace http {
    export function query<T extends object>(input: Query): Resolved<T>;
    export function assertQuery<T extends object>(input: Query): Resolved<T>;
    export function isQuery<T extends object>(input: Query): Resolved<T> | null;
    export function validateQuery<T extends object>(
        input: Query
    ): IValidation<Resolved<T>>;
 
    export function createQuery<T extends object>(): (input: Query) => Resolved<T>;
    export function createAssertQuery<T extends object>(): (
        input: Query
    ) => Resolved<T>;
    export function createIsQuery<T extends object>(): (
        input: Query
    ) => Resolved<T> | null;
    export function createValidateQuery<T extends object>(): (
        input: Query
    ) => IValidation<Resolved<T>>;
}
type Query = string | URLSearchParams;

URL query decoder functions.

typia.http.query<T>() is a function decoding a query string or an URLSearchParams instance, with automatic type casting to the expected type. When property type be defined as boolean or number type, typia.http.query<T>() will cast the value to the expected type when decoding.

By the way, as URL query is not enough to express complex data structures, typia.http.query<T>() function has some limitations. If target type T is not following those restrictions, compilation errors would be occured.

  1. Type T must be an object type
  2. Do not allow dynamic property
  3. Only boolean, bigint, number, string or their array types are allowed
  4. By the way, union type never be not allowed

Also, typia.http.query<T>() function does not perform validation about the decoded value. Therefore, if you can't sure that input data is following the T type, it would better to call one of below functions intead.

examples/src/query.ts
import typia from "typia";
 
interface IQuery {
    limit?: number;
    enforce: boolean;
    values?: string[];
    atomic: string | null;
    indexes: number[];
}
typia.http.createQuery<IQuery>();

headers() functions

export namespace http {
    export function headers<T extends object>(input: Headers): Resolved<T>;
    export function assertHeaders<T extends object>(input: Headers): Resolved<T>;
    export function isHeaders<T extends object>(input: Headers): Resolved<T> | null;
    export function validateHeaders<T extends object>(
        input: Headers
    ): IValidation<Resolved<T>>;
 
    export function createHeaders<T extends object>(): (
        input: Headers
    ) => Resolved<T>;
    export function createAssertHeaders<T extends object>(): (
        input: Headers
    ) => Resolved<T>;
    export function createIsHeaders<T extends object>(): (
        input: Headers
    ) => Resolved<T> | null;
    export function createValidateHeaders<T extends object>(): (
        input: Headers
    ) => IValidation<Resolved<T>>;
}
type Headers = Record<string, string | string[] | undefined>;

Headers decoder (for express and fastify).

typia.http.headers<t>() is a function decoding an header instance, with automatic type casting to the expected type. When property type be defined as boolean or number type, typia.http.headers<t>() will cast the value to the expected type.

By the way, as HTTP headers are not enough to express complex data structures, typia.http.headers<t>() function has some limitations. If target type T is not following those restrictions, compilation errors would be occured.

  1. Type T must be an object type
  2. Do not allow dynamic property
  3. Property key must be lower case
  4. Property value cannot be null, but undefined is possible
  5. Only boolean, bigint, number, string or their array types are allowed
  6. By the way, union type never be not allowed
  7. Property set-cookie must be array type
  8. Those properties cannot be array type
  • age
  • authorization
  • content-length
  • content-type
  • etag
  • expires
  • from
  • host
  • if-modified-since
  • if-unmodified-since
  • last-modified
  • location
  • max-forwards
  • proxy-authorization
  • referer
  • retry-after
  • server
  • user-agent

Also, typia.http.headers<t>() function does not perform validation about the decoded value. Therefore, if you can't sure that input data is following the T type, it would better to call one of below functions intead.

examples/src/headers.ts
import typia from "typia";
 
interface IHeaders {
    "x-Category": "x" | "y" | "z";
    "x-MEMO"?: string;
    "x-nAmE"?: string;
    "x-ValUes": number[];
    "x-FlAgS": boolean[];
    "X-Descriptions": string[];
}
typia.http.createHeaders<IHeaders>();

parameter() functions

export namespace http {
    export function parameter<T extends Atomic.Type | null>(input: string): T;
    export function createParameter<T extends Atomic.Type | null>(): (
        input: string
    ) => T;
}

URL path parameter decoder.

typia.http.parameter<T>() is a function decoding a path parameter, with automatic type casting to the expected type. When type T has beeen defined as boolean or number type, typia.http.parameter<T>() will cast the value to the expected type.

Also, typia.http.parameter<T>() performs type assertion to the decoded value by combining with assert function. Therefore, when the decoded value is not following the T type, TypeGuardError would be thrown.

examples/src/parameter.ts
import typia, { tags } from "typia";
 
typia.http.createParameter<string & tags.Format<"uuid">>();
typia.http.createParameter<number & tags.Type<"uint32">>();