moost 0.6.45 → 0.6.47

package/dist/index.cjs

@@ -48,7 +48,7 @@ let stamped = false;
 	if (stamped) return;
 	stamped = true;
 	stampModuleIdentity({
-		version: "0.6.45",
+		version: "0.6.47",
 		path: typeof __filename === "string" ? __filename : require("url").pathToFileURL(__filename).href
 	});
 }
@@ -2323,6 +2323,7 @@ function _define_property(obj, key, value) {
 			}
 			if (typeof a.getProvideRegistry === "function") this.setProvideRegistry(a.getProvideRegistry());
 		}
+		this.initHookPhase = "pending";
 		this.unregisteredControllers.unshift({ controller: this });
 		let auditError;
 		try {
@@ -2337,16 +2338,36 @@ function _define_property(obj, key, value) {
 		this.initialized = true;
 	}
 	/**
-	* Runs every `@MoostInit`-decorated controller method exactly once, after all
-	* controllers are bound (complete `getControllersOverview()`) and before the
-	* `adapter.onInit` loop. Hooks run in ascending `priority`, then registration
-	* order. Each runs on its controller's SINGLETON instance inside a synthetic
-	* init context (no interceptors; params resolve via the RESOLVE pipe only).
-	* A throwing hook rejects `init()` (fail-fast).
+	* Runs every init hook exactly once, after all controllers are bound
+	* (complete `getControllersOverview()`) and before the `adapter.onInit`
+	* loop: `@MoostInit` controller methods and functions registered with
+	* {@link addInitHook}. Hooks run in ascending `priority`, then registration
+	* order. Each runs inside a synthetic init context (no interceptors; params
+	* of `@MoostInit` methods resolve via the RESOLVE pipe only). Hooks added
+	* while the pass runs are picked up. A throwing hook rejects `init()`
+	* (fail-fast).
 	*/ async runInitHooks() {
-		if (this.initHooks.length === 0) return;
-		const hooks = this.initHooks.toSorted((a, b) => a.priority - b.priority);
-		for (const hook of hooks) await (0, _wooksjs_event_core.createEventContext)({ logger: this.logger }, async () => {
+		this.initHookPhase = "running";
+		const done = /* @__PURE__ */ new Set();
+		try {
+			for (;;) {
+				let next;
+				for (const hook of this.initHooks) if (!done.has(hook) && (!next || hook.priority < next.priority)) next = hook;
+				if (!next) break;
+				done.add(next);
+				await this.runInitHook(next);
+			}
+		} finally {
+			this.initHookPhase = "done";
+		}
+	}
+	async runInitHook(hook) {
+		await (0, _wooksjs_event_core.createEventContext)({ logger: this.logger }, async () => {
+			if (hook.kind === "fn") {
+				setControllerContext(this, "init", "", { prefix: "" });
+				await hook.fn(this);
+				return;
+			}
 			const instance = await hook.getInstance();
 			setControllerContext(instance, hook.method, "", { prefix: hook.computedPrefix });
 			const args = hook.resolveArgs ? await hook.resolveArgs() : [];
@@ -2354,6 +2375,45 @@ function _define_property(obj, key, value) {
 		});
 	}
 	/**
+	* ### addInitHook
+	* Programmatic counterpart of `@MoostInit`: runs `fn` once during `init()`,
+	* after every controller is bound (complete `getControllersOverview()`) and
+	* before the adapters' `onInit`, in the same pass as `@MoostInit` hooks:
+	* ascending `priority` (default 0), then registration order. Runs inside the
+	* same synthetic init context (controller context = the app; no
+	* interceptors, no request composables). A throwing hook rejects `init()`.
+	*
+	* May be called at any time:
+	* - before the hook pass starts (including from a controller constructor
+	*   during binding) — queued;
+	* - while the pass runs (from another hook) — runs later in the same pass;
+	* - after the pass finished — runs once, immediately (asynchronously, in its
+	*   own init context) and is NOT stored, so it does not run again on
+	*   re-init and per-request callers (`FOR_EVENT` constructors) do not grow
+	*   the hook list. A failure is logged, since there is no `init()` left to
+	*   reject.
+	*
+	* No de-duplication: registering the same function twice runs it twice
+	* (per-request callers should guard non-idempotent work themselves). Hooks
+	* registered before or during a pass re-run on re-init exactly like
+	* `@MoostInit` hooks; to get a hook on every future init, register it
+	* before `init()`.
+	* @since 0.6.46
+	*/ addInitHook(fn, opts) {
+		const hook = {
+			kind: "fn",
+			priority: opts?.priority ?? 0,
+			fn
+		};
+		if (this.initHookPhase === "done") {
+			this.runInitHook(hook).catch((error) => {
+				this.logger.error(`Late init hook failed: ${errorMessage(error)}`);
+			});
+			return;
+		}
+		this.initHooks.push(hook);
+	}
+	/**
 	* ### dispose
 	* Graceful shutdown: stops the adapters, then runs every `@MoostDispose`
 	* hook of every singleton this app can reach — DI registry singletons
@@ -2711,7 +2771,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, "defaultProvide", void 0), _define_property(this, "defaultReplace", 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.defaultProvide = {}, this.defaultReplace = {}, this.unregisteredControllers = [], this.paramAuditFindings = [], this.initialized = false, this.singletonInstances = /* @__PURE__ */ new Set();
+		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, "initHookPhase", void 0), _define_property(this, "provide", void 0), _define_property(this, "replace", void 0), _define_property(this, "defaultProvide", void 0), _define_property(this, "defaultReplace", 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.initHookPhase = "pending", this.provide = (0, _prostojs_infact.createProvideRegistry)([_prostojs_infact.Infact, getMoostInfact], [_prostojs_mate.Mate, getMoostMate]), this.replace = {}, this.defaultProvide = {}, this.defaultReplace = {}, 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`);

package/dist/index.d.ts

@@ -468,17 +468,25 @@ interface TParamAuditFinding {
 type TParamAuditMode = 'error' | 'warn' | 'off';
 
 /**
- * A `@MoostInit`-decorated controller method, collected at bind time and run
- * once by `Moost.init()` after all controllers are bound. Interceptors are not
- * applied; params resolve through the RESOLVE pipe only.
- */
-interface TInitHook {
+ * An init hook collected for `Moost.init()`: either a `@MoostInit`-decorated
+ * controller method (collected at bind time) or a function registered with
+ * `Moost.addInitHook`. Interceptors are not applied; params of method hooks
+ * resolve through the RESOLVE pipe only.
+ */
+type TInitHook = TMethodInitHook | TFnInitHook;
+interface TMethodInitHook {
+    kind?: 'method';
     priority: number;
     method: string;
     computedPrefix: string;
     getInstance: () => Promise<TObject> | TObject;
     resolveArgs?: () => unknown[] | Promise<unknown[]>;
 }
+interface TFnInitHook {
+    kind: 'fn';
+    priority: number;
+    fn: (app: never) => unknown;
+}
 
 /** Mode for the bind-time inheritance audit (see `TMoostOptions['diagnostics']`). */
 type TInheritanceAuditMode = 'warn' | 'off';
@@ -692,6 +700,7 @@ declare class Moost extends Hookable {
     protected controllersOverview: TControllerOverview[];
     protected handlerOverviewIndex?: Map<TFunction, Map<string, THandlerOverview[]>>;
     protected initHooks: TInitHook[];
+    protected initHookPhase: 'pending' | 'running' | 'done';
     protected provide: TProvideRegistry;
     protected replace: TReplaceRegistry;
     /** Lowest-precedence layers, filled by `set*Registry(reg, { override: false })`. */
@@ -744,14 +753,46 @@ declare class Moost extends Hookable {
      */
     init(): Promise<void>;
     /**
-     * Runs every `@MoostInit`-decorated controller method exactly once, after all
-     * controllers are bound (complete `getControllersOverview()`) and before the
-     * `adapter.onInit` loop. Hooks run in ascending `priority`, then registration
-     * order. Each runs on its controller's SINGLETON instance inside a synthetic
-     * init context (no interceptors; params resolve via the RESOLVE pipe only).
-     * A throwing hook rejects `init()` (fail-fast).
+     * Runs every init hook exactly once, after all controllers are bound
+     * (complete `getControllersOverview()`) and before the `adapter.onInit`
+     * loop: `@MoostInit` controller methods and functions registered with
+     * {@link addInitHook}. Hooks run in ascending `priority`, then registration
+     * order. Each runs inside a synthetic init context (no interceptors; params
+     * of `@MoostInit` methods resolve via the RESOLVE pipe only). Hooks added
+     * while the pass runs are picked up. A throwing hook rejects `init()`
+     * (fail-fast).
      */
     protected runInitHooks(): Promise<void>;
+    protected runInitHook(hook: TInitHook): Promise<void>;
+    /**
+     * ### addInitHook
+     * Programmatic counterpart of `@MoostInit`: runs `fn` once during `init()`,
+     * after every controller is bound (complete `getControllersOverview()`) and
+     * before the adapters' `onInit`, in the same pass as `@MoostInit` hooks:
+     * ascending `priority` (default 0), then registration order. Runs inside the
+     * same synthetic init context (controller context = the app; no
+     * interceptors, no request composables). A throwing hook rejects `init()`.
+     *
+     * May be called at any time:
+     * - before the hook pass starts (including from a controller constructor
+     *   during binding) — queued;
+     * - while the pass runs (from another hook) — runs later in the same pass;
+     * - after the pass finished — runs once, immediately (asynchronously, in its
+     *   own init context) and is NOT stored, so it does not run again on
+     *   re-init and per-request callers (`FOR_EVENT` constructors) do not grow
+     *   the hook list. A failure is logged, since there is no `init()` left to
+     *   reject.
+     *
+     * No de-duplication: registering the same function twice runs it twice
+     * (per-request callers should guard non-idempotent work themselves). Hooks
+     * registered before or during a pass re-run on re-init exactly like
+     * `@MoostInit` hooks; to get a hook on every future init, register it
+     * before `init()`.
+     * @since 0.6.46
+     */
+    addInitHook(fn: (app: this) => unknown, opts?: {
+        priority?: number;
+    }): void;
     /**
      * ### dispose
      * Graceful shutdown: stops the adapters, then runs every `@MoostDispose`

package/dist/index.mjs

@@ -47,7 +47,7 @@ let stamped = false;
 	if (stamped) return;
 	stamped = true;
 	stampModuleIdentity({
-		version: "0.6.45",
+		version: "0.6.47",
 		path: typeof __filename === "string" ? __filename : import.meta.url
 	});
 }
@@ -2322,6 +2322,7 @@ function _define_property(obj, key, value) {
 			}
 			if (typeof a.getProvideRegistry === "function") this.setProvideRegistry(a.getProvideRegistry());
 		}
+		this.initHookPhase = "pending";
 		this.unregisteredControllers.unshift({ controller: this });
 		let auditError;
 		try {
@@ -2336,16 +2337,36 @@ function _define_property(obj, key, value) {
 		this.initialized = true;
 	}
 	/**
-	* Runs every `@MoostInit`-decorated controller method exactly once, after all
-	* controllers are bound (complete `getControllersOverview()`) and before the
-	* `adapter.onInit` loop. Hooks run in ascending `priority`, then registration
-	* order. Each runs on its controller's SINGLETON instance inside a synthetic
-	* init context (no interceptors; params resolve via the RESOLVE pipe only).
-	* A throwing hook rejects `init()` (fail-fast).
+	* Runs every init hook exactly once, after all controllers are bound
+	* (complete `getControllersOverview()`) and before the `adapter.onInit`
+	* loop: `@MoostInit` controller methods and functions registered with
+	* {@link addInitHook}. Hooks run in ascending `priority`, then registration
+	* order. Each runs inside a synthetic init context (no interceptors; params
+	* of `@MoostInit` methods resolve via the RESOLVE pipe only). Hooks added
+	* while the pass runs are picked up. A throwing hook rejects `init()`
+	* (fail-fast).
 	*/ async runInitHooks() {
-		if (this.initHooks.length === 0) return;
-		const hooks = this.initHooks.toSorted((a, b) => a.priority - b.priority);
-		for (const hook of hooks) await createEventContext$1({ logger: this.logger }, async () => {
+		this.initHookPhase = "running";
+		const done = /* @__PURE__ */ new Set();
+		try {
+			for (;;) {
+				let next;
+				for (const hook of this.initHooks) if (!done.has(hook) && (!next || hook.priority < next.priority)) next = hook;
+				if (!next) break;
+				done.add(next);
+				await this.runInitHook(next);
+			}
+		} finally {
+			this.initHookPhase = "done";
+		}
+	}
+	async runInitHook(hook) {
+		await createEventContext$1({ logger: this.logger }, async () => {
+			if (hook.kind === "fn") {
+				setControllerContext(this, "init", "", { prefix: "" });
+				await hook.fn(this);
+				return;
+			}
 			const instance = await hook.getInstance();
 			setControllerContext(instance, hook.method, "", { prefix: hook.computedPrefix });
 			const args = hook.resolveArgs ? await hook.resolveArgs() : [];
@@ -2353,6 +2374,45 @@ function _define_property(obj, key, value) {
 		});
 	}
 	/**
+	* ### addInitHook
+	* Programmatic counterpart of `@MoostInit`: runs `fn` once during `init()`,
+	* after every controller is bound (complete `getControllersOverview()`) and
+	* before the adapters' `onInit`, in the same pass as `@MoostInit` hooks:
+	* ascending `priority` (default 0), then registration order. Runs inside the
+	* same synthetic init context (controller context = the app; no
+	* interceptors, no request composables). A throwing hook rejects `init()`.
+	*
+	* May be called at any time:
+	* - before the hook pass starts (including from a controller constructor
+	*   during binding) — queued;
+	* - while the pass runs (from another hook) — runs later in the same pass;
+	* - after the pass finished — runs once, immediately (asynchronously, in its
+	*   own init context) and is NOT stored, so it does not run again on
+	*   re-init and per-request callers (`FOR_EVENT` constructors) do not grow
+	*   the hook list. A failure is logged, since there is no `init()` left to
+	*   reject.
+	*
+	* No de-duplication: registering the same function twice runs it twice
+	* (per-request callers should guard non-idempotent work themselves). Hooks
+	* registered before or during a pass re-run on re-init exactly like
+	* `@MoostInit` hooks; to get a hook on every future init, register it
+	* before `init()`.
+	* @since 0.6.46
+	*/ addInitHook(fn, opts) {
+		const hook = {
+			kind: "fn",
+			priority: opts?.priority ?? 0,
+			fn
+		};
+		if (this.initHookPhase === "done") {
+			this.runInitHook(hook).catch((error) => {
+				this.logger.error(`Late init hook failed: ${errorMessage(error)}`);
+			});
+			return;
+		}
+		this.initHooks.push(hook);
+	}
+	/**
 	* ### dispose
 	* Graceful shutdown: stops the adapters, then runs every `@MoostDispose`
 	* hook of every singleton this app can reach — DI registry singletons
@@ -2710,7 +2770,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, "defaultProvide", void 0), _define_property(this, "defaultReplace", 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.defaultProvide = {}, this.defaultReplace = {}, this.unregisteredControllers = [], this.paramAuditFindings = [], this.initialized = false, this.singletonInstances = /* @__PURE__ */ new Set();
+		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, "initHookPhase", void 0), _define_property(this, "provide", void 0), _define_property(this, "replace", void 0), _define_property(this, "defaultProvide", void 0), _define_property(this, "defaultReplace", 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.initHookPhase = "pending", this.provide = createProvideRegistry$1([Infact, getMoostInfact], [Mate, getMoostMate]), this.replace = {}, this.defaultProvide = {}, this.defaultReplace = {}, 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`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moost",
-  "version": "0.6.45",
+  "version": "0.6.47",
   "description": "moost",
   "keywords": [
     "composables",
@@ -49,7 +49,7 @@
     "@wooksjs/event-http": "^0.7.26",
     "@wooksjs/http-body": "^0.7.26",
     "vitest": "3.2.7",
-    "@moostjs/event-http": "^0.6.45"
+    "@moostjs/event-http": "^0.6.47"
   },
   "scripts": {
     "pub": "pnpm publish --access public",