@velajs/vela 1.9.0 → 1.12.0

package/dist/container/container.d.ts

@@ -17,6 +17,8 @@ export declare class Container {
     private scopes;
     private globals;
     private diagnostics;
+    private root;
+    private disposables;
     constructor(options?: ContainerOptions);
     register<T>(provider: Type<T> | ProviderOptions<T>, declaringModuleId?: string): this;
     private registerClass;
@@ -50,8 +52,41 @@ export declare class Container {
     has(token: Token): boolean;
     /** True if the specified module's bucket has a registration for `token`. */
     hasInScope(token: Token, moduleId: string): boolean;
+    /** Module buckets that hold a registration for `token` (registration order). */
+    getOwnerModuleIds(token: Token): string[];
+    /**
+     * 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<T>(provider: Type<T> | ProviderOptions<T>, options?: {
+        buckets?: 'all-existing' | 'root' | string[];
+    }): this;
     getProviderScope(token: Token): Scope | undefined;
     getTokens(): Token[];
+    /**
+     * Every statically-provided (useValue) instance across ALL module buckets.
+     * Unlike resolving a token (which yields only the first bucket's registration),
+     * this surfaces per-instance values — e.g. one BindingRef per multi-instance
+     * binding module — so framework adapters can initialize all of them.
+     */
+    getUseValues(): unknown[];
+    /**
+     * Compute request-scope bubbling for every registration (call once at
+     * bootstrap, after all providers are registered). A provider whose declared
+     * scope is not REQUEST but which (transitively) depends on a request-scoped
+     * provider is marked `effectiveScope = REQUEST`, so it is rebuilt per request
+     * instead of capturing the first request's instance — matching NestJS.
+     */
+    computeEffectiveScopes(): void;
+    /** The dependency tokens a registration would resolve when constructed. */
+    private dependencyTokensOf;
+    private tryFindRegistration;
     /**
      * Create a child container for request-scoped resolution.
      * The child shares the parent's providers but caches REQUEST-scoped
@@ -60,8 +95,31 @@ export declare class Container {
     createChild(): Container;
     createDetached(): Container;
     clear(): void;
+    /** Whether this container has any tracked disposables (cheap request-path check). */
+    hasDisposables(): boolean;
+    /**
+     * Dispose container-constructed instances (Symbol.asyncDispose /
+     * Symbol.dispose / .dispose()) in reverse creation order (LIFO). Errors are
+     * logged and skipped so one bad teardown never blocks the rest.
+     *
+     * A REQUEST child disposes only its own request-scoped instances; the root
+     * disposes shared SINGLETONs and clears their cached instance so a dev HMR
+     * generation cannot leak a stale graph. Shared provider maps are left intact
+     * for a request child (they belong to the root).
+     */
+    dispose(): Promise<void>;
     private resolveRegistration;
     private resolveClass;
+    /**
+     * 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.
+     */
+    private resolveFactoryDependency;
+    private resolveFactoryDependencyAsync;
     private resolveFactory;
     resolveAsync<T>(token: Token<T>, requestingModuleId?: string): Promise<T>;
     private createLazyProxy;

package/dist/container/container.js

@@ -1,4 +1,5 @@
 import { Scope } from "../constants.js";
+import { disposeInstance, isDisposable } from "./disposable.js";
 import { getConstructorDependencies, getInjectMetadata, getScope, isInjectable } from "./decorators.js";
 import { ForwardRef, InjectionToken, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID } from "./types.js";
 const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips type-only imports at ' + 'runtime and `design:paramtypes` emits `Object`/`undefined` for their ' + 'positions. Use a runtime `import { X }` for DI tokens.';
@@ -25,6 +26,13 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
     scopes = new Map();
     globals = new Set();
     diagnostics;
+    // The root container that owns shared state; a request child points back here
+    // so container-constructed SINGLETONs are tracked (and disposed) at the root,
+    // never by the ephemeral child that happened to first resolve them.
+    root = this;
+    // Container-constructed instances in creation order, for LIFO disposal.
+    // useValue providers are never tracked (they return before construction).
+    disposables = [];
     constructor(options = {}){
         this.diagnostics = options.diagnostics ?? 'log';
     }
@@ -280,12 +288,45 @@ 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);
+    }
     getProviderScope(token) {
         const exporters = this.exporterIndex.get(token);
         if (!exporters) return undefined;
         for (const owner of exporters){
             const reg = this.providers.get(owner)?.get(token);
-            if (reg) return reg.scope;
+            if (reg) return reg.effectiveScope ?? reg.scope;
         }
         return undefined;
     }
@@ -299,6 +340,95 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
         ];
     }
     /**
+   * Every statically-provided (useValue) instance across ALL module buckets.
+   * Unlike resolving a token (which yields only the first bucket's registration),
+   * this surfaces per-instance values — e.g. one BindingRef per multi-instance
+   * binding module — so framework adapters can initialize all of them.
+   */ getUseValues() {
+        const out = [];
+        for (const bucket of this.providers.values()){
+            for (const reg of bucket.values()){
+                if (reg.useValue !== undefined) out.push(reg.useValue);
+            }
+        }
+        return out;
+    }
+    /**
+   * Compute request-scope bubbling for every registration (call once at
+   * bootstrap, after all providers are registered). A provider whose declared
+   * scope is not REQUEST but which (transitively) depends on a request-scoped
+   * provider is marked `effectiveScope = REQUEST`, so it is rebuilt per request
+   * instead of capturing the first request's instance — matching NestJS.
+   */ computeEffectiveScopes() {
+        // Reverse-propagation worklist: seed with every declared-REQUEST provider,
+        // then flood "request-ness" to consumers transitively. This is order- and
+        // cycle-independent (a node flips to REQUEST at most once), avoiding the
+        // finalize-during-in-progress-cycle hazard of a recursive DFS.
+        const regs = [];
+        for (const bucket of this.providers.values()){
+            for (const reg of bucket.values()){
+                reg.effectiveScope = reg.scope;
+                regs.push(reg);
+            }
+        }
+        // Build reverse edges: dependency registration -> registrations that consume it.
+        const consumers = new Map();
+        for (const reg of regs){
+            for (const depToken of this.dependencyTokensOf(reg)){
+                const depReg = this.tryFindRegistration(depToken, reg.declaringModuleId);
+                if (!depReg) continue;
+                const list = consumers.get(depReg);
+                if (list) list.push(reg);
+                else consumers.set(depReg, [
+                    reg
+                ]);
+            }
+        }
+        const queue = regs.filter((r)=>r.effectiveScope === Scope.REQUEST);
+        while(queue.length > 0){
+            const dep = queue.pop();
+            for (const consumer of consumers.get(dep) ?? []){
+                if (consumer.effectiveScope !== Scope.REQUEST) {
+                    consumer.effectiveScope = Scope.REQUEST;
+                    queue.push(consumer);
+                }
+            }
+        }
+    }
+    /** The dependency tokens a registration would resolve when constructed. */ dependencyTokensOf(reg) {
+        if (reg.useExisting) return [
+            reg.useExisting
+        ];
+        if (reg.useFactory) {
+            return (reg.inject ?? []).map((t)=>t instanceof ForwardRef ? t.factory() : t);
+        }
+        const cls = reg.useClass ?? (typeof reg.provide === 'function' ? reg.provide : undefined);
+        if (!cls) return [];
+        const paramTypes = getConstructorDependencies(cls);
+        const injectMetadata = getInjectMetadata(cls);
+        const injectMap = new Map(injectMetadata.map((m)=>[
+                m.index,
+                m
+            ]));
+        const arity = Math.max(paramTypes.length, injectMetadata.reduce((max, m)=>Math.max(max, m.index + 1), 0));
+        const tokens = [];
+        for(let i = 0; i < arity; i++){
+            const raw = injectMap.get(i)?.token;
+            const token = raw instanceof ForwardRef ? raw.factory() : raw ?? paramTypes[i];
+            if (token && !isErasedTypeToken(token)) tokens.push(token);
+        }
+        return tokens;
+    }
+    tryFindRegistration(token, requestingModuleId) {
+        try {
+            return this.findRegistration(token, requestingModuleId);
+        } catch  {
+            // Ambiguous (MultipleProvidersFoundError) or unreachable — treat as
+            // unknown for scope computation; real resolution will surface any error.
+            return undefined;
+        }
+    }
+    /**
    * Create a child container for request-scoped resolution.
    * The child shares the parent's providers but caches REQUEST-scoped
    * instances separately per child (per request).
@@ -312,6 +442,9 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
         child.exporterIndex = this.exporterIndex;
         child.scopes = this.scopes;
         child.globals = this.globals;
+        // SINGLETON disposal is owned by the root; the child keeps only its own
+        // REQUEST-scoped disposables (cleared when the request ends).
+        child.root = this.root;
         return child;
     }
     createDetached() {
@@ -343,6 +476,44 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
         this.requestInstances.clear();
         this.scopes.clear();
         this.globals.clear();
+        this.disposables = [];
+    }
+    /** Whether this container has any tracked disposables (cheap request-path check). */ hasDisposables() {
+        return this.disposables.length > 0;
+    }
+    /**
+   * Dispose container-constructed instances (Symbol.asyncDispose /
+   * Symbol.dispose / .dispose()) in reverse creation order (LIFO). Errors are
+   * logged and skipped so one bad teardown never blocks the rest.
+   *
+   * A REQUEST child disposes only its own request-scoped instances; the root
+   * disposes shared SINGLETONs and clears their cached instance so a dev HMR
+   * generation cannot leak a stale graph. Shared provider maps are left intact
+   * for a request child (they belong to the root).
+   */ async dispose() {
+        const pending = this.disposables;
+        this.disposables = [];
+        for(let i = pending.length - 1; i >= 0; i--){
+            try {
+                await disposeInstance(pending[i]);
+            } catch (error) {
+                if (this.diagnostics !== 'silent') {
+                    console.error('Error disposing instance:', error);
+                }
+            }
+        }
+        this.requestInstances.clear();
+        if (this.root === this) {
+            // Drop cached singleton instances (except useValue, which the app owns)
+            // so a rebuilt graph starts clean.
+            for (const bucket of this.providers.values()){
+                for (const registration of bucket.values()){
+                    if (registration.scope === Scope.SINGLETON && registration.useValue === undefined) {
+                        registration.instance = undefined;
+                    }
+                }
+            }
+        }
     }
     resolveRegistration(registration, requestingModuleId) {
         if (registration.useValue !== undefined) {
@@ -352,12 +523,16 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
             // Pass through the original requester to catch alias leaks
             return this.resolve(registration.useExisting, requestingModuleId);
         }
+        // Effective scope accounts for request-scope bubbling: a SINGLETON that
+        // (transitively) depends on a request-scoped provider is treated as REQUEST
+        // so it is rebuilt per request instead of capturing the first one.
+        const scope = registration.effectiveScope ?? registration.scope;
         // Singleton: return cached from registration (shared across all containers)
-        if (registration.scope === Scope.SINGLETON && registration.instance !== undefined) {
+        if (scope === Scope.SINGLETON && registration.instance !== undefined) {
             return registration.instance;
         }
         // Request: return cached from this child's requestInstances
-        if (registration.scope === Scope.REQUEST) {
+        if (scope === Scope.REQUEST) {
             const cached = this.requestInstances.get(registration.provide);
             if (cached !== undefined) {
                 return cached;
@@ -374,20 +549,23 @@ 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);
             } else {
                 throw new Error(`Invalid provider registration for: ${this.tokenToString(registration.provide)}`);
             }
-            if (registration.scope === Scope.SINGLETON) {
+            if (scope === Scope.SINGLETON) {
                 registration.instance = instance;
-            } else if (registration.scope === Scope.REQUEST) {
+                // Track for disposal on the ROOT — a singleton outlives the request
+                // child that may have first constructed it.
+                if (isDisposable(instance)) this.root.disposables.push(instance);
+            } else if (scope === Scope.REQUEST) {
                 this.requestInstances.set(registration.provide, instance);
+                if (isDisposable(instance)) this.disposables.push(instance);
             }
             return instance;
         } finally{
@@ -432,16 +610,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) {
@@ -468,18 +670,21 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
             throw new Error(`No provider found for token: ${this.tokenToString(token)}`);
         }
         if (registration.useFactory) {
-            if (registration.scope === Scope.SINGLETON && registration.instance !== undefined) {
+            const scope = registration.effectiveScope ?? registration.scope;
+            if (scope === Scope.SINGLETON && registration.instance !== undefined) {
                 return registration.instance;
             }
-            // Factory inject deps resolve without a requester (same escape hatch as
-            // sync resolveFactory).
+            // 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 (registration.scope === Scope.SINGLETON) {
+            if (scope === Scope.SINGLETON) {
                 registration.instance = instance;
+                // Track for disposal on the ROOT, matching the sync resolveRegistration path.
+                if (isDisposable(instance)) this.root.disposables.push(instance);
             }
             return instance;
         }

package/dist/container/disposable.d.ts

@@ -0,0 +1,5 @@
+export interface Disposable {
+    dispose?(): void | Promise<void>;
+}
+export declare function isDisposable(value: unknown): boolean;
+export declare function disposeInstance(value: unknown): Promise<void>;

package/dist/container/disposable.js

@@ -0,0 +1,33 @@
+// 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
+// esnext.disposable typings.
+const ASYNC_DISPOSE = Symbol.asyncDispose;
+const SYNC_DISPOSE = Symbol.dispose;
+function asRecord(value) {
+    if (value === null) return undefined;
+    return typeof value === 'object' || typeof value === 'function' ? value : undefined;
+}
+export function isDisposable(value) {
+    const obj = asRecord(value);
+    if (!obj) return false;
+    if (ASYNC_DISPOSE && typeof obj[ASYNC_DISPOSE] === 'function') return true;
+    if (SYNC_DISPOSE && typeof obj[SYNC_DISPOSE] === 'function') return true;
+    return typeof obj.dispose === 'function';
+}
+export async function disposeInstance(value) {
+    const obj = asRecord(value);
+    if (!obj) return;
+    if (ASYNC_DISPOSE && typeof obj[ASYNC_DISPOSE] === 'function') {
+        await obj[ASYNC_DISPOSE].call(obj);
+        return;
+    }
+    if (SYNC_DISPOSE && typeof obj[SYNC_DISPOSE] === 'function') {
+        obj[SYNC_DISPOSE].call(obj);
+        return;
+    }
+    if (typeof obj.dispose === 'function') {
+        await obj.dispose.call(obj);
+    }
+}

package/dist/container/types.d.ts

@@ -57,7 +57,15 @@ export interface ProviderOptions<T = unknown> {
 }
 export interface ProviderRegistration<T = unknown> {
     provide: Token<T>;
+    /** The declared scope (from `@Injectable`/`@Controller`/provider options). */
     scope: Scope;
+    /**
+     * Scope after request-scope bubbling: `REQUEST` if this provider (transitively)
+     * depends on a request-scoped provider, else the declared scope. Computed once
+     * at bootstrap (`Container.computeEffectiveScopes`); falls back to `scope`
+     * until then. Governs caching + eager instantiation.
+     */
+    effectiveScope?: Scope;
     /**
      * Module that owns this registration. Used by `resolveClass` to determine
      * the POV from which the class's dependencies resolve. Sandbox/bootstrap

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;
+}