ripple-di 1.0.1 → 1.2.0

package/README.md

@@ -61,6 +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`
+| Continue every current override layer         | `withDetachedContext`
+| Run detached with selected overrides          | `withDetachedOverrides`
 | Keep one scope open across several operations | `createScope`
 | Shut everything down                          | `dispose`
 
@@ -172,6 +174,53 @@ 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.
 
+### Continue after the current scope closes
+
+`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"
+
+const tenant = useTenant()
+
+const backgroundTask = withDetachedOverrides(
+  provide(useTenant, tenant),
+  () => updateTenantSearchIndex(),
+)
+
+trackBackgroundTask(backgroundTask)
+```
+
+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:
+
+```ts
+withDetachedContext(() =>
+  runBackgroundTask().finally(finalizeBackgroundTask),
+)
+```
+
 ## Where a value belongs
 
 The same tracked dependency calls that decide when a factory result must be rebuilt also decide which lifecycle owns it and invokes its disposer.
@@ -581,6 +630,8 @@ Every runtime has the same methods, and each has a module-level counterpart that
 - `resolve`
 - `createScope`
 - `withOverrides`
+- `withDetachedContext`
+- `withDetachedOverrides`
 - `createValueOverride`
 - `createOverrideRunner`
 - `dispose`

package/dist/index.d.mts

@@ -189,6 +189,20 @@ interface Runtime {
    * for the callback afterward.
    */
   withOverrides<TCallbackResult>(provisions: ProvisionInput, callback: (scope: Scope) => TCallbackResult): Promise<Awaited<TCallbackResult>>;
+  /**
+   * Runs a callback in a temporary child of the runtime's current base scope.
+   *
+   * The callback does not inherit the current ambient scope, but its scope
+   * 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.
@@ -240,6 +254,21 @@ declare function createScope(provisions?: ProvisionInput): Scope;
  * callbacks, and are cleaned up when the callback finishes.
  */
 declare function withOverrides<TCallbackResult>(provisions: ProvisionInput, callback: (scope: Scope) => TCallbackResult): Promise<Awaited<TCallbackResult>>;
+/**
+ * Runs a callback with overrides outside the current ambient scope.
+ *
+ * The temporary scope inherits from the active installation or runtime root
+ * 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.
@@ -319,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[];
@@ -376,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, 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;
@@ -817,6 +854,14 @@ var RuntimeImpl = class {
 		this.assertScopeManagementAllowed("Runtime.withOverrides");
 		return withChildScope(this.currentAmbientScope(), provisions, callback);
 	}
+	withDetachedOverrides(provisions, callback) {
+		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);
 	}
@@ -956,6 +1001,25 @@ function withOverrides(provisions, callback) {
 	return globalRuntime.withOverrides(provisions, callback);
 }
 /**
+* Runs a callback with overrides outside the current ambient scope.
+*
+* The temporary scope inherits from the active installation or runtime root
+* and remains part of that lifecycle until the callback finishes.
+*/
+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.
 *
@@ -980,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, 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.0.1",
+  "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",