@znight/core 0.6.1 → 0.6.3

package/README.md

@@ -153,7 +153,10 @@ 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). 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 +274,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
@@ -368,13 +372,17 @@ return what is known (`[]`).
 declared in core, so producers and observers (`@znight/observability`, your plugins) share them
 without depending on each other:
 
-| Hook                | Event                   | Produced by                                                                  |
-| ------------------- | ----------------------- | ---------------------------------------------------------------------------- |
-| `http:request`      | `HttpRequestEvent`      | `@znight/http`, one request                                                  |
-| `messaging:message` | `MessageDeliveryEvent`  | `@znight/messaging`, one delivery                                            |
-| `messaging:publish` | `MessagePublishEvent`   | `@znight/messaging`, one `MessageBroker` publication                         |
-| `schedule:run`      | `ScheduledRunEvent`     | `@znight/schedule`, one occurrence of a job (executed or not, see `outcome`) |
-| `graphql:operation` | `GraphQLOperationEvent` | `@znight/graphql` (RFC 0005), one GraphQL operation                          |
+| Hook                   | Event                      | Produced by                                                                  |
+| ---------------------- | -------------------------- | ---------------------------------------------------------------------------- |
+| `http:request`         | `HttpRequestEvent`         | `@znight/http`, one request                                                  |
+| `messaging:message`    | `MessageDeliveryEvent`     | `@znight/messaging`, one delivery                                            |
+| `messaging:publish`    | `MessagePublishEvent`      | `@znight/messaging`, one `MessageBroker` publication                         |
+| `schedule:run`         | `ScheduledRunEvent`        | `@znight/schedule`, one occurrence of a job (executed or not, see `outcome`) |
+| `graphql:operation`    | `GraphQLOperationEvent`    | `@znight/graphql` (RFC 0005), one GraphQL operation                          |
+| `websocket:message`    | `WebSocketMessageEvent`    | `@znight/websocket` (RFC 0003), one inbound message (`$ping` excluded)       |
+| `websocket:connection` | `WebSocketConnectionEvent` | `@znight/websocket`, a connection opened or closed (emitted only)            |
+| `events:publish`       | `EventPublishEvent`        | `@znight/events` (RFC 0011), one publication with at least one listener      |
+| `events:listener`      | `EventListenerEvent`       | `@znight/events`, one listener invocation, inline or detached                |
 
 `ScheduledRunEvent` carries `job`, `kind` (`cron` / `interval` / `timeout`), `host`, `method`,
 `runId`, `trigger` (`schedule` / `start` / `manual` / `queued`), `scheduledAt` (epoch ms),
@@ -461,6 +469,7 @@ the [architecture specification](../../docs/internals/architecture.md#48-validat
 The catalogue is shared by the compiler and every first-party package. `ZNIGHT001`–`ZNIGHT029`
 belong to the core, the compiler and the features of the first release (`ZNIGHT023`, a missing
 route decision, is reported by `@znight/http`). From `ZNIGHT030`, each package owns a block of ten:
-`ZNIGHT030`–`039` `@znight/openapi`, `ZNIGHT040`–`049` `@znight/schedule`, `ZNIGHT060`–`069`
-`@znight/graphql` (RFC 0005; `050`–`059` are reserved for `@znight/websocket`, RFC 0003).
+`ZNIGHT030`–`039` `@znight/openapi`, `ZNIGHT040`–`049` `@znight/schedule`, `ZNIGHT050`–`059`
+`@znight/websocket` (RFC 0003), `ZNIGHT060`–`069` `@znight/graphql` (RFC 0005, RFC 0007),
+`ZNIGHT070`–`079` `@znight/events` (RFC 0011).
 Inside a block, codes are allocated in order; third-party packages get no `ZNIGHT` code.

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;
 	}
@@ -2112,11 +2126,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 +2146,21 @@ 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;
+			}
+		}
 		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 +2181,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"));