ripple-di 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,379 @@
+//#region src/value.d.ts
+declare const asValueBrand: unique symbol;
+/**
+ * A factory result marked as the dependency value itself.
+ *
+ * Create it with `asValue`.
+ */
+interface AsValue<T> {
+  readonly [asValueBrand]: (value: T) => T;
+}
+/** What a dependency factory may return: the value, or a marked value. */
+type FactoryResult<T> = T | AsValue<T>;
+/**
+ * Uses a factory result as the dependency value even when it is a `Promise`.
+ *
+ * A factory that returns a promise is normally rejected, because dependency
+ * reads made after an `await` are not tracked.
+ * Wrap the result when the promise itself is the value the dependency holds.
+ * A value that merely implements `then`, such as a query builder, is an
+ * ordinary value and does not need this.
+ */
+declare function asValue<T>(value: T): AsValue<T>;
+//#endregion
+//#region src/provide.d.ts
+declare const provisionBrand: unique symbol;
+/**
+ * A value or factory prepared for a scope or runtime installation.
+ *
+ * Create provisions with `provide` or `provideFactory`.
+ */
+interface Provision {
+  readonly [provisionBrand]: true;
+}
+/** One provision or a list accepted by scopes, installations, and overrides. */
+type ProvisionInput = Provision | readonly Provision[];
+/** Ownership options for an existing value supplied with `provide`. */
+interface ProvideOptions<T> {
+  /**
+   * Cleanup called when the receiving scope or installation closes.
+   *
+   * Pass `true` to use the dependency's cleanup callback, or pass a different
+   * callback explicitly.
+   * Either form transfers ownership of the value to Ripple DI.
+   */
+  readonly dispose?: Disposer<T> | true;
+}
+/**
+ * Uses an existing value for a dependency in a scope or installation.
+ *
+ * Ripple DI cleans up the value only when `options.dispose` is provided.
+ * Pass `true` to reuse cleanup configured by `defineDependency`, or pass a
+ * callback to override it.
+ * A function passed as the value remains a value rather than becoming a factory.
+ * A provision that transfers ownership can be used in only one scope or
+ * installation.
+ */
+declare function provide<T>(dependency: Dependency<T>, value: NoInfer<T>, options?: ProvideOptions<NoInfer<T>>): Provision;
+/**
+ * Creates a dependency override on demand in the receiving scope or
+ * installation.
+ *
+ * The factory must be synchronous.
+ * Calls to other dependencies inside it are tracked automatically.
+ * The receiving scope or installation owns the created value.
+ * When the dependency has a configured `dispose` callback, that callback
+ * cleans up the override when its owner closes.
+ */
+declare function provideFactory<T>(dependency: Dependency<T>, factory: () => FactoryResult<NoInfer<T>>): Provision;
+//#endregion
+//#region src/scope.d.ts
+/** Current lifecycle phase of a scope. */
+type ScopeState = "active" | "retiring" | "closing" | "closed";
+/**
+ * An isolated view of dependency values that inherits from a parent scope.
+ *
+ * A scope can replace selected dependencies without changing its parent.
+ * Scope management and lifecycle methods cannot be called from a dependency
+ * factory or disposer in the same runtime.
+ */
+interface Scope {
+  /** Returns a dependency value explicitly from this scope. */
+  resolve<T>(dependency: Dependency<T>): T;
+  /** Creates a child scope with optional dependency overrides. */
+  createScope(provisions?: ProvisionInput): Scope;
+  /** Makes this scope current while the callback runs without closing it. */
+  run<TCallbackResult>(callback: () => TCallbackResult): TCallbackResult;
+  /** Runs a callback in a temporary child scope and cleans it up afterward. */
+  withOverrides<TCallbackResult>(provisions: ProvisionInput, callback: (scope: Scope) => TCallbackResult): Promise<Awaited<TCallbackResult>>;
+  /** Waits for existing child scopes before cleaning up this scope. */
+  retire(): Promise<void>;
+  /** Closes all child scopes and then cleans up this scope. */
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/overrides.d.ts
+/** Builds the provisions used by one call. */
+type ProvisionFactory = () => ProvisionInput;
+/**
+ * A prepared set of overrides applied separately to each call.
+ *
+ * Use it when a long-lived object runs every operation in its own short-lived
+ * scope with the same providers.
+ */
+interface OverrideRunner {
+  /**
+   * Runs a callback with this runner's overrides.
+   *
+   * Every call gets its own scope, so concurrent calls stay isolated, and the
+   * scope is cleaned up when the callback finishes.
+   */
+  run<TCallbackResult>(callback: (scope: Scope) => TCallbackResult): Promise<Awaited<TCallbackResult>>;
+  /**
+   * Returns a function that runs the given one with these overrides.
+   *
+   * Every call of the returned function is one `run` call that forwards the
+   * arguments and the receiver it was called with, so nothing exists before
+   * the returned function is called.
+   */
+  wrap<TThis, TArgs extends unknown[], TCallbackResult>(callback: (this: TThis, ...args: TArgs) => TCallbackResult): (this: TThis, ...args: TArgs) => Promise<Awaited<TCallbackResult>>;
+  /**
+   * Returns a runner that adds more overrides on top of these ones.
+   *
+   * The added overrides replace the ones they share a dependency with, and
+   * this runner keeps working on its own.
+   */
+  extend(factory: ProvisionFactory): OverrideRunner;
+}
+/**
+ * Replaces one dependency with a value for the duration of a callback.
+ *
+ * Create it with `createValueOverride` for a dependency that application code
+ * replaces the same way again and again.
+ */
+type ValueOverride<T> = <TCallbackResult>(value: T, callback: (scope: Scope) => TCallbackResult) => Promise<Awaited<TCallbackResult>>;
+//#endregion
+//#region src/runtime.d.ts
+/** Options for starting an independent dependency graph. */
+interface RuntimeOptions {
+  /** Human-readable name used in scope names and error messages. */
+  readonly name?: string;
+}
+/**
+ * Long-lived providers used as the default application wiring for a runtime.
+ *
+ * Close the installation to remove its providers and clean up the scopes and
+ * owned values created beneath it.
+ */
+interface Installation {
+  /** Removes these providers and closes everything owned beneath them. */
+  close(): Promise<void>;
+}
+/**
+ * An independent dependency graph with its own definitions, cached values,
+ * and lifecycle.
+ *
+ * Most applications can use the module-level functions and do not need to
+ * create a runtime explicitly.
+ * Installation and scope management methods cannot be called from one of this
+ * runtime's dependency factories or disposers.
+ */
+interface Runtime {
+  /**
+   * Defines a dependency with no built-in value.
+   *
+   * Supply it through an installation or scope before reading it.
+   * A configured disposer applies only to values Ripple DI owns.
+   */
+  defineDependency<T>(options?: DependencyOptions<T>): Dependency<T>;
+  /**
+   * Defines a dependency with a lazy built-in factory.
+   *
+   * The result is cached. A scope gets a separate result when it overrides a
+   * dependency that the factory called.
+   */
+  defineDependency<T>(factory: () => FactoryResult<T>, options?: DependencyOptions<T>): Dependency<T>;
+  /**
+   * Installs long-lived providers as the fallback beneath scoped overrides.
+   *
+   * A runtime can have one active installation, and previously created scopes
+   * must be fully closed before this method is called.
+   */
+  install(provisions: ProvisionInput): Installation;
+  /** Returns a dependency value from the current scope. */
+  resolve<T>(dependency: Dependency<T>): T;
+  /** Creates a manually managed child of the current scope. */
+  createScope(provisions?: ProvisionInput): Scope;
+  /**
+   * Runs a callback with temporary overrides and cleans up everything created
+   * for the callback afterward.
+   */
+  withOverrides<TCallbackResult>(provisions: ProvisionInput, callback: (scope: Scope) => TCallbackResult): Promise<Awaited<TCallbackResult>>;
+  /**
+   * Prepares overrides that are applied again to each call of the returned
+   * runner.
+   */
+  createOverrideRunner(factory: ProvisionFactory): OverrideRunner;
+  /**
+   * Prepares a reusable helper that replaces one dependency with a value for
+   * one callback.
+   */
+  createValueOverride<T>(dependency: Dependency<T>, options?: ProvideOptions<NoInfer<T>>): ValueOverride<T>;
+  /** Closes every scope and cleans up every value owned by this runtime. */
+  dispose(): Promise<void>;
+}
+/**
+ * Creates an independent dependency graph.
+ *
+ * Define its dependencies through the methods on the returned runtime.
+ */
+declare function createRuntime(options?: RuntimeOptions): Runtime;
+/**
+ * Defines a dependency with no built-in value.
+ *
+ * Supply it through an installation or scope before reading it.
+ * A configured disposer applies only to values Ripple DI owns.
+ */
+declare function defineDependency<T>(options?: DependencyOptions<T>): Dependency<T>;
+/**
+ * Defines a dependency with a lazy built-in factory.
+ *
+ * The result is cached. A scope gets a separate result when it overrides a
+ * dependency that the factory called.
+ */
+declare function defineDependency<T>(factory: () => FactoryResult<T>, options?: DependencyOptions<T>): Dependency<T>;
+/**
+ * Installs long-lived providers for module-level dependencies.
+ *
+ * Scoped overrides still take priority. Close the returned installation to
+ * remove its providers and clean up everything created from them.
+ */
+declare function install(provisions: ProvisionInput): Installation;
+/** Returns a dependency value from the current scope. */
+declare function resolve<T>(dependency: Dependency<T>): T;
+/** Creates a manually managed scope with optional dependency overrides. */
+declare function createScope(provisions?: ProvisionInput): Scope;
+/**
+ * Runs a callback with temporary dependency overrides.
+ *
+ * Overrides remain active across `await`, stay isolated from concurrent
+ * callbacks, and are cleaned up when the callback finishes.
+ */
+declare function withOverrides<TCallbackResult>(provisions: ProvisionInput, callback: (scope: Scope) => TCallbackResult): Promise<Awaited<TCallbackResult>>;
+/**
+ * Prepares dependency overrides that are applied again to each call of the
+ * returned runner.
+ *
+ * The factory runs again for every call, so a call can own the values it
+ * provides.
+ */
+declare function createOverrideRunner(factory: ProvisionFactory): OverrideRunner;
+/**
+ * Prepares a helper that replaces one dependency with a value for one callback.
+ *
+ * Use it for a dependency that application code supplies the same way in many
+ * places, such as a client or a request context.
+ * Ownership options given here apply to every value the helper receives.
+ */
+declare function createValueOverride<T>(dependency: Dependency<T>, options?: ProvideOptions<NoInfer<T>>): ValueOverride<T>;
+/** Closes every scope and cleans up every owned value. */
+declare function dispose(): Promise<void>;
+//#endregion
+//#region src/dependency.d.ts
+declare const dependencyBrand: unique symbol;
+/**
+ * A function that returns the dependency value for the current scope.
+ *
+ * Pass the same function to `provide` to replace its value or to
+ * `scope.resolve` when you need to read from a specific scope.
+ */
+type Dependency<T> = (() => T) & {
+  readonly [dependencyBrand]: (value: T) => T;
+};
+/** Cleans up a value when Ripple DI no longer needs it. */
+type Disposer<T> = (value: T) => void | Promise<void>;
+/** Optional diagnostics and cleanup for a dependency. */
+interface DependencyOptions<T> {
+  /** Optional name used only in error messages and resolution paths. */
+  readonly name?: string;
+  /**
+   * Cleans up values owned by Ripple DI.
+   *
+   * This applies to the built-in factory, `provideFactory`, and values passed
+   * through `provide` with `dispose: true`.
+   * Plain values passed through `provide` remain borrowed.
+   */
+  readonly dispose?: Disposer<T>;
+}
+//#endregion
+//#region src/errors.d.ts
+/** Base class for errors thrown by Ripple DI. */
+declare class RippleError extends Error {}
+/** The dependency was requested without a provider or built-in factory. */
+declare class MissingProviderError extends RippleError {
+  readonly dependencyName: string;
+  readonly path: readonly string[];
+  constructor(dependencyName: string, path: readonly string[]);
+}
+/** A dependency was used with a different runtime than the one that defined it. */
+declare class CrossRuntimeDependencyError extends RippleError {
+  readonly dependencyName: string;
+  readonly dependencyRuntimeName: string;
+  readonly requestedRuntimeName: string;
+  constructor(dependencyName: string, dependencyRuntimeName: string, requestedRuntimeName: string);
+}
+/** `install()` was called while another installation or scope was unfinished. */
+declare class InstallationConflictError extends RippleError {
+  readonly runtimeName: string;
+  readonly reason: "active-installation" | "closing-installation" | "live-scopes";
+  readonly scopeNames: readonly string[];
+  constructor(runtimeName: string, reason: "active-installation" | "closing-installation" | "live-scopes", scopeNames?: readonly string[]);
+}
+/** The same dependency appears more than once in one provision list. */
+declare class DuplicateProviderError extends RippleError {
+  readonly dependencyName: string;
+  constructor(dependencyName: string);
+}
+/** One owned-value provision was installed for more than one owner. */
+declare class OwnedProvisionReuseError extends RippleError {
+  readonly dependencyName: string;
+  constructor(dependencyName: string);
+}
+/** Dependency factories called one another in a cycle. */
+declare class DependencyCycleError extends RippleError {
+  readonly path: readonly string[];
+  constructor(path: readonly string[]);
+}
+/** A dependency factory returned a `Promise` instead of the value. */
+declare class AsyncFactoryError extends RippleError {
+  readonly dependencyName: string;
+  readonly path: readonly string[];
+  constructor(dependencyName: string, path: readonly string[]);
+}
+/** A dependency factory threw an error available through this error's `cause`. */
+declare class FactoryError extends RippleError {
+  readonly dependencyName: string;
+  readonly path: readonly string[];
+  constructor(dependencyName: string, path: readonly string[], cause: unknown);
+}
+/** An operation tried to use a scope that is retiring, closing, or closed. */
+declare class ScopeClosedError extends RippleError {
+  readonly targetName: string;
+  readonly scopeName: string;
+  readonly scopeId: number;
+  readonly state: ScopeState;
+  constructor(targetName: string, scopeName: string, scopeId: number, state: ScopeState);
+}
+/** A factory tried to read explicitly from a different scope. */
+declare class CrossScopeResolutionError extends RippleError {
+  readonly dependencyName: string;
+  readonly factoryScopeName: string;
+  readonly requestedScopeName: string;
+  constructor(dependencyName: string, factoryScopeName: string, requestedScopeName: string);
+}
+/** A dependency factory tried to manage runtime context or lifecycle. */
+declare class FactoryScopeOperationError extends RippleError {
+  readonly dependencyName: string;
+  readonly operation: string;
+  constructor(dependencyName: string, operation: string);
+}
+/** Code running in or started by a disposer used the runtime being closed. */
+declare class DisposerContextError extends RippleError {
+  readonly targetName: string;
+  readonly scopeName: string;
+  readonly scopeId: number;
+  constructor(targetName: string, scopeName: string, scopeId: number);
+}
+/**
+ * A `withOverrides` callback created child scopes and returned without closing
+ * them.
+ *
+ * Ripple DI force-closes the leaked scopes before throwing this error.
+ */
+declare class LeakedChildScopeError extends RippleError {
+  readonly scopeName: string;
+  readonly leakedChildCount: number;
+  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 };