@typia/interface 12.0.0-dev.20260225

package/src/typings/Primitive.ts

@@ -0,0 +1,71 @@
+import { Format } from "../tags/Format";
+import { Equal } from "./internal/Equal";
+import { IsTuple } from "./internal/IsTuple";
+import { NativeClass } from "./internal/NativeClass";
+import { ValueOf } from "./internal/ValueOf";
+
+/**
+ * Converts a type to its JSON-serializable primitive form.
+ *
+ * `Primitive<T>` transforms types for JSON serialization: boxed primitives
+ * become primitives (Boolean→boolean), classes become plain objects with
+ * methods removed, Date becomes `string & Format<"date-time">`, and types with
+ * `toJSON()` use their return type. Native classes (except Date) and bigint
+ * become `never` as they're not JSON-serializable.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @author Kyungsu Kang - https://github.com/kakasoo
+ * @author Michael - https://github.com/8471919
+ * @template T Target type to convert
+ */
+export type Primitive<T> =
+  Equal<T, PrimitiveMain<T>> extends true ? T : PrimitiveMain<T>;
+
+type PrimitiveMain<Instance> = Instance extends [never]
+  ? never // (special trick for jsonable | null) type
+  : ValueOf<Instance> extends bigint
+    ? never
+    : ValueOf<Instance> extends boolean | number | string
+      ? ValueOf<Instance>
+      : Instance extends Function
+        ? never
+        : ValueOf<Instance> extends object
+          ? Instance extends object
+            ? Instance extends Date
+              ? string & Format<"date-time">
+              : Instance extends IJsonable<infer Raw>
+                ? ValueOf<Raw> extends object
+                  ? Raw extends object
+                    ? PrimitiveObject<Raw> // object would be primitified
+                    : never // cannot be
+                  : ValueOf<Raw> // atomic value
+                : Instance extends Exclude<NativeClass, Date>
+                  ? never
+                  : PrimitiveObject<Instance> // object would be primitified
+            : never // cannot be
+          : ValueOf<Instance>;
+
+type PrimitiveObject<Instance extends object> =
+  Instance extends Array<infer T>
+    ? IsTuple<Instance> extends true
+      ? PrimitiveTuple<Instance>
+      : PrimitiveMain<T>[]
+    : {
+        [P in keyof Instance]: PrimitiveMain<Instance[P]>;
+      };
+
+type PrimitiveTuple<T extends readonly any[]> = T extends []
+  ? []
+  : T extends [infer F]
+    ? [PrimitiveMain<F>]
+    : T extends [infer F, ...infer Rest extends readonly any[]]
+      ? [PrimitiveMain<F>, ...PrimitiveTuple<Rest>]
+      : T extends [(infer F)?]
+        ? [PrimitiveMain<F>?]
+        : T extends [(infer F)?, ...infer Rest extends readonly any[]]
+          ? [PrimitiveMain<F>?, ...PrimitiveTuple<Rest>]
+          : [];
+
+interface IJsonable<T> {
+  toJSON(): T;
+}

package/src/typings/ProtobufAtomic.ts

@@ -0,0 +1,30 @@
+/**
+ * Protocol Buffers atomic (scalar) type names.
+ *
+ * Union of all primitive type identifiers used in Protocol Buffers wire format
+ * encoding/decoding.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export type ProtobufAtomic =
+  | "bool"
+  | "int32"
+  | "uint32"
+  | "int64"
+  | "uint64"
+  | "float"
+  | "double"
+  | "string";
+export namespace ProtobufAtomic {
+  /** Numeric protobuf types (integers and floats). */
+  export type Numeric =
+    | "int32"
+    | "uint32"
+    | "int64"
+    | "uint64"
+    | "float"
+    | "double";
+
+  /** 64-bit integer types that map to JavaScript `bigint`. */
+  export type BigNumeric = "int64" | "uint64";
+}

package/src/typings/Resolved.ts

@@ -0,0 +1,58 @@
+import { Equal } from "./internal/Equal";
+import { IsTuple } from "./internal/IsTuple";
+import { NativeClass } from "./internal/NativeClass";
+import { ValueOf } from "./internal/ValueOf";
+
+/**
+ * Converts a type to its resolved form by erasing all methods.
+ *
+ * `Resolved<T>` transforms classes to plain objects, extracts primitive values
+ * from boxed types (Boolean→boolean, Number→number, String→string), and
+ * recursively processes nested structures. Native classes (Date, Set, Map,
+ * etc.) are preserved unchanged.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @author Kyungsu Kang - https://github.com/kakasoo
+ * @template T Target type to resolve
+ */
+export type Resolved<T> =
+  Equal<T, ResolvedMain<T>> extends true ? T : ResolvedMain<T>;
+
+type ResolvedMain<T> = T extends [never]
+  ? never // (special trick for jsonable | null) type
+  : ValueOf<T> extends boolean | number | bigint | string
+    ? ValueOf<T>
+    : T extends Function
+      ? never
+      : T extends object
+        ? ResolvedObject<T>
+        : ValueOf<T>;
+
+type ResolvedObject<T extends object> =
+  T extends Array<infer U>
+    ? IsTuple<T> extends true
+      ? ResolvedTuple<T>
+      : ResolvedMain<U>[]
+    : T extends Set<infer U>
+      ? Set<ResolvedMain<U>>
+      : T extends Map<infer K, infer V>
+        ? Map<ResolvedMain<K>, ResolvedMain<V>>
+        : T extends WeakSet<any> | WeakMap<any, any>
+          ? never
+          : T extends NativeClass
+            ? T
+            : {
+                [P in keyof T]: ResolvedMain<T[P]>;
+              };
+
+type ResolvedTuple<T extends readonly any[]> = T extends []
+  ? []
+  : T extends [infer F]
+    ? [ResolvedMain<F>]
+    : T extends [infer F, ...infer Rest extends readonly any[]]
+      ? [ResolvedMain<F>, ...ResolvedTuple<Rest>]
+      : T extends [(infer F)?]
+        ? [ResolvedMain<F>?]
+        : T extends [(infer F)?, ...infer Rest extends readonly any[]]
+          ? [ResolvedMain<F>?, ...ResolvedTuple<Rest>]
+          : [];

package/src/typings/SnakeCase.ts

@@ -0,0 +1,126 @@
+import { Equal } from "./internal/Equal";
+import { NativeClass } from "./internal/NativeClass";
+import { ValueOf } from "./internal/ValueOf";
+
+/**
+ * Converts all object keys to snake_case.
+ *
+ * `SnakeCase<T>` transforms object property names to snake_case format and
+ * erases methods like {@link Resolved}. Recursively processes nested
+ * structures.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @template T Target type to transform
+ */
+export type SnakeCase<T> =
+  Equal<T, SnakageMain<T>> extends true ? T : SnakageMain<T>;
+
+/* -----------------------------------------------------------
+    OBJECT CONVERSION
+----------------------------------------------------------- */
+
+type SnakageMain<T> = T extends [never]
+  ? never // special trick for (jsonable | null) type
+  : T extends { valueOf(): boolean | bigint | number | string }
+    ? ValueOf<T>
+    : T extends Function
+      ? never
+      : T extends object
+        ? SnakageObject<T>
+        : T;
+
+type SnakageObject<T extends object> =
+  T extends Array<infer U>
+    ? IsTuple<T> extends true
+      ? SnakageTuple<T>
+      : SnakageMain<U>[]
+    : T extends Set<infer U>
+      ? Set<SnakageMain<U>>
+      : T extends Map<infer K, infer V>
+        ? Map<SnakageMain<K>, SnakageMain<V>>
+        : T extends WeakSet<any> | WeakMap<any, any>
+          ? never
+          : T extends NativeClass
+            ? T
+            : {
+                [Key in keyof T as SnakageString<Key & string>]: SnakageMain<
+                  T[Key]
+                >;
+              };
+
+/* -----------------------------------------------------------
+    SPECIAL CASES
+----------------------------------------------------------- */
+type IsTuple<T extends readonly any[] | { length: number }> = [T] extends [
+  never,
+]
+  ? false
+  : T extends readonly any[]
+    ? number extends T["length"]
+      ? false
+      : true
+    : false;
+type SnakageTuple<T extends readonly any[]> = T extends []
+  ? []
+  : T extends [infer F]
+    ? [SnakageMain<F>]
+    : T extends [infer F, ...infer Rest extends readonly any[]]
+      ? [SnakageMain<F>, ...SnakageTuple<Rest>]
+      : T extends [(infer F)?]
+        ? [SnakageMain<F>?]
+        : T extends [(infer F)?, ...infer Rest extends readonly any[]]
+          ? [SnakageMain<F>?, ...SnakageTuple<Rest>]
+          : [];
+
+/* -----------------------------------------------------------
+    STRING CONVERTER
+----------------------------------------------------------- */
+type SnakageString<Key extends string> = Key extends `${infer _}`
+  ? SnakageStringRepeatedly<Key, "">
+  : Key;
+type SnakageStringRepeatedly<
+  S extends string,
+  Previous extends string,
+> = S extends `${infer First}${infer Second}${infer Rest}`
+  ? `${Underscore<Previous, First>}${Lowercase<First>}${Underscore<
+      First,
+      Second
+    >}${Lowercase<Second>}${SnakageStringRepeatedly<Rest, Second>}`
+  : S extends `${infer First}`
+    ? `${Underscore<Previous, First>}${Lowercase<First>}`
+    : "";
+type Underscore<First extends string, Second extends string> = First extends
+  | UpperAlphabetic
+  | ""
+  | "_"
+  ? ""
+  : Second extends UpperAlphabetic
+    ? "_"
+    : "";
+type UpperAlphabetic =
+  | "A"
+  | "B"
+  | "C"
+  | "D"
+  | "E"
+  | "F"
+  | "G"
+  | "H"
+  | "I"
+  | "J"
+  | "K"
+  | "L"
+  | "M"
+  | "N"
+  | "O"
+  | "P"
+  | "Q"
+  | "R"
+  | "S"
+  | "T"
+  | "U"
+  | "V"
+  | "W"
+  | "X"
+  | "Y"
+  | "Z";

package/src/typings/SpecialFields.ts

@@ -0,0 +1,13 @@
+/**
+ * Extracts property keys whose value type extends the target type.
+ *
+ * `SpecialFields<Instance, Target>` returns a union of property names from
+ * `Instance` where the property value extends `Target`.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @template Instance Source object type
+ * @template Target Target value type to match
+ */
+export type SpecialFields<Instance extends object, Target> = {
+  [P in keyof Instance]: Instance[P] extends Target ? P : never;
+}[keyof Instance & string];

package/src/typings/ValidationPipe.ts

@@ -0,0 +1,20 @@
+/**
+ * Discriminated union for validation results.
+ *
+ * `ValidationPipe<T, E>` represents either a successful validation with data of
+ * type `T`, or a failed validation with an array of errors of type `E`. Use the
+ * `success` discriminant to narrow the type.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @template T Success data type
+ * @template E Error type
+ */
+export type ValidationPipe<T, E> =
+  | {
+      success: true;
+      data: T;
+    }
+  | {
+      success: false;
+      errors: E[];
+    };

package/src/typings/index.ts

@@ -0,0 +1,13 @@
+export * from "./AssertionGuard";
+export * from "./CamelCase";
+export * from "./PascalCase";
+export * from "./Primitive";
+export * from "./Resolved";
+export * from "./SnakeCase";
+
+export * from "./Atomic";
+export * from "./ClassProperties";
+export * from "./OmitNever";
+export * from "./ProtobufAtomic";
+export * from "./SpecialFields";
+export * from "./ValidationPipe";

package/src/typings/internal/Equal.ts

@@ -0,0 +1,14 @@
+/**
+ * Checks if two types are exactly equal.
+ *
+ * `Equal<X, Y>` returns `true` if types X and Y are identical, `false`
+ * otherwise. Works with any TypeScript types including unions.
+ *
+ * @author Kyungsu Kang - https://github.com/kakasoo
+ * @template X First type to compare
+ * @template Y Second type to compare
+ */
+export type Equal<X, Y> =
+  (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2
+    ? true
+    : false;

package/src/typings/internal/IsTuple.ts

@@ -0,0 +1,17 @@
+/**
+ * Checks if an array type is a tuple (fixed length) or regular array.
+ *
+ * Returns `true` for tuple types like `[string, number]` where length is fixed,
+ * and `false` for array types like `string[]` where length is variable.
+ *
+ * @template T Array or tuple type to check
+ */
+export type IsTuple<T extends readonly any[] | { length: number }> = [
+  T,
+] extends [never]
+  ? false
+  : T extends readonly any[]
+    ? number extends T["length"]
+      ? false
+      : true
+    : false;

package/src/typings/internal/NativeClass.ts

@@ -0,0 +1,31 @@
+/**
+ * Union of JavaScript built-in class types.
+ *
+ * `NativeClass` includes Date, collections (Set, Map, WeakSet, WeakMap), typed
+ * arrays (Uint8Array, Int32Array, etc.), binary data types (ArrayBuffer,
+ * DataView, Blob, File), and RegExp. These types receive special handling in
+ * typia's serialization and validation.
+ */
+export type NativeClass =
+  | Date
+  | Set<any>
+  | Map<any, any>
+  | WeakSet<any>
+  | WeakMap<any, any>
+  | Uint8Array
+  | Uint8ClampedArray
+  | Uint16Array
+  | Uint32Array
+  | BigUint64Array
+  | Int8Array
+  | Int16Array
+  | Int32Array
+  | BigInt64Array
+  | Float32Array
+  | Float64Array
+  | ArrayBuffer
+  | SharedArrayBuffer
+  | DataView
+  | Blob
+  | File
+  | RegExp;

package/src/typings/internal/ValueOf.ts

@@ -0,0 +1,29 @@
+/**
+ * Extracts the primitive value type from boxed primitives.
+ *
+ * `ValueOf<Instance>` converts boxed primitive types (Boolean, Number, String)
+ * to their primitive equivalents (boolean, number, string). Non-boxed types are
+ * returned unchanged.
+ *
+ * @template Instance Type to extract primitive from
+ */
+export type ValueOf<Instance> =
+  IsValueOf<Instance, Boolean> extends true
+    ? boolean
+    : IsValueOf<Instance, Number> extends true
+      ? number
+      : IsValueOf<Instance, String> extends true
+        ? string
+        : Instance;
+
+type IsValueOf<Instance, Object extends IValueOf<any>> = Instance extends Object
+  ? Object extends IValueOf<infer Primitive>
+    ? Instance extends Primitive
+      ? false
+      : true // not Primitive, but Object
+    : false // cannot be
+  : false;
+
+interface IValueOf<T> {
+  valueOf(): T;
+}

package/src/utils/IRandomGenerator.ts

@@ -0,0 +1,105 @@
+import { OpenApi } from "../openapi/OpenApi";
+
+/**
+ * Random value generator interface for typia.
+ *
+ * `IRandomGenerator` defines methods for generating random values of various
+ * types. Used by `typia.random<T>()` for mock data generation.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface IRandomGenerator {
+  /** Generates a random boolean. */
+  boolean(): boolean | undefined;
+
+  /** Generates a random number within schema constraints. */
+  number(schema: OpenApi.IJsonSchema.INumber): number;
+
+  /** Generates a random integer within schema constraints. */
+  integer(schema: OpenApi.IJsonSchema.IInteger): number;
+
+  /** Generates a random bigint within schema constraints. */
+  bigint(schema: OpenApi.IJsonSchema.IInteger): bigint;
+
+  /** Generates a random string within schema constraints. */
+  string(schema: OpenApi.IJsonSchema.IString): string;
+
+  /** Generates a random array with elements from the generator function. */
+  array<T>(
+    schema: Omit<OpenApi.IJsonSchema.IArray, "items"> & {
+      element: (index: number, count: number) => T;
+    },
+  ): T[];
+
+  /** Generates a random string matching the regex pattern. */
+  pattern(regex: RegExp): string;
+
+  // String format generators
+  byte(): string;
+
+  password(): string;
+
+  regex(): string;
+
+  uuid(): string;
+
+  email(): string;
+
+  hostname(): string;
+
+  idnEmail(): string;
+
+  idnHostname(): string;
+
+  iri(): string;
+
+  iriReference(): string;
+
+  ipv4(): string;
+
+  ipv6(): string;
+
+  uri(): string;
+
+  uriReference(): string;
+
+  uriTemplate(): string;
+
+  url(): string;
+
+  datetime(props?: { minimum?: number; maximum?: number }): string;
+
+  date(props?: { minimum?: number; maximum?: number }): string;
+
+  time(): string;
+
+  duration(): string;
+
+  jsonPointer(): string;
+
+  relativeJsonPointer(): string;
+}
+
+export namespace IRandomGenerator {
+  /** Custom generators for specific schema properties. */
+  export interface CustomMap {
+    string?: (
+      schema: OpenApi.IJsonSchema.IString & Record<string, any>,
+    ) => string;
+    number?: (
+      schema: OpenApi.IJsonSchema.INumber & Record<string, any>,
+    ) => number;
+    integer?: (
+      schema: OpenApi.IJsonSchema.IInteger & Record<string, any>,
+    ) => number;
+    bigint?: (
+      schema: OpenApi.IJsonSchema.IInteger & Record<string, any>,
+    ) => bigint;
+    boolean?: (schema: Record<string, any>) => boolean | undefined;
+    array?: <T>(
+      schema: Omit<OpenApi.IJsonSchema.IArray, "items"> & {
+        element: (index: number, count: number) => T;
+      } & Record<string, any>,
+    ) => T[];
+  }
+}

package/src/utils/IReadableURLSearchParams.ts

@@ -0,0 +1,25 @@
+/**
+ * Minimal interface for reading URL query parameters.
+ *
+ * `IReadableURLSearchParams` is a subset of the standard {@link URLSearchParams}
+ * interface, containing only the read operations needed for query parameter
+ * parsing. This interface was designed specifically for compatibility with the
+ * [Hono.js](https://hono.dev/) web framework, which provides its own query
+ * parameter implementation.
+ *
+ * The interface exposes:
+ *
+ * - {@link URLSearchParams.size | size}: Number of parameters
+ * - {@link URLSearchParams.get | get}: Retrieve first value for a key
+ * - {@link URLSearchParams.getAll | getAll}: Retrieve all values for a key
+ *
+ * Use this interface when implementing query parameter handling that needs to
+ * work with both standard `URLSearchParams` and framework-specific
+ * implementations.
+ *
+ * @author https://github.com/miyaji255
+ */
+export type IReadableURLSearchParams = Pick<
+  URLSearchParams,
+  "size" | "get" | "getAll"
+>;

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from "./IRandomGenerator";
+export * from "./IReadableURLSearchParams";