@velajs/vela 1.4.0 → 1.5.0

package/dist/http/route.manager.js

@@ -1,28 +1,14 @@
 import { Hono } from "hono";
-import { getCookie } from "hono/cookie";
-import { HttpMethod, ParamType } from "../constants.js";
+import { HttpMethod } from "../constants.js";
 import { getMetadata } from "../metadata.js";
 import { joinPaths } from "../registry/paths.js";
-import { buildExecutionContext } from "./execution-context.js";
+import { ArgumentResolver } from "./argument-resolver.js";
+import { HandlerExecutor } from "./handler-executor.js";
+import { instantiate, instantiateMany } from "./instantiate.js";
 import { REQUEST_CONTEXT, createRequestContext } from "./request-context.js";
-import { ForbiddenException, HttpException } from "../errors/http-exception.js";
 import { ComponentManager } from "../pipeline/component.manager.js";
-import { shouldFilterCatch } from "../pipeline/decorators.js";
 import { MetadataRegistry } from "../registry/metadata.registry.js";
-import { getHttpCode, getRedirect, getResponseHeaders } from "./decorators.js";
 const defaultGetClientIp = (c)=>c.req.raw.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ?? c.req.raw.headers.get('x-real-ip') ?? null;
-function parseRedirectResult(result) {
-    if (typeof result !== 'object' || result === null) return undefined;
-    if (!('url' in result)) return undefined;
-    const obj = result;
-    if (typeof obj.url !== 'string') return undefined;
-    return {
-        url: obj.url,
-        ...typeof obj.statusCode === 'number' ? {
-            statusCode: obj.statusCode
-        } : {}
-    };
-}
 export class RouteManager {
     container;
     static METHOD_REGISTRAR = new Map([
@@ -59,48 +45,6 @@ export class RouteManager {
             (app, p, h)=>app.all(p, h)
         ]
     ]);
-    static PARAM_EXTRACTORS = new Map([
-        [
-            ParamType.PARAM,
-            (c, p)=>p.name ? c.req.param(p.name) : c.req.param()
-        ],
-        [
-            ParamType.QUERY,
-            (c, p)=>p.name ? c.req.query(p.name) : c.req.query()
-        ],
-        [
-            ParamType.BODY,
-            async (c, p)=>{
-                let body;
-                try {
-                    body = await c.req.json();
-                } catch  {
-                    return undefined;
-                }
-                return p.name && body !== null && typeof body === 'object' ? body[p.name] : body;
-            }
-        ],
-        [
-            ParamType.HEADERS,
-            (c, p)=>p.name ? c.req.header(p.name) : c.req.header()
-        ],
-        [
-            ParamType.REQUEST,
-            (c)=>c
-        ],
-        [
-            ParamType.RESPONSE,
-            (c)=>c
-        ],
-        [
-            ParamType.COOKIE,
-            (c, p)=>p.name ? getCookie(c, p.name) : getCookie(c)
-        ],
-        [
-            ParamType.RAW_BODY,
-            async (c)=>new Uint8Array(await c.req.arrayBuffer())
-        ]
-    ]);
     controllers = [];
     globalMiddleware = [];
     globalPipes = [];
@@ -109,10 +53,16 @@ export class RouteManager {
     globalFilters = [];
     globalPrefix = '';
     consumerMiddlewareDefinitions = [];
-    ipExtractor;
+    handlerExecutor;
     constructor(container, options = {}){
         this.container = container;
-        this.ipExtractor = options.getClientIp ?? defaultGetClientIp;
+        const argumentResolver = new ArgumentResolver(options.getClientIp ?? defaultGetClientIp);
+        this.handlerExecutor = new HandlerExecutor(argumentResolver, ()=>({
+                guards: this.globalGuards,
+                pipes: this.globalPipes,
+                interceptors: this.globalInterceptors,
+                filters: this.globalFilters
+            }), (c)=>this.getRequestContainer(c));
     }
     registerConsumerMiddleware(definitions) {
         this.consumerMiddlewareDefinitions.push(...definitions);
@@ -162,21 +112,6 @@ export class RouteManager {
         this.globalFilters.push(...filterTokens);
         return this;
     }
-    instantiate(classOrInstance, container) {
-        if (typeof classOrInstance === 'function') {
-            if (container.has(classOrInstance)) {
-                return container.resolve(classOrInstance);
-            }
-            return new classOrInstance();
-        }
-        if (container.has(classOrInstance)) {
-            return container.resolve(classOrInstance);
-        }
-        return classOrInstance;
-    }
-    instantiateMany(items, container) {
-        return items.map((item)=>this.instantiate(item, container));
-    }
     getMiddlewarePriority(entry) {
         if (entry == null) return 0;
         if (typeof entry === 'function') {
@@ -189,7 +124,7 @@ export class RouteManager {
             if (typeof inst.constructor?.priority === 'number') return inst.constructor.priority;
         }
         try {
-            const resolved = this.instantiate(entry, this.container);
+            const resolved = instantiate(entry, this.container);
             if (resolved && typeof resolved === 'object') {
                 const p = resolved.priority;
                 if (typeof p === 'number') return p;
@@ -215,6 +150,9 @@ export class RouteManager {
         const prefix = MetadataRegistry.getControllerPath(controller);
         const options = MetadataRegistry.getControllerOptions(controller);
         const routes = MetadataRegistry.getRoutes(controller);
+        // The ModuleLoader registers controllers in their owning module's bucket;
+        // fall back to a `__root__` registration only for controllers that arrive
+        // here outside the module-loading flow (test harnesses, custom adapters).
         if (!this.container.has(controller)) {
             this.container.register(controller);
         }
@@ -237,21 +175,18 @@ export class RouteManager {
                 index,
                 priority: this.getMiddlewarePriority(entry)
             })).sort((a, b)=>a.priority - b.priority || a.index - b.index);
-        // Register global middleware on the Hono app
         for (const { entry } of sortedGlobal){
             app.use('*', (c, next)=>{
                 const requestContainer = this.getRequestContainer(c);
-                const resolved = this.instantiate(entry, requestContainer);
+                const resolved = instantiate(entry, requestContainer);
                 return resolved.use(c, next);
             });
         }
-        // Sort consumer middleware with the same stable-by-index rule.
         const sortedConsumer = this.consumerMiddlewareDefinitions.map((def, index)=>({
                 def,
                 index,
                 priority: def.priority ?? 0
             })).sort((a, b)=>a.priority - b.priority || a.index - b.index);
-        // Register MiddlewareConsumer-configured middleware
         for (const { def } of sortedConsumer){
             const matchRoute = this.compileRouteMatcher(def.routes);
             const matchExclude = this.compileRouteMatcher(def.excludes);
@@ -262,30 +197,27 @@ export class RouteManager {
                 const requestContainer = this.getRequestContainer(c);
                 const runChain = (index)=>{
                     if (index >= def.middleware.length) return next();
-                    const instance = this.instantiate(def.middleware[index], requestContainer);
+                    const instance = instantiate(def.middleware[index], requestContainer);
                     // eslint-disable-next-line @typescript-eslint/no-explicit-any
                     return instance.use(c, ()=>runChain(index + 1)).then(()=>{});
                 };
                 return runChain(0);
             });
         }
-        // First pass: register all custom routes (must come before CRUD /:id routes)
+        // First pass: register all custom routes (must come before CRUD /:id routes).
         for (const { controller, metadata, routes } of this.controllers){
             if (routes.length > 0) {
                 const allParamMetadata = MetadataRegistry.getParameters(controller);
                 for (const route of routes){
-                    // Determine effective version: route-level overrides controller-level
                     const effectiveVersion = route.version ?? metadata.version;
-                    // Build versioned paths
                     const versionedPaths = this.buildVersionedPaths(this.globalPrefix, metadata.prefix, route.path, effectiveVersion);
-                    // Register per-route middleware as Hono middleware before the handler
                     const middlewareItems = ComponentManager.getComponents('middleware', controller, route.handlerName);
-                    const handler = this.createHandler(route, controller, allParamMetadata);
+                    const handler = this.handlerExecutor.create(route, controller, allParamMetadata);
                     for (const fullPath of versionedPaths){
                         for (const middlewareItem of middlewareItems){
                             app.use(fullPath, (c, next)=>{
                                 const requestContainer = this.getRequestContainer(c);
-                                const resolved = this.instantiate(middlewareItem, requestContainer);
+                                const resolved = instantiate(middlewareItem, requestContainer);
                                 return resolved.use(c, next);
                             });
                         }
@@ -294,7 +226,7 @@ export class RouteManager {
                 }
             }
         }
-        // Second pass: mount CRUD sub-apps (/:id routes registered last)
+        // Second pass: mount CRUD sub-apps (/:id routes registered last).
         for (const { controller, metadata } of this.controllers){
             const crudConfig = getMetadata('vela:crud', controller);
             if (crudConfig) {
@@ -303,7 +235,7 @@ export class RouteManager {
                     const { buildCrudRoutes } = await import(pkg);
                     await buildCrudRoutes(app, controller, metadata.prefix, crudConfig, {
                         globalPrefix: this.globalPrefix,
-                        globalGuards: this.instantiateMany(this.globalGuards, this.container),
+                        globalGuards: instantiateMany(this.globalGuards, this.container),
                         joinPaths
                     });
                 } catch (err) {
@@ -315,155 +247,6 @@ export class RouteManager {
         }
         return app;
     }
-    createExecutionContext(c, controller, route) {
-        return buildExecutionContext(c, controller, route.handlerName);
-    }
-    createHandler(route, controller, allParamMetadata) {
-        const paramMetadata = (allParamMetadata.get(route.handlerName) || []).sort((a, b)=>a.index - b.index);
-        // Read param types once at build time for metatype population.
-        // 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);
-        // Collect controller + method level components at build time
-        const methodGuards = ComponentManager.getComponents('guard', controller, route.handlerName);
-        const methodPipes = ComponentManager.getComponents('pipe', controller, route.handlerName);
-        const methodInterceptors = ComponentManager.getComponents('interceptor', controller, route.handlerName);
-        // Filters: reverse order (handler → controller → global) — closest to handler runs first
-        const methodFilters = [
-            ...ComponentManager.getComponents('filter', controller, route.handlerName)
-        ].reverse();
-        // Read response decorators at build time
-        const httpCode = getHttpCode(controller, route.handlerName);
-        const responseHeaders = getResponseHeaders(controller, route.handlerName);
-        const redirect = getRedirect(controller, route.handlerName);
-        return async (c)=>{
-            // Combine global + method at request time (allows post-create registration)
-            const requestContainer = this.getRequestContainer(c);
-            const guards = [
-                ...this.instantiateMany(this.globalGuards, requestContainer),
-                ...this.instantiateMany(methodGuards, requestContainer)
-            ];
-            const pipes = [
-                ...this.instantiateMany(this.globalPipes, requestContainer),
-                ...this.instantiateMany(methodPipes, requestContainer)
-            ];
-            const interceptors = [
-                ...this.instantiateMany(this.globalInterceptors, requestContainer),
-                ...this.instantiateMany(methodInterceptors, requestContainer)
-            ];
-            const filters = [
-                ...this.instantiateMany(methodFilters, requestContainer),
-                ...this.instantiateMany(this.globalFilters, requestContainer)
-            ];
-            const executionContext = this.createExecutionContext(c, controller, route);
-            try {
-                const instance = requestContainer.resolve(controller);
-                // 1. Extract args + run pipes
-                const args = await this.extractArguments(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);
-                // Handle @Redirect
-                if (redirect) {
-                    const overrides = parseRedirectResult(result);
-                    const finalUrl = overrides?.url ?? redirect.url;
-                    const finalStatus = overrides?.statusCode ?? redirect.statusCode;
-                    return c.redirect(finalUrl, finalStatus);
-                }
-                // Build response with @HttpCode and @Header support
-                const response = this.createResponse(c, result, httpCode);
-                // Apply @Header decorators
-                for (const [headerName, headerValue] of responseHeaders){
-                    response.headers.set(headerName, headerValue);
-                }
-                return response;
-            } catch (error) {
-                // Run exception filters
-                for (const filter of filters){
-                    if (shouldFilterCatch(filter, error)) {
-                        try {
-                            const result = await filter.catch(error, executionContext);
-                            return this.createResponse(c, result);
-                        } catch  {
-                            break;
-                        }
-                    }
-                }
-                // Default HttpException handling
-                if (error instanceof HttpException) {
-                    const response = error.getResponse();
-                    const status = error.getStatus();
-                    return c.json(response, status);
-                }
-                // Default 500
-                return c.json({
-                    statusCode: 500,
-                    message: 'Internal Server Error'
-                }, 500);
-            }
-        };
-    }
-    async extractArguments(c, paramMetadata, pipes, requestContainer, paramTypes) {
-        if (paramMetadata.length === 0) {
-            return [
-                c
-            ];
-        }
-        const maxIndex = paramMetadata.at(-1).index;
-        const args = new Array(maxIndex + 1).fill(undefined);
-        for (const param of paramMetadata){
-            let value = await this.extractParam(c, param);
-            const metadata = {
-                type: param.type,
-                data: param.name,
-                metatype: paramTypes?.[param.index]
-            };
-            // Run shared pipes (global + controller + method)
-            for (const pipe of pipes){
-                value = await pipe.transform(value, metadata);
-            }
-            // Run param-level pipes
-            if (param.pipes && param.pipes.length > 0) {
-                for (const paramPipe of param.pipes){
-                    const pipeInstance = this.instantiate(paramPipe, requestContainer);
-                    value = await pipeInstance.transform(value, metadata);
-                }
-            }
-            args[param.index] = value;
-        }
-        return args;
-    }
-    extractParam(c, param) {
-        if (param.type === ParamType.IP) return this.ipExtractor(c);
-        const extractor = RouteManager.PARAM_EXTRACTORS.get(param.type);
-        if (extractor) return extractor(c, param);
-        return param.factory ? param.factory(param.name, c) : undefined;
-    }
-    createResponse(c, result, statusCode) {
-        if (result instanceof Response) {
-            return result;
-        }
-        if (result === null || result === undefined) {
-            return c.body(null, statusCode ?? 204);
-        }
-        if (typeof result === 'string') {
-            return c.text(result, statusCode ?? 200);
-        }
-        return c.json(result, statusCode ?? 200);
-    }
     registerRoute(app, method, path, handler) {
         const normalizedPath = path || '/';
         const registrar = RouteManager.METHOD_REGISTRAR.get(method);

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export { bootstrap } from './factory/bootstrap';
 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, mixin, } from './container/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 { 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, applyDecorators, } from './http/index';
@@ -30,7 +30,7 @@ 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, createModuleRef } from './module/index';
+export { Global, Module, defineDynamicModule, stableHash, } from './module/index';
 export type { ModuleOptions, DynamicModule, AsyncModuleOptions, ModuleImport } from './module/index';
 export type { MiddlewareConsumer, NestModule, RouteInfo } from './http/index';
 export { definePlugin, composePlugins, PluginRegistry, PluginRootModule, PLUGIN_REGISTRY_TOKEN, } from './plugin/plugin';

package/dist/index.js

@@ -7,7 +7,7 @@ export { bootstrap } from "./factory/bootstrap.js";
 // OpenAPI
 export { createOpenApiDocument, ApiDoc, ApiTags, ApiResponse, zodToJsonSchema } from "./openapi/index.js";
 // DI Container
-export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, forwardRef, ModuleRef, ModuleVisibilityError, mixin } from "./container/index.js";
+export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, forwardRef, ModuleRef, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID, mixin } from "./container/index.js";
 // Constants
 export { METADATA_KEYS, HttpMethod, ParamType, Scope } from "./constants.js";
 // HTTP Decorators
@@ -33,7 +33,7 @@ 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, createModuleRef } from "./module/index.js";
+export { Global, Module, defineDynamicModule, stableHash } from "./module/index.js";
 // Plugin manifest + composer
 export { definePlugin, composePlugins, PluginRegistry, PluginRootModule, PLUGIN_REGISTRY_TOKEN } from "./plugin/plugin.js";
 // Pipeline Decorators

package/dist/module/decorators.d.ts

@@ -1,6 +1,10 @@
-import type { Constructor, ModuleMetadata, ModuleOptions, Type } from '../registry/types';
+import type { Constructor, DynamicModule, ModuleMetadata, ModuleOptions } from '../registry/types';
 export declare function Global(): ClassDecorator;
 export declare function Module(options?: ModuleOptions): ClassDecorator;
 export declare function isModule(target: Constructor): boolean;
-export declare function createModuleRef(name: string): Type;
+/**
+ * Normalize a DynamicModule, defaulting `key` to `"default"`. Module authors
+ * call this from `forRoot()` so the loader always sees an explicit key.
+ */
+export declare function defineDynamicModule(input: DynamicModule): DynamicModule;
 export declare function getModuleMetadata(target: Constructor): ModuleMetadata | undefined;

package/dist/module/decorators.js

@@ -23,13 +23,14 @@ export function Module(options = {}) {
 export function isModule(target) {
     return MetadataRegistry.getModuleOptions(target) !== undefined;
 }
-export function createModuleRef(name) {
-    const moduleClass = class {
+/**
+ * Normalize a DynamicModule, defaulting `key` to `"default"`. Module authors
+ * call this from `forRoot()` so the loader always sees an explicit key.
+ */ export function defineDynamicModule(input) {
+    return {
+        ...input,
+        key: input.key ?? 'default'
     };
-    Object.defineProperty(moduleClass, 'name', {
-        value: name
-    });
-    return moduleClass;
 }
 export function getModuleMetadata(target) {
     const options = MetadataRegistry.getModuleOptions(target);

package/dist/module/index.d.ts

@@ -1,4 +1,5 @@
-export { Global, Module, isModule, getModuleMetadata, createModuleRef } from './decorators';
+export { Global, Module, isModule, getModuleMetadata, defineDynamicModule, } from './decorators';
+export { stableHash } from './stable-hash';
 export { ModuleLoader } from './module-loader';
 export { MiddlewareBuilder } from './middleware';
 export type { MiddlewareConsumer, MiddlewareConfigProxy, MiddlewareRouteDefinition, NestModule, RouteInfo, } from './middleware';

package/dist/module/index.js

@@ -1,3 +1,4 @@
-export { Global, Module, isModule, getModuleMetadata, createModuleRef } from "./decorators.js";
+export { Global, Module, isModule, getModuleMetadata, defineDynamicModule } from "./decorators.js";
+export { stableHash } from "./stable-hash.js";
 export { ModuleLoader } from "./module-loader.js";
 export { MiddlewareBuilder } from "./middleware.js";

package/dist/module/module-loader.d.ts

@@ -14,12 +14,17 @@ export declare class ModuleLoader {
     private consumerMiddlewareDefinitions;
     private appProviderCounter;
     private appProviderTokens;
-    private moduleIdByClass;
+    private moduleIdByClassKey;
     private seenModuleIds;
     constructor(container: Container, router: RouteManager);
     load(rootModule: Type): void;
     private getModuleId;
+    private isProcessed;
+    private markProcessed;
+    private getCachedExports;
+    private cacheExports;
     private processModule;
+    private warnOnMixedDefaultAndKeyed;
     private registerProvider;
     private isAppToken;
     private buildExportSet;