@nestia/sdk 14.0.1 → 14.0.3

package/src/generates/internal/SwaggerDescriptionComposer.ts

@@ -1,6 +1,28 @@
 import { IJsDocTagInfo } from "typia";
 
+/**
+ * Composes the title or summary and the description of a document member from
+ * its comment.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace reads the explicit tag, and otherwise takes the first line of the description when it is a sentence.
+ * @evidence contracts/common.md#clear-and-simple-design Three functions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The tag has priority over the derived text.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SwaggerDescriptionComposer composes OpenAPI data; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SwaggerDescriptionComposer {
+  /**
+   * Returns the `summary` or `title` and the `description` of a member.
+   *
+   * The explicit tag is the summary; otherwise the description's first line,
+   * without its final period, when that line ends with one.
+   *
+   * @evidence contracts/common.md#principled-implementation The derived summary is only ever a whole sentence, and a description that is not a sentence has none.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The kind is the caller's choice.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SwaggerDescriptionComposer.compose composes OpenAPI data; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const compose = <Kind extends "summary" | "title">(props: {
     description: string | null;
     jsDocTags: IJsDocTagInfo[];
@@ -28,6 +50,17 @@ export namespace SwaggerDescriptionComposer {
     } as any;
   };
 
+  /**
+   * Returns the first text part of the first JSDoc tag with the name and a text
+   * array, matching the parameter name when one is given. Returns undefined
+   * when that selected tag has no text part.
+   *
+   * @evidence contracts/common.md#principled-implementation A matching tag with a text array is selected, then its first text part is returned if present.
+   * @evidence contracts/common.md#clear-and-simple-design One search.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It reads the tags.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SwaggerDescriptionComposer.descriptionFromJsDocTag composes OpenAPI data; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const descriptionFromJsDocTag = (props: {
     jsDocTags: IJsDocTagInfo[];
     tag: string;
@@ -48,6 +81,15 @@ export namespace SwaggerDescriptionComposer {
       : undefined;
   };
 
+  /**
+   * Returns the text of every JSDoc tag with the name and a non-empty text.
+   *
+   * @evidence contracts/common.md#principled-implementation The tags are filtered, then read.
+   * @evidence contracts/common.md#clear-and-simple-design One filter and one map.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts An empty text is not returned.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SwaggerDescriptionComposer.getJsDocTexts composes OpenAPI data; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const getJsDocTexts = (props: {
     jsDocTags: IJsDocTagInfo[];
     name: string;
@@ -60,5 +102,9 @@ export namespace SwaggerDescriptionComposer {
           tag.text.find((elem) => elem.kind === "text" && elem.text.length) !==
             undefined,
       )
-      .map((tag) => tag.text!.find((elem) => elem.kind === "text")!.text);
+      .map(
+        (tag) =>
+          tag.text!.find((elem) => elem.kind === "text" && elem.text.length)!
+            .text,
+      );
 }

package/src/generates/internal/SwaggerOperationComposer.ts

@@ -8,7 +8,25 @@ import { SwaggerDescriptionComposer } from "./SwaggerDescriptionComposer";
 import { SwaggerOperationParameterComposer } from "./SwaggerOperationParameterComposer";
 import { SwaggerOperationResponseComposer } from "./SwaggerOperationResponseComposer";
 
+/**
+ * Composes the operation object of a route.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace collects tags, security, parameters, and responses.
+ * @evidence contracts/common.md#clear-and-simple-design One function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The document's own tag list is edited only by adding.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SwaggerOperationComposer composes OpenAPI data; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SwaggerOperationComposer {
+  /**
+   * Returns the operation of a route, registering its tags in the document.
+   *
+   * @evidence contracts/common.md#principled-implementation The tags are the controller's, the route's, and the `@tag` comments, each registered once with the first description, and the security is merged from the controller, the route, and the `@security` comments.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts A tag's description is never overwritten.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SwaggerOperationComposer.compose composes OpenAPI data; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const compose = (props: {
     config: Omit<INestiaConfig.ISwaggerConfig, "output">;
     document: OpenApi.IDocument;

package/src/generates/internal/SwaggerOperationParameterComposer.ts

@@ -13,9 +13,27 @@ import {
 } from "../../internal/legacy";
 import { ITypedHttpRouteParameter } from "../../structures/ITypedHttpRouteParameter";
 import { SwaggerDescriptionComposer } from "./SwaggerDescriptionComposer";
-import { SwaggerReadonlyArrayEmender } from "./SwaggerReadonlyArrayEmender";
 
+/**
+ * Composes the parameters and the request body of an operation.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace writes each parameter where the router reads it, decomposes a query or headers object into its keys where the format needs it, and fits a body into what Swagger 2.0 can hold.
+ * @evidence contracts/common.md#clear-and-simple-design Two public functions over private helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The 2.0 restrictions are applied by dedicated helpers.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SwaggerOperationParameterComposer composes OpenAPI data; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SwaggerOperationParameterComposer {
+  /**
+   * The inputs of a parameter's composition: the configuration, the document,
+   * the route's comment tags, the parameter, and its schema.
+   *
+   * @evidence contracts/common.md#principled-implementation The record is the argument of every composer.
+   * @evidence contracts/common.md#clear-and-simple-design A flat record.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SwaggerOperationParameterComposer.IProps composes OpenAPI data; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export interface IProps<Parameter extends ITypedHttpRouteParameter> {
     config: Omit<INestiaConfig.ISwaggerConfig, "output">;
     document: OpenApi.IDocument;
@@ -24,6 +42,15 @@ export namespace SwaggerOperationParameterComposer {
     parameter: Parameter;
   }
 
+  /**
+   * Returns the parameter objects of a path, query, or header parameter.
+   *
+   * @evidence contracts/common.md#principled-implementation A query object or a headers object is decomposed into one parameter per property where the format needs it.
+   * @evidence contracts/common.md#clear-and-simple-design One dispatch by category.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The category decides the location.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SwaggerOperationParameterComposer.compose composes OpenAPI data; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const compose = (
     props: IProps<ITypedHttpRouteParameter>,
   ): OpenApi.IOperation.IParameter[] =>
@@ -35,6 +62,17 @@ export namespace SwaggerOperationParameterComposer {
           ? query({ ...props, parameter: props.parameter })
           : header({ ...props, parameter: props.parameter });
 
+  /**
+   * Returns the request body of a route, or `undefined`.
+   *
+   * Swagger 2.0 receives the form a body parameter can hold.
+   *
+   * @evidence contracts/common.md#principled-implementation The description carries the encryption warning, and the flag is written for the versions that can hold it.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The 2.0 conversion is separate.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SwaggerOperationParameterComposer.body composes OpenAPI data; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const body = (
     props: IProps<ITypedHttpRouteParameter.IBody>,
   ): OpenApi.IOperation.IRequestBody | undefined => {
@@ -222,14 +260,9 @@ export namespace SwaggerOperationParameterComposer {
             value: p.value,
           });
         if (json === null) return null;
-        SwaggerReadonlyArrayEmender.emend({
-          components: json.components,
-          schema: json.schemas[0],
-          metadata: p.value,
-        });
         // Only what the document lacks: the parameter's own schema already
-        // brought every component its properties reach, emended for readonly
-        // arrays, and this copy is not.
+        // brought every component its properties reach from the native bake.
+        // Existing document components take precedence over this copy.
         props.document.components ??= {};
         props.document.components.schemas ??= {};
         for (const [name, schema] of Object.entries(

package/src/generates/internal/SwaggerOperationResponseComposer.ts

@@ -7,7 +7,26 @@ import { ITypedHttpRoute } from "../../structures/ITypedHttpRoute";
 import { StringUtil } from "../../utils/StringUtil";
 import { SwaggerDescriptionComposer } from "./SwaggerDescriptionComposer";
 
+/**
+ * Composes the responses of an operation.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace writes the responses of the exceptions, of the `@throws` comments, and of the success, and shares the media type of a 2.0 operation.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Every response goes through one content writer.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SwaggerOperationResponseComposer composes OpenAPI data; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SwaggerOperationResponseComposer {
+  /**
+   * Returns the responses of a route, by status: the declared exceptions, the
+   * `@throws` comments, and the success.
+   *
+   * @evidence contracts/common.md#principled-implementation Decorated exceptions retain their schemas and gain a missing description from comments. The success response replaces any entry at its own status. A 2.0 document omits named examples and shares the success body's media type where present.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The sources are ordered.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SwaggerOperationResponseComposer.compose composes OpenAPI data; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const compose = (props: {
     config: Omit<INestiaConfig.ISwaggerConfig, "output">;
     schema: (metadata: MetadataSchema) => OpenApi.IJsonSchema | undefined;

package/src/internal/legacy-augmentation.d.ts

@@ -0,0 +1,16 @@
+// Module augmentation: typia v13's `IReference` carries only a symbolic
+// `name` + tags, but `MetadataSchema.from(plain, dictionary)` mutates
+// each reference to also hold the resolved target type so downstream
+// sdk code can keep its `ref.type!.value` / `ref.type!.elements` access
+// pattern from the legacy `@typia/core` `MetadataArray` / `MetadataTuple`
+// classes. The field is optional because it is only populated after a
+// `MetadataSchema.from` walk against a dictionary.
+export {};
+
+declare module "@typia/interface" {
+  namespace IMetadataSchema {
+    interface IReference {
+      type?: IArrayType | ITupleType | IObjectType | IAliasType;
+    }
+  }
+}