@velajs/vela 0.4.2 → 0.5.0

package/dist/cache/cache.module.d.ts

@@ -1,5 +1,8 @@
-import type { DynamicModule } from '../module/types';
+import type { AsyncModuleOptions, DynamicModule } from '../module/types';
 import type { CacheModuleOptions } from './cache.types';
 export declare class CacheModule {
     static forRoot(options?: CacheModuleOptions): DynamicModule;
+    static registerAsync(options: AsyncModuleOptions<CacheModuleOptions> & {
+        isGlobal?: boolean;
+    }): DynamicModule;
 }

package/dist/cache/cache.module.js

@@ -6,16 +6,20 @@ import { CacheInterceptor } from "./cache.interceptor.js";
 import { CacheService } from "./cache.service.js";
 import { MemoryCacheStore } from "./cache.store.js";
 import { CACHE_MANAGER, CACHE_MODULE_OPTIONS } from "./cache.tokens.js";
+function makeCacheModuleClass(name) {
+    const moduleClass = class {
+    };
+    Object.defineProperty(moduleClass, 'name', {
+        value: name
+    });
+    defineMetadata(METADATA_KEYS.MODULE, true, moduleClass);
+    return moduleClass;
+}
 export class CacheModule {
     static forRoot(options = {}) {
         const { ttl = 5, max = 100, isGlobal = false } = options;
         const store = new MemoryCacheStore(ttl, max);
-        const moduleClass = class CacheDynamicModule {
-        };
-        Object.defineProperty(moduleClass, 'name', {
-            value: 'CacheModule'
-        });
-        defineMetadata(METADATA_KEYS.MODULE, true, moduleClass);
+        const moduleClass = makeCacheModuleClass('CacheModule');
         MetadataRegistry.setModuleOptions(moduleClass, {
             exports: [
                 CACHE_MANAGER,
@@ -26,11 +30,11 @@ export class CacheModule {
         });
         const providers = [
             {
-                token: CACHE_MANAGER,
+                provide: CACHE_MANAGER,
                 useValue: store
             },
             {
-                token: CACHE_MODULE_OPTIONS,
+                provide: CACHE_MODULE_OPTIONS,
                 useValue: options
             },
             CacheService,
@@ -38,7 +42,45 @@ export class CacheModule {
         ];
         if (isGlobal) {
             providers.push({
-                token: APP_INTERCEPTOR,
+                provide: APP_INTERCEPTOR,
+                useExisting: CacheInterceptor
+            });
+        }
+        return {
+            module: moduleClass,
+            providers
+        };
+    }
+    static registerAsync(options) {
+        const moduleClass = makeCacheModuleClass('CacheModule');
+        MetadataRegistry.setModuleOptions(moduleClass, {
+            imports: options.imports ?? [],
+            exports: [
+                CACHE_MANAGER,
+                CACHE_MODULE_OPTIONS,
+                CacheService,
+                CacheInterceptor
+            ]
+        });
+        const providers = [
+            {
+                provide: CACHE_MODULE_OPTIONS,
+                useFactory: options.useFactory,
+                inject: options.inject ?? []
+            },
+            {
+                provide: CACHE_MANAGER,
+                useFactory: (opts)=>new MemoryCacheStore(opts.ttl ?? 5, opts.max ?? 100),
+                inject: [
+                    CACHE_MODULE_OPTIONS
+                ]
+            },
+            CacheService,
+            CacheInterceptor
+        ];
+        if (options.isGlobal) {
+            providers.push({
+                provide: APP_INTERCEPTOR,
                 useExisting: CacheInterceptor
             });
         }

package/dist/config/config.module.d.ts

@@ -1,5 +1,8 @@
-import type { DynamicModule } from '../module/types';
+import type { AsyncModuleOptions, DynamicModule } from '../module/types';
 import type { ConfigModuleOptions } from './config.types';
 export declare class ConfigModule {
     static forRoot<T extends Record<string, unknown>>(options: ConfigModuleOptions<T>): DynamicModule;
+    static forRootAsync<T extends Record<string, unknown>>(options: AsyncModuleOptions<ConfigModuleOptions<T>> & {
+        isGlobal?: boolean;
+    }): DynamicModule;
 }

package/dist/config/config.module.js

@@ -16,17 +16,54 @@ export class ConfigModule {
             exports: [
                 ConfigService,
                 CONFIG_OPTIONS
-            ]
+            ],
+            isGlobal: options.isGlobal
         });
         return {
             module: moduleClass,
             providers: [
                 {
-                    token: CONFIG_OPTIONS,
+                    provide: CONFIG_OPTIONS,
                     useValue: config
                 },
                 ConfigService
-            ]
+            ],
+            ...options.isGlobal ? {
+                global: true
+            } : {}
+        };
+    }
+    static forRootAsync(options) {
+        const moduleClass = class ConfigAsyncDynamicModule {
+        };
+        Object.defineProperty(moduleClass, 'name', {
+            value: 'ConfigModule'
+        });
+        defineMetadata(METADATA_KEYS.MODULE, true, moduleClass);
+        MetadataRegistry.setModuleOptions(moduleClass, {
+            imports: options.imports ?? [],
+            exports: [
+                ConfigService,
+                CONFIG_OPTIONS
+            ],
+            isGlobal: options.isGlobal
+        });
+        return {
+            module: moduleClass,
+            providers: [
+                {
+                    provide: CONFIG_OPTIONS,
+                    useFactory: async (...args)=>{
+                        const opts = await options.useFactory(...args);
+                        return opts.validate ? opts.validate(opts.config) : opts.config;
+                    },
+                    inject: options.inject ?? []
+                },
+                ConfigService
+            ],
+            ...options.isGlobal ? {
+                global: true
+            } : {}
         };
     }
 }

package/dist/config/config.types.d.ts

@@ -1,4 +1,5 @@
 export interface ConfigModuleOptions<T extends Record<string, unknown> = Record<string, unknown>> {
     config: T;
     validate?: (config: T) => T;
+    isGlobal?: boolean;
 }

package/dist/constants.d.ts

@@ -3,6 +3,7 @@ export declare const METADATA_KEYS: {
     readonly INJECT: "vela:inject";
     readonly SCOPE: "vela:scope";
     readonly MODULE: "vela:module";
+    readonly MODULE_OPTIONS: "vela:module-options";
     readonly CONTROLLER: "vela:controller";
     readonly ROUTES: "vela:routes";
     readonly PARAMS: "vela:params";
@@ -26,7 +27,11 @@ export declare enum ParamType {
     QUERY = "query",
     PARAM = "param",
     HEADERS = "headers",
-    REQUEST = "request"
+    REQUEST = "request",
+    RESPONSE = "response",
+    IP = "ip",
+    COOKIE = "cookie",
+    RAW_BODY = "raw_body"
 }
 export declare enum Scope {
     SINGLETON = "singleton",

package/dist/constants.js

@@ -5,6 +5,7 @@ export const METADATA_KEYS = {
     SCOPE: 'vela:scope',
     // Module
     MODULE: 'vela:module',
+    MODULE_OPTIONS: 'vela:module-options',
     // HTTP
     CONTROLLER: 'vela:controller',
     ROUTES: 'vela:routes',
@@ -33,6 +34,10 @@ export var ParamType = /*#__PURE__*/ function(ParamType) {
     ParamType["PARAM"] = "param";
     ParamType["HEADERS"] = "headers";
     ParamType["REQUEST"] = "request";
+    ParamType["RESPONSE"] = "response";
+    ParamType["IP"] = "ip";
+    ParamType["COOKIE"] = "cookie";
+    ParamType["RAW_BODY"] = "raw_body";
     return ParamType;
 }({});
 export var Scope = /*#__PURE__*/ function(Scope) {

package/dist/container/container.d.ts

@@ -1,3 +1,4 @@
+import { Scope } from '../constants';
 import type { ProviderOptions, Token, Type } from './types';
 export declare class Container {
     private providers;
@@ -9,6 +10,7 @@ export declare class Container {
     private registerOptions;
     resolve<T>(token: Token<T>): T;
     has(token: Token): boolean;
+    getProviderScope(token: Token): Scope | undefined;
     getTokens(): Token[];
     /**
      * Create a child container for request-scoped resolution.
@@ -16,10 +18,12 @@ export declare class Container {
      * instances separately per child (per request).
      */
     createChild(): Container;
+    createDetached(): Container;
     clear(): void;
     private resolveRegistration;
     private resolveClass;
     private resolveFactory;
     resolveAsync<T>(token: Token<T>): Promise<T>;
+    private createLazyProxy;
     private tokenToString;
 }

package/dist/container/container.js

@@ -1,6 +1,6 @@
 import { Scope } from "../constants.js";
 import { getConstructorDependencies, getInjectMetadata, getScope, isInjectable } from "./decorators.js";
-import { InjectionToken } from "./types.js";
+import { ForwardRef, InjectionToken } from "./types.js";
 export class Container {
     providers = new Map();
     resolutionStack = new Set();
@@ -20,18 +20,18 @@ export class Container {
         }
         const scope = getScope(target);
         this.providers.set(target, {
-            token: target,
+            provide: target,
             scope,
             useClass: target
         });
     }
     registerOptions(options) {
-        const token = options.token;
+        const token = options.provide;
         if (!token) {
             throw new Error('Provider registration requires a token');
         }
         const registration = {
-            token,
+            provide: token,
             scope: options.scope ?? Scope.SINGLETON
         };
         if (options.useValue !== undefined) {
@@ -40,6 +40,8 @@ export class Container {
         } else if (options.useFactory) {
             registration.useFactory = options.useFactory;
             registration.inject = options.inject;
+        } else if (options.useClass) {
+            registration.useClass = options.useClass;
         } else if (options.useExisting) {
             registration.useExisting = options.useExisting;
         } else if (typeof token === 'function') {
@@ -56,7 +58,7 @@ export class Container {
             }
             if (token instanceof InjectionToken && token.options?.factory) {
                 this.register({
-                    token,
+                    provide: token,
                     useFactory: token.options.factory
                 });
                 return this.resolve(token);
@@ -68,6 +70,9 @@ export class Container {
     has(token) {
         return this.providers.has(token);
     }
+    getProviderScope(token) {
+        return this.providers.get(token)?.scope;
+    }
     getTokens() {
         return Array.from(this.providers.keys());
     }
@@ -81,6 +86,11 @@ export class Container {
         child.providers = this.providers; // share provider registrations
         return child;
     }
+    createDetached() {
+        const child = new Container();
+        child.providers = new Map(this.providers); // copy, not share
+        return child;
+    }
     clear() {
         this.providers.clear();
         this.resolutionStack.clear();
@@ -99,19 +109,19 @@ export class Container {
         }
         // Request: return cached from this child's requestInstances
         if (registration.scope === Scope.REQUEST) {
-            const cached = this.requestInstances.get(registration.token);
+            const cached = this.requestInstances.get(registration.provide);
             if (cached !== undefined) {
                 return cached;
             }
         }
-        if (this.resolutionStack.has(registration.token)) {
+        if (this.resolutionStack.has(registration.provide)) {
             const chain = [
                 ...this.resolutionStack,
-                registration.token
+                registration.provide
             ].map((t)=>this.tokenToString(t)).join(' -> ');
             throw new Error(`Circular dependency detected: ${chain}`);
         }
-        this.resolutionStack.add(registration.token);
+        this.resolutionStack.add(registration.provide);
         try {
             let instance;
             if (registration.useFactory) {
@@ -119,16 +129,16 @@ export class Container {
             } else if (registration.useClass) {
                 instance = this.resolveClass(registration.useClass);
             } else {
-                throw new Error(`Invalid provider registration for: ${this.tokenToString(registration.token)}`);
+                throw new Error(`Invalid provider registration for: ${this.tokenToString(registration.provide)}`);
             }
             if (registration.scope === Scope.SINGLETON) {
                 registration.instance = instance;
             } else if (registration.scope === Scope.REQUEST) {
-                this.requestInstances.set(registration.token, instance);
+                this.requestInstances.set(registration.provide, instance);
             }
             return instance;
         } finally{
-            this.resolutionStack.delete(registration.token);
+            this.resolutionStack.delete(registration.provide);
         }
     }
     resolveClass(target) {
@@ -136,13 +146,24 @@ export class Container {
         const injectMetadata = getInjectMetadata(target);
         const injectMap = new Map(injectMetadata.map((m)=>[
                 m.index,
-                m.token
+                m
             ]));
         const dependencies = paramTypes.map((paramType, index)=>{
-            const token = injectMap.get(index) ?? paramType;
+            const meta = injectMap.get(index);
+            const rawToken = meta?.token;
+            const isForwardRef = rawToken instanceof ForwardRef;
+            const token = isForwardRef ? rawToken.factory() : rawToken ?? paramType;
             if (!token || token === Object) {
+                if (meta?.optional) return undefined;
                 throw new Error(`Cannot resolve dependency at index ${index} for ${target.name}. ` + `Parameter type is undefined or Object. ` + `Use @Inject() to specify the token explicitly.`);
             }
+            if (meta?.optional && !this.has(token)) {
+                return undefined;
+            }
+            // forwardRef with circular dep — break the cycle with a lazy Proxy
+            if (isForwardRef && this.resolutionStack.has(token)) {
+                return this.createLazyProxy(token);
+            }
             return this.resolve(token);
         });
         return new target(...dependencies);
@@ -154,7 +175,7 @@ export class Container {
         const dependencies = (registration.inject || []).map((token)=>this.resolve(token));
         const result = registration.useFactory(...dependencies);
         if (result instanceof Promise) {
-            throw new Error(`Async factory for ${this.tokenToString(registration.token)} returned a Promise. ` + `Use resolveAsync() for async providers.`);
+            throw new Error(`Async factory for ${this.tokenToString(registration.provide)} returned a Promise. ` + `Use resolveAsync() for async providers.`);
         }
         return result;
     }
@@ -180,6 +201,22 @@ export class Container {
         }
         return this.resolve(token);
     }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    createLazyProxy(token) {
+        const container = this;
+        return new Proxy({}, {
+            get (_target, prop) {
+                const instance = container.resolve(token);
+                const value = instance[prop];
+                return typeof value === 'function' ? value.bind(instance) : value;
+            },
+            set (_target, prop, value) {
+                const instance = container.resolve(token);
+                instance[prop] = value;
+                return true;
+            }
+        });
+    }
     tokenToString(token) {
         if (token instanceof InjectionToken) {
             return token.toString();

package/dist/container/decorators.d.ts

@@ -1,7 +1,9 @@
 import { Scope } from '../constants';
 import type { InjectableOptions, InjectMetadata, Token } from './types';
+import { ForwardRef } from './types';
 export declare function Injectable(options?: InjectableOptions): ClassDecorator;
-export declare function Inject(token: Token): ParameterDecorator;
+export declare function Optional(): ParameterDecorator;
+export declare function Inject(token: Token | ForwardRef): ParameterDecorator;
 export declare function isInjectable(target: object): boolean;
 export declare function getScope(target: object): Scope;
 export declare function getConstructorDependencies(target: object): unknown[];

package/dist/container/decorators.js

@@ -11,13 +11,34 @@ export function Injectable(options = {}) {
         defineMetadata(METADATA_KEYS.SCOPE, scope, target);
     };
 }
+export function Optional() {
+    return (target, _propertyKey, parameterIndex)=>{
+        const existing = getInjectMetadata(target);
+        const entry = existing.find((m)=>m.index === parameterIndex);
+        if (entry) {
+            entry.optional = true;
+        } else {
+            existing.push({
+                index: parameterIndex,
+                optional: true
+            });
+        }
+        MetadataRegistry.setInjectTokens(target, existing);
+        defineMetadata(METADATA_KEYS.INJECT, existing, target);
+    };
+}
 export function Inject(token) {
     return (target, _propertyKey, parameterIndex)=>{
-        const existing = MetadataRegistry.getInjectTokens(target) ?? (getMetadata(METADATA_KEYS.INJECT, target) || []);
-        existing.push({
-            index: parameterIndex,
-            token
-        });
+        const existing = getInjectMetadata(target);
+        const entry = existing.find((m)=>m.index === parameterIndex);
+        if (entry) {
+            entry.token = token;
+        } else {
+            existing.push({
+                index: parameterIndex,
+                token
+            });
+        }
         MetadataRegistry.setInjectTokens(target, existing);
         defineMetadata(METADATA_KEYS.INJECT, existing, target);
     };
@@ -32,5 +53,5 @@ export function getConstructorDependencies(target) {
     return Reflect.getMetadata('design:paramtypes', target) || [];
 }
 export function getInjectMetadata(target) {
-    return MetadataRegistry.getInjectTokens(target) ?? (getMetadata(METADATA_KEYS.INJECT, target) || []);
+    return MetadataRegistry.getInjectTokens(target) ?? getMetadata(METADATA_KEYS.INJECT, target) ?? [];
 }

package/dist/container/index.d.ts

@@ -1,4 +1,6 @@
 export { Container } from './container';
-export { Injectable, Inject, isInjectable, getScope } from './decorators';
-export { InjectionToken } from './types';
+export { Injectable, Inject, Optional, isInjectable, getScope } from './decorators';
+export { InjectionToken, ForwardRef, forwardRef } from './types';
+export { ModuleRef } from './module-ref';
+export { mixin } from './mixin';
 export type { Type, Token, InjectableOptions, InjectMetadata, ProviderOptions, ProviderRegistration, InjectionTokenOptions, } from './types';

package/dist/container/index.js

@@ -1,3 +1,5 @@
 export { Container } from "./container.js";
-export { Injectable, Inject, isInjectable, getScope } from "./decorators.js";
-export { InjectionToken } from "./types.js";
+export { Injectable, Inject, Optional, isInjectable, getScope } from "./decorators.js";
+export { InjectionToken, ForwardRef, forwardRef } from "./types.js";
+export { ModuleRef } from "./module-ref.js";
+export { mixin } from "./mixin.js";

package/dist/container/mixin.d.ts

@@ -0,0 +1,24 @@
+import type { Type } from './types';
+/**
+ * Creates a reusable injectable mixin class from a base class.
+ * Applies @Injectable() so the returned class can be registered as a provider.
+ *
+ * @example
+ * ```ts
+ * function RoleGuardMixin(role: string) {
+ *   class MixedRoleGuard implements CanActivate {
+ *     canActivate(ctx: ExecutionContext) {
+ *       return ctx.getRequest().headers.get('x-role') === role;
+ *     }
+ *   }
+ *   return mixin(MixedRoleGuard);
+ * }
+ *
+ * const AdminGuard = RoleGuardMixin('admin');
+ *
+ * @UseGuards(AdminGuard)
+ * @Get('/admin')
+ * adminOnly() { ... }
+ * ```
+ */
+export declare function mixin<T>(mixinClass: Type<T>): Type<T>;

package/dist/container/mixin.js

@@ -0,0 +1,26 @@
+import { Injectable } from "./decorators.js";
+/**
+ * Creates a reusable injectable mixin class from a base class.
+ * Applies @Injectable() so the returned class can be registered as a provider.
+ *
+ * @example
+ * ```ts
+ * function RoleGuardMixin(role: string) {
+ *   class MixedRoleGuard implements CanActivate {
+ *     canActivate(ctx: ExecutionContext) {
+ *       return ctx.getRequest().headers.get('x-role') === role;
+ *     }
+ *   }
+ *   return mixin(MixedRoleGuard);
+ * }
+ *
+ * const AdminGuard = RoleGuardMixin('admin');
+ *
+ * @UseGuards(AdminGuard)
+ * @Get('/admin')
+ * adminOnly() { ... }
+ * ```
+ */ export function mixin(mixinClass) {
+    Injectable()(mixinClass);
+    return mixinClass;
+}

package/dist/container/module-ref.d.ts

@@ -0,0 +1,21 @@
+import type { Token, Type } from './types';
+import type { Container } from './container';
+export declare class ModuleRef {
+    private readonly container;
+    constructor(container: Container);
+    /**
+     * Retrieve a provider instance from the DI container.
+     * Returns the existing singleton (or cached value) for the token.
+     */
+    get<T>(token: Token<T>): T;
+    /**
+     * Resolve a provider, creating a new instance for TRANSIENT-scoped providers.
+     * For SINGLETON-scoped providers this is equivalent to get().
+     */
+    resolve<T>(token: Token<T>): T;
+    /**
+     * Instantiate a class outside of the DI container's singleton cache.
+     * Dependencies are resolved from the container. Each call returns a new instance.
+     */
+    create<T>(type: Type<T>): T;
+}

package/dist/container/module-ref.js

@@ -0,0 +1,48 @@
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+import { Scope } from "../constants.js";
+import { Injectable } from "./decorators.js";
+export class ModuleRef {
+    container;
+    constructor(container){
+        this.container = container;
+    }
+    /**
+   * Retrieve a provider instance from the DI container.
+   * Returns the existing singleton (or cached value) for the token.
+   */ get(token) {
+        return this.container.resolve(token);
+    }
+    /**
+   * Resolve a provider, creating a new instance for TRANSIENT-scoped providers.
+   * For SINGLETON-scoped providers this is equivalent to get().
+   */ resolve(token) {
+        return this.container.resolve(token);
+    }
+    /**
+   * Instantiate a class outside of the DI container's singleton cache.
+   * Dependencies are resolved from the container. Each call returns a new instance.
+   */ create(type) {
+        const sandbox = this.container.createDetached();
+        sandbox.register({
+            provide: type,
+            useClass: type,
+            scope: Scope.TRANSIENT
+        });
+        return sandbox.resolve(type);
+    }
+}
+ModuleRef = _ts_decorate([
+    Injectable(),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof Container === "undefined" ? Object : Container
+    ])
+], ModuleRef);

package/dist/container/types.d.ts

@@ -9,24 +9,31 @@ export declare class InjectionToken<T = unknown> {
     constructor(description: string, options?: InjectionTokenOptions<T> | undefined);
     toString(): string;
 }
+export declare class ForwardRef<T = unknown> {
+    readonly factory: () => Token<T>;
+    constructor(factory: () => Token<T>);
+}
+export declare function forwardRef<T>(factory: () => Token<T>): ForwardRef<T>;
 export type Token<T = any> = Type<T> | InjectionToken<T> | string | symbol;
 export interface InjectableOptions {
     scope?: Scope;
 }
 export interface InjectMetadata {
     index: number;
-    token: Token;
+    token?: Token | ForwardRef;
+    optional?: boolean;
 }
 export interface ProviderOptions<T = unknown> {
-    token?: Token<T>;
+    provide?: Token<T>;
     scope?: Scope;
     useValue?: T;
     useFactory?: (...args: any[]) => T | Promise<T>;
+    useClass?: Type<T>;
     inject?: Token[];
     useExisting?: Token<T>;
 }
 export interface ProviderRegistration<T = unknown> {
-    token: Token<T>;
+    provide: Token<T>;
     scope: Scope;
     instance?: T;
     useValue?: T;

package/dist/container/types.js

@@ -9,3 +9,12 @@ export class InjectionToken {
         return `InjectionToken(${this.description})`;
     }
 }
+export class ForwardRef {
+    factory;
+    constructor(factory){
+        this.factory = factory;
+    }
+}
+export function forwardRef(factory) {
+    return new ForwardRef(factory);
+}