ripple-di 1.0.1 → 1.1.0

package/README.md

@@ -61,6 +61,7 @@ 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`
 | Keep one scope open across several operations | `createScope`
 | Shut everything down                          | `dispose`
 
@@ -172,6 +173,32 @@ 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
+
+`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.
+
+```ts
+import { provide, withDetachedOverrides } from "ripple-di"
+
+const tenant = useTenant()
+
+const backgroundTask = withDetachedOverrides(
+  provide(useTenant, tenant),
+  () => updateTenantSearchIndex(),
+)
+
+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.
+
+The returned promise settles after the callback and cleanup finish.
+Keep or observe it so callback and cleanup failures are handled.
+
 ## 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 +608,7 @@ Every runtime has the same methods, and each has a module-level counterpart that
 - `resolve`
 - `createScope`
 - `withOverrides`
+- `withDetachedOverrides`
 - `createValueOverride`
 - `createOverrideRunner`
 - `dispose`

package/dist/index.d.mts

@@ -189,6 +189,13 @@ 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>>;
   /**
    * Prepares overrides that are applied again to each call of the returned
    * runner.
@@ -240,6 +247,13 @@ 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>>;
 /**
  * Prepares dependency overrides that are applied again to each call of the
  * returned runner.
@@ -376,4 +390,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, 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 };

package/dist/index.mjs

@@ -817,6 +817,10 @@ 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);
+	}
 	createOverrideRunner(factory) {
 		return createOverrideRunnerFor(this, factory);
 	}
@@ -956,6 +960,15 @@ 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);
+}
+/**
 * Prepares dependency overrides that are applied again to each call of the
 * returned runner.
 *
@@ -980,4 +993,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, DisposerContextError, DuplicateProviderError, FactoryError, FactoryScopeOperationError, InstallationConflictError, LeakedChildScopeError, MissingProviderError, OwnedProvisionReuseError, RippleError, ScopeClosedError, asValue, createOverrideRunner, createRuntime, createScope, createValueOverride, defineDependency, dispose, install, provide, provideFactory, resolve, withDetachedOverrides, withOverrides };

package/package.json

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