@nestia/sdk 13.0.4 → 14.0.1

package/src/internal/legacy.ts

@@ -4,8 +4,8 @@
 // its runtime classes.
 //
 // The utilities index components, resolve references, read metadata flags
-// and precomputed fields, validate SDK policy, and compose schemas for
-// decomposed parameters whose metadata has no precomputed JSON schema.
+// and precomputed fields, validate SDK policy, and read the precomputed JSON
+// schemas, including the per-property ones decomposed parameters use.
 import type {
   IJsonSchemaCollection,
   IMetadataComponents,
@@ -53,6 +53,19 @@ export interface IReflectJsonSchema {
   version: "3.0" | "3.1";
   components: OpenApi.IComponents;
   schema: OpenApi.IJsonSchema;
+
+  /**
+   * The schema of each property of the first object type, keyed by property
+   * name and resolved against {@link components}: the property schema typia's
+   * object schema holds, without the title, description, deprecation, and
+   * readOnly an OpenAPI parameter carries in its own fields or cannot use.
+   *
+   * Baked on the resolved schema of route parameters only, for the Swagger
+   * generator to decompose a query or headers object into one parameter per
+   * property. A property typia's object schema omits (`@hidden`, `@ignore`,
+   * `@internal`, or a value with no JSON form) has no entry.
+   */
+  properties?: Record<string, OpenApi.IJsonSchema>;
 }
 
 /**
@@ -133,6 +146,39 @@ export const emptyOf = (m: IMetadataSchema): boolean =>
 export const isRequiredOf = (m: IMetadataSchema): boolean =>
   m.required && !m.optional;
 
+/**
+ * Reads a constant's value as the SDK's Go contributor writes it.
+ *
+ * JSON holds neither a bigint nor NaN or ±Infinity, so the metadata carries a
+ * bigint value as its decimal digits and a non-finite number by its name
+ * (`"Infinity"`), both as strings. `type` is the constant's type, which is its
+ * value's own, so a bigint or number constant's string is always one of those;
+ * every other value is returned as it is.
+ */
+export const decodeMetadataValue = (type: string, value: unknown): unknown =>
+  typeof value !== "string"
+    ? value
+    : type === "bigint"
+      ? BigInt(value)
+      : type === "number"
+        ? Number(value)
+        : value;
+
+/**
+ * Reads a type tag's value as the SDK's Go contributor writes it.
+ *
+ * A tag's `target` is the type it tags, not its value's: `tags.Sequence<1>` on
+ * a bigint holds a number, and `tags.Example<"Infinity">` on a number holds a
+ * string. So a value encoded as a string, a bigint's digits or a non-finite
+ * number's name, arrives with the type it stands for in `encoding`.
+ */
+export const decodeTagValue = (
+  tag: IMetadataTypeTag & { encoding?: "bigint" | "number" },
+): unknown =>
+  tag.encoding !== undefined
+    ? decodeMetadataValue(tag.encoding, tag.value)
+    : tag.value;
+
 /**
  * Equivalent of the legacy `MetadataSchema.isSoleLiteral()` method: `true` when
  * the schema represents exactly one constant literal value and nothing else.
@@ -393,22 +439,6 @@ export namespace JsonMetadataFactory {
   };
 }
 
-export namespace HttpQueryProgrammer {
-  export const validate: MetadataFactory.Validator = () => [];
-}
-
-export namespace HttpHeadersProgrammer {
-  export const validate: MetadataFactory.Validator = () => [];
-}
-
-export namespace HttpParameterProgrammer {
-  export const validate: MetadataFactory.Validator = () => [];
-}
-
-export namespace HttpFormDataProgrammer {
-  export const validate: MetadataFactory.Validator = () => [];
-}
-
 // ---------------------------------------------------------------------
 //  `JsonSchemasProgrammer.writeSchemas` — consumes the per-metadata
 //  pre-baked `jsonSchema` field the nestia transform emits.
@@ -418,12 +448,16 @@ 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.
+   * carries a baked schema whenever typia can describe the type. Metadata
+   * without one falls back to a minimal JS-side converter that reads only the
+   * atomic kinds — no type tags, template patterns, or constant annotations —
+   * so it is no substitute for the bake.
+   *
+   * The schemas and components are copies. The bake belongs to the route
+   * metadata, which every composition in the process reads, while the composer
+   * edits what it is given in place (the readonly-array emender), and so can a
+   * `SwaggerCustomizer`; handing the bake out by reference let each document
+   * inherit the previous one's edits.
    */
   export const writeSchemas = (props: {
     version: "3.0" | "3.1";
@@ -434,7 +468,7 @@ export namespace JsonSchemasProgrammer {
     for (const m of props.metadatas) {
       const baked = (m as IReflectMetadata).jsonSchema;
       if (baked !== undefined) {
-        schemas.push(baked.schema);
+        schemas.push(copy(baked.schema));
         Object.assign(
           (components.schemas ??= {}),
           baked.components.schemas ?? {},
@@ -443,14 +477,57 @@ export namespace JsonSchemasProgrammer {
         schemas.push(schemaFromMetadata(m));
       }
     }
+    // Copied once the last bake of each name has won, rather than per bake.
+    if (components.schemas !== undefined)
+      components.schemas = copy(components.schemas);
     return {
       version: props.version,
       components,
       schemas,
     } as IJsonSchemaCollection;
   };
+
+  /**
+   * Writes the schema of one property of `metadata`'s first object type, for a
+   * decomposed query or headers parameter.
+   *
+   * Reads the schema baked beside `metadata`'s own schema (see
+   * {@link IReflectJsonSchema.properties}), resolved against the same
+   * components. The schema and components are copies, for the reason
+   * {@link writeSchemas} gives. Returns `null` when that bake exists but has no
+   * entry for the property, because typia's object schema omits it, so no
+   * parameter describes it either. Only metadata the transform did not bake
+   * falls back to {@link writeSchemas} over the property value.
+   */
+  export const writeProperty = (props: {
+    version: "3.0" | "3.1";
+    metadata: IMetadataSchema;
+    key: string;
+    value: IMetadataSchema;
+  }): IJsonSchemaCollection | null => {
+    const properties: Record<string, OpenApi.IJsonSchema> | undefined = (
+      props.metadata as IReflectMetadata
+    ).jsonSchema?.properties;
+    if (properties === undefined)
+      return writeSchemas({
+        version: props.version,
+        metadatas: [props.value],
+      });
+    if (Object.prototype.hasOwnProperty.call(properties, props.key) === false)
+      return null;
+    return {
+      version: props.version,
+      components: copy(
+        (props.metadata as IReflectMetadata).jsonSchema!.components,
+      ),
+      schemas: [copy(properties[props.key]!)],
+    } as IJsonSchemaCollection;
+  };
 }
 
+/** Deep copy of baked data, which is parsed JSON, so JSON copies it exactly. */
+const copy = <T>(value: T): T => JSON.parse(JSON.stringify(value));
+
 const schemaFromMetadata = (m: IMetadataSchema): OpenApi.IJsonSchema => {
   const union: OpenApi.IJsonSchema[] = [];
   if (m.nullable) union.push({ type: "null" } as OpenApi.IJsonSchema);
@@ -459,7 +536,7 @@ const schemaFromMetadata = (m: IMetadataSchema): OpenApi.IJsonSchema => {
   for (const constant of m.constants)
     for (const value of constant.values)
       union.push({
-        const: value.value,
+        const: jsonValue(decodeMetadataValue(constant.type, value.value)),
       } as unknown as OpenApi.IJsonSchema);
   for (const tpl of m.templates) {
     union.push({ type: "string" } as OpenApi.IJsonSchema);
@@ -491,6 +568,17 @@ const schemaFromMetadata = (m: IMetadataSchema): OpenApi.IJsonSchema => {
   return { oneOf: union } as unknown as OpenApi.IJsonSchema;
 };
 
+/**
+ * A value as a JSON document holds it: the number a bigint is, and null for a
+ * non-finite number, as `JSON.stringify` writes it.
+ */
+const jsonValue = (value: unknown): unknown =>
+  typeof value === "bigint"
+    ? Number(value)
+    : typeof value === "number" && Number.isFinite(value) === false
+      ? null
+      : value;
+
 const schemaFromAtomic = (atomic: IMetadataSchema.IAtomic): unknown => {
   if (atomic.type === "boolean") return { type: "boolean" };
   if (atomic.type === "bigint" || atomic.type === "number")

package/src/structures/IOperationMetadata.ts

@@ -32,6 +32,34 @@ export namespace IOperationMetadata {
   export interface ISchema {
     components: IMetadataComponents;
     metadata: IMetadataSchema;
+
+    /**
+     * Violations of each HTTP input's wire rules, baked on the resolved schema
+     * of a route parameter only; the SDK picks the one its decorator selects.
+     */
+    http?: IHttpRules;
+  }
+
+  /**
+   * The violations of each HTTP input category's rules, which are typia's own
+   * validators except the path parameter rule typia keeps unexported and the
+   * one of a field-named `@Query("key")` or `@Headers("key")`.
+   */
+  export interface IHttpRules {
+    /** A query object: `@TypedQuery()`, `@Query()`, `@TypedQuery.Body()`. */
+    query: IError[];
+
+    /** A headers object: `@TypedHeaders()`, `@Headers()`. */
+    headers: IError[];
+
+    /** A path parameter: `@TypedParam("key")`, `@Param("key")`. */
+    param: IError[];
+
+    /** One query key or header: `@Query("key")`, `@Headers("key")`. */
+    field: IError[];
+
+    /** A multipart body: `@TypedFormData.Body()`. */
+    formData: IError[];
   }
   export interface IError {
     name: string;

package/src/structures/IReflectHttpOperationException.ts

@@ -1,4 +1,8 @@
-import { IMetadataComponents, IMetadataSchema } from "@typia/interface";
+import {
+  IMetadataComponents,
+  IMetadataSchema,
+  OpenApi,
+} from "@typia/interface";
 
 import { MetadataFactory } from "../internal/legacy";
 import { IReflectType } from "./IReflectType";
@@ -8,7 +12,8 @@ export interface IReflectHttpOperationException {
   status: number | "2XX" | "3XX" | "4XX" | "5XX";
   description: string | null;
   example?: any;
-  examples?: Record<string, any>;
+  /** Named examples, as OpenAPI Example Objects. */
+  examples?: Record<string, OpenApi.IExample>;
 
   // REFLECTED PROPERTIES
   type: IReflectType;

package/src/structures/IReflectHttpOperationParameter.ts

@@ -2,6 +2,7 @@ import {
   IJsDocTagInfo,
   IMetadataComponents,
   IMetadataSchema,
+  OpenApi,
 } from "@typia/interface";
 
 import { MetadataFactory } from "../internal/legacy";
@@ -37,9 +38,15 @@ export namespace IReflectHttpOperationParameter {
     type: IReflectType;
     metadata: IMetadataSchema;
     components: IMetadataComponents;
-    validate: MetadataFactory.Validator;
+
+    /**
+     * SDK policy checked over the metadata, for a JSON or text body. An HTTP
+     * input's wire rules are typia's instead, baked beside its metadata.
+     */
+    validate?: MetadataFactory.Validator;
     example?: any;
-    examples?: Record<string, any>;
+    /** Named examples, as OpenAPI Example Objects. */
+    examples?: Record<string, OpenApi.IExample>;
     description: string | null;
     jsDocTags: IJsDocTagInfo[];
   }

package/src/structures/IReflectHttpOperationSuccess.ts

@@ -1,4 +1,8 @@
-import { IMetadataComponents, IMetadataSchema } from "@typia/interface";
+import {
+  IMetadataComponents,
+  IMetadataSchema,
+  OpenApi,
+} from "@typia/interface";
 
 import { MetadataFactory } from "../internal/legacy";
 import { HttpResponseContentTypeUtil } from "../utils/HttpResponseContentTypeUtil";
@@ -12,7 +16,8 @@ export interface IReflectHttpOperationSuccess {
   encrypted: boolean;
   components: IMetadataComponents;
   metadata: IMetadataSchema;
-  validate: MetadataFactory.Validator;
+  validate?: MetadataFactory.Validator;
   example?: any;
-  examples?: Record<string, any>;
+  /** Named examples, as OpenAPI Example Objects. */
+  examples?: Record<string, OpenApi.IExample>;
 }

package/src/structures/ITypedHttpRoute.ts

@@ -10,6 +10,14 @@ export interface ITypedHttpRoute {
   protocol: "http";
   function: Function;
   controller: IReflectController;
+  /**
+   * Property key of the controller method.
+   *
+   * {@link name} is the SDK function's name, which the accessor analysis
+   * renames: a reserved word such as `delete` becomes `_delete`. Metadata the
+   * method's decorators define, and what names the method, read this key.
+   */
+  key: string;
   name: string;
   method: string;
   path: string;

package/src/structures/ITypedHttpRouteException.ts

@@ -1,3 +1,5 @@
+import { OpenApi } from "@typia/interface";
+
 import { MetadataSchema } from "../internal/legacy";
 import { IReflectType } from "./IReflectType";
 
@@ -6,7 +8,8 @@ export interface ITypedHttpRouteException {
   status: number | "2XX" | "3XX" | "4XX" | "5XX";
   description: string | null;
   example: any;
-  examples: Record<string, any>;
+  /** Named examples, as OpenAPI Example Objects. */
+  examples: Record<string, OpenApi.IExample>;
 
   // REFLECTED PROPERTIES
   type: IReflectType;

package/src/structures/ITypedHttpRouteParameter.ts

@@ -1,3 +1,4 @@
+import { OpenApi } from "@typia/interface";
 import { IJsDocTagInfo } from "typia";
 
 import { MetadataSchema } from "../internal/legacy";
@@ -34,7 +35,8 @@ export namespace ITypedHttpRouteParameter {
     type: IReflectType;
     metadata: MetadataSchema;
     example?: any;
-    examples?: Record<string, any>;
+    /** Named examples, as OpenAPI Example Objects. */
+    examples?: Record<string, OpenApi.IExample>;
     description: string | null;
     jsDocTags: IJsDocTagInfo[];
   }

package/src/structures/ITypedHttpRouteSuccess.ts

@@ -1,3 +1,5 @@
+import { OpenApi } from "@typia/interface";
+
 import { MetadataSchema } from "../internal/legacy";
 import { HttpResponseContentTypeUtil } from "../utils/HttpResponseContentTypeUtil";
 import { IReflectType } from "./IReflectType";
@@ -10,7 +12,8 @@ export interface ITypedHttpRouteSuccess {
   encrypted: boolean;
   metadata: MetadataSchema;
   example?: any;
-  examples?: Record<string, any>;
+  /** Named examples, as OpenAPI Example Objects. */
+  examples?: Record<string, OpenApi.IExample>;
   setHeaders: Array<
     | { type: "setter"; source: string; target?: string }
     | { type: "assigner"; source: string }

package/src/structures/ITypedWebSocketRoute.ts

@@ -8,6 +8,14 @@ import { ITypedWebSocketRouteParameter } from "./ITypedWebSocketRouteParameter";
 export interface ITypedWebSocketRoute {
   protocol: "websocket";
   controller: IReflectController;
+  /**
+   * Property key of the controller method.
+   *
+   * {@link name} is the SDK function's name, which the accessor analysis
+   * renames: a reserved word such as `delete` becomes `_delete`. Metadata the
+   * method's decorators define, and what names the method, read this key.
+   */
+  key: string;
   name: string;
   path: string;
   accessor: string[];

package/src/utils/SourceFinder.ts

@@ -28,7 +28,7 @@ export namespace SourceFinder {
           closure(path.resolve(pattern));
           continue;
         }
-        for (const file of await _Glob(pattern)) {
+        for (const file of await expand(pattern)) {
           const stats: fs.Stats = await fs.promises.stat(file);
           if (stats.isDirectory() === true)
             await iterate(filter)(closure)(file);
@@ -51,9 +51,30 @@ export namespace SourceFinder {
       }
     };
 
-  const _Glob = async (pattern: string): Promise<string[]> => {
-    const matches = await glob(pattern);
-    return matches.map((str) => path.resolve(str));
+  /**
+   * Files and directories a path or glob pattern names.
+   *
+   * An existing path is taken literally, whatever characters it holds, as a
+   * directory such as `app [v2]` would otherwise read as a character class. For
+   * a pattern, the longest existing ancestor is the literal base and only the
+   * rest is globbed, with `/` separators, since glob reads a Windows backslash
+   * as an escape.
+   */
+  export const expand = async (pattern: string): Promise<string[]> => {
+    const absolute: string = path.resolve(pattern);
+    if (fs.existsSync(absolute)) return [absolute];
+    let base: string = absolute;
+    while (fs.existsSync(base) === false) {
+      const parent: string = path.dirname(base);
+      if (parent === base) return [];
+      base = parent;
+    }
+    const rest: string = path
+      .relative(base, absolute)
+      .split(path.sep)
+      .join("/");
+    const matches: string[] = await glob(rest, { cwd: base });
+    return matches.map((str) => path.resolve(base, str));
   };
 
   const _Is_file = (pattern: string): boolean =>

package/src/utils/VersioningStrategy.ts

@@ -8,21 +8,36 @@ export namespace VersioningStrategy {
   ): Array<string | typeof VERSION_NEUTRAL> =>
     value === undefined ? [] : Array.isArray(value) ? value : [value];
 
+  /**
+   * Version path segments of a route, resolved as NestJS resolves them: the
+   * method's versions, else the controller's, else the default version, and no
+   * version at all is the unversioned path.
+   *
+   * The controller's and the method's versions were joined, so a method
+   * overriding its controller's version was also described at the controller's,
+   * and a route with no version and no default got no path at all (#1735).
+   */
   export const merge =
     (project: Omit<INestiaProject, "config">) =>
-    (values: Array<string | typeof VERSION_NEUTRAL>): string[] => {
-      if (project.input.versioning === undefined) return [""];
-      const set: Set<string | typeof VERSION_NEUTRAL> = new Set(values);
-      const array: Array<string | typeof VERSION_NEUTRAL> =
-        set.size === 0
-          ? cast(project.input.versioning?.defaultVersion)
-          : Array.from(set);
-      return !!array?.length
-        ? array.map((x) =>
-            typeof x === "symbol"
-              ? ""
-              : `${project.input.versioning!.prefix}${x}`,
+    (props: {
+      controller: Array<string | typeof VERSION_NEUTRAL> | undefined;
+      method: Array<string | typeof VERSION_NEUTRAL> | undefined;
+    }): string[] => {
+      const versioning = project.input.versioning;
+      if (versioning === undefined) return [""];
+      const chosen: Array<string | typeof VERSION_NEUTRAL> = props.method
+        ?.length
+        ? props.method
+        : props.controller?.length
+          ? props.controller
+          : cast(versioning.defaultVersion);
+      const unique: Array<string | typeof VERSION_NEUTRAL> = [
+        ...new Set(chosen),
+      ];
+      return unique.length
+        ? unique.map((x) =>
+            typeof x === "symbol" ? "" : `${versioning.prefix}${x}`,
           )
-        : [];
+        : [""];
     };
 }

package/lib/validators/HttpHeadersValidator.d.ts

@@ -1,11 +0,0 @@
-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.
- */
-export declare namespace HttpHeadersValidator {
-    const validate: MetadataFactory.Validator;
-}

package/lib/validators/HttpHeadersValidator.js

@@ -1,15 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.HttpHeadersValidator = void 0;
-/**
- * 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.
- */
-var HttpHeadersValidator;
-(function (HttpHeadersValidator) {
-    HttpHeadersValidator.validate = () => [];
-})(HttpHeadersValidator || (exports.HttpHeadersValidator = HttpHeadersValidator = {}));
-//# sourceMappingURL=HttpHeadersValidator.js.map

package/lib/validators/HttpHeadersValidator.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"HttpHeadersValidator.js","sourceRoot":"","sources":["../../src/validators/HttpHeadersValidator.ts"],"names":[],"mappings":";;;AAEA;;;;;;GAMG;AACH,IAAiB,oBAAoB,CAEpC;AAFD,WAAiB,oBAAoB;IACtB,6BAAQ,GAA8B,GAAG,EAAE,CAAC,EAAE,CAAC;AAC9D,CAAC,EAFgB,oBAAoB,aAApB,oBAAoB,GAApB,oBAAoB,QAEpC"}

package/lib/validators/HttpQueryValidator.d.ts

@@ -1,10 +0,0 @@
-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.
- */
-export declare namespace HttpQueryValidator {
-    const validate: MetadataFactory.Validator;
-}

package/lib/validators/HttpQueryValidator.js

@@ -1,14 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.HttpQueryValidator = void 0;
-/**
- * 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.
- */
-var HttpQueryValidator;
-(function (HttpQueryValidator) {
-    HttpQueryValidator.validate = () => [];
-})(HttpQueryValidator || (exports.HttpQueryValidator = HttpQueryValidator = {}));
-//# sourceMappingURL=HttpQueryValidator.js.map

package/lib/validators/HttpQueryValidator.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"HttpQueryValidator.js","sourceRoot":"","sources":["../../src/validators/HttpQueryValidator.ts"],"names":[],"mappings":";;;AAEA;;;;;GAKG;AACH,IAAiB,kBAAkB,CAElC;AAFD,WAAiB,kBAAkB;IACpB,2BAAQ,GAA8B,GAAG,EAAE,CAAC,EAAE,CAAC;AAC9D,CAAC,EAFgB,kBAAkB,aAAlB,kBAAkB,GAAlB,kBAAkB,QAElC"}

package/src/validators/HttpHeadersValidator.ts

@@ -1,12 +0,0 @@
-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.
- */
-export namespace HttpHeadersValidator {
-  export const validate: MetadataFactory.Validator = () => [];
-}

package/src/validators/HttpQueryValidator.ts

@@ -1,11 +0,0 @@
-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.
- */
-export namespace HttpQueryValidator {
-  export const validate: MetadataFactory.Validator = () => [];
-}