typia 8.0.3 → 8.1.0

package/lib/json.d.mts

@@ -0,0 +1,480 @@
+import { IJsonSchemaCollection } from "./schemas/json/IJsonSchemaCollection";
+import { IValidation } from "./IValidation";
+import { Primitive } from "./Primitive";
+import { TypeGuardError } from "./TypeGuardError";
+/**
+ * > You must configure the generic argument `Types`.
+ *
+ * JSON Schemas generator.
+ *
+ * Creates a JSON schema list which contains both main JSON schemas
+ * and components. Note that, all of the named types are stored in the
+ * {@link IJsonSchemaCollection.components} property for the `$ref` referencing.
+ *
+ * Also, you can specify the OpenAPI version by configuring the second generic
+ * argument `Version`. For reference, the default version is `"3.1"`, and key
+ * different of `"3.0"` and `"3.1"` is whether supporting the tuple type or not.
+ *
+ * @template Types Tuple of target types
+ * @template Version Version of OpenAPI specification. Default is 3.1
+ * @return JSON schema list
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function schemas(): never;
+/**
+ * JSON Schemas generator.
+ *
+ * Creates a JSON schema list which contains both main JSON schemas
+ * and components. Note that, all of the named types are stored in the
+ * {@link IJsonSchemaCollection.components} property for the `$ref` referencing.
+ *
+ * Also, you can specify the OpenAPI version by configuring the second generic
+ * argument `Version`. For reference, the default version is `"3.1"`, and key
+ * different of `"3.0"` and `"3.1"` is whether supporting the tuple type or not.
+ *
+ * @template Types Tuple of target types
+ * @template Version Version of OpenAPI specification. Default is 3.1
+ * @return JSON schema list
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function schemas<Types extends unknown[], Version extends "3.0" | "3.1" = "3.1">(): IJsonSchemaCollection<Version, Types>;
+/**
+ * > You must configure the generic argument `Types`.
+ *
+ * JSON Schemas generator.
+ *
+ * Creates a JSON schema list which contains both main JSON schemas
+ * and components. Note that, all of the named types are stored in the
+ * {@link IJsonSchemaCollection.components} property for the `$ref` referencing.
+ *
+ * Also, you can specify the OpenAPI version by configuring the second generic
+ * argument `Version`. For reference, the default version is `"3.1"`, and key
+ * different of `"3.0"` and `"3.1"` is whether supporting the tuple type or not.
+ *
+ * @template Types Tuple of target types
+ * @template Version Version of OpenAPI specification. Default is 3.1
+ * @return JSON schema list
+ *
+ * @deprecated Use {@link schemas} function instead please.
+ *             This function would be changed to return {@linkk ILlmApplication} like
+ *             structure in the future version (maybe next v8 major update).
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function application(): never;
+/**
+ * JSON Schemas generator.
+ *
+ * Creates a JSON schema list which contains both main JSON schemas
+ * and components. Note that, all of the named types are stored in the
+ * {@link IJsonSchemaCollection.components} property for the `$ref` referencing.
+ *
+ * Also, you can specify the OpenAPI version by configuring the second generic
+ * argument `Version`. For reference, the default version is `"3.1"`, and key
+ * different of `"3.0"` and `"3.1"` is whether supporting the tuple type or not.
+ *
+ * @template Types Tuple of target types
+ * @template Version Version of OpenAPI specification. Default is 3.1
+ * @return JSON schema list
+ *
+ * @deprecated Use {@link schemas} function instead please.
+ *             This function would be changed to return {@linkk ILlmApplication} like
+ *             structure in the future version (maybe next v8 major update).
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function application<Types extends unknown[], Version extends "3.0" | "3.1" = "3.1">(): IJsonSchemaCollection<Version, Types>;
+/**
+ * Safe `JSON.parse()` function with type assertion.
+ *
+ * `typia.json.assertParse()` is a combination function of `JSON.parse()` and
+ * {@link assert}. Therefore, it converts a JSON (JavaScript Object Notation) string
+ * to a `T` typed instance with type assertion.
+ *
+ * In such reason, when parsed JSON string value is not matched with the type `T`,
+ * it throws {@link TypeGuardError} or custom error generated by *errorFactory*.
+ * Otherwise, there's no problem on the parsed value, the parsed value would be
+ * returned.
+ *
+ * @template T Expected type of parsed value
+ * @param input JSON string
+ * @param errorFactory Custom error factory. Default is `TypeGuardError`
+ * @returns Parsed value
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function assertParse<T>(input: string, errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error)): Primitive<T>;
+/**
+ * > You must configure the generic argument `T`.
+ *
+ * Safe `JSON.parse()` function with type checking.
+ *
+ * `typia.json.isParse()` is a combination function of `JSON.parse()` and {@link is}.
+ * Therefore, it converts a JSON (JavaScript Object Notation) string to a `T` typed
+ * instance with type checking.
+ *
+ * In such reason, when parsed JSON string value is not matched with the type `T`, it
+ * returns `null` value. Otherwise, there's no problem on the parsed value, the parsed
+ * value would be returned.
+ *
+ * @template T Expected type of parsed value
+ * @param input JSON string
+ * @returns Parsed value when exact type, otherwise `null`
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function isParse(input: string): never;
+/**
+ * Safe `JSON.parse()` function with type checking.
+ *
+ * `typia.json.isParse()` is a combination function of `JSON.parse()` and {@link is}.
+ * Therefore, it converts a JSON (JavaScript Object Notation) string to a `T` typed
+ * instance with type checking.
+ *
+ * In such reason, when parsed JSON string value is not matched with the type `T`, it
+ * returns `null` value. Otherwise, there's no problem on the parsed value, the parsed
+ * value would be returned.
+ *
+ * @template T Expected type of parsed value
+ * @param input JSON string
+ * @returns Parsed value when exact type, otherwise `null`
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function isParse<T>(input: string): Primitive<T> | null;
+/**
+ * > You must configure the generic argument `T`.
+ *
+ * Safe `JSON.parse()` function with detailed type validation.
+ *
+ * `typia.json.validateParse()` is a combination function of `JSON.parse()` and
+ * {@link validate}. Therefore, it converts a JSON (JavaScript Object Notation) string
+ * to a `T` typed instance with detailed type validation.
+ *
+ * In such reason, when parsed JSON string value is not matched with the type `T`, it
+ * returns {@link IValidation.IFailure} value with detailed error reasons. Otherwise,
+ * there's no problem on the parsed value, the parsed value would be stored in `data`
+ * property of the output {@link IValidation.ISuccess} instance.
+ *
+ * @template T Expected type of parsed value
+ * @param input JSON string
+ * @returns Validation result with JSON parsed value
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function validateParse(input: string): never;
+/**
+ * Safe `JSON.parse()` function with detailed type validation.
+ *
+ * `typia.json.validateParse()` is a combination function of `JSON.parse()` and
+ * {@link validate}. Therefore, it converts a JSON (JavaScript Object Notation) string
+ * to a `T` typed instance with detailed type validation.
+ *
+ * In such reason, when parsed JSON string value is not matched with the type `T`, it
+ * returns {@link IValidation.IFailure} value with detailed error reasons. Otherwise,
+ * there's no problem on the parsed value, the parsed value would be stored in `data`
+ * property of the output {@link IValidation.ISuccess} instance.
+ *
+ * @template T Expected type of parsed value
+ * @param input JSON string
+ * @returns Validation result with JSON parsed value
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function validateParse<T>(input: string): IValidation<Primitive<T>>;
+/**
+ * 8x faster `JSON.stringify()` function.
+ *
+ * Converts an input value to a JSON (JavaScript Object Notation) string, about 8x
+ * faster than the native `JSON.stringify()` function. The 5x faster principle is
+ * because it writes an optimized JSON conversion plan, only for the type `T`.
+ *
+ * For reference, this `typia.json.stringify()` does not validate the input value type.
+ * It just believes that the input value is following the type `T`. Therefore, if you
+ * can't ensure the input value type, it would be better to call one of below
+ * functions instead.
+ *
+ *  - {@link assertStringify}
+ *  - {@link isStringify}
+ *  - {@link validateStringify}
+ *
+ * @template T Type of the input value
+ * @param input A value to be converted
+ * @return JSON string value
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function stringify<T>(input: T): string;
+/**
+ * 5x faster `JSON.stringify()` function with type assertion.
+ *
+ * `typia.json.assertStringify()` is a combination function of {@link assert} and
+ * {@link stringify}. Therefore, it converts an input value to
+ * JSON (JavaScript Object Notation) string, with type assertion.
+ *
+ * In such reason, when `input` value is not matched with the type `T`, it throws an
+ * {@link TypeGuardError} or custom error generated by *errorFactory*. Otherwise,
+ * there's no problem on the `input` value, JSON string would be returned.
+ *
+ * For reference, with type assertion, it is even 5x times faster than the native
+ * `JSON.stringify()` function. So, just enjoy the safe and fast JSON conversion
+ * with confidence.
+ *
+ * @template T Type of the input value
+ * @param input A value to be asserted and converted
+ * @param errorFactory Custom error factory. Default is `TypeGuardError`
+ * @return JSON string value
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function assertStringify<T>(input: T, errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error)): string;
+/**
+ * 5x faster `JSON.stringify()` function with type assertion.
+ *
+ * `typia.json.assertStringify()` is a combination function of {@link assert} and
+ * {@link stringify}. Therefore, it converts an input value to
+ * JSON (JavaScript Object Notation) string, with type assertion.
+ *
+ * In such reason, when `input` value is not matched with the type `T`, it throws an
+ * {@link TypeGuardError} or custom error generated by *errorFactory*. Otherwise,
+ * there's no problem on the `input` value, JSON string would be returned.
+ *
+ * For reference, with type assertion, it is even 5x times faster than the native
+ * `JSON.stringify()` function. So, just enjoy the safe and fast JSON conversion
+ * with confidence.
+ *
+ * @template T Type of the input value
+ * @param input A value to be asserted and converted
+ * @param errorFactory Custom error factory. Default is `TypeGuardError`
+ * @return JSON string value
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function assertStringify<T>(input: T, errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error)): unknown;
+/**
+ * 7x faster `JSON.stringify()` function with type checking.
+ *
+ * `typia.json.stringify()` is a combination function of {@link is} and
+ * {@link stringify}. Therefore, it converts an input value to JSON
+ * (JavaScript Object Notation) string, with type checking.
+ *
+ * In such reason, when `input` value is not matched with the type `T`, it returns
+ * `null` value. Otherwise, there's no problem on the `input` value, JSON string
+ * would be returned.
+ *
+ * For reference, with type checking, it is even 7x times faster than the native
+ * `JSON.stringify()` function. So, just enjoy the safe and fast JSON conversion
+ * with confidence.
+ *
+ * @template T Type of the input value
+ * @param input A value to be checked and converted
+ * @return JSON string value when exact type, otherwise null
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function isStringify<T>(input: T): string | null;
+/**
+ * 7x faster `JSON.stringify()` function with type checking.
+ *
+ * `typia.json.isStringify()` is a combination function of {@link is} and
+ * {@link stringify}. Therefore, it converts an input value to JSON
+ * (JavaScript Object Notation) string, with type checking.
+ *
+ * In such reason, when `input` value is not matched with the type `T`, it returns
+ * `null` value. Otherwise, there's no problem on the `input` value, JSON string
+ * would be returned.
+ *
+ * For reference, with type checking, it is even 7x times faster than the native
+ * `JSON.stringify()` function. So, just enjoy the safe and fast JSON conversion
+ * with confidence.
+ *
+ * @template T Type of the input value
+ * @param input A value to be checked and converted
+ * @return JSON string value when exact type, otherwise null
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function isStringify<T>(input: unknown): string | null;
+/**
+ * 5x faster `JSON.stringify()` function with detailed type validation.
+ *
+ * `typia.json.validateStringify()` is a combination function of {@link validate} and
+ * {@link stringify}. Therefore, it converts an input value to JSON (JavaScript Object
+ * Notation) string, with detailed type validation.
+ *
+ * In such reason, when `input` value is not matched with the type `T`, it returns
+ * {@link IValidation.IFailure} value with detailed error reasons. Otherwise,
+ * there's no problem on the `input` value, JSON string would be stored in `data`
+ * property of the output {@link IValidation.ISuccess} instance.
+ *
+ * For reference, with detailed type validation, it is even 5x times faster than the
+ * native `JSON.stringify()` function. So, just enjoy the safe and fast JSON
+ * conversion with confidence.
+ *
+ * @template T Type of the input value
+ * @param input A value to be checked and converted
+ * @returns Validation result with JSON string value
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function validateStringify<T>(input: T): IValidation<string>;
+/**
+ * 5x faster `JSON.stringify()` function with detailed type validation.
+ *
+ * `typia.json.validateStringify()` is a combination function of {@link validate} and
+ * {@link stringify}. Therefore, it converts an input value to JSON (JavaScript Object
+ * Notation) string, with detailed type validation.
+ *
+ * In such reason, when `input` value is not matched with the type `T`, it returns
+ * {@link IValidation.IFailure} value with detailed error reasons. Otherwise,
+ * there's no problem on the `input` value, JSON string would be stored in `data`
+ * property of the output {@link IValidation.ISuccess} instance.
+ *
+ * For reference, with detailed type validation, it is even 5x times faster than the
+ * native `JSON.stringify()` function. So, just enjoy the safe and fast JSON
+ * conversion with confidence.
+ *
+ * @template T Type of the input value
+ * @param input A value to be checked and converted
+ * @returns Validation result with JSON string value
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function validateStringify<T>(input: unknown): IValidation<string>;
+/**
+ * Creates a reusable {@link isParse} function.
+ *
+ * @danger You must configure the generic argument `T`
+ * @returns Nothing until you configure the generic argument `T`
+ * @throws compile error
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function createIsParse(): never;
+/**
+ * Creates a reusable {@link isParse} function.
+ *
+ * @template T Expected type of parsed value
+ * @returns A reusable `isParse` function
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function createIsParse<T>(): (input: string) => Primitive<T> | null;
+/**
+ * Creates a reusable {@link assertParse} function.
+ *
+ * @danger You must configure the generic argument `T`
+ * @returns Nothing until you configure the generic argument `T`
+ * @param errorFactory Custom error factory. Default is `TypeGuardError`
+ * @throws compile error
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function createAssertParse(errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error)): never;
+/**
+ * Creates a reusable {@link assertParse} function.
+ *
+ * @template T Expected type of parsed value
+ * @param errorFactory Custom error factory. Default is `TypeGuardError`
+ * @returns A reusable `assertParse` function
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function createAssertParse<T>(errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error)): (input: string) => Primitive<T>;
+/**
+ * Creates a reusable {@link validateParse} function.
+ *
+ * @danger You must configure the generic argument `T`
+ * @returns Nothing until you configure the generic argument `T`
+ * @throws compile error
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function createValidateParse(): never;
+/**
+ * Creates a reusable {@link validateParse} function.
+ *
+ * @template T Expected type of parsed value
+ * @returns A reusable `validateParse` function
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function createValidateParse<T>(): (input: string) => IValidation<Primitive<T>>;
+/**
+ * Creates a reusable {@link stringify} function.
+ *
+ * @danger You must configure the generic argument `T`
+ * @returns Nothing until you configure the generic argument `T`
+ * @throws compile error
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function createStringify(): never;
+/**
+ * Creates a reusable {@link stringify} function.
+ *
+ * @template T Type of the input value
+ * @returns A reusable `stringify` function
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function createStringify<T>(): (input: T) => string;
+/**
+ * Creates a reusable {@link assertStringify} function.
+ *
+ * @danger You must configure the generic argument `T`
+ * @param errorFactory Custom error factory. Default is `TypeGuardError`
+ * @returns Nothing until you configure the generic argument `T`
+ * @throws compile error
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function createAssertStringify(errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error)): never;
+/**
+ * Creates a reusable {@link assertStringify} function.
+ *
+ * @template T Type of the input value
+ * @param errorFactory Custom error factory. Default is `TypeGuardError`
+ * @returns A reusable `assertStringify` function
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function createAssertStringify<T>(errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error)): (input: unknown) => string;
+/**
+ * Creates a reusable {@link isStringify} function.
+ *
+ * @danger You must configure the generic argument `T`
+ * @returns Nothing until you configure the generic argument `T`
+ * @throws compile error
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function createIsStringify(): never;
+/**
+ * Creates a reusable {@link isStringify} function.
+ *
+ * @template T Type of the input value
+ * @returns A reusable `isStringify` function
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function createIsStringify<T>(): (input: unknown) => string | null;
+/**
+ * Creates a reusable {@link validateStringify} function.
+ *
+ * @danger You must configure the generic argument `T`
+ * @returns Nothing until you configure the generic argument `T`
+ * @throws compile error
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function createValidateStringify(): never;
+/**
+ * Creates a reusable {@link validateStringify} function.
+ *
+ * @template T Type of the input value
+ * @returns A reusable `validateStringify` function
+
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function createValidateStringify<T>(): (input: unknown) => IValidation<string>;