@znight/core 0.1.1 → 0.1.3

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Ugho STEPHAN
+Copyright (c) 2026 Ugho STEPHAN
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -238,6 +238,18 @@ Scopes are isolated with `AsyncLocalStorage` (concurrent requests never share in
 request-scoped provider outside of a scope throws `ZNIGHT013`. `container.currentScope()` exposes the
 active scope (`get`, `set`, `has`). Plugins (HTTP, messaging) open the scopes for you.
 
+`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
+rejects with `ZNIGHT021` when a disposal fails; it must be called once the work is over.
+
+```ts
+const scope = container.openScope([['@znight/http#HttpContext', ctx]])
+const user = scope.run(() => container.get(CurrentUser).name)
+await scope.close()
+```
+
 ## Lazy dependencies
 
 `Lazy<T>` injects a handle resolved at call time, in the current scope. It breaks cycles and lets a

package/dist/index.d.mts

@@ -399,6 +399,29 @@ interface ManagedInstance {
 }
 /** Seed values of a request scope: token-keyed pairs (aliases and known classes are accepted). */
 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.
+ */
+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;
+}
 /**
  * The dependency injection container. It consumes the metadata generated by `@znight/compiler`:
  * no reflection happens at runtime, factories are called in a precomputed order and resolving a
@@ -500,6 +523,12 @@ export declare class Container {
    * disposal failed.
    */
   runInScope<R>(fn: () => R | Promise<R>, values?: ScopeValues): Promise<R>;
+  /**
+   * 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;
   /** The active request scope, if any. */
   currentScope(): ScopeContext | undefined;
   /**
@@ -1065,5 +1094,5 @@ export declare class ZnightAggregateError extends ZnightError {
  * that were attached to it instead of being thrown. Empty when there are none.
  */
 export declare function getSuppressedErrors(error: unknown): readonly unknown[];
-export type { ApplicationOptions, ApplicationState, ClassKey, ClassMarker, ConsoleLike, ConsoleLoggerOptions, CoreLogger, HookEvent, HookListener, HookName, HookWrapper, HooksOptions, HotContext, HttpRequestEvent, InitOptions, InjectableOptions, InterceptMethodOptions, InterceptOptionsArgs, InterceptorClass, InterceptorLink, LogContext, LogLevel, ManagedInstance, MessageDeliveryEvent, MessagePublishEvent, MethodInterceptor, MethodInvocation, MethodMarker, OnReady, OnStart, OnStop, ParameterMarker, Plugin, PluginContext, PluginHook, PluginOptions, PluginRootsContext, ProcessLike, ProviderKey, ProviderValues, ProvidesOptions, ScheduledRunAbortReason, ScheduledRunEvent, ScheduledRunOutcome, ScheduledRunTrigger, ScopeContext, ScopeValues, ShutdownOptions, ShutdownSignal, TypedToken, ZnightHooks };
+export type { ApplicationOptions, ApplicationState, ClassKey, ClassMarker, ConsoleLike, ConsoleLoggerOptions, CoreLogger, HookEvent, HookListener, HookName, HookWrapper, HooksOptions, HotContext, HttpRequestEvent, InitOptions, InjectableOptions, InterceptMethodOptions, InterceptOptionsArgs, InterceptorClass, InterceptorLink, LogContext, LogLevel, ManagedInstance, MessageDeliveryEvent, MessagePublishEvent, MethodInterceptor, MethodInvocation, MethodMarker, OnReady, OnStart, OnStop, OpenedScope, ParameterMarker, Plugin, PluginContext, PluginHook, PluginOptions, PluginRootsContext, ProcessLike, ProviderKey, ProviderValues, ProvidesOptions, ScheduledRunAbortReason, ScheduledRunEvent, ScheduledRunOutcome, ScheduledRunTrigger, ScopeContext, ScopeValues, ShutdownOptions, ShutdownSignal, TypedToken, ZnightHooks };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -809,12 +809,30 @@ function lifecycleError(step, error) {
 // src/scope.ts
 /** Implementation of {@link ScopeContext} used by the container (internal). */
 var RequestScope = class {
-	values = /* @__PURE__ */ new Map();
 	created = [];
 	closed = false;
 	#canonical;
-	constructor(canonical) {
+	#values;
+	/** Seed values not yet in {@link values}: canonical tokens and values, alternately. */
+	#seeds;
+	/** `seeds`: canonical tokens and their values, alternately (copied into {@link values} on first use). */
+	constructor(canonical, seeds) {
 		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() {
+		let values = this.#values;
+		if (values === void 0) {
+			values = /* @__PURE__ */ new Map();
+			const seeds = this.#seeds;
+			if (seeds !== void 0) {
+				for (let index = 0; index < seeds.length; index += 2) values.set(seeds[index], seeds[index + 1]);
+				this.#seeds = void 0;
+			}
+			this.#values = values;
+		}
+		return values;
 	}
 	get(key) {
 		return this.values.get(this.#canonical(key));
@@ -1309,10 +1327,24 @@ var Container = class Container {
 		if (errors.length > 0) throw new ZnightAggregateError(ErrorCode.LifecycleFailed, `Failed to dispose ${errors.length} request-scoped instance(s)`, errors);
 		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) {
+		let seeds;
+		if (values !== void 0) {
+			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() {
 		return this.#storage.getStore();
 	}
+	#closeScopeFn = (scope) => this.#closeScope(scope);
 	async #closeScope(scope) {
 		scope.closed = true;
 		const errors = [];
@@ -1551,6 +1583,38 @@ function disposeQuietly(instance, method) {
 		if (isThenable(result)) result.then(void 0, () => void 0);
 	} catch {}
 }
+/** Implementation of {@link OpenedScope}. */
+var ScopeHandle = class {
+	#storage;
+	#scope;
+	#dispose;
+	#closed = false;
+	#closing;
+	constructor(storage, scope, dispose) {
+		this.#storage = storage;
+		this.#scope = scope;
+		this.#dispose = dispose;
+	}
+	get context() {
+		return this.#scope;
+	}
+	run(fn, ...args) {
+		return this.#storage.run(this.#scope, fn, ...args);
+	}
+	close() {
+		if (this.#closed) return this.#closing;
+		this.#closed = true;
+		const scope = this.#scope;
+		if (scope.created.length === 0) {
+			scope.closed = true;
+			return;
+		}
+		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;
+	}
+};
 // src/hooks.ts
 const EMPTY = Object.freeze([]);
 /**