injeca 0.2.0 → 0.4.0

package/dist/index-DTYp044J.d.mts

@@ -0,0 +1,763 @@
+import { Logg } from "@guiiai/logg";
+/**
+ * The logger of a container. `warn` always writes. The other methods write the lifecycle trace, and injeca calls them only when the `logging` option of the container is `true`.
+ */
+interface Logger {
+  provide: (name: string, dependencies: string[]) => void;
+  invoke: (dependencies: string[]) => void;
+  beforeRun: (name: string) => void;
+  run: (name: string, duration: number) => void;
+  hookOnStart: (name: string) => void;
+  hookOnStartComplete: (name: string, duration: number) => void;
+  hookOnStop: (name: string) => void;
+  hookOnStopComplete: (name: string, duration: number) => void;
+  running: () => void;
+  /** A call that injeca handled in another way than the caller asked, for example a re-entrant `dispose()` that resolved at once. */
+  warn: (message: string) => void;
+}
+interface LoggerOptions {
+  /**
+   * Writes the lifecycle trace: `provide`, `invoke`, builds, `start` and `stop` hooks, and `running`. It defaults to `false`.
+   * A child container uses the value of its parent, unless it sets its own. `warn` does not depend on it.
+   */
+  logging?: boolean;
+  /**
+   * The logger. It defaults to the logger of the parent container, then to `createDefaultLogger()`.
+   * To also silence the warnings, for example in tests, pass `createNoopLogger()`.
+   */
+  logger?: Logger;
+}
+declare function createDefaultLogger(): Logger;
+declare function createLoggLogger(logg: Logg): Logger;
+declare function createNoopLogger(): Logger;
+/**
+ * The time source of a container. Pass a custom clock to control time in tests.
+ *
+ * The reconciler uses it for requeue delays and hook timeouts, and `timeout()` uses it for its signal. The work queue does not use it. It drains on microtasks.
+ */
+interface Clock {
+  now: () => number;
+  /** Calls `callback` after `ms` milliseconds. Returns a function that cancels the call. */
+  setTimeout: (callback: () => void, ms: number) => () => void;
+}
+declare const systemClock: Clock;
+type OwnerValue = string | number | boolean | null | readonly OwnerValue[] | {
+  readonly [key: string]: OwnerValue;
+};
+/** A serializable record that names the owner of a container. injeca does not interpret its fields. */
+interface OwnerRecord {
+  readonly [key: string]: OwnerValue;
+}
+/**
+ * The phase of a service.
+ *
+ * - `declared`: a transaction reserved the service. Consumers cannot resolve it.
+ * - `pending`: the service waits until its required dependencies are available, or for `start()`. It runs no code.
+ * - `conflict`: an exclusive key has more than one declaration in one resolution area. It runs no code.
+ * - `building`: `build` runs. The instance is not visible.
+ * - `starting`: the instance is published. The `start` hooks run.
+ * - `retrying`: a `start` hook returned `requeue`. The service keeps its instance and its dependencies, and waits for the next attempt. It is not available.
+ * - `running`: the instance serves calls. Only this phase has a status.
+ * - `stopping`: the service waits until its holders release it. Then the `stop` hooks and the effect disposers run.
+ * - `failed`: a build failed, a hook returned `fail`, retries ended, or a timeout failed. `start()` or `replace()` moves the service out of it.
+ * - `withdrawn`: the registration is withdrawn and the instance is disposed.
+ */
+type ServicePhase = 'declared' | 'pending' | 'conflict' | 'building' | 'starting' | 'retrying' | 'running' | 'stopping' | 'failed' | 'withdrawn';
+/**
+ * The status of a running instance.
+ *
+ * - `ready`: the service works at full quality.
+ * - `degraded`: every call completes, at lower quality.
+ * - `unavailable`: the instance exists, but calls fail now.
+ */
+type ServiceStatus = 'ready' | 'degraded' | 'unavailable';
+/** One link of a cause chain. A remote plugin uses it to report a cause inside the plugin. */
+interface StatusCause {
+  readonly key: string;
+  readonly owner: OwnerRecord;
+  readonly status: ServiceStatus;
+  readonly reason?: string;
+  readonly cause?: StatusCause;
+}
+/** The second argument of `setStatus` in its object form. */
+interface SetStatusOptions {
+  readonly reason?: string;
+  readonly cause?: StatusCause;
+}
+/** The identity and the effective status of one resolved dependency. */
+interface DependencyState {
+  /** The key name of the provider. For `firstAvailable`, it is the selected key. */
+  readonly provider: string;
+  readonly instanceId: string;
+  readonly status: ServiceStatus;
+}
+/** One dependency in the snapshot of a dependency hook. */
+interface DependencySnapshot<T> extends DependencyState {
+  readonly value: T;
+}
+/** The difference of one dependency between the last handled snapshot and the current snapshot. `undefined` means no provider. */
+interface DependencyChange {
+  /** The local name in `dependsOn`. */
+  readonly key: string;
+  readonly from: DependencyState | undefined;
+  readonly to: DependencyState | undefined;
+}
+/** The state that `watch` sends. `phase` is `undefined` when no provider exists for the key. */
+interface ServiceState {
+  readonly phase: ServicePhase | undefined;
+  /** The effective status. It is `undefined` outside `running`. */
+  readonly status: ServiceStatus | undefined;
+  readonly instanceId: string | undefined;
+  readonly reason?: string;
+  readonly cause?: StatusCause;
+}
+/**
+ * One reason why a service is not `running`, or why it is not available.
+ *
+ * - `missing-provider`: no container in the resolution chain has a provider for a required key.
+ * - `failed-dependency`: the provider of a required key is in `failed`.
+ * - `pending-dependency`: the provider of a required key exists, but it does not run yet.
+ * - `unavailable-dependency`: the provider of a required key runs, but its effective status is `unavailable`. `cause` starts the cause chain.
+ * - `rejected-provider`: a resolution condition rejected the provider of a required key. `owner` and `metadata` name the provider.
+ * - `conflicting-dependency`: the provider of a required key is an exclusive key with more than one declaration.
+ * - `conflict`: the service itself is an exclusive key with more than one declaration. `owners` lists the owner of each declaration.
+ * - `failed`: the service itself is in `failed`.
+ * - `retrying`: a `start` hook of the service returned `requeue`. `attempt` is the attempt that requeued, and `reason` is its reason.
+ * - `not-started`: the container of the service is not started, and nothing demands the service.
+ */
+type ServiceBlocker = {
+  readonly kind: 'missing-provider';
+  readonly dependency: string;
+  readonly key: string;
+} | {
+  readonly kind: 'failed-dependency';
+  readonly dependency: string;
+  readonly key: string;
+  readonly error: unknown;
+} | {
+  readonly kind: 'pending-dependency';
+  readonly dependency: string;
+  readonly key: string;
+  readonly phase: ServicePhase;
+} | {
+  readonly kind: 'unavailable-dependency';
+  readonly dependency: string;
+  readonly key: string;
+  readonly cause: StatusCause;
+} | {
+  readonly kind: 'rejected-provider';
+  readonly dependency: string;
+  readonly key: string;
+  readonly owner: OwnerRecord;
+  readonly metadata: Readonly<Record<string, unknown>>;
+} | {
+  readonly kind: 'conflicting-dependency';
+  readonly dependency: string;
+  readonly key: string;
+  readonly owners: readonly OwnerRecord[];
+} | {
+  readonly kind: 'conflict';
+  readonly key: string;
+  readonly owners: readonly OwnerRecord[];
+} | {
+  readonly kind: 'failed';
+  readonly error: unknown;
+} | {
+  readonly kind: 'retrying';
+  readonly attempt: number;
+  readonly reason?: string;
+} | {
+  readonly kind: 'not-started';
+};
+/** Why a service or an invocation is not `running`, or why it is not available. `graph(container).explain()` returns it. */
+interface ServiceExplanation {
+  readonly name: string;
+  readonly kind: 'service' | 'invocation';
+  readonly owner: OwnerRecord;
+  /** The phase of the service. It is `undefined` for a key without a service. Then `owner` is the owner of the container of the query. */
+  readonly phase: ServicePhase | undefined;
+  /** The effective status of a running service. */
+  readonly status?: ServiceStatus;
+  readonly reason?: string;
+  /** The cause chain of the effective status. */
+  readonly cause?: StatusCause;
+  readonly blockers: readonly ServiceBlocker[];
+  /**
+   * The new instance of a replacement in progress, from `replace()`, a transaction, or a make-before-break rebuild.
+   * The old instance serves until the new one completes `start`. Its phase and blockers tell why the swap did not happen yet.
+   */
+  readonly replacement?: ServiceExplanation;
+}
+declare const providedType: unique symbol;
+declare const optionalType: unique symbol;
+declare const fallbackType: unique symbol;
+declare const conditionalType: unique symbol;
+declare const optionalBrand: unique symbol;
+declare const fallbackBrand: unique symbol;
+declare const conditionBrand: unique symbol;
+type DependencyMap = Record<string, any>;
+/**
+ * A typed identity for a service. `provide` and `defineKey` return one.
+ */
+interface ProvidedKey<Key, T, _D extends DependencyMap | undefined> {
+  key: Key;
+  /** `true` for a key from `defineKey(name, { exclusive: true })`. Only one provider can exist in its resolution area. */
+  readonly exclusive?: boolean;
+  /** Carries the value type. It has no value at run time. */
+  readonly [providedType]?: T;
+}
+/** A key name, a key from `defineKey`, or the result of `provide`. */
+type KeyReference = string | ProvidedKey<string, unknown, DependencyMap | undefined>;
+interface KeyOptions {
+  /** Makes an exclusive key. Two or more providers in one resolution area all go to `conflict`. */
+  readonly exclusive?: boolean;
+}
+/** A frozen record on a registration. Resolution conditions and graph queries read it. */
+type ServiceMetadata = Readonly<Record<string, unknown>>;
+/** The read-only information about a provider that a resolution condition gets. */
+interface ProviderInfo {
+  /** The key name of the provider. */
+  readonly key: string;
+  /** The owner record of the container of the provider. */
+  readonly owner: OwnerRecord;
+  readonly metadata: ServiceMetadata;
+}
+/** A resolution condition from `where`. It must be pure and synchronous. A thrown error counts as `false`. */
+type ResolutionCondition = (provider: ProviderInfo) => boolean;
+type ProvidedBy<T> = string & {
+  __providedType?: T;
+};
+/** A dependency marker from `optional(key)`. A missing provider gives `undefined` and does not keep the dependent `pending`. */
+interface OptionalDependency<T> {
+  readonly [optionalBrand]: true;
+  /** The names of the keys, in order. More than one name comes from `optional(firstAvailable(...))`. */
+  readonly dependencies: readonly string[];
+  /** The resolution condition from `where`, when the marker has one. It filters each candidate. */
+  readonly condition?: ResolutionCondition;
+  /** The resolution conditions of single candidates, from `firstAvailable(where(key, condition), ...)`, by key name. */
+  readonly candidateConditions?: Readonly<Record<string, ResolutionCondition>>;
+  /** Carries the value type. It has no value at run time. */
+  readonly [optionalType]?: T;
+}
+/** A required dependency marker from `where(key, condition)`. A provider that the condition rejects does not resolve. */
+interface ConditionalDependency<T> {
+  readonly [conditionBrand]: true;
+  /** The name of the key. */
+  readonly dependencies: readonly string[];
+  readonly condition: ResolutionCondition;
+  /** Carries the value type. It has no value at run time. */
+  readonly [conditionalType]?: T;
+}
+/**
+ * A fallback dependency marker from `firstAvailable(...keys)`. It resolves to the first available provider in the list.
+ * A resolution condition filters the candidates. The selection is the first available candidate that passes.
+ */
+interface FallbackDependency<T> {
+  readonly [fallbackBrand]: true;
+  /** The names of the keys, in order of preference. */
+  readonly dependencies: readonly string[];
+  /** The resolution condition from `where(firstAvailable(...), condition)`. It filters each candidate. */
+  readonly condition?: ResolutionCondition;
+  /** The resolution conditions of single candidates, from `firstAvailable(where(key, condition), ...)`, by key name. */
+  readonly candidateConditions?: Readonly<Record<string, ResolutionCondition>>;
+  /** Carries the value type. It has no value at run time. */
+  readonly [fallbackType]?: T;
+}
+/** One value of a `dependsOn` declaration: a name, a key, an optional marker, a fallback marker, or a condition marker. */
+type DependencyDeclaration = string | ProvidedKey<string, unknown, DependencyMap | undefined> | OptionalDependency<unknown> | FallbackDependency<unknown> | ConditionalDependency<unknown>;
+type DependencyDeclarations = Record<string, DependencyDeclaration>;
+/** The resolved value of an optional dependency. */
+interface OptionalValue<T> {
+  readonly value: T;
+  readonly status: ServiceStatus;
+}
+type InferProvided<T> = T extends ProvidedKey<any, infer P, any> ? P : T extends ProvidedBy<infer P> ? P : T extends ConditionalDependency<infer P> ? P : never;
+/** A required dependency is its value. An optional dependency is `{ value, status }` or `undefined`. */
+type ResolveDependencyDeclaration<Deps extends DependencyDeclarations> = { [K in keyof Deps]: Deps[K] extends OptionalDependency<infer T> ? OptionalValue<T> | undefined : Deps[K] extends FallbackDependency<infer T> ? T : Deps[K] extends ConditionalDependency<infer T> ? T : Deps[K] extends ProvidedKey<any, infer T, any> ? T : Deps[K] extends ProvidedBy<infer T> ? T : any; };
+/** The hooks that `on` registers in `build` and in an invocation callback. */
+type ServiceHook = 'start' | 'stop' | 'dependency-change' | 'dependency-status-change';
+/** The hooks that run when a dependency changes. Their context has `dependsOn` and `changes`. */
+type DependencyHook = 'dependency-change' | 'dependency-status-change';
+interface DecisionOptions {
+  readonly reason?: string;
+}
+interface ExponentialBackoff {
+  readonly kind: 'exponential';
+  readonly initial: number;
+  readonly max: number;
+  readonly jitter?: number;
+}
+interface RequeueOptions extends DecisionOptions {
+  /** A fixed delay in milliseconds. */
+  readonly after?: number;
+  readonly backoff?: ExponentialBackoff;
+  readonly maxAttempts?: number;
+}
+/** The fields that injeca fills from the hook context. */
+interface DecisionSource {
+  /** The name of the service, or of the invocation. */
+  readonly service: string;
+  readonly instanceId: string;
+  readonly hook: ServiceHook;
+  readonly attempt: number;
+  /** The time of the container clock when `decide` created the decision. */
+  readonly issuedAt: number;
+}
+interface HandledDecision extends DecisionSource, DecisionOptions {
+  readonly kind: 'handled';
+}
+interface RebuildDecision extends DecisionSource, DecisionOptions {
+  readonly kind: 'rebuild';
+}
+interface RequeueDecision extends DecisionSource, RequeueOptions {
+  readonly kind: 'requeue';
+}
+interface StopDecision extends DecisionSource, DecisionOptions {
+  readonly kind: 'stop';
+}
+interface FailDecision extends DecisionSource, DecisionOptions {
+  readonly kind: 'fail';
+  readonly error: unknown;
+}
+/**
+ * The value that a hook returns to tell injeca what to do next. Only `decide` in the hook context creates it.
+ */
+type Decision = HandledDecision | RebuildDecision | RequeueDecision | StopDecision | FailDecision;
+type DecisionKind = Decision['kind'];
+/** The decision kinds that a hook accepts. */
+type HookDecisionKind<H extends ServiceHook> = H extends 'start' ? 'handled' | 'requeue' | 'stop' | 'fail' : H extends 'stop' ? 'handled' | 'fail' : DecisionKind;
+/** The decisions that a hook accepts. */
+type DecisionFor<H extends ServiceHook> = Extract<Decision, {
+  readonly kind: HookDecisionKind<H>;
+}>;
+/**
+ * The value that a hook handler can return.
+ *
+ * A decision tells injeca what to do next. Any other value, for example the result of `app.listen()`, selects the default of the hook.
+ * So the shorthand `on('start', () => app.listen(port))` type-checks.
+ * The `decide` of each hook has only the methods that the hook accepts. A decision from another run fails at run time with `invalid-decision`.
+ */
+type HookResult<_H extends ServiceHook = ServiceHook> = unknown;
+/** All decision constructors. A hook context has only the constructors that its hook accepts. */
+interface Decide {
+  readonly handled: (options?: DecisionOptions) => HandledDecision;
+  readonly rebuild: (options?: DecisionOptions) => RebuildDecision;
+  readonly requeue: (options?: RequeueOptions) => RequeueDecision;
+  readonly stop: (options?: DecisionOptions) => StopDecision;
+  readonly fail: (error: unknown, options?: DecisionOptions) => FailDecision;
+}
+/** The `decide` object of a hook context. A method that the hook does not accept is a type error. */
+type DecideFor<H extends ServiceHook> = Pick<Decide, HookDecisionKind<H>>;
+/** The context of an `onTimeout` handler. `hook` tells which hook timed out, and selects the methods of `decide`. */
+type TimeoutContext = { readonly [H in 'start' | 'stop']: {
+  readonly hook: H;
+  /** The configured timeout in milliseconds. */
+  readonly timeoutMs: number;
+  /** The attempt of the hook run that timed out. */
+  readonly attempt: number;
+  /** The last decision of this hook for this instance. */
+  readonly previous: DecisionFor<H> | undefined;
+  readonly decide: DecideFor<H>;
+}; }['start' | 'stop'];
+/**
+ * Decides what happens when a `start` or `stop` hook times out. It runs synchronously.
+ *
+ * For a `start` timeout, a value that is not a decision or a promise gives `fail` with `hook-timeout`.
+ * For a `stop` timeout, it gives `handled`, so that the stop continues. A throw gives `fail` for both hooks.
+ */
+type TimeoutHandler = (context: TimeoutContext) => unknown;
+/** The timeouts of the `start` and `stop` hooks in milliseconds. A missing value means no timeout. */
+interface HookTimeouts {
+  /** The time for all `start` hooks of one attempt. */
+  start?: number;
+  /** The time for all `stop` hooks and effect disposers of one instance. */
+  stop?: number;
+}
+/**
+ * The retry and timeout options of a service or a container. injeca has no built-in values.
+ *
+ * A service value overrides a container value. A container without a value uses the value of its nearest ancestor that has one.
+ */
+interface PolicyOptions {
+  /**
+   * Limits the attempts of a hook that returns `requeue`. A `maxAttempts` on the decision overrides it.
+   * Without a limit, the requeue continues until the dependency or the container changes.
+   */
+  maxAttempts?: number;
+  /** The timeouts of the `start` and `stop` hooks. Each field overrides the same field of the container. */
+  timeouts?: HookTimeouts;
+  /** Decides what happens when a hook times out. Without it, a `start` timeout gives `fail` with `hook-timeout`, and a `stop` timeout counts as `handled`. */
+  onTimeout?: TimeoutHandler;
+}
+interface Container {
+  logger: Logger;
+  /** `true` when the container writes the lifecycle trace to `logger`. A child container reads it when it is created. */
+  logging: boolean;
+  readonly owner: OwnerRecord;
+  readonly parent: Container | undefined;
+}
+/** The options of `createContainer`. `maxAttempts`, `timeouts`, and `onTimeout` apply to each service of the container and of its descendants that does not set its own value. */
+interface ContainerOptions extends LoggerOptions, PolicyOptions {
+  /** Makes a child container. It resolves keys from its own registrations and from those of its ancestors. */
+  parent?: Container;
+  /** A serializable owner record. It defaults to an empty record. */
+  owner?: OwnerRecord;
+  /** The time source. Only a root container reads it. A child container uses the clock of its root. */
+  clock?: Clock;
+  /**
+   * The random source for the backoff jitter. It returns a number from 0 up to, but not including, 1. It defaults to `Math.random`.
+   * Only a root container reads it. A child container uses the random source of its root.
+   */
+  random?: () => number;
+  /**
+   * The keys that do not resolve from the ancestors. The container and its descendants resolve them only from their own registrations.
+   * An isolated key also ends the resolution area of an exclusive key of an ancestor.
+   */
+  isolate?: readonly KeyReference[];
+}
+type HookDependency<V> = [Exclude<V, undefined>] extends [OptionalValue<infer T>] ? DependencySnapshot<T> | undefined : DependencySnapshot<V>;
+/** The snapshot of a dependency hook: each dependency with its value, `instanceId`, and effective status. An optional dependency can be `undefined`. */
+type HookDependencies<D> = D extends DependencyMap ? { readonly [K in keyof D]: HookDependency<D[K]>; } : Readonly<Record<string, DependencySnapshot<unknown> | undefined>>;
+type Disposer = () => void | Promise<void>;
+type EffectSetup = () => Disposer | void;
+/** The context that each hook handler gets. */
+interface HookContext<H extends ServiceHook> {
+  /** Creates the decisions that this hook accepts. Each decision is bound to this run. */
+  readonly decide: DecideFor<H>;
+  /** The number of the current run of this hook for this instance. The first run is `1`. A requeue adds one. */
+  readonly attempt: number;
+  /** The last decision of this hook for this instance. */
+  readonly previous: DecisionFor<H> | undefined;
+  /** Aborts when a newer target supersedes this run, or when the instance is disposed. */
+  readonly signal: AbortSignal;
+}
+/** The context of `dependency-change` and `dependency-status-change`. */
+interface DependencyHookContext<H extends DependencyHook, D = undefined> extends HookContext<H> {
+  /** The current snapshot of all dependencies. Decide from it, not from one change only. */
+  readonly dependsOn: HookDependencies<D>;
+  /** The difference between the last handled snapshot and the current snapshot. */
+  readonly changes: readonly DependencyChange[];
+}
+type HookContextFor<H extends ServiceHook, D = undefined> = H extends DependencyHook ? DependencyHookContext<H, D> : HookContext<H>;
+type HookHandler<H extends ServiceHook = ServiceHook, D = undefined> = (context: HookContextFor<H, D>) => HookResult<H> | Promise<HookResult<H>>;
+/** The lifecycle members that `build` and an invocation callback get. */
+interface LifecycleContext<D = undefined> {
+  /** Registers a hook. It is valid only while `build` or the callback runs. A later call throws `hook-outside-build`. */
+  on: <H extends ServiceHook>(hook: H, handler: HookHandler<H, D>) => void;
+  /** Runs `setup` and stores the returned disposer on the instance. */
+  effect: (setup: EffectSetup) => void;
+  /** Aborts when a newer target supersedes the build, or when the instance is disposed. */
+  signal: AbortSignal;
+}
+type BuildContext<D extends DependencyMap | undefined = undefined> = {
+  container: Container;
+  name: string;
+  /** The id of the instance that this build creates. */
+  instanceId: string;
+  /** The owner record of the consumer container, when the service has `perConsumer: true`. */
+  consumer?: OwnerRecord;
+  /**
+   * Sets the own status of the instance. It stays valid after `build` returns.
+   * After the instance is disposed, a call has no effect and goes to the observe stream.
+   */
+  setStatus: (status: ServiceStatus, reasonOrOptions?: string | SetStatusOptions) => void;
+} & LifecycleContext<D> & (D extends undefined ? {
+  dependsOn?: unknown;
+} : {
+  dependsOn: D;
+});
+type InvocationContext<D = undefined> = LifecycleContext<D>;
+/** One service, invocation, or declared service in a graph query result. */
+interface GraphService {
+  /** The key name of the service, or the name of the invocation. */
+  readonly key: string;
+  readonly kind: 'service' | 'invocation';
+  /** The owner record of the container of the service. */
+  readonly owner: OwnerRecord;
+  readonly phase: ServicePhase;
+  /** The effective status of a running service. */
+  readonly status?: ServiceStatus;
+  readonly instanceId?: string;
+  readonly metadata: ServiceMetadata;
+  readonly exclusive: boolean;
+  readonly perConsumer: boolean;
+  /** `true` for a registration that `provide(..., { export: true })` exports to the resolution area of the parent container. */
+  readonly exported: boolean;
+  /** The owner record of the consumer container of a `perConsumer` instance. */
+  readonly consumer?: OwnerRecord;
+}
+/**
+ * How a declared edge resolves now.
+ *
+ * - `resolved`: a running provider serves the edge.
+ * - `not-running`: a provider exists, but it does not run.
+ * - `missing`: no provider exists.
+ * - `rejected`: a resolution condition rejected the provider.
+ * - `conflict`: the provider is an exclusive key with more than one declaration.
+ */
+type GraphResolution = 'resolved' | 'not-running' | 'missing' | 'rejected' | 'conflict';
+/** One declared edge of a service. */
+interface GraphDependency {
+  /** The local name in `dependsOn`. */
+  readonly name: string;
+  /** The key names of the edge. A `firstAvailable` edge has its list. */
+  readonly keys: readonly string[];
+  readonly optional: boolean;
+  readonly fallback: boolean;
+  /** `true` when the edge has a resolution condition from `where`. */
+  readonly conditional: boolean;
+  readonly resolution: GraphResolution;
+  /** The provider that the edge selects now. A `missing` edge has none. */
+  readonly provider?: GraphService;
+}
+/**
+ * A proposed change for `impact`.
+ *
+ * - `withdraw`: the service of `key` is withdrawn.
+ * - `replace`: the service of `key` gets a new instance.
+ * - `dispose`: `container` and its descendants are disposed.
+ */
+type ImpactChange = {
+  readonly kind: 'withdraw';
+  readonly key: KeyReference;
+} | {
+  readonly kind: 'replace';
+  readonly key: KeyReference;
+} | {
+  readonly kind: 'dispose';
+  readonly container: Container;
+};
+/** The services that a proposed change affects. Each list has only services that have an instance now. */
+interface ImpactResult {
+  /** The services that stop: the withdrawn services, and the dependents that lose a required dependency. */
+  readonly stopped: readonly GraphService[];
+  /** The dependents that rebuild, because a dependency changes and they have no `dependency-change` handler. */
+  readonly rebuilt: readonly GraphService[];
+  /** The dependents that get a `dependency-change` call. Their handler decides what happens. */
+  readonly notified: readonly GraphService[];
+}
+/**
+ * The graph queries of a container. They are pure reads and never change state.
+ *
+ * The queries cover the container and its descendants. A key resolves as for a consumer in the container: from the container, then from its ancestors.
+ */
+interface Graph {
+  /** All services and invocations, with the declared services of open transactions. */
+  readonly services: () => readonly GraphService[];
+  /** The declared edges of the service of `key`. */
+  readonly dependencies: (key: KeyReference) => readonly GraphDependency[];
+  /** The services whose edges select the service of `key` now. */
+  readonly dependents: (key: KeyReference) => readonly GraphService[];
+  /**
+   * The topological order: each provider comes before its dependents.
+   * With `keys`, the order has only those services and their transitive dependencies. The members of one cycle come together, in registration order.
+   */
+  readonly order: (keys?: readonly KeyReference[]) => readonly GraphService[];
+  /** Each dependency cycle, as a list of services. */
+  readonly cycles: () => readonly (readonly GraphService[])[];
+  /** The services that a proposed change stops, rebuilds, or notifies. It runs on a copy of the graph. */
+  readonly impact: (change: ImpactChange) => ImpactResult;
+  /**
+   * Why the service of `key` is not `running`: missing, conflicting, rejected, failed, or unavailable dependencies.
+   * A key without a service gives `phase: undefined` and one `missing-provider` blocker.
+   */
+  readonly explain: (key: KeyReference) => ServiceExplanation;
+}
+/** The value type of a dependency declaration for `peek`. */
+type PeekValue<D> = D extends OptionalDependency<infer T> ? T : D extends FallbackDependency<infer T> ? T : D extends ConditionalDependency<infer T> ? T : D extends ProvidedKey<string, infer T, DependencyMap | undefined> ? T : D extends ProvidedBy<infer T> ? T : unknown;
+/**
+ * The result of `peek`: the value now, or the reason why no value is available now.
+ *
+ * - `resolved`: a running provider serves the key with the status `ready` or `degraded`.
+ * - `unavailable`: a running provider has the effective status `unavailable`. `reason` and `cause` tell why.
+ * - `not-running`: a provider exists, but it does not run. `phase` is its phase. A `failed` provider has `error`.
+ * - `rejected`: a resolution condition rejected the provider.
+ * - `conflict`: the key is exclusive and has more than one declaration. `owners` lists them.
+ * - `missing`: no provider exists.
+ *
+ * `key` is the key name of the provider. For `firstAvailable`, it is the selected key, or the first key when no key has a provider.
+ */
+type PeekResult<T> = {
+  readonly kind: 'resolved';
+  readonly key: string;
+  readonly owner: OwnerRecord;
+  readonly value: T;
+  readonly status: Exclude<ServiceStatus, 'unavailable'>;
+  readonly instanceId: string;
+} | {
+  readonly kind: 'unavailable';
+  readonly key: string;
+  readonly owner: OwnerRecord;
+  readonly instanceId: string;
+  readonly reason?: string;
+  readonly cause?: StatusCause;
+} | {
+  readonly kind: 'not-running';
+  readonly key: string;
+  readonly owner: OwnerRecord;
+  readonly phase: ServicePhase;
+  readonly error?: unknown;
+} | {
+  readonly kind: 'rejected';
+  readonly key: string;
+  readonly owner: OwnerRecord;
+  readonly metadata: ServiceMetadata;
+} | {
+  readonly kind: 'conflict';
+  readonly key: string;
+  readonly owners: readonly OwnerRecord[];
+} | {
+  readonly kind: 'missing';
+  readonly key: string;
+};
+/** A dependency declaration that `peek` reads. An `optional` marker has no effect. */
+type PeekDependency = DependencyDeclaration;
+/** The registration options that each object form of `provide` accepts. */
+interface RegistrationOptions extends PolicyOptions {
+  /** A record that resolution conditions and graph queries read. injeca freezes a copy. */
+  metadata?: ServiceMetadata;
+  /**
+   * Runs `build` once for each consumer container. The build context then has `consumer`.
+   * Each instance disposes with its consumer container.
+   */
+  perConsumer?: boolean;
+  /**
+   * Exports the registration one level up. The registration stays in its container: its owner, its disposal, its dependencies, and its phases.
+   * It is also a candidate for consumers in the resolution area of the parent container: the parent and each descendant of the parent.
+   * For an exclusive key, it counts as a declaration in that area. On a root container, it has no effect.
+   */
+  export?: boolean;
+}
+type ProvideOptionObject<T, D extends DependencyMap | undefined = undefined> = {
+  build: (context: BuildContext<D>) => T | Promise<T>;
+} & RegistrationOptions & (D extends undefined ? {
+  dependsOn?: Record<string, never>;
+} : {
+  dependsOn: { [K in keyof D]: string; };
+});
+type ProvideOptionFunc<T, D extends DependencyMap | undefined = undefined> = (context: BuildContext<D>) => T | Promise<T>;
+type ProvideOption<T, D extends DependencyMap | undefined = undefined> = ProvideOptionObject<T, D> | ProvideOptionFunc<T, D>;
+interface ProvideOptionObjectWithKeys<T, Deps extends DependencyDeclarations> extends RegistrationOptions {
+  build: (context: BuildContext<ResolveDependencyDeclaration<Deps>>) => T | Promise<T>;
+  dependsOn: Deps;
+}
+type ProvideOptionWithKeys<T, Deps extends DependencyDeclarations> = ProvideOptionObjectWithKeys<T, Deps>;
+type InvokeOptionObject<D extends DependencyMap | undefined = undefined> = {
+  callback: (dependencies: D, context: InvocationContext<D>) => void | Promise<void>;
+} & (D extends undefined ? {
+  dependsOn?: Record<string, never>;
+} : {
+  dependsOn: { [K in keyof D]: string; };
+});
+type InvokeOptionFunc<D extends DependencyMap | undefined = undefined> = (dependencies: D, context: InvocationContext<D>) => void | Promise<void>;
+type InvokeOption<D extends DependencyMap | undefined = undefined> = InvokeOptionObject<D> | InvokeOptionFunc<D>;
+interface InvokeOptionObjectWithKeys<Deps extends DependencyDeclarations> {
+  callback: (dependencies: ResolveDependencyDeclaration<Deps>, context: InvocationContext<ResolveDependencyDeclaration<Deps>>) => void | Promise<void>;
+  dependsOn: Deps;
+}
+type InvokeOptionWithKeys<Deps extends DependencyDeclarations> = InvokeOptionObjectWithKeys<Deps>;
+/**
+ * The `replace()` of a registration. It takes the function shorthand, or the object form with or without `dependsOn`.
+ * An option without `metadata`, `maxAttempts`, `timeouts`, or `onTimeout` keeps that value of the registration. `perConsumer` does not change.
+ */
+interface ReplaceFunction<T> {
+  <Deps extends DependencyDeclarations>(option: ProvideOptionWithKeys<T, Deps>, options?: ReplaceOptions): Promise<boolean>;
+  (option: ProvideOption<T, undefined>, options?: ReplaceOptions): Promise<boolean>;
+}
+/** The options of `replace()`. */
+interface ReplaceOptions {
+  /**
+   * Cancels the pending replacement when the signal aborts, as a newer `replace` does. The old instance stays, and `replace()` resolves `false`.
+   * An aborted signal resolves `false` at once and changes nothing. After the swap, the signal has no effect.
+   */
+  signal?: AbortSignal;
+}
+/** The options of `withdraw()` of a registration or an invocation. */
+interface WithdrawOptions {
+  /**
+   * Ends the wait when the signal aborts, and rejects with the reason. The withdrawal continues. There is no default.
+   * The service gets a `wait-aborted` record in the observe stream when it did not finish its withdrawal. An aborted signal still starts the withdrawal.
+   */
+  signal?: AbortSignal;
+}
+/**
+ * The result of `provide`: the typed key of the service, with `withdraw()` and `replace()`.
+ */
+interface Registration<Key, T, D extends DependencyMap | undefined> extends ProvidedKey<Key, T, D> {
+  /**
+   * Withdraws the service. Dependents stop first. Then the service runs its `stop` hooks and effect disposers.
+   *
+   * Resolves `false` for a stale registration and does not change any service. Rejects with the teardown errors.
+   *
+   * A call from a cleanup that the withdrawal waits for cannot wait: of the service, of a consumer service of it, or of a service that holds it.
+   * injeca finds such a call by the signal of the cleanup, or by the synchronous part of the cleanup. It warns, sends a `reentrant-call` record, and resolves `true` at once. The withdrawal continues.
+   */
+  readonly withdraw: (options?: WithdrawOptions) => Promise<boolean>;
+  /**
+   * Replaces the instance of the service without a gap.
+   *
+   * The old instance keeps serving with its status while the new instance runs `build` and `start`. The swap is one batch.
+   * Resolves `true` after the swap. Resolves `false` for a stale registration, when a newer `replace` or a withdrawal supersedes this call, or when `options.signal` aborts before the swap.
+   * Rejects with the build or start error of the new instance, and the old instance does not change.
+   * Rejects with `replace-while-stopping` when the service is in `stopping`.
+   */
+  readonly replace: ReplaceFunction<T>;
+}
+/** The result of `invoke`. */
+interface InvocationHandle {
+  /** The name of the invocation. Graph queries, for example `graph(container).dependencies(key)` and `explain(key)`, accept it. */
+  readonly key: string;
+  /** Withdraws the invocation. Resolves `false` when it is already withdrawn. Rejects with the teardown errors. `options` work as for `withdraw()` of a registration. */
+  readonly withdraw: (options?: WithdrawOptions) => Promise<boolean>;
+}
+interface DeclareOptions {
+  /** The declared edges. A later `tx.provide` without `dependsOn` uses them. */
+  dependsOn?: DependencyDeclarations;
+  /** An optional declaration does not need a `tx.provide`. Without one, the commit drops it. */
+  optional?: boolean;
+}
+/** The `provide` of a transaction. It takes a name or a key, as `provide` does. */
+interface TransactionProvide {
+  <T, Key extends string, Deps extends DependencyDeclarations>(name: Key, option: ProvideOptionWithKeys<T, Deps>): Registration<Key, T, ResolveDependencyDeclaration<Deps>>;
+  <D extends DependencyMap | undefined, T = unknown, Key extends string = string>(name: Key, option: ProvideOption<T, D>): Registration<Key, T, D>;
+  <T, Key extends string, Deps extends DependencyDeclarations>(key: ProvidedKey<Key, T, DependencyMap | undefined>, option: ProvideOptionWithKeys<NoInfer<T>, Deps>): Registration<Key, T, ResolveDependencyDeclaration<Deps>>;
+  <T, Key extends string>(key: ProvidedKey<Key, T, DependencyMap | undefined>, option: ProvideOption<NoInfer<T>, undefined>): Registration<Key, T, undefined>;
+}
+/** The `replace` of a transaction. It takes the current registration of the key at the commit. */
+interface TransactionReplace {
+  <T, Deps extends DependencyDeclarations>(key: ProvidedKey<string, T, DependencyMap | undefined> | string, option: ProvideOptionWithKeys<NoInfer<T>, Deps>): void;
+  <T>(key: ProvidedKey<string, T, DependencyMap | undefined> | string, option: ProvideOption<NoInfer<T>, undefined>): void;
+}
+/** The options of `tx.commit()`. */
+interface TransactionCommitOptions {
+  /** Aborts the transaction when the signal aborts before the publish. */
+  signal?: AbortSignal;
+}
+/**
+ * A set of registrations that publish together. `transaction(container)` creates it.
+ *
+ * Nothing is visible to consumers before `commit()`. A failed build publishes nothing.
+ */
+interface Transaction {
+  /** Reserves a service. Graph queries see it as `declared`. Consumers cannot resolve it. */
+  readonly declare: (key: KeyReference, options?: DeclareOptions) => void;
+  /** Fills a declared service, or adds a new service. The registration becomes current at the commit. */
+  readonly provide: TransactionProvide;
+  /** Replaces the current registration of `key` in the container at the commit, as `replace()` does. */
+  readonly replace: TransactionReplace;
+  /**
+   * Builds the services in dependency order, then publishes them in one batch. Then the `start` hooks run.
+   *
+   * A service whose required dependencies are not available goes to `pending`. That is not a failure.
+   * If one build fails, nothing publishes, no `start` hook runs, and the promise rejects with the build error.
+   * Resolves after the publish. It does not wait for the `start` hooks.
+   *
+   * When `options.signal` aborts before the publish, the transaction aborts and rolls back, and the commit rejects at once with the reason.
+   * An aborted signal rejects at once and builds nothing. After the publish, the signal has no effect.
+   */
+  readonly commit: (options?: TransactionCommitOptions) => Promise<void>;
+  /** Removes all declared and built services of the transaction. A build that settles later cannot publish. */
+  readonly abort: () => Promise<void>;
+}
+export { DecisionSource as $, PeekValue as A, OwnerRecord as At, LifecycleContext as B, systemClock as Bt, GraphDependency as C, ProviderInfo as Ct, ImpactResult as D, DependencyChange as Dt, ImpactChange as E, ServiceMetadata as Et, HookContext as F, ServiceState as Ft, TimeoutContext as G, createNoopLogger as Gt, ContainerOptions as H, LoggerOptions as Ht, HookContextFor as I, ServiceStatus as It, DecideFor as J, TimeoutHandler as K, HookDependencies as L, SetStatusOptions as Lt, DependencyHookContext as M, ServiceBlocker as Mt, Disposer as N, ServiceExplanation as Nt, PeekDependency as O, DependencySnapshot as Ot, EffectSetup as P, ServicePhase as Pt, DecisionOptions as Q, HookHandler as R, StatusCause as Rt, Graph as S, ProvidedKey as St, GraphService as T, ResolveDependencyDeclaration as Tt, HookTimeouts as U, createDefaultLogger as Ut, Container as V, Logger as Vt, PolicyOptions as W, createLoggLogger as Wt, DecisionFor as X, Decision as Y, DecisionKind as Z, Registration as _, KeyOptions as _t, TransactionReplace as a, HookResult as at, ReplaceOptions as b, OptionalValue as bt, InvokeOptionFunc as c, RequeueOptions as ct, InvokeOptionWithKeys as d, ConditionalDependency as dt, DependencyHook as et, ProvideOption as f, DependencyDeclaration as ft, ProvideOptionWithKeys as g, InferProvided as gt, ProvideOptionObjectWithKeys as h, FallbackDependency as ht, TransactionProvide as i, HookDecisionKind as it, BuildContext as j, OwnerValue as jt, PeekResult as k, DependencyState as kt, InvokeOptionObject as l, ServiceHook as lt, ProvideOptionObject as m, DependencyMap as mt, Transaction as n, FailDecision as nt, InvocationHandle as o, RebuildDecision as ot, ProvideOptionFunc as p, DependencyDeclarations as pt, Decide as q, TransactionCommitOptions as r, HandledDecision as rt, InvokeOption as s, RequeueDecision as st, DeclareOptions as t, ExponentialBackoff as tt, InvokeOptionObjectWithKeys as u, StopDecision as ut, RegistrationOptions as v, KeyReference as vt, GraphResolution as w, ResolutionCondition as wt, WithdrawOptions as x, ProvidedBy as xt, ReplaceFunction as y, OptionalDependency as yt, InvocationContext as z, Clock as zt };
+//# sourceMappingURL=index-DTYp044J.d.mts.map