tsoa-next 8.0.4 → 8.0.5-dev.57.84bb4a63

package/README.MD

@@ -47,65 +47,22 @@ Where historical release notes or migration references still point upstream, the
 - 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.
 
-## External Validators
-
-`@Validate(...)` adds opt-in runtime authority for external schemas on supported controller method parameters.
-
-- Supported forms: `@Validate(schema)`, `@Validate('zod', schema)`, `@Validate({ kind: 'zod', schema })`
-- Supported libraries: `zod`, `joi`, `yup`, `superstruct`, `io-ts`
-- `io-ts` installs: add `fp-ts`, and add `io-ts-types` as well if you rely on helpers like `withMessage`
-- Supported parameter decorators: `@Body`, `@BodyProp`, `@Query`, `@Queries`, `@Path`, `@Header`, and `@FormField` / uploaded file params
-- Behavior: TypeScript metadata still drives OpenAPI generation, while the external schema replaces built-in runtime validation for the decorated parameter subtree
-- Compatibility: routes without `@Validate(...)` keep their current behavior
-
-Generated `RegisterRoutes(...)` functions also accept an optional validation context so applications can provide translation or failure-formatting hooks:
-
-```ts
-RegisterRoutes(app, {
-  validation: {
-    translate: (key, params) => translateMessage(key, params),
-    errorFormatter: failure => failure,
-  },
-})
-```
-
-```ts
-import * as t from 'io-ts'
-import { withMessage } from 'io-ts-types'
-import { Body, Controller, Post, Route, Validate } from 'tsoa-next'
-
-interface PositiveFloatBrand {
-  readonly PositiveFloat: unique symbol
-}
-
-const PositiveFloat = withMessage(
-  t.brand(t.number, (n): n is t.Branded<number, PositiveFloatBrand> => Number.isFinite(n) && n > 0, 'PositiveFloat'),
-  () => 'validation.wager.amount.mustBePositiveFloat',
-)
-
-const WagerCodec = t.type({
-  amount: PositiveFloat,
-  outcome: t.Int,
-})
-
-type Wager = t.TypeOf<typeof WagerCodec>
-
-@Route('wagers')
-export class WagersController extends Controller {
-  @Post()
-  public createWager(
-    @Body()
-    @Validate('io-ts', WagerCodec)
-    wager: Wager,
-  ): Wager {
-    return wager
-  }
-}
-```
-
-## Migration Note
-
-This feature is fully opt-in. If you do not use `@Validate(...)`, existing interface/class models, generated routes, validation behavior, and error responses are unchanged.
+## Feature List
+
+- Generate OpenAPI 2.0, 3.0, or 3.1 documents directly from your TypeScript controllers, models, and JSDoc comments.
+- Treat TypeScript controllers and models as the source of truth for paths, parameters, schemas, examples, tags, and security metadata.
+- Generate framework-specific route handlers for Express, Koa, and Hapi, or supply your own Handlebars templates for custom runtimes.
+- Validate request input at runtime with configurable coercion and additional-property handling that stays aligned with the generated schema.
+- Expose controller-local spec endpoints with `@SpecPath(...)` without reading a generated spec file from local disk at request time.
+- Serve built-in `json`, `yaml`, `swagger`, `redoc`, and `rapidoc` spec targets, with docs UI packages loaded lazily as optional peers when available.
+- Attach multiple `@SpecPath(...)` decorators to the same controller as long as their resolved paths are unique.
+- Cache built-in or custom spec responses with `'none'`, in-process `'memory'`, or a custom cache handler that can read from strings or streams.
+- Return either `string` or `Readable` responses from custom `@SpecPath(...)` handlers for bespoke documentation or downstream integrations.
+- Use `@Validate(...)` to delegate runtime validation to supported external schema libraries such as `zod`, `joi`, `yup`, `superstruct`, or `io-ts`.
+- Customize validation translation and failure formatting through the optional validation context accepted by generated `RegisterRoutes(...)` functions.
+- Support authentication hooks, dependency injection, typed alternate responders, file uploads, custom middleware, and custom validation workflows.
+- Use the `tsoa` CLI for spec and route generation, or call the programmatic APIs from `tsoa-next/cli`.
+- Target modern Node.js releases with the support policy verified in CI across the previous LTS, current LTS, and Node vNext.
 
 ## Getting Started
 
@@ -127,6 +84,8 @@ This feature is fully opt-in. If you do not use `@Validate(...)`, existing inter
 
 Check out the [guides](https://tsoa-next.dev/)
 
+Use the companion [playground repository](https://github.com/tsoa-next/playground) for runnable example apps and server-focused scenarios.
+
 See example controllers in [the tests](https://github.com/tsoa-next/tsoa-next/tree/main/tests/fixtures/controllers)
 
 See example models in [the tests](https://github.com/tsoa-next/tsoa-next/blob/main/tests/fixtures/testModel.ts)

package/dist/cli-bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli-bin.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const runCLI_1 = require("@tsoa-next/cli/dist/runCLI");
+if (require.main === module) {
+    void (async () => {
+        try {
+            await (0, runCLI_1.runCLI)();
+        }
+        catch (err) {
+            console.error('tsoa cli error:\n', err);
+            process.exit(1);
+        }
+    })();
+}
+//# sourceMappingURL=cli-bin.js.map

package/dist/cli-bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-bin.js","sourceRoot":"","sources":["../src/cli-bin.ts"],"names":[],"mappings":";;;AACA,uDAAmD;AAEnD,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;IAC5B,KAAK,CAAC,KAAK,IAAI,EAAE;QACf,IAAI,CAAC;YACH,MAAM,IAAA,eAAM,GAAE,CAAA;QAChB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAA;YACvC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QACjB,CAAC;IACH,CAAC,CAAC,EAAE,CAAA;AACN,CAAC"}

package/dist/index.d.ts

@@ -1 +1,2 @@
 export * from '@tsoa-next/runtime';
+export * from './spec';

package/dist/index.js

@@ -15,4 +15,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("@tsoa-next/runtime"), exports);
+__exportStar(require("./spec"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qDAAkC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qDAAkC;AAClC,yCAAsB"}

package/dist/spec.d.ts

@@ -0,0 +1,2 @@
+import type { RuntimeSpecConfigSnapshot, SpecGenerator } from '@tsoa-next/runtime';
+export declare function createOpenApiSpecGenerator(config?: RuntimeSpecConfigSnapshot): SpecGenerator;

package/dist/spec.js

@@ -0,0 +1,72 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOpenApiSpecGenerator = createOpenApiSpecGenerator;
+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 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 specPromise;
+    };
+    const getSpecString = async (format) => {
+        const cached = stringCache.get(format);
+        if (cached) {
+            return cached;
+        }
+        const stringPromise = (async () => {
+            const cli = await loadCli();
+            return cli.serializeSpec(await getSpecObject(), format === 'yaml');
+        })();
+        stringCache.set(format, stringPromise);
+        return stringPromise;
+    };
+    return {
+        getSpecObject,
+        getSpecString,
+    };
+}
+//# sourceMappingURL=spec.js.map

package/dist/spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.js","sourceRoot":"","sources":["../src/spec.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAUA,gEAkCC;AA1CD,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,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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tsoa-next",
-  "version": "8.0.4",
+  "version": "8.0.5-dev.57.84bb4a63",
   "description": "Build swagger-compliant REST APIs using TypeScript and Node",
   "main": "./dist/index.js",
   "typings": "./dist/index.d.ts",
@@ -9,7 +9,7 @@
     "tsoa-next-logo-590.png"
   ],
   "bin": {
-    "tsoa": "dist/cli.js"
+    "tsoa": "dist/cli-bin.js"
   },
   "scripts": {
     "build": "npm run tsc",
@@ -32,13 +32,37 @@
   "author": "Vanna DiCatania <vanna@dicatania.me> (http://www.dicatania.me)",
   "license": "MIT",
   "dependencies": {
-    "@tsoa-next/cli": "8.0.4",
-    "@tsoa-next/runtime": "8.0.4"
+    "@tsoa-next/cli": "8.0.5-dev.57.84bb4a63",
+    "@tsoa-next/runtime": "8.0.5-dev.57.84bb4a63"
   },
   "devDependencies": {
     "@types/node": "24.12.0",
     "typescript": "^5.9.3"
   },
+  "peerDependencies": {
+    "hapi-swagger": "^17.3.2",
+    "rapidoc": "^9.3.8",
+    "redoc": "^2.5.2",
+    "swagger-ui-express": "^5.0.1",
+    "swagger-ui-koa": "^0.0.1"
+  },
+  "peerDependenciesMeta": {
+    "hapi-swagger": {
+      "optional": true
+    },
+    "rapidoc": {
+      "optional": true
+    },
+    "redoc": {
+      "optional": true
+    },
+    "swagger-ui-express": {
+      "optional": true
+    },
+    "swagger-ui-koa": {
+      "optional": true
+    }
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/tsoa-next/tsoa-next.git",