@znight/core 0.6.2 → 0.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@znight/core",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Znight core runtime: compile-time DI container, lifecycle, plugins and marker decorators",
   "license": "MIT",
   "author": "Ugho STEPHAN",

package/src/application.ts

@@ -116,6 +116,13 @@ export class Application {
   #startAborted = false
   /** Releases a `stop()` waiting for the start, when a start hook asks to stop in turn. */
   #releaseStopWait: (() => void) | undefined
+  /** Owner of the `onStart` hook in progress. */
+  #starting: StartOwner | undefined
+  /**
+   * 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: StartOwner | undefined
 
   private constructor(options: ApplicationOptions) {
     const plugins = [...(options.plugins ?? [])]
@@ -292,11 +299,11 @@ export class Application {
   async #runStartHooks(): Promise<boolean> {
     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) {
@@ -311,18 +318,51 @@ export 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: () => Promise<void>): Promise<boolean> {
+  async #startHook(hook: () => Promise<void>, owner?: StartOwner): Promise<boolean> {
     const marker = {}
     this.#startHookMarker = marker
+    this.#starting = owner
+    let started = false
     try {
       await startHookContext.run(marker, hook)
+      started = true
     } finally {
       this.#startHookMarker = undefined
+      this.#starting = undefined
+      if (owner !== undefined && 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: StartOwner, started: boolean): Promise<void> {
+    const { plugin, provider } = owner
+    const label = plugin === undefined ? `${provider?.displayName}.onStart()` : `Plugin "${plugin.name}" onStart()`
+    this.#logger.warn(`${label} settled after the shutdown stopped waiting for it: stopping it now`)
+    const errors: unknown[] = []
+    const step = this.#stepRunner(errors)
+    if (plugin !== undefined) {
+      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 !== undefined && 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(): boolean {
     const marker = this.#startHookMarker
@@ -339,11 +379,12 @@ export class Application {
   }
 
   /**
-   * 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
@@ -359,13 +400,25 @@ export class Application {
   }
 
   async #runStop(): Promise<void> {
-    if (this.#state === 'starting' && !this.#startAborted) await this.#waitForStart()
+    const errors: unknown[] = []
+    const step = this.#stepRunner(errors)
+    if (this.#state === 'starting' && !this.#startAborted) {
+      // a start hook may never settle: waiting for the start is a step of the shutdown
+      await step('Waiting for start()', () => this.#waitForStart())
+      if (this.#state === 'starting') {
+        // timed out: the remaining start hooks are skipped, what completed its onStart is stopped,
+        // and the owner of the onStart still in flight is stopped and disposed once it settles
+        this.#startAborted = true
+        this.#releaseStopWait = undefined
+        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) {
@@ -395,11 +448,9 @@ export 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(): Promise<unknown[]> {
-    const errors: unknown[] = []
-    const step = this.#stepRunner(errors)
+  async #shutdown(errors: unknown[] = [], step = this.#stepRunner(errors)): Promise<unknown[]> {
     for (const plugin of [...this.#startedPlugins].reverse()) {
       if (typeof plugin.onStop === 'function') {
         await step(`Plugin "${plugin.name}" onStop()`, () => plugin.onStop?.(this.#context))
@@ -421,7 +472,8 @@ export class Application {
       errors.push(...flatten(error))
     }
     for (const plugin of [...this.#registered].reverse()) {
-      if (typeof plugin.onDispose === 'function') {
+      // a plugin whose onStart is still in flight is disposed when it settles (#stopLateStart)
+      if (typeof plugin.onDispose === 'function' && plugin !== this.#lateStart?.plugin) {
         await step(`Plugin "${plugin.name}" onDispose()`, () => plugin.onDispose?.(this.#context))
       }
     }
@@ -500,6 +552,12 @@ export class Application {
   }
 }
 
+/** The plugin or provider an `onStart` hook belongs to. */
+interface StartOwner {
+  readonly plugin?: Plugin
+  readonly provider?: ManagedInstance
+}
+
 function entriesOf(values: ProviderValues): Iterable<readonly [ProviderKey, unknown]> {
   if (typeof (values as Partial<Iterable<unknown>>)[Symbol.iterator] === 'function') {
     return values as Iterable<readonly [ProviderKey, unknown]>

package/src/container.ts

@@ -31,7 +31,7 @@ import {
   isMissing,
   missingProvidersError,
 } from './graph.ts'
-import { disposeInstance } from './lifecycle.ts'
+import { disposeInstance, isDisposable } from './lifecycle.ts'
 import {
   type ExternalDefinition,
   type Lazy,
@@ -160,6 +160,11 @@ export class Container {
   readonly #storage = new AsyncLocalStorage<RequestScope>()
   /** Instantiated singletons, in creation order. */
   readonly #created: Slot[] = []
+  /**
+   * 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).
+   */
+  readonly #constructing = new Set<Slot>()
   #order: readonly Slot[] = []
   #names: Map<string, Slot[]> | undefined
   #status: Status = 'open'
@@ -574,22 +579,31 @@ export class Container {
   /** Instantiates a request-scoped or transient provider (synchronous factories only). */
   #create(slot: Slot): unknown {
     const definition = slot.definition as ProviderDefinition
+    const constructing = this.#constructing
+    if (constructing.has(slot)) throw reentrantCreationError(slot)
+    constructing.add(slot)
     let deps: unknown[]
-    try {
-      deps = this.#resolveDeps(slot)
-    } catch (error) {
-      throw error instanceof InstantiationError ? error.withParents([slot.token]) : error
-    }
     let instance: unknown
     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 !== undefined) {
       try {
         applyInterceptors(instance as object, definition.interceptors, deps, slot.displayName)
       } catch (error) {
+        // the instance is never handed out nor tracked by a scope: release it now
+        disposeQuietly(instance, definition.dispose)
         throw new InstantiationError(slot.token, [slot.token], error, definition.source)
       }
     }
@@ -606,7 +620,9 @@ export class Container {
     this.#assertResolvable(slot)
     const instance = this.#create(slot)
     values.set(slot.token, instance)
-    scope.created.push({ token: slot.token, instance, dispose: slot.definition?.dispose })
+    // only what has something to dispose is tracked: a scope without any closes synchronously
+    const dispose = slot.definition?.dispose
+    if (isDisposable(instance, dispose)) scope.created.push({ token: slot.token, instance, dispose })
     return instance
   }
 

package/src/scope.ts

@@ -17,7 +17,10 @@ export interface ScopeContext {
   readonly closed: boolean
 }
 
-/** A request-scoped instance created by the container, disposed when its scope closes. */
+/**
+ * A request-scoped instance created by the container that has something to dispose (a dispose
+ * method or `[Symbol.asyncDispose]`/`[Symbol.dispose]`), disposed when its scope closes.
+ */
 export interface ScopedInstance {
   readonly token: Token
   readonly instance: unknown