@velajs/vela 1.8.1 → 1.8.3

package/dist/container/index.d.ts

@@ -3,4 +3,4 @@ export { Injectable, Inject, Optional, isInjectable, getScope } from './decorato
 export { InjectionToken, ForwardRef, forwardRef, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID, } from './types';
 export { ModuleRef } from './module-ref';
 export { mixin } from './mixin';
-export type { Type, Token, InjectableOptions, InjectMetadata, ProviderOptions, ProviderRegistration, InjectionTokenOptions, ModuleScope, ContainerOptions, Diagnostics, } from './types';
+export type { Type, Token, InferToken, InferTokens, InjectableOptions, InjectMetadata, ProviderOptions, ProviderRegistration, InjectionTokenOptions, ModuleScope, ContainerOptions, Diagnostics, } from './types';

package/dist/container/types.d.ts

@@ -16,6 +16,28 @@ export declare class ForwardRef<T = unknown> {
 }
 export declare function forwardRef<T>(factory: () => Token<T>): ForwardRef<T>;
 export type Token<T = any> = Type<T> | InjectionToken<T> | string | symbol;
+/**
+ * Maps a single DI `Token<T>` to its resolved value type at the type level:
+ * - `InjectionToken<T>`           → `T`
+ * - `Type<T>` / `Constructor<T>`  → `T` (the instance type)
+ * - `ForwardRef<T>`               → `T`
+ * - `string` / `symbol`           → `unknown` (runtime-only tokens carry no
+ *                                   static type info; the consumer asserts).
+ *
+ * Used by `AsyncModuleOptions` to give `useFactory` parameters their real
+ * types based on the literal `inject` tuple — without `as const` at the call
+ * site (relies on the `const` type parameter on the consuming generic).
+ */
+export type InferToken<T> = T extends InjectionToken<infer U> ? U : T extends ForwardRef<infer U> ? U : T extends abstract new (...args: any[]) => infer U ? U : unknown;
+/**
+ * Map every position of a `Token[]` tuple to its resolved value type.
+ * Pairs with `const Inject extends readonly Token<unknown>[]` generics to
+ * give `useFactory(...deps)` parameter types inferred from the literal
+ * `inject` array.
+ */
+export type InferTokens<T extends readonly unknown[]> = {
+    [K in keyof T]: InferToken<T[K]>;
+};
 export interface InjectableOptions {
     scope?: Scope;
 }
@@ -30,7 +52,7 @@ export interface ProviderOptions<T = unknown> {
     useValue?: T;
     useFactory?: (...args: any[]) => T | Promise<T>;
     useClass?: Type<T>;
-    inject?: Token[];
+    inject?: readonly Token[];
     useExisting?: Token<T>;
 }
 export interface ProviderRegistration<T = unknown> {
@@ -46,7 +68,7 @@ export interface ProviderRegistration<T = unknown> {
     useValue?: T;
     useFactory?: (...args: any[]) => T | Promise<T>;
     useClass?: Type<T>;
-    inject?: Token[];
+    inject?: readonly Token[];
     useExisting?: Token<T>;
 }
 export interface ModuleScope {

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/index.d.ts

@@ -7,7 +7,7 @@ export type { BootstrapOptions, BootstrapResult } from './factory/bootstrap';
 export { createOpenApiDocument, ApiDoc, ApiTags, ApiResponse, zodToJsonSchema, } from './openapi/index';
 export type { OpenApiDocument, OpenApiInfo, OpenApiOperation, OpenApiParameter, OpenApiPathItem, OpenApiRequestBody, OpenApiResponse, ApiDocMetadata, ApiResponseEntry, ApiResponseOptions, CreateOpenApiDocumentOptions, HttpVerb, JsonSchema, } from './openapi/index';
 export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, forwardRef, ModuleRef, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID, mixin, } from './container/index';
-export type { Type, Token, InjectableOptions, ProviderOptions, ModuleScope, ContainerOptions, Diagnostics, } from './container/index';
+export type { Type, Token, InferToken, InferTokens, InjectableOptions, ProviderOptions, ModuleScope, ContainerOptions, Diagnostics, } from './container/index';
 export { METADATA_KEYS, HttpMethod, ParamType, Scope } from './constants';
 export { Controller, Version, Get, Post, Put, Patch, Delete, Options, Head, All, Sse, Param, Query, Body, Headers, Req, Res, Ip, Cookie, Cookies, RawBody, HttpCode, Header, Redirect, createParamDecorator, createLazyParamDecorator, applyDecorators, } from './http/index';
 export { REQUEST_CONTEXT } from './http/request-context';

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,32 @@ 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
+                };
+            }
+        }
+    }
     const document = {
         openapi: '3.1.0',
         info: {

package/dist/registry/types.d.ts

@@ -1,7 +1,7 @@
 import type { Context } from 'hono';
 import type { CanActivate, ExceptionFilter, NestInterceptor, NestMiddleware, PipeTransform } from '../pipeline/types';
-import type { Constructor, ForwardRef, InjectionToken, ProviderOptions, Token, Type } from '../container/types';
-export type { Constructor, ForwardRef, InjectionToken, ProviderOptions, Token, Type };
+import type { Constructor, ForwardRef, InferToken, InferTokens, InjectionToken, ProviderOptions, Token, Type } from '../container/types';
+export type { Constructor, ForwardRef, InferToken, InferTokens, InjectionToken, ProviderOptions, Token, Type };
 export type ComponentType = 'middleware' | 'guard' | 'pipe' | 'interceptor' | 'filter';
 export type MiddlewareType = Type<NestMiddleware> | NestMiddleware;
 export type GuardType = Type<CanActivate> | CanActivate;
@@ -38,10 +38,30 @@ export interface HttpHandlerMeta {
     };
 }
 export type ModuleImport = Type | DynamicModule | ForwardRef;
-export interface AsyncModuleOptions<T = unknown> {
+/**
+ * Async module options with **type-inferred `useFactory` parameters**.
+ *
+ * The `Inject` generic captures the literal `inject` tuple via `const` type
+ * parameter inference at the call site (TS 5.0+ — vela already requires it).
+ * `useFactory`'s parameter types are computed from that tuple via
+ * `InferTokens<Inject>`, so:
+ *
+ * ```ts
+ * SomeModule.forRootAsync({
+ *   inject: [D1Service, ConfigService],   // captured as readonly [typeof D1Service, typeof ConfigService]
+ *   useFactory: (d1, config) => { ... },  // d1: D1Service, config: ConfigService — inferred
+ * });
+ * ```
+ *
+ * Backwards compatible: when `inject` isn't a literal tuple (or is omitted),
+ * `Inject` falls back to `readonly Token<unknown>[]`, `InferTokens` resolves
+ * to `unknown[]`, and `useFactory` accepts variadic `unknown[]` — the prior
+ * loose-typing behavior. Existing callers don't break.
+ */
+export interface AsyncModuleOptions<T = unknown, Inject extends readonly Token<unknown>[] = readonly Token<unknown>[]> {
     imports?: ModuleImport[];
-    useFactory: (...args: any[]) => T | Promise<T>;
-    inject?: Token[];
+    inject?: Inject;
+    useFactory: (...args: InferTokens<Inject>) => T | Promise<T>;
 }
 export interface DynamicModule {
     module: Type;

package/package.json

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