@nestia/sdk 11.2.1 → 12.0.0-dev.20260521.1

package/src/analyses/TypedHttpRouteAnalyzer.ts

@@ -1,10 +1,13 @@
 import {
   IMetadataDictionary,
+  MetadataAliasType,
+  MetadataArrayType,
   MetadataComponents,
   MetadataFactory,
   MetadataObjectType,
   MetadataSchema,
-} from "@typia/core";
+  MetadataTupleType,
+} from "../internal/legacy";
 import { NamingConvention } from "@typia/utils";
 import { IMetadataComponents, IMetadataSchema } from "typia";
 
@@ -31,26 +34,10 @@ export namespace TypedHttpRouteAnalyzer {
           individual.push(e.components);
       }
     const components: MetadataComponents = MetadataComponents.from({
-      objects: Object.values(
-        Object.fromEntries(
-          individual.map((c) => c.objects.map((o) => [o.name, o])).flat(),
-        ),
-      ),
-      arrays: Object.values(
-        Object.fromEntries(
-          individual.map((c) => c.arrays.map((a) => [a.name, a])).flat(),
-        ),
-      ),
-      tuples: Object.values(
-        Object.fromEntries(
-          individual.map((c) => c.tuples.map((t) => [t.name, t])).flat(),
-        ),
-      ),
-      aliases: Object.values(
-        Object.fromEntries(
-          individual.map((c) => c.aliases.map((a) => [a.name, a])).flat(),
-        ),
-      ),
+      objects: uniqueComponents(individual.flatMap((c) => c.objects)),
+      arrays: uniqueComponents(individual.flatMap((c) => c.arrays)),
+      tuples: uniqueComponents(individual.flatMap((c) => c.tuples)),
+      aliases: uniqueComponents(individual.flatMap((c) => c.aliases)),
     });
     return components.dictionary;
   };
@@ -66,14 +53,18 @@ export namespace TypedHttpRouteAnalyzer {
     const cast = (
       next: {
         metadata: IMetadataSchema;
+        components: IMetadataComponents;
         validate: MetadataFactory.Validator;
       },
       from: string,
       escape: boolean,
     ): MetadataSchema => {
+      const components: MetadataComponents = MetadataComponents.from(
+        next.components,
+      );
       const metadata: MetadataSchema = MetadataSchema.from(
         next.metadata,
-        props.dictionary,
+        components.dictionary,
       );
       const metaErrors: MetadataFactory.IError[] = MetadataFactory.validate({
         options: {
@@ -192,8 +183,349 @@ export namespace TypedHttpRouteAnalyzer {
         }) satisfies ITypedHttpRoute,
     );
   };
+
+  export const routeDictionary = (
+    routes: Array<ITypedHttpRoute>,
+  ): IMetadataDictionary => {
+    renameDuplicateComponents(routes);
+    const dictionary: IMetadataDictionary = {
+      objects: new Map(),
+      aliases: new Map(),
+      arrays: new Map(),
+      tuples: new Map(),
+    };
+    for (const route of routes) {
+      for (const p of [
+        ...route.pathParameters,
+        ...route.queryParameters,
+        ...route.headerParameters,
+        ...(route.queryObject ? [route.queryObject] : []),
+        ...(route.body ? [route.body] : []),
+        ...(route.headerObject ? [route.headerObject] : []),
+      ])
+        enrollMetadata(dictionary, p.metadata);
+      for (const e of Object.values(route.exceptions))
+        enrollMetadata(dictionary, e.metadata);
+      enrollMetadata(dictionary, route.success.metadata);
+    }
+    return dictionary;
+  };
 }
 
+type ComponentKind = "objects" | "aliases" | "arrays" | "tuples";
+type ComponentType =
+  | MetadataObjectType
+  | MetadataAliasType
+  | MetadataArrayType
+  | MetadataTupleType;
+
+interface IComponentEntry {
+  kind: ComponentKind;
+  route: ITypedHttpRoute;
+  signature: string;
+  type: ComponentType;
+}
+
+const renameDuplicateComponents = (routes: ITypedHttpRoute[]): void => {
+  const entries: IComponentEntry[] = [];
+  for (const route of routes)
+    for (const metadata of routeMetadatas(route))
+      collectComponentEntries(entries, route, metadata);
+
+  const used: Set<string> = new Set(entries.map((e) => e.type!.name));
+  const groups: Map<string, IComponentEntry[]> = new Map();
+  for (const entry of entries) {
+    const key: string = `${entry.kind}:${entry.type!.name}`;
+    const group: IComponentEntry[] | undefined = groups.get(key);
+    if (group === undefined) groups.set(key, [entry]);
+    else group.push(entry);
+  }
+  for (const group of groups.values()) {
+    const signatures: Set<string> = new Set(group.map((e) => e.signature));
+    if (signatures.size <= 1) continue;
+
+    const renamed: Map<string, string> = new Map();
+    for (const entry of group) {
+      const oldName: string = entry.type!.name;
+      const next: string =
+        renamed.get(entry.signature) ??
+        (() => {
+          const prefix: string = normalizeComponentNamespace(
+            entry.route.controller.class.name,
+          );
+          const name: string = escapeComponentName(
+            used,
+            `${prefix}.${oldName}`,
+          );
+          renamed.set(entry.signature, name);
+          used.add(name);
+          return name;
+        })();
+      (entry.type as { name: string }).name = next;
+    }
+  }
+  for (const route of routes)
+    for (const metadata of routeMetadatas(route)) clearMetadataNameCache(metadata);
+};
+
+const routeMetadatas = (route: ITypedHttpRoute): MetadataSchema[] => [
+  ...[
+    ...route.pathParameters,
+    ...route.queryParameters,
+    ...route.headerParameters,
+    ...(route.queryObject ? [route.queryObject] : []),
+    ...(route.body ? [route.body] : []),
+    ...(route.headerObject ? [route.headerObject] : []),
+  ].map((p) => p.metadata),
+  ...Object.values(route.exceptions).map((e) => e.metadata),
+  route.success.metadata,
+];
+
+const collectComponentEntries = (
+  entries: IComponentEntry[],
+  route: ITypedHttpRoute,
+  metadata: MetadataSchema,
+  visited: ICollectVisited = createCollectVisited(),
+): void => {
+  if (visited.schemas.has(metadata)) return;
+  visited.schemas.add(metadata);
+
+  if (metadata.rest !== null)
+    collectComponentEntries(entries, route, metadata.rest, visited);
+  if (metadata.escaped !== null) {
+    collectComponentEntries(entries, route, metadata.escaped.original, visited);
+    collectComponentEntries(entries, route, metadata.escaped.returns, visited);
+  }
+  for (const func of metadata.functions) {
+    for (const p of func.parameters)
+      collectComponentEntries(entries, route, p.type, visited);
+    collectComponentEntries(entries, route, func.output, visited);
+  }
+  for (const set of metadata.sets)
+    collectComponentEntries(entries, route, set.value, visited);
+  for (const map of metadata.maps) {
+    collectComponentEntries(entries, route, map.key, visited);
+    collectComponentEntries(entries, route, map.value, visited);
+  }
+  for (const array of metadata.arrays)
+    if (visited.arrays.has((array.type as MetadataArrayType)) === false) {
+      visited.arrays.add((array.type as MetadataArrayType));
+      entries.push(componentEntry(route, "arrays", (array.type as MetadataArrayType)));
+      collectComponentEntries(entries, route, ((array.type as MetadataArrayType) as MetadataArrayType).value, visited);
+    }
+  for (const tuple of metadata.tuples)
+    if (visited.tuples.has((tuple.type as MetadataTupleType)) === false) {
+      visited.tuples.add((tuple.type as MetadataTupleType));
+      entries.push(componentEntry(route, "tuples", (tuple.type as MetadataTupleType)));
+      for (const elem of ((tuple.type as MetadataTupleType) as MetadataTupleType).elements)
+        collectComponentEntries(entries, route, elem, visited);
+    }
+  for (const alias of metadata.aliases)
+    if (visited.aliases.has((alias.type as MetadataAliasType)) === false) {
+      visited.aliases.add((alias.type as MetadataAliasType));
+      entries.push(componentEntry(route, "aliases", (alias.type as MetadataAliasType)));
+      collectComponentEntries(entries, route, ((alias.type as MetadataAliasType) as MetadataAliasType).value, visited);
+    }
+  for (const obj of metadata.objects)
+    if (visited.objects.has((obj.type as MetadataObjectType)) === false) {
+      visited.objects.add((obj.type as MetadataObjectType));
+      entries.push(componentEntry(route, "objects", (obj.type as MetadataObjectType)));
+      for (const p of ((obj.type as MetadataObjectType) as MetadataObjectType).properties) {
+        collectComponentEntries(entries, route, p.key, visited);
+        collectComponentEntries(entries, route, p.value, visited);
+      }
+    }
+};
+
+const componentEntry = <T extends ComponentType>(
+  route: ITypedHttpRoute,
+  kind: ComponentKind,
+  type: T,
+): IComponentEntry => ({
+  kind,
+  route,
+  signature: componentSignature(type),
+  type,
+});
+
+const componentSignature = (type: ComponentType): string =>
+  JSON.stringify(type, (key, value) =>
+    // `type` is the resolved back-reference attached by
+    // `MetadataSchema.from`; it closes a cycle on recursive schemas.
+    // `index` carries the per-route ordinal and is not part of the
+    // component's identity.
+    key === "index" || key === "type" ? undefined : value,
+  );
+
+const normalizeComponentNamespace = (name: string): string => {
+  const next: string = name.replace(/[^A-Za-z0-9_$]/g, "_");
+  return next.length ? next : "Route";
+};
+
+const escapeComponentName = (used: Set<string>, name: string): string =>
+  used.has(name) ? escapeComponentName(used, `_${name}`) : name;
+
+const clearMetadataNameCache = (
+  metadata: MetadataSchema,
+  visited: WeakSet<MetadataSchema> = new WeakSet(),
+): void => {
+  if (visited.has(metadata)) return;
+  visited.add(metadata);
+  (metadata as unknown as { name_?: string }).name_ = undefined;
+
+  if (metadata.rest !== null) clearMetadataNameCache(metadata.rest, visited);
+  if (metadata.escaped !== null) {
+    clearMetadataNameCache(metadata.escaped.original, visited);
+    clearMetadataNameCache(metadata.escaped.returns, visited);
+  }
+  for (const func of metadata.functions) {
+    for (const p of func.parameters) clearMetadataNameCache(p.type, visited);
+    clearMetadataNameCache(func.output, visited);
+  }
+  for (const set of metadata.sets) {
+    (set as unknown as { name_?: string }).name_ = undefined;
+    clearMetadataNameCache(set.value, visited);
+  }
+  for (const map of metadata.maps) {
+    (map as unknown as { name_?: string }).name_ = undefined;
+    clearMetadataNameCache(map.key, visited);
+    clearMetadataNameCache(map.value, visited);
+  }
+  for (const array of metadata.arrays) {
+    (array as unknown as { name_?: string }).name_ = undefined;
+    clearMetadataNameCache(((array.type as MetadataArrayType) as MetadataArrayType).value, visited);
+  }
+  for (const tuple of metadata.tuples) {
+    (tuple as unknown as { name_?: string }).name_ = undefined;
+    for (const elem of ((tuple.type as MetadataTupleType) as MetadataTupleType).elements)
+      clearMetadataNameCache(elem, visited);
+  }
+  for (const alias of metadata.aliases) {
+    (alias as unknown as { name_?: string }).name_ = undefined;
+    clearMetadataNameCache(((alias.type as MetadataAliasType) as MetadataAliasType).value, visited);
+  }
+  for (const obj of metadata.objects) {
+    (obj as unknown as { name_?: string }).name_ = undefined;
+    for (const p of ((obj.type as MetadataObjectType) as MetadataObjectType).properties) {
+      clearMetadataNameCache(p.key, visited);
+      clearMetadataNameCache(p.value, visited);
+    }
+  }
+};
+
+interface ICollectVisited {
+  aliases: WeakSet<MetadataAliasType>;
+  arrays: WeakSet<MetadataArrayType>;
+  objects: WeakSet<MetadataObjectType>;
+  schemas: WeakSet<MetadataSchema>;
+  tuples: WeakSet<MetadataTupleType>;
+}
+
+const createCollectVisited = (): ICollectVisited => ({
+  aliases: new WeakSet<MetadataAliasType>(),
+  arrays: new WeakSet<MetadataArrayType>(),
+  objects: new WeakSet<MetadataObjectType>(),
+  schemas: new WeakSet<MetadataSchema>(),
+  tuples: new WeakSet<MetadataTupleType>(),
+});
+
+const uniqueComponents = <T extends { name: string }>(input: T[]): T[] => {
+  const dict: Record<string, T> = {};
+  for (const elem of input) {
+    const oldbie: T | undefined = dict[elem.name];
+    if (oldbie === undefined)
+      dict[elem.name] = elem;
+    else if (
+      elem.name.includes(".") ||
+      componentScore(oldbie) < componentScore(elem)
+    )
+      dict[elem.name] = elem;
+  }
+  return Object.values(dict);
+};
+
+const componentScore = (input: unknown): number =>
+  JSON.stringify(input, (key, value) =>
+    // Resolved-reference back-edges close cycles on recursive schemas;
+    // skip them when scoring component "richness".
+    key === "type" ? undefined : value,
+  ).length;
+
+const enrollMetadata = (
+  dictionary: IMetadataDictionary,
+  metadata: MetadataSchema,
+  visited: IVisitedMetadata = createVisitedMetadata(),
+): void => {
+  if (visited.schemas.has(metadata)) return;
+  visited.schemas.add(metadata);
+
+  if (metadata.rest !== null) enrollMetadata(dictionary, metadata.rest, visited);
+  if (metadata.escaped !== null) {
+    enrollMetadata(dictionary, metadata.escaped.original, visited);
+    enrollMetadata(dictionary, metadata.escaped.returns, visited);
+  }
+  for (const func of metadata.functions) {
+    for (const p of func.parameters)
+      enrollMetadata(dictionary, p.type, visited);
+    enrollMetadata(dictionary, func.output, visited);
+  }
+  for (const set of metadata.sets)
+    enrollMetadata(dictionary, set.value, visited);
+  for (const map of metadata.maps) {
+    enrollMetadata(dictionary, map.key, visited);
+    enrollMetadata(dictionary, map.value, visited);
+  }
+  for (const array of metadata.arrays)
+    if (enroll(dictionary.arrays, (array.type as MetadataArrayType)))
+      enrollMetadata(dictionary, ((array.type as MetadataArrayType) as MetadataArrayType).value, visited);
+  for (const tuple of metadata.tuples)
+    if (enroll(dictionary.tuples, (tuple.type as MetadataTupleType)))
+      for (const elem of ((tuple.type as MetadataTupleType) as MetadataTupleType).elements)
+        enrollMetadata(dictionary, elem, visited);
+  for (const alias of metadata.aliases)
+    if (enroll(dictionary.aliases, (alias.type as MetadataAliasType)))
+      enrollMetadata(dictionary, ((alias.type as MetadataAliasType) as MetadataAliasType).value, visited);
+  for (const obj of metadata.objects)
+    if (enroll(dictionary.objects, (obj.type as MetadataObjectType)))
+      for (const p of ((obj.type as MetadataObjectType) as MetadataObjectType).properties) {
+        enrollMetadata(dictionary, p.key, visited);
+        enrollMetadata(dictionary, p.value, visited);
+      }
+};
+
+const enroll = <
+  T extends
+    | MetadataObjectType
+    | MetadataAliasType
+    | MetadataArrayType
+    | MetadataTupleType,
+>(
+  dict: Map<string, T>,
+  elem: T,
+): boolean => {
+  const oldbie: T | undefined = dict.get(elem.name);
+  if (oldbie === elem) return false;
+  if (oldbie === undefined) {
+    dict.set(elem.name, elem);
+    return true;
+  } else if (
+    elem.name.includes(".") ||
+    componentScore(oldbie) < componentScore(elem)
+  ) {
+    dict.set(elem.name, elem);
+    return true;
+  }
+  return false;
+};
+
+interface IVisitedMetadata {
+  schemas: WeakSet<MetadataSchema>;
+}
+
+const createVisitedMetadata = (): IVisitedMetadata => ({
+  schemas: new WeakSet<MetadataSchema>(),
+});
+
 const join = ({
   object,
   key,

package/src/decorators/OperationMetadata.ts

@@ -1,12 +1,26 @@
-import { IOperationMetadata } from "../transformers/IOperationMetadata";
+import { IOperationMetadata } from "../structures/IOperationMetadata";
 
+/**
+ * Carries the compile-time operation metadata the SDK / Swagger / e2e
+ * generators read through `Reflect.getMetadata("nestia/OperationMetadata")`.
+ *
+ * The `@nestia/sdk` native transform injects this decorator as a synthesized
+ * AST node, so its argument is a single JSON string literal rather than an
+ * object literal — keeping the constructed node tree minimal. The string is
+ * parsed once here at module-evaluation time. A pre-parsed `IOperationMetadata`
+ * object is still accepted for hand-written or test usage.
+ */
 export function OperationMetadata(
-  metadata: IOperationMetadata,
+  metadata: IOperationMetadata | string,
 ): MethodDecorator {
+  const parsed: IOperationMetadata =
+    typeof metadata === "string"
+      ? (JSON.parse(metadata) as IOperationMetadata)
+      : metadata;
   return function OperationMetadata(target, propertyKey, descriptor) {
     Reflect.defineMetadata(
       "nestia/OperationMetadata",
-      metadata,
+      parsed,
       target,
       propertyKey,
     );