tsoa-next 8.2.0 → 8.2.1-dev.65.5d3e3033

package/README.MD

@@ -28,7 +28,7 @@ Where historical release notes or migration references still point upstream, the
 ## Goal
 
 - TypeScript controllers and models as the single source of truth for your API
-- A valid OpenAPI (formerly Swagger) spec (2.0 or 3.0 if you choose 😍) is generated from your controllers and models, including:
+- A valid OpenAPI (formerly Swagger) 2.0, 3.0, or 3.1 spec is generated from your controllers and models, including:
   - Paths (e.g. GET /users)
   - Definitions based on TypeScript interfaces (models)
   - Parameters/model properties marked as required or optional based on TypeScript (e.g. myProperty?: string is optional in the OpenAPI spec)
@@ -44,8 +44,8 @@ Where historical release notes or migration references still point upstream, the
 - Use jsdoc for pure text metadata (e.g. endpoint descriptions)
 - Minimize boilerplate
 - Models are best represented by interfaces (pure data structures), but can also be represented by classes
-- Runtime validation of tsoa-next should behave as closely as possible to the specifications that the generated OpenAPI 2/3 schema describes. Any differences in validation logic are clarified by logging warnings during the generation of the OpenAPI Specification (OAS) and/or the routes.
-  - Please note that by enabling OpenAPI 3 you minimize the chances of divergent validation logic since OpenAPI 3 has a more expressive schema syntax.
+- Runtime validation of tsoa-next should behave as closely as possible to the specifications that the generated OpenAPI schema describes. Any differences in validation logic are clarified by logging warnings during the generation of the OpenAPI Specification (OAS) and/or the routes.
+  - Please note that by enabling OpenAPI 3.0 or 3.1 you minimize the chances of divergent validation logic since the newer schema shapes are more expressive than OpenAPI 2.0.
 
 ## Feature List
 

package/dist/spec.d.ts

@@ -1,4 +1,9 @@
-import type { RuntimeSpecConfigSnapshot, SpecGenerator } from '@tsoa-next/runtime';
+import type { EmbeddedSpecGeneratorArtifacts, RuntimeSpecConfigSnapshot, SpecGenerator } from '@tsoa-next/runtime';
+/**
+ * Creates a runtime spec generator from a prebuilt OpenAPI artifact embedded into generated route code.
+ * This keeps built-in `SpecPath` targets independent from source files and TypeScript analysis at request time.
+ */
+export declare function createEmbeddedSpecGenerator(artifacts: EmbeddedSpecGeneratorArtifacts): SpecGenerator;
 /**
  * Creates a runtime spec generator that lazily builds the OpenAPI document once per generator instance using `@tsoa-next/cli`,
  * then caches the generated spec object and serialized strings for subsequent reads.

package/dist/spec.js

@@ -33,13 +33,52 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEmbeddedSpecGenerator = createEmbeddedSpecGenerator;
 exports.createOpenApiSpecGenerator = createOpenApiSpecGenerator;
+const loadCli = async () => await Promise.resolve().then(() => __importStar(require('@tsoa-next/cli')));
 function assertSpecConfig(config) {
     if (!config) {
         throw new Error('SpecPath requires spec generation settings. Provide spec configuration when generating routes so built-in spec targets can rebuild the OpenAPI document at runtime.');
     }
     return config;
 }
+function serializeEmbeddedJson(spec) {
+    return JSON.stringify(spec, null, '\t');
+}
+/**
+ * Creates a runtime spec generator from a prebuilt OpenAPI artifact embedded into generated route code.
+ * This keeps built-in `SpecPath` targets independent from source files and TypeScript analysis at request time.
+ */
+function createEmbeddedSpecGenerator(artifacts) {
+    const specPromise = Promise.resolve(artifacts.spec);
+    const stringCache = new Map();
+    const getSpecObject = async () => specPromise;
+    const getSpecString = async (format) => {
+        const cached = stringCache.get(format);
+        if (cached) {
+            return cached;
+        }
+        let stringPromise;
+        if (format === 'json') {
+            stringPromise = Promise.resolve(artifacts.json ?? serializeEmbeddedJson(artifacts.spec));
+        }
+        else {
+            const yaml = artifacts.yaml;
+            if (yaml === undefined) {
+                stringPromise = Promise.reject(new Error('Embedded spec generator cannot produce YAML because no embedded YAML artifact was provided. Embed `artifacts.yaml` when generating routes, or use `createOpenApiSpecGenerator` if runtime CLI-based serialization is required.'));
+            }
+            else {
+                stringPromise = Promise.resolve(yaml);
+            }
+        }
+        stringCache.set(format, stringPromise);
+        return stringPromise;
+    };
+    return {
+        getSpecObject,
+        getSpecString,
+    };
+}
 /**
  * Creates a runtime spec generator that lazily builds the OpenAPI document once per generator instance using `@tsoa-next/cli`,
  * then caches the generated spec object and serialized strings for subsequent reads.
@@ -47,12 +86,11 @@ function assertSpecConfig(config) {
 function createOpenApiSpecGenerator(config) {
     let specPromise;
     const stringCache = new Map();
-    const loadCli = async () => await Promise.resolve().then(() => __importStar(require('@tsoa-next/cli')));
     const getSpecObject = async () => {
         specPromise ??= (async () => {
             const runtimeConfig = assertSpecConfig(config);
             const cli = await loadCli();
-            return cli.buildSpec(runtimeConfig.spec, runtimeConfig.compilerOptions, runtimeConfig.ignore, undefined, runtimeConfig.defaultNumberType);
+            return cli.buildSpec(runtimeConfig.spec, runtimeConfig.compilerOptions, runtimeConfig.ignore, runtimeConfig.metadata, runtimeConfig.defaultNumberType);
         })();
         return specPromise;
     };

package/dist/spec.js.map

@@ -1 +1 @@
-{"version":3,"file":"spec.js","sourceRoot":"","sources":["../src/spec.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAcA,gEAkCC;AA9CD,SAAS,gBAAgB,CAAC,MAAkC;IAC1D,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,qKAAqK,CAAC,CAAA;IACxL,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;GAGG;AACH,SAAgB,0BAA0B,CAAC,MAAkC;IAC3E,IAAI,WAA2E,CAAA;IAC/E,MAAM,WAAW,GAAG,IAAI,GAAG,EAAoC,CAAA;IAE/D,MAAM,OAAO,GAAG,KAAK,IAAI,EAAE,CAAC,wDAAa,gBAAgB,GAAC,CAAA;IAC1D,MAAM,aAAa,GAAmC,KAAK,IAAI,EAAE;QAC/D,WAAW,KAAK,CAAC,KAAK,IAAI,EAAE;YAC1B,MAAM,aAAa,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAA;YAC9C,MAAM,GAAG,GAAG,MAAM,OAAO,EAAE,CAAA;YAC3B,OAAO,GAAG,CAAC,SAAS,CAAC,aAAa,CAAC,IAAI,EAAE,aAAa,CAAC,eAAmE,EAAE,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAA;QAC/L,CAAC,CAAC,EAAE,CAAA;QAEJ,OAAO,WAAW,CAAA;IACpB,CAAC,CAAA;IAED,MAAM,aAAa,GAAmC,KAAK,EAAC,MAAM,EAAC,EAAE;QACnE,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;QACtC,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,MAAM,CAAA;QACf,CAAC;QAED,MAAM,aAAa,GAAG,CAAC,KAAK,IAAI,EAAE;YAChC,MAAM,GAAG,GAAG,MAAM,OAAO,EAAE,CAAA;YAC3B,OAAO,GAAG,CAAC,aAAa,CAAC,MAAM,aAAa,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC,CAAA;QACpE,CAAC,CAAC,EAAE,CAAA;QAEJ,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;QACtC,OAAO,aAAa,CAAA;IACtB,CAAC,CAAA;IAED,OAAO;QACL,aAAa;QACb,aAAa;KACd,CAAA;AACH,CAAC"}
+{"version":3,"file":"spec.js","sourceRoot":"","sources":["../src/spec.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tsoa-next",
-  "version": "8.2.0",
+  "version": "8.2.1-dev.65.5d3e3033",
   "description": "Build swagger-compliant REST APIs using TypeScript and Node",
   "main": "./dist/index.js",
   "typings": "./dist/index.d.ts",
@@ -32,8 +32,8 @@
   "author": "Vanna DiCatania <vanna@dicatania.me> (http://www.dicatania.me)",
   "license": "MIT",
   "dependencies": {
-    "@tsoa-next/cli": "8.2.0",
-    "@tsoa-next/runtime": "8.2.0"
+    "@tsoa-next/cli": "8.2.1-dev.65.5d3e3033",
+    "@tsoa-next/runtime": "8.2.1-dev.65.5d3e3033"
   },
   "devDependencies": {
     "@types/node": "24.12.0",