typia 5.2.7-dev.20231109 → 5.3.0-dev.20231117

package/src/module.ts

@@ -1,7 +1,6 @@
 import { Namespace } from "./functional/Namespace";
 
-import { IMetadataApplication } from "./schemas/metadata/IMetadataApplication";
-
+import { AssertionGuard } from "./AssertionGuard";
 import { IRandomGenerator } from "./IRandomGenerator";
 import { IValidation } from "./IValidation";
 import { Resolved } from "./Resolved";
@@ -11,11 +10,13 @@ export * as json from "./json";
 export * as misc from "./misc";
 export * as notations from "./notations";
 export * as protobuf from "./protobuf";
+export * as reflect from "./reflect";
 export * as tags from "./tags";
 
 export * from "./schemas/json/IJsonApplication";
 export * from "./schemas/json/IJsonComponents";
 export * from "./schemas/json/IJsonSchema";
+export * from "./AssertionGuard";
 export * from "./IRandomGenerator";
 export * from "./IValidation";
 export * from "./TypeGuardError";
@@ -39,6 +40,8 @@ export * from "./SnakeCase";
  * If what you want is not asserting but just knowing whether the parametric value is
  * following the type `T` or not, you can choose the {@link is} function instead.
  * Otherwise you want to know all the errors, {@link validate} is the way to go.
+ * Also, if you want to automatically cast the parametric value to the type `T`
+ * when no problem (perform the assertion guard of type).
  *
  * On the other and, if you don't want to allow any superfluous property that is not
  * enrolled to the type `T`, you can use {@link assertEquals} function instead.
@@ -83,6 +86,66 @@ export function assert(): never {
 }
 Object.assign(assert, Namespace.assert("assert"));
 
+/**
+ * Assertion guard of a value type.
+ *
+ * Asserts a parametric value type and throws a {@link TypeGuardError} with detailed
+ * reason, if the parametric value is not following the type `T`. Otherwise, the
+ * value is following the type `T`, nothing would be returned, but the input value
+ * would be automatically casted to the type `T`. This is the concept of
+ * "assertion guard" of a value type.
+ *
+ * If what you want is not asserting but just knowing whether the parametric value is
+ * following the type `T` or not, you can choose the {@link is} function instead.
+ * Otherwise you want to know all the errors, {@link validate} is the way to go.
+ * Also, if you want to returns the parametric value when no problem, you can use
+ * {@link assert} function instead.
+ *
+ * On the other and, if you don't want to allow any superfluous property that is not
+ * enrolled to the type `T`, you can use {@link assertGuardEquals} function instead.
+ *
+ * @template T Type of the input value
+ * @param input A value to be asserted
+ * @throws A {@link TypeGuardError} instance with detailed reason
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export function assertGuard<T>(input: T): asserts input is T;
+
+/**
+ * Assertion guard of a value type.
+ *
+ * Asserts a parametric value type and throws a {@link TypeGuardError} with detailed
+ * reason, if the parametric value is not following the type `T`. Otherwise, the
+ * value is following the type `T`, nothing would be returned, but the input value
+ * would be automatically casted to the type `T`. This is the concept of
+ * "assertion guard" of a value type.
+ *
+ * If what you want is not asserting but just knowing whether the parametric value is
+ * following the type `T` or not, you can choose the {@link is} function instead.
+ * Otherwise you want to know all the errors, {@link validate} is the way to go.
+ * Also, if you want to returns the parametric value when no problem, you can use
+ * {@link assert} function instead.
+ *
+ * On the other and, if you don't want to allow any superfluous property that is not
+ * enrolled to the type `T`, you can use {@link assertGuardEquals} function instead.
+ *
+ * @template T Type of the input value
+ * @param input A value to be asserted
+ * @throws A {@link TypeGuardError} instance with detailed reason
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export function assertGuard<T>(input: unknown): asserts input is T;
+
+/**
+ * @internal
+ */
+export function assertGuard(): never {
+    halt("assertGuard");
+}
+Object.assign(assertGuard, Namespace.assert("assertGuard"));
+
 /**
  * Tests a value type.
  *
@@ -258,6 +321,72 @@ export function assertEquals(): never {
 }
 Object.assign(assertEquals, Namespace.assert("assertEquals"));
 
+/**
+ * Assertion guard of a type with equality.
+ *
+ * Asserts a parametric value type and throws a {@link TypeGuardError} with detailed
+ * reason, if the parametric value is not following the type `T` or some superfluous
+ * property that is not listed on the type `T` has been found.
+ *
+ * Otherwise, the value is following the type `T` without any superfluous property,
+ * nothing would be returned, but the input value would be automatically casted to
+ * the type `T`. This is the concept of "assertion guard" of a value type.
+ *
+ * If what you want is not asserting but just knowing whether the parametric value is
+ * following the type `T` or not, you can choose the {@link equals} function instead.
+ * Otherwise, you want to know all the errors, {@link validateEquals} is the way to go.
+ * Also, if you want to returns the parametric value when no problem, you can use
+ * {@link assert} function instead.
+ *
+ * On the other hand, if you want to allow superfluous property that is not enrolled
+ * to the type `T`, you can use {@link assertEquals} function instead.
+ *
+ * @template T Type of the input value
+ * @param input A value to be asserted
+ * @returns Parametric input value casted as `T`
+ * @throws A {@link TypeGuardError} instance with detailed reason
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export function assertGuardEquals<T>(input: T): asserts input is T;
+
+/**
+ * Assertion guard of a type with equality.
+ *
+ * Asserts a parametric value type and throws a {@link TypeGuardError} with detailed
+ * reason, if the parametric value is not following the type `T` or some superfluous
+ * property that is not listed on the type `T` has been found.
+ *
+ * Otherwise, the value is following the type `T` without any superfluous property,
+ * nothing would be returned, but the input value would be automatically casted to
+ * the type `T`. This is the concept of "assertion guard" of a value type.
+ *
+ * If what you want is not asserting but just knowing whether the parametric value is
+ * following the type `T` or not, you can choose the {@link equals} function instead.
+ * Otherwise, you want to know all the errors, {@link validateEquals} is the way to go.
+ * Also, if you want to returns the parametric value when no problem, you can use
+ * {@link assertEquals} function instead.
+ *
+ * On the other hand, if you want to allow superfluous property that is not enrolled
+ * to the type `T`, you can use {@link assertGuard} function instead.
+ *
+ * @template T Type of the input value
+ * @param input A value to be asserted
+ * @returns Parametric input value casted as `T`
+ * @throws A {@link TypeGuardError} instance with detailed reason
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export function assertGuardEquals<T>(input: unknown): asserts input is T;
+
+/**
+ * @internal
+ */
+export function assertGuardEquals(): never {
+    halt("assertGuardEquals");
+}
+Object.assign(assertGuardEquals, Namespace.assert("assertGuardEquals"));
+
 /**
  * Tests equality between a value and its type.
  *
@@ -425,23 +554,6 @@ export function random(): never {
 }
 Object.assign(random, Namespace.random());
 
-/**
- * @internal
- */
-export function metadata(): never;
-
-/**
- * @internal
- */
-export function metadata<Types extends unknown[]>(): IMetadataApplication;
-
-/**
- * @internal
- */
-export function metadata(): never {
-    halt("metadata");
-}
-
 /* -----------------------------------------------------------
     FACTORY FUNCTIONS
 ----------------------------------------------------------- */
@@ -474,6 +586,65 @@ export function createAssert<T>(): (input: unknown) => T {
 }
 Object.assign(createAssert, assert);
 
+/**
+ * Creates a reusable {@link assertGuard} function.
+ *
+ * Note that, you've to declare the variable type of the factory function caller
+ * like below. If you don't declare the variable type, compilation error be thrown.
+ * This is the special rule of the TypeScript compiler.
+ *
+ * ```typescript
+ * // MUST DECLARE THE VARIABLE TYPE
+ * const func: typia.AssertionGuard<number> = typia.createAssertGuard<number>();
+ *
+ * // IF NOT, COMPILATION ERROR BE OCCURED
+ * const func = typia.createAssertGuard<number>();
+ * ```
+ *
+ * > *Assertions require every name in the call target to be declared with an*
+ * > *explicit type annotation.*
+ *
+ * @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 function createAssertGuard(): never;
+
+/**
+ * Creates a reusable {@link assertGuard} function.
+ *
+ * Note that, you've to declare the variable type of the factory function caller
+ * like below. If you don't declare the variable type, compilation error be thrown.
+ * This is the special rule of the TypeScript compiler.
+ *
+ * ```typescript
+ * // MUST DECLARE THE VARIABLE TYPE
+ * const func: typia.AssertionGuard<number> = typia.createAssertGuard<number>();
+ *
+ * // IF NOT, COMPILATION ERROR BE OCCURED
+ * const func = typia.createAssertGuard<number>();
+ * ```
+ *
+ * > *Assertions require every name in the call target to be declared with an*
+ * > *explicit type annotation.*
+ *
+ * @returns Nothing until you configure the generic argument `T`
+ * @throws compile error
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export function createAssertGuard<T>(): (input: unknown) => AssertionGuard<T>;
+
+/**
+ * @internal
+ */
+export function createAssertGuard<T>(): (input: unknown) => AssertionGuard<T> {
+    halt("createAssertGuard");
+}
+Object.assign(createAssertGuard, assertGuard);
+
 /**
  * Creates a reusable {@link is} function.
  *
@@ -561,6 +732,69 @@ export function createAssertEquals<T>(): (input: unknown) => T {
 }
 Object.assign(createAssertEquals, assertEquals);
 
+/**
+ * Creates a reusable {@link assertGuardEquals} function.
+ *
+ * Note that, you've to declare the variable type of the factory function caller
+ * like below. If you don't declare the variable type, compilation error be thrown.
+ * This is the special rule of the TypeScript compiler.
+ *
+ * ```typescript
+ * // MUST DECLARE THE VARIABLE TYPE
+ * const func: typia.AssertionGuard<number> = typia.createAssertGuardEquals<number>();
+ *
+ * // IF NOT, COMPILATION ERROR BE OCCURED
+ * const func = typia.createAssertGuardEquals<number>();
+ * ```
+ *
+ * > *Assertions require every name in the call target to be declared with an*
+ * > *explicit type annotation.*
+ *
+ * @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 function createAssertGuardEquals(): never;
+
+/**
+ * Creates a reusable {@link assertGuardEquals} function.
+ *
+ * Note that, you've to declare the variable type of the factory function caller
+ * like below. If you don't declare the variable type, compilation error be thrown.
+ * This is the special rule of the TypeScript compiler.
+ *
+ * ```typescript
+ * // MUST DECLARE THE VARIABLE TYPE
+ * const func: typia.AssertionGuard<number> = typia.createAssertGuardEquals<number>();
+ *
+ * // IF NOT, COMPILATION ERROR BE OCCURED
+ * const func = typia.createAssertGuardEquals<number>();
+ * ```
+ *
+ * > *Assertions require every name in the call target to be declared with an*
+ * > *explicit type annotation.*
+ *
+ * @returns Nothing until you configure the generic argument `T`
+ * @throws compile error
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export function createAssertGuardEquals<T>(): (
+    input: unknown,
+) => AssertionGuard<T>;
+
+/**
+ * @internal
+ */
+export function createAssertGuardEquals<T>(): (
+    input: unknown,
+) => AssertionGuard<T> {
+    halt("createAssertGuardEquals");
+}
+Object.assign(createAssertGuardEquals, assertGuardEquals);
+
 /**
  * Creates a reusable {@link equals} function.
  *

package/src/programmers/AssertProgrammer.ts

@@ -16,12 +16,16 @@ export namespace AssertProgrammer {
     export const write =
         (project: IProject) =>
         (modulo: ts.LeftHandSideExpression) =>
-        (equals: boolean) =>
+        (props: boolean | { equals: boolean; guard: boolean }) =>
         (type: ts.Type, name?: string) => {
+            // TO SUPPORT LEGACY FEATURE
+            if (typeof props === "boolean")
+                props = { equals: props, guard: false };
+
             const importer: FunctionImporter = new FunctionImporter(
                 modulo.getText(),
             );
-            const is = IsProgrammer.write(project)(modulo, true)(equals)(
+            const is = IsProgrammer.write(project)(modulo, true)(props.equals)(
                 type,
                 name ?? TypeFactory.getFullName(project.checker)(type),
             );
@@ -30,7 +34,7 @@ export namespace AssertProgrammer {
                 path: true,
                 trace: true,
                 numeric: OptionPredicator.numeric(project.options),
-                equals,
+                equals: props.equals,
                 atomist: (explore) => (entry) => (input) =>
                     [
                         ...(entry.expression ? [entry.expression] : []),
@@ -91,8 +95,8 @@ export namespace AssertProgrammer {
                                   ),
                               ]),
                     ].reduce((x, y) => ts.factory.createLogicalAnd(x, y)),
-                combiner: combiner(equals)(project)(importer),
-                joiner: joiner(equals)(project)(importer),
+                combiner: combiner(props.equals)(project)(importer),
+                joiner: joiner(props.equals)(project)(importer),
                 success: ts.factory.createTrue(),
                 addition: () => importer.declare(modulo),
             })(importer)(type, name);
@@ -106,9 +110,21 @@ export namespace AssertProgrammer {
                         TypeFactory.keyword("any"),
                     ),
                 ],
-                ts.factory.createTypeReferenceNode(
-                    name ?? TypeFactory.getFullName(project.checker)(type),
-                ),
+                props.guard
+                    ? ts.factory.createTypePredicateNode(
+                          ts.factory.createToken(ts.SyntaxKind.AssertsKeyword),
+                          ts.factory.createIdentifier("input"),
+                          ts.factory.createTypeReferenceNode(
+                              name ??
+                                  TypeFactory.getFullName(project.checker)(
+                                      type,
+                                  ),
+                          ),
+                      )
+                    : ts.factory.createTypeReferenceNode(
+                          name ??
+                              TypeFactory.getFullName(project.checker)(type),
+                      ),
                 undefined,
                 ts.factory.createBlock(
                     [
@@ -137,9 +153,13 @@ export namespace AssertProgrammer {
                             ),
                             undefined,
                         ),
-                        ts.factory.createReturnStatement(
-                            ts.factory.createIdentifier(`input`),
-                        ),
+                        ...(props.guard === false
+                            ? [
+                                  ts.factory.createReturnStatement(
+                                      ts.factory.createIdentifier(`input`),
+                                  ),
+                              ]
+                            : []),
                     ],
                     true,
                 ),

package/src/programmers/helpers/ProtobufUtil.ts

@@ -26,7 +26,7 @@ export namespace ProtobufUtil {
             if (c.type === "boolean") set.add("bool");
             else if (c.type === "bigint") set.add("uint64");
             else if (c.type === "number")
-                set.add(deduce_numeric_type(c.values));
+                set.add(deduce_numeric_type(c.values as number[]));
             else if (c.type === "string") set.add("string");
         for (const atomic of meta.atomics)
             if (atomic.type === "boolean") set.add("bool");
@@ -42,7 +42,8 @@ export namespace ProtobufUtil {
     export const getNumbers = (meta: Metadata) => {
         const set: Set<ProtobufAtomic.Numeric> = new Set();
         for (const c of meta.constants)
-            if (c.type === "number") set.add(deduce_numeric_type(c.values));
+            if (c.type === "number")
+                set.add(deduce_numeric_type(c.values as number[]));
         for (const atomic of meta.atomics)
             if (atomic.type === "number")
                 decode_number(atomic.tags).forEach((t) => set.add(t));

package/src/programmers/internal/check_string.ts

@@ -40,8 +40,11 @@ const check_string_type_tags =
             .map((row) =>
                 row.map((tag) => ({
                     expected: `string & ${tag.name}`,
-                    expression: ExpressionFactory.transpile(project.context)(
-                        tag.validate!,
+                    expression: (
+                        tag.predicate ??
+                        ExpressionFactory.transpile(project.context)(
+                            tag.validate!,
+                        )
                     )(input),
                 })),
             );

package/src/programmers/internal/metadata_to_pattern.ts

@@ -18,7 +18,9 @@ export const metadata_to_pattern =
             meta.constants.map((c) => {
                 if (c.type !== "string")
                     return c.values.map((v) => v.toString());
-                return c.values.map((str) => PatternUtil.escape(str));
+                return (c.values as string[]).map((str) =>
+                    PatternUtil.escape(str),
+                );
             }),
         );
         for (const a of meta.atomics)

package/src/reflect.ts

@@ -0,0 +1,24 @@
+import { Namespace } from "./functional/Namespace";
+
+import { MetadataApplication } from "./schemas/metadata/MetadataApplication";
+
+export function metadata(): never;
+
+export function metadata<Types extends unknown[]>(): MetadataApplication;
+
+/**
+ * @internal
+ */
+export function metadata(): never {
+    halt("metadata");
+}
+Object.assign(metadata, Namespace.reflect.metadata());
+
+/**
+ * @internal
+ */
+function halt(name: string): never {
+    throw new Error(
+        `Error on typia.reflect.${name}(): no transform has been configured. Read and follow https://typia.io/docs/setup please.`,
+    );
+}

package/src/schemas/metadata/IMetadataApplication.ts

@@ -1,7 +1,7 @@
 import { IMetadata } from "./IMetadata";
-import { IMetadataCollection } from "./IMetadataCollection";
+import { IMetadataComponents } from "./IMetadataComponents";
 
 export interface IMetadataApplication {
     metadatas: IMetadata[];
-    collection: IMetadataCollection;
+    components: IMetadataComponents;
 }

package/src/schemas/metadata/{IMetadataCollection.ts → IMetadataComponents.ts}

@@ -3,7 +3,7 @@ import { IMetadataArrayType } from "./IMetadataArrayType";
 import { IMetadataObject } from "./IMetadataObject";
 import { IMetadataTupleType } from "./IMetadataTupleType";
 
-export interface IMetadataCollection {
+export interface IMetadataComponents {
     objects: IMetadataObject[];
     aliases: IMetadataAlias[];
     arrays: IMetadataArrayType[];

package/src/schemas/metadata/IMetadataConstant.ts

@@ -6,7 +6,7 @@ export type IMetadataConstant =
     | IMetadataConstant.IBase<"boolean", boolean>
     | IMetadataConstant.IBase<"number", number>
     | IMetadataConstant.IBase<"string", string>
-    | IMetadataConstant.IBase<"bigint", bigint>;
+    | IMetadataConstant.IBase<"bigint", string>;
 export namespace IMetadataConstant {
     export interface IBase<
         Type extends Atomic.Literal,

package/src/schemas/metadata/IMetadataTypeTag.ts

@@ -4,9 +4,9 @@ export interface IMetadataTypeTag {
     target: "boolean" | "bigint" | "number" | "string" | "array";
     name: string;
     kind: string;
-    value: any;
-    validate: string | undefined;
     exclusive: boolean | string[];
+    value?: any;
+    validate?: string | undefined;
 
     /**
      * @internal