@znight/core 0.1.1 → 0.1.3

package/package.json

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

package/src/container.ts

@@ -93,6 +93,30 @@ export interface ManagedInstance {
 /** Seed values of a request scope: token-keyed pairs (aliases and known classes are accepted). */
 export type ScopeValues = Iterable<readonly [ProviderKey, unknown]>
 
+/**
+ * A request scope opened with {@link Container.openScope}: its owner runs code in it with
+ * {@link OpenedScope.run} and ends it with {@link OpenedScope.close}. The callback-free form of
+ * {@link Container.runInScope}, for hot paths that stay synchronous as long as their work is (the
+ * HTTP pipeline): no promise is created unless something is asynchronous.
+ */
+export interface OpenedScope {
+  /** The values of the scope (what `currentScope()` returns in {@link run}). */
+  readonly context: ScopeContext
+  /**
+   * Calls `fn(...args)` in the scope and returns its result. The code it runs and the asynchronous
+   * continuations it creates (awaits, promise callbacks, timers) see the scope, like the callback
+   * of `runInScope`. May be called several times until the scope is closed.
+   */
+  run<A extends readonly unknown[], R>(fn: (...args: A) => R, ...args: A): R
+  /**
+   * Closes the scope (a later resolution of a request-scoped provider in it throws ZNIGHT013) and
+   * disposes the instances created in it, in reverse creation order. Returns `undefined` when no
+   * instance was created (nothing to wait for), otherwise a promise rejecting with ZNIGHT021 when a
+   * disposal fails. Idempotent: later calls return the first result.
+   */
+  close(): Promise<void> | undefined
+}
+
 type Status = 'open' | 'initializing' | 'ready' | 'failed' | 'disposed'
 
 interface InitRun {
@@ -706,11 +730,27 @@ export class Container {
     return result
   }
 
+  /**
+   * Opens a request scope seeded with `values`, like {@link runInScope}, but without running
+   * anything: the caller runs code in it (`run`) and closes it (`close`) when the work it started
+   * is over. Request-scoped providers resolved in it are disposed by `close`, which must be called.
+   */
+  openScope(values?: ScopeValues): OpenedScope {
+    let seeds: unknown[] | undefined
+    if (values !== undefined) {
+      seeds = []
+      for (const [key, value] of values) seeds.push(this.#canonical(key), value)
+    }
+    return new ScopeHandle(this.#storage, new RequestScope(this.#canonical, seeds), this.#closeScopeFn)
+  }
+
   /** The active request scope, if any. */
   currentScope(): ScopeContext | undefined {
     return this.#storage.getStore()
   }
 
+  readonly #closeScopeFn = (scope: RequestScope): Promise<unknown[]> => this.#closeScope(scope)
+
   async #closeScope(scope: RequestScope): Promise<unknown[]> {
     scope.closed = true
     const errors: unknown[] = []
@@ -1011,3 +1051,50 @@ function disposeQuietly(instance: unknown, method: string | undefined): void {
     // best effort
   }
 }
+
+/** Implementation of {@link OpenedScope}. */
+class ScopeHandle implements OpenedScope {
+  readonly #storage: AsyncLocalStorage<RequestScope>
+  readonly #scope: RequestScope
+  readonly #dispose: (scope: RequestScope) => Promise<unknown[]>
+  #closed = false
+  #closing: Promise<void> | undefined
+
+  constructor(
+    storage: AsyncLocalStorage<RequestScope>,
+    scope: RequestScope,
+    dispose: (scope: RequestScope) => Promise<unknown[]>,
+  ) {
+    this.#storage = storage
+    this.#scope = scope
+    this.#dispose = dispose
+  }
+
+  get context(): ScopeContext {
+    return this.#scope
+  }
+
+  run<A extends readonly unknown[], R>(fn: (...args: A) => R, ...args: A): R {
+    return this.#storage.run(this.#scope, fn, ...args)
+  }
+
+  close(): Promise<void> | undefined {
+    if (this.#closed) return this.#closing
+    this.#closed = true
+    const scope = this.#scope
+    if (scope.created.length === 0) {
+      scope.closed = true
+      return undefined
+    }
+    this.#closing = this.#dispose(scope).then(errors => {
+      if (errors.length > 0) {
+        throw new ZnightAggregateError(
+          ErrorCode.LifecycleFailed,
+          `Failed to dispose ${errors.length} request-scoped instance(s)`,
+          errors,
+        )
+      }
+    })
+    return this.#closing
+  }
+}

package/src/index.ts

@@ -17,7 +17,7 @@ export {
   type ProviderValues,
   type ShutdownOptions,
 } from './application.ts'
-export { Container, type InitOptions, type ManagedInstance, type ScopeValues } from './container.ts'
+export { Container, type InitOptions, type ManagedInstance, type OpenedScope, type ScopeValues } from './container.ts'
 export {
   type ClassMarker,
   Factory,

package/src/scope.ts

@@ -26,13 +26,32 @@ export interface ScopedInstance {
 
 /** Implementation of {@link ScopeContext} used by the container (internal). */
 export class RequestScope implements ScopeContext {
-  readonly values: Map<Token, unknown> = new Map()
   readonly created: ScopedInstance[] = []
   closed = false
   readonly #canonical: (key: ProviderKey) => Token
+  #values: Map<Token, unknown> | undefined
+  /** Seed values not yet in {@link values}: canonical tokens and values, alternately. */
+  #seeds: readonly unknown[] | undefined
 
-  constructor(canonical: (key: ProviderKey) => Token) {
+  /** `seeds`: canonical tokens and their values, alternately (copied into {@link values} on first use). */
+  constructor(canonical: (key: ProviderKey) => Token, seeds?: readonly unknown[]) {
     this.#canonical = canonical
+    this.#seeds = seeds
+  }
+
+  /** The values of the scope by canonical token: the seeds, then what was set or created in it. */
+  get values(): Map<Token, unknown> {
+    let values = this.#values
+    if (values === undefined) {
+      values = new Map()
+      const seeds = this.#seeds
+      if (seeds !== undefined) {
+        for (let index = 0; index < seeds.length; index += 2) values.set(seeds[index] as Token, seeds[index + 1])
+        this.#seeds = undefined
+      }
+      this.#values = values
+    }
+    return values
   }
 
   get<T = unknown>(key: ProviderKey<T>): T | undefined {