injeca 0.2.0 → 0.3.0

package/dist/global.d.mts

@@ -1,2 +1,2 @@
-import { a as setLogger, i as resolve, n as provide, o as start, r as resetContainer, s as stop, t as invoke } from "./global-BLY6_SI_.mjs";
-export { invoke, provide, resetContainer, resolve, setLogger, start, stop };
+import { a as resolve, c as stop, i as resetContainer, n as invoke, o as setLogger, r as provide, s as start, t as getContainer } from "./global-B9Bk2EG2.mjs";
+export { getContainer, invoke, provide, resetContainer, resolve, setLogger, start, stop };

package/dist/global.mjs

@@ -1,3 +1 @@
-import { _ as start, f as invoke, g as setLogger, h as resolve, m as resetContainer, p as provide, v as stop } from "./src-UXkTj4Np.mjs";
-
-export { invoke, provide, resetContainer, resolve, setLogger, start, stop };
+export { t as getContainer, n as invoke, r as provide, i as resetContainer, a as resolve, o as setLogger, s as start, c as stop } from "./global-C0Nk0pU8.mjs";

package/dist/index-DXguNx2M.d.mts

@@ -0,0 +1,643 @@
+import { Logg } from "@guiiai/logg";
+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;
+}
+interface LoggerOptions {
+  enabled?: boolean;
+  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. 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;
+  readonly phase: ServicePhase;
+  /** 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[];
+}
+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. */
+  readonly condition?: 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. */
+interface FallbackDependency<T> {
+  readonly [fallbackBrand]: true;
+  /** The names of the keys, in order of preference. */
+  readonly dependencies: readonly string[];
+  /** 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 : 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.
+ *
+ * A value that is not a decision, a promise, or a throw gives `fail` with `hook-timeout`.
+ */
+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, the result is `fail` with `hook-timeout`. */
+  onTimeout?: TimeoutHandler;
+}
+interface Container {
+  logger: Logger;
+  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;
+  /** 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. */
+  readonly explain: (key: KeyReference) => ServiceExplanation | undefined;
+}
+/** 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;
+}
+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>): Promise<boolean>;
+  (option: ProvideOption<T, undefined>): Promise<boolean>;
+}
+/**
+ * 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.
+   */
+  readonly withdraw: () => 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, or when a newer `replace` or a withdrawal supersedes this call.
+   * 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 {
+  /** Withdraws the invocation. Resolves `false` when it is already withdrawn. Rejects with the teardown errors. */
+  readonly withdraw: () => 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;
+}
+/**
+ * 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.
+   */
+  readonly commit: () => Promise<void>;
+  /** Removes all declared and built services of the transaction. A build that settles later cannot publish. */
+  readonly abort: () => Promise<void>;
+}
+export { HookResult as $, HookContextFor as A, ServiceStatus as At, TimeoutHandler as B, ImpactChange as C, DependencyState as Ct, Disposer as D, ServiceExplanation as Dt, DependencyHookContext as E, ServiceBlocker as Et, Container as F, Logger as Ft, DecisionKind as G, DecideFor as H, ContainerOptions as I, LoggerOptions as It, DependencyHook as J, DecisionOptions as K, HookTimeouts as L, createDefaultLogger as Lt, HookHandler as M, StatusCause as Mt, InvocationContext as N, Clock as Nt, EffectSetup as O, ServicePhase as Ot, LifecycleContext as P, systemClock as Pt, HookDecisionKind as Q, PolicyOptions as R, createLoggLogger as Rt, GraphService as S, DependencySnapshot as St, BuildContext as T, OwnerValue as Tt, Decision as U, Decide as V, DecisionFor as W, FailDecision as X, ExponentialBackoff as Y, HandledDecision as Z, RegistrationOptions as _, ProviderInfo as _t, InvocationHandle as a, ConditionalDependency as at, GraphDependency as b, ServiceMetadata as bt, InvokeOptionObject as c, DependencyMap as ct, ProvideOption as d, KeyOptions as dt, RebuildDecision as et, ProvideOptionFunc as f, KeyReference as ft, Registration as g, ProvidedKey as gt, ProvideOptionWithKeys as h, ProvidedBy as ht, TransactionReplace as i, StopDecision as it, HookDependencies as j, SetStatusOptions as jt, HookContext as k, ServiceState as kt, InvokeOptionObjectWithKeys as l, FallbackDependency as lt, ProvideOptionObjectWithKeys as m, OptionalValue as mt, Transaction as n, RequeueOptions as nt, InvokeOption as o, DependencyDeclaration as ot, ProvideOptionObject as p, OptionalDependency as pt, DecisionSource as q, TransactionProvide as r, ServiceHook as rt, InvokeOptionFunc as s, DependencyDeclarations as st, DeclareOptions as t, RequeueDecision as tt, InvokeOptionWithKeys as u, InferProvided as ut, ReplaceFunction as v, ResolutionCondition as vt, ImpactResult as w, OwnerRecord as wt, GraphResolution as x, DependencyChange as xt, Graph as y, ResolveDependencyDeclaration as yt, TimeoutContext as z, createNoopLogger as zt };
+//# sourceMappingURL=index-DXguNx2M.d.mts.map