typia 6.0.0-dev.20240122 → 6.0.0

package/src/misc.ts

@@ -7,10 +7,13 @@
 ==============================================================
     LITERALS
 ----------------------------------------------------------- */
+import * as Namespace from "./functional/Namespace";
+
 import { Atomic } from "./typings/Atomic";
 
 import { IValidation } from "./IValidation";
 import { Resolved } from "./Resolved";
+import { TypeGuardError } from "./TypeGuardError";
 
 /**
  * > You must configure the generic argument `T`.
@@ -74,14 +77,19 @@ export function literals(): never {
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function clone<T>(input: T): Resolved<T>;
+function clone<T>(input: T): Resolved<T>;
 
 /**
  * @internal
  */
-export function clone(): never {
+function clone(): never {
   halt("clone");
 }
+const clonePure = /** @__PURE__ */ Object.assign<typeof clone, {}>(
+  clone,
+  /** @__PURE__ */ Namespace.misc.clone("clone"),
+);
+export { clonePure as clone };
 
 /**
  * Clone a data with type assertion.
@@ -91,16 +99,20 @@ export function clone(): never {
  * methods would not be cloned.
  *
  * 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, cloned
- * data would be returned.
+ * {@link TypeGuardError} or custom error generated by *errorFactory*. Otherwise,
+ * there's no problem on the `input` value, cloned data would be returned.
  *
  * @template T Type of the input value
  * @param input A value to be cloned
+ * @param errorFactory Custom error factory. Default is `TypeGuardError`
  * @return Cloned data
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function assertClone<T>(input: T): Resolved<T>;
+function assertClone<T>(
+  input: T,
+  errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error),
+): Resolved<T>;
 
 /**
  * Clone a data with type assertion.
@@ -110,23 +122,37 @@ export function assertClone<T>(input: T): Resolved<T>;
  * methods would not be cloned.
  *
  * 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, cloned
- * data would be returned.
+ * {@link TypeGuardError} or custom error generated by *errorFactory*. Otherwise,
+ * there's no problem on the `input` value, cloned data would be returned.
  *
  * @template T Type of the input value
  * @param input A value to be cloned
+ * @param errorFactory Custom error factory. Default is `TypeGuardError`
  * @return Cloned data
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function assertClone<T>(input: unknown): Resolved<T>;
+function assertClone<T>(
+  input: unknown,
+  errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error),
+): Resolved<T>;
 
 /**
  * @internal
  */
-export function assertClone(): never {
+function assertClone(): never {
   halt("assertClone");
 }
+const assertClonePure = /** @__PURE__ */ Object.assign<
+  typeof assertClone,
+  {},
+  {}
+>(
+  assertClone,
+  /** @__PURE__ */ Namespace.assert("misc.assertClone"),
+  /** @__PURE__ */ Namespace.misc.clone("assertClone"),
+);
+export { assertClonePure as assertClone };
 
 /**
  * Clone a data with type checking.
@@ -145,7 +171,7 @@ export function assertClone(): never {
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function isClone<T>(input: T): Resolved<T> | null;
+function isClone<T>(input: T): Resolved<T> | null;
 
 /**
  * Clone a data with type checking.
@@ -164,14 +190,20 @@ export function isClone<T>(input: T): Resolved<T> | null;
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function isClone<T>(input: unknown): Resolved<T> | null;
+function isClone<T>(input: unknown): Resolved<T> | null;
 
 /**
  * @internal
  */
-export function isClone(): never {
+function isClone(): never {
   halt("isClone");
 }
+const isClonePure = /** @__PURE__ */ Object.assign<typeof isClone, {}, {}>(
+  isClone,
+  /** @__PURE__ */ Namespace.is(),
+  /** @__PURE__ */ Namespace.misc.clone("isClone"),
+);
+export { isClonePure as isClone };
 
 /**
  * Clone a data with detailed type validation.
@@ -189,7 +221,7 @@ export function isClone(): never {
  * @param input A value to be cloned
  * @returns Validation result with cloned value
  */
-export function validateClone<T>(input: T): IValidation<Resolved<T>>;
+function validateClone<T>(input: T): IValidation<Resolved<T>>;
 
 /**
  * Clone a data with detailed type validation.
@@ -207,14 +239,24 @@ export function validateClone<T>(input: T): IValidation<Resolved<T>>;
  * @param input A value to be cloned
  * @returns Validation result with cloned value
  */
-export function validateClone<T>(input: unknown): IValidation<Resolved<T>>;
+function validateClone<T>(input: unknown): IValidation<Resolved<T>>;
 
 /**
  * @internal
  */
-export function validateClone(): never {
+function validateClone(): never {
   halt("validateClone");
 }
+const validateClonePure = /** @__PURE__ */ Object.assign<
+  typeof validateClone,
+  {},
+  {}
+>(
+  validateClone,
+  /** @__PURE__ */ Namespace.validate(),
+  /** @__PURE__ */ Namespace.misc.clone("validateClone"),
+);
+export { validateClonePure as validateClone };
 
 /* -----------------------------------------------------------
     PRUNE
@@ -240,14 +282,19 @@ export function validateClone(): never {
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function prune<T extends object>(input: T): void;
+function prune<T extends object>(input: T): void;
 
 /**
  * @internal
  */
-export function prune(): never {
+function prune(): never {
   halt("prune");
 }
+const prunePure = /** @__PURE__ */ Object.assign<typeof prune, {}>(
+  prune,
+  /** @__PURE__ */ Namespace.misc.prune("prune"),
+);
+export { prunePure as prune };
 
 /**
  * Prune, erase superfluous properties, with type assertion.
@@ -257,15 +304,20 @@ export function prune(): never {
  * object including nested objects, 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, its
- * every superfluous properties would be removed, including nested objects.
+ * {@link TypeGuardError} or custom error generated by *errorFactory*. Otherwise,
+ * there's no problem on the `input` value, its every superfluous properties would be
+ * removed, including nested objects.
  *
  * @template T Type of the input value
  * @param input Target instance to assert and prune
+ * @param errorFactory Custom error factory. Default is `TypeGuardError`
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function assertPrune<T>(input: T): T;
+function assertPrune<T>(
+  input: T,
+  errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error),
+): T;
 
 /**
  * Prune, erase superfluous properties, with type assertion.
@@ -275,22 +327,37 @@ export function assertPrune<T>(input: T): T;
  * object including nested objects, 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, its
- * every superfluous properties would be removed, including nested objects.
+ * {@link TypeGuardError} or custom error generated by *errorFactory*. Otherwise, there's
+ * no problem on the `input` value, its every superfluous properties would be removed,
+ * including nested objects.
  *
  * @template T Type of the input value
  * @param input Target instance to assert and prune
+ * @param errorFactory Custom error factory. Default is `TypeGuardError`
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function assertPrune<T>(input: unknown): T;
+function assertPrune<T>(
+  input: unknown,
+  errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error),
+): T;
 
 /**
  * @internal
  */
-export function assertPrune(): unknown {
+function assertPrune(): unknown {
   halt("assertPrune");
 }
+const assertPrunePure = /** @__PURE__ */ Object.assign<
+  typeof assertPrune,
+  {},
+  {}
+>(
+  assertPrune,
+  /** @__PURE__ */ Namespace.assert("misc.assertPrune"),
+  /** @__PURE__ */ Namespace.misc.prune("assertPrune"),
+);
+export { assertPrunePure as assertPrune };
 
 /**
  * Prune, erase superfluous properties, with type checking.
@@ -309,7 +376,7 @@ export function assertPrune(): unknown {
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function isPrune<T>(input: T): input is T;
+function isPrune<T>(input: T): input is T;
 
 /**
  * Prune, erase superfluous properties, with type checking.
@@ -328,14 +395,20 @@ export function isPrune<T>(input: T): input is T;
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function isPrune<T>(input: unknown): input is T;
+function isPrune<T>(input: unknown): input is T;
 
 /**
  * @internal
  */
-export function isPrune(): never {
+function isPrune(): never {
   halt("isPrune");
 }
+const isPrunePure = /** @__PURE__ */ Object.assign<typeof isPrune, {}, {}>(
+  isPrune,
+  /** @__PURE__ */ Namespace.is(),
+  /** @__PURE__ */ Namespace.misc.prune("isPrune"),
+);
+export { isPrunePure as isPrune };
 
 /**
  * Prune, erase superfluous properties, with type validation.
@@ -355,7 +428,7 @@ export function isPrune(): never {
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function validatePrune<T>(input: T): IValidation<T>;
+function validatePrune<T>(input: T): IValidation<T>;
 
 /**
  * Prune, erase superfluous properties, with type validation.
@@ -375,15 +448,26 @@ export function validatePrune<T>(input: T): IValidation<T>;
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function validatePrune<T>(input: unknown): IValidation<T>;
+function validatePrune<T>(input: unknown): IValidation<T>;
 
 /**
  * @internal
  */
-export function validatePrune<T>(): IValidation<T> {
+function validatePrune<T>(): IValidation<T> {
   halt("validatePrune");
 }
 
+const validatePrunePure = /** @__PURE__ */ Object.assign<
+  typeof validatePrune,
+  {},
+  {}
+>(
+  validatePrune,
+  /** @__PURE__ */ Namespace.misc.prune("validatePrune"),
+  /** @__PURE__ */ Namespace.validate(),
+);
+export { validatePrunePure as validatePrune };
+
 /* -----------------------------------------------------------
     FACTORY FUNCTIONS
 ----------------------------------------------------------- */
@@ -396,7 +480,7 @@ export function validatePrune<T>(): IValidation<T> {
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function createClone(): never;
+function createClone(): never;
 
 /**
  * Creates a resuable {@link clone} function.
@@ -406,42 +490,58 @@ export function createClone(): never;
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function createClone<T>(): (input: T) => Resolved<T>;
+function createClone<T>(): (input: T) => Resolved<T>;
 
 /**
  * @internal
  */
-export function createClone(): never {
+function createClone(): never {
   halt("createClone");
 }
+const createClonePure = /** @__PURE__ */ Object.assign<typeof createClone, {}>(
+  createClone,
+  clonePure,
+);
+export { createClonePure as createClone };
 
 /**
  * Creates a reusable {@link assertClone} 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 createAssertClone(): never;
+function createAssertClone(
+  errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error),
+): never;
 
 /**
  * Creates a resuable {@link assertClone} function.
  *
  * @template T Type of the input value
+ * @param errorFactory Custom error factory. Default is `TypeGuardError`
  * @returns A reusable `clone` function
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function createAssertClone<T>(): (input: unknown) => Resolved<T>;
+function createAssertClone<T>(
+  errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error),
+): (input: unknown) => Resolved<T>;
 
 /**
  * @internal
  */
-export function createAssertClone(): never {
+function createAssertClone(): never {
   halt("createAssertClone");
 }
+const createAssertClonePure = /** @__PURE__ */ Object.assign<
+  typeof createAssertClone,
+  {}
+>(createAssertClone, assertClonePure);
+export { createAssertClonePure as createAssertClone };
 
 /**
  * Creates a reusable {@link isClone} function.
@@ -452,7 +552,7 @@ export function createAssertClone(): never {
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function createIsClone(): never;
+function createIsClone(): never;
 
 /**
  * Creates a resuable {@link isClone} function.
@@ -462,14 +562,19 @@ export function createIsClone(): never;
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function createIsClone<T>(): (input: unknown) => Resolved<T> | null;
+function createIsClone<T>(): (input: unknown) => Resolved<T> | null;
 
 /**
  * @internal
  */
-export function createIsClone(): never {
+function createIsClone(): never {
   halt("createIsClone");
 }
+const createIsClonePure = /** @__PURE__ */ Object.assign<
+  typeof createIsClone,
+  {}
+>(createIsClone, isClonePure);
+export { createIsClonePure as createIsClone };
 
 /**
  * Creates a reusable {@link validateClone} function.
@@ -480,7 +585,7 @@ export function createIsClone(): never {
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function createValidateClone(): never;
+function createValidateClone(): never;
 
 /**
  * Creates a resuable {@link validateClone} function.
@@ -490,16 +595,19 @@ export function createValidateClone(): never;
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function createValidateClone<T>(): (
-  input: unknown,
-) => IValidation<Resolved<T>>;
+function createValidateClone<T>(): (input: unknown) => IValidation<Resolved<T>>;
 
 /**
  * @internal
  */
-export function createValidateClone(): never {
+function createValidateClone(): never {
   halt("createValidateClone");
 }
+const createValidateClonePure = /** @__PURE__ */ Object.assign<
+  typeof createValidateClone,
+  {}
+>(createValidateClone, validateClonePure);
+export { createValidateClonePure as createValidateClone };
 
 /**
  * Creates a reusable {@link prune} function.
@@ -510,7 +618,7 @@ export function createValidateClone(): never {
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function createPrune(): never;
+function createPrune(): never;
 
 /**
  * Creates a resuable {@link prune} function.
@@ -520,42 +628,58 @@ export function createPrune(): never;
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function createPrune<T extends object>(): (input: T) => void;
+function createPrune<T extends object>(): (input: T) => void;
 
 /**
  * @internal
  */
-export function createPrune<T extends object>(): (input: T) => void {
+function createPrune<T extends object>(): (input: T) => void {
   halt("createPrune");
 }
+const createPrunePure = /** @__PURE__ */ Object.assign<typeof createPrune, {}>(
+  createPrune,
+  prunePure,
+);
+export { createPrunePure as createPrune };
 
 /**
  * Creates a reusable {@link assertPrune} 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 createAssertPrune(): never;
+function createAssertPrune(
+  errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error),
+): never;
 
 /**
  * Creates a resuable {@link assertPrune} function.
  *
  * @template T Type of the input value
+ * @param errorFactory Custom error factory. Default is `TypeGuardError`
  * @returns A reusable `isPrune` function
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function createAssertPrune<T extends object>(): (input: T) => T;
+function createAssertPrune<T extends object>(
+  errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error),
+): (input: T) => T;
 
 /**
  * @internal
  */
-export function createAssertPrune<T extends object>(): (input: T) => T {
+function createAssertPrune<T extends object>(): (input: T) => T {
   halt("createAssertPrune");
 }
+const createAssertPrunePure = /** @__PURE__ */ Object.assign<
+  typeof createAssertPrune,
+  {}
+>(createAssertPrune, assertPrunePure);
+export { createAssertPrunePure as createAssertPrune };
 
 /**
  * Creates a reusable {@link isPrune} function.
@@ -566,7 +690,7 @@ export function createAssertPrune<T extends object>(): (input: T) => T {
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function createIsPrune(): never;
+function createIsPrune(): never;
 
 /**
  * Creates a resuable {@link isPrune} function.
@@ -576,14 +700,19 @@ export function createIsPrune(): never;
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function createIsPrune<T extends object>(): (input: T) => input is T;
+function createIsPrune<T extends object>(): (input: T) => input is T;
 
 /**
  * @internal
  */
-export function createIsPrune<T extends object>(): (input: T) => input is T {
+function createIsPrune<T extends object>(): (input: T) => input is T {
   halt("createIsPrune");
 }
+const createIsPrunePure = /** @__PURE__ */ Object.assign<
+  typeof createIsPrune,
+  {}
+>(createIsPrune, isPrunePure);
+export { createIsPrunePure as createIsPrune };
 
 /**
  * Creates a reusable {@link validatePrune} function.
@@ -594,7 +723,7 @@ export function createIsPrune<T extends object>(): (input: T) => input is T {
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function createValidatePrune(): never;
+function createValidatePrune(): never;
 
 /**
  * Creates a resuable {@link validatePrune} function.
@@ -604,18 +733,19 @@ export function createValidatePrune(): never;
  *
  * @author Jeongho Nam - https://github.com/samchon
  */
-export function createValidatePrune<T extends object>(): (
-  input: T,
-) => IValidation<T>;
+function createValidatePrune<T extends object>(): (input: T) => IValidation<T>;
 
 /**
  * @internal
  */
-export function createValidatePrune<T extends object>(): (
-  input: T,
-) => IValidation<T> {
+function createValidatePrune<T extends object>(): (input: T) => IValidation<T> {
   halt("createValidatePrune");
 }
+const createValidatePrunePure = /** @__PURE__ */ Object.assign<
+  typeof createValidatePrune,
+  {}
+>(createValidatePrune, validatePrunePure);
+export { createValidatePrunePure as createValidatePrune };
 
 /**
  * @internal