@velajs/vela 1.10.0 → 1.13.0

package/dist/container/container.js

@@ -33,9 +33,40 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
     // Container-constructed instances in creation order, for LIFO disposal.
     // useValue providers are never tracked (they return before construction).
     disposables = [];
+    // Lazy-module seam (root-owned; children reach it via this.root). A
+    // resolution of a deferred registration CLAIMS its module; claimed groups
+    // are completed (constructed + hooks replayed) only when the resolution
+    // stack has unwound and no resolveAsync cascade is in flight — running the
+    // replay mid-construction could force-resolve a class currently on the
+    // resolution stack (discovery cascades) and mint a spurious
+    // circular-dependency error.
+    lazyHook;
+    asyncDepth = 0;
     constructor(options = {}){
         this.diagnostics = options.diagnostics ?? 'log';
     }
+    /** Install the lazy-module seam (bootstrap-time; root container only). */ setLazyHook(hook) {
+        this.root.lazyHook = hook;
+    }
+    claimLazyModule(declaringModuleId) {
+        const hook = this.root.lazyHook;
+        if (hook?.isPending(declaringModuleId)) {
+            hook.claim(declaringModuleId);
+        }
+    }
+    maybeDrainSync() {
+        const root = this.root;
+        const hook = root.lazyHook;
+        if (!hook?.hasClaimed()) return;
+        // Never replay hooks while construction is in flight; an async cascade
+        // drains (with await) at its own end instead. A running drain picks
+        // pending claims up itself — re-entering it is at best a no-op and on
+        // the async path a self-deadlock.
+        if (this.resolutionStack.size > 0) return;
+        if (root.asyncDepth > 0) return;
+        if (hook.isDraining()) return;
+        hook.drainSync();
+    }
     register(provider, declaringModuleId) {
         const moduleId = declaringModuleId ?? ROOT_MODULE_ID;
         if (typeof provider === 'function') {
@@ -125,7 +156,9 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
     resolve(token, requestingModuleId) {
         const registration = this.findRegistration(token, requestingModuleId);
         if (registration) {
-            return this.resolveRegistration(registration, requestingModuleId);
+            const instance = this.resolveRegistration(registration, requestingModuleId);
+            this.maybeDrainSync();
+            return instance;
         }
         // Visibility error fires first when the token exists in some bucket but
         // isn't reachable from the requester's scope — the user wants to know
@@ -155,7 +188,9 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
     }
     resolveAll(token, requestingModuleId) {
         const registrations = this.findAllRegistrations(token, requestingModuleId);
-        return registrations.map((r)=>this.resolveRegistration(r, requestingModuleId));
+        const instances = registrations.map((r)=>this.resolveRegistration(r, requestingModuleId));
+        this.maybeDrainSync();
+        return instances;
     }
     /**
    * Find a single reachable registration for a token, applying the visibility
@@ -288,6 +323,65 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
     /** True if the specified module's bucket has a registration for `token`. */ hasInScope(token, moduleId) {
         return this.providers.get(moduleId)?.has(token) ?? false;
     }
+    /** Module buckets that hold a registration for `token` (registration order). */ getOwnerModuleIds(token) {
+        return [
+            ...this.exporterIndex.get(token) ?? []
+        ];
+    }
+    /**
+   * Force-replace a provider across module scopes — the supported form of the
+   * override loop test harnesses need (module-scoped resolution consults the
+   * module's own bucket first, so a root-only override would never win there).
+   *
+   * - `'all-existing'` (default): every non-root bucket that already holds the
+   *   token, plus `__root__` (so framework-internal lookups see it too).
+   * - `'root'`: only the `__root__` bucket.
+   * - `string[]`: exactly these bucket ids.
+   */ replaceProvider(provider, options = {}) {
+        const buckets = options.buckets ?? 'all-existing';
+        if (buckets === 'root') {
+            return this.register(provider);
+        }
+        if (Array.isArray(buckets)) {
+            for (const moduleId of buckets)this.register(provider, moduleId);
+            return this;
+        }
+        const token = typeof provider === 'function' ? provider : provider.provide;
+        if (!token) {
+            throw new Error('replaceProvider requires a token (`provide`)');
+        }
+        for (const [moduleId, bucket] of this.providers){
+            if (moduleId === ROOT_MODULE_ID) continue;
+            if (bucket.has(token)) this.register(provider, moduleId);
+        }
+        return this.register(provider);
+    }
+    /**
+   * True when the token belongs exclusively to lazy modules that have not
+   * been materialized yet — resolving it would trigger materialization.
+   * Build-time probes (route-manager middleware priority, entrypoint
+   * snapshots) use this to defer instead of forcing the group.
+   */ isLazyPending(token) {
+        const hook = this.root.lazyHook;
+        if (!hook) return false;
+        const owners = this.exporterIndex.get(token);
+        if (!owners || owners.size === 0) return false;
+        for (const owner of owners){
+            if (!hook.isPending(owner)) return false;
+        }
+        return true;
+    }
+    /**
+   * True when any registration of the token holds a constructed instance.
+   * Diagnostic helper (cold-start tests): checks WITHOUT resolving, so it
+   * never triggers lazy materialization.
+   */ isInstantiated(token) {
+        for (const owner of this.exporterIndex.get(token) ?? []){
+            const reg = this.providers.get(owner)?.get(token);
+            if (reg && reg.instance !== undefined) return true;
+        }
+        return false;
+    }
     getProviderScope(token) {
         const exporters = this.exporterIndex.get(token);
         if (!exporters) return undefined;
@@ -434,6 +528,13 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
         child.exporterIndex = clonedIndex;
         child.scopes = this.scopes;
         child.globals = this.globals;
+        // Registration objects are shallow-shared, so a sandbox resolve of a lazy
+        // module's singleton caches onto the SHARED registration. Point the
+        // sandbox at the real root so that resolution claims the module and
+        // replays its hooks like any other trigger — otherwise ModuleRef.create
+        // would leave a hook-less instance poisoning the shared cache (and its
+        // disposables tracked on an ephemeral root).
+        child.root = this.root;
         return child;
     }
     clear() {
@@ -484,8 +585,12 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
     }
     resolveRegistration(registration, requestingModuleId) {
         if (registration.useValue !== undefined) {
+            // Deliberately BEFORE the lazy claim: reading a lazy module's useValue
+            // (options tokens) has no construction cost to defer and must not
+            // materialize the group.
             return registration.useValue;
         }
+        this.claimLazyModule(registration.declaringModuleId);
         if (registration.useExisting) {
             // Pass through the original requester to catch alias leaks
             return this.resolve(registration.useExisting, requestingModuleId);
@@ -516,10 +621,9 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
         try {
             let instance;
             if (registration.useFactory) {
-                // Factories (forRootAsync, useFactory) commonly inject deps from the
-                // importing module's scope. Vela has no `forRootAsync({ imports })`
-                // surface to track that, so factory inject deps resolve from the
-                // declaring module's POV — same escape-hatch shape as ModuleRef.
+                // Factory inject deps resolve from the declaring module's scope first
+                // (visibility-correct for forRootAsync), with the legacy no-requester
+                // lookup kept as fallback — see resolveFactoryDependency.
                 instance = this.resolveFactory(registration);
             } else if (registration.useClass) {
                 instance = this.resolveClass(registration.useClass, registration.declaringModuleId);
@@ -578,16 +682,40 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
         });
         return new target(...dependencies);
     }
+    /**
+   * Resolve one factory `inject` dependency. Since 1.11 the declaring module's
+   * scope is consulted FIRST (proper visibility semantics — a `forRootAsync`
+   * factory can inject providers reachable through its module's imports); on
+   * any failure the legacy no-requester lookup (root bucket, then first
+   * exporter) is kept as fallback, so every previously-resolving graph still
+   * resolves.
+   */ resolveFactoryDependency(token, declaringModuleId) {
+        if (declaringModuleId !== ROOT_MODULE_ID && this.scopes.has(declaringModuleId)) {
+            try {
+                return this.resolve(token, declaringModuleId);
+            } catch  {
+            // Fall through to the legacy escape hatch below.
+            }
+        }
+        return this.resolve(token);
+    }
+    async resolveFactoryDependencyAsync(token, declaringModuleId) {
+        if (declaringModuleId !== ROOT_MODULE_ID && this.scopes.has(declaringModuleId)) {
+            try {
+                return await this.resolveAsync(token, declaringModuleId);
+            } catch  {
+            // Fall through to the legacy escape hatch below.
+            }
+        }
+        return this.resolveAsync(token);
+    }
     resolveFactory(registration) {
         if (!registration.useFactory) {
             throw new Error('Factory function is missing');
         }
-        // Factory inject deps resolve without a requester — Vela has no
-        // `forRootAsync({ imports })` surface to track which module the factory
-        // resolves from, so it uses the same escape-hatch shape as ModuleRef.
         const dependencies = (registration.inject || []).map((token)=>{
             const resolved = token instanceof ForwardRef ? token.factory() : token;
-            return this.resolve(resolved);
+            return this.resolveFactoryDependency(resolved, registration.declaringModuleId);
         });
         const result = registration.useFactory(...dependencies);
         if (result instanceof Promise) {
@@ -596,6 +724,20 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
         return result;
     }
     async resolveAsync(token, requestingModuleId) {
+        const root = this.root;
+        root.asyncDepth++;
+        let result;
+        try {
+            result = await this.resolveAsyncInner(token, requestingModuleId);
+        } finally{
+            root.asyncDepth--;
+        }
+        if (root.asyncDepth === 0 && root.lazyHook?.hasClaimed() && !root.lazyHook.isDraining()) {
+            await root.lazyHook.drainAsync();
+        }
+        return result;
+    }
+    async resolveAsyncInner(token, requestingModuleId) {
         const registration = this.findRegistration(token, requestingModuleId);
         if (!registration) {
             if (requestingModuleId !== undefined && this.scopes.has(requestingModuleId) && this.exporterIndex.has(token)) {
@@ -618,11 +760,12 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
             if (scope === Scope.SINGLETON && registration.instance !== undefined) {
                 return registration.instance;
             }
-            // Factory inject deps resolve without a requester (same escape hatch as
-            // sync resolveFactory).
+            this.claimLazyModule(registration.declaringModuleId);
+            // Module scope first, legacy no-requester fallback — same policy as the
+            // sync resolveFactory path.
             const dependencies = await Promise.all((registration.inject || []).map((t)=>{
                 const resolved = t instanceof ForwardRef ? t.factory() : t;
-                return this.resolveAsync(resolved);
+                return this.resolveFactoryDependencyAsync(resolved, registration.declaringModuleId);
             }));
             const instance = await registration.useFactory(...dependencies);
             if (scope === Scope.SINGLETON) {

package/dist/container/disposable.js

@@ -1,4 +1,4 @@
-// Edge-safe disposal contract (mirrors stratal's). Precedence:
+// Edge-safe disposal contract. Precedence:
 //   Symbol.asyncDispose > Symbol.dispose > .dispose()
 // Symbol.asyncDispose/Symbol.dispose are resolved at runtime (they are not in
 // the ES2022 lib the project targets), so nothing here depends on the

package/dist/container/types.d.ts

@@ -85,6 +85,33 @@ export interface ModuleScope {
     importedModules: Set<string>;
     exportedTokens: Set<Token>;
     isGlobal: boolean;
+    /** Module instance opted into deferred (first-use) materialization. */
+    lazy?: boolean;
+}
+/**
+ * The container's seam into lazy-module materialization (implemented by
+ * `LazyModuleManager`). The container only ever *claims* a pending module at
+ * a resolution trigger and *drains* completed claims when the resolution
+ * stack has fully unwound — construction and hook replay live behind this
+ * interface so the container stays module-system-agnostic.
+ */
+export interface LazyResolutionHook {
+    /** Is this module instance still deferred (untriggered)? */
+    isPending(moduleId: string): boolean;
+    /** Mark a pending module as triggered; idempotent. */
+    claim(moduleId: string): void;
+    /** Any claimed-but-unmaterialized groups? (cheap fast-path check) */
+    hasClaimed(): boolean;
+    /**
+     * A drain loop is currently running. The container must NOT start (or
+     * await) another drain from inside it — the running loop picks pending
+     * claims up; awaiting would self-deadlock on the async path.
+     */
+    isDraining(): boolean;
+    /** Complete claimed groups synchronously; throws if async work surfaces. */
+    drainSync(): void;
+    /** Complete claimed groups, awaiting async construction and hooks. */
+    drainAsync(): Promise<void>;
 }
 export type Diagnostics = 'silent' | 'log' | 'throw';
 export interface ContainerOptions {

package/dist/cors/cors.module.d.ts

@@ -1,7 +1,7 @@
-import type { DynamicModule } from '../module/types';
 import type { CorsOptions } from './cors.types';
-export declare class CorsModule {
-    static forRoot(options?: CorsOptions & {
-        key?: string;
-    }): DynamicModule;
+declare const ConfigurableModuleClass: import("..").ConfigurableModuleClassType<CorsOptions, "forRoot", "create", {
+    isGlobal?: boolean;
+}>;
+export declare class CorsModule extends ConfigurableModuleClass {
 }
+export {};

package/dist/cors/cors.module.js

@@ -1,36 +1,37 @@
 import { cors } from "hono/cors";
-import { stableHash } from "../module/stable-hash.js";
+import { defineModule } from "../module/define-module.js";
 import { APP_MIDDLEWARE } from "../pipeline/tokens.js";
 import { CORS_OPTIONS } from "./cors.tokens.js";
-export class CorsModule {
-    static forRoot(options = {}) {
-        const corsMiddleware = cors({
-            origin: options.origin ?? '*',
-            allowMethods: options.allowMethods,
-            allowHeaders: options.allowHeaders,
-            exposeHeaders: options.exposeHeaders,
-            credentials: options.credentials,
-            maxAge: options.maxAge
-        });
-        const middleware = {
-            use: (c, next)=>corsMiddleware(c, next)
-        };
-        return {
-            module: CorsModule,
-            key: options.key ?? stableHash(options),
+function buildCorsMiddleware(options) {
+    const corsMiddleware = cors({
+        origin: options.origin ?? '*',
+        allowMethods: options.allowMethods,
+        allowHeaders: options.allowHeaders,
+        exposeHeaders: options.exposeHeaders,
+        credentials: options.credentials,
+        maxAge: options.maxAge
+    });
+    return {
+        use: (c, next)=>corsMiddleware(c, next)
+    };
+}
+const { ConfigurableModuleClass } = defineModule({
+    name: 'Cors',
+    optionsToken: CORS_OPTIONS,
+    setup: ({ OPTIONS })=>({
             providers: [
-                {
-                    provide: CORS_OPTIONS,
-                    useValue: options
-                },
                 {
                     provide: APP_MIDDLEWARE,
-                    useValue: middleware
+                    useFactory: (options)=>buildCorsMiddleware(options),
+                    inject: [
+                        OPTIONS
+                    ]
                 }
             ],
             exports: [
-                CORS_OPTIONS
+                OPTIONS
             ]
-        };
-    }
+        })
+});
+export class CorsModule extends ConfigurableModuleClass {
 }

package/dist/discovery/discoverable.decorator.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A decorator whose annotated classes/methods are findable through
+ * `DiscoveryService` by the decorator itself (no string key at the call site).
+ */
+export interface DiscoverableDecorator<T> {
+    (value: T): ClassDecorator & MethodDecorator;
+    /** The metadata key backing this decorator — stable across HMR re-evals. */
+    KEY: string;
+}
+export interface CreateDiscoverableDecoratorOptions {
+    /**
+     * Append to a class-level list instead of overwriting a single slot —
+     * for stackable method decorators (`@Cron`-style: each application pushes
+     * `{ methodName, ...value }` onto the class's list, which
+     * `DiscoveryService.methodsWithMeta` flattens back to per-method entries).
+     */
+    append?: boolean;
+}
+/**
+ * Mint a discoverable decorator for a module's extension surface:
+ *
+ * ```ts
+ * export interface QueueConsumerMeta { queue: string }
+ * export const QueueConsumer = createDiscoverableDecorator<QueueConsumerMeta>('vela:queue:consumer');
+ *
+ * @QueueConsumer({ queue: 'emails' })
+ * @Injectable()
+ * class EmailConsumer { ... }
+ *
+ * // At bootstrap, anywhere:
+ * discovery.providersWithMeta(QueueConsumer)  // typed { meta: QueueConsumerMeta }
+ * ```
+ *
+ * Unlike `Reflector.createDecorator`, the key is required and caller-chosen:
+ * a random key would mint a fresh identity on every HMR re-eval and orphan
+ * previously-decorated classes. Namespace it (`'<pkg>:<area>:<thing>'`).
+ */
+export declare function createDiscoverableDecorator<T>(key: string, options?: CreateDiscoverableDecoratorOptions): DiscoverableDecorator<T>;

package/dist/discovery/discoverable.decorator.js

@@ -0,0 +1,42 @@
+import { MetadataRegistry } from "../registry/metadata.registry.js";
+/**
+ * Mint a discoverable decorator for a module's extension surface:
+ *
+ * ```ts
+ * export interface QueueConsumerMeta { queue: string }
+ * export const QueueConsumer = createDiscoverableDecorator<QueueConsumerMeta>('vela:queue:consumer');
+ *
+ * @QueueConsumer({ queue: 'emails' })
+ * @Injectable()
+ * class EmailConsumer { ... }
+ *
+ * // At bootstrap, anywhere:
+ * discovery.providersWithMeta(QueueConsumer)  // typed { meta: QueueConsumerMeta }
+ * ```
+ *
+ * Unlike `Reflector.createDecorator`, the key is required and caller-chosen:
+ * a random key would mint a fresh identity on every HMR re-eval and orphan
+ * previously-decorated classes. Namespace it (`'<pkg>:<area>:<thing>'`).
+ */ export function createDiscoverableDecorator(key, options = {}) {
+    const decorator = (value)=>{
+        return (target, propertyKey)=>{
+            const ctor = propertyKey !== undefined ? target.constructor : target;
+            if (options.append) {
+                if (propertyKey !== undefined) {
+                    MetadataRegistry.appendCustomClassMeta(ctor, key, {
+                        methodName: propertyKey,
+                        ...value
+                    });
+                } else {
+                    MetadataRegistry.appendCustomClassMeta(ctor, key, value);
+                }
+            } else if (propertyKey !== undefined) {
+                MetadataRegistry.setCustomHandlerMeta(ctor, propertyKey, key, value);
+            } else {
+                MetadataRegistry.setCustomClassMeta(ctor, key, value);
+            }
+        };
+    };
+    decorator.KEY = key;
+    return decorator;
+}

package/dist/discovery/discovery.service.d.ts

@@ -0,0 +1,102 @@
+import { Scope } from '../constants';
+import { Container } from '../container/container';
+import type { Token, Type } from '../container/types';
+import type { Constructor } from '../registry/types';
+import type { DiscoverableDecorator } from './discoverable.decorator';
+/** A container-registered class provider surfaced by discovery. */
+export interface DiscoveredClass<T = unknown> {
+    token: Token;
+    metatype: Type<T>;
+    /** Module buckets holding this token (registration order; first = primary). */
+    moduleIds: string[];
+    scope: Scope;
+    /**
+     * Resolved instance. `undefined` only when the provider is request-scoped
+     * and `includeRequestScoped` was not set — request-scoped providers cannot
+     * be materialized at bootstrap without fabricating a phantom request.
+     */
+    instance: T | undefined;
+}
+export interface DiscoveredMethodMeta<M = unknown> {
+    class: DiscoveredClass;
+    methodName: string | symbol;
+    meta: M;
+}
+export interface DiscoveryFilter {
+    /** Restrict to providers declared by these module buckets. */
+    moduleId?: string | string[];
+    /**
+     * Resolve request-scoped providers too (constructs an instance outside any
+     * request — only for callers that know what they're doing). Default false:
+     * request-scoped hits are skipped with a diagnostics warning.
+     */
+    includeRequestScoped?: boolean;
+    /**
+     * Return providers of not-yet-materialized lazy modules as metadata-only
+     * entries (`instance: undefined`, mirroring the request-scoped convention)
+     * instead of resolving them — which would force the whole module group.
+     * Used by `EntrypointRegistry.build`; default false so every existing
+     * scanner keeps its transparent cascade-materialization semantics.
+     */
+    deferLazy?: boolean;
+}
+/**
+ * Decorator-driven provider discovery — the public replacement for the
+ * bootstrap scan every subsystem used to hand-roll (`container.getTokens()` +
+ * `MetadataRegistry.getCustomClassMeta` + `resolve` + diagnostics handling).
+ *
+ * Registered globally by `bootstrap()`, so any provider can inject it:
+ *
+ * ```ts
+ * @Injectable()
+ * class MyRegistry implements OnApplicationBootstrap {
+ *   constructor(private readonly discovery: DiscoveryService) {}
+ *   onApplicationBootstrap() {
+ *     for (const { instance, meta } of this.discovery.providersWithMeta<MyMeta>(MY_KEY)) {
+ *       this.register(instance, meta);
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * Discovery is kernel-level, not encapsulation-scoped: module visibility
+ * protects modules from *each other*, never from the framework's own
+ * dispatchers. Use `DiscoveryFilter.moduleId` for the rare narrowing case.
+ *
+ * The resolve-failure policy honors the container's diagnostics mode exactly
+ * like the legacy loops: `throw` rethrows, `log` warns and skips, `silent`
+ * skips — so a broken provider never silently changes discovery semantics.
+ */
+export declare class DiscoveryService {
+    private readonly container;
+    constructor(container: Container);
+    /** Every class-token provider registered in the container. */
+    getProviders(filter?: DiscoveryFilter): DiscoveredClass[];
+    /**
+     * Providers whose class carries class-level metadata under `key` — both
+     * class decorators (single value) and method decorators that append
+     * class-level lists (`@Cron`, `@OnEvent`, `@SubscribeMessage`).
+     */
+    providersWithMeta<M>(key: string | DiscoverableDecorator<M>, filter?: DiscoveryFilter): Array<DiscoveredClass & {
+        meta: M;
+    }>;
+    /**
+     * Handler methods carrying metadata under `key`. Merges the two storage
+     * conventions:
+     *  - class-level appended lists whose items carry `methodName`
+     *    (`@Cron`/`@OnEvent`-style method decorators), and
+     *  - true handler-level metadata (`@SetMetadata`/`createDiscoverableDecorator`
+     *    applied to a method).
+     */
+    methodsWithMeta<M>(key: string | DiscoverableDecorator<M>, filter?: DiscoveryFilter): DiscoveredMethodMeta<M>[];
+    /**
+     * Index-first candidate walk with a legacy full-scan fallback: when the
+     * reverse index knows nothing about a key, an older copy of the registry
+     * module may have taken the writes (mixed dist/src or package versions in
+     * one process) — fall back to scanning container tokens the way the
+     * pre-DiscoveryService loops did.
+     */
+    private candidatesWithClassMeta;
+    private buildEntry;
+}
+export type { Constructor };