ripple-di 1.1.0 → 1.2.0

package/README.md

@@ -61,7 +61,8 @@ The package is published as ESM.
 | Define an input, derived value, or service    | `defineDependency`
 | Supply the application's values at startup    | `install` with `provide` or `provideFactory`
 | Replace values for one callback               | `withOverrides` with `provide` or `provideFactory`
-| Run after the current scope can close         | `withDetachedOverrides`
+| Continue every current override layer         | `withDetachedContext`
+| Run detached with selected overrides          | `withDetachedOverrides`
 | Keep one scope open across several operations | `createScope`
 | Shut everything down                          | `dispose`
 
@@ -173,11 +174,27 @@ Use such a value inside the callback, and use `createScope` when it has to outli
 Wrapping the value in an object prevents it from being awaited, but the temporary scope still closes before the caller receives it.
 Anything that scope owned has already been cleaned up.
 
-### Run outside the current scope
+### Continue after the current scope closes
 
-`withDetachedOverrides` runs work in a temporary scope that does not inherit the current ambient scope.
-Use it when work must continue after a request or another scoped operation can finish.
-Capture every request value the work needs and provide it explicitly.
+`withDetachedContext` and `withDetachedOverrides` run work outside the current ambient scope, so a request or another scoped operation can close while that work continues.
+
+Use `withDetachedContext` to continue with every override layer that is active when you call it:
+
+```ts
+import { withDetachedContext } from "ripple-di"
+
+const backgroundTask = withDetachedContext(() =>
+  updateTenantSearchIndex(),
+)
+
+trackBackgroundTask(backgroundTask)
+```
+
+It reproduces those layers in new scopes without copying cached dependency values.
+Borrowed values keep their identity, while factory provisions run again and their results belong to the new scopes.
+If a layer owns an existing provided value, the call rejects with `DetachedContextOwnedProvisionError` because the value cannot belong to both contexts.
+
+Use `withDetachedOverrides` when the work should receive only selected values, especially across a security-sensitive boundary:
 
 ```ts
 import { provide, withDetachedOverrides } from "ripple-di"
@@ -192,12 +209,17 @@ const backgroundTask = withDetachedOverrides(
 trackBackgroundTask(backgroundTask)
 ```
 
-The detached scope inherits from the active installation, or from the runtime root when no installation is active.
-It remains part of that lifecycle: closing the installation or calling `dispose()` force-closes it.
-When no installation is active, an unfinished detached scope also prevents `install()` until its callback and cleanup finish.
+Both functions create scopes beneath the active installation, or beneath the runtime root when no installation is active.
+Closing the installation or calling `dispose()` force-closes them, and an unfinished root child prevents `install()`.
+
+The scope remains current while the callback runs and while Ripple DI awaits its result.
+The returned promise settles after cleanup, so code that needs the detached context, including finalization, belongs inside the callback:
 
-The returned promise settles after the callback and cleanup finish.
-Keep or observe it so callback and cleanup failures are handled.
+```ts
+withDetachedContext(() =>
+  runBackgroundTask().finally(finalizeBackgroundTask),
+)
+```
 
 ## Where a value belongs
 
@@ -608,6 +630,7 @@ Every runtime has the same methods, and each has a module-level counterpart that
 - `resolve`
 - `createScope`
 - `withOverrides`
+- `withDetachedContext`
 - `withDetachedOverrides`
 - `createValueOverride`
 - `createOverrideRunner`

package/dist/index.d.mts

@@ -196,6 +196,13 @@ interface Runtime {
    * remains owned by the active installation or runtime root.
    */
   withDetachedOverrides<TCallbackResult>(provisions: ProvisionInput, callback: (scope: Scope) => TCallbackResult): Promise<Awaited<TCallbackResult>>;
+  /**
+   * Continues the current dependency context outside its original scope.
+   *
+   * The runtime reproduces every current override layer beneath its active
+   * installation or root without copying cached dependency values.
+   */
+  withDetachedContext<TCallbackResult>(callback: (scope: Scope) => TCallbackResult): Promise<Awaited<TCallbackResult>>;
   /**
    * Prepares overrides that are applied again to each call of the returned
    * runner.
@@ -254,6 +261,14 @@ declare function withOverrides<TCallbackResult>(provisions: ProvisionInput, call
  * and remains part of that lifecycle until the callback finishes.
  */
 declare function withDetachedOverrides<TCallbackResult>(provisions: ProvisionInput, callback: (scope: Scope) => TCallbackResult): Promise<Awaited<TCallbackResult>>;
+/**
+ * Continues the current dependency context outside its original scope.
+ *
+ * Current override layers are reproduced beneath the active installation or
+ * runtime root without copying cached values, and are cleaned up after the
+ * callback finishes.
+ */
+declare function withDetachedContext<TCallbackResult>(callback: (scope: Scope) => TCallbackResult): Promise<Awaited<TCallbackResult>>;
 /**
  * Prepares dependency overrides that are applied again to each call of the
  * returned runner.
@@ -333,6 +348,12 @@ declare class OwnedProvisionReuseError extends RippleError {
   readonly dependencyName: string;
   constructor(dependencyName: string);
 }
+/** A detached context cannot reproduce a provision that owns its value. */
+declare class DetachedContextOwnedProvisionError extends RippleError {
+  readonly dependencyName: string;
+  readonly scopeName: string;
+  constructor(dependencyName: string, scopeName: string);
+}
 /** Dependency factories called one another in a cycle. */
 declare class DependencyCycleError extends RippleError {
   readonly path: readonly string[];
@@ -390,4 +411,4 @@ declare class LeakedChildScopeError extends RippleError {
   constructor(scopeName: string, leakedChildCount: number);
 }
 //#endregion
-export { type AsValue, AsyncFactoryError, CrossRuntimeDependencyError, CrossScopeResolutionError, type Dependency, DependencyCycleError, type DependencyOptions, type Disposer, DisposerContextError, DuplicateProviderError, FactoryError, type FactoryResult, FactoryScopeOperationError, Installation, InstallationConflictError, LeakedChildScopeError, MissingProviderError, type OverrideRunner, OwnedProvisionReuseError, type ProvideOptions, type Provision, type ProvisionFactory, type ProvisionInput, RippleError, Runtime, RuntimeOptions, type Scope, ScopeClosedError, type ScopeState, type ValueOverride, asValue, createOverrideRunner, createRuntime, createScope, createValueOverride, defineDependency, dispose, install, provide, provideFactory, resolve, withDetachedOverrides, withOverrides };
+export { type AsValue, AsyncFactoryError, CrossRuntimeDependencyError, CrossScopeResolutionError, type Dependency, DependencyCycleError, type DependencyOptions, DetachedContextOwnedProvisionError, type Disposer, DisposerContextError, DuplicateProviderError, FactoryError, type FactoryResult, FactoryScopeOperationError, Installation, InstallationConflictError, LeakedChildScopeError, MissingProviderError, type OverrideRunner, OwnedProvisionReuseError, type ProvideOptions, type Provision, type ProvisionFactory, type ProvisionInput, RippleError, Runtime, RuntimeOptions, type Scope, ScopeClosedError, type ScopeState, type ValueOverride, asValue, createOverrideRunner, createRuntime, createScope, createValueOverride, defineDependency, dispose, install, provide, provideFactory, resolve, withDetachedContext, withDetachedOverrides, withOverrides };

package/dist/index.mjs

@@ -58,6 +58,17 @@ var OwnedProvisionReuseError = class extends RippleError {
 		this.name = "OwnedProvisionReuseError";
 	}
 };
+/** A detached context cannot reproduce a provision that owns its value. */
+var DetachedContextOwnedProvisionError = class extends RippleError {
+	dependencyName;
+	scopeName;
+	constructor(dependencyName, scopeName) {
+		super(`Cannot detach context from scope "${scopeName}" because its provision for dependency "${dependencyName}" owns an existing value. Use a borrowed value or factory provision when the context must be reproducible.`);
+		this.dependencyName = dependencyName;
+		this.scopeName = scopeName;
+		this.name = "DetachedContextOwnedProvisionError";
+	}
+};
 /** Dependency factories called one another in a cycle. */
 var DependencyCycleError = class extends RippleError {
 	path;
@@ -695,6 +706,32 @@ async function withChildScope(parent, provisions, callback) {
 	if (callbackFailed) throw new Error("ripple-di lost a scoped callback error.");
 	return result;
 }
+/** Reproduces the current scope layers beneath a separate lifecycle parent. */
+async function withDetachedScopeContext(base, current, callback) {
+	const snapshots = snapshotDetachedLayers(base, current);
+	return await replayDetachedLayers(base, snapshots.length > 0 ? snapshots : [[]], 0, callback);
+}
+/** Captures immutable provider recipes without retaining scope caches. */
+function snapshotDetachedLayers(base, current) {
+	if (current.state !== "active") throw new ScopeClosedError("Runtime.withDetachedContext", current.name, current.id, current.state);
+	const scopes = [];
+	let cursor = current;
+	while (cursor !== base) {
+		if (!cursor) throw new Error(`Scope "${current.name}" is not beneath base scope "${base.name}".`);
+		if (cursor.state === "closing" || cursor.state === "closed") throw new ScopeClosedError("Runtime.withDetachedContext", cursor.name, cursor.id, cursor.state);
+		scopes.push(cursor);
+		cursor = cursor[scopeParent];
+	}
+	scopes.reverse();
+	for (const scope of scopes) for (const binding of scope.bindings.values()) if (binding.spec.kind === "owned-value") throw new DetachedContextOwnedProvisionError(nodeOf(binding.stamp.dependency).name, scope.name);
+	return scopes.map((scope) => [...scope.bindings.values()].map((binding) => binding.spec.kind === "factory" ? provideFactory(binding.stamp.dependency, binding.spec.factory) : provide(binding.stamp.dependency, binding.spec.value)));
+}
+/** Enters reproduced layers from the original outermost layer inward. */
+async function replayDetachedLayers(parent, layers, index, callback) {
+	const provisions = layers[index];
+	if (!provisions) throw new Error("ripple-di lost a detached context layer.");
+	return await withChildScope(parent, provisions, (scope) => index === layers.length - 1 ? callback(scope) : replayDetachedLayers(scope, layers, index + 1, callback));
+}
 function createDeferred() {
 	let settle;
 	let reject;
@@ -821,6 +858,10 @@ var RuntimeImpl = class {
 		this.assertScopeManagementAllowed("Runtime.withDetachedOverrides");
 		return withChildScope(this.baseScope(), provisions, callback);
 	}
+	withDetachedContext(callback) {
+		this.assertScopeManagementAllowed("Runtime.withDetachedContext");
+		return withDetachedScopeContext(this.baseScope(), this.currentAmbientScope(), callback);
+	}
 	createOverrideRunner(factory) {
 		return createOverrideRunnerFor(this, factory);
 	}
@@ -969,6 +1010,16 @@ function withDetachedOverrides(provisions, callback) {
 	return globalRuntime.withDetachedOverrides(provisions, callback);
 }
 /**
+* Continues the current dependency context outside its original scope.
+*
+* Current override layers are reproduced beneath the active installation or
+* runtime root without copying cached values, and are cleaned up after the
+* callback finishes.
+*/
+function withDetachedContext(callback) {
+	return globalRuntime.withDetachedContext(callback);
+}
+/**
 * Prepares dependency overrides that are applied again to each call of the
 * returned runner.
 *
@@ -993,4 +1044,4 @@ function dispose() {
 	return globalRuntime.dispose();
 }
 //#endregion
-export { AsyncFactoryError, CrossRuntimeDependencyError, CrossScopeResolutionError, DependencyCycleError, DisposerContextError, DuplicateProviderError, FactoryError, FactoryScopeOperationError, InstallationConflictError, LeakedChildScopeError, MissingProviderError, OwnedProvisionReuseError, RippleError, ScopeClosedError, asValue, createOverrideRunner, createRuntime, createScope, createValueOverride, defineDependency, dispose, install, provide, provideFactory, resolve, withDetachedOverrides, withOverrides };
+export { AsyncFactoryError, CrossRuntimeDependencyError, CrossScopeResolutionError, DependencyCycleError, DetachedContextOwnedProvisionError, DisposerContextError, DuplicateProviderError, FactoryError, FactoryScopeOperationError, InstallationConflictError, LeakedChildScopeError, MissingProviderError, OwnedProvisionReuseError, RippleError, ScopeClosedError, asValue, createOverrideRunner, createRuntime, createScope, createValueOverride, defineDependency, dispose, install, provide, provideFactory, resolve, withDetachedContext, withDetachedOverrides, withOverrides };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ripple-di",
   "type": "module",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Scoped dependency injection for TypeScript with automatic dependency tracking, lifecycle-aware cleanup, and no container lookups in application code.",
   "keywords": [
     "dependency-injection",