@velajs/vela 1.4.0 → 1.5.0

package/dist/module/module-loader.js

@@ -1,5 +1,5 @@
 import { Scope } from "../constants.js";
-import { ForwardRef, InjectionToken, ModuleVisibilityError } from "../container/types.js";
+import { ForwardRef, InjectionToken, ModuleVisibilityError, MultipleProvidersFoundError } from "../container/types.js";
 import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE } from "../pipeline/tokens.js";
 import { MetadataRegistry } from "../registry/metadata.registry.js";
 import { getOrCreateArray } from "../registry/util.js";
@@ -12,22 +12,43 @@ const APP_TOKENS = new Set([
     APP_FILTER,
     APP_MIDDLEWARE
 ]);
+const DEFAULT_KEY = "default";
 function isDynamicModule(value) {
+    // TS 4.9+ narrows `'module' in value` so `value.module` is typed `unknown`
+    // — no cast required for the typeof check below.
     return typeof value === "object" && value !== null && "module" in value && typeof value.module === "function";
 }
 function implementsNestModule(cls) {
+    // `Type.prototype` is `any` — direct property access is type-safe enough.
     return typeof cls.prototype?.configure === "function";
 }
 function tokenOfProvider(provider) {
     return typeof provider === "function" ? provider : provider.provide;
 }
+function keyOfImport(entry) {
+    return isDynamicModule(entry) ? entry.key ?? DEFAULT_KEY : DEFAULT_KEY;
+}
+/**
+ * `ForwardRef.factory` is typed to return the broader `Token<T>` because the
+ * primitive is shared with provider injection. In module-imports position the
+ * runtime contract narrows: the factory must yield a module class or a
+ * `DynamicModule`. This helper validates the contract AND narrows the type
+ * without a structural cast.
+ */ function unwrapModuleForwardRef(ref) {
+    const result = ref.factory();
+    if (typeof result === 'function') return result;
+    if (isDynamicModule(result)) return result;
+    throw new Error(`forwardRef in module imports must resolve to a module class or DynamicModule; ` + `got ${typeof result === 'object' ? 'a non-module object' : typeof result}.`);
+}
 export class ModuleLoader {
     container;
     router;
-    processedModules = new Set();
+    // class → set of keys already processed (multi-instance dedup is by both)
+    processedModules = new Map();
     processingStack = new Set();
     collectedControllers = new Set();
     registeredProviders = [];
+    // (class, key) → exported tokens
     moduleExportsCache = new Map();
     globalExports = new Set();
     consumerMiddlewareDefinitions = [];
@@ -54,7 +75,8 @@ export class ModuleLoader {
             []
         ]
     ]);
-    moduleIdByClass = new Map();
+    // (class, key) → composed moduleId (cached for stable identity within a load)
+    moduleIdByClassKey = new Map();
     seenModuleIds = new Set();
     constructor(container, router){
         this.container = container;
@@ -66,47 +88,80 @@ export class ModuleLoader {
             this.router.registerController(controller);
         }
     }
-    getModuleId(moduleClass) {
-        const cached = this.moduleIdByClass.get(moduleClass);
-        if (cached) return cached;
+    getModuleId(moduleClass, key) {
+        let perClass = this.moduleIdByClassKey.get(moduleClass);
+        if (perClass) {
+            const cached = perClass.get(key);
+            if (cached) return cached;
+        } else {
+            perClass = new Map();
+            this.moduleIdByClassKey.set(moduleClass, perClass);
+        }
         const baseName = moduleClass.name || "AnonModule";
-        let id = baseName;
+        let id = `${baseName}#${key}`;
         let counter = 0;
+        // Cross-class name collision (rare): two different classes named identically.
+        // The (class, key) pair identifies us; bump suffix to keep `id` strings unique
+        // in `seenModuleIds` so debug output stays unambiguous.
         while(this.seenModuleIds.has(id)){
-            id = `${baseName}#${++counter}`;
+            id = `${baseName}#${key}~${++counter}`;
         }
         this.seenModuleIds.add(id);
-        this.moduleIdByClass.set(moduleClass, id);
+        perClass.set(key, id);
         return id;
     }
+    isProcessed(moduleClass, key) {
+        return this.processedModules.get(moduleClass)?.has(key) ?? false;
+    }
+    markProcessed(moduleClass, key) {
+        let keys = this.processedModules.get(moduleClass);
+        if (!keys) {
+            keys = new Set();
+            this.processedModules.set(moduleClass, keys);
+        }
+        keys.add(key);
+    }
+    getCachedExports(moduleClass, key) {
+        return this.moduleExportsCache.get(moduleClass)?.get(key);
+    }
+    cacheExports(moduleClass, key, exports) {
+        let perClass = this.moduleExportsCache.get(moduleClass);
+        if (!perClass) {
+            perClass = new Map();
+            this.moduleExportsCache.set(moduleClass, perClass);
+        }
+        perClass.set(key, exports);
+    }
     processModule(moduleClassOrDynamic) {
-        // Handle dynamic modules ({ module, imports, controllers, providers })
         let moduleClass;
         let extraImports = [];
         let extraControllers = [];
         let extraProviders = [];
         let extraExports = [];
+        let key = DEFAULT_KEY;
         if (isDynamicModule(moduleClassOrDynamic)) {
             moduleClass = moduleClassOrDynamic.module;
             extraImports = moduleClassOrDynamic.imports ?? [];
             extraControllers = moduleClassOrDynamic.controllers ?? [];
             extraProviders = moduleClassOrDynamic.providers ?? [];
             extraExports = moduleClassOrDynamic.exports ?? [];
+            key = moduleClassOrDynamic.key ?? DEFAULT_KEY;
         } else {
             moduleClass = moduleClassOrDynamic;
         }
-        if (this.processedModules.has(moduleClass)) {
+        if (this.isProcessed(moduleClass, key)) {
             // Even if already processed, still collect extra controllers from dynamic module
             for (const controller of extraControllers){
                 this.collectedControllers.add(controller);
             }
-            return this.moduleExportsCache.get(moduleClass) ?? new Set();
+            return this.getCachedExports(moduleClass, key) ?? new Set();
         }
-        if (this.processingStack.has(moduleClass)) {
+        const stackKey = `${moduleClass.name}#${key}`;
+        if (this.processingStack.has(stackKey)) {
             const chain = [
                 ...this.processingStack,
-                moduleClass
-            ].map((m)=>m.name).join(" -> ");
+                stackKey
+            ].join(" -> ");
             throw new Error(`Circular module dependency detected: ${chain}`);
         }
         if (!isModule(moduleClass)) {
@@ -120,25 +175,35 @@ export class ModuleLoader {
         if (!metadata) {
             throw new Error(`Failed to get module metadata for ${moduleClass.name}`);
         }
-        this.processingStack.add(moduleClass);
-        const moduleId = this.getModuleId(moduleClass);
+        this.processingStack.add(stackKey);
+        const moduleId = this.getModuleId(moduleClass, key);
         try {
             const importedProviders = new Set(this.globalExports);
             // Determine importedModuleIds eagerly (before recursing) so child
             // modules can be referenced in our scope's importedModules set.
             const importedModuleIds = new Set();
-            for (const entry of [
+            // Track per-class keys seen in this imports array — emit a loader-time
+            // diagnostic when the same module class appears under both `"default"`
+            // and at least one explicit key (almost always user error).
+            const keysByClassInImports = new Map();
+            const allImports = [
                 ...metadata.imports,
                 ...extraImports
-            ]){
-                // Unwrap forwardRef(() => Module) — resolves lazy circular references
-                const isForwardRef = entry instanceof ForwardRef;
-                const importedModule = isForwardRef ? entry.factory() : entry;
+            ];
+            for (const entry of allImports){
+                const importedModule = entry instanceof ForwardRef ? unwrapModuleForwardRef(entry) : entry;
                 const importedModuleClass = isDynamicModule(importedModule) ? importedModule.module : importedModule;
-                importedModuleIds.add(this.getModuleId(importedModuleClass));
-                // If this forwardRef-wrapped import is currently being processed, skip it to
-                // break the circular chain. Non-forwardRef circular imports still throw.
-                if (isForwardRef && this.processingStack.has(importedModuleClass)) {
+                const importedKey = keyOfImport(importedModule);
+                let keys = keysByClassInImports.get(importedModuleClass);
+                if (!keys) {
+                    keys = new Set();
+                    keysByClassInImports.set(importedModuleClass, keys);
+                }
+                keys.add(importedKey);
+                const importedId = this.getModuleId(importedModuleClass, importedKey);
+                importedModuleIds.add(importedId);
+                const importedStackKey = `${importedModuleClass.name}#${importedKey}`;
+                if (entry instanceof ForwardRef && this.processingStack.has(importedStackKey)) {
                     continue;
                 }
                 const exportedTokens = this.processModule(importedModule);
@@ -146,6 +211,7 @@ export class ModuleLoader {
                     importedProviders.add(token);
                 }
             }
+            this.warnOnMixedDefaultAndKeyed(moduleClass.name, keysByClassInImports);
             const allProviders = [
                 ...metadata.providers,
                 ...extraProviders
@@ -183,15 +249,18 @@ export class ModuleLoader {
                 this.registerProvider(provider, moduleId);
             }
             for (const controller of allControllers){
+                // Register the controller in its owning module's bucket so its
+                // dependencies resolve from the module's POV (vs `__root__`'s).
+                this.container.register(controller, moduleId);
                 this.collectedControllers.add(controller);
             }
             // Propagate module-level Use* decorators (@UseGuards, @UseInterceptors, etc.) to each controller
             for (const controller of allControllers){
                 MetadataRegistry.propagateControllerComponents(moduleClass, controller);
             }
-            this.processedModules.add(moduleClass);
+            this.markProcessed(moduleClass, key);
             const exports = this.buildExportSet(allExports, allProviders, importedProviders);
-            this.moduleExportsCache.set(moduleClass, exports);
+            this.cacheExports(moduleClass, key, exports);
             if (isGlobal) {
                 for (const token of exports){
                     this.globalExports.add(token);
@@ -200,7 +269,7 @@ export class ModuleLoader {
             // Call configure() if the module implements NestModule. The module is
             // resolved through the container so it can have its own DI dependencies.
             if (implementsNestModule(moduleClass)) {
-                if (!this.container.has(moduleClass)) {
+                if (!this.container.hasInScope(moduleClass, moduleId)) {
                     this.container.register(moduleClass, moduleId);
                 }
                 const instance = this.container.resolve(moduleClass, moduleId);
@@ -210,15 +279,26 @@ export class ModuleLoader {
             }
             return exports;
         } finally{
-            this.processingStack.delete(moduleClass);
+            this.processingStack.delete(stackKey);
+        }
+    }
+    warnOnMixedDefaultAndKeyed(parentName, keysByClass) {
+        const mode = this.container.getDiagnostics();
+        if (mode === "silent") return;
+        for (const [cls, keys] of keysByClass){
+            if (keys.size < 2) continue;
+            if (!keys.has(DEFAULT_KEY)) continue;
+            const message = `[vela] ${cls.name} imported in both bare and keyed form in '${parentName}'. ` + `These resolve to distinct module instances; consumers asking for an exported ` + `token will hit MultipleProvidersFoundError. Use one form consistently.`;
+            if (mode === "throw") throw new Error(message);
+            console.warn(message);
         }
     }
     registerProvider(provider, moduleId) {
         if (typeof provider === "function") {
-            if (!this.container.has(provider)) {
-                this.container.register(provider, moduleId);
-                this.registeredProviders.push(provider);
-            }
+            // Per-module bucket: the same class can be registered in multiple
+            // modules' buckets simultaneously without collision.
+            this.container.register(provider, moduleId);
+            this.registeredProviders.push(provider);
         } else {
             const token = provider.provide;
             if (!token) {
@@ -226,22 +306,21 @@ export class ModuleLoader {
                 return;
             }
             if (this.isAppToken(token)) {
+                // Multiple APP_* providers within the same module bucket need
+                // distinct tokens so they don't overwrite each other in the bucket
+                // Map. Across buckets, `container.resolveAll(APP_GUARD)` walks
+                // every bucket — no need to mark synthetic tokens global.
                 const syntheticToken = new InjectionToken(`${token.toString()}:${this.appProviderCounter++}`);
                 this.container.register({
                     ...provider,
                     provide: syntheticToken
                 }, moduleId);
-                // Synthetic APP_* tokens are resolved at request time by RouteManager
-                // with no requester; mark them global so the visibility check passes.
-                this.container.markGlobalToken(syntheticToken);
                 this.registeredProviders.push(syntheticToken);
                 getOrCreateArray(this.appProviderTokens, token).push(syntheticToken);
                 return;
             }
-            if (!this.container.has(token)) {
-                this.container.register(provider, moduleId);
-                this.registeredProviders.push(token);
-            }
+            this.container.register(provider, moduleId);
+            this.registeredProviders.push(token);
         }
     }
     isAppToken(token) {
@@ -258,7 +337,7 @@ export class ModuleLoader {
             const isLocalProvider = providerTokens.has(exported);
             const isImportedProvider = importedProviders.has(exported);
             if (!isLocalProvider && !isImportedProvider) {
-                const name = exported.name ?? String(exported);
+                const name = typeof exported === 'function' ? exported.name : String(exported);
                 console.warn(`Warning: Exporting '${name}' which is neither a local provider nor imported from another module.`);
             }
             exportSet.add(exported);
@@ -295,9 +374,9 @@ export class ModuleLoader {
                 const instance = await this.container.resolveAsync(token);
                 instanceSet.add(instance);
             } catch (err) {
-                // Module visibility errors must always propagate — they indicate a
-                // genuine wiring bug, not something to swallow as a discovery skip.
-                if (err instanceof ModuleVisibilityError) throw err;
+                if (err instanceof ModuleVisibilityError || err instanceof MultipleProvidersFoundError) {
+                    throw err;
+                }
                 this.routeError(err, `resolve provider`);
             }
         }
@@ -309,7 +388,9 @@ export class ModuleLoader {
                 const instance = await this.container.resolveAsync(controller);
                 instanceSet.add(instance);
             } catch (err) {
-                if (err instanceof ModuleVisibilityError) throw err;
+                if (err instanceof ModuleVisibilityError || err instanceof MultipleProvidersFoundError) {
+                    throw err;
+                }
                 this.routeError(err, `resolve controller ${controller.name}`);
             }
         }
@@ -323,7 +404,6 @@ export class ModuleLoader {
         if (mode === "throw") {
             throw err instanceof Error ? err : new Error(String(err));
         }
-        // 'log'
         console.warn(`[vela] ${context} failed:`, err);
     }
 }

package/dist/module/stable-hash.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Deterministic, sync, edge-safe hash for module-instance discrimination.
+ *
+ * Walks values (objects/arrays/primitives/functions/class instances) into a
+ * sorted, source-fingerprinting JSON string, then runs FNV-1a (32-bit) for a
+ * compact 8-hex-char output.
+ *
+ * Functions and class instances are tolerated — they become `__fn:source` or
+ * `__cls:ClassName` markers. Two distinct closures with the same source code
+ * collide; module authors who care about that should pass an explicit `key`.
+ *
+ * Not cryptographic. Sufficient for discriminating module instances within
+ * an app.
+ */
+export declare function stableHash(value: unknown): string;

package/dist/module/stable-hash.js

@@ -0,0 +1,52 @@
+/**
+ * Deterministic, sync, edge-safe hash for module-instance discrimination.
+ *
+ * Walks values (objects/arrays/primitives/functions/class instances) into a
+ * sorted, source-fingerprinting JSON string, then runs FNV-1a (32-bit) for a
+ * compact 8-hex-char output.
+ *
+ * Functions and class instances are tolerated — they become `__fn:source` or
+ * `__cls:ClassName` markers. Two distinct closures with the same source code
+ * collide; module authors who care about that should pass an explicit `key`.
+ *
+ * Not cryptographic. Sufficient for discriminating module instances within
+ * an app.
+ */ export function stableHash(value) {
+    return fnv1a(stableStringify(value));
+}
+function stableStringify(value) {
+    if (value === null || value === undefined) return JSON.stringify(value) ?? 'undefined';
+    if (typeof value === 'function') {
+        // Source-fingerprint via FNV-1a so we don't bloat the parent hash; this
+        // keeps two distinct factory functions distinguishable as long as their
+        // source differs (the common case). Names are intentionally excluded —
+        // two arrow functions with the same body should dedup.
+        return `__fn:${fnv1a(value.toString())}`;
+    }
+    if (typeof value === 'symbol') {
+        return `__sym:${value.description ?? ''}`;
+    }
+    if (typeof value !== 'object') return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return '[' + value.map(stableStringify).join(',') + ']';
+    }
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== null && proto !== Object.prototype) {
+        const name = proto?.constructor?.name ?? 'AnonymousClass';
+        return `__cls:${name}` + stringifyOwnProps(value);
+    }
+    return stringifyOwnProps(value);
+}
+function stringifyOwnProps(obj) {
+    const keys = Object.keys(obj).sort();
+    const parts = keys.map((k)=>JSON.stringify(k) + ':' + stableStringify(obj[k]));
+    return '{' + parts.join(',') + '}';
+}
+function fnv1a(s) {
+    let h = 0x811c9dc5;
+    for(let i = 0; i < s.length; i++){
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0).toString(16).padStart(8, '0');
+}

package/dist/registry/types.d.ts

@@ -45,6 +45,17 @@ export interface AsyncModuleOptions<T = unknown> {
 }
 export interface DynamicModule {
     module: Type;
+    /**
+     * Author-supplied instance discriminator. Two DynamicModules with the same
+     * `module` class and the same `key` dedup; with different keys they coexist
+     * as separate module instances. Defaults to `"default"` when absent — which
+     * preserves single-instance dedup for the common case.
+     *
+     * For `forRoot(options)`, derive `key: stableHash(options)` so identical
+     * options dedup automatically. For `forRootAsync` (factories aren't
+     * structurally hashable), pass an explicit string.
+     */
+    key?: string;
     imports?: ModuleImport[];
     providers?: Array<Type | ProviderOptions>;
     controllers?: Type[];

package/dist/throttler/throttler.module.d.ts

@@ -1,6 +1,10 @@
 import type { AsyncModuleOptions, DynamicModule } from '../module/types';
 import type { ThrottlerModuleOptions } from './throttler.types';
 export declare class ThrottlerModule {
-    static forRoot(options: ThrottlerModuleOptions): DynamicModule;
-    static forRootAsync(options: AsyncModuleOptions<ThrottlerModuleOptions>): DynamicModule;
+    static forRoot(options: ThrottlerModuleOptions & {
+        key?: string;
+    }): DynamicModule;
+    static forRootAsync(options: AsyncModuleOptions<ThrottlerModuleOptions> & {
+        key?: string;
+    }): DynamicModule;
 }

package/dist/throttler/throttler.module.js

@@ -1,3 +1,4 @@
+import { stableHash } from "../module/stable-hash.js";
 import { APP_GUARD } from "../pipeline/tokens.js";
 import { ThrottlerGuard } from "./throttler.guard.js";
 import { ThrottlerStorage } from "./throttler.storage.js";
@@ -21,6 +22,7 @@ export class ThrottlerModule {
         ];
         return {
             module: ThrottlerModule,
+            key: options.key ?? stableHash(options),
             providers,
             exports: [
                 THROTTLER_OPTIONS,
@@ -51,6 +53,10 @@ export class ThrottlerModule {
         ];
         return {
             module: ThrottlerModule,
+            key: options.key ?? stableHash({
+                inject: options.inject,
+                useFactory: options.useFactory
+            }),
             imports: options.imports ?? [],
             providers,
             exports: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/vela",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "NestJS-compatible framework for edge runtimes, powered by Hono",
   "type": "module",
   "main": "./dist/index.js",