@velajs/vela 1.8.2 → 1.8.4

package/dist/http/crud-bridge.d.ts

@@ -0,0 +1,90 @@
+import type { Hono } from 'hono';
+import type { Type } from '../container/types';
+import type { CanActivate } from '../pipeline/types';
+import type { OpenApiPathItem } from '../openapi/types';
+/**
+ * Context passed to {@link CrudBridge.buildRoutes} when mounting CRUD
+ * sub-applications for a `@Crud()`-decorated controller.
+ *
+ * The bridge receives the framework's already-resolved view of the world so
+ * it can produce identical routing behavior to a hand-written controller:
+ * the same global prefix is prepended to every path, the same global guard
+ * instances run before any generated handler, and the same path-joining
+ * helper composes URL segments without double slashes.
+ */
+export interface CrudBridgeRouteContext {
+    /** Application-wide path prefix (e.g. `/api`), already normalized. */
+    globalPrefix: string;
+    /** Global guard instances, pre-resolved from the root container. */
+    globalGuards: CanActivate[];
+    /** Path joiner used by the framework — handles slash normalization. */
+    joinPaths: (...parts: string[]) => string;
+}
+/**
+ * Context passed to {@link CrudBridge.buildOpenApiPaths} when contributing
+ * OpenAPI path items for a `@Crud()`-decorated controller.
+ *
+ * The bridge is responsible for producing fully-qualified path keys that
+ * match the routes it actually mounts at request time. The framework supplies
+ * the prefixes so the bridge does not have to re-derive them.
+ */
+export interface CrudBridgeOpenApiContext {
+    /** Application-wide path prefix (e.g. `/api`), already normalized. */
+    globalPrefix: string;
+    /** Controller-level prefix as registered with `@Controller(...)`. */
+    controllerPrefix: string;
+}
+/**
+ * Contract between `@velajs/vela` and a CRUD route generator (typically
+ * `@velajs/crud`). The bridge inverts the previous dynamic-import pattern,
+ * which was incompatible with Cloudflare Workers because esbuild leaves
+ * `await import(variable)` calls as runtime imports the Workers loader
+ * cannot resolve.
+ *
+ * A consumer registers an implementation once via {@link registerCrudBridge}
+ * — usually as a side effect of importing `@velajs/crud` — and the framework
+ * delegates both route building (at bootstrap) and OpenAPI generation
+ * (at document creation) to it.
+ */
+export interface CrudBridge {
+    /**
+     * Mount the CRUD sub-app for a controller with `vela:crud` metadata.
+     *
+     * Called during {@link RouteManager.build} after all `@Get`/`@Post`/etc.
+     * routes have been registered. The bridge is expected to attach generated
+     * routes (list, read, create, update, delete, …) onto the supplied Hono
+     * app under `ctx.globalPrefix + prefix`.
+     */
+    buildRoutes(app: Hono, controller: Type, prefix: string, crudConfig: unknown, ctx: CrudBridgeRouteContext): Promise<void>;
+    /**
+     * Contribute OpenAPI path items for a `@Crud()`-decorated controller.
+     *
+     * Called once per CRUD controller from `createOpenApiDocument` after the
+     * standard `@Get`/`@Post`/etc. paths have been collected. The returned
+     * record maps full OpenAPI path strings (e.g. `/api/users/{id}`) to path
+     * items, and is merged into the document — entries already present from
+     * hand-written handlers are preserved verb-by-verb.
+     */
+    buildOpenApiPaths(controller: Type, crudConfig: unknown, ctx: CrudBridgeOpenApiContext): Record<string, OpenApiPathItem>;
+}
+/**
+ * Register a {@link CrudBridge} implementation. Intended to be called once at
+ * import time by the CRUD package; subsequent calls overwrite the previous
+ * registration (last-writer-wins). This is deliberate so test harnesses can
+ * swap in mocks without a teardown step on the global state.
+ */
+export declare function registerCrudBridge(bridge: CrudBridge): void;
+/**
+ * Return the currently registered {@link CrudBridge}, or `undefined` if no
+ * bridge has been registered. Consumers using `@Crud()` without a registered
+ * bridge will receive a clear install-it error from the framework at build
+ * time — see `RouteManager.build`.
+ */
+export declare function getCrudBridge(): CrudBridge | undefined;
+/**
+ * Reset the global bridge registration. Test-only — not exported from
+ * `@velajs/vela/internal`. Use this in `beforeEach` to keep cases isolated.
+ *
+ * @internal
+ */
+export declare function _resetCrudBridge(): void;

package/dist/http/crud-bridge.js

@@ -0,0 +1,25 @@
+let registered;
+/**
+ * Register a {@link CrudBridge} implementation. Intended to be called once at
+ * import time by the CRUD package; subsequent calls overwrite the previous
+ * registration (last-writer-wins). This is deliberate so test harnesses can
+ * swap in mocks without a teardown step on the global state.
+ */ export function registerCrudBridge(bridge) {
+    registered = bridge;
+}
+/**
+ * Return the currently registered {@link CrudBridge}, or `undefined` if no
+ * bridge has been registered. Consumers using `@Crud()` without a registered
+ * bridge will receive a clear install-it error from the framework at build
+ * time — see `RouteManager.build`.
+ */ export function getCrudBridge() {
+    return registered;
+}
+/**
+ * Reset the global bridge registration. Test-only — not exported from
+ * `@velajs/vela/internal`. Use this in `beforeEach` to keep cases isolated.
+ *
+ * @internal
+ */ export function _resetCrudBridge() {
+    registered = undefined;
+}

package/dist/http/route.manager.js

@@ -4,6 +4,7 @@ import { HttpException } from "../errors/http-exception.js";
 import { getMetadata } from "../metadata.js";
 import { joinPaths } from "../registry/paths.js";
 import { ArgumentResolver } from "./argument-resolver.js";
+import { getCrudBridge } from "./crud-bridge.js";
 import { buildMiddlewareExecutionContext } from "./execution-context.js";
 import { HandlerExecutor } from "./handler-executor.js";
 import { instantiate, instantiateMany } from "./instantiate.js";
@@ -279,23 +280,25 @@ export class RouteManager {
             }
         }
         // Second pass: mount CRUD sub-apps (/:id routes registered last).
+        //
+        // Routes are produced by a registered CrudBridge — usually contributed
+        // by `@velajs/crud` as an import side effect. Inversion was deliberate:
+        // a previous implementation called `await import('@velajs/crud')` via
+        // an indirect variable to dodge esbuild's static analysis, which made
+        // Cloudflare Workers unable to resolve the module at runtime. The
+        // bridge contract removes that hazard — no runtime resolver involved.
         for (const { controller, metadata } of this.controllers){
             const crudConfig = getMetadata('vela:crud', controller);
-            if (crudConfig) {
-                try {
-                    const pkg = '@velajs/crud';
-                    const { buildCrudRoutes } = await import(pkg);
-                    await buildCrudRoutes(app, controller, metadata.prefix, crudConfig, {
-                        globalPrefix: this.globalPrefix,
-                        globalGuards: instantiateMany(this.globalGuards, this.container),
-                        joinPaths
-                    });
-                } catch (err) {
-                    throw new Error(`@Crud() requires '@velajs/crud'. Install it: pnpm add @velajs/crud`, {
-                        cause: err
-                    });
-                }
+            if (!crudConfig) continue;
+            const bridge = getCrudBridge();
+            if (!bridge) {
+                throw new Error("@Crud() requires '@velajs/crud'. Install it: pnpm add @velajs/crud");
             }
+            await bridge.buildRoutes(app, controller, metadata.prefix, crudConfig, {
+                globalPrefix: this.globalPrefix,
+                globalGuards: instantiateMany(this.globalGuards, this.container),
+                joinPaths
+            });
         }
         return app;
     }

package/dist/internal.d.ts

@@ -5,6 +5,8 @@ export type { ModuleScope, ContainerOptions, Diagnostics, } from './container/ty
 export { bindAppProviders } from './pipeline/app-providers';
 export { RouteManager } from './http/route.manager';
 export type { RouteManagerOptions } from './http/route.manager';
+export { registerCrudBridge, getCrudBridge, } from './http/crud-bridge';
+export type { CrudBridge, CrudBridgeRouteContext, CrudBridgeOpenApiContext, } from './http/crud-bridge';
 export { ModuleLoader } from './module/module-loader';
 export { ComponentManager } from './pipeline/component.manager';
 export { VelaApplication } from './application';

package/dist/internal.js

@@ -6,6 +6,13 @@ export { ModuleRef } from "./container/module-ref.js";
 export { ModuleVisibilityError } from "./container/types.js";
 export { bindAppProviders } from "./pipeline/app-providers.js";
 export { RouteManager } from "./http/route.manager.js";
+// CRUD bridge registry — the integration seam for `@velajs/crud` (and any
+// future CRUD route generator). `@velajs/crud` calls `registerCrudBridge`
+// once at import time; the framework consults `getCrudBridge` whenever it
+// encounters a controller carrying `vela:crud` metadata, both at route
+// build time and at OpenAPI document generation. The types are exposed so
+// integrators can write their own bridges or strongly-typed mocks in tests.
+export { registerCrudBridge, getCrudBridge } from "./http/crud-bridge.js";
 export { ModuleLoader } from "./module/module-loader.js";
 export { ComponentManager } from "./pipeline/component.manager.js";
 export { VelaApplication } from "./application.js";

package/dist/openapi/document.js

@@ -1,7 +1,9 @@
+import { METADATA_KEYS, ParamType } from "../constants.js";
+import { getCrudBridge } from "../http/crud-bridge.js";
+import { getMetadata } from "../metadata.js";
 import { collectControllers } from "../module/graph.js";
 import { MetadataRegistry } from "../registry/metadata.registry.js";
 import { joinPaths, toOpenApiPath } from "../registry/paths.js";
-import { ParamType } from "../constants.js";
 import { getApiDoc, getApiResponses, getApiTags } from "./decorators.js";
 import { isOptional, zodToJsonSchema } from "./zod-to-json-schema.js";
 /**
@@ -198,7 +200,8 @@ export function createOpenApiDocument(rootModule, options = {}) {
     const paths = {};
     const globalPrefix = options.globalPrefix ?? '';
     const registry = new ComponentsRegistry();
-    for (const controller of collectControllers(rootModule)){
+    const controllers = collectControllers(rootModule);
+    for (const controller of controllers){
         const controllerPath = MetadataRegistry.getControllerPath(controller);
         const routes = MetadataRegistry.getRoutes(controller);
         for (const route of routes){
@@ -212,6 +215,60 @@ export function createOpenApiDocument(rootModule, options = {}) {
             paths[pathString] = pathItem;
         }
     }
+    // Second pass: include `@Crud()`-generated routes via the registered
+    // CrudBridge. The bridge knows how to turn its own metadata config into
+    // OpenAPI path items; this loop is silent when no bridge is registered or
+    // no controller carries `vela:crud` metadata, so consumers without
+    // `@velajs/crud` see no behavioral change.
+    const bridge = getCrudBridge();
+    if (bridge) {
+        for (const controller of controllers){
+            const crudConfig = getMetadata(METADATA_KEYS.CRUD, controller);
+            if (!crudConfig) continue;
+            const controllerPrefix = MetadataRegistry.getControllerPath(controller);
+            const crudPaths = bridge.buildOpenApiPaths(controller, crudConfig, {
+                globalPrefix,
+                controllerPrefix
+            });
+            for (const [pathKey, pathItem] of Object.entries(crudPaths)){
+                // Verb-level merge: a hand-written `@Get('/')` on the same controller
+                // is preserved when the bridge contributes `post`/`patch`/etc. on
+                // the same path key.
+                paths[pathKey] = {
+                    ...paths[pathKey] ?? {},
+                    ...pathItem
+                };
+            }
+        }
+    }
+    // Aggregate the document-root `tags` array. NestJS declares tag
+    // groups/descriptions/order via `DocumentBuilder().addTag(name, desc)`
+    // while its scanner auto-collects operation tags; we wire both halves
+    // here. Walk every operation's `tags` in first-seen order (stable: paths
+    // insertion order, then verb order), then merge with `options.tags`
+    // (caller-declared tags first — preserving their order + descriptions —
+    // followed by any purely-collected tag not already declared, as `{ name }`).
+    const seenTagNames = new Set();
+    const collectedTagNames = [];
+    for (const pathItem of Object.values(paths)){
+        for (const verb of VERB_WHITELIST){
+            const operation = pathItem[verb];
+            if (!operation?.tags) continue;
+            for (const tagName of operation.tags){
+                if (seenTagNames.has(tagName)) continue;
+                seenTagNames.add(tagName);
+                collectedTagNames.push(tagName);
+            }
+        }
+    }
+    const declaredTags = options.tags ?? [];
+    const declaredTagNames = new Set(declaredTags.map((t)=>t.name));
+    const tags = [
+        ...declaredTags,
+        ...collectedTagNames.filter((name)=>!declaredTagNames.has(name)).map((name)=>({
+                name
+            }))
+    ];
     const document = {
         openapi: '3.1.0',
         info: {
@@ -229,5 +286,11 @@ export function createOpenApiDocument(rootModule, options = {}) {
             schemas
         };
     }
+    // Only attach `tags` when non-empty. Emitting `tags: []` on a tag-less
+    // spec is the exact symptom the consumer reported, so omit the key
+    // entirely in that case (mirrors the `components` handling above).
+    if (tags.length > 0) {
+        document.tags = tags;
+    }
     return document;
 }

package/dist/openapi/types.d.ts

@@ -90,6 +90,17 @@ export interface ApiResponseEntry extends ApiResponseOptions {
 export interface CreateOpenApiDocumentOptions {
     info?: Partial<OpenApiInfo>;
     globalPrefix?: string;
+    /**
+     * Declare top-level tag groups with descriptions and an explicit order
+     * (mirrors NestJS `DocumentBuilder().addTag(name, description)`). Tags
+     * actually used by operations but NOT declared here are still emitted —
+     * appended after the declared ones in first-seen order. Declared tags
+     * with no operations are kept (lets you pre-declare ordering/description).
+     */
+    tags?: Array<{
+        name: string;
+        description?: string;
+    }>;
 }
 export interface MountOpenApiOptions {
     /** Pre-built OpenAPI document to serve. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/vela",
-  "version": "1.8.2",
+  "version": "1.8.4",
   "description": "NestJS-compatible framework for edge runtimes, powered by Hono",
   "type": "module",
   "main": "./dist/index.js",