@nestia/sdk 12.0.0-rc.4 → 12.1.0

package/src/generates/internal/SdkFileProgrammer.ts

@@ -51,9 +51,7 @@ export namespace SdkFileProgrammer {
     (directory: SdkRouteDirectory) =>
     async (outDir: string): Promise<void> => {
       // CREATE A NEW DIRECTORY
-      try {
-        await fs.promises.mkdir(outDir);
-      } catch {}
+      await fs.promises.mkdir(outDir, { recursive: true });
 
       // ITERATE CHILDREN
       const statements: Node[] = [];

package/src/generates/internal/SdkHttpCloneReferencer.ts

@@ -69,22 +69,24 @@ export namespace SdkHttpCloneReferencer {
     directory: string;
     route: ITypedWebSocketRoute;
   }): void => {
-    const unique: Set<string> = new Set();
+    const unique: Map<string, string> = new Map();
     const keep: ITypedWebSocketRoute["imports"] = [];
     for (const imp of props.route.imports) {
       const cloned: string[] = SdkWebSocketCloneProgrammer.isNodeModulesPath(
         imp.file,
       )
         ? []
-        : imp.elements.filter((elem) =>
-            props.cloned.has(
-              SdkWebSocketCloneProgrammer.importKey(imp.file, elem),
-            ),
-          );
+        : imp.elements.filter((elem) => {
+            const imported: string = imp.elementAliases?.[elem] ?? elem;
+            return props.cloned.has(
+              SdkWebSocketCloneProgrammer.importKey(imp.file, imported),
+            );
+          });
       const remained: string[] = imp.elements.filter(
         (elem) => cloned.includes(elem) === false,
       );
-      for (const elem of cloned) unique.add(elem);
+      for (const elem of cloned)
+        unique.set(elem, imp.elementAliases?.[elem] ?? elem);
       if (
         imp.asterisk !== null ||
         imp.default !== null ||
@@ -98,11 +100,14 @@ export namespace SdkHttpCloneReferencer {
 
     props.route.imports = [
       ...keep,
-      ...Array.from(unique).map((str) => ({
-        file: `${props.directory}/${str}`,
+      ...Array.from(unique).map(([local, imported]) => ({
+        file: `${props.directory}/${imported}`,
         asterisk: null,
         default: null,
-        elements: [str],
+        elements: [local],
+        ...(local === imported
+          ? {}
+          : { elementAliases: { [local]: imported } }),
       })),
     ];
   };

package/src/generates/internal/SdkWebSocketCloneProgrammer.ts

@@ -14,9 +14,10 @@ export namespace SdkWebSocketCloneProgrammer {
     for (const route of app.routes)
       if (route.protocol === "websocket")
         for (const imp of route.imports)
-          for (const name of imp.elements) {
-            if (await clone(ctx)(imp.file, name))
-              cloned.add(importKey(imp.file, name));
+          for (const local of imp.elements) {
+            const imported: string = imp.elementAliases?.[local] ?? local;
+            if (await clone(ctx)(imp.file, imported))
+              cloned.add(importKey(imp.file, imported));
           }
     return cloned;
   };

package/src/generates/internal/SwaggerOperationComposer.ts

@@ -1,8 +1,8 @@
-import { MetadataSchema } from "../../internal/legacy";
 import { OpenApi } from "@typia/interface";
 
 import { INestiaConfig } from "../../INestiaConfig";
 import { SecurityAnalyzer } from "../../analyses/SecurityAnalyzer";
+import { MetadataSchema } from "../../internal/legacy";
 import { ITypedHttpRoute } from "../../structures/ITypedHttpRoute";
 import { SwaggerDescriptionComposer } from "./SwaggerDescriptionComposer";
 import { SwaggerOperationParameterComposer } from "./SwaggerOperationParameterComposer";

package/src/internal/legacy.ts

@@ -12,7 +12,6 @@
 // cross-reference lookups in O(1). Everything else either reads a
 // pre-baked field or short-circuits because typia's compile-time
 // transform already enforces the invariant.
-
 import type {
   IJsonSchemaCollection,
   IMetadataComponents,
@@ -39,16 +38,15 @@ declare module "@typia/interface" {
 /**
  * Plain `IMetadataSchema` augmented with the fields the nestia transform
  * pre-bakes. `size`, `name`, and `empty` replace the methods the legacy
- * `MetadataSchema` class exposed; `jsonSchema` is the OpenAPI 3.1
- * conversion typia's Go-side produces but does not expose to JS at
- * runtime.
+ * `MetadataSchema` class exposed; `jsonSchema` is the OpenAPI 3.1 conversion
+ * typia's Go-side produces but does not expose to JS at runtime.
  *
  * Fields are declared optional so that nested `IMetadataSchema` values
- * (`metadata.rest`, `metadata.escaped.original`, `IObjectType.value`,
- * …) — which are not top-level route inputs and therefore do not carry
- * the pre-baked overlay — still satisfy the type when passed through
- * legacy utilities. The utilities read the fields via the optional
- * accessor and fall back when absent.
+ * (`metadata.rest`, `metadata.escaped.original`, `IObjectType.value`, …) —
+ * which are not top-level route inputs and therefore do not carry the pre-baked
+ * overlay — still satisfy the type when passed through legacy utilities. The
+ * utilities read the fields via the optional accessor and fall back when
+ * absent.
  */
 export interface IReflectMetadata extends IMetadataSchema {
   size?: number;
@@ -64,9 +62,9 @@ export interface IReflectJsonSchema {
 }
 
 /**
- * Cross-reference dictionary produced by `MetadataComponents.from`. Each
- * map is keyed by the entry's `.name`, matching the lookup pattern the
- * legacy `MetadataComponents.dictionary` getter offered.
+ * Cross-reference dictionary produced by `MetadataComponents.from`. Each map is
+ * keyed by the entry's `.name`, matching the lookup pattern the legacy
+ * `MetadataComponents.dictionary` getter offered.
  */
 export interface IMetadataDictionary {
   objects: Map<string, IMetadataSchema.IObjectType>;
@@ -89,9 +87,9 @@ export type MetadataTupleType = IMetadataSchema.ITupleType;
 export type MetadataObjectType = IMetadataSchema.IObjectType;
 export type MetadataAtomic = IMetadataSchema.IAtomic;
 /**
- * Flattened constant-value shape: typia v13 splits `IConstant.IValue<T>` by
- * the atomic discriminator, but sdk's literal writer just needs the runtime
- * `value` payload, so collapse the union to a single ergonomic shape.
+ * Flattened constant-value shape: typia v13 splits `IConstant.IValue<T>` by the
+ * atomic discriminator, but sdk's literal writer just needs the runtime `value`
+ * payload, so collapse the union to a single ergonomic shape.
  */
 export interface MetadataConstantValue {
   value: string | number | bigint | boolean;
@@ -101,12 +99,12 @@ export type MetadataEscaped = IMetadataSchema.IEscaped;
 export type MetadataProperty = IMetadataSchema.IProperty;
 
 /**
- * Reference to a named array/tuple/object/alias type. typia v13's
- * plain `IReference` carries only the symbolic `name` + tags; the
- * legacy class additionally exposed `.type` as a getter that resolved
- * against the dictionary. `MetadataSchema.from` walks the metadata
- * tree once and attaches the resolved `.type` field so downstream
- * sdk code can keep its `ref.type` access pattern.
+ * Reference to a named array/tuple/object/alias type. typia v13's plain
+ * `IReference` carries only the symbolic `name` + tags; the legacy class
+ * additionally exposed `.type` as a getter that resolved against the
+ * dictionary. `MetadataSchema.from` walks the metadata tree once and attaches
+ * the resolved `.type` field so downstream sdk code can keep its `ref.type`
+ * access pattern.
  */
 export type MetadataArray = IMetadataSchema.IReference & {
   type: MetadataArrayType;
@@ -138,10 +136,10 @@ export const emptyOf = (m: IMetadataSchema): boolean =>
   (m as IReflectMetadata).empty ?? false;
 
 /**
- * Equivalent of the legacy `MetadataSchema.isSoleLiteral()` method:
- * `true` when the schema represents exactly one constant literal value
- * and nothing else. Used by sdk's type printer to fall back to literal
- * emission instead of a union.
+ * Equivalent of the legacy `MetadataSchema.isSoleLiteral()` method: `true` when
+ * the schema represents exactly one constant literal value and nothing else.
+ * Used by sdk's type printer to fall back to literal emission instead of a
+ * union.
  */
 export const isSoleLiteralOf = (m: IMetadataSchema): boolean => {
   if (m.any) return false;
@@ -184,11 +182,11 @@ export namespace MetadataComponents {
 
 export namespace MetadataSchema {
   /**
-   * Walks the metadata tree and attaches the resolved `.type` field to
-   * every `IReference` it encounters, using the supplied dictionary as
-   * the lookup index. This is idempotent — references whose `.type`
-   * has already been resolved are left alone — and mutates the input,
-   * matching the in-place resolution model `@typia/core` 12.x used.
+   * Walks the metadata tree and attaches the resolved `.type` field to every
+   * `IReference` it encounters, using the supplied dictionary as the lookup
+   * index. This is idempotent — references whose `.type` has already been
+   * resolved are left alone — and mutates the input, matching the in-place
+   * resolution model `@typia/core` 12.x used.
    */
   export const from = (
     plain: IMetadataSchema,
@@ -202,12 +200,11 @@ export namespace MetadataSchema {
 }
 
 /**
- * The walk tracks visited *targets* (the IObjectType / IArrayType / …
- * instances reached through the dictionary), not the wrapper schemas.
- * Wrapper schemas are reconstructed on the JS side and are not shared
- * across recursive references, so a `visited<IMetadataSchema>` set never
- * matches and the walk would recurse forever on cycles like
- * `interface Node { children: Node[] }`.
+ * The walk tracks visited _targets_ (the IObjectType / IArrayType / … instances
+ * reached through the dictionary), not the wrapper schemas. Wrapper schemas are
+ * reconstructed on the JS side and are not shared across recursive references,
+ * so a `visited<IMetadataSchema>` set never matches and the walk would recurse
+ * forever on cycles like `interface Node { children: Node[] }`.
  */
 const attachTypes = (
   schema: IMetadataSchema | null | undefined,
@@ -222,7 +219,8 @@ const attachTypes = (
     for (const elem of target.elements) attachTypes(elem, dict, visited);
   });
   attachReferences(schema.objects, dict.objects, visited, (target) => {
-    for (const prop of target.properties) attachTypes(prop.value, dict, visited);
+    for (const prop of target.properties)
+      attachTypes(prop.value, dict, visited);
   });
   attachReferences(schema.aliases, dict.aliases, visited, (target) =>
     attachTypes(target.value, dict, visited),
@@ -254,8 +252,7 @@ const attachReferences = <Target extends { name: string }>(
     const mutable = ref as IMetadataSchema.IReference & { type?: Target };
     if (mutable.type === undefined) {
       const target = index.get(ref.name);
-      if (target !== undefined)
-        (mutable as { type?: Target }).type = target;
+      if (target !== undefined) (mutable as { type?: Target }).type = target;
     }
     if (mutable.type !== undefined && visited.has(mutable.type) === false) {
       visited.add(mutable.type);
@@ -290,13 +287,12 @@ export namespace MetadataFactory {
 
   /**
    * Walks the metadata tree once, invoking the provided validator on each
-   * visited node, and accumulates the produced messages into `IError`
-   * entries. The walk skips back-edges through references so cyclic
-   * structures terminate. This is a faithful reimplementation of the
-   * legacy `@typia/core` walker, kept lean: the typia native transform
-   * has already validated structural invariants, so the validator is only
-   * called for SDK-side policy checks (JSON-serializability, query/header
-   * atomic-only rules, …).
+   * visited node, and accumulates the produced messages into `IError` entries.
+   * The walk skips back-edges through references so cyclic structures
+   * terminate. This is a faithful reimplementation of the legacy `@typia/core`
+   * walker, kept lean: the typia native transform has already validated
+   * structural invariants, so the validator is only called for SDK-side policy
+   * checks (JSON-serializability, query/header atomic-only rules, …).
    */
   export const validate = (props: {
     options?: unknown;
@@ -315,39 +311,49 @@ export namespace MetadataFactory {
       if (messages.length)
         errors.push({ name: nameOf(metadata), explore, messages });
       for (const obj of metadata.objects) {
-        const type = (obj as IMetadataSchema.IReference & {
-          type?: IMetadataSchema.IObjectType;
-        }).type;
+        const type = (
+          obj as IMetadataSchema.IReference & {
+            type?: IMetadataSchema.IObjectType;
+          }
+        ).type;
         if (type === undefined || visited.has(type)) continue;
         visited.add(type);
         for (const prop of type.properties)
           visit(prop.value, {
             object: type,
-            property: nameOf(prop.key) || String(prop.key.constants[0]?.values[0]?.value ?? ""),
+            property:
+              nameOf(prop.key) ||
+              String(prop.key.constants[0]?.values[0]?.value ?? ""),
             parameter: null,
             output: explore.output,
           });
       }
       for (const arr of metadata.arrays) {
-        const type = (arr as IMetadataSchema.IReference & {
-          type?: IMetadataSchema.IArrayType;
-        }).type;
+        const type = (
+          arr as IMetadataSchema.IReference & {
+            type?: IMetadataSchema.IArrayType;
+          }
+        ).type;
         if (type === undefined || visited.has(type)) continue;
         visited.add(type);
         visit(type.value, explore);
       }
       for (const tuple of metadata.tuples) {
-        const type = (tuple as IMetadataSchema.IReference & {
-          type?: IMetadataSchema.ITupleType;
-        }).type;
+        const type = (
+          tuple as IMetadataSchema.IReference & {
+            type?: IMetadataSchema.ITupleType;
+          }
+        ).type;
         if (type === undefined || visited.has(type)) continue;
         visited.add(type);
         for (const elem of type.elements) visit(elem, explore);
       }
       for (const alias of metadata.aliases) {
-        const type = (alias as IMetadataSchema.IReference & {
-          type?: IMetadataSchema.IAliasType;
-        }).type;
+        const type = (
+          alias as IMetadataSchema.IReference & {
+            type?: IMetadataSchema.IAliasType;
+          }
+        ).type;
         if (type === undefined || visited.has(type)) continue;
         visited.add(type);
         visit(type.value, explore);
@@ -370,10 +376,10 @@ export namespace MetadataFactory {
 export namespace JsonMetadataFactory {
   /**
    * Rejects metadata that cannot be losslessly JSON-serialized. The typia
-   * native runtime already screens out most structurally invalid types, so
-   * this only adds the JSON-policy bans the legacy `@typia/core` walker
-   * enforced — bare `bigint` payloads, function-typed properties, and
-   * `Map` / `Set` containers that have no canonical JSON representation.
+   * native runtime already screens out most structurally invalid types, so this
+   * only adds the JSON-policy bans the legacy `@typia/core` walker enforced —
+   * bare `bigint` payloads, function-typed properties, and `Map` / `Set`
+   * containers that have no canonical JSON representation.
    */
   export const validate: MetadataFactory.Validator = (props) => {
     const messages: string[] = [];
@@ -414,12 +420,12 @@ export namespace JsonSchemasProgrammer {
   /**
    * Consumes the per-metadata `jsonSchema` field the nestia transform
    * pre-bakes. Top-level route metadata (success / parameter / exception)
-   * always carries a baked schema; for nested metadata (object property
-   * values reached by the decomposed-query path), the bake is absent and
-   * this function falls back to a minimal JS-side converter that handles
-   * the schema shapes decompose actually emits — atomics, constants,
-   * templates, arrays of those, named references — without re-implementing
-   * the typia native programmer wholesale.
+   * always carries a baked schema; for nested metadata (object property values
+   * reached by the decomposed-query path), the bake is absent and this function
+   * falls back to a minimal JS-side converter that handles the schema shapes
+   * decompose actually emits — atomics, constants, templates, arrays of those,
+   * named references — without re-implementing the typia native programmer
+   * wholesale.
    */
   export const writeSchemas = (props: {
     version: "3.0" | "3.1";
@@ -462,12 +468,16 @@ const schemaFromMetadata = (m: IMetadataSchema): OpenApi.IJsonSchema => {
     void tpl;
   }
   for (const arr of m.arrays) {
-    const inner = (arr as IMetadataSchema.IReference & {
-      type?: IMetadataSchema.IArrayType;
-    }).type;
+    const inner = (
+      arr as IMetadataSchema.IReference & {
+        type?: IMetadataSchema.IArrayType;
+      }
+    ).type;
     union.push({
       type: "array",
-      items: inner ? schemaFromMetadata(inner.value) : ({} as OpenApi.IJsonSchema),
+      items: inner
+        ? schemaFromMetadata(inner.value)
+        : ({} as OpenApi.IJsonSchema),
     } as unknown as OpenApi.IJsonSchema);
   }
   for (const obj of m.objects)

package/src/structures/IReflectHttpOperationException.ts

@@ -1,6 +1,6 @@
-import { MetadataFactory } from "../internal/legacy";
 import { IMetadataComponents, IMetadataSchema } from "@typia/interface";
 
+import { MetadataFactory } from "../internal/legacy";
 import { IReflectType } from "./IReflectType";
 
 export interface IReflectHttpOperationException {

package/src/structures/IReflectHttpOperationParameter.ts

@@ -1,10 +1,10 @@
-import { MetadataFactory } from "../internal/legacy";
 import {
   IJsDocTagInfo,
   IMetadataComponents,
   IMetadataSchema,
 } from "@typia/interface";
 
+import { MetadataFactory } from "../internal/legacy";
 import { IReflectType } from "./IReflectType";
 
 export type IReflectHttpOperationParameter =

package/src/structures/IReflectImport.ts

@@ -3,4 +3,6 @@ export interface IReflectImport {
   asterisk: string | null;
   default: string | null;
   elements: string[];
+  /** Maps a local named binding to the name exported by its source module. */
+  elementAliases?: Record<string, string>;
 }

package/src/structures/IReflectMcpOperation.ts

@@ -1,4 +1,4 @@
-import ts from "typescript";
+import { IJsDocTagInfo } from "typia";
 
 import { IReflectImport } from "./IReflectImport";
 import { IReflectMcpOperationParameter } from "./IReflectMcpOperationParameter";
@@ -25,7 +25,7 @@ export interface IReflectMcpOperation {
   returnType: IReflectType | null;
   imports: IReflectImport[];
   description: string | null;
-  jsDocTags: ts.JSDocTagInfo[];
+  jsDocTags: IJsDocTagInfo[];
 }
 
 export namespace IReflectMcpOperation {

package/src/structures/ITypedApplication.ts

@@ -1,5 +1,4 @@
 import { IMetadataDictionary } from "../internal/legacy";
-
 import { INestiaProject } from "./INestiaProject";
 import { ITypedHttpRoute } from "./ITypedHttpRoute";
 import { ITypedMcpRoute } from "./ITypedMcpRoute";

package/src/structures/ITypedHttpRouteException.ts

@@ -1,5 +1,4 @@
 import { MetadataSchema } from "../internal/legacy";
-
 import { IReflectType } from "./IReflectType";
 
 export interface ITypedHttpRouteException {

package/src/structures/ITypedHttpRouteParameter.ts

@@ -1,6 +1,6 @@
-import { MetadataSchema } from "../internal/legacy";
 import { IJsDocTagInfo } from "typia";
 
+import { MetadataSchema } from "../internal/legacy";
 import { IReflectType } from "./IReflectType";
 
 export type ITypedHttpRouteParameter =

package/src/structures/ITypedMcpRoute.ts

@@ -1,4 +1,4 @@
-import ts from "typescript";
+import { IJsDocTagInfo } from "typia";
 
 import { IReflectController } from "./IReflectController";
 import { IReflectImport } from "./IReflectImport";
@@ -29,5 +29,5 @@ export interface ITypedMcpRoute {
   annotations: IReflectMcpOperation.IAnnotations | null;
   imports: IReflectImport[];
   description: string | null;
-  jsDocTags: ts.JSDocTagInfo[];
+  jsDocTags: IJsDocTagInfo[];
 }

package/src/utils/TsConfigReader.ts

@@ -10,7 +10,10 @@ export namespace TsConfigReader {
   export const read = async (file: string): Promise<ITsConfig> =>
     merge(file, new Set());
 
-  const merge = async (file: string, visited: Set<string>): Promise<ITsConfig> => {
+  const merge = async (
+    file: string,
+    visited: Set<string>,
+  ): Promise<ITsConfig> => {
     const location: string = path.resolve(file);
     if (visited.has(location)) return {};
     visited.add(location);
@@ -20,7 +23,10 @@ export namespace TsConfigReader {
     );
     const bases: ITsConfig[] = [];
     for (const parent of asArray(current.extends)) {
-      const next: string | null = resolveExtends(parent, path.dirname(location));
+      const next: string | null = resolveExtends(
+        parent,
+        path.dirname(location),
+      );
       if (next !== null) bases.push(await merge(next, visited));
     }
     return [...bases, current].reduce<ITsConfig>(
@@ -45,7 +51,9 @@ export namespace TsConfigReader {
   const resolveExtends = (specifier: string, cwd: string): string | null => {
     const candidates = (base: string): string[] => {
       const ext: string = path.extname(base);
-      return ext === ".json" || ext === ".jsonc" ? [base] : [base, `${base}.json`];
+      return ext === ".json" || ext === ".jsonc"
+        ? [base]
+        : [base, `${base}.json`];
     };
 
     if (path.isAbsolute(specifier) || specifier.startsWith(".")) {

package/src/validators/HttpHeadersValidator.ts

@@ -3,8 +3,9 @@ import { MetadataFactory } from "../internal/legacy";
 /**
  * Validator slot reserved for `@TypedHeaders` per-field SDK-side checks.
  * Returns `[]` because the typia native transform already enforces the
- * "atomic-or-array-of-atomic" constraint at compile time, and `MetadataFactory.validate`
- * — the only call site — is itself a passthrough on the v13 runtime.
+ * "atomic-or-array-of-atomic" constraint at compile time, and
+ * `MetadataFactory.validate` — the only call site — is itself a passthrough on
+ * the v13 runtime.
  */
 export namespace HttpHeadersValidator {
   export const validate: MetadataFactory.Validator = () => [];

package/src/validators/HttpQueryValidator.ts

@@ -1,10 +1,10 @@
 import { MetadataFactory } from "../internal/legacy";
 
 /**
- * Validator slot reserved for `@TypedQuery` per-field SDK-side checks.
- * Returns `[]` because the typia native transform already enforces the
- * atomic-only constraint at compile time, and `MetadataFactory.validate` —
- * the only call site — is itself a passthrough on the v13 runtime.
+ * Validator slot reserved for `@TypedQuery` per-field SDK-side checks. Returns
+ * `[]` because the typia native transform already enforces the atomic-only
+ * constraint at compile time, and `MetadataFactory.validate` — the only call
+ * site — is itself a passthrough on the v13 runtime.
  */
 export namespace HttpQueryValidator {
   export const validate: MetadataFactory.Validator = () => [];