typia 6.0.0-dev.20240122 → 6.0.0

package/src/json.ts

@@ -1,7 +1,10 @@
+import * as Namespace from "./functional/Namespace";
+
 import { IJsonApplication } from "./schemas/json/IJsonApplication";
 
 import { IValidation } from "./IValidation";
 import { Primitive } from "./Primitive";
+import { TypeGuardError } from "./TypeGuardError";
 
 /* ===========================================================
     JSON
@@ -21,16 +24,9 @@ import { Primitive } from "./Primitive";
  * components. Note that, all of the named types are stored in the
  * {@link IJsonApplication.components} property for the `$ref` referencing.
  *
- * Also, `typia.json.application()` has two additional generic arguments.
- *
- * The 1st *Purpose* means the purpose determines the JSON schema definition spec.
- * For an example, `ajv` has an extra property "$recursiveRef"  that are not
- * exists in the standard JSON schema definition spec. Otherwise, `swagger`
- * can't identify the tuple definition.
- *
- * The next *Surplus* means whether to allow surplus properties starting with
- * `x-typia-` or not. If `true`, the surplus properties like `x-typia-jsDocTags`
- * would be registered into the JSON schema, otherwise, not.
+ * 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 Purpose Purpose of the JSON schema
@@ -48,29 +44,20 @@ export function application(): never;
  * components. Note that, all of the named types are stored in the
  * {@link IJsonApplication.components} property for the `$ref` referencing.
  *
- * Also, `typia.json.application()` has two additional generic arguments.
- *
- * The 1st *Purpose* means the purpose determines the JSON schema definition spec.
- * For an example, `ajv` has an extra property "$recursiveRef"  that are not
- * exists in the standard JSON schema definition spec. Otherwise, `swagger`
- * can't identify the tuple definition.
- *
- * The next *Surplus* means whether to allow surplus properties starting with
- * `x-typia-` or not. If `true`, the surplus properties like `x-typia-jsDocTags`
- * would be registered into the JSON schema, otherwise, not.
+ * 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 Purpose Purpose of the JSON schema
- * @template Surplus Allow surplus properties starting with `x-typia-` or not
+ * @template Version Version of OpenAPI specification. Default is 3.1
  * @return JSON schema application
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
 export function application<
   Types extends unknown[],
-  Purpose extends "ajv" | "swagger" = "swagger",
-  Surplus extends boolean = false,
->(): IJsonApplication;
+  Version extends "3.0" | "3.1" = "3.1",
+>(): IJsonApplication<Version>;
 
 /**
  * @internal
@@ -92,16 +79,20 @@ export function application(): never {
  * 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}. Otherwise, there's no problem on the parsed value,
- * the parsed value would be returned.
+ * 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 function assertParse(input: string): never;
+function assertParse(
+  input: string,
+  errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error),
+): never;
 
 /**
  * Safe `JSON.parse()` function with type assertion.
@@ -111,23 +102,33 @@ export function assertParse(input: string): never;
  * 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}. Otherwise, there's no problem on the parsed
- * value, the parsed value would be returned.
+ * 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 function assertParse<T>(input: string): Primitive<T>;
+function assertParse<T>(
+  input: string,
+  errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error),
+): Primitive<T>;
 
 /**
  * @internal
  */
-export function assertParse<T>(): Primitive<T> {
+function assertParse<T>(): Primitive<T> {
   halt("assertParse");
 }
+const assertParsePure = /** @__PURE__ */ Object.assign<typeof assertParse, {}>(
+  assertParse,
+  /** @__PURE__ */ Namespace.assert("json.assertParse"),
+);
+export { assertParsePure as assertParse };
 
 /**
  * > You must configure the generic argument `T`.
@@ -148,7 +149,7 @@ export function assertParse<T>(): Primitive<T> {
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function isParse(input: string): never;
+function isParse(input: string): never;
 
 /**
  * Safe `JSON.parse()` function with type checking.
@@ -167,14 +168,19 @@ export function isParse(input: string): never;
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function isParse<T>(input: string): Primitive<T> | null;
+function isParse<T>(input: string): Primitive<T> | null;
 
 /**
  * @internal
  */
-export function isParse<T>(): Primitive<T> | null {
+function isParse<T>(): Primitive<T> | null {
   halt("isParse");
 }
+const isParsePure = /** @__PURE__ */ Object.assign<typeof isParse, {}>(
+  isParse,
+  /** @__PURE__ */ Namespace.is(),
+);
+export { isParsePure as isParse };
 
 /**
  * > You must configure the generic argument `T`.
@@ -196,7 +202,7 @@ export function isParse<T>(): Primitive<T> | null {
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function validateParse(input: string): never;
+function validateParse(input: string): never;
 
 /**
  * Safe `JSON.parse()` function with detailed type validation.
@@ -216,14 +222,19 @@ export function validateParse(input: string): never;
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function validateParse<T>(input: string): IValidation<Primitive<T>>;
+function validateParse<T>(input: string): IValidation<Primitive<T>>;
 
 /**
  * @internal
  */
-export function validateParse<T>(): IValidation<Primitive<T>> {
+function validateParse<T>(): IValidation<Primitive<T>> {
   halt("validateParse");
 }
+const validateParsePure = /** @__PURE__ */ Object.assign<
+  typeof validateParse,
+  {}
+>(validateParse, /** @__PURE__ */ Namespace.validate());
+export { validateParsePure as validateParse };
 
 /* -----------------------------------------------------------
     STRINGIFY
@@ -250,14 +261,19 @@ export function validateParse<T>(): IValidation<Primitive<T>> {
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function stringify<T>(input: T): string;
+function stringify<T>(input: T): string;
 
 /**
  * @internal
  */
-export function stringify(): never {
+function stringify(): never {
   halt("stringify");
 }
+const stringifyPure = /** @__PURE__ */ Object.assign<typeof stringify, {}>(
+  stringify,
+  /** @__PURE__ */ Namespace.json.stringify("stringify"),
+);
+export { stringifyPure as stringify };
 
 /**
  * 5x faster `JSON.stringify()` function with type assertion.
@@ -267,8 +283,8 @@ export function stringify(): never {
  * 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}. Otherwise, there's no problem on the `input` value, JSON
- * string would be returned.
+ * {@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
@@ -276,11 +292,15 @@ export function stringify(): never {
  *
  * @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 function assertStringify<T>(input: T): string;
+function assertStringify<T>(
+  input: T,
+  errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error),
+): string;
 
 /**
  * 5x faster `JSON.stringify()` function with type assertion.
@@ -290,8 +310,8 @@ export function assertStringify<T>(input: T): string;
  * 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}. Otherwise, there's no problem on the `input` value, JSON
- * string would be returned.
+ * {@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
@@ -299,18 +319,32 @@ export function assertStringify<T>(input: T): string;
  *
  * @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 function assertStringify<T>(input: T): unknown;
+function assertStringify<T>(
+  input: T,
+  errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error),
+): unknown;
 
 /**
  * @internal
  */
-export function assertStringify(): string {
+function assertStringify(): string {
   halt("assertStringify");
 }
+const assertStringifyPure = /** @__PURE__ */ Object.assign<
+  typeof assertStringify,
+  {},
+  {}
+>(
+  assertStringify,
+  /** @__PURE__ */ Namespace.assert("json.assertStringify"),
+  /** @__PURE__ */ Namespace.json.stringify("assertStringify"),
+);
+export { assertStringifyPure as assertStringify };
 
 /**
  * 7x faster `JSON.stringify()` function with type checking.
@@ -333,7 +367,7 @@ export function assertStringify(): string {
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function isStringify<T>(input: T): string | null;
+function isStringify<T>(input: T): string | null;
 
 /**
  * 7x faster `JSON.stringify()` function with type checking.
@@ -356,15 +390,26 @@ export function isStringify<T>(input: T): string | null;
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function isStringify<T>(input: unknown): string | null;
+function isStringify<T>(input: unknown): string | null;
 
 /**
  * @internal
  */
-export function isStringify(): string | null {
+function isStringify(): string | null {
   halt("isStringify");
 }
 
+const isStringifyPure = /** @__PURE__ */ Object.assign<
+  typeof isStringify,
+  {},
+  {}
+>(
+  isStringify,
+  /** @__PURE__ */ Namespace.is(),
+  /** @__PURE__ */ Namespace.json.stringify("isStringify"),
+);
+export { isStringifyPure as isStringify };
+
 /**
  * 5x faster `JSON.stringify()` function with detailed type validation.
  *
@@ -387,7 +432,7 @@ export function isStringify(): string | null {
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function validateStringify<T>(input: T): IValidation<string>;
+function validateStringify<T>(input: T): IValidation<string>;
 
 /**
  * 5x faster `JSON.stringify()` function with detailed type validation.
@@ -411,14 +456,24 @@ export function validateStringify<T>(input: T): IValidation<string>;
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function validateStringify<T>(input: unknown): IValidation<string>;
+function validateStringify<T>(input: unknown): IValidation<string>;
 
 /**
  * @internal
  */
-export function validateStringify(): IValidation<string> {
+function validateStringify(): IValidation<string> {
   halt("validateStringify");
 }
+const validateStringifyPure = /** @__PURE__ */ Object.assign<
+  typeof validateStringify,
+  {},
+  {}
+>(
+  validateStringify,
+  /** @__PURE__ */ Namespace.validate(),
+  /** @__PURE__ */ Namespace.json.stringify("validateStringify"),
+);
+export { validateStringifyPure as validateStringify };
 
 /* -----------------------------------------------------------
     FACTORY FUNCTIONS
@@ -432,7 +487,7 @@ export function validateStringify(): IValidation<string> {
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function createIsParse(): never;
+function createIsParse(): never;
 
 /**
  * Creates a reusable {@link isParse} function.
@@ -442,42 +497,58 @@ export function createIsParse(): never;
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function createIsParse<T>(): (input: string) => Primitive<T> | null;
+function createIsParse<T>(): (input: string) => Primitive<T> | null;
 
 /**
  * @internal
  */
-export function createIsParse<T>(): (input: string) => Primitive<T> | null {
+function createIsParse<T>(): (input: string) => Primitive<T> | null {
   halt("createIsParse");
 }
+const createIsParsePure = /** @__PURE__ */ Object.assign<
+  typeof createIsParse,
+  {}
+>(createIsParse, isParsePure);
+export { createIsParsePure as createIsParse };
 
 /**
  * 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 function createAssertParse(): never;
+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 function createAssertParse<T>(): (input: string) => Primitive<T>;
+function createAssertParse<T>(
+  errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error),
+): (input: string) => Primitive<T>;
 
 /**
  * @internal
  */
-export function createAssertParse<T>(): (input: string) => Primitive<T> {
+function createAssertParse<T>(): (input: string) => Primitive<T> {
   halt("createAssertParse");
 }
+const createAssertParsePure = /** @__PURE__ */ Object.assign<
+  typeof createAssertParse,
+  {}
+>(createAssertParse, assertParsePure);
+export { createAssertParsePure as createAssertParse };
 
 /**
  * Creates a reusable {@link validateParse} function.
@@ -488,7 +559,7 @@ export function createAssertParse<T>(): (input: string) => Primitive<T> {
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function createValidateParse(): never;
+function createValidateParse(): never;
 
 /**
  * Creates a reusable {@link validateParse} function.
@@ -498,19 +569,23 @@ export function createValidateParse(): never;
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function createValidateParse<T>(): (
-  input: string,
-) => IValidation<Primitive<T>>;
+function createValidateParse<T>(): (input: string) => IValidation<Primitive<T>>;
 
 /**
  * @internal
  */
-export function createValidateParse<T>(): (
+function createValidateParse<T>(): (
   input: string,
 ) => IValidation<Primitive<T>> {
   halt("createValidateParse");
 }
 
+const createValidateParsePure = /** @__PURE__ */ Object.assign<
+  typeof createValidateParse,
+  {}
+>(createValidateParse, validateParsePure);
+export { createValidateParsePure as createValidateParse };
+
 /**
  * Creates a reusable {@link stringify} function.
  *
@@ -520,7 +595,7 @@ export function createValidateParse<T>(): (
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function createStringify(): never;
+function createStringify(): never;
 
 /**
  * Creates a reusable {@link stringify} function.
@@ -530,43 +605,61 @@ export function createStringify(): never;
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function createStringify<T>(): (input: T) => string;
+function createStringify<T>(): (input: T) => string;
 
 /**
  * @internal
  */
-export function createStringify<T>(): (input: T) => string {
+function createStringify<T>(): (input: T) => string {
   halt("createStringify");
 }
 
+const createStringifyPure = /** @__PURE__ */ Object.assign<
+  typeof createStringify,
+  {}
+>(createStringify, stringifyPure);
+export { createStringifyPure as createStringify };
+
 /**
  * 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 function createAssertStringify(): never;
+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 function createAssertStringify<T>(): (input: unknown) => string;
+function createAssertStringify<T>(
+  errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error),
+): (input: unknown) => string;
 
 /**
  * @internal
  */
-export function createAssertStringify(): (input: unknown) => string {
+function createAssertStringify(): (input: unknown) => string {
   halt("createAssertStringify");
 }
 
+const createAssertStringifyPure = /** @__PURE__ */ Object.assign<
+  typeof createAssertStringify,
+  {}
+>(createAssertStringify, assertStringifyPure);
+export { createAssertStringifyPure as createAssertStringify };
+
 /**
  * Creates a reusable {@link isStringify} function.
  *
@@ -576,7 +669,7 @@ export function createAssertStringify(): (input: unknown) => string {
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function createIsStringify(): never;
+function createIsStringify(): never;
 
 /**
  * Creates a reusable {@link isStringify} function.
@@ -586,15 +679,21 @@ export function createIsStringify(): never;
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function createIsStringify<T>(): (input: unknown) => string | null;
+function createIsStringify<T>(): (input: unknown) => string | null;
 
 /**
  * @internal
  */
-export function createIsStringify(): (input: unknown) => string | null {
+function createIsStringify(): (input: unknown) => string | null {
   halt("createIsStringify");
 }
 
+const createIsStringifyPure = /** @__PURE__ */ Object.assign<
+  typeof createIsStringify,
+  {}
+>(createIsStringify, isStringifyPure);
+export { createIsStringifyPure as createIsStringify };
+
 /**
  * Creates a reusable {@link validateStringify} function.
  *
@@ -604,7 +703,7 @@ export function createIsStringify(): (input: unknown) => string | null {
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function createValidateStringify(): never;
+function createValidateStringify(): never;
 
 /**
  * Creates a reusable {@link validateStringify} function.
@@ -614,19 +713,21 @@ export function createValidateStringify(): never;
 
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function createValidateStringify<T>(): (
-  input: unknown,
-) => IValidation<string>;
+function createValidateStringify<T>(): (input: unknown) => IValidation<string>;
 
 /**
  * @internal
  */
-export function createValidateStringify(): (
-  input: unknown,
-) => IValidation<string> {
+function createValidateStringify(): (input: unknown) => IValidation<string> {
   halt("createValidateStringify");
 }
 
+const createValidateStringifyPure = /** @__PURE__ */ Object.assign<
+  typeof createValidateStringify,
+  {}
+>(createValidateStringify, validateStringifyPure);
+export { createValidateStringifyPure as createValidateStringify };
+
 /**
  * @internal
  */