@velajs/vela 1.8.4 → 1.8.7

package/dist/application.d.ts

@@ -24,13 +24,20 @@ export declare class VelaApplication {
     useGlobalInterceptors(...interceptors: InterceptorType[]): this;
     useGlobalFilters(...filters: FilterType[]): this;
     /**
-     * Serve a pre-built OpenAPI document (and optionally a Scalar UI) on
-     * the underlying Hono app. Edge-safe: the UI HTML loads Scalar from a
-     * CDN at runtime so nothing is bundled server-side.
+     * Serve a pre-built OpenAPI document and one or more interactive doc UIs
+     * (Swagger UI, Scalar, ReDoc) on the underlying Hono app, mirroring the
+     * hono-crud docs convention. Edge-safe: each UI is a tiny self-contained
+     * HTML shell that loads its renderer from a CDN at runtime so nothing is
+     * bundled server-side and no extra dependency is required.
+     *
+     * Defaults: spec at `/openapi.json`, Scalar at `/scalar`, Swagger UI at
+     * `/docs`, ReDoc at `/redoc`. The deprecated `path` / `uiPath` aliases are
+     * retained for migration from the previous single-UI shape.
      *
      * ```ts
      * const doc = createOpenApiDocument(AppModule);
-     * app.mountOpenApi({ document: doc, ui: 'scalar' });
+     * app.mountOpenApi({ document: doc });            // Scalar @ /scalar
+     * app.mountOpenApi({ document: doc, ui: 'all' }); // swagger + scalar + redoc
      * ```
      */
     mountOpenApi(options: MountOpenApiOptions): this;

package/dist/application.js

@@ -1,5 +1,7 @@
 import { hasBeforeApplicationShutdown, hasOnApplicationBootstrap, hasOnApplicationShutdown, hasOnModuleDestroy, hasOnModuleInit } from "./lifecycle/index.js";
 import { renderScalarUi } from "./openapi/scalar-ui.js";
+import { renderSwaggerUi } from "./openapi/swagger-ui.js";
+import { renderRedocUi } from "./openapi/redoc-ui.js";
 export class VelaApplication {
     container;
     routeManager;
@@ -54,23 +56,69 @@ export class VelaApplication {
         return this;
     }
     /**
-   * Serve a pre-built OpenAPI document (and optionally a Scalar UI) on
-   * the underlying Hono app. Edge-safe: the UI HTML loads Scalar from a
-   * CDN at runtime so nothing is bundled server-side.
+   * Serve a pre-built OpenAPI document and one or more interactive doc UIs
+   * (Swagger UI, Scalar, ReDoc) on the underlying Hono app, mirroring the
+   * hono-crud docs convention. Edge-safe: each UI is a tiny self-contained
+   * HTML shell that loads its renderer from a CDN at runtime so nothing is
+   * bundled server-side and no extra dependency is required.
+   *
+   * Defaults: spec at `/openapi.json`, Scalar at `/scalar`, Swagger UI at
+   * `/docs`, ReDoc at `/redoc`. The deprecated `path` / `uiPath` aliases are
+   * retained for migration from the previous single-UI shape.
    *
    * ```ts
    * const doc = createOpenApiDocument(AppModule);
-   * app.mountOpenApi({ document: doc, ui: 'scalar' });
+   * app.mountOpenApi({ document: doc });            // Scalar @ /scalar
+   * app.mountOpenApi({ document: doc, ui: 'all' }); // swagger + scalar + redoc
    * ```
    */ mountOpenApi(options) {
         const app = this.getApp();
-        const jsonPath = options.path ?? '/docs.json';
         const doc = options.document;
-        app.get(jsonPath, (c)=>c.json(doc));
-        if (options.ui === 'scalar') {
-            const uiPath = options.uiPath ?? '/docs';
-            const html = renderScalarUi(jsonPath);
-            app.get(uiPath, (c)=>c.html(html));
+        const title = options.title;
+        // Spec JSON: new default `/openapi.json`. The deprecated `path` alias is
+        // honored as an override only (does not change the default).
+        const specPath = options.specPath ?? options.path ?? '/openapi.json';
+        app.get(specPath, (c)=>c.json(doc));
+        // Normalize the requested UI set. Default is Scalar only.
+        const uiOption = options.ui;
+        let uis;
+        let singleStringUi = false;
+        if (uiOption === undefined) {
+            uis = [
+                'scalar'
+            ];
+        } else if (uiOption === 'all') {
+            uis = [
+                'swagger',
+                'scalar',
+                'redoc'
+            ];
+        } else if (Array.isArray(uiOption)) {
+            uis = uiOption;
+        } else {
+            uis = [
+                uiOption
+            ];
+            singleStringUi = true;
+        }
+        for (const ui of uis){
+            // Back-compat: the old `{ ui: 'scalar', uiPath }` form mapped a single
+            // string UI to `uiPath`. Honor that only when exactly one UI was
+            // requested as a string.
+            const legacyPath = singleStringUi && uis.length === 1 ? options.uiPath : undefined;
+            if (ui === 'swagger') {
+                const path = legacyPath ?? options.swaggerPath ?? '/docs';
+                const html = renderSwaggerUi(specPath, title);
+                app.get(path, (c)=>c.html(html));
+            } else if (ui === 'redoc') {
+                const path = legacyPath ?? options.redocPath ?? '/redoc';
+                const html = renderRedocUi(specPath, title);
+                app.get(path, (c)=>c.html(html));
+            } else {
+                const path = legacyPath ?? options.scalarPath ?? '/scalar';
+                const html = renderScalarUi(specPath, title);
+                app.get(path, (c)=>c.html(html));
+            }
         }
         return this;
     }

package/dist/container/container.js

@@ -401,7 +401,18 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
                 m.index,
                 m
             ]));
-        const dependencies = paramTypes.map((paramType, index)=>{
+        // Constructor arity. Normally `design:paramtypes` (emitDecoratorMetadata)
+        // gives the count, but some bundlers — notably esbuild (and therefore
+        // Wrangler) — do not emit it, leaving `paramTypes` empty even when
+        // `@Inject(token)` recorded explicit tokens. Fall back to the highest
+        // `@Inject` index so explicit-token constructors still resolve without
+        // emitted metadata. Slots with neither a param type nor an `@Inject` token
+        // still hit the unresolved-dependency error below.
+        const arity = Math.max(paramTypes.length, injectMetadata.reduce((max, m)=>Math.max(max, m.index + 1), 0));
+        const dependencies = Array.from({
+            length: arity
+        }, (_unused, index)=>{
+            const paramType = paramTypes[index];
             const meta = injectMap.get(index);
             const rawToken = meta?.token;
             const isForwardRef = rawToken instanceof ForwardRef;

package/dist/http/instantiate.js

@@ -1,18 +1,45 @@
+import { getConstructorDependencies, getInjectMetadata } from "../container/decorators.js";
 // Resolve a class/token through the container if registered, otherwise treat
 // the input as a plain instance. Used by RouteManager and HandlerExecutor to
 // materialize middleware, guards, pipes, interceptors, and filters per request.
+//
+// When the input is a class that is NOT registered in the container, we fall
+// back to `new clazz()` so plain parameterless helper classes (e.g. mixin
+// guards, ad-hoc `@UseGuards(LocalGuard)` references) keep working. That
+// fallback is unsafe for classes whose CONSTRUCTOR EXPECTS DEPENDENCIES,
+// because zero-arg construction would leave every injected slot `undefined`
+// — a silent failure mode that surfaces later as
+// `Cannot read properties of undefined (reading '...')` deep inside the
+// class. For those classes we throw a loud, actionable error instead.
+//
+// We treat "expects dependencies" as: any `@Inject(...)` parameter metadata
+// OR a non-empty `design:paramtypes` (the SWC/TS emit for any constructor
+// parameter). `@Injectable()` alone is NOT sufficient — `mixin()` and many
+// parameterless guards are `@Injectable()` and still safe to `new` directly.
 export function instantiate(classOrInstance, container) {
     if (typeof classOrInstance === 'function') {
-        if (container.has(classOrInstance)) {
-            return container.resolve(classOrInstance);
+        const clazz = classOrInstance;
+        if (container.has(clazz)) {
+            return container.resolve(clazz);
         }
-        return new classOrInstance();
+        if (constructorExpectsDependencies(clazz)) {
+            throw new Error(`Cannot instantiate ${clazz.name}: the class declares constructor ` + `dependencies (\`@Inject(...)\` parameters or typed constructor ` + `parameters), but no matching provider is registered in the ` + `container. Add it to a module's providers (and export it if used ` + `outside its declaring module) instead of relying on the bare ` + `\`new\` fallback, which would construct the class without ` + `honouring its dependency-injection metadata and leave every ` + `injected field \`undefined\`.`);
+        }
+        return new clazz();
     }
     if (container.has(classOrInstance)) {
         return container.resolve(classOrInstance);
     }
     return classOrInstance;
 }
+// True when calling `new clazz()` would leave an injected slot `undefined`:
+// either the class has explicit `@Inject(...)` metadata, or it has any typed
+// constructor parameter (TS/SWC's `design:paramtypes` emit). Parameterless
+// `@Injectable()` classes return false — `new()` is safe for them.
+function constructorExpectsDependencies(clazz) {
+    if (getInjectMetadata(clazz).length > 0) return true;
+    return getConstructorDependencies(clazz).length > 0;
+}
 export function instantiateMany(items, container) {
     return items.map((item)=>instantiate(item, container));
 }

package/dist/openapi/index.d.ts

@@ -2,4 +2,6 @@ export { createOpenApiDocument } from './document';
 export { ApiDoc, ApiTags, ApiResponse, API_DOC_METADATA, API_TAGS_METADATA, API_RESPONSES_METADATA, } from './decorators';
 export { zodToJsonSchema } from './zod-to-json-schema';
 export { renderScalarUi } from './scalar-ui';
-export type { ApiDocMetadata, ApiResponseEntry, ApiResponseOptions, CreateOpenApiDocumentOptions, HttpVerb, JsonSchema, MountOpenApiOptions, OpenApiDocument, OpenApiInfo, OpenApiOperation, OpenApiParameter, OpenApiPathItem, OpenApiRequestBody, OpenApiResponse, } from './types';
+export { renderSwaggerUi } from './swagger-ui';
+export { renderRedocUi } from './redoc-ui';
+export type { ApiDocMetadata, ApiResponseEntry, ApiResponseOptions, CreateOpenApiDocumentOptions, HttpVerb, JsonSchema, MountOpenApiOptions, OpenApiUi, OpenApiDocument, OpenApiInfo, OpenApiOperation, OpenApiParameter, OpenApiPathItem, OpenApiRequestBody, OpenApiResponse, } from './types';

package/dist/openapi/index.js

@@ -2,3 +2,5 @@ export { createOpenApiDocument } from "./document.js";
 export { ApiDoc, ApiTags, ApiResponse, API_DOC_METADATA, API_TAGS_METADATA, API_RESPONSES_METADATA } from "./decorators.js";
 export { zodToJsonSchema } from "./zod-to-json-schema.js";
 export { renderScalarUi } from "./scalar-ui.js";
+export { renderSwaggerUi } from "./swagger-ui.js";
+export { renderRedocUi } from "./redoc-ui.js";

package/dist/openapi/redoc-ui.d.ts

@@ -0,0 +1 @@
+export declare function renderRedocUi(specUrl: string, title?: string): string;

package/dist/openapi/redoc-ui.js

@@ -0,0 +1,19 @@
+// Minimal HTML shell that bootstraps ReDoc from a CDN. Served as a static
+// string so it works on every edge runtime with no Node or bundler deps —
+// ReDoc itself is loaded from a CDN at runtime.
+export function renderRedocUi(specUrl, title) {
+    const safeUrl = specUrl.replace(/"/g, '"');
+    const safeTitle = (title ?? 'API Reference').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    return `<!doctype html>
+<html>
+  <head>
+    <title>${safeTitle}</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <redoc spec-url="${safeUrl}"></redoc>
+    <script src="https://cdn.jsdelivr.net/npm/redoc/bundles/redoc.standalone.js"></script>
+  </body>
+</html>`;
+}

package/dist/openapi/scalar-ui.d.ts

@@ -1 +1 @@
-export declare function renderScalarUi(jsonUrl: string): string;
+export declare function renderScalarUi(jsonUrl: string, title?: string): string;

package/dist/openapi/scalar-ui.js

@@ -1,12 +1,13 @@
 // Minimal HTML shell that bootstraps Scalar's hosted API-reference UI.
 // Served as a static string so it works on every edge runtime with no
 // Node or bundler deps. Scalar itself is loaded from a CDN at runtime.
-export function renderScalarUi(jsonUrl) {
+export function renderScalarUi(jsonUrl, title) {
     const safeUrl = jsonUrl.replace(/"/g, '"');
+    const safeTitle = (title ?? 'API Reference').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
     return `<!doctype html>
 <html>
   <head>
-    <title>API Reference</title>
+    <title>${safeTitle}</title>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
   </head>

package/dist/openapi/swagger-ui.d.ts

@@ -0,0 +1 @@
+export declare function renderSwaggerUi(specUrl: string, title?: string): string;

package/dist/openapi/swagger-ui.js

@@ -0,0 +1,23 @@
+// Minimal HTML shell that bootstraps Swagger UI from a CDN. Served as a
+// static string so it works on every edge runtime with no Node or bundler
+// deps — Swagger UI itself is loaded from a CDN at runtime.
+export function renderSwaggerUi(specUrl, title) {
+    const safeUrl = specUrl.replace(/"/g, '"');
+    const safeTitle = (title ?? 'API Reference').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    return `<!doctype html>
+<html>
+  <head>
+    <title>${safeTitle}</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui.css" />
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui-bundle.js"></script>
+    <script>
+      window.ui = SwaggerUIBundle({ url: "${safeUrl}", dom_id: '#swagger-ui' });
+    </script>
+  </body>
+</html>`;
+}

package/dist/openapi/types.d.ts

@@ -102,13 +102,27 @@ export interface CreateOpenApiDocumentOptions {
         description?: string;
     }>;
 }
+export type OpenApiUi = 'swagger' | 'scalar' | 'redoc';
 export interface MountOpenApiOptions {
     /** Pre-built OpenAPI document to serve. */
     document: OpenApiDocument;
-    /** Path for the JSON endpoint. Default `/docs.json`. */
+    /** OpenAPI JSON spec path. @default '/openapi.json' */
+    specPath?: string;
+    /**
+     * UI(s) to mount. 'all' mounts swagger + scalar + redoc.
+     * @default 'scalar'
+     */
+    ui?: OpenApiUi | OpenApiUi[] | 'all';
+    /** Swagger UI path. @default '/docs' */
+    swaggerPath?: string;
+    /** Scalar path. @default '/scalar' */
+    scalarPath?: string;
+    /** ReDoc path. @default '/redoc' */
+    redocPath?: string;
+    /** Page title for the UIs. */
+    title?: string;
+    /** @deprecated use `specPath`. Back-compat alias; if set, overrides specPath default. */
     path?: string;
-    /** Opt-in UI renderer. Only `scalar` is bundled today. */
-    ui?: 'scalar';
-    /** Path the UI is served at when `ui` is set. Default `/docs`. */
+    /** @deprecated single-UI path override; applies to the single `ui` when a string. */
     uiPath?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/vela",
-  "version": "1.8.4",
+  "version": "1.8.7",
   "description": "NestJS-compatible framework for edge runtimes, powered by Hono",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,6 +29,14 @@
     "LICENSE",
     "CHANGELOG.md"
   ],
+  "scripts": {
+    "build": "rm -rf dist && swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
+    "test": "vitest run",
+    "test:workers": "vitest run --config vitest.config.workers.ts",
+    "typecheck": "tsc --noEmit",
+    "prepare": "swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
+    "prepublishOnly": "pnpm run typecheck && pnpm test"
+  },
   "sideEffects": [
     "./dist/index.js"
   ],
@@ -58,24 +66,26 @@
     "node": ">=20"
   },
   "dependencies": {
-    "hono": "^4"
+    "hono": "^4.12.26"
+  },
+  "packageManager": "pnpm@10.20.0",
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "@swc/core",
+      "esbuild",
+      "workerd"
+    ]
   },
   "devDependencies": {
-    "@cloudflare/vitest-pool-workers": "^0.15.2",
-    "@swc/cli": "^0.8.0",
-    "@swc/core": "^1.15.11",
+    "@cloudflare/vitest-pool-workers": "^0.16.18",
+    "@swc/cli": "^0.8.1",
+    "@swc/core": "^1.15.41",
     "@types/bun": "latest",
-    "@vitest/runner": "^4.1.5",
-    "@vitest/snapshot": "^4.1.5",
-    "typescript": "^5",
+    "@vitest/runner": "^4.1.9",
+    "@vitest/snapshot": "^4.1.9",
+    "typescript": "^6.0.3",
     "unplugin-swc": "^1.5.9",
-    "vitest": "^4.1.5",
-    "zod": "^4.3.6"
-  },
-  "scripts": {
-    "build": "rm -rf dist && swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
-    "test": "vitest run",
-    "test:workers": "vitest run --config vitest.config.workers.ts",
-    "typecheck": "tsc --noEmit"
+    "vitest": "^4.1.9",
+    "zod": "^4.4.3"
   }
-}
+}