@znight/core 0.6.2 → 0.6.4

package/README.md

@@ -153,7 +153,11 @@ token; keys may be tokens or classes. Override values that look like a provider
 (start listening), then providers' and plugins' `onReady`. Signal handlers are installed when the start
 begins. If a step fails, what was started is stopped, everything is disposed and the error is rethrown.
 
-**`app.stop()`** is idempotent and waits for an in-progress start. It runs three phases:
+**`app.stop()`** is idempotent and waits for an in-progress start, at most `hookTimeoutMs` (a start
+hook that never settles cannot block the shutdown: past that budget, a `Waiting for start() timed out`
+failure is recorded, the remaining start hooks are skipped and what completed its `onStart` is
+stopped; a plugin whose `onStart` is still in flight is stopped and disposed when that hook settles,
+not before). It runs three phases:
 
 1. plugins' `onStop`, in reverse order (stop ingress, drain in-flight work);
 2. for each provider in reverse resolution order: `onStop` (if it was started), then disposal;
@@ -271,7 +275,8 @@ active scope (`get`, `set`, `has`). Plugins (HTTP, messaging) open the scopes fo
 `container.openScope(values?)` opens the same scope without a callback, for hot paths that stay
 synchronous as long as their work is (the HTTP pipeline): `run(fn, ...args)` calls `fn` in the scope
 and returns its result (its continuations stay in the scope), `close()` disposes the instances created
-in it. `close()` returns `undefined` when there is nothing to dispose, otherwise a promise that
+in it. `close()` returns `undefined` when there is nothing to dispose (no instance created in the scope
+has a dispose method, `[Symbol.asyncDispose]` or `[Symbol.dispose]`), otherwise a promise that
 rejects with `ZNIGHT021` when a disposal fails; it must be called once the work is over.
 
 ```ts

package/dist/index.d.mts

@@ -1167,11 +1167,12 @@ export declare class Application {
    */
   start(): Promise<void>;
   /**
-   * Stops the application (idempotent; waits for an in-progress `start()`):
-   * plugins' `onStop` (reverse) → providers' `onStop` + disposal (reverse resolution order) →
-   * plugins' `onDispose` (reverse). Every step is attempted, each within `hookTimeoutMs` and all
-   * within `timeoutMs`; failures are collected into a ZnightAggregateError (ZNIGHT021). Signal
-   * handlers are removed.
+   * Stops the application (idempotent; waits for an in-progress `start()`, as a step bounded like
+   * the others: past it, the remaining start hooks are skipped and what completed its `onStart` is
+   * stopped): plugins' `onStop` (reverse) → providers' `onStop` + disposal (reverse resolution
+   * order) → plugins' `onDispose` (reverse). Every step is attempted, each within `hookTimeoutMs`
+   * and all within `timeoutMs`; failures are collected into a ZnightAggregateError (ZNIGHT021).
+   * Signal handlers are removed.
    *
    * Called from a start hook (`onStart`/`onReady` of a provider or plugin, or work it awaits), it
    * does not wait for the start, which waits for that hook: the shutdown runs right away, stopping

package/dist/index.mjs

@@ -938,6 +938,11 @@ var Container = class Container {
 	#storage = new AsyncLocalStorage();
 	/** Instantiated singletons, in creation order. */
 	#created = [];
+	/**
+	* Request-scoped and transient slots whose factory is running. Creation is synchronous, so a slot
+	* found here again was requested by its own construction (a `Lazy<T>.get()` in a constructor).
+	*/
+	#constructing = /* @__PURE__ */ new Set();
 	#order = [];
 	#names;
 	#status = "open";
@@ -1261,21 +1266,29 @@ var Container = class Container {
 	/** Instantiates a request-scoped or transient provider (synchronous factories only). */
 	#create(slot) {
 		const definition = slot.definition;
+		const constructing = this.#constructing;
+		if (constructing.has(slot)) throw reentrantCreationError(slot);
+		constructing.add(slot);
 		let deps;
-		try {
-			deps = this.#resolveDeps(slot);
-		} catch (error) {
-			throw error instanceof InstantiationError ? error.withParents([slot.token]) : error;
-		}
 		let instance;
 		try {
-			instance = definition.factory(deps);
-		} catch (error) {
-			throw new InstantiationError(slot.token, [slot.token], error, definition.source);
+			try {
+				deps = this.#resolveDeps(slot);
+			} catch (error) {
+				throw error instanceof InstantiationError ? error.withParents([slot.token]) : error;
+			}
+			try {
+				instance = definition.factory(deps);
+			} catch (error) {
+				throw new InstantiationError(slot.token, [slot.token], error, definition.source);
+			}
+		} finally {
+			constructing.delete(slot);
 		}
 		if (definition.interceptors !== void 0) try {
 			applyInterceptors(instance, definition.interceptors, deps, slot.displayName);
 		} catch (error) {
+			disposeQuietly(instance, definition.dispose);
 			throw new InstantiationError(slot.token, [slot.token], error, definition.source);
 		}
 		return instance;
@@ -1290,10 +1303,11 @@ var Container = class Container {
 		this.#assertResolvable(slot);
 		const instance = this.#create(slot);
 		values.set(slot.token, instance);
-		scope.created.push({
+		const dispose = slot.definition?.dispose;
+		if (isDisposable(instance, dispose)) scope.created.push({
 			token: slot.token,
 			instance,
-			dispose: slot.definition?.dispose
+			dispose
 		});
 		return instance;
 	}
@@ -1942,6 +1956,13 @@ var Application = class Application {
 	#startAborted = false;
 	/** Releases a `stop()` waiting for the start, when a start hook asks to stop in turn. */
 	#releaseStopWait;
+	/** Owner of the `onStart` hook in progress. */
+	#starting;
+	/**
+	* Owner of the `onStart` hook still in flight when the wait of `stop()` timed out: the shutdown
+	* skips its `onDispose`, and it is stopped and disposed when that hook settles.
+	*/
+	#lateStart;
 	constructor(options) {
 		const plugins = [...options.plugins ?? []];
 		const byName = /* @__PURE__ */ new Map();
@@ -2075,11 +2096,11 @@ var Application = class Application {
 	async #runStartHooks() {
 		const providers = this.container.instances();
 		for (const provider of providers) {
-			if (!await this.#startHook(() => this.#callProvider(provider, "onStart"))) return false;
+			if (!await this.#startHook(() => this.#callProvider(provider, "onStart"), { provider })) return false;
 			this.#startedProviders.add(provider.token);
 		}
 		for (const plugin of this.#plugins) {
-			if (!await this.#startHook(() => this.#callPlugin(plugin, "onStart"))) return false;
+			if (!await this.#startHook(() => this.#callPlugin(plugin, "onStart"), { plugin })) return false;
 			this.#startedPlugins.push(plugin);
 		}
 		for (const provider of providers) if (!await this.#startHook(() => this.#callProvider(provider, "onReady"))) return false;
@@ -2089,17 +2110,41 @@ var Application = class Application {
 	/**
 	* Runs one start hook in an async context carrying a fresh marker, so that a `stop()` called from
 	* it (or from work it awaits) is recognised. Returns `false` when the hook stopped the application.
+	* `owner` is given for `onStart` hooks: one that settles after `stop()` stopped waiting for it is
+	* stopped and disposed then (see `#stopLateStart`).
 	*/
-	async #startHook(hook) {
+	async #startHook(hook, owner) {
 		const marker = {};
 		this.#startHookMarker = marker;
+		this.#starting = owner;
+		let started = false;
 		try {
 			await startHookContext.run(marker, hook);
+			started = true;
 		} finally {
 			this.#startHookMarker = void 0;
+			this.#starting = void 0;
+			if (owner !== void 0 && this.#lateStart === owner) await this.#stopLateStart(owner, started);
 		}
 		return !this.#startAborted;
 	}
+	/**
+	* Stops what an `onStart` hook settling after the shutdown started (best effort, failures logged):
+	* a plugin gets `onStop` (when its `onStart` succeeded) then the `onDispose` the shutdown skipped;
+	* a provider, already disposed by the shutdown, gets `onStop` when its `onStart` succeeded.
+	*/
+	async #stopLateStart(owner, started) {
+		const { plugin, provider } = owner;
+		const label = plugin === void 0 ? `${provider?.displayName}.onStart()` : `Plugin "${plugin.name}" onStart()`;
+		this.#logger.warn(`${label} settled after the shutdown stopped waiting for it: stopping it now`);
+		const errors = [];
+		const step = this.#stepRunner(errors);
+		if (plugin !== void 0) {
+			if (started && typeof plugin.onStop === "function") await step(`Plugin "${plugin.name}" onStop()`, () => plugin.onStop?.(this.#context));
+			if (typeof plugin.onDispose === "function") await step(`Plugin "${plugin.name}" onDispose()`, () => plugin.onDispose?.(this.#context));
+		} else if (provider !== void 0 && started && hasLifecycleHook(provider.instance, "onStop")) await step(`${provider.displayName}.onStop()`, () => callLifecycleHook(provider.instance, "onStop"));
+		for (const error of errors) this.#logger.error("Failed to stop a late start", { err: error });
+	}
 	/** Whether the caller runs in the async context of the start hook in progress. */
 	#calledFromStartHook() {
 		const marker = this.#startHookMarker;
@@ -2112,11 +2157,12 @@ var Application = class Application {
 		} catch {}
 	}
 	/**
-	* Stops the application (idempotent; waits for an in-progress `start()`):
-	* plugins' `onStop` (reverse) → providers' `onStop` + disposal (reverse resolution order) →
-	* plugins' `onDispose` (reverse). Every step is attempted, each within `hookTimeoutMs` and all
-	* within `timeoutMs`; failures are collected into a ZnightAggregateError (ZNIGHT021). Signal
-	* handlers are removed.
+	* Stops the application (idempotent; waits for an in-progress `start()`, as a step bounded like
+	* the others: past it, the remaining start hooks are skipped and what completed its `onStart` is
+	* stopped): plugins' `onStop` (reverse) → providers' `onStop` + disposal (reverse resolution
+	* order) → plugins' `onDispose` (reverse). Every step is attempted, each within `hookTimeoutMs`
+	* and all within `timeoutMs`; failures are collected into a ZnightAggregateError (ZNIGHT021).
+	* Signal handlers are removed.
 	*
 	* Called from a start hook (`onStart`/`onReady` of a provider or plugin, or work it awaits), it
 	* does not wait for the start, which waits for that hook: the shutdown runs right away, stopping
@@ -2131,13 +2177,22 @@ var Application = class Application {
 		return this.#stopPromise;
 	}
 	async #runStop() {
-		if (this.#state === "starting" && !this.#startAborted) await this.#waitForStart();
+		const errors = [];
+		const step = this.#stepRunner(errors);
+		if (this.#state === "starting" && !this.#startAborted) {
+			await step("Waiting for start()", () => this.#waitForStart());
+			if (this.#state === "starting") {
+				this.#startAborted = true;
+				this.#releaseStopWait = void 0;
+				this.#lateStart = this.#starting;
+			}
+		}
 		if (this.#state === "failed" || this.#state === "stopped") {
 			this.#removeSignals();
 			return;
 		}
 		this.#state = "stopping";
-		const errors = await this.#shutdown();
+		await this.#shutdown(errors, step);
 		this.#removeSignals();
 		this.#state = "stopped";
 		if (errors.length > 0) throw new ZnightAggregateError(ErrorCode.LifecycleFailed, `The application stopped with ${errors.length} error(s)`, errors);
@@ -2158,11 +2213,9 @@ var Application = class Application {
 	}
 	/**
 	* The three shutdown phases (also used to roll back a failed create/start: only what was started
-	* is stopped). Never throws: returns the errors of the failed steps.
+	* is stopped). Never throws: returns the errors of the failed steps (appended to `errors`).
 	*/
-	async #shutdown() {
-		const errors = [];
-		const step = this.#stepRunner(errors);
+	async #shutdown(errors = [], step = this.#stepRunner(errors)) {
 		for (const plugin of [...this.#startedPlugins].reverse()) if (typeof plugin.onStop === "function") await step(`Plugin "${plugin.name}" onStop()`, () => plugin.onStop?.(this.#context));
 		for (const provider of this.container.instances().reverse()) {
 			if (this.#startedProviders.has(provider.token) && hasLifecycleHook(provider.instance, "onStop")) await step(`${provider.displayName}.onStop()`, () => callLifecycleHook(provider.instance, "onStop"));
@@ -2174,7 +2227,7 @@ var Application = class Application {
 		} catch (error) {
 			errors.push(...flatten(error));
 		}
-		for (const plugin of [...this.#registered].reverse()) if (typeof plugin.onDispose === "function") await step(`Plugin "${plugin.name}" onDispose()`, () => plugin.onDispose?.(this.#context));
+		for (const plugin of [...this.#registered].reverse()) if (typeof plugin.onDispose === "function" && plugin !== this.#lateStart?.plugin) await step(`Plugin "${plugin.name}" onDispose()`, () => plugin.onDispose?.(this.#context));
 		this.#startedPlugins.length = 0;
 		this.#startedProviders.clear();
 		return errors;