@nestia/sdk 14.0.0 → 14.0.2

package/src/generates/internal/ImportDictionary.ts

@@ -11,6 +11,16 @@ import { ImportAnalyzer } from "../../analyses/ImportAnalyzer";
 import { IReflectImport } from "../../structures/IReflectImport";
 import { FilePrinter } from "./FilePrinter";
 
+/**
+ * The imports of one generated file, merged by module and kind, and printed as
+ * import declarations.
+ *
+ * @evidence contracts/common.md#principled-implementation An import is keyed by its module, its type-only flag, and its default or namespace name, so the same import is one declaration whose named bindings are collected in order.
+ * @evidence contracts/common.md#clear-and-simple-design One class with a hash map of components, and private helpers for the paths.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The keys are equal exactly when the declarations can be merged.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidence contracts/portability.md#os-neutral-implementation Source path spelling uses Node path.resolve and relative imports use path.relative followed by native-separator conversion to forward slashes. Package registration uses a node_modules marker; normalization is lexical, not symlink or filesystem-case canonicalization.
+ */
 export class ImportDictionary {
   private readonly components_: HashMap<ICompositeKey, ICompositeValue> =
     new HashMap(
@@ -24,10 +34,32 @@ export class ImportDictionary {
 
   public constructor(public readonly file: string) {}
 
+  /**
+   * Reports whether the file has no import.
+   *
+   * @evidence contracts/common.md#principled-implementation The dictionary is empty exactly when no component was registered.
+   * @evidence contracts/common.md#clear-and-simple-design One call.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It reads the map.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ImportDictionary.prototype.empty composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   public empty(): boolean {
     return this.components_.empty();
   }
 
+  /**
+   * Registers the imports a route's declarations need, merged by file, as
+   * type-only imports.
+   *
+   * The `WebSocketAcceptor` element is skipped, because the SDK refers to it
+   * through `tgrid`.
+   *
+   * @evidence contracts/common.md#principled-implementation Each namespace, default, and named import is registered under its alias so a name resolves to the same local binding.
+   * @evidence contracts/common.md#clear-and-simple-design One loop over the merged imports.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The skipped element is the one binding that the generated code supplies itself.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidence contracts/portability.md#os-neutral-implementation Source path spelling uses Node path.resolve and relative imports use path.relative followed by native-separator conversion to forward slashes. Package registration uses a node_modules marker; normalization is lexical, not symlink or filesystem-case canonicalization.
+   */
   public declarations(imports: IReflectImport[]): void {
     imports = ImportAnalyzer.merge(imports);
     for (const imp of imports) {
@@ -59,6 +91,63 @@ export class ImportDictionary {
     }
   }
 
+  /**
+   * Every identifier the imports bind in the file.
+   *
+   * @evidence contracts/common.md#principled-implementation The namespace, the default, and each named local are collected, so a caller can see what a route name would shadow.
+   * @evidence contracts/common.md#clear-and-simple-design One loop.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It reads the components without changing them.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ImportDictionary.prototype.locals composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
+  public locals(): string[] {
+    const output: string[] = [];
+    for (const { second: c } of this.components_) {
+      if (c.asterisk !== null) output.push(c.asterisk);
+      if (c.default !== null) output.push(c.default);
+      for (const { first: local } of c.elements) output.push(local);
+    }
+    return output;
+  }
+
+  /**
+   * Returns registered bindings in the route import representation, retaining
+   * normalized module paths and local-to-exported aliases. The route emitter
+   * consumes these as type-only declarations.
+   *
+   * @evidence contracts/common.md#principled-implementation The projection reads the same normalized module keys and local-to-exported binding map used by toStatements, so a structural type writer and its route retain the same imports.
+   * @evidence contracts/common.md#clear-and-simple-design One projection over existing registrations.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No AST parsing or second import policy reconstructs the bindings.
+   * @evidence contracts/common.md#meaningful-documentation Documents normalized paths, alias direction and the route's type-only consumption.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ImportDictionary.prototype.toImports composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
+  public toImports(): IReflectImport[] {
+    return Array.from(this.components_).map(({ second: component }) => {
+      const bindings = Array.from(component.elements);
+      const aliases = Object.fromEntries(
+        bindings
+          .filter(({ first, second }) => first !== second)
+          .map(({ first, second }) => [first, second]),
+      );
+      return {
+        file: component.file,
+        asterisk: component.asterisk,
+        default: component.default,
+        elements: bindings.map(({ first }) => first),
+        ...(Object.keys(aliases).length ? { elementAliases: aliases } : {}),
+      };
+    });
+  }
+
+  /**
+   * Registers an import of a package and returns the local name it binds.
+   *
+   * @evidence contracts/common.md#principled-implementation The file is placed under `node_modules`, so the printer emits the bare package specifier.
+   * @evidence contracts/common.md#clear-and-simple-design One delegation.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It shares the registration of `internal`.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidence contracts/portability.md#os-neutral-implementation Source path spelling uses Node path.resolve and relative imports use path.relative followed by native-separator conversion to forward slashes. Package registration uses a node_modules marker; normalization is lexical, not symlink or filesystem-case canonicalization.
+   */
   public external(props: ImportDictionary.IProps): string {
     const file: string = `node_modules/${props.file}`;
     return this.internal({
@@ -67,6 +156,15 @@ export class ImportDictionary {
     });
   }
 
+  /**
+   * Registers an import of a source file and returns the local name it binds.
+   *
+   * @evidence contracts/common.md#principled-implementation The path is normalized and its source extension removed, so equal normalized module spellings share a component, and a named binding is stored under its local name. Symlink and filesystem-case identity are not canonicalized.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The result is the alias when there is one.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidence contracts/portability.md#os-neutral-implementation Source path spelling uses Node path.resolve and relative imports use path.relative followed by native-separator conversion to forward slashes. Package registration uses a node_modules marker; normalization is lexical, not symlink or filesystem-case canonicalization.
+   */
   public internal(props: ImportDictionary.IProps): string {
     const file: string = normalize(trimSourceExtension(props.file));
     const key: ICompositeKey = {
@@ -86,6 +184,16 @@ export class ImportDictionary {
     return props.type === "element" ? (props.alias ?? props.name) : props.name;
   }
 
+  /**
+   * Returns the import declarations, packages first and files after them,
+   * sorted by module, with paths relative to the output directory.
+   *
+   * @evidence contracts/common.md#principled-implementation The package paths are cut at their last `node_modules`, and a file path is made relative with forward slashes, so the output does not depend on the platform.
+   * @evidence contracts/common.md#clear-and-simple-design One function over one filter helper.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Both groups are sorted and separated by one empty line.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidence contracts/portability.md#os-neutral-implementation Source path spelling uses Node path.resolve and relative imports use path.relative followed by native-separator conversion to forward slashes. Package registration uses a node_modules marker; normalization is lexical, not symlink or filesystem-case canonicalization.
+   */
   public toStatements(outDir: string): Node[] {
     outDir = path.resolve(outDir);
 
@@ -120,7 +228,7 @@ export class ImportDictionary {
           container.push(
             factory.createImportDeclaration(
               undefined,
-              this.toImportClaude(c),
+              this.toImportClause(c),
               factory.createStringLiteral(c.file),
             ),
           );
@@ -135,7 +243,7 @@ export class ImportDictionary {
     ];
   }
 
-  private toImportClaude(c: ICompositeValue): ImportClause {
+  private toImportClause(c: ICompositeValue): ImportClause {
     // A namespace binding cannot carry a per-binding `type` modifier, so the
     // type-only flag goes on the clause itself (`import type * as X`) —
     // generated SDK code references DTO namespaces only in type positions.
@@ -167,6 +275,16 @@ export class ImportDictionary {
   }
 }
 export namespace ImportDictionary {
+  /**
+   * One import to register: its kind, its module, its name, an optional alias,
+   * and whether it is type-only.
+   *
+   * @evidence contracts/common.md#principled-implementation The record is the argument of both registrations.
+   * @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.
+   * @evidence contracts/portability.md#os-neutral-implementation Source path spelling uses Node path.resolve and relative imports use path.relative followed by native-separator conversion to forward slashes. Package registration uses a node_modules marker; normalization is lexical, not symlink or filesystem-case canonicalization.
+   */
   export interface IProps {
     type: "default" | "element" | "asterisk";
     file: string;

package/src/generates/internal/SdkAliasCollection.ts

@@ -16,8 +16,28 @@ import { FilePrinter } from "./FilePrinter";
 import { ImportDictionary } from "./ImportDictionary";
 import { SdkHttpParameterProgrammer } from "./SdkHttpParameterProgrammer";
 import { SdkTypeProgrammer } from "./SdkTypeProgrammer";
+import type { SdkWebSocketParameterProgrammer } from "./SdkWebSocketParameterProgrammer";
 
+/**
+ * Type nodes of the SDK: the named types of routes, and the request and
+ * response aliases.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace builds each type as the syntax tree that the printer writes, from the reflected names or from the metadata when `clone` is on.
+ * @evidence contracts/common.md#clear-and-simple-design Several small builders.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The builders depend on the project configuration for the choice of source.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkAliasCollection composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SdkAliasCollection {
+  /**
+   * Returns the type reference of a reflected type, with its type arguments.
+   *
+   * @evidence contracts/common.md#principled-implementation The arguments are built recursively.
+   * @evidence contracts/common.md#clear-and-simple-design One recursion.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It writes the name as reflected.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkAliasCollection.name composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const name = ({ type }: { type: IReflectType }): TypeNode =>
     factory.createTypeReferenceNode(
       type.name,
@@ -26,20 +46,58 @@ export namespace SdkAliasCollection {
         : undefined,
     );
 
+  /**
+   * Returns the type of one chunk of a binary response:
+   * `Uint8Array<ArrayBufferLike>`.
+   *
+   * @evidence contracts/common.md#principled-implementation The chunk type of the platform stream is a byte array.
+   * @evidence contracts/common.md#clear-and-simple-design One node.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The type is fixed.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkAliasCollection.binaryChunk composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const binaryChunk = (): TypeNode =>
     factory.createTypeReferenceNode("Uint8Array", [
       factory.createTypeReferenceNode("ArrayBufferLike"),
     ]);
 
+  /**
+   * Returns the type of a binary response: `ReadableStream` of its chunks.
+   *
+   * @evidence contracts/common.md#principled-implementation A binary response is streamed, not read into memory.
+   * @evidence contracts/common.md#clear-and-simple-design One node.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The chunk type is shared.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkAliasCollection.binaryResponse composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const binaryResponse = (): TypeNode =>
     factory.createTypeReferenceNode("ReadableStream", [binaryChunk()]);
 
+  /**
+   * Returns the type node of a metadata.
+   *
+   * @evidence contracts/common.md#principled-implementation The metadata is written by the type programmer, so the result is the DTO the clone declares.
+   * @evidence contracts/common.md#clear-and-simple-design One delegation.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It shares the type writer.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkAliasCollection.from composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const from =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
     (metadata: MetadataSchema): TypeNode =>
       SdkTypeProgrammer.write(project)(importer)(metadata) as TypeNode;
 
+  /**
+   * Returns the object type of a route's keyword parameters, each with the
+   * description of its parameter or its `@param` tag.
+   *
+   * @evidence contracts/common.md#principled-implementation The entries are the route's path, query, and body parameters, optional where the metadata is, without prefix.
+   * @evidence contracts/common.md#clear-and-simple-design One map over the entries.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts A parameter with a description carries it as a comment.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkAliasCollection.httpProps composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const httpProps =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
@@ -82,7 +140,20 @@ export namespace SdkAliasCollection {
           .flat(),
       );
 
-  export const websocketProps = (route: ITypedWebSocketRoute): TypeNode =>
+  /**
+   * Returns the object type of a WebSocket route's keyword parameters: its path
+   * parameters, its query, and its provider.
+   *
+   * @evidence contracts/common.md#principled-implementation The keys are the names decided by the parameter programmer, so the type and the function agree.
+   * @evidence contracts/common.md#clear-and-simple-design One literal.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The names are shared.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkAliasCollection.websocketProps composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
+  export const websocketProps = (
+    route: ITypedWebSocketRoute,
+    names: SdkWebSocketParameterProgrammer.INames,
+  ): TypeNode =>
     factory.createTypeLiteralNode([
       ...route.pathParameters.map((p) =>
         factory.createPropertySignature(
@@ -96,7 +167,7 @@ export namespace SdkAliasCollection {
         ? [
             factory.createPropertySignature(
               undefined,
-              "query",
+              names.query,
               undefined,
               factory.createTypeReferenceNode("Query"),
             ),
@@ -104,12 +175,22 @@ export namespace SdkAliasCollection {
         : []),
       factory.createPropertySignature(
         undefined,
-        "provider",
+        names.provider,
         undefined,
         factory.createTypeReferenceNode("Provider"),
       ),
     ]);
 
+  /**
+   * Returns the type of a route's headers: its reflected name, or the
+   * metadata's type under `clone`.
+   *
+   * @evidence contracts/common.md#principled-implementation The source follows the `clone` setting.
+   * @evidence contracts/common.md#clear-and-simple-design One conditional.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The choice is made on one flag.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkAliasCollection.headers composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const headers =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
@@ -129,6 +210,16 @@ export namespace SdkAliasCollection {
       );
     };
 
+  /**
+   * Returns the type of a route's query: its metadata under `clone`, otherwise
+   * its reflected type wrapped in Resolved unless primitive conversion is off.
+   *
+   * @evidence contracts/common.md#principled-implementation Clone mode uses the resolved metadata graph; source mode uses the declared type with the configured Resolved conversion.
+   * @evidence contracts/common.md#clear-and-simple-design One conditional.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The choice is made on one flag.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkAliasCollection.query composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const query =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
@@ -148,6 +239,16 @@ export namespace SdkAliasCollection {
       );
     };
 
+  /**
+   * Returns the type of a route's body: a form data input for a multipart body,
+   * and otherwise the reflected name or the metadata's type under `clone`.
+   *
+   * @evidence contracts/common.md#principled-implementation The multipart body is an input of files and fields, not the declared class.
+   * @evidence contracts/common.md#clear-and-simple-design One conditional.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The cases are the content types.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkAliasCollection.body composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const body =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
@@ -176,14 +277,28 @@ export namespace SdkAliasCollection {
       );
     };
 
+  /**
+   * Returns the type of a route's output: the success and every exception as a
+   * union of `IPropagation` members, or the success body alone when propagation
+   * is off.
+   *
+   * @evidence contracts/common.md#principled-implementation Status keys retain their declared numeric or range spelling for IPropagation to expand. Source success types follow their content type, while declared exceptions use JSON Primitive conversion independently of the success media type; primitive:false preserves declared source types.
+   * @evidence contracts/common.md#clear-and-simple-design One function of two branches.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The exceptions are the declared ones.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkAliasCollection.response composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const response =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
     (route: ITypedHttpRoute): TypeNode => {
-      const schema = (p: {
-        metadata: MetadataSchema;
-        type: IReflectType;
-      }): TypeNode =>
+      const schema = (
+        p: {
+          metadata: MetadataSchema;
+          type: IReflectType;
+        },
+        json: boolean,
+      ): TypeNode =>
         sizeOf(p.metadata) === 0
           ? TypeFactory.keyword("void")
           : project.config.clone === true
@@ -194,11 +309,7 @@ export namespace SdkAliasCollection {
                     file: "typia",
                     declaration: true,
                     type: "element",
-                    name:
-                      route.success.contentType === "application/json" ||
-                      route.success.encrypted === true
-                        ? "Primitive"
-                        : "Resolved",
+                    name: json ? "Primitive" : "Resolved",
                   }),
                   [name(p)],
                 )
@@ -206,7 +317,11 @@ export namespace SdkAliasCollection {
       const success: TypeNode =
         route.success.binary === true
           ? binaryResponse()
-          : schema(route.success);
+          : schema(
+              route.success,
+              route.success.contentType === "application/json" ||
+                route.success.encrypted === true,
+            );
       if (project.config.propagate !== true) return success;
 
       const branches: IBranch[] = [
@@ -218,7 +333,7 @@ export namespace SdkAliasCollection {
         },
         ...Object.entries(route.exceptions).map(([status, value]) => ({
           status,
-          type: schema(value),
+          type: schema(value, true),
         })),
       ];
       return factory.createTypeReferenceNode(
@@ -233,7 +348,10 @@ export namespace SdkAliasCollection {
             branches.map((b) =>
               factory.createPropertySignature(
                 undefined,
-                factory.createNumericLiteral(b.status),
+                // a status range like "4XX" is no numeric literal
+                /^\d+$/.test(b.status)
+                  ? factory.createNumericLiteral(b.status)
+                  : factory.createStringLiteral(b.status),
                 undefined,
                 b.type,
               ),
@@ -250,6 +368,17 @@ export namespace SdkAliasCollection {
       );
     };
 
+  /**
+   * Returns the type of the success body: a stream for a binary response, the
+   * reflected type for a plain one, and its primitive form for a JSON
+   * response.
+   *
+   * @evidence contracts/common.md#principled-implementation The route's metadata decides between the branches.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The branches are the response kinds.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkAliasCollection.responseBody composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const responseBody =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>