@velajs/vela 1.10.0 → 1.13.0

package/dist/factory/bootstrap.js

@@ -1,11 +1,11 @@
 import { Scope } from "../constants.js";
 import { Container } from "../container/container.js";
 import { ModuleRef } from "../container/module-ref.js";
+import { DiscoveryService } from "../discovery/discovery.service.js";
 import { REQUEST_CONTEXT } from "../http/request-context.js";
 import { RouteManager } from "../http/route.manager.js";
 import { ModuleLoader } from "../module/module-loader.js";
 import { bindAppProviders } from "../pipeline/app-providers.js";
-import { ComponentManager } from "../pipeline/component.manager.js";
 import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE } from "../pipeline/tokens.js";
 /**
  * Wire the DI graph for `rootModule` and prepare the route manager — without
@@ -32,6 +32,15 @@ import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE } from
         ]
     });
     container.markGlobalToken(ModuleRef);
+    // Decorator-driven discovery — global so any provider can inject it.
+    container.register({
+        provide: DiscoveryService,
+        useFactory: (c)=>new DiscoveryService(c),
+        inject: [
+            Container
+        ]
+    });
+    container.markGlobalToken(DiscoveryService);
     for (const t of [
         APP_GUARD,
         APP_PIPE,
@@ -61,8 +70,11 @@ import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE } from
         useValue: routeManager
     });
     container.markGlobalToken(RouteManager);
-    ComponentManager.init(container);
     const loader = new ModuleLoader(container, routeManager);
+    // loader.load() also arms the deferred-init seam (LazyModuleManager) — kept
+    // inside the loader so hand-rolled bootstrap paths that never call this
+    // function (@velajs/testing's TestingModuleBuilder.compile) get identical
+    // lazy semantics.
     loader.load(rootModule);
     bindAppProviders(routeManager, container, loader);
     routeManager.registerConsumerMiddleware(loader.getConsumerMiddlewareDefinitions());

package/dist/factory.d.ts

@@ -1,6 +1,16 @@
 import { VelaApplication } from './application';
 import type { Type } from './container/types';
+import type { RuntimeAdapter } from './factory/adapter';
 import type { BootstrapOptions } from './factory/bootstrap';
+export interface VelaCreateOptions extends BootstrapOptions {
+    /**
+     * Runtime adapters binding this app to a platform (Cloudflare bindings,
+     * WebSocket transports, …). Their `requestMiddleware` is prepended to the
+     * global middleware chain; `onBootstrap`/`onRoutesBuilt` hooks run around
+     * route building. See {@link RuntimeAdapter}.
+     */
+    adapters?: RuntimeAdapter[];
+}
 export declare const VelaFactory: {
-    create(rootModule: Type, options?: BootstrapOptions): Promise<VelaApplication>;
+    create(rootModule: Type, options?: VelaCreateOptions): Promise<VelaApplication>;
 };

package/dist/factory.js

@@ -1,15 +1,36 @@
 import { VelaApplication } from "./application.js";
+import { DiscoveryService } from "./discovery/discovery.service.js";
 import { bootstrap } from "./factory/bootstrap.js";
 export const VelaFactory = {
     async create (rootModule, options = {}) {
-        const { container, routeManager, loader } = await bootstrap(rootModule, options);
+        const { adapters = [], ...bootstrapOptions } = options;
+        const adapterMiddleware = adapters.flatMap((a)=>a.requestMiddleware ?? []);
+        if (adapterMiddleware.length > 0) {
+            bootstrapOptions.middleware = [
+                ...adapterMiddleware,
+                ...bootstrapOptions.middleware ?? []
+            ];
+        }
+        const { container, routeManager, loader } = await bootstrap(rootModule, bootstrapOptions);
         const app = new VelaApplication(container, routeManager);
         const instances = await loader.resolveAllInstances();
         app.setInstances(instances);
         await app.callOnModuleInit();
         await app.callOnApplicationBootstrap();
-        // Build routes (async — supports CRUD integration with dynamic imports)
+        const adapterContext = {
+            app,
+            container,
+            routeManager,
+            discovery: container.resolve(DiscoveryService)
+        };
+        for (const adapter of adapters){
+            await adapter.onBootstrap?.(adapterContext);
+        }
+        // Build routes (async — supports route-contributor integration)
         await app.initRoutes();
+        for (const adapter of adapters){
+            await adapter.onRoutesBuilt?.(adapterContext);
+        }
         return app;
     }
 };

package/dist/http/handler-executor.js

@@ -1,6 +1,7 @@
-import { ForbiddenException, HttpException } from "../errors/http-exception.js";
+import { HttpException } from "../errors/http-exception.js";
 import { ComponentManager } from "../pipeline/component.manager.js";
 import { shouldFilterCatch } from "../pipeline/decorators.js";
+import { PipelineRunner } from "../pipeline/pipeline-runner.js";
 import { getHttpCode, getRedirect, getResponseHeaders } from "./decorators.js";
 import { buildExecutionContext } from "./execution-context.js";
 import { instantiateMany } from "./instantiate.js";
@@ -25,12 +26,12 @@ export class HandlerExecutor {
         // Routed via Reflect so the polyfill funnels both src-level and dist-level
         // consumers to the same registry (matters in tests that import from dist).
         const paramTypes = Reflect.getMetadata('design:paramtypes', controller.prototype, route.handlerName);
-        const methodGuards = ComponentManager.getComponents('guard', controller, route.handlerName);
-        const methodPipes = ComponentManager.getComponents('pipe', controller, route.handlerName);
-        const methodInterceptors = ComponentManager.getComponents('interceptor', controller, route.handlerName);
+        const methodGuards = ComponentManager.getScopedComponents('guard', controller, route.handlerName);
+        const methodPipes = ComponentManager.getScopedComponents('pipe', controller, route.handlerName);
+        const methodInterceptors = ComponentManager.getScopedComponents('interceptor', controller, route.handlerName);
         // Filters: reverse order (handler → controller → global) — closest to handler runs first
         const methodFilters = [
-            ...ComponentManager.getComponents('filter', controller, route.handlerName)
+            ...ComponentManager.getScopedComponents('filter', controller, route.handlerName)
         ].reverse();
         const httpCode = getHttpCode(controller, route.handlerName);
         const responseHeaders = getResponseHeaders(controller, route.handlerName);
@@ -58,24 +59,20 @@ export class HandlerExecutor {
             const executionContext = buildExecutionContext(c, controller, route.handlerName);
             try {
                 const instance = requestContainer.resolve(controller);
-                // 1. Extract args + run pipes (vela order: args before guards).
-                const args = await this.argumentResolver.extract(c, paramMetadata, pipes, requestContainer, paramTypes);
-                // 2. Guards (fail-fast).
-                for (const guard of guards){
-                    const canActivate = await guard.canActivate(executionContext);
-                    if (!canActivate) {
-                        throw new ForbiddenException();
-                    }
-                }
-                // 3. Get handler method.
                 const method = Reflect.get(instance, route.handlerName);
                 if (typeof method !== 'function') {
                     throw new Error(`Method ${String(route.handlerName)} not found on controller`);
                 }
-                // 4. Build core handler.
-                const coreHandler = async ()=>Reflect.apply(method, instance, args);
-                // 5. Run interceptor chain.
-                const result = await ComponentManager.runInterceptorChain(interceptors, executionContext, coreHandler);
+                // Args + pipes → guards → interceptor chain → handler, via the shared
+                // runner. `argsBeforeGuards` preserves the deliberate vela HTTP order.
+                const result = await PipelineRunner.run({
+                    context: executionContext,
+                    guards,
+                    interceptors,
+                    argsBeforeGuards: true,
+                    resolveArgs: ()=>this.argumentResolver.extract(c, paramMetadata, pipes, requestContainer, paramTypes),
+                    invoke: async (args)=>Reflect.apply(method, instance, args)
+                });
                 if (redirect) {
                     return mapRedirect(c, result, redirect);
                 }
@@ -98,6 +95,12 @@ export class HandlerExecutor {
                     const status = error.getStatus();
                     return c.json(response, status);
                 }
+                // An unknown error reaching here means no filter claimed it — never
+                // swallow it silently: the response is a generic 500, but the cause
+                // must land in the logs (diagnostics 'silent' opts out).
+                if (requestContainer.getDiagnostics() !== 'silent') {
+                    console.error(`[vela] unhandled error in ${controller.name}.${String(route.handlerName)}:`, error);
+                }
                 return c.json({
                     statusCode: 500,
                     message: 'Internal Server Error'

package/dist/http/route-contributor.d.ts

@@ -0,0 +1,68 @@
+import type { Hono } from 'hono';
+import type { Container } from '../container/container';
+import type { Type } from '../container/types';
+import type { OpenApiPathItem } from '../openapi/types';
+import type { CanActivate } from '../pipeline/types';
+/**
+ * Context passed to {@link RouteContributor.buildRoutes} for each controller
+ * the contributor claims. The contributor receives the framework's resolved
+ * view of the world so generated routes behave identically to hand-written
+ * ones: same global prefix, same global guard instances, same path joining.
+ */
+export interface RouteContributorContext {
+    /** The claimed controller class. */
+    controller: Type;
+    /** Controller-level prefix as registered with `@Controller(...)`. */
+    controllerPrefix: string;
+    /** The metadata value (under `claimsMetaKey`) that claimed this controller. */
+    meta: unknown;
+    /** Application-wide path prefix (e.g. `/api`), already normalized. */
+    globalPrefix: string;
+    /** Global guard instances, pre-resolved from the root container. */
+    globalGuards: CanActivate[];
+    /** The app's root container — resolve controller/services from here. */
+    container: Container;
+    /** Path joiner used by the framework — handles slash normalization. */
+    joinPaths: (...parts: string[]) => string;
+}
+/** Context for {@link RouteContributor.buildOpenApiPaths}. */
+export interface RouteContributorOpenApiContext {
+    controller: Type;
+    meta: unknown;
+    /** Application-wide path prefix (e.g. `/api`), already normalized. */
+    globalPrefix: string;
+    /** Controller-level prefix as registered with `@Controller(...)`. */
+    controllerPrefix: string;
+}
+/**
+ * A route generator that claims controllers by class-level metadata and
+ * mounts routes for them — the public extension point behind `@Crud()` (and
+ * any future metadata-driven route generator: storage HTTP surfaces, admin
+ * panels, RPC bridges).
+ *
+ * Register once at import time (`registerRouteContributor`); the framework
+ * consults contributors during `RouteManager.build` — AFTER all explicit
+ * `@Get`/`@Post` routes, so generated `/:id` catch-alls never shadow custom
+ * routes — and during OpenAPI document generation.
+ *
+ * This contract exists instead of dynamic `import()` because esbuild leaves
+ * `await import(variable)` as a runtime import Cloudflare Workers cannot
+ * resolve.
+ */
+export interface RouteContributor {
+    /** Stable identifier; re-registering the same id overwrites (HMR-friendly). */
+    id: string;
+    /** Class-level metadata key whose presence claims a controller. */
+    claimsMetaKey: string;
+    buildRoutes(app: Hono, ctx: RouteContributorContext): void | Promise<void>;
+    buildOpenApiPaths?(ctx: RouteContributorOpenApiContext): Record<string, OpenApiPathItem>;
+}
+/** Register a contributor. Last registration per `id` wins. */
+export declare function registerRouteContributor(contributor: RouteContributor): void;
+/** All registered contributors (registration order). */
+export declare function getRouteContributors(): RouteContributor[];
+/**
+ * Reset all contributor registrations. Test-only.
+ * @internal
+ */
+export declare function _resetRouteContributors(): void;

package/dist/http/route-contributor.js

@@ -0,0 +1,22 @@
+// Contributors register at import time (package side effect), so the store is
+// anchored on `globalThis` like MetadataRegistry state: a Vite HMR re-eval
+// reuses the same store instead of minting an empty one.
+const STORE_KEY = Symbol.for('vela:route-contributors:v1');
+function store() {
+    const g = globalThis;
+    return g[STORE_KEY] ??= new Map();
+}
+/** Register a contributor. Last registration per `id` wins. */ export function registerRouteContributor(contributor) {
+    store().set(contributor.id, contributor);
+}
+/** All registered contributors (registration order). */ export function getRouteContributors() {
+    return [
+        ...store().values()
+    ];
+}
+/**
+ * Reset all contributor registrations. Test-only.
+ * @internal
+ */ export function _resetRouteContributors() {
+    store().clear();
+}

package/dist/http/route.manager.js

@@ -5,7 +5,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 { getRouteContributors } from "./route-contributor.js";
 import { buildMiddlewareExecutionContext } from "./execution-context.js";
 import { HandlerExecutor } from "./handler-executor.js";
 import { instantiate, instantiateMany } from "./instantiate.js";
@@ -177,6 +177,11 @@ export class RouteManager {
             if (typeof inst.priority === 'number') return inst.priority;
             if (typeof inst.constructor?.priority === 'number') return inst.constructor.priority;
         }
+        // A token owned exclusively by unmaterialized lazy modules must not be
+        // instantiate-probed here — the probe at route build would defeat the
+        // module's deferral (i18n's APP_MIDDLEWARE). Default priority instead;
+        // the middleware still materializes on its first request.
+        if (this.container.isLazyPending(entry)) return 0;
         try {
             const resolved = instantiate(entry, this.container);
             if (resolved && typeof resolved === 'object') {
@@ -348,7 +353,9 @@ export class RouteManager {
                 for (const route of routes){
                     const effectiveVersion = route.version ?? metadata.version;
                     const versionedPaths = this.buildVersionedPaths(this.globalPrefix, metadata.prefix, route.path, effectiveVersion);
-                    const middlewareItems = ComponentManager.getComponents('middleware', controller, route.handlerName);
+                    // Scoped (controller/handler) middleware only — global middleware is
+                    // applied once by this manager's own global pass, never re-read here.
+                    const middlewareItems = ComponentManager.getScopedComponents('middleware', controller, route.handlerName);
                     const handler = this.handlerExecutor.create(route, controller, allParamMetadata);
                     for (const fullPath of versionedPaths){
                         for (const middlewareItem of middlewareItems){
@@ -363,26 +370,33 @@ 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.
+        // Second pass: route contributors (generated routes registered last, so a
+        // contributor's `/:id` catch-alls never shadow explicit routes). Each
+        // contributor claims controllers by class-level metadata; `@velajs/crud`
+        // registers one as an import side effect. The registry contract (instead
+        // of dynamic `import()`) exists because esbuild leaves
+        // `await import(variable)` as a runtime import Cloudflare Workers cannot
+        // resolve.
+        const contributors = getRouteContributors();
         for (const { controller, metadata } of this.controllers){
-            const crudConfig = getMetadata('vela:crud', controller);
-            if (!crudConfig) continue;
-            const bridge = getCrudBridge();
-            if (!bridge) {
+            for (const contributor of contributors){
+                const meta = getMetadata(contributor.claimsMetaKey, controller);
+                if (meta === undefined) continue;
+                await contributor.buildRoutes(app, {
+                    controller,
+                    controllerPrefix: metadata.prefix,
+                    meta,
+                    globalPrefix: this.globalPrefix,
+                    globalGuards: instantiateMany(this.globalGuards, this.container),
+                    container: this.container,
+                    joinPaths
+                });
+            }
+            // DX guard for the common mistake: @Crud() metadata present but the
+            // contributor package never imported.
+            if (getMetadata('vela:crud', controller) !== undefined && !contributors.some((c)=>c.claimsMetaKey === 'vela:crud')) {
                 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/i18n/i18n.module.js

@@ -20,7 +20,10 @@ const { ConfigurableModuleClass } = new ConfigurableModuleBuilder({
 // Empty marker module for `registerMessages`. The contribution is a side-effect
 // on the global MessageRegistry; this carries NO providers so it never
 // duplicates I18nModule's providers (which would trip vela's multi-instance
-// encapsulation → MultipleProvidersFoundError).
+// encapsulation → MultipleProvidersFoundError). New modules whose contribution
+// is providers (not an external registry) should use `sideEffectModule` from
+// the authoring kit; this predates it and keeps a shared-class identity so
+// identical message trees dedup as one module instance.
 let I18nMessagesModule = class I18nMessagesModule {
 };
 I18nMessagesModule = _ts_decorate([
@@ -41,6 +44,11 @@ export class I18nModule extends ConfigurableModuleClass {
 }
 I18nModule = _ts_decorate([
     Module({
+        // Lazy: the merged-message snapshot (MessageLoaderService constructor) and
+        // locale middleware materialize on the first request that reaches them —
+        // message registration itself is import-time and unaffected. Safe because
+        // the route-build priority probe skips lazy-pending APP_MIDDLEWARE tokens.
+        lazy: true,
         providers: [
             MessageRegistry,
             MessageLoaderService,

package/dist/index.d.ts

@@ -33,12 +33,21 @@ export { HealthModule, HealthCheckService, HealthIndicatorService, HttpHealthInd
 export type { HealthCheckResult, HealthCheckStatus, HealthIndicatorResult, HealthIndicatorFunction, ResponseCheckCallback, HttpPingOptions, } from './health/index';
 export { ThrottlerModule, ThrottlerGuard, ThrottlerStorage, Throttle, SkipThrottle, THROTTLER_OPTIONS, THROTTLER_STORAGE, THROTTLE_METADATA, SKIP_THROTTLE_METADATA, } from './throttler/index';
 export type { ThrottlerModuleOptions, ThrottleConfig, ThrottlerStore, ThrottlerStorageRecord, RateLimitInfo, } from './throttler/index';
-export { Global, Module, defineDynamicModule, stableHash, ConfigurableModuleBuilder, defineConfigurableModule, } from './module/index';
-export type { ModuleOptions, DynamicModule, AsyncModuleOptions, ModuleImport, ConfigurableModuleAsyncOptions, ConfigurableModuleBuilderOptions, ConfigurableModuleClassType, ConfigurableModuleExtras, ConfigurableModuleExtrasTransform, ConfigurableModuleHost, ConfigurableModuleOptionsFactory, DefineConfigurableModuleSpec, } from './module/index';
+export { Global, Module, defineDynamicModule, stableHash, moduleKey, ConfigurableModuleBuilder, defineConfigurableModule, defineModule, buildAsyncOptionsProviders, lazyProvider, moduleToken, provideGlobal, sideEffectModule, } from './module/index';
+export type { ModuleOptions, DynamicModule, AsyncModuleOptions, ModuleImport, ConfigurableModuleAsyncOptions, ConfigurableModuleBuilderOptions, ConfigurableModuleClassType, ConfigurableModuleExtras, ConfigurableModuleExtrasTransform, ConfigurableModuleHost, ConfigurableModuleOptionsFactory, DefineConfigurableModuleSpec, DefineModuleSpec, GlobalComponentSlot, ModuleContributions, ModuleSetupContext, LazyProviderSpec, } from './module/index';
 export type { MiddlewareConsumer, NestModule, RouteInfo } from './http/index';
+export { DiscoveryService, createDiscoverableDecorator, } from './discovery/index';
+export type { DiscoveredClass, DiscoveredMethodMeta, DiscoveryFilter, DiscoverableDecorator, CreateDiscoverableDecoratorOptions, } from './discovery/index';
+export { EntrypointRegistry, registerEntrypointKind, getEntrypointKinds, contributesEntrypoints, runInEntrypointScope, buildEntrypointExecutionContext, } from './entrypoint/index';
+export type { ContributesEntrypoints, Entrypoint, EntrypointKind, EntrypointExecutionContext, } from './entrypoint/index';
+export { registerRouteContributor, getRouteContributors, } from './http/route-contributor';
+export type { RouteContributor, RouteContributorContext, RouteContributorOpenApiContext, } from './http/route-contributor';
+export type { AdapterContext, RuntimeAdapter } from './factory/adapter';
+export type { VelaCreateOptions } from './factory';
 export { definePlugin, composePlugins, PluginRegistry, PluginRootModule, PLUGIN_REGISTRY_TOKEN, } from './plugin/plugin';
 export type { Plugin } from './plugin/plugin';
-export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, SetMetadata, Reflector, APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE, } from './pipeline/index';
+export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, SetMetadata, Reflector, PipelineRunner, getCatchTypes, shouldFilterCatch, APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE, } from './pipeline/index';
+export type { PipelineRunOptions } from './pipeline/index';
 export type { HttpArgumentsHost, ExecutionContext, CanActivate, CallHandler, NestInterceptor, NestMiddleware, PipeTransform, ExceptionFilter, ArgumentMetadata, ReflectableDecorator, CreateDecoratorOptions, } from './pipeline/index';
 export type { Constructor, MiddlewareType, GuardType, PipeType, InterceptorType, FilterType, } from './registry/index';
 export { ParseIntPipe, ParseFloatPipe, ParseBoolPipe, ParseUUIDPipe, ParseEnumPipe, ParseArrayPipe, DefaultValuePipe, RequiredPipe, ZodValidationPipe, } from './pipeline/index';

package/dist/index.js

@@ -37,11 +37,18 @@ export { HealthModule, HealthCheckService, HealthIndicatorService, HttpHealthInd
 // Throttler
 export { ThrottlerModule, ThrottlerGuard, ThrottlerStorage, Throttle, SkipThrottle, THROTTLER_OPTIONS, THROTTLER_STORAGE, THROTTLE_METADATA, SKIP_THROTTLE_METADATA } from "./throttler/index.js";
 // Module
-export { Global, Module, defineDynamicModule, stableHash, ConfigurableModuleBuilder, defineConfigurableModule } from "./module/index.js";
+export { Global, Module, defineDynamicModule, stableHash, moduleKey, ConfigurableModuleBuilder, defineConfigurableModule, defineModule, buildAsyncOptionsProviders, lazyProvider, moduleToken, provideGlobal, sideEffectModule } from "./module/index.js";
+// Discovery — decorator-driven provider discovery (the public replacement for
+// hand-rolled bootstrap scans)
+export { DiscoveryService, createDiscoverableDecorator } from "./discovery/index.js";
+// Entrypoints — the open non-HTTP entry surface (websocket, queue, cron, …)
+export { EntrypointRegistry, registerEntrypointKind, getEntrypointKinds, contributesEntrypoints, runInEntrypointScope, buildEntrypointExecutionContext } from "./entrypoint/index.js";
+// Route contribution — metadata-claimed route generators (@Crud-style)
+export { registerRouteContributor, getRouteContributors } from "./http/route-contributor.js";
 // Plugin manifest + composer
 export { definePlugin, composePlugins, PluginRegistry, PluginRootModule, PLUGIN_REGISTRY_TOKEN } from "./plugin/plugin.js";
 // Pipeline Decorators
-export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, SetMetadata, Reflector, APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE } from "./pipeline/index.js";
+export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, SetMetadata, Reflector, PipelineRunner, getCatchTypes, shouldFilterCatch, APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE } from "./pipeline/index.js";
 // Built-in Pipes
 export { ParseIntPipe, ParseFloatPipe, ParseBoolPipe, ParseUUIDPipe, ParseEnumPipe, ParseArrayPipe, DefaultValuePipe, RequiredPipe, ZodValidationPipe } from "./pipeline/index.js";
 // Errors

package/dist/internal.d.ts

@@ -5,8 +5,6 @@ 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,13 +6,6 @@ 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/module/configurable-module.builder.d.ts

@@ -1,11 +1,23 @@
 import type { DynamicModule } from '../registry/types';
 import type { ConfigurableModuleBuilderOptions, ConfigurableModuleExtras, ConfigurableModuleExtrasTransform, ConfigurableModuleHost, DefineConfigurableModuleSpec } from './configurable-module.types';
+/**
+ * Blessed key-derivation helper for hand-written `forRoot` statics: the one
+ * documented way to derive a `DynamicModule.key` from an options bag so
+ * identical configurations dedup (HMR-idempotent) and distinct ones coexist.
+ * Alias of {@link stableHash} with a module-authoring name.
+ */
+export declare const moduleKey: (options: unknown) => string;
 /**
  * NestJS-parity builder that generates `forRoot`/`forRootAsync` (and `key`,
  * `global`, factory-param inference) from a tiny spec — so a module is just its
  * tokens + options type + service + a `@Module({...})` bag, while vela keeps its
  * encapsulation (`exports`/visibility) and multi-instance `key` dedup.
  *
+ * Since 1.11 this is a thin adapter over {@link defineModule} — the single
+ * authoring engine. Prefer `defineModule` for new modules: it additionally
+ * supports contributions (providers/controllers/imports/exports/global
+ * components) computed as functions of the options.
+ *
  * @example
  * ```ts
  * const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } =

package/dist/module/configurable-module.builder.js

@@ -1,18 +1,22 @@
-import { InjectionToken } from "../container/types.js";
+import { defineModule } from "./define-module.js";
 import { stableHash } from "./stable-hash.js";
-/** Default extra: `isGlobal` toggles `DynamicModule.global`, hiding the naming split. */ const DEFAULT_EXTRAS = {
-    isGlobal: false
-};
-const DEFAULT_TRANSFORM = (def, extras)=>extras.isGlobal ? {
-        ...def,
-        global: true
-    } : def;
+/**
+ * Blessed key-derivation helper for hand-written `forRoot` statics: the one
+ * documented way to derive a `DynamicModule.key` from an options bag so
+ * identical configurations dedup (HMR-idempotent) and distinct ones coexist.
+ * Alias of {@link stableHash} with a module-authoring name.
+ */ export const moduleKey = stableHash;
 /**
  * NestJS-parity builder that generates `forRoot`/`forRootAsync` (and `key`,
  * `global`, factory-param inference) from a tiny spec — so a module is just its
  * tokens + options type + service + a `@Module({...})` bag, while vela keeps its
  * encapsulation (`exports`/visibility) and multi-instance `key` dedup.
  *
+ * Since 1.11 this is a thin adapter over {@link defineModule} — the single
+ * authoring engine. Prefer `defineModule` for new modules: it additionally
+ * supports contributions (providers/controllers/imports/exports/global
+ * components) computed as functions of the options.
+ *
  * @example
  * ```ts
  * const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } =
@@ -28,8 +32,8 @@ const DEFAULT_TRANSFORM = (def, extras)=>extras.isGlobal ? {
     options;
     classMethodName = 'forRoot';
     factoryMethodName = 'create';
-    extrasDefaults = DEFAULT_EXTRAS;
-    extrasTransform = DEFAULT_TRANSFORM;
+    extrasDefaults;
+    extrasTransform;
     constructor(options = {}){
         this.options = options;
     }
@@ -47,112 +51,15 @@ const DEFAULT_TRANSFORM = (def, extras)=>extras.isGlobal ? {
         return this;
     }
     build() {
-        const moduleName = this.options.moduleName ?? 'ConfigurableModule';
-        const optionsToken = this.options.optionsInjectionToken ?? new InjectionToken(`${moduleName}_MODULE_OPTIONS`);
-        const syncName = this.classMethodName;
-        const asyncName = `${this.classMethodName}Async`;
-        const factoryMethodName = this.factoryMethodName;
-        const extrasDefaults = this.extrasDefaults;
-        const transform = this.extrasTransform;
-        let ConfigurableModuleClass = class ConfigurableModuleClass {
-        };
-        Object.defineProperty(ConfigurableModuleClass, syncName, {
-            configurable: true,
-            writable: true,
-            enumerable: false,
-            value (options = {}) {
-                const { key, ...rest } = options;
-                const definition = {
-                    module: this,
-                    key: key ?? stableHash(rest),
-                    providers: [
-                        {
-                            provide: optionsToken,
-                            useValue: rest
-                        }
-                    ]
-                };
-                return transform(definition, {
-                    ...extrasDefaults,
-                    ...rest
-                });
-            }
+        return defineModule({
+            name: this.options.moduleName ?? 'ConfigurableModule',
+            optionsToken: this.options.optionsInjectionToken,
+            extras: this.extrasDefaults,
+            transform: this.extrasTransform,
+            methodName: this.classMethodName,
+            factoryMethodName: this.factoryMethodName
         });
-        Object.defineProperty(ConfigurableModuleClass, asyncName, {
-            configurable: true,
-            writable: true,
-            enumerable: false,
-            value (options = {}) {
-                const { key, imports, inject, useFactory, useClass, useExisting, ...restExtras } = options;
-                const definition = {
-                    module: this,
-                    // Include extras (e.g. isGlobal) in the key — like forRoot — so two
-                    // async instances differing only in an extra don't wrongly dedup.
-                    key: key ?? stableHash({
-                        inject,
-                        useFactory,
-                        useClass,
-                        useExisting,
-                        ...restExtras
-                    }),
-                    imports: imports ?? [],
-                    providers: buildAsyncOptionsProviders(optionsToken, factoryMethodName, {
-                        inject,
-                        useFactory,
-                        useClass,
-                        useExisting
-                    })
-                };
-                return transform(definition, {
-                    ...extrasDefaults,
-                    ...restExtras
-                });
-            }
-        });
-        return {
-            ConfigurableModuleClass: ConfigurableModuleClass,
-            MODULE_OPTIONS_TOKEN: optionsToken,
-            // Type-only sentinels — never read at runtime.
-            OPTIONS_TYPE: undefined,
-            ASYNC_OPTIONS_TYPE: undefined
-        };
-    }
-}
-/** Lower `useFactory`/`useClass`/`useExisting` async options into provider registrations. */ function buildAsyncOptionsProviders(optionsToken, factoryMethodName, async) {
-    if (async.useFactory) {
-        return [
-            {
-                provide: optionsToken,
-                useFactory: async.useFactory,
-                inject: async.inject ?? []
-            }
-        ];
-    }
-    if (async.useClass) {
-        const factoryClass = async.useClass;
-        return [
-            factoryClass,
-            {
-                provide: optionsToken,
-                useFactory: (instance)=>instance[factoryMethodName](),
-                inject: [
-                    factoryClass
-                ]
-            }
-        ];
-    }
-    if (async.useExisting) {
-        return [
-            {
-                provide: optionsToken,
-                useFactory: (instance)=>instance[factoryMethodName](),
-                inject: [
-                    async.useExisting
-                ]
-            }
-        ];
     }
-    throw new Error('Async module options require one of `useFactory`, `useClass`, or `useExisting`.');
 }
 /**
  * Lower-level engine for cases a class-mixin can't express — chiefly a