@velajs/vela 0.2.1

package/dist/module/module-loader.js

@@ -0,0 +1,159 @@
+import { getModuleMetadata, isModule } from "./decorators.js";
+function isDynamicModule(value) {
+    return typeof value === 'object' && value !== null && 'module' in value && typeof value.module === 'function';
+}
+export class ModuleLoader {
+    container;
+    router;
+    processedModules = new Set();
+    processingStack = new Set();
+    collectedControllers = [];
+    registeredProviders = [];
+    moduleExportsCache = new Map();
+    constructor(container, router){
+        this.container = container;
+        this.router = router;
+    }
+    load(rootModule) {
+        this.processModule(rootModule);
+        for (const controller of this.collectedControllers){
+            this.router.registerController(controller);
+        }
+    }
+    processModule(moduleClassOrDynamic) {
+        // Handle dynamic modules ({ module, controllers, providers })
+        let moduleClass;
+        let extraControllers = [];
+        let extraProviders = [];
+        if (isDynamicModule(moduleClassOrDynamic)) {
+            moduleClass = moduleClassOrDynamic.module;
+            extraControllers = moduleClassOrDynamic.controllers ?? [];
+            extraProviders = moduleClassOrDynamic.providers ?? [];
+        } else {
+            moduleClass = moduleClassOrDynamic;
+        }
+        if (this.processedModules.has(moduleClass)) {
+            // Even if already processed, still collect extra controllers from dynamic module
+            for (const controller of extraControllers){
+                if (!this.collectedControllers.includes(controller)) {
+                    this.collectedControllers.push(controller);
+                }
+            }
+            return this.moduleExportsCache.get(moduleClass) ?? new Set();
+        }
+        if (this.processingStack.has(moduleClass)) {
+            const chain = [
+                ...this.processingStack,
+                moduleClass
+            ].map((m)=>m.name).join(' -> ');
+            throw new Error(`Circular module dependency detected: ${chain}`);
+        }
+        if (!isModule(moduleClass)) {
+            throw new Error(`${moduleClass.name} is not a module. Add @Module() decorator to the class.`);
+        }
+        const metadata = getModuleMetadata(moduleClass);
+        if (!metadata) {
+            throw new Error(`Failed to get module metadata for ${moduleClass.name}`);
+        }
+        this.processingStack.add(moduleClass);
+        try {
+            const importedProviders = new Set();
+            for (const importedModule of metadata.imports){
+                const exportedTokens = this.processModule(importedModule);
+                for (const token of exportedTokens){
+                    importedProviders.add(token);
+                }
+            }
+            // Register metadata providers + dynamic module extra providers
+            const allProviders = [
+                ...metadata.providers,
+                ...extraProviders
+            ];
+            for (const provider of allProviders){
+                this.registerProvider(provider);
+            }
+            // Collect metadata controllers + dynamic module extra controllers
+            const allControllers = [
+                ...metadata.controllers,
+                ...extraControllers
+            ];
+            for (const controller of allControllers){
+                if (!this.collectedControllers.includes(controller)) {
+                    this.collectedControllers.push(controller);
+                }
+            }
+            this.processedModules.add(moduleClass);
+            const exports = this.buildExportSet(metadata.exports, allProviders, importedProviders);
+            this.moduleExportsCache.set(moduleClass, exports);
+            return exports;
+        } finally{
+            this.processingStack.delete(moduleClass);
+        }
+    }
+    registerProvider(provider) {
+        if (typeof provider === 'function') {
+            if (!this.container.has(provider)) {
+                this.container.register(provider);
+                this.registeredProviders.push(provider);
+            }
+        } else {
+            const token = provider.token;
+            if (token && !this.container.has(token)) {
+                this.container.register(provider);
+                this.registeredProviders.push(token);
+            } else if (!token) {
+                this.container.register(provider);
+            }
+        }
+    }
+    buildExportSet(exports, providers, importedProviders) {
+        const exportSet = new Set();
+        for (const exported of exports){
+            const isLocalProvider = providers.some((p)=>{
+                if (typeof p === 'function') {
+                    return p === exported;
+                }
+                return p.token === exported;
+            });
+            const isImportedProvider = importedProviders.has(exported);
+            if (!isLocalProvider && !isImportedProvider) {
+                const name = exported.name ?? String(exported);
+                console.warn(`Warning: Exporting '${name}' which is neither a local provider nor imported from another module.`);
+            }
+            exportSet.add(exported);
+        }
+        return exportSet;
+    }
+    getControllers() {
+        return [
+            ...this.collectedControllers
+        ];
+    }
+    getRegisteredProviders() {
+        return [
+            ...this.registeredProviders
+        ];
+    }
+    resolveAllInstances() {
+        const instances = [];
+        for (const token of this.registeredProviders){
+            try {
+                const instance = this.container.resolve(token);
+                instances.push(instance);
+            } catch  {
+            // Skip unresolvable tokens
+            }
+        }
+        for (const controller of this.collectedControllers){
+            try {
+                const instance = this.container.resolve(controller);
+                if (!instances.includes(instance)) {
+                    instances.push(instance);
+                }
+            } catch  {
+            // Skip unresolvable controllers
+            }
+        }
+        return instances;
+    }
+}

package/dist/module/types.d.ts

@@ -0,0 +1,19 @@
+import type { InjectionToken, ProviderOptions, Type } from '../container/types';
+export interface DynamicModule {
+    module: Type;
+    providers?: Array<Type | ProviderOptions>;
+    controllers?: Type[];
+    exports?: Array<Type | InjectionToken>;
+}
+export interface ModuleOptions {
+    providers?: Array<Type | ProviderOptions>;
+    controllers?: Type[];
+    imports?: Array<Type | DynamicModule>;
+    exports?: Array<Type | InjectionToken>;
+}
+export interface ModuleMetadata {
+    providers: Array<Type | ProviderOptions>;
+    controllers: Type[];
+    imports: Array<Type | DynamicModule>;
+    exports: Array<Type | InjectionToken>;
+}

package/dist/module/types.js

@@ -0,0 +1 @@
+export { };

package/dist/pipeline/component.manager.d.ts

@@ -0,0 +1,18 @@
+import type { Container } from '../container/container';
+import type { ComponentType, ComponentTypeMap, Constructor, FilterType, GuardType, InterceptorType, MiddlewareType, PipeType } from '../registry/types';
+import type { ArgumentMetadata, CanActivate, ExceptionFilter, ExecutionContext, NestInterceptor, NestMiddleware, PipeTransform } from './types';
+export declare class ComponentManager {
+    private static container;
+    static init(container: Container): void;
+    static registerGlobal<T extends ComponentType>(type: T, ...components: ComponentTypeMap[T][]): void;
+    static registerController<T extends ComponentType>(type: T, controller: Constructor, ...components: ComponentTypeMap[T][]): void;
+    static registerHandler<T extends ComponentType>(type: T, controller: Constructor, handlerName: string | symbol, ...components: ComponentTypeMap[T][]): void;
+    static getComponents<T extends ComponentType>(type: T, controller: Constructor, handlerName: string | symbol): ComponentTypeMap[T][];
+    static resolveMiddleware(items: MiddlewareType[]): NestMiddleware[];
+    static resolveGuards(items: GuardType[]): CanActivate[];
+    static resolvePipes(items: PipeType[]): PipeTransform[];
+    static resolveInterceptors(items: InterceptorType[]): NestInterceptor[];
+    static resolveFilters(items: FilterType[]): ExceptionFilter[];
+    static executePipes(value: unknown, metadata: ArgumentMetadata, pipes: PipeTransform[]): Promise<unknown>;
+    static runInterceptorChain(interceptors: NestInterceptor[], context: ExecutionContext, coreHandler: () => Promise<unknown>): Promise<unknown>;
+}

package/dist/pipeline/component.manager.js

@@ -0,0 +1,105 @@
+import { MetadataRegistry } from "../registry/metadata.registry.js";
+function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}
+export class ComponentManager {
+    static container;
+    static init(container) {
+        this.container = container;
+    }
+    // 3-level registration
+    static registerGlobal(type, ...components) {
+        for (const component of components){
+            MetadataRegistry.registerGlobal(type, component);
+        }
+    }
+    static registerController(type, controller, ...components) {
+        for (const component of components){
+            MetadataRegistry.registerController(type, controller, component);
+        }
+    }
+    static registerHandler(type, controller, handlerName, ...components) {
+        const handlerKey = `${controller.name}:${String(handlerName)}`;
+        for (const component of components){
+            MetadataRegistry.registerHandler(type, handlerKey, component);
+        }
+    }
+    // 3-level resolution: global → controller → handler
+    static getComponents(type, controller, handlerName) {
+        const handlerKey = `${controller.name}:${String(handlerName)}`;
+        const globalComponents = Array.from(MetadataRegistry.getGlobal(type));
+        const controllerComponents = MetadataRegistry.getController(type, controller);
+        const handlerComponents = MetadataRegistry.getHandler(type, handlerKey);
+        return [
+            ...globalComponents,
+            ...controllerComponents,
+            ...handlerComponents
+        ];
+    }
+    // Type-specific resolvers
+    static resolveMiddleware(items) {
+        return items.map((item)=>{
+            if (isObject(item) && 'use' in item) {
+                return item;
+            }
+            return this.container.resolve(item);
+        });
+    }
+    static resolveGuards(items) {
+        return items.map((item)=>{
+            if (isObject(item) && 'canActivate' in item) {
+                return item;
+            }
+            return this.container.resolve(item);
+        });
+    }
+    static resolvePipes(items) {
+        return items.map((item)=>{
+            if (isObject(item) && 'transform' in item) {
+                return item;
+            }
+            return this.container.resolve(item);
+        });
+    }
+    static resolveInterceptors(items) {
+        return items.map((item)=>{
+            if (isObject(item) && 'intercept' in item) {
+                return item;
+            }
+            return this.container.resolve(item);
+        });
+    }
+    static resolveFilters(items) {
+        return items.map((item)=>{
+            if (isObject(item) && 'catch' in item) {
+                return item;
+            }
+            return this.container.resolve(item);
+        });
+    }
+    // Pipe execution
+    static async executePipes(value, metadata, pipes) {
+        let transformed = value;
+        for (const pipe of pipes){
+            transformed = await pipe.transform(transformed, metadata);
+        }
+        return transformed;
+    }
+    // Interceptor chain (onion pattern)
+    static async runInterceptorChain(interceptors, context, coreHandler) {
+        if (interceptors.length === 0) {
+            return coreHandler();
+        }
+        let next = {
+            handle: coreHandler
+        };
+        for(let i = interceptors.length - 1; i >= 0; i--){
+            const interceptor = interceptors[i];
+            const currentNext = next;
+            next = {
+                handle: ()=>interceptor.intercept(context, currentNext)
+            };
+        }
+        return next.handle();
+    }
+}

package/dist/pipeline/decorators.d.ts

@@ -0,0 +1,10 @@
+import type { Type } from '../container/types';
+import type { ComponentTypeMap } from '../registry/types';
+export declare function UseMiddleware(...middleware: ComponentTypeMap['middleware'][]): (target: Function | object, propertyKey?: string | symbol) => void;
+export declare function UseGuards(...guards: ComponentTypeMap['guard'][]): (target: Function | object, propertyKey?: string | symbol) => void;
+export declare function UsePipes(...pipes: ComponentTypeMap['pipe'][]): (target: Function | object, propertyKey?: string | symbol) => void;
+export declare function UseInterceptors(...interceptors: ComponentTypeMap['interceptor'][]): (target: Function | object, propertyKey?: string | symbol) => void;
+export declare function UseFilters(...filters: ComponentTypeMap['filter'][]): (target: Function | object, propertyKey?: string | symbol) => void;
+export declare function Catch(...exceptions: Type<Error>[]): ClassDecorator;
+export declare function getCatchTypes(filter: unknown): Type<Error>[];
+export declare function shouldFilterCatch(filter: unknown, exception: unknown): boolean;

package/dist/pipeline/decorators.js

@@ -0,0 +1,50 @@
+import { METADATA_KEYS } from "../constants.js";
+import { getMetadata } from "../metadata.js";
+import { ComponentManager } from "./component.manager.js";
+import { MetadataRegistry } from "../registry/metadata.registry.js";
+function UseComponent(type, ...components) {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+    return (target, propertyKey)=>{
+        if (propertyKey !== undefined) {
+            // Method decorator — target is prototype, target.constructor is the class
+            ComponentManager.registerHandler(type, target.constructor, propertyKey, ...components);
+        } else {
+            // Class decorator — target is the class itself
+            ComponentManager.registerController(type, target, ...components);
+        }
+    };
+}
+export function UseMiddleware(...middleware) {
+    return UseComponent('middleware', ...middleware);
+}
+export function UseGuards(...guards) {
+    return UseComponent('guard', ...guards);
+}
+export function UsePipes(...pipes) {
+    return UseComponent('pipe', ...pipes);
+}
+export function UseInterceptors(...interceptors) {
+    return UseComponent('interceptor', ...interceptors);
+}
+export function UseFilters(...filters) {
+    return UseComponent('filter', ...filters);
+}
+export function Catch(...exceptions) {
+    return (target)=>{
+        MetadataRegistry.setCatchTypes(target, exceptions);
+    };
+}
+export function getCatchTypes(filter) {
+    const filterClass = typeof filter === 'function' ? filter : filter.constructor;
+    if (MetadataRegistry.hasCatchTypes(filterClass)) {
+        return MetadataRegistry.getCatchTypes(filterClass) ?? [];
+    }
+    return getMetadata(METADATA_KEYS.CATCH, filterClass) ?? [];
+}
+export function shouldFilterCatch(filter, exception) {
+    const catchTypes = getCatchTypes(filter);
+    if (catchTypes.length === 0) {
+        return true;
+    }
+    return catchTypes.some((type)=>exception instanceof type);
+}

package/dist/pipeline/index.d.ts

@@ -0,0 +1,7 @@
+export { ComponentManager } from './component.manager';
+export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, getCatchTypes, shouldFilterCatch, } from './decorators';
+export { SetMetadata, Reflector } from './reflector';
+export type { ReflectableDecorator, CreateDecoratorOptions } from './reflector';
+export { APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE } from './tokens';
+export { ParseIntPipe, ParseFloatPipe, ParseBoolPipe, DefaultValuePipe, RequiredPipe, ZodValidationPipe, } from './pipes';
+export type { ExecutionContext, CanActivate, CallHandler, NestInterceptor, NestMiddleware, PipeTransform, ExceptionFilter, ArgumentMetadata, } from './types';

package/dist/pipeline/index.js

@@ -0,0 +1,5 @@
+export { ComponentManager } from "./component.manager.js";
+export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, getCatchTypes, shouldFilterCatch } from "./decorators.js";
+export { SetMetadata, Reflector } from "./reflector.js";
+export { APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE } from "./tokens.js";
+export { ParseIntPipe, ParseFloatPipe, ParseBoolPipe, DefaultValuePipe, RequiredPipe, ZodValidationPipe } from "./pipes.js";

package/dist/pipeline/pipes.d.ts

@@ -0,0 +1,25 @@
+import type { ArgumentMetadata, PipeTransform } from './types';
+export declare class ParseIntPipe implements PipeTransform<string, number> {
+    transform(value: string, metadata: ArgumentMetadata): number;
+}
+export declare class ParseFloatPipe implements PipeTransform<string, number> {
+    transform(value: string, metadata: ArgumentMetadata): number;
+}
+export declare class ParseBoolPipe implements PipeTransform<string, boolean> {
+    transform(value: string, metadata: ArgumentMetadata): boolean;
+}
+export declare class DefaultValuePipe<T = unknown> implements PipeTransform<T | undefined, T> {
+    private readonly defaultValue;
+    constructor(defaultValue: T);
+    transform(value: T | undefined, _metadata: ArgumentMetadata): T;
+}
+export declare class RequiredPipe implements PipeTransform {
+    transform(value: unknown, metadata: ArgumentMetadata): unknown;
+}
+export declare class ZodValidationPipe implements PipeTransform {
+    private readonly schema;
+    constructor(schema: {
+        parse(data: unknown): unknown;
+    });
+    transform(value: unknown, _metadata: ArgumentMetadata): unknown;
+}

package/dist/pipeline/pipes.js

@@ -0,0 +1,52 @@
+import { BadRequestException } from "../errors/http-exception.js";
+export class ParseIntPipe {
+    transform(value, metadata) {
+        const parsed = parseInt(value, 10);
+        if (isNaN(parsed)) {
+            throw new BadRequestException(`Validation failed (numeric string expected)${metadata.data ? ` for parameter '${metadata.data}'` : ''}`);
+        }
+        return parsed;
+    }
+}
+export class ParseFloatPipe {
+    transform(value, metadata) {
+        const parsed = parseFloat(value);
+        if (isNaN(parsed)) {
+            throw new BadRequestException(`Validation failed (float string expected)${metadata.data ? ` for parameter '${metadata.data}'` : ''}`);
+        }
+        return parsed;
+    }
+}
+export class ParseBoolPipe {
+    transform(value, metadata) {
+        if (value === 'true') return true;
+        if (value === 'false') return false;
+        throw new BadRequestException(`Validation failed (boolean string expected)${metadata.data ? ` for parameter '${metadata.data}'` : ''}`);
+    }
+}
+export class DefaultValuePipe {
+    defaultValue;
+    constructor(defaultValue){
+        this.defaultValue = defaultValue;
+    }
+    transform(value, _metadata) {
+        return value !== undefined && value !== null ? value : this.defaultValue;
+    }
+}
+export class RequiredPipe {
+    transform(value, metadata) {
+        if (value === undefined || value === null || value === '') {
+            throw new BadRequestException(`Validation failed (value required)${metadata.data ? ` for parameter '${metadata.data}'` : ''}`);
+        }
+        return value;
+    }
+}
+export class ZodValidationPipe {
+    schema;
+    constructor(schema){
+        this.schema = schema;
+    }
+    transform(value, _metadata) {
+        return this.schema.parse(value);
+    }
+}

package/dist/pipeline/reflector.d.ts

@@ -0,0 +1,102 @@
+export interface CreateDecoratorOptions {
+    key?: string;
+}
+export interface ReflectableDecorator<TParam> {
+    (value: TParam): ClassDecorator & MethodDecorator;
+    KEY: string;
+}
+/**
+ * Decorator that attaches custom metadata to a class or method.
+ * Read via Reflector in guards/interceptors.
+ *
+ * @example
+ * ```ts
+ * const Roles = (...roles: string[]) => SetMetadata('roles', roles);
+ *
+ * @Controller('/admin')
+ * @Roles('admin')
+ * class AdminController { ... }
+ * ```
+ */
+export declare function SetMetadata<V = unknown>(key: string, value: V): (target: Function | object, propertyKey?: string | symbol) => void;
+/**
+ * Reads custom metadata set by @SetMetadata().
+ * Use in guards/interceptors via ExecutionContext.
+ *
+ * @example
+ * ```ts
+ * class RolesGuard implements CanActivate {
+ *   private reflector = new Reflector();
+ *
+ *   canActivate(context: ExecutionContext): boolean {
+ *     const roles = this.reflector.get<string[]>('roles', context);
+ *     if (!roles) return true;
+ *     const user = ...; // extract from request
+ *     return roles.some(r => user.roles.includes(r));
+ *   }
+ * }
+ * ```
+ */
+export declare class Reflector {
+    /**
+     * Create a type-safe decorator that sets metadata with a typed key.
+     *
+     * @example
+     * ```ts
+     * const Roles = Reflector.createDecorator<string[]>();
+     * // Roles(['admin']) — class or method decorator
+     * // reflector.get(Roles, context) — typed as string[] | undefined
+     * ```
+     */
+    static createDecorator<TParam = unknown>(options?: CreateDecoratorOptions): ReflectableDecorator<TParam>;
+    private resolveKey;
+    /**
+     * Get metadata value from handler first, then class.
+     * Handler-level metadata takes priority over class-level.
+     */
+    get<T = unknown>(key: string | ReflectableDecorator<T>, context: {
+        getClass(): Function;
+        getHandler(): string | symbol;
+    }): T | undefined;
+    /**
+     * Get metadata only from the handler (method) level.
+     */
+    getHandler<T = unknown>(key: string | ReflectableDecorator<T>, context: {
+        getClass(): Function;
+        getHandler(): string | symbol;
+    }): T | undefined;
+    /**
+     * Get metadata only from the class level.
+     */
+    getClass<T = unknown>(key: string | ReflectableDecorator<T>, context: {
+        getClass(): Function;
+    }): T | undefined;
+    /**
+     * Get all metadata values for a key from both handler and class.
+     * Returns [handlerValue, classValue] (either may be undefined).
+     */
+    getAll<T = unknown>(key: string | ReflectableDecorator<T>, context: {
+        getClass(): Function;
+        getHandler(): string | symbol;
+    }): [T | undefined, T | undefined];
+    /**
+     * Returns handler value if defined, else class value, else undefined.
+     * First defined value wins.
+     */
+    getAllAndOverride<T = unknown>(key: string | ReflectableDecorator<T>, context: {
+        getClass(): Function;
+        getHandler(): string | symbol;
+    }): T | undefined;
+    /**
+     * Collects handler + class values, filters undefineds.
+     * - 0 values → []
+     * - 1 value → return it
+     * - Arrays → concatenate
+     * - Objects → Object.assign({}, ...values)
+     * - Otherwise → wrap in array
+     */
+    getAllAndMerge<T = unknown>(key: string | ReflectableDecorator<T>, context: {
+        getClass(): Function;
+        getHandler(): string | symbol;
+    }): T | T[];
+}