moost 0.6.35 → 0.6.37

package/dist/index.cjs

@@ -48,7 +48,7 @@ let stamped = false;
 	if (stamped) return;
 	stamped = true;
 	stampModuleIdentity({
-		version: "0.6.35",
+		version: "0.6.37",
 		path: typeof __filename === "string" ? __filename : require("url").pathToFileURL(__filename).href
 	});
 }
@@ -225,6 +225,18 @@ let loggingOptions = {
 /** Returns the shared Infact DI container used by Moost for dependency injection. */ function getMoostInfact() {
 	return sharedMoostInfact;
 }
+/**
+* Every SINGLETON instance currently held by an Infact container's **global**
+* registry (per-event `scopes` registries are excluded — those instances are
+* torn down with their event).
+*
+* Infact keeps the registry as a protected symbol-keyed object; this helper
+* centralizes the one cast needed to read it, so consumers
+* (`Moost.dispose()`, the `@moostjs/vite` dev plugin) do not each re-derive it.
+*/ function getInfactSingletonInstances(infact = getMoostInfact()) {
+	const { registry } = infact;
+	return Object.getOwnPropertySymbols(registry).map((k) => registry[k]).filter(Boolean);
+}
 const scopeVarsMap = /* @__PURE__ */ new Map();
 /**
 * Define global scope name to be used with `@InjectFromScope` and `@InjectScopeVars` decorators
@@ -640,6 +652,126 @@ function nextScopeId() {
 	}
 }
 
+//#endregion
+//#region packages/moost/src/dispose.ts
+/**
+* Instances whose dispose hooks already ran. Module-level and weak, so
+* disposal is at-most-once per instance no matter which entry point triggers
+* it — `Moost.dispose()` twice, or a hot-reload eject followed by a shutdown,
+* never re-runs a hook.
+*/ const disposedInstances = /* @__PURE__ */ new WeakSet();
+const DISPOSE_BANNER = `moost`;
+/**
+* `Symbol.asyncDispose` / `Symbol.dispose` are only present on newer runtimes —
+* resolve them once through a guarded read so older ones simply have no
+* well-known fallback hook.
+*/ const asyncDisposeSymbol = typeof Symbol.asyncDispose === "symbol" ? Symbol.asyncDispose : void 0;
+const disposeSymbol = typeof Symbol.dispose === "symbol" ? Symbol.dispose : void 0;
+/** Class name of an instance, read through the prototype (never touches own props). */ function classNameOf(instance) {
+	return Object.getPrototypeOf(instance)?.constructor?.name || "Object";
+}
+/** @internal Message of a thrown value, whatever it is. */ function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/** `Class.method (message)` pairs for every failed hook. */ function formatDisposeErrors(errors) {
+	const list = errors.map((e) => `${classNameOf(e.instance)}.${String(e.method)} (${errorMessage(e.error)})`).join(", ");
+	return `[moost] ${errors.length} dispose hook(s) failed: ${list}`;
+}
+/**
+* True when `sym` resolves to a data property holding a function anywhere on the
+* instance/prototype chain. Descriptor based — accessors are never invoked.
+*/ function hasSymbolMethod(instance, sym) {
+	if (!sym) return false;
+	let obj = instance;
+	while (obj && obj !== Object.prototype) {
+		const desc = Object.getOwnPropertyDescriptor(obj, sym);
+		if (desc) return typeof desc.value === "function";
+		obj = Object.getPrototypeOf(obj);
+	}
+	return false;
+}
+/**
+* Dispose hooks of one instance: every `@MoostDispose`-decorated method or —
+* when the class decorates none — its `Symbol.asyncDispose` / `Symbol.dispose`
+* method (preferring the async one) as a single priority-0 hook. The method
+* scan goes through `getInstanceOwnMethods`, which classifies by descriptor and
+* never evaluates getters.
+*/ function collectHooks(instance) {
+	const mate = getMoostMate();
+	const hooks = [];
+	for (const method of getInstanceOwnMethods(instance)) {
+		const priority = mate.read(instance, method)?.moostDispose?.priority;
+		if (typeof priority === "number") hooks.push({
+			instance,
+			method,
+			priority
+		});
+	}
+	if (hooks.length > 0) return hooks;
+	const sym = hasSymbolMethod(instance, asyncDisposeSymbol) ? asyncDisposeSymbol : hasSymbolMethod(instance, disposeSymbol) ? disposeSymbol : void 0;
+	return sym ? [{
+		instance,
+		method: sym,
+		priority: 0
+	}] : [];
+}
+async function runHook(hook, errors, opts) {
+	const fn = hook.instance[hook.method];
+	try {
+		await fn.call(hook.instance);
+	} catch (error) {
+		errors.push({
+			instance: hook.instance,
+			method: hook.method,
+			error
+		});
+		if (opts?.onError !== "throw") (opts?.logger || getDefaultLogger(DISPOSE_BANNER)).warn(`[moost] dispose hook ${classNameOf(hook.instance)}.${String(hook.method)} failed: ${errorMessage(error)}`);
+	}
+}
+/**
+* Runs the dispose hooks of every given instance, once per instance, ever.
+*
+* A hook is either a `@MoostDispose()`-decorated method or, when the class
+* decorates none, the instance's `[Symbol.asyncDispose]()` / `[Symbol.dispose]()`
+* method. Hooks run **sequentially** in ascending `priority` (ties keep input
+* order) and each one is awaited, so teardown that must happen in order (drain
+* consumers, then close the connection they use) can be expressed with
+* priorities.
+*
+* Failures never stop the run: with `onError: 'warn'` (default) each one is
+* logged and collected; with `onError: 'throw'` every hook still runs and one
+* `AggregateError` is thrown at the end.
+*
+* Instances already disposed (by an earlier call, or by `Moost.dispose()`) are
+* skipped, so passing overlapping sets is safe.
+*/ async function disposeInstances(instances, opts) {
+	const hooks = [];
+	const disposed = [];
+	for (const instance of instances) {
+		if (!instance || disposedInstances.has(instance)) continue;
+		disposedInstances.add(instance);
+		const own = collectHooks(instance);
+		if (own.length > 0) {
+			disposed.push(instance);
+			hooks.push(...own);
+		}
+	}
+	const errors = [];
+	for (const hook of hooks.toSorted((a, b) => a.priority - b.priority)) await runHook(hook, errors, opts);
+	if (opts?.onError === "throw" && errors.length > 0) throw new AggregateError(errors.map((e) => e.error), formatDisposeErrors(errors));
+	return {
+		hooks: hooks.length,
+		errors,
+		disposed
+	};
+}
+/**
+* @internal Renders the aggregate message used when disposal failures are
+* rethrown (`Moost.dispose()` and `disposeInstances(..., { onError: 'throw' })`).
+*/ function describeDisposeErrors(errors) {
+	return formatDisposeErrors(errors);
+}
+
 //#endregion
 //#region packages/moost/src/decorators/circular.decorator.ts
 /**
@@ -767,6 +899,56 @@ function ImportController(prefix, controller, provide) {
 	}, true);
 }
 
+//#endregion
+//#region packages/moost/src/decorators/dispose.decorator.ts
+/**
+* ## MoostDispose
+* ### @Decorator
+* Marks a method to run **once**, when its instance is **disposed** — either by
+* `Moost.dispose()` (graceful shutdown) or by the `@moostjs/vite` dev server
+* when the instance is ejected on hot reload. It is the teardown counterpart of
+* {@link MoostInit}: release what the singleton owns (a queue consumer, a cache
+* client, a database handle, timers, watchers) so a replaced instance does not
+* leak it.
+*
+* Works on SINGLETON controllers **and** on any `@Injectable()` singleton — the
+* hooks are discovered from live instances at dispose time, so a provider that
+* owns a connection is covered without being a controller.
+*
+* The method takes **no arguments** (dispose tears down an existing instance —
+* inject whatever it needs in the constructor). Async methods are awaited.
+* Errors are collected, not fatal: every other hook still runs, `Moost.dispose()`
+* then rejects with an `AggregateError`, and a hot reload only warns.
+*
+* An instance is disposed at most once (tracked per instance), so a second
+* `dispose()` — or an eject followed by a shutdown — never re-runs a hook.
+*
+* When a class defines no `@MoostDispose` method but exposes
+* `[Symbol.asyncDispose]()` / `[Symbol.dispose]()`, that is used instead.
+*
+* Applying `@MoostDispose` to a `FOR_EVENT` **controller** is a configuration
+* error and throws at bind time (per-event instances are torn down with their
+* event — put the hook on the singleton that owns the resource). On a
+* `FOR_EVENT` **injectable** the hook is simply never invoked.
+*
+* @param opts.priority lower runs first across all `@MoostDispose` methods (default 0)
+*
+* @example
+* ```ts
+* │  @Injectable()
+* │  export class CacheClient {
+* │    private readonly client = createCacheClient()
+* │
+* │    @MoostDispose()
+* │    async close() {
+* │      await this.client.quit()
+* │    }
+* │  }
+* ```
+*/ function MoostDispose(opts) {
+	return getMoostMate().decorate("moostDispose", { priority: opts?.priority ?? 0 }, false);
+}
+
 //#endregion
 //#region packages/moost/src/decorators/resolve.decorator.ts
 /**
@@ -1612,6 +1794,7 @@ async function bindControllerMethods(options) {
 			className: classConstructor.name,
 			methodName: method
 		}));
+		if (methodMeta.moostDispose && meta.injectable === "FOR_EVENT") throw new Error(`@MoostDispose is not allowed on a FOR_EVENT controller (${classConstructor.name}.${String(method)}). Dispose hooks run on the SINGLETON instance; FOR_EVENT instances are torn down with their event — put the hook on the singleton that owns the resource.`);
 		if (methodMeta.moostInit) {
 			if (meta.injectable === "FOR_EVENT") throw new Error(`@MoostInit is not allowed on a FOR_EVENT controller (${classConstructor.name}.${String(method)}). Init hooks run once at boot on the SINGLETON instance; FOR_EVENT controllers have no init-time instance.`);
 			const initArgsPipes = (methodMeta.params || []).map((p) => ({
@@ -1769,6 +1952,67 @@ function lostCtorParamsMessage(input, ancestor, count) {
 	return [auditRouteDrop(input), auditLostCtorParams(input)].filter((f) => f !== void 0);
 }
 
+//#endregion
+//#region packages/moost/src/dispose-signals.ts
+/**
+* Global key for the record above. Global (rather than module-scoped) for the
+* same reason the module-identity stamp is: two copies of moost, or the entry
+* re-executing under the `@moostjs/vite` dev server, must share one set of
+* process listeners instead of stacking one per app.
+*/ const DISPOSE_SIGNALS_KEY = Symbol.for("moost:dispose-on-signals");
+/**
+* Removes every registered listener and forgets the record. A no-op for a record
+* that is no longer the live one (a stale unregister fn, or a signal that already
+* dropped it).
+*/ function dropSignalsRecord(record) {
+	const holder = globalThis;
+	if (holder[DISPOSE_SIGNALS_KEY] !== record) return;
+	for (const [signal, listener] of record.listeners) process.off(signal, listener);
+	record.listeners.clear();
+	delete holder[DISPOSE_SIGNALS_KEY];
+}
+/**
+* The one listener body per signal (NestJS `enableShutdownHooks` semantics):
+* unhook every listener first, dispose the newest app, then re-raise `signal`
+* so the process exits with Node's default status for it. Because the listeners
+* are already gone, a second signal while disposal runs gets Node's default
+* handling (exit `128 + n`) — an impatient Ctrl-C is never stuck.
+*/ async function onSignal(signal) {
+	const record = globalThis[DISPOSE_SIGNALS_KEY];
+	if (!record) return;
+	const { app } = record;
+	dropSignalsRecord(record);
+	try {
+		await app.dispose();
+	} catch (error) {
+		app.getLogger().warn(`[moost] dispose on ${signal} failed: ${errorMessage(error)}`);
+	}
+	process.kill(process.pid, signal);
+}
+/**
+* @internal Backs `Moost.disposeOnSignals()` — see that method's JSDoc for the
+* full contract. Registers at most one process listener per signal, ever, and
+* re-targets the existing ones at `app`.
+*/ function registerDisposeOnSignals(app, signals) {
+	var _holder, _DISPOSE_SIGNALS_KEY;
+	const record = (_holder = globalThis)[_DISPOSE_SIGNALS_KEY = DISPOSE_SIGNALS_KEY] ?? (_holder[_DISPOSE_SIGNALS_KEY] = {
+		app,
+		listeners: /* @__PURE__ */ new Map()
+	});
+	record.app = app;
+	for (const signal of signals) {
+		if (record.listeners.has(signal)) continue;
+		const listener = () => {
+			onSignal(signal);
+		};
+		record.listeners.set(signal, listener);
+		process.on(signal, listener);
+	}
+	return () => {
+		dropSignalsRecord(record);
+	};
+}
+
 //#endregion
 //#region packages/moost/src/moost.ts
 function _define_property(obj, key, value) {
@@ -1932,6 +2176,84 @@ function _define_property(obj, key, value) {
 		});
 	}
 	/**
+	* ### dispose
+	* Graceful shutdown: stops the adapters, then runs every `@MoostDispose`
+	* hook of every singleton this app can reach — DI registry singletons
+	* (`@Injectable()` providers included) plus the controller instances bound at
+	* boot. A class with no decorated hook but an `[Symbol.asyncDispose]()` /
+	* `[Symbol.dispose]()` method is disposed through that.
+	*
+	* Order: every adapter's `onDispose` in registration order (stop taking new
+	* work first), then instance hooks by ascending `priority`. Everything is
+	* awaited, failures never stop the run — once all hooks have run, a failed
+	* disposal rejects the returned promise with an `AggregateError` naming each
+	* failing `Class.method`.
+	*
+	* Idempotent: the promise of the first call is returned for every later one,
+	* and an instance already disposed (e.g. ejected by the `@moostjs/vite` dev
+	* server) is skipped.
+	*
+	* DI registries and metadata caches are left intact — use the existing
+	* cleanup helpers when a clean container is what you need.
+	*
+	* ```ts
+	* app.disposeOnSignals() // SIGTERM + SIGINT → dispose() → re-raise
+	* ```
+	*/ dispose() {
+		if (!this.disposePromise) this.disposePromise = this.runDispose();
+		return this.disposePromise;
+	}
+	/**
+	* ### disposeOnSignals
+	* Disposes this app when the process receives one of `signals` (default
+	* `['SIGTERM', 'SIGINT']`), then re-raises the signal with no listener left,
+	* so the process exits with Node's default status for it.
+	*
+	* Registers each process listener **once per process**: calling it again —
+	* e.g. the entry re-executing under the `@moostjs/vite` dev server — re-targets
+	* the existing listeners at the newest app instead of stacking one handler per
+	* old app (which is what a plain `process.once(...)` in the entry does, until
+	* Node warns about a listener leak). Signals are unioned across calls; an
+	* already-registered one is never replaced or removed.
+	*
+	* A second signal while disposal runs gets Node's default handling, since the
+	* listeners are already removed. A failing `dispose()` is logged as a warning
+	* and the signal is re-raised all the same.
+	*
+	* Returns a function that unregisters the listeners (tests, embedded runners).
+	*
+	* ```ts
+	* await app.init()
+	* app.disposeOnSignals()
+	* ```
+	*/ disposeOnSignals(signals = ["SIGTERM", "SIGINT"]) {
+		return registerDisposeOnSignals(this, signals);
+	}
+	/** Adapters' `onDispose` in registration order; errors are collected, not fatal. */ async disposeAdapters() {
+		const errors = [];
+		for (const a of this.adapters) try {
+			await a.onDispose?.(this);
+		} catch (error) {
+			errors.push({
+				instance: a,
+				method: "onDispose",
+				error
+			});
+			this.logger.warn(`[moost] adapter "${a.name}" onDispose failed: ${errorMessage(error)}`);
+		}
+		return errors;
+	}
+	/** The one-shot body behind {@link Moost.dispose} (see its docs for the contract). */ async runDispose() {
+		const errors = await this.disposeAdapters();
+		const result = await disposeInstances([...getInfactSingletonInstances(), ...this.singletonInstances], {
+			logger: this.logger,
+			onError: "warn"
+		});
+		errors.push(...result.errors);
+		this.logger.debug(`[moost] disposed: ${this.adapters.length} adapter(s), ${result.hooks} hook(s), ${errors.length} error(s)`);
+		if (errors.length > 0) throw new AggregateError(errors.map((e) => e.error), describeDisposeErrors(errors));
+	}
+	/**
 	* D1 audit of a DI-instantiated controller class' constructor params.
 	* Findings are collected for `init()` to flush. Returns `true` when the
 	* bind-time SINGLETON instantiation must be skipped: in `'error'` mode a
@@ -1990,6 +2312,7 @@ function _define_property(obj, key, value) {
 			instance = controller;
 			infact.setInstanceRegistries(instance, provide, replace, { pipes });
 		}
+		if (instance) this.singletonInstances.add(instance);
 		const getInstance = instance ? () => instance : async () => await infact.get(controller, { ...infactOpts });
 		const classConstructor = (0, _prostojs_mate.isConstructor)(controller) ? controller : (0, _prostojs_mate.getConstructor)(controller);
 		const controllerOverview = await bindControllerMethods({
@@ -2165,7 +2488,7 @@ function _define_property(obj, key, value) {
 		this.logger.info(`${prefix || ""}${c}${eventName} ${"\x1B[0m\x1B[2m\x1B[32m" + c}→ ${classConstructor.name}.${"\x1B[36m" + c}${method}()${coff}`);
 	}
 	constructor(options) {
-		super(), _define_property(this, "options", void 0), _define_property(this, "logger", void 0), _define_property(this, "pipes", void 0), _define_property(this, "interceptors", void 0), _define_property(this, "adapters", void 0), _define_property(this, "controllersOverview", void 0), _define_property(this, "handlerOverviewIndex", void 0), _define_property(this, "initHooks", void 0), _define_property(this, "provide", void 0), _define_property(this, "replace", void 0), _define_property(this, "unregisteredControllers", void 0), _define_property(this, "paramAuditFindings", void 0), _define_property(this, "paramAuditMode", void 0), _define_property(this, "inheritanceAuditMode", void 0), _define_property(this, "initialized", void 0), _define_property(this, "globalInterceptorHandler", void 0), this.options = options, this.pipes = Array.from(sharedPipes), this.interceptors = [], this.adapters = [], this.controllersOverview = [], this.initHooks = [], this.provide = (0, _prostojs_infact.createProvideRegistry)([_prostojs_infact.Infact, getMoostInfact], [_prostojs_mate.Mate, getMoostMate]), this.replace = {}, this.unregisteredControllers = [], this.paramAuditFindings = [], this.initialized = false;
+		super(), _define_property(this, "options", void 0), _define_property(this, "logger", void 0), _define_property(this, "pipes", void 0), _define_property(this, "interceptors", void 0), _define_property(this, "adapters", void 0), _define_property(this, "controllersOverview", void 0), _define_property(this, "handlerOverviewIndex", void 0), _define_property(this, "initHooks", void 0), _define_property(this, "provide", void 0), _define_property(this, "replace", void 0), _define_property(this, "unregisteredControllers", void 0), _define_property(this, "paramAuditFindings", void 0), _define_property(this, "paramAuditMode", void 0), _define_property(this, "inheritanceAuditMode", void 0), _define_property(this, "initialized", void 0), _define_property(this, "singletonInstances", void 0), _define_property(this, "disposePromise", void 0), _define_property(this, "globalInterceptorHandler", void 0), this.options = options, this.pipes = Array.from(sharedPipes), this.interceptors = [], this.adapters = [], this.controllersOverview = [], this.initHooks = [], this.provide = (0, _prostojs_infact.createProvideRegistry)([_prostojs_infact.Infact, getMoostInfact], [_prostojs_mate.Mate, getMoostMate]), this.replace = {}, this.unregisteredControllers = [], this.paramAuditFindings = [], this.initialized = false, this.singletonInstances = /* @__PURE__ */ new Set();
 		this.paramAuditMode = resolveParamAuditMode(options?.diagnostics?.paramTypes);
 		this.inheritanceAuditMode = options?.diagnostics?.inheritance || "warn";
 		this.logger = options?.logger || getDefaultLogger(`moost`);
@@ -2275,6 +2598,7 @@ exports.Label = Label;
 exports.LoggerTopic = LoggerTopic;
 exports.MOOST_MODULE_IDENTITY_KEY = MOOST_MODULE_IDENTITY_KEY;
 exports.Moost = Moost;
+exports.MoostDispose = MoostDispose;
 exports.MoostInit = MoostInit;
 exports.OnError = OnError;
 exports.Optional = Optional;
@@ -2340,6 +2664,7 @@ exports.defineInfactScope = defineInfactScope;
 exports.defineInterceptor = defineInterceptor;
 exports.defineMoostEventHandler = defineMoostEventHandler;
 exports.definePipeFn = definePipeFn;
+exports.disposeInstances = disposeInstances;
 Object.defineProperty(exports, 'eventTypeKey', {
   enumerable: true,
   get: function () {
@@ -2366,6 +2691,7 @@ Object.defineProperty(exports, 'getGlobalWooks', {
 });
 exports.getHandlerPaths = getHandlerPaths;
 exports.getInfactScopeVars = getInfactScopeVars;
+exports.getInfactSingletonInstances = getInfactSingletonInstances;
 exports.getInstanceOwnMethods = getInstanceOwnMethods;
 exports.getInstanceOwnProps = getInstanceOwnProps;
 exports.getMoostInfact = getMoostInfact;

package/dist/index.d.ts

@@ -168,6 +168,55 @@ declare function ImportController(controller: TFunction | TObject, provide?: TPr
  */
 declare function ImportController(prefix: string, controller: TFunction | TObject, provide?: TProvideRegistry): ClassDecorator;
 
+/**
+ * ## MoostDispose
+ * ### @Decorator
+ * Marks a method to run **once**, when its instance is **disposed** — either by
+ * `Moost.dispose()` (graceful shutdown) or by the `@moostjs/vite` dev server
+ * when the instance is ejected on hot reload. It is the teardown counterpart of
+ * {@link MoostInit}: release what the singleton owns (a queue consumer, a cache
+ * client, a database handle, timers, watchers) so a replaced instance does not
+ * leak it.
+ *
+ * Works on SINGLETON controllers **and** on any `@Injectable()` singleton — the
+ * hooks are discovered from live instances at dispose time, so a provider that
+ * owns a connection is covered without being a controller.
+ *
+ * The method takes **no arguments** (dispose tears down an existing instance —
+ * inject whatever it needs in the constructor). Async methods are awaited.
+ * Errors are collected, not fatal: every other hook still runs, `Moost.dispose()`
+ * then rejects with an `AggregateError`, and a hot reload only warns.
+ *
+ * An instance is disposed at most once (tracked per instance), so a second
+ * `dispose()` — or an eject followed by a shutdown — never re-runs a hook.
+ *
+ * When a class defines no `@MoostDispose` method but exposes
+ * `[Symbol.asyncDispose]()` / `[Symbol.dispose]()`, that is used instead.
+ *
+ * Applying `@MoostDispose` to a `FOR_EVENT` **controller** is a configuration
+ * error and throws at bind time (per-event instances are torn down with their
+ * event — put the hook on the singleton that owns the resource). On a
+ * `FOR_EVENT` **injectable** the hook is simply never invoked.
+ *
+ * @param opts.priority lower runs first across all `@MoostDispose` methods (default 0)
+ *
+ * @example
+ * ```ts
+ * │  @Injectable()
+ * │  export class CacheClient {
+ * │    private readonly client = createCacheClient()
+ * │
+ * │    @MoostDispose()
+ * │    async close() {
+ * │      await this.client.quit()
+ * │    }
+ * │  }
+ * ```
+ */
+declare function MoostDispose(opts?: {
+    priority?: number;
+}): MethodDecorator;
+
 type TDecoratorLevel = 'CLASS' | 'METHOD' | 'PROP' | 'PARAM';
 
 /** Metadata context passed to pipe functions during argument/property resolution. */
@@ -311,6 +360,14 @@ interface TMoostMetadata<H extends TObject = TEmpty> extends TCommonMetaFields,
     moostInit?: {
         priority: number;
     };
+    /**
+     * Set by `@MoostDispose()` — marks a method to run when the instance is
+     * disposed (`Moost.dispose()`, or a hot-reload eject in `@moostjs/vite`).
+     * `priority` orders hooks (ascending) across all instances.
+     */
+    moostDispose?: {
+        priority: number;
+    };
     params: (TMateParamMeta & TMoostParamsMetadata)[];
 }
 /** Metadata attached to constructor/method parameters by Moost decorators. */
@@ -365,6 +422,16 @@ interface TInfactLoggingOptions {
 declare function setInfactLoggingOptions(options: TInfactLoggingOptions): void;
 /** Returns the shared Infact DI container used by Moost for dependency injection. */
 declare function getMoostInfact(): Infact<TMoostMetadata<TEmpty>, TMoostMetadata<TEmpty>, TMoostParamsMetadata, TCustom>;
+/**
+ * Every SINGLETON instance currently held by an Infact container's **global**
+ * registry (per-event `scopes` registries are excluded — those instances are
+ * torn down with their event).
+ *
+ * Infact keeps the registry as a protected symbol-keyed object; this helper
+ * centralizes the one cast needed to read it, so consumers
+ * (`Moost.dispose()`, the `@moostjs/vite` dev plugin) do not each re-derive it.
+ */
+declare function getInfactSingletonInstances(infact?: ReturnType<typeof getMoostInfact>): object[];
 interface TCustom {
     pipes?: TPipeData[];
 }
@@ -417,6 +484,53 @@ interface TInitHook {
 /** Mode for the bind-time inheritance audit (see `TMoostOptions['diagnostics']`). */
 type TInheritanceAuditMode = 'warn' | 'off';
 
+/** One failed dispose hook: the instance, the method that threw, and the thrown value. */
+interface TDisposeError {
+    instance: object;
+    method: string | symbol;
+    error: unknown;
+}
+/** Outcome of {@link disposeInstances}: how many hooks ran, and which of them failed. */
+interface TDisposeResult {
+    /** Number of hooks invoked (a class may declare several). */
+    hooks: number;
+    /** Failed hooks, in run order. */
+    errors: TDisposeError[];
+    /**
+     * Instances that had at least one hook invoked — i.e. the ones actually torn
+     * down, as opposed to the ones passed in that declare no hook at all.
+     */
+    disposed: object[];
+}
+/** Options for {@link disposeInstances}. */
+interface TDisposeOptions {
+    /** Logger for `onError: 'warn'` diagnostics; defaults to the Moost default logger. */
+    logger?: TConsoleBase;
+    /**
+     * `'warn'` (default) — log every failure and keep going;
+     * `'throw'` — still run every hook, then throw one `AggregateError`.
+     */
+    onError?: 'warn' | 'throw';
+}
+/**
+ * Runs the dispose hooks of every given instance, once per instance, ever.
+ *
+ * A hook is either a `@MoostDispose()`-decorated method or, when the class
+ * decorates none, the instance's `[Symbol.asyncDispose]()` / `[Symbol.dispose]()`
+ * method. Hooks run **sequentially** in ascending `priority` (ties keep input
+ * order) and each one is awaited, so teardown that must happen in order (drain
+ * consumers, then close the connection they use) can be expressed with
+ * priorities.
+ *
+ * Failures never stop the run: with `onError: 'warn'` (default) each one is
+ * logged and collected; with `onError: 'throw'` every hook still runs and one
+ * `AggregateError` is thrown at the end.
+ *
+ * Instances already disposed (by an earlier call, or by `Moost.dispose()`) are
+ * skipped, so passing overlapping sets is safe.
+ */
+declare function disposeInstances(instances: Iterable<object>, opts?: TDisposeOptions): Promise<TDisposeResult>;
+
 interface TMoostOptions {
     /**
      * Global path prefix — mounts the whole app under one path segment.
@@ -580,6 +694,15 @@ declare class Moost extends Hookable {
     protected readonly inheritanceAuditMode: TInheritanceAuditMode;
     /** D5: set once `init()` completes — late provide/replace registrations then warn. */
     protected initialized: boolean;
+    /**
+     * SINGLETON controller instances this app obtained at bind time (DI-resolved
+     * or registered as objects). They are disposed together with the DI registry
+     * singletons — an object-registered controller never enters the Infact
+     * registry, so it would otherwise be missed.
+     */
+    protected singletonInstances: Set<object>;
+    /** In-flight/settled `dispose()` run — makes disposal idempotent. */
+    protected disposePromise?: Promise<void>;
     constructor(options?: TMoostOptions | undefined);
     _fireEventStart(source: TMoostAdapter<unknown>): void;
     _fireEventEnd(source: TMoostAdapter<unknown>): void;
@@ -617,6 +740,61 @@ declare class Moost extends Hookable {
      * A throwing hook rejects `init()` (fail-fast).
      */
     protected runInitHooks(): Promise<void>;
+    /**
+     * ### dispose
+     * Graceful shutdown: stops the adapters, then runs every `@MoostDispose`
+     * hook of every singleton this app can reach — DI registry singletons
+     * (`@Injectable()` providers included) plus the controller instances bound at
+     * boot. A class with no decorated hook but an `[Symbol.asyncDispose]()` /
+     * `[Symbol.dispose]()` method is disposed through that.
+     *
+     * Order: every adapter's `onDispose` in registration order (stop taking new
+     * work first), then instance hooks by ascending `priority`. Everything is
+     * awaited, failures never stop the run — once all hooks have run, a failed
+     * disposal rejects the returned promise with an `AggregateError` naming each
+     * failing `Class.method`.
+     *
+     * Idempotent: the promise of the first call is returned for every later one,
+     * and an instance already disposed (e.g. ejected by the `@moostjs/vite` dev
+     * server) is skipped.
+     *
+     * DI registries and metadata caches are left intact — use the existing
+     * cleanup helpers when a clean container is what you need.
+     *
+     * ```ts
+     * app.disposeOnSignals() // SIGTERM + SIGINT → dispose() → re-raise
+     * ```
+     */
+    dispose(): Promise<void>;
+    /**
+     * ### disposeOnSignals
+     * Disposes this app when the process receives one of `signals` (default
+     * `['SIGTERM', 'SIGINT']`), then re-raises the signal with no listener left,
+     * so the process exits with Node's default status for it.
+     *
+     * Registers each process listener **once per process**: calling it again —
+     * e.g. the entry re-executing under the `@moostjs/vite` dev server — re-targets
+     * the existing listeners at the newest app instead of stacking one handler per
+     * old app (which is what a plain `process.once(...)` in the entry does, until
+     * Node warns about a listener leak). Signals are unioned across calls; an
+     * already-registered one is never replaced or removed.
+     *
+     * A second signal while disposal runs gets Node's default handling, since the
+     * listeners are already removed. A failing `dispose()` is logged as a warning
+     * and the signal is re-raised all the same.
+     *
+     * Returns a function that unregisters the listeners (tests, embedded runners).
+     *
+     * ```ts
+     * await app.init()
+     * app.disposeOnSignals()
+     * ```
+     */
+    disposeOnSignals(signals?: NodeJS.Signals[]): () => void;
+    /** Adapters' `onDispose` in registration order; errors are collected, not fatal. */
+    protected disposeAdapters(): Promise<TDisposeError[]>;
+    /** The one-shot body behind {@link Moost.dispose} (see its docs for the contract). */
+    protected runDispose(): Promise<void>;
     /**
      * D1 audit of a DI-instantiated controller class' constructor params.
      * Findings are collected for `init()` to flush. Returns `true` when the
@@ -719,6 +897,13 @@ interface TMoostAdapter<H> {
     name: string;
     bindHandler: <T extends TObject = TObject>(options: TMoostAdapterOptions<H, T>) => void | Promise<void>;
     onInit?: (moost: Moost) => void | Promise<void>;
+    /**
+     * Called by {@link Moost.dispose} **before** any `@MoostDispose` instance
+     * hook, in adapter registration order: stop taking new work here (close the
+     * server, stop the consumer/engine). Awaited; a throwing `onDispose` is
+     * logged and collected, never aborts the rest of the shutdown.
+     */
+    onDispose?: (moost: Moost) => void | Promise<void>;
     getProvideRegistry?: () => TProvideRegistry;
 }
 
@@ -1270,5 +1455,5 @@ declare function createLogger(opts?: Partial<TProstoLoggerOptions>): ProstoLogge
 /** Default colored console transport used by Moost loggers. */
 declare const loggerConsoleTransport: _prostojs_logger.TProstoLoggerTransportFn<any>;
 
-export { After, ApplyDecorators, Before, Circular, Const, ConstFactory, Controller, Description, HandlerPaths, Id, ImportController, Inherit, Inject, InjectEventLogger, InjectFromScope, InjectMoost, InjectMoostLogger, InjectScopeVars, Injectable, Intercept, Interceptor, InterceptorHandler, Label, LoggerTopic, MOOST_MODULE_IDENTITY_KEY, Moost, MoostInit, OnError, Optional, Overtake, Param, Params, Pipe, Provide, Replace, Required, Resolve, Response, TInterceptorPriority, TPipePriority, Value, createLogger, defineAfterInterceptor, defineBeforeInterceptor, defineErrorInterceptor, defineInfactScope, defineInterceptor, defineMoostEventHandler, definePipeFn, getHandlerPaths, getInfactScopeVars, getInstanceOwnMethods, getInstanceOwnProps, getMoostInfact, getMoostMate, getNewMoostInfact, globalKey, isThenable, loggerConsoleTransport, mergeSorted, registerEventScope, resolvePipe, setControllerContext, setInfactLoggingOptions, setInterceptResult, setOvertake, stampModuleIdentity, stampOnce, useControllerContext, useHandlerPaths, useInterceptResult, useOvertake, useScopeId };
-export type { TAny, TAnyFn, TClassConstructor, TContextInjectorHook, TControllerOverview, TControllerRegistration, TControllersGroup, TEmpty, TFunction, TGetHandlerPathsOptions, TInjectableScope, TInterceptorAfterFn, TInterceptorBeforeFn, TInterceptorData, TInterceptorDef, TInterceptorDefFactory, TInterceptorEntry, TInterceptorErrorFn, TLogger, TMoostAdapter, TMoostAdapterOptions, TMoostEventHandlerHookOptions, TMoostEventHandlerOptions, TMoostHandler, TMoostMetadata, TMoostModuleIdentity, TMoostOptions, TMoostParamsMetadata, TObject, TOvertakeFn, TPipeData, TPipeFn, TPipeMetas, TPrimitives };
+export { After, ApplyDecorators, Before, Circular, Const, ConstFactory, Controller, Description, HandlerPaths, Id, ImportController, Inherit, Inject, InjectEventLogger, InjectFromScope, InjectMoost, InjectMoostLogger, InjectScopeVars, Injectable, Intercept, Interceptor, InterceptorHandler, Label, LoggerTopic, MOOST_MODULE_IDENTITY_KEY, Moost, MoostDispose, MoostInit, OnError, Optional, Overtake, Param, Params, Pipe, Provide, Replace, Required, Resolve, Response, TInterceptorPriority, TPipePriority, Value, createLogger, defineAfterInterceptor, defineBeforeInterceptor, defineErrorInterceptor, defineInfactScope, defineInterceptor, defineMoostEventHandler, definePipeFn, disposeInstances, getHandlerPaths, getInfactScopeVars, getInfactSingletonInstances, getInstanceOwnMethods, getInstanceOwnProps, getMoostInfact, getMoostMate, getNewMoostInfact, globalKey, isThenable, loggerConsoleTransport, mergeSorted, registerEventScope, resolvePipe, setControllerContext, setInfactLoggingOptions, setInterceptResult, setOvertake, stampModuleIdentity, stampOnce, useControllerContext, useHandlerPaths, useInterceptResult, useOvertake, useScopeId };
+export type { TAny, TAnyFn, TClassConstructor, TContextInjectorHook, TControllerOverview, TControllerRegistration, TControllersGroup, TDisposeError, TDisposeOptions, TDisposeResult, TEmpty, TFunction, TGetHandlerPathsOptions, TInjectableScope, TInterceptorAfterFn, TInterceptorBeforeFn, TInterceptorData, TInterceptorDef, TInterceptorDefFactory, TInterceptorEntry, TInterceptorErrorFn, TLogger, TMoostAdapter, TMoostAdapterOptions, TMoostEventHandlerHookOptions, TMoostEventHandlerOptions, TMoostHandler, TMoostMetadata, TMoostModuleIdentity, TMoostOptions, TMoostParamsMetadata, TObject, TOvertakeFn, TPipeData, TPipeFn, TPipeMetas, TPrimitives };

package/dist/index.mjs

@@ -47,7 +47,7 @@ let stamped = false;
 	if (stamped) return;
 	stamped = true;
 	stampModuleIdentity({
-		version: "0.6.35",
+		version: "0.6.37",
 		path: typeof __filename === "string" ? __filename : import.meta.url
 	});
 }
@@ -224,6 +224,18 @@ let loggingOptions = {
 /** Returns the shared Infact DI container used by Moost for dependency injection. */ function getMoostInfact() {
 	return sharedMoostInfact;
 }
+/**
+* Every SINGLETON instance currently held by an Infact container's **global**
+* registry (per-event `scopes` registries are excluded — those instances are
+* torn down with their event).
+*
+* Infact keeps the registry as a protected symbol-keyed object; this helper
+* centralizes the one cast needed to read it, so consumers
+* (`Moost.dispose()`, the `@moostjs/vite` dev plugin) do not each re-derive it.
+*/ function getInfactSingletonInstances(infact = getMoostInfact()) {
+	const { registry } = infact;
+	return Object.getOwnPropertySymbols(registry).map((k) => registry[k]).filter(Boolean);
+}
 const scopeVarsMap = /* @__PURE__ */ new Map();
 /**
 * Define global scope name to be used with `@InjectFromScope` and `@InjectScopeVars` decorators
@@ -639,6 +651,126 @@ function nextScopeId() {
 	}
 }
 
+//#endregion
+//#region packages/moost/src/dispose.ts
+/**
+* Instances whose dispose hooks already ran. Module-level and weak, so
+* disposal is at-most-once per instance no matter which entry point triggers
+* it — `Moost.dispose()` twice, or a hot-reload eject followed by a shutdown,
+* never re-runs a hook.
+*/ const disposedInstances = /* @__PURE__ */ new WeakSet();
+const DISPOSE_BANNER = `moost`;
+/**
+* `Symbol.asyncDispose` / `Symbol.dispose` are only present on newer runtimes —
+* resolve them once through a guarded read so older ones simply have no
+* well-known fallback hook.
+*/ const asyncDisposeSymbol = typeof Symbol.asyncDispose === "symbol" ? Symbol.asyncDispose : void 0;
+const disposeSymbol = typeof Symbol.dispose === "symbol" ? Symbol.dispose : void 0;
+/** Class name of an instance, read through the prototype (never touches own props). */ function classNameOf(instance) {
+	return Object.getPrototypeOf(instance)?.constructor?.name || "Object";
+}
+/** @internal Message of a thrown value, whatever it is. */ function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/** `Class.method (message)` pairs for every failed hook. */ function formatDisposeErrors(errors) {
+	const list = errors.map((e) => `${classNameOf(e.instance)}.${String(e.method)} (${errorMessage(e.error)})`).join(", ");
+	return `[moost] ${errors.length} dispose hook(s) failed: ${list}`;
+}
+/**
+* True when `sym` resolves to a data property holding a function anywhere on the
+* instance/prototype chain. Descriptor based — accessors are never invoked.
+*/ function hasSymbolMethod(instance, sym) {
+	if (!sym) return false;
+	let obj = instance;
+	while (obj && obj !== Object.prototype) {
+		const desc = Object.getOwnPropertyDescriptor(obj, sym);
+		if (desc) return typeof desc.value === "function";
+		obj = Object.getPrototypeOf(obj);
+	}
+	return false;
+}
+/**
+* Dispose hooks of one instance: every `@MoostDispose`-decorated method or —
+* when the class decorates none — its `Symbol.asyncDispose` / `Symbol.dispose`
+* method (preferring the async one) as a single priority-0 hook. The method
+* scan goes through `getInstanceOwnMethods`, which classifies by descriptor and
+* never evaluates getters.
+*/ function collectHooks(instance) {
+	const mate = getMoostMate();
+	const hooks = [];
+	for (const method of getInstanceOwnMethods(instance)) {
+		const priority = mate.read(instance, method)?.moostDispose?.priority;
+		if (typeof priority === "number") hooks.push({
+			instance,
+			method,
+			priority
+		});
+	}
+	if (hooks.length > 0) return hooks;
+	const sym = hasSymbolMethod(instance, asyncDisposeSymbol) ? asyncDisposeSymbol : hasSymbolMethod(instance, disposeSymbol) ? disposeSymbol : void 0;
+	return sym ? [{
+		instance,
+		method: sym,
+		priority: 0
+	}] : [];
+}
+async function runHook(hook, errors, opts) {
+	const fn = hook.instance[hook.method];
+	try {
+		await fn.call(hook.instance);
+	} catch (error) {
+		errors.push({
+			instance: hook.instance,
+			method: hook.method,
+			error
+		});
+		if (opts?.onError !== "throw") (opts?.logger || getDefaultLogger(DISPOSE_BANNER)).warn(`[moost] dispose hook ${classNameOf(hook.instance)}.${String(hook.method)} failed: ${errorMessage(error)}`);
+	}
+}
+/**
+* Runs the dispose hooks of every given instance, once per instance, ever.
+*
+* A hook is either a `@MoostDispose()`-decorated method or, when the class
+* decorates none, the instance's `[Symbol.asyncDispose]()` / `[Symbol.dispose]()`
+* method. Hooks run **sequentially** in ascending `priority` (ties keep input
+* order) and each one is awaited, so teardown that must happen in order (drain
+* consumers, then close the connection they use) can be expressed with
+* priorities.
+*
+* Failures never stop the run: with `onError: 'warn'` (default) each one is
+* logged and collected; with `onError: 'throw'` every hook still runs and one
+* `AggregateError` is thrown at the end.
+*
+* Instances already disposed (by an earlier call, or by `Moost.dispose()`) are
+* skipped, so passing overlapping sets is safe.
+*/ async function disposeInstances(instances, opts) {
+	const hooks = [];
+	const disposed = [];
+	for (const instance of instances) {
+		if (!instance || disposedInstances.has(instance)) continue;
+		disposedInstances.add(instance);
+		const own = collectHooks(instance);
+		if (own.length > 0) {
+			disposed.push(instance);
+			hooks.push(...own);
+		}
+	}
+	const errors = [];
+	for (const hook of hooks.toSorted((a, b) => a.priority - b.priority)) await runHook(hook, errors, opts);
+	if (opts?.onError === "throw" && errors.length > 0) throw new AggregateError(errors.map((e) => e.error), formatDisposeErrors(errors));
+	return {
+		hooks: hooks.length,
+		errors,
+		disposed
+	};
+}
+/**
+* @internal Renders the aggregate message used when disposal failures are
+* rethrown (`Moost.dispose()` and `disposeInstances(..., { onError: 'throw' })`).
+*/ function describeDisposeErrors(errors) {
+	return formatDisposeErrors(errors);
+}
+
 //#endregion
 //#region packages/moost/src/decorators/circular.decorator.ts
 /**
@@ -766,6 +898,56 @@ function ImportController(prefix, controller, provide) {
 	}, true);
 }
 
+//#endregion
+//#region packages/moost/src/decorators/dispose.decorator.ts
+/**
+* ## MoostDispose
+* ### @Decorator
+* Marks a method to run **once**, when its instance is **disposed** — either by
+* `Moost.dispose()` (graceful shutdown) or by the `@moostjs/vite` dev server
+* when the instance is ejected on hot reload. It is the teardown counterpart of
+* {@link MoostInit}: release what the singleton owns (a queue consumer, a cache
+* client, a database handle, timers, watchers) so a replaced instance does not
+* leak it.
+*
+* Works on SINGLETON controllers **and** on any `@Injectable()` singleton — the
+* hooks are discovered from live instances at dispose time, so a provider that
+* owns a connection is covered without being a controller.
+*
+* The method takes **no arguments** (dispose tears down an existing instance —
+* inject whatever it needs in the constructor). Async methods are awaited.
+* Errors are collected, not fatal: every other hook still runs, `Moost.dispose()`
+* then rejects with an `AggregateError`, and a hot reload only warns.
+*
+* An instance is disposed at most once (tracked per instance), so a second
+* `dispose()` — or an eject followed by a shutdown — never re-runs a hook.
+*
+* When a class defines no `@MoostDispose` method but exposes
+* `[Symbol.asyncDispose]()` / `[Symbol.dispose]()`, that is used instead.
+*
+* Applying `@MoostDispose` to a `FOR_EVENT` **controller** is a configuration
+* error and throws at bind time (per-event instances are torn down with their
+* event — put the hook on the singleton that owns the resource). On a
+* `FOR_EVENT` **injectable** the hook is simply never invoked.
+*
+* @param opts.priority lower runs first across all `@MoostDispose` methods (default 0)
+*
+* @example
+* ```ts
+* │  @Injectable()
+* │  export class CacheClient {
+* │    private readonly client = createCacheClient()
+* │
+* │    @MoostDispose()
+* │    async close() {
+* │      await this.client.quit()
+* │    }
+* │  }
+* ```
+*/ function MoostDispose(opts) {
+	return getMoostMate().decorate("moostDispose", { priority: opts?.priority ?? 0 }, false);
+}
+
 //#endregion
 //#region packages/moost/src/decorators/resolve.decorator.ts
 /**
@@ -1611,6 +1793,7 @@ async function bindControllerMethods(options) {
 			className: classConstructor.name,
 			methodName: method
 		}));
+		if (methodMeta.moostDispose && meta.injectable === "FOR_EVENT") throw new Error(`@MoostDispose is not allowed on a FOR_EVENT controller (${classConstructor.name}.${String(method)}). Dispose hooks run on the SINGLETON instance; FOR_EVENT instances are torn down with their event — put the hook on the singleton that owns the resource.`);
 		if (methodMeta.moostInit) {
 			if (meta.injectable === "FOR_EVENT") throw new Error(`@MoostInit is not allowed on a FOR_EVENT controller (${classConstructor.name}.${String(method)}). Init hooks run once at boot on the SINGLETON instance; FOR_EVENT controllers have no init-time instance.`);
 			const initArgsPipes = (methodMeta.params || []).map((p) => ({
@@ -1768,6 +1951,67 @@ function lostCtorParamsMessage(input, ancestor, count) {
 	return [auditRouteDrop(input), auditLostCtorParams(input)].filter((f) => f !== void 0);
 }
 
+//#endregion
+//#region packages/moost/src/dispose-signals.ts
+/**
+* Global key for the record above. Global (rather than module-scoped) for the
+* same reason the module-identity stamp is: two copies of moost, or the entry
+* re-executing under the `@moostjs/vite` dev server, must share one set of
+* process listeners instead of stacking one per app.
+*/ const DISPOSE_SIGNALS_KEY = Symbol.for("moost:dispose-on-signals");
+/**
+* Removes every registered listener and forgets the record. A no-op for a record
+* that is no longer the live one (a stale unregister fn, or a signal that already
+* dropped it).
+*/ function dropSignalsRecord(record) {
+	const holder = globalThis;
+	if (holder[DISPOSE_SIGNALS_KEY] !== record) return;
+	for (const [signal, listener] of record.listeners) process.off(signal, listener);
+	record.listeners.clear();
+	delete holder[DISPOSE_SIGNALS_KEY];
+}
+/**
+* The one listener body per signal (NestJS `enableShutdownHooks` semantics):
+* unhook every listener first, dispose the newest app, then re-raise `signal`
+* so the process exits with Node's default status for it. Because the listeners
+* are already gone, a second signal while disposal runs gets Node's default
+* handling (exit `128 + n`) — an impatient Ctrl-C is never stuck.
+*/ async function onSignal(signal) {
+	const record = globalThis[DISPOSE_SIGNALS_KEY];
+	if (!record) return;
+	const { app } = record;
+	dropSignalsRecord(record);
+	try {
+		await app.dispose();
+	} catch (error) {
+		app.getLogger().warn(`[moost] dispose on ${signal} failed: ${errorMessage(error)}`);
+	}
+	process.kill(process.pid, signal);
+}
+/**
+* @internal Backs `Moost.disposeOnSignals()` — see that method's JSDoc for the
+* full contract. Registers at most one process listener per signal, ever, and
+* re-targets the existing ones at `app`.
+*/ function registerDisposeOnSignals(app, signals) {
+	var _holder, _DISPOSE_SIGNALS_KEY;
+	const record = (_holder = globalThis)[_DISPOSE_SIGNALS_KEY = DISPOSE_SIGNALS_KEY] ?? (_holder[_DISPOSE_SIGNALS_KEY] = {
+		app,
+		listeners: /* @__PURE__ */ new Map()
+	});
+	record.app = app;
+	for (const signal of signals) {
+		if (record.listeners.has(signal)) continue;
+		const listener = () => {
+			onSignal(signal);
+		};
+		record.listeners.set(signal, listener);
+		process.on(signal, listener);
+	}
+	return () => {
+		dropSignalsRecord(record);
+	};
+}
+
 //#endregion
 //#region packages/moost/src/moost.ts
 function _define_property(obj, key, value) {
@@ -1931,6 +2175,84 @@ function _define_property(obj, key, value) {
 		});
 	}
 	/**
+	* ### dispose
+	* Graceful shutdown: stops the adapters, then runs every `@MoostDispose`
+	* hook of every singleton this app can reach — DI registry singletons
+	* (`@Injectable()` providers included) plus the controller instances bound at
+	* boot. A class with no decorated hook but an `[Symbol.asyncDispose]()` /
+	* `[Symbol.dispose]()` method is disposed through that.
+	*
+	* Order: every adapter's `onDispose` in registration order (stop taking new
+	* work first), then instance hooks by ascending `priority`. Everything is
+	* awaited, failures never stop the run — once all hooks have run, a failed
+	* disposal rejects the returned promise with an `AggregateError` naming each
+	* failing `Class.method`.
+	*
+	* Idempotent: the promise of the first call is returned for every later one,
+	* and an instance already disposed (e.g. ejected by the `@moostjs/vite` dev
+	* server) is skipped.
+	*
+	* DI registries and metadata caches are left intact — use the existing
+	* cleanup helpers when a clean container is what you need.
+	*
+	* ```ts
+	* app.disposeOnSignals() // SIGTERM + SIGINT → dispose() → re-raise
+	* ```
+	*/ dispose() {
+		if (!this.disposePromise) this.disposePromise = this.runDispose();
+		return this.disposePromise;
+	}
+	/**
+	* ### disposeOnSignals
+	* Disposes this app when the process receives one of `signals` (default
+	* `['SIGTERM', 'SIGINT']`), then re-raises the signal with no listener left,
+	* so the process exits with Node's default status for it.
+	*
+	* Registers each process listener **once per process**: calling it again —
+	* e.g. the entry re-executing under the `@moostjs/vite` dev server — re-targets
+	* the existing listeners at the newest app instead of stacking one handler per
+	* old app (which is what a plain `process.once(...)` in the entry does, until
+	* Node warns about a listener leak). Signals are unioned across calls; an
+	* already-registered one is never replaced or removed.
+	*
+	* A second signal while disposal runs gets Node's default handling, since the
+	* listeners are already removed. A failing `dispose()` is logged as a warning
+	* and the signal is re-raised all the same.
+	*
+	* Returns a function that unregisters the listeners (tests, embedded runners).
+	*
+	* ```ts
+	* await app.init()
+	* app.disposeOnSignals()
+	* ```
+	*/ disposeOnSignals(signals = ["SIGTERM", "SIGINT"]) {
+		return registerDisposeOnSignals(this, signals);
+	}
+	/** Adapters' `onDispose` in registration order; errors are collected, not fatal. */ async disposeAdapters() {
+		const errors = [];
+		for (const a of this.adapters) try {
+			await a.onDispose?.(this);
+		} catch (error) {
+			errors.push({
+				instance: a,
+				method: "onDispose",
+				error
+			});
+			this.logger.warn(`[moost] adapter "${a.name}" onDispose failed: ${errorMessage(error)}`);
+		}
+		return errors;
+	}
+	/** The one-shot body behind {@link Moost.dispose} (see its docs for the contract). */ async runDispose() {
+		const errors = await this.disposeAdapters();
+		const result = await disposeInstances([...getInfactSingletonInstances(), ...this.singletonInstances], {
+			logger: this.logger,
+			onError: "warn"
+		});
+		errors.push(...result.errors);
+		this.logger.debug(`[moost] disposed: ${this.adapters.length} adapter(s), ${result.hooks} hook(s), ${errors.length} error(s)`);
+		if (errors.length > 0) throw new AggregateError(errors.map((e) => e.error), describeDisposeErrors(errors));
+	}
+	/**
 	* D1 audit of a DI-instantiated controller class' constructor params.
 	* Findings are collected for `init()` to flush. Returns `true` when the
 	* bind-time SINGLETON instantiation must be skipped: in `'error'` mode a
@@ -1989,6 +2311,7 @@ function _define_property(obj, key, value) {
 			instance = controller;
 			infact.setInstanceRegistries(instance, provide, replace, { pipes });
 		}
+		if (instance) this.singletonInstances.add(instance);
 		const getInstance = instance ? () => instance : async () => await infact.get(controller, { ...infactOpts });
 		const classConstructor = isConstructor$1(controller) ? controller : getConstructor$1(controller);
 		const controllerOverview = await bindControllerMethods({
@@ -2164,7 +2487,7 @@ function _define_property(obj, key, value) {
 		this.logger.info(`${prefix || ""}${c}${eventName} ${"\x1B[0m\x1B[2m\x1B[32m" + c}→ ${classConstructor.name}.${"\x1B[36m" + c}${method}()${coff}`);
 	}
 	constructor(options) {
-		super(), _define_property(this, "options", void 0), _define_property(this, "logger", void 0), _define_property(this, "pipes", void 0), _define_property(this, "interceptors", void 0), _define_property(this, "adapters", void 0), _define_property(this, "controllersOverview", void 0), _define_property(this, "handlerOverviewIndex", void 0), _define_property(this, "initHooks", void 0), _define_property(this, "provide", void 0), _define_property(this, "replace", void 0), _define_property(this, "unregisteredControllers", void 0), _define_property(this, "paramAuditFindings", void 0), _define_property(this, "paramAuditMode", void 0), _define_property(this, "inheritanceAuditMode", void 0), _define_property(this, "initialized", void 0), _define_property(this, "globalInterceptorHandler", void 0), this.options = options, this.pipes = Array.from(sharedPipes), this.interceptors = [], this.adapters = [], this.controllersOverview = [], this.initHooks = [], this.provide = createProvideRegistry$1([Infact, getMoostInfact], [Mate, getMoostMate]), this.replace = {}, this.unregisteredControllers = [], this.paramAuditFindings = [], this.initialized = false;
+		super(), _define_property(this, "options", void 0), _define_property(this, "logger", void 0), _define_property(this, "pipes", void 0), _define_property(this, "interceptors", void 0), _define_property(this, "adapters", void 0), _define_property(this, "controllersOverview", void 0), _define_property(this, "handlerOverviewIndex", void 0), _define_property(this, "initHooks", void 0), _define_property(this, "provide", void 0), _define_property(this, "replace", void 0), _define_property(this, "unregisteredControllers", void 0), _define_property(this, "paramAuditFindings", void 0), _define_property(this, "paramAuditMode", void 0), _define_property(this, "inheritanceAuditMode", void 0), _define_property(this, "initialized", void 0), _define_property(this, "singletonInstances", void 0), _define_property(this, "disposePromise", void 0), _define_property(this, "globalInterceptorHandler", void 0), this.options = options, this.pipes = Array.from(sharedPipes), this.interceptors = [], this.adapters = [], this.controllersOverview = [], this.initHooks = [], this.provide = createProvideRegistry$1([Infact, getMoostInfact], [Mate, getMoostMate]), this.replace = {}, this.unregisteredControllers = [], this.paramAuditFindings = [], this.initialized = false, this.singletonInstances = /* @__PURE__ */ new Set();
 		this.paramAuditMode = resolveParamAuditMode(options?.diagnostics?.paramTypes);
 		this.inheritanceAuditMode = options?.diagnostics?.inheritance || "warn";
 		this.logger = options?.logger || getDefaultLogger(`moost`);
@@ -2242,4 +2565,4 @@ function _define_property(obj, key, value) {
 }
 
 //#endregion
-export { After, ApplyDecorators, Before, Circular, Const, ConstFactory, ContextInjector, Controller, Description, HandlerPaths, Id, ImportController, Inherit, Inject, InjectEventLogger, InjectFromScope, InjectMoost, InjectMoostLogger, InjectScopeVars, Injectable, Intercept, Interceptor, InterceptorHandler, Label, LoggerTopic, MOOST_MODULE_IDENTITY_KEY, Moost, MoostInit, OnError, Optional, Overtake, Param, Params, Pipe, ProstoLogger, Provide, Replace, Required, Resolve, Response, TInterceptorPriority, TPipePriority, Value, cached, clearGlobalWooks, createEventContext, createLogger, createProvideRegistry, createReplaceRegistry, current, defineAfterInterceptor, defineBeforeInterceptor, defineErrorInterceptor, defineInfactScope, defineInterceptor, defineMoostEventHandler, definePipeFn, eventTypeKey, getConstructor, getContextInjector, getGlobalWooks, getHandlerPaths, getInfactScopeVars, getInstanceOwnMethods, getInstanceOwnProps, getMoostInfact, getMoostMate, getNewMoostInfact, globalKey, isConstructor, isThenable, key, loggerConsoleTransport, mergeSorted, registerEventScope, replaceContextInjector, resetContextInjector, resolvePipe, run, setControllerContext, setInfactLoggingOptions, setInterceptResult, setOvertake, stampModuleIdentity, stampOnce, useControllerContext, useHandlerPaths, useInterceptResult, useLogger, useOvertake, useScopeId };
+export { After, ApplyDecorators, Before, Circular, Const, ConstFactory, ContextInjector, Controller, Description, HandlerPaths, Id, ImportController, Inherit, Inject, InjectEventLogger, InjectFromScope, InjectMoost, InjectMoostLogger, InjectScopeVars, Injectable, Intercept, Interceptor, InterceptorHandler, Label, LoggerTopic, MOOST_MODULE_IDENTITY_KEY, Moost, MoostDispose, MoostInit, OnError, Optional, Overtake, Param, Params, Pipe, ProstoLogger, Provide, Replace, Required, Resolve, Response, TInterceptorPriority, TPipePriority, Value, cached, clearGlobalWooks, createEventContext, createLogger, createProvideRegistry, createReplaceRegistry, current, defineAfterInterceptor, defineBeforeInterceptor, defineErrorInterceptor, defineInfactScope, defineInterceptor, defineMoostEventHandler, definePipeFn, disposeInstances, eventTypeKey, getConstructor, getContextInjector, getGlobalWooks, getHandlerPaths, getInfactScopeVars, getInfactSingletonInstances, getInstanceOwnMethods, getInstanceOwnProps, getMoostInfact, getMoostMate, getNewMoostInfact, globalKey, isConstructor, isThenable, key, loggerConsoleTransport, mergeSorted, registerEventScope, replaceContextInjector, resetContextInjector, resolvePipe, run, setControllerContext, setInfactLoggingOptions, setInterceptResult, setOvertake, stampModuleIdentity, stampOnce, useControllerContext, useHandlerPaths, useInterceptResult, useLogger, useOvertake, useScopeId };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moost",
-  "version": "0.6.35",
+  "version": "0.6.37",
   "description": "moost",
   "keywords": [
     "composables",
@@ -41,15 +41,15 @@
     "@prostojs/infact": "^0.5.0",
     "@prostojs/logger": "^0.4.3",
     "@prostojs/mate": "^0.5.0",
-    "@wooksjs/event-core": "^0.7.22",
+    "@wooksjs/event-core": "^0.7.23",
     "hookable": "^5.5.3",
-    "wooks": "^0.7.22"
+    "wooks": "^0.7.23"
   },
   "devDependencies": {
-    "@wooksjs/event-http": "^0.7.22",
-    "@wooksjs/http-body": "^0.7.22",
+    "@wooksjs/event-http": "^0.7.23",
+    "@wooksjs/http-body": "^0.7.23",
     "vitest": "3.2.7",
-    "@moostjs/event-http": "^0.6.35"
+    "@moostjs/event-http": "^0.6.37"
   },
   "scripts": {
     "pub": "pnpm publish --access public",