@velajs/vela 0.1.0

package/dist/pipeline/reflector.js

@@ -0,0 +1,166 @@
+import { getMetadata as internalGetMetadata } from "../metadata.js";
+import { MetadataRegistry } from "../registry/metadata.registry.js";
+const SET_METADATA_KEY = 'vela:metadata';
+let _decoratorKeyCounter = 0;
+/**
+ * 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 function SetMetadata(key, value) {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+    return (target, propertyKey)=>{
+        if (propertyKey !== undefined) {
+            // Method decorator
+            MetadataRegistry.setCustomHandlerMeta(target.constructor, propertyKey, key, value);
+        } else {
+            // Class decorator
+            MetadataRegistry.setCustomClassMeta(target, key, value);
+        }
+    };
+}
+/**
+ * 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 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(options) {
+        const key = options?.key ?? `vela:custom:${_decoratorKeyCounter++}`;
+        const decorator = (value)=>SetMetadata(key, value);
+        decorator.KEY = key;
+        return decorator;
+    }
+    resolveKey(keyOrDecorator) {
+        return typeof keyOrDecorator === 'string' ? keyOrDecorator : keyOrDecorator.KEY;
+    }
+    /**
+   * Get metadata value from handler first, then class.
+   * Handler-level metadata takes priority over class-level.
+   */ get(key, context) {
+        const resolvedKey = this.resolveKey(key);
+        // Check handler-level first (MetadataRegistry)
+        const handlerValue = MetadataRegistry.getCustomHandlerMeta(context.getClass(), context.getHandler(), resolvedKey);
+        if (handlerValue !== undefined) {
+            return handlerValue;
+        }
+        // Check class-level (MetadataRegistry)
+        const classValue = MetadataRegistry.getCustomClassMeta(context.getClass(), resolvedKey);
+        if (classValue !== undefined) {
+            return classValue;
+        }
+        // Fallback to WeakMap for external package compat
+        const handlerMeta = internalGetMetadata(SET_METADATA_KEY, context.getClass(), context.getHandler());
+        if (handlerMeta?.has(resolvedKey)) {
+            return handlerMeta.get(resolvedKey);
+        }
+        const classMeta = internalGetMetadata(SET_METADATA_KEY, context.getClass());
+        if (classMeta?.has(resolvedKey)) {
+            return classMeta.get(resolvedKey);
+        }
+        return undefined;
+    }
+    /**
+   * Get metadata only from the handler (method) level.
+   */ getHandler(key, context) {
+        const resolvedKey = this.resolveKey(key);
+        // MetadataRegistry first
+        const value = MetadataRegistry.getCustomHandlerMeta(context.getClass(), context.getHandler(), resolvedKey);
+        if (value !== undefined) {
+            return value;
+        }
+        // Fallback to WeakMap
+        const meta = internalGetMetadata(SET_METADATA_KEY, context.getClass(), context.getHandler());
+        return meta?.get(resolvedKey);
+    }
+    /**
+   * Get metadata only from the class level.
+   */ getClass(key, context) {
+        const resolvedKey = this.resolveKey(key);
+        // MetadataRegistry first
+        const value = MetadataRegistry.getCustomClassMeta(context.getClass(), resolvedKey);
+        if (value !== undefined) {
+            return value;
+        }
+        // Fallback to WeakMap
+        const meta = internalGetMetadata(SET_METADATA_KEY, context.getClass());
+        return meta?.get(resolvedKey);
+    }
+    /**
+   * Get all metadata values for a key from both handler and class.
+   * Returns [handlerValue, classValue] (either may be undefined).
+   */ getAll(key, context) {
+        return [
+            this.getHandler(key, context),
+            this.getClass(key, context)
+        ];
+    }
+    /**
+   * Returns handler value if defined, else class value, else undefined.
+   * First defined value wins.
+   */ getAllAndOverride(key, context) {
+        const handlerValue = this.getHandler(key, context);
+        if (handlerValue !== undefined) {
+            return handlerValue;
+        }
+        return this.getClass(key, context);
+    }
+    /**
+   * Collects handler + class values, filters undefineds.
+   * - 0 values → []
+   * - 1 value → return it
+   * - Arrays → concatenate
+   * - Objects → Object.assign({}, ...values)
+   * - Otherwise → wrap in array
+   */ getAllAndMerge(key, context) {
+        const [handlerValue, classValue] = this.getAll(key, context);
+        const values = [];
+        if (handlerValue !== undefined) values.push(handlerValue);
+        if (classValue !== undefined) values.push(classValue);
+        if (values.length === 0) {
+            return [];
+        }
+        if (values.length === 1) {
+            return values[0];
+        }
+        // Both defined — merge strategy depends on type
+        if (Array.isArray(values[0]) && Array.isArray(values[1])) {
+            return [
+                ...values[0],
+                ...values[1]
+            ];
+        }
+        if (typeof values[0] === 'object' && values[0] !== null && !Array.isArray(values[0]) && typeof values[1] === 'object' && values[1] !== null && !Array.isArray(values[1])) {
+            return Object.assign({}, values[0], values[1]);
+        }
+        return values;
+    }
+}

package/dist/pipeline/tokens.d.ts

@@ -0,0 +1,33 @@
+import { InjectionToken } from '../container/types';
+import type { CanActivate, ExceptionFilter, NestInterceptor, NestMiddleware, PipeTransform } from './types';
+/**
+ * Register global guards via module providers instead of app.useGlobalGuards().
+ *
+ * @example
+ * ```ts
+ * @Module({
+ *   providers: [
+ *     AuthGuard,
+ *     { token: APP_GUARD, useClass: AuthGuard },
+ *   ],
+ * })
+ * class AppModule {}
+ * ```
+ */
+export declare const APP_GUARD: InjectionToken<CanActivate>;
+/**
+ * Register global pipes via module providers.
+ */
+export declare const APP_PIPE: InjectionToken<PipeTransform<unknown, unknown>>;
+/**
+ * Register global interceptors via module providers.
+ */
+export declare const APP_INTERCEPTOR: InjectionToken<NestInterceptor>;
+/**
+ * Register global filters via module providers.
+ */
+export declare const APP_FILTER: InjectionToken<ExceptionFilter<unknown>>;
+/**
+ * Register global middleware via module providers.
+ */
+export declare const APP_MIDDLEWARE: InjectionToken<NestMiddleware>;

package/dist/pipeline/tokens.js

@@ -0,0 +1,27 @@
+import { InjectionToken } from "../container/types.js";
+/**
+ * Register global guards via module providers instead of app.useGlobalGuards().
+ *
+ * @example
+ * ```ts
+ * @Module({
+ *   providers: [
+ *     AuthGuard,
+ *     { token: APP_GUARD, useClass: AuthGuard },
+ *   ],
+ * })
+ * class AppModule {}
+ * ```
+ */ export const APP_GUARD = new InjectionToken('APP_GUARD');
+/**
+ * Register global pipes via module providers.
+ */ export const APP_PIPE = new InjectionToken('APP_PIPE');
+/**
+ * Register global interceptors via module providers.
+ */ export const APP_INTERCEPTOR = new InjectionToken('APP_INTERCEPTOR');
+/**
+ * Register global filters via module providers.
+ */ export const APP_FILTER = new InjectionToken('APP_FILTER');
+/**
+ * Register global middleware via module providers.
+ */ export const APP_MIDDLEWARE = new InjectionToken('APP_MIDDLEWARE');

package/dist/pipeline/types.d.ts

@@ -0,0 +1,31 @@
+import type { Context } from 'hono';
+import type { Type } from '../container/types';
+export interface ExecutionContext {
+    getClass(): Type;
+    getHandler(): string | symbol;
+    getContext<T = Context>(): T;
+    getRequest(): Request;
+}
+export interface CanActivate {
+    canActivate(context: ExecutionContext): boolean | Promise<boolean>;
+}
+export interface CallHandler {
+    handle(): Promise<unknown>;
+}
+export interface NestInterceptor {
+    intercept(context: ExecutionContext, next: CallHandler): Promise<unknown>;
+}
+export interface ArgumentMetadata {
+    type: string;
+    metatype?: Type;
+    data?: string;
+}
+export interface PipeTransform<T = unknown, R = unknown> {
+    transform(value: T, metadata: ArgumentMetadata): R | Promise<R>;
+}
+export interface ExceptionFilter<T = unknown> {
+    catch(exception: T, context: ExecutionContext): unknown | Promise<unknown>;
+}
+export interface NestMiddleware {
+    use(c: import('hono').Context, next: import('hono').Next): Promise<Response | void>;
+}

package/dist/pipeline/types.js

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

package/dist/registry/index.d.ts

@@ -0,0 +1,2 @@
+export { MetadataRegistry } from './metadata.registry';
+export type { Type, Constructor, ComponentType, ComponentTypeMap, ComponentInstance, MiddlewareType, GuardType, PipeType, InterceptorType, FilterType, RouteDefinition, ParameterMetadata, ModuleOptions, ProviderOptions, InjectionTokenLike, } from './types';

package/dist/registry/index.js

@@ -0,0 +1 @@
+export { MetadataRegistry } from "./metadata.registry.js";

package/dist/registry/metadata.registry.d.ts

@@ -0,0 +1,61 @@
+import type { Scope } from '../constants';
+import type { InjectMetadata } from '../container/types';
+import type { Type } from '../container/types';
+import type { ComponentType, ComponentTypeMap, Constructor, HttpHandlerMeta, ModuleOptions, ParameterMetadata, RouteDefinition } from './types';
+export interface ControllerOptions {
+    version?: number | number[];
+}
+export declare class MetadataRegistry {
+    private static readonly routes;
+    private static readonly controllers;
+    private static readonly controllerOptions;
+    private static readonly modules;
+    private static readonly parameters;
+    private static readonly global;
+    private static readonly controller;
+    private static readonly handler;
+    private static readonly injectables;
+    private static readonly scopes;
+    private static readonly injectTokens;
+    private static readonly handlerHttpMeta;
+    private static readonly catchTypes;
+    private static readonly routeVersions;
+    private static readonly customClassMeta;
+    private static readonly customHandlerMeta;
+    static getRoutes(controller: Constructor): RouteDefinition[];
+    static addRoute(controller: Constructor, route: RouteDefinition): void;
+    static getControllerPath(controller: Constructor): string;
+    static setControllerPath(controller: Constructor, path: string): void;
+    static getControllerOptions(controller: Constructor): ControllerOptions;
+    static setControllerOptions(controller: Constructor, options: ControllerOptions): void;
+    static getModuleOptions(module: Constructor): ModuleOptions | undefined;
+    static setModuleOptions(module: Constructor, options: ModuleOptions): void;
+    static getParameters(controller: Constructor): Map<string | symbol, ParameterMetadata[]>;
+    static addParameter(controller: Constructor, methodName: string | symbol, param: ParameterMetadata): void;
+    static registerGlobal<T extends ComponentType>(type: T, component: ComponentTypeMap[T]): void;
+    static getGlobal<T extends ComponentType>(type: T): Set<ComponentTypeMap[T]>;
+    static registerController<T extends ComponentType>(type: T, controller: Constructor, component: ComponentTypeMap[T]): void;
+    static getController<T extends ComponentType>(type: T, controller: Constructor): ComponentTypeMap[T][];
+    static registerHandler<T extends ComponentType>(type: T, handlerKey: string, component: ComponentTypeMap[T]): void;
+    static getHandler<T extends ComponentType>(type: T, handlerKey: string): ComponentTypeMap[T][];
+    static markInjectable(target: Constructor): void;
+    static hasInjectable(target: Constructor): boolean;
+    static setScope(target: Constructor, scope: Scope): void;
+    static getScope(target: Constructor): Scope | undefined;
+    static setInjectTokens(target: Constructor, tokens: InjectMetadata[]): void;
+    static getInjectTokens(target: Constructor): InjectMetadata[] | undefined;
+    static setHandlerHttpMeta(controller: Constructor, method: string | symbol, meta: HttpHandlerMeta): void;
+    static getHandlerHttpMeta(controller: Constructor, method: string | symbol): HttpHandlerMeta | undefined;
+    static setCatchTypes(filter: Constructor, types: Type<Error>[]): void;
+    static getCatchTypes(filter: Constructor): Type<Error>[] | undefined;
+    static hasCatchTypes(filter: Constructor): boolean;
+    static setRouteVersion(controller: Constructor, method: string | symbol, version: number | number[]): void;
+    static getRouteVersion(controller: Constructor, method: string | symbol): number | number[] | undefined;
+    static setCustomClassMeta(target: Constructor, key: string, value: unknown): void;
+    static getCustomClassMeta(target: Constructor, key: string): unknown;
+    static getCustomClassMetaAll(target: Constructor): Map<string, unknown> | undefined;
+    static setCustomHandlerMeta(target: Constructor, handler: string | symbol, key: string, value: unknown): void;
+    static getCustomHandlerMeta(target: Constructor, handler: string | symbol, key: string): unknown;
+    static getCustomHandlerMetaAll(target: Constructor, handler: string | symbol): Map<string, unknown> | undefined;
+    static clear(): void;
+}

package/dist/registry/metadata.registry.js

@@ -0,0 +1,276 @@
+export class MetadataRegistry {
+    static routes = new Map();
+    static controllers = new Map();
+    static controllerOptions = new Map();
+    static modules = new Map();
+    static parameters = new Map();
+    // 3-level component hierarchy
+    static global = new Map([
+        [
+            'middleware',
+            new Set()
+        ],
+        [
+            'guard',
+            new Set()
+        ],
+        [
+            'pipe',
+            new Set()
+        ],
+        [
+            'interceptor',
+            new Set()
+        ],
+        [
+            'filter',
+            new Set()
+        ]
+    ]);
+    static controller = new Map([
+        [
+            'middleware',
+            new Map()
+        ],
+        [
+            'guard',
+            new Map()
+        ],
+        [
+            'pipe',
+            new Map()
+        ],
+        [
+            'interceptor',
+            new Map()
+        ],
+        [
+            'filter',
+            new Map()
+        ]
+    ]);
+    static handler = new Map([
+        [
+            'middleware',
+            new Map()
+        ],
+        [
+            'guard',
+            new Map()
+        ],
+        [
+            'pipe',
+            new Map()
+        ],
+        [
+            'interceptor',
+            new Map()
+        ],
+        [
+            'filter',
+            new Map()
+        ]
+    ]);
+    // DI metadata
+    static injectables = new Set();
+    static scopes = new Map();
+    static injectTokens = new Map();
+    // HTTP handler metadata
+    static handlerHttpMeta = new Map();
+    // Exception filter types
+    static catchTypes = new Map();
+    // Route versions
+    static routeVersions = new Map();
+    // Custom metadata (SetMetadata)
+    static customClassMeta = new Map();
+    static customHandlerMeta = new Map();
+    // Routes
+    static getRoutes(controller) {
+        return this.routes.get(controller) || [];
+    }
+    static addRoute(controller, route) {
+        if (!this.routes.has(controller)) {
+            this.routes.set(controller, []);
+        }
+        this.routes.get(controller).push(route);
+    }
+    // Controllers
+    static getControllerPath(controller) {
+        return this.controllers.get(controller) || '';
+    }
+    static setControllerPath(controller, path) {
+        this.controllers.set(controller, path);
+    }
+    static getControllerOptions(controller) {
+        return this.controllerOptions.get(controller) || {};
+    }
+    static setControllerOptions(controller, options) {
+        this.controllerOptions.set(controller, options);
+    }
+    // Modules
+    static getModuleOptions(module) {
+        return this.modules.get(module);
+    }
+    static setModuleOptions(module, options) {
+        this.modules.set(module, options);
+    }
+    // Parameters
+    static getParameters(controller) {
+        return this.parameters.get(controller) || new Map();
+    }
+    static addParameter(controller, methodName, param) {
+        if (!this.parameters.has(controller)) {
+            this.parameters.set(controller, new Map());
+        }
+        const methodParams = this.parameters.get(controller);
+        if (!methodParams.has(methodName)) {
+            methodParams.set(methodName, []);
+        }
+        methodParams.get(methodName).push(param);
+    }
+    // Component registration — 3 levels
+    static registerGlobal(type, component) {
+        this.global.get(type).add(component);
+    }
+    static getGlobal(type) {
+        return this.global.get(type);
+    }
+    static registerController(type, controller, component) {
+        const typeMap = this.controller.get(type);
+        if (!typeMap.has(controller)) {
+            typeMap.set(controller, []);
+        }
+        typeMap.get(controller).push(component);
+    }
+    static getController(type, controller) {
+        const typeMap = this.controller.get(type);
+        return typeMap.get(controller) || [];
+    }
+    static registerHandler(type, handlerKey, component) {
+        const typeMap = this.handler.get(type);
+        if (!typeMap.has(handlerKey)) {
+            typeMap.set(handlerKey, []);
+        }
+        typeMap.get(handlerKey).push(component);
+    }
+    static getHandler(type, handlerKey) {
+        const typeMap = this.handler.get(type);
+        return typeMap.get(handlerKey) || [];
+    }
+    // DI metadata
+    static markInjectable(target) {
+        this.injectables.add(target);
+    }
+    static hasInjectable(target) {
+        return this.injectables.has(target);
+    }
+    static setScope(target, scope) {
+        this.scopes.set(target, scope);
+    }
+    static getScope(target) {
+        return this.scopes.get(target);
+    }
+    static setInjectTokens(target, tokens) {
+        this.injectTokens.set(target, tokens);
+    }
+    static getInjectTokens(target) {
+        return this.injectTokens.get(target);
+    }
+    // HTTP handler metadata
+    static setHandlerHttpMeta(controller, method, meta) {
+        if (!this.handlerHttpMeta.has(controller)) {
+            this.handlerHttpMeta.set(controller, new Map());
+        }
+        const methodMap = this.handlerHttpMeta.get(controller);
+        const existing = methodMap.get(method) ?? {};
+        // Append-merge responseHeaders
+        const merged = {
+            ...existing,
+            ...meta
+        };
+        if (meta.responseHeaders) {
+            merged.responseHeaders = [
+                ...existing.responseHeaders ?? [],
+                ...meta.responseHeaders
+            ];
+        }
+        methodMap.set(method, merged);
+    }
+    static getHandlerHttpMeta(controller, method) {
+        return this.handlerHttpMeta.get(controller)?.get(method);
+    }
+    // Exception filter types
+    static setCatchTypes(filter, types) {
+        this.catchTypes.set(filter, types);
+    }
+    static getCatchTypes(filter) {
+        return this.catchTypes.get(filter);
+    }
+    static hasCatchTypes(filter) {
+        return this.catchTypes.has(filter);
+    }
+    // Route versions
+    static setRouteVersion(controller, method, version) {
+        if (!this.routeVersions.has(controller)) {
+            this.routeVersions.set(controller, new Map());
+        }
+        this.routeVersions.get(controller).set(method, version);
+    }
+    static getRouteVersion(controller, method) {
+        return this.routeVersions.get(controller)?.get(method);
+    }
+    // Custom metadata (SetMetadata)
+    static setCustomClassMeta(target, key, value) {
+        if (!this.customClassMeta.has(target)) {
+            this.customClassMeta.set(target, new Map());
+        }
+        this.customClassMeta.get(target).set(key, value);
+    }
+    static getCustomClassMeta(target, key) {
+        return this.customClassMeta.get(target)?.get(key);
+    }
+    static getCustomClassMetaAll(target) {
+        return this.customClassMeta.get(target);
+    }
+    static setCustomHandlerMeta(target, handler, key, value) {
+        if (!this.customHandlerMeta.has(target)) {
+            this.customHandlerMeta.set(target, new Map());
+        }
+        const handlerMap = this.customHandlerMeta.get(target);
+        if (!handlerMap.has(handler)) {
+            handlerMap.set(handler, new Map());
+        }
+        handlerMap.get(handler).set(key, value);
+    }
+    static getCustomHandlerMeta(target, handler, key) {
+        return this.customHandlerMeta.get(target)?.get(handler)?.get(key);
+    }
+    static getCustomHandlerMetaAll(target, handler) {
+        return this.customHandlerMeta.get(target)?.get(handler);
+    }
+    // Clear all (for testing)
+    static clear() {
+        this.routes.clear();
+        this.controllers.clear();
+        this.controllerOptions.clear();
+        this.modules.clear();
+        this.parameters.clear();
+        for (const set of this.global.values()){
+            set.clear();
+        }
+        for (const map of this.controller.values()){
+            map.clear();
+        }
+        for (const map of this.handler.values()){
+            map.clear();
+        }
+        this.injectables.clear();
+        this.scopes.clear();
+        this.injectTokens.clear();
+        this.handlerHttpMeta.clear();
+        this.catchTypes.clear();
+        this.routeVersions.clear();
+        this.customClassMeta.clear();
+        this.customHandlerMeta.clear();
+    }
+}

package/dist/registry/types.d.ts

@@ -0,0 +1,55 @@
+import type { CanActivate, ExceptionFilter, NestInterceptor, NestMiddleware, PipeTransform } from '../pipeline/types';
+export type Type<T = any> = new (...args: any[]) => T;
+export type Constructor = Function;
+export type ComponentType = 'middleware' | 'guard' | 'pipe' | 'interceptor' | 'filter';
+export type MiddlewareType = Type<NestMiddleware> | NestMiddleware;
+export type GuardType = Type<CanActivate> | CanActivate;
+export type PipeType = Type<PipeTransform> | PipeTransform;
+export type InterceptorType = Type<NestInterceptor> | NestInterceptor;
+export type FilterType = Type<ExceptionFilter> | ExceptionFilter;
+export interface ComponentTypeMap {
+    middleware: MiddlewareType;
+    guard: GuardType;
+    pipe: PipeType;
+    interceptor: InterceptorType;
+    filter: FilterType;
+}
+export type ComponentInstance = MiddlewareType | GuardType | PipeType | InterceptorType | FilterType;
+export interface RouteDefinition {
+    method: string;
+    path: string;
+    handlerName: string | symbol;
+    version?: number | number[];
+}
+export interface ParameterMetadata {
+    index: number;
+    type: string;
+    name?: string;
+    pipes?: PipeType[];
+    factory?: (data: unknown, ctx: unknown) => unknown;
+}
+export interface HttpHandlerMeta {
+    httpCode?: number;
+    responseHeaders?: Array<[string, string]>;
+    redirect?: {
+        url: string;
+        statusCode: number;
+    };
+}
+export interface ModuleOptions {
+    imports?: unknown[];
+    providers?: Array<Type | ProviderOptions>;
+    controllers?: Type[];
+    exports?: Array<Type | InjectionTokenLike>;
+}
+export interface InjectionTokenLike {
+    toString(): string;
+}
+export interface ProviderOptions<T = unknown> {
+    token?: unknown;
+    scope?: string;
+    useValue?: T;
+    useFactory?: (...args: unknown[]) => T | Promise<T>;
+    inject?: unknown[];
+    useExisting?: unknown;
+}

package/dist/registry/types.js

@@ -0,0 +1,2 @@
+// Forward-compatible with ProviderOptions
+export { };