ripple-di 1.0.0 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # Ripple DI
 
-Scoped dependency injection for TypeScript without container lookups in application code.
+Scoped dependency injection for TypeScript with automatic dependency tracking, lifecycle-aware cleanup, and no container lookups in application code.
 
 ## Example
 
@@ -29,7 +29,7 @@ Now replace only the configuration for one operation:
 import { provide, withOverrides } from "ripple-di"
 
 const users = await withOverrides(
-  [provide(useConfig, { databaseUrl: testDatabaseUrl })],
+  provide(useConfig, { databaseUrl: testDatabaseUrl }),
   () => loadUsers(),
 )
 ```
@@ -37,7 +37,13 @@ const users = await withOverrides(
 `useDb` reads `useConfig()`, so Ripple DI builds a separate database for the test configuration and loads the users through it.
 The production database and everything unrelated keep the instances they already had, and the temporary database is closed when the callback finishes.
 
-This is the ripple: override one input, and only the values built from it change.
+This is the ripple: override one input, and only the values derived from it are rebuilt.
+
+## Design trade-off
+
+Ripple DI is an ambient service locator by design: code imports a dependency and calls it instead of receiving it as an argument.
+
+This makes dependencies convenient to use and override, but also makes them less explicit: looking at a function's signature does not tell you which Ripple DI dependencies it reads.
 
 ## Install
 
@@ -48,59 +54,23 @@ npm install ripple-di
 Ripple DI needs `node:async_hooks`, so it runs on Node.js 18 or newer, Bun, and Deno with Node compatibility, but not in browsers.
 The package is published as ESM.
 
-## Quick start
-
-Define each shared input and service once, next to the code that owns it.
-Factories are lazy: they run the first time something reads the value.
-
-```ts
-// config.ts
-import { defineDependency } from "ripple-di"
-
-export const useConfig = defineDependency(() => ({
-  databaseUrl: process.env.DATABASE_URL,
-}))
-```
-
-```ts
-// db.ts
-import { defineDependency } from "ripple-di"
-
-import { useConfig } from "./config"
-
-export const useDb = defineDependency(
-  () => createDb(useConfig().databaseUrl),
-  { dispose: db => db.close() },
-)
-```
-
-Anything that needs the database imports it and calls it.
-
-```ts
-import { useDb } from "./db"
-
-export async function loadUsers() {
-  return useDb().query("select * from users")
-}
-```
-
-The return type of `useDb()` is inferred from `createDb`.
-
 ## Which function do I call?
 
-| You want to                                               | Call
-| --------------------------------------------------------- | ---------------------------
-| Define an input, derived value, or service                | `defineDependency`
-| Supply the real values when the application starts        | `install`
-| Replace values for one callback                           | `withOverrides`
-| Name an override of one dependency you write often        | `createValueOverride`
-| Replace the same values for many separate calls           | `createOverrideRunner`
-| Replace values for a lifetime you manage yourself         | `createScope`
-| Supply a value, or a factory, to `install` or an override | `provide`, `provideFactory`
-| Shut everything down                                      | `dispose`
+| You want to                                   | Call
+| --------------------------------------------- | --------------------------------------------------
+| 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`
+
+`createValueOverride` and `createOverrideRunner` in [Advanced usage](#advanced-usage) turn overrides you write repeatedly into reusable helpers.
 
 ## Define dependencies
 
+Define each shared input and service once, in the module that owns it, and import it wherever it is used.
+
 Call `defineDependency<T>()` without a factory when a value must come from the application, request, or task boundary.
 
 ```ts
@@ -109,7 +79,7 @@ import { defineDependency, provide, withOverrides } from "ripple-di"
 const useTenant = defineDependency<Tenant>()
 
 await withOverrides(
-  [provide(useTenant, tenant)],
+  provide(useTenant, tenant),
   () => processRequest(),
 )
 ```
@@ -117,29 +87,57 @@ await withOverrides(
 Reading it without a provider throws `MissingProviderError`.
 Pass a factory when the dependency has a built-in value.
 The factory runs lazily, and calls to other dependencies inside it are tracked.
-A function is always taken as that factory, so a dependency whose own value is a function needs `defineDependency(() => handler)`.
+A function in the first argument is always the factory, so a dependency whose value is itself a function wraps it: `defineDependency(() => handler)`.
 
 ```ts
 const useClock = defineDependency(() => systemClock)
 const usePublicUrl = defineDependency(() => createPublicUrl(useConfig()))
 ```
 
-The result is cached and recreated wherever one of the dependencies it read is overridden.
-Add a `dispose` callback when values owned by Ripple DI need cleanup, as shown by `useDb` in the quick start.
+The result is cached, and a scope that overrides one of the dependencies it read gets a separate result.
+Its type comes from the factory, so `useDb()` returns whatever `createDb` returns.
+Add a `dispose` callback when values owned by Ripple DI need cleanup, as shown by `useDb` in the example above.
+
+A factory can read dependencies, but cannot create, enter, close, or retire scopes and installations in its own runtime; misuse throws `FactoryScopeOperationError`.
+
+### Promises and thenables
+
+A factory returns the value itself, synchronously; disposers may be asynchronous.
+
+```ts
+import { asValue, defineDependency } from "ripple-di"
+
+// The usual case: the factory returns the value.
+defineDependency(() => createSessionStore())
+
+// Reading this throws AsyncFactoryError: reads made after an await are not tracked.
+defineDependency(async () => loadSession())
+
+// The promise itself is the cached dependency value.
+defineDependency(() => asValue(loadSession()))
+
+// A query builder implements `then` but is an ordinary value.
+defineDependency(() => selectSessions())
+```
+
+A factory is rejected only when it returns a native `Promise` object, so a value that merely implements `then` is stored as it is.
+Wrap the result in `asValue` when the promise itself is the value the dependency holds.
+
+`asValue` marks the promise as the value and does nothing else.
+The dependencies its asynchronous work reads after an `await` are still untracked, so a promise cached for the whole application can end up built from the temporary values of whichever scope started it.
 
 ## Override dependencies
 
 `withOverrides` runs a callback with temporary values and cleans up whatever it created for that callback.
+Pass one `provide` or `provideFactory` directly.
 
 ```ts
 import { provide, withOverrides } from "ripple-di"
 
 const users = await withOverrides(
-  [
-    provide(useConfig, {
-      databaseUrl: "postgres://localhost/test",
-    }),
-  ],
+  provide(useConfig, {
+    databaseUrl: "postgres://localhost/test",
+  }),
   () => loadUsers(),
 )
 ```
@@ -159,43 +157,107 @@ await withOverrides(
 )
 ```
 
-For one dependency, you can omit the array:
+Overrides survive `await` and stay isolated between parallel callbacks.
 
 ```ts
-await withOverrides(
-  provide(useConfig, testConfig),
-  () => loadUsers(),
-)
+const [leftUsers, rightUsers] = await Promise.all([
+  withOverrides(provide(useConfig, leftConfig), () => loadUsers()),
+  withOverrides(provide(useConfig, rightConfig), () => loadUsers()),
+])
 ```
 
-Overrides survive `await` and stay isolated between parallel callbacks.
+### Awaitable callback results
+
+`withOverrides`, and every helper built on it, awaits what its callback returns before closing the temporary scope, so returning a query builder from one of them runs the query.
+Use such a value inside the callback, and use `createScope` when it has to outlive the callback.
+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
-const [leftUsers, rightUsers] = await Promise.all([
-  withOverrides([provide(useConfig, leftConfig)], () => loadUsers()),
-  withOverrides([provide(useConfig, rightConfig)], () => loadUsers()),
-])
+import { provide, withDetachedOverrides } from "ripple-di"
+
+const tenant = useTenant()
+
+const backgroundTask = withDetachedOverrides(
+  provide(useTenant, tenant),
+  () => updateTenantSearchIndex(),
+)
+
+trackBackgroundTask(backgroundTask)
 ```
 
-### Name an override you write repeatedly
+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.
 
-When the same dependency is supplied the same way all over the application, `createValueOverride` turns that into one named helper.
+## 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.
+A factory-created value belongs to the innermost scope that supplied either its factory or one of the dependencies it read.
+When its factory and everything it read belong to the application, the value belongs to the application too, and closing a child scope leaves it alone.
+
+**Reading a dependency inside a scope does not make its value scope-local.**
 
 ```ts
-import { createValueOverride } from "ripple-di"
+// Wrong: every request shares this one transaction.
+const useTransaction = defineDependency(
+  () => useDb().transaction(),
+  { dispose: tx => tx.rollback() },
+)
+```
 
-const withOpenAiClient = createValueOverride(useOpenAiClient)
+`useDb` belongs to the application, so a transaction built from it belongs to the application too.
+Every request reads the same transaction, and it is rolled back at shutdown rather than when the request ends.
 
-await withOpenAiClient(client, () => createTextEmbedding(text))
+For a value that belongs to one operation, define the dependency without a built-in factory.
+Provide its factory when you create the scope of that operation:
+
+```ts
+const useTransaction = defineDependency<Transaction>({
+  dispose: tx => tx.rollback(),
+})
+
+await withOverrides(
+  provideFactory(useTransaction, () => useDb().transaction()),
+  () => processRequest(),
+)
 ```
 
-Each call supplies the value it is given to one callback, exactly like writing `withOverrides` with a single `provide` by hand.
-Pass the ownership options once, and every call cleans its own value up.
+Each call now builds its own transaction, still lazily, and the scope rolls it back when the callback finishes.
+Reading `useTransaction()` outside such a scope throws `MissingProviderError` instead of quietly sharing one.
+
+A value also becomes scope-local through what it reads: a factory that reads a dependency the scope provides — a request context, a tenant, a fixed clock — is rebuilt in that scope and cleaned up with it.
+
+An installation follows the same rule: a value belongs to it when the installation supplied its factory or one of the dependencies the factory read.
 
 ```ts
-const withConnection = createValueOverride(useConnection, { dispose: true })
+const useBuiltInConfig = defineDependency(() => rootConfig)
+const useRootPool = defineDependency(() => createPool(useBuiltInConfig()), {
+  dispose: pool => pool.end(),
+})
+
+const useInstalledConfig = defineDependency<DatabaseConfig>()
+const useInstalledPool = defineDependency(() => createPool(useInstalledConfig()), {
+  dispose: pool => pool.end(),
+})
+
+const installation = install(provide(useInstalledConfig, installedConfig))
+useRootPool()
+useInstalledPool()
+await installation.close() // Before installing replacement providers.
 ```
 
+The installed pool closes with the installation, while the root pool remains cached until `dispose()` because its factory read only built-in dependencies.
+
 ## Wire the application at startup
 
 Some dependencies get their real value only when the application starts.
@@ -211,11 +273,11 @@ export const useTenantResolver = defineDependency<TenantResolver>()
 
 ```ts
 // startup.ts
-import { install, provide } from "ripple-di"
+import { dispose, install, provide } from "ripple-di"
 
 import { useTenantResolver, useWebConfig } from "./dependencies"
 
-const installation = install([
+install([
   provide(useWebConfig, config),
   provide(useTenantResolver, resolveTenant),
 ])
@@ -223,20 +285,25 @@ const installation = install([
 try {
   await runApplication()
 } finally {
-  await installation.close()
+  await dispose()
 }
 ```
 
 Installed providers are the fallback everywhere: request handlers, background jobs, tests, and any other code running outside a scope.
 Nothing is resolved eagerly, and a scoped override still wins over an installed provider.
-Closing the installation removes its providers and cleans up the scopes and owned values created beneath it.
+Closing an installation removes its providers and cleans up values whose factory or tracked dependencies belong to it.
+It keeps the runtime usable, so application-owned values remain cached for later installations.
+Use `installation.close()` before a controlled replacement; use `dispose()` to shut the application down.
 
 - Installing while another installation or any scope is still open throws `InstallationConflictError`, whose message says what is still open.
   Await `installation.close()` before installing a replacement.
 - Providing the same dependency twice in one installation is rejected, exactly like in `withOverrides`.
-- Installing late is allowed: it applies to the reads that come after it, and closing it brings the earlier values back.
+- Install once during startup.
+  Late installation is supported for a controlled bootstrap or a test setup: it applies to the reads that come after it, and closing it brings the earlier values back.
+- If a resource needs the lifetime of each installation, define its dependency without a built-in factory and export a module provision builder that returns `provideFactory`.
+  This keeps the factory body in its owning module, but removes the built-in fallback: reading the dependency without that provision throws `MissingProviderError`.
 - Every worker thread and every process wires its own installation.
-- In tests, install once for the whole process and use `withOverrides` per test.
+- In tests, install once for the whole process and override per test, as shown in [Test your application](#test-your-application).
 
 ### Collect the providers of several modules
 
@@ -264,17 +331,19 @@ export function getPlatformProvisions() {
 
 ```ts
 // startup.ts
-const installation = install([
+import { dispose, install } from "ripple-di"
+
+install([
   ...getCoreProvisions(),
   ...getPlatformProvisions(),
 ])
 
-onShutdown(() => installation.close())
+onShutdown(() => dispose())
 ```
 
 - Export a function that builds the provisions rather than a ready-made array, so each installation gets provisions of its own.
   A provision that hands over ownership belongs to a single installation and cannot be reused by the next one.
-- The composition root that installs the provisions is also the one that closes the installation, from whichever shutdown hook the application already has.
+- The composition root that installs the provisions also calls `dispose()` from the shutdown hook the application already has.
 - Tests have the same single composition root: one preload installs the provisions of every layer the suite needs.
   Separate preloads installing on their own would fail on the second `install` instead of adding their providers.
 
@@ -282,6 +351,7 @@ onShutdown(() => installation.close())
 
 Call `dispose()` when the application shuts down.
 It closes every scope and cleans up every owned value still held by the module-level API, including an active installation.
+Closing only the installation can leave [application-owned values](#where-a-value-belongs) cached.
 
 ```ts
 import { dispose } from "ripple-di"
@@ -294,6 +364,66 @@ Values created inside `withOverrides` never wait for shutdown; they are cleaned
 `dispose()` is final: afterwards the runtime cannot resolve dependencies, create scopes, or install providers, and those calls throw `ScopeClosedError`.
 Do not use it to reset state between tests — use `withOverrides` for that, or create a separate runtime for each lifecycle.
 
+## Test your application
+
+Install the wiring the suite needs once for the whole test process, from the preload or setup file the test runner already has, and give each test the values of its own.
+
+```ts
+import {
+  createOverrideRunner,
+  createScope,
+  provide,
+  type Scope,
+  withOverrides,
+} from "ripple-di"
+
+test("loads users from the test database", () =>
+  withOverrides(
+    provide(useConfig, testConfig),
+    () => loadUsers(),
+  ),
+)
+```
+
+The scope lives exactly as long as that callback, so tests running in parallel cannot see one another's overrides.
+
+When several tests share one set of values that is expensive to build, create the scope once and run each test inside it.
+
+```ts
+let scope: Scope
+
+beforeAll(() => {
+  scope = createScope(provide(useConfig, testConfig))
+})
+
+afterAll(() => scope.close())
+
+test("lists users", () => scope.run(() => listUsers()))
+test("creates a user", () => scope.run(() => createUser()))
+```
+
+Entering a scope in a hook does not carry it into the tests that follow.
+
+```ts
+// Wrong: the scope is current inside this callback and nowhere else.
+beforeAll(() => scope.run(() => {}))
+```
+
+- `scope.run` and `withOverrides` make a scope current for their own callback only, so every test that needs the scope runs inside one of them.
+- Tests that share a suite scope also share the values cached in it, so keep that recipe for values they can safely reuse.
+- `scope.run` does not report child scopes a test leaves open, so a test that creates one closes it itself instead of leaving it until `afterAll`.
+
+When every test in a file needs the same overrides in a separate scope, a runner applies them to each test independently.
+
+```ts
+const testConfigOverrides = createOverrideRunner(() =>
+  provide(useConfig, testConfig),
+)
+
+test("lists users", testConfigOverrides.wrap(() => listUsers()))
+test("creates a user", testConfigOverrides.wrap(() => createUser()))
+```
+
 ## Advanced usage
 
 Everything below is optional.
@@ -320,6 +450,7 @@ provide(useDb, fakeDb, { dispose: db => db.closeImmediately() })
 
 A function passed to `provide` stays an ordinary function value; use `provideFactory` when it should build the value instead.
 The dependencies an override factory reads are tracked like the ones read by the factory it replaces.
+An override factory cannot read the previous value of the dependency it replaces; define a base dependency and a decorated one instead.
 `dispose: true` reuses the disposer from `defineDependency`, so it throws right away when the dependency declares none.
 
 A provision that hands over ownership belongs to a single scope or installation.
@@ -332,15 +463,13 @@ const useQueue = defineDependency<Queue>({
   dispose: queue => queue.close(),
 })
 
-const installation = install([
-  provideFactory(useQueue, () => createQueue(queueUrl)),
-])
+install(provideFactory(useQueue, () => createQueue(queueUrl)))
 
-// Later, at shutdown:
-await installation.close()
+// Later, at application shutdown:
+await dispose()
 ```
 
-The installed factory is lazy, and its queue client is closed with the installation.
+The installed factory is lazy, and its queue client is closed either with the installation during a controlled replacement or with the runtime at application shutdown.
 
 ### Manage a scope explicitly
 
@@ -350,9 +479,7 @@ Use `createScope` when several operations share the same overrides and close at
 ```ts
 import { createScope, provide } from "ripple-di"
 
-const scope = createScope([
-  provide(useConfig, tenantConfig),
-])
+const scope = createScope(provide(useConfig, tenantConfig))
 
 try {
   await scope.run(() => processTenant())
@@ -361,13 +488,36 @@ try {
 }
 ```
 
-- `scope.run` makes the scope current for a callback without closing it.
+- `scope.run` makes the scope current for a callback without closing it, and returns the callback's result unchanged.
 - `scope.resolve(useDb)` reads a dependency from that scope rather than the current one.
+  A factory reads from its own scope only, so calling `scope.resolve` on a different scope inside one throws `CrossScopeResolutionError`.
 - `scope.createScope` and `scope.withOverrides` create children of that scope instead of the current one.
 - A child of the scope that `withOverrides` created must be closed before the callback returns, otherwise Ripple DI closes it and throws `LeakedChildScopeError`.
 - `scope.close()` closes the scope and everything below it, while `scope.retire()` waits for child scopes to finish first.
 - Closing disposes what the scope itself created; reused application values stay open.
 - Cleanup continues past a failing disposer and reports every failure in one `AggregateError`.
+- A disposer, and any async work it starts, cannot read dependencies or manage scopes and installations in the runtime being closed; misuse throws `DisposerContextError`.
+  Put everything cleanup needs into the dependency value itself.
+
+### Name an override you write repeatedly
+
+When a dependency is replaced in only one place, keep `withOverrides` with one `provide` at the call site.
+For repeated replacements, `createValueOverride` turns the pattern into a named helper.
+
+```ts
+import { createValueOverride } from "ripple-di"
+
+const withOpenAiClient = createValueOverride(useOpenAiClient)
+
+await withOpenAiClient(client, () => createTextEmbedding(text))
+```
+
+Each call supplies the value it is given to one callback, exactly like writing `withOverrides` with a single `provide` by hand.
+Pass the ownership options once, and every call cleans its own value up.
+
+```ts
+const withConnection = createValueOverride(useConnection, { dispose: true })
+```
 
 ### Reuse one set of overrides
 
@@ -377,9 +527,9 @@ A long-lived object such as an API caller or a job worker is created once, but e
 ```ts
 import { createOverrideRunner, provide } from "ripple-di"
 
-const jobOverrides = createOverrideRunner(() => [
+const jobOverrides = createOverrideRunner(() =>
   provide(useJobContext, createJobContext(), { dispose: true }),
-])
+)
 
 const worker = createWorker(job => jobOverrides.run(() => handleJob(job)))
 ```
@@ -403,9 +553,9 @@ That also suits a file of independent test cases that share one set of overrides
 `extend` returns a runner with one more layer of overrides and leaves the runner it extends unchanged:
 
 ```ts
-const tenantOverrides = jobOverrides.extend(() => [
+const tenantOverrides = jobOverrides.extend(() =>
   provide(useTenantResolver, tenantResolver),
-])
+)
 
 await tenantOverrides.run(() => handleRequest())
 ```
@@ -449,6 +599,7 @@ await Promise.all([
 ```
 
 A dependency belongs to the runtime that defined it and cannot be read or overridden in another one.
+The module-level `defineDependency` always defines a dependency of the built-in runtime, so an application factory like the one above defines every dependency it needs through its own runtime.
 Pass `name` to `createRuntime` to see that name in error messages.
 Every runtime has the same methods, and each has a module-level counterpart that targets the built-in runtime:
 
@@ -457,6 +608,7 @@ Every runtime has the same methods, and each has a module-level counterpart that
 - `resolve`
 - `createScope`
 - `withOverrides`
+- `withDetachedOverrides`
 - `createValueOverride`
 - `createOverrideRunner`
 - `dispose`
@@ -471,36 +623,31 @@ Errors thrown by your own factory arrive wrapped in `FactoryError` with the orig
 A failed factory is not cached, so the next read tries again.
 
 These errors name the dependencies involved.
-Pass `name` to give one a readable label instead of a generated one:
+An explicit `name` is always used when you provide one:
 
 ```ts
 const useConfig = defineDependency(loadConfig, { name: "config" })
 ```
 
 The name only affects messages.
+Without an explicit name, Ripple DI uses a non-empty factory name or shows a generated name with the `defineDependency` call location, such as `dependency#21 (packages/core/src/openai/config.ts:36)`.
+The location follows the runtime's stack and source maps, is captured once when the dependency is defined, and adds no work during resolution.
 
-## Limits
+## Do not mix package copies
+
+Two copies of Ripple DI, separately installed or bundled, each run their own graph and cannot be combined.
+Do not pass dependencies or provisions between them, and do not call one copy's dependency inside a factory owned by the other.
+Such a call is not detected: the dependency may resolve against its own copy instead of failing at the boundary.
+
+Declare `ripple-di` as a peer dependency in any package that exports dependencies of its own.
+
+## Caveats
 
-- Factories are synchronous; disposers may be asynchronous.
-  A factory returns the value itself, so a value that implements `then`, such as a query builder or another awaitable client, is stored as it is.
-  A factory is rejected only when it returns a native `Promise` object, because dependency reads made after an `await` are not tracked.
-  When the promise is the value, wrap the result in `asValue`: `defineDependency(() => asValue(loadToken()))` defines a `Promise<Token>` dependency created once and awaited by its readers.
-- A `withOverrides` callback that returns an awaitable value has it awaited, exactly like any promise returned from a callback, so returning a query builder runs its query.
-  Use the value inside the callback, and use `createScope` when it has to outlive the callback.
-  Returning it wrapped in an object avoids the await but hands back a value whose scope is already closed, together with everything that scope owned.
-- A factory can read dependencies, but cannot create, enter, close, or retire scopes and installations in its own runtime; misuse throws `FactoryScopeOperationError`.
-- A disposer, and any async work it starts, cannot read dependencies or manage scopes and installations in the runtime being closed; misuse throws `DisposerContextError`.
-  Put everything cleanup needs into the dependency value itself.
-- A factory reads from its own scope only; `scope.resolve` on a different scope throws `CrossScopeResolutionError`.
 - Only the dependency calls made while a factory runs are tracked.
-  Reads from `process.env`, `Date.now()`, or another async context are not.
-- An override factory cannot read the previous value of the dependency it replaces; define a base dependency and a decorated one instead.
-- A factory-created value is scoped only by the dependencies its factory reads.
-  A value whose factory reads none stays shared even when it is first requested inside a scope.
+  Everything else stays invisible: `process.env`, `Date.now()`, and any dependency called after the factory has returned.
 - Read dependencies where you use them.
   A module-level `const db = useDb()` freezes one scope's value forever.
-- Two copies of Ripple DI, separately installed or bundled, each run their own graph and cannot be combined.
-  Do not pass dependencies or provisions between them, and do not call one copy's dependency inside a factory owned by the other.
+- When a factory catches an error from reading a dependency, its value is not shared: every scope that asks for it builds a new one.
 
 ## License
 

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

@@ -170,13 +170,45 @@ var DependencyNodeImpl = class {
 	dispose;
 	dependency;
 	constructor(definition) {
-		this.name = definition.name ?? `dependency#${this.id}`;
+		const generatedName = `dependency#${this.id}`;
+		this.name = definition.name ?? (definition.definitionSite ? `${generatedName} (${definition.definitionSite})` : generatedName);
 		this.runtime = definition.runtime;
 		this.defaultFactory = definition.defaultFactory;
 		this.dispose = definition.dispose;
 		this.dependency = (() => this.runtime.readCallable(this));
 	}
 };
+/** Captures and reduces a definition stack before it enters private metadata. */
+function captureDefinitionSite(caller) {
+	const error = /* @__PURE__ */ new Error();
+	const captureStackTrace = typeof Error.captureStackTrace === "function" ? Error.captureStackTrace : void 0;
+	if (captureStackTrace) captureStackTrace(error, caller);
+	const frames = error.stack?.split("\n").slice(1) ?? [];
+	const skippedFrames = captureStackTrace ? frames : frames.slice(2);
+	for (const frame of skippedFrames) {
+		const site = definitionSiteFromFrame(frame);
+		if (site) return site;
+	}
+}
+function definitionSiteFromFrame(frame) {
+	let location = frame.trim().replace(/^at\s+/, "");
+	const openingParenthesis = location.lastIndexOf("(");
+	if (openingParenthesis >= 0 && location.endsWith(")")) location = location.slice(openingParenthesis + 1, -1);
+	else {
+		const atSign = location.lastIndexOf("@");
+		if (atSign >= 0) location = location.slice(atSign + 1);
+		location = location.replace(/^async\s+/, "");
+	}
+	const match = /^(.*):(\d+):\d+$/.exec(location);
+	if (!match || !match[1]) return;
+	let file = match[1].replace(/^file:\/\//, "").replaceAll("\\", "/");
+	try {
+		file = decodeURI(file);
+	} catch {}
+	const workingDirectory = `${process.cwd().replaceAll("\\", "/")}/`;
+	if (file.startsWith(workingDirectory)) file = file.slice(workingDirectory.length);
+	return `${file}:${match[2]}`;
+}
 /** Creates a property-free callable whose metadata lives only in a `WeakMap`. */
 function createDependency(definition) {
 	const node = new DependencyNodeImpl(definition);
@@ -748,11 +780,15 @@ var RuntimeImpl = class {
 		this.root = new ScopeImpl(this, void 0, []);
 	}
 	defineDependency(factoryOrOptions, maybeOptions) {
+		return this.defineDependencyAt(factoryOrOptions, maybeOptions, captureDefinitionSite(this.defineDependency));
+	}
+	defineDependencyAt(factoryOrOptions, maybeOptions, definitionSite) {
 		const isFactory = typeof factoryOrOptions === "function";
 		const factory = isFactory ? factoryOrOptions : void 0;
 		const options = (isFactory ? maybeOptions : factoryOrOptions) ?? {};
 		return createDependency({
-			name: options.name,
+			name: options.name ?? (factory?.name || void 0),
+			definitionSite,
 			runtime: this,
 			defaultFactory: factory,
 			dispose: options.dispose
@@ -781,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);
 	}
@@ -891,8 +931,7 @@ function createRuntime(options = {}) {
 }
 const globalRuntime = new RuntimeImpl({ name: "global" });
 function defineDependency(factoryOrOptions, maybeOptions) {
-	if (typeof factoryOrOptions === "function") return globalRuntime.defineDependency(factoryOrOptions, maybeOptions);
-	return globalRuntime.defineDependency(factoryOrOptions);
+	return globalRuntime.defineDependencyAt(factoryOrOptions, maybeOptions, captureDefinitionSite(defineDependency));
 }
 /**
 * Installs long-lived providers for module-level dependencies.
@@ -921,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.
 *
@@ -945,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,15 +1,18 @@
 {
   "name": "ripple-di",
   "type": "module",
-  "version": "1.0.0",
-  "description": "Scoped dependency injection for TypeScript with automatic dependency tracking and lifecycle-aware cleanup.",
+  "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",
     "di",
     "inversion-of-control",
     "ioc",
+    "service-locator",
     "typescript",
     "scoped",
+    "dependency-tracking",
+    "dependency-graph",
     "async-context",
     "asynclocalstorage",
     "async-hooks",
@@ -22,7 +25,7 @@
   "engines": {
     "node": ">=18"
   },
-  "packageManager": "bun@1.3.14",
+  "packageManager": "bun@1.4.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/IlyaSemenov/ripple-di.git"
@@ -56,7 +59,7 @@
     "@biomejs/biome": "^2.5.5",
     "@changesets/cli": "^2.31.1",
     "@tsconfig/bun": "^1.0.10",
-    "@types/bun": "^1.3.14",
+    "@types/bun": "^1.4.0",
     "publint": "^0.3.22",
     "tsdown": "^0.22.14",
     "typescript": "^7.0.2"