injeca 0.2.0 → 0.4.0

package/dist/global-DPfe26g5.d.mts

@@ -0,0 +1,217 @@
+import { A as PeekValue, At as OwnerRecord, H as ContainerOptions, O as PeekDependency, P as EffectSetup, S as Graph, St as ProvidedKey, Tt as ResolveDependencyDeclaration, V as Container, Vt as Logger, _ as Registration, _t as KeyOptions, d as InvokeOptionWithKeys, dt as ConditionalDependency, f as ProvideOption, g as ProvideOptionWithKeys, gt as InferProvided, ht as FallbackDependency, k as PeekResult, mt as DependencyMap, n as Transaction, o as InvocationHandle, pt as DependencyDeclarations, s as InvokeOption, wt as ResolutionCondition, xt as ProvidedBy, yt as OptionalDependency } from "./index-DTYp044J.mjs";
+import { setActiveSub } from "alien-signals";
+/** The identity of an event. Any object with a string `id` is an event key, for example an eventa definition. */
+interface EventKey {
+  readonly id: string;
+}
+/** A frozen record on a listener, for example its priority, timeout, or failure policy. injeca does not read it. */
+type ListenerMetadata = Readonly<Record<string, unknown>>;
+/** One listener that `listeners()` returns. */
+interface ListenerEntry<H> {
+  readonly handler: H;
+  /** The owner record of the container that owns the listener. */
+  readonly owner: OwnerRecord;
+  readonly metadata: ListenerMetadata;
+}
+/**
+ * Creates a container. With `options.parent`, the container is a child of that container.
+ *
+ * A child container does not start when it is created, even under a started parent. It waits for `start(child)`.
+ */
+declare function createContainer(options?: ContainerOptions): Container;
+/**
+ * Runs `setup` and stores the returned disposer on the container. `dispose(container)` runs the disposers in reverse order.
+ *
+ * When the disposal of the container started or ended, the disposer runs at once after `setup`, so that the resource does not leak.
+ * A disposer that throws throws to the caller. A disposer promise that rejects is reported outside the call, as an unhandled error.
+ */
+declare function effect$1(container: Container, setup: EffectSetup): void;
+interface DisposeOptions {
+  /**
+   * Ends the wait when the signal aborts, and rejects with the reason. The disposal continues in the background. There is no default.
+   * Each service that did not stop yet gets a `wait-aborted` record in the observe stream.
+   */
+  signal?: AbortSignal;
+}
+/**
+ * Withdraws the registrations and invocations of the container, disposes the child containers, and runs the container effects in reverse order.
+ *
+ * One error keeps its identity. More than one error becomes an `AggregateError`. A second call from outside without a signal gets the same promise.
+ *
+ * A call from the cleanup chain of the container or of a descendant cannot wait, because the disposal waits for that cleanup.
+ * The same is true for a cleanup of a service that holds a service of the subtree, directly or through other instances, or a consumer service of a `perConsumer` registration of 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 at once. The disposal continues.
+ *
+ * When `options.signal` aborts, the call rejects with the reason and stops waiting. The disposal continues: the container stays in `disposing`, and calls on it fail with `build-after-dispose`.
+ * A later `dispose()` waits for the same disposal and gets its result. An aborted signal starts the disposal, then rejects at once.
+ */
+declare function dispose(container: Container, options?: DisposeOptions): Promise<void>;
+/**
+ * Registers an invocation: a service without a value. The callback runs when the required dependencies are available.
+ * Before `start()`, it waits for `start()`.
+ */
+declare function invoke$1<Deps extends DependencyDeclarations>(container: Container, option: InvokeOptionWithKeys<Deps>): InvocationHandle;
+declare function invoke$1<D extends DependencyMap>(container: Container, option: InvokeOption<D>): InvocationHandle;
+type KeyLike<T = unknown> = ProvidedKey<string, T, DependencyMap | undefined> | ProvidedBy<T>;
+/**
+ * Creates a typed key without a provider. A consumer can depend on it now. `provide(key, ...)` registers a provider later.
+ *
+ * With `options.exclusive`, the key can have only one provider in its resolution area. Two or more providers all go to `conflict`.
+ */
+declare function defineKey<T>(name: string, options?: KeyOptions): ProvidedKey<string, T, undefined>;
+/**
+ * Marks a fallback dependency. It resolves to the first provider in the list whose effective status is available.
+ *
+ * A change of the selection is a change of identity: the dependent gets `dependency-change`.
+ * It is required, unless it is wrapped in `optional()`.
+ * A `where(key, condition)` marker in the list filters that candidate only. `where(firstAvailable(...), condition)` filters each candidate.
+ * The selection is the first available candidate that passes its conditions.
+ */
+declare function firstAvailable<const Keys extends readonly (KeyLike | ConditionalDependency<unknown>)[]>(...keys: Keys): FallbackDependency<InferProvided<Keys[number]>>;
+/**
+ * Marks an optional dependency. The dependent gets `{ value, status }`, or `undefined` when no provider runs.
+ * It also accepts a `firstAvailable` marker and a `where` marker, with their conditions.
+ */
+declare function optional<T>(dependency: KeyLike<T> | FallbackDependency<T> | ConditionalDependency<T>): OptionalDependency<T>;
+/**
+ * Adds a resolution condition to a dependency. The condition gets the key, the owner, and the metadata of the provider.
+ *
+ * If it returns `false`, the dependency does not resolve. A required dependency keeps the dependent `pending`. An optional one is `undefined`.
+ * The condition must be pure and synchronous. A thrown error counts as `false` and goes to the observe stream.
+ * Wrap the result in `optional()`, or pass an `optional()` marker, to combine the two.
+ *
+ * For a `firstAvailable` marker, the condition filters each candidate. The selection is the first available candidate that passes.
+ * A candidate that `firstAvailable(where(key, other), ...)` filters must pass both conditions.
+ */
+declare function where<T>(dependency: OptionalDependency<T>, condition: ResolutionCondition): OptionalDependency<T>;
+declare function where<T>(dependency: FallbackDependency<T>, condition: ResolutionCondition): FallbackDependency<T>;
+declare function where<T>(dependency: KeyLike<T>, condition: ResolutionCondition): ConditionalDependency<T>;
+interface StartOptions {
+  /**
+   * Ends the wait when the signal aborts. The services keep converging.
+   * A timeout reason (`name === 'TimeoutError'`) rejects with `start-timeout` and the explanations. Another reason rejects as it is. There is no default.
+   */
+  signal?: AbortSignal;
+}
+interface StopOptions {
+  /**
+   * Ends the wait when the signal aborts, and rejects with the reason. The cleanups that did not settle keep running.
+   * Each service that did not stop yet gets a `wait-aborted` record in the observe stream. There is no default.
+   */
+  signal?: AbortSignal;
+}
+/**
+ * Begins convergence of the container and of each child container that was started.
+ *
+ * Resolves when all their services and invocations are `running`. Rejects with the build and start errors.
+ * A service in `failed` tries again. A required key without a provider keeps the promise pending, unless `options.signal` aborts.
+ * A child container that was never started does not start. Call `start(child)` for it.
+ */
+declare function start$1(container: Container, options?: StartOptions): Promise<void>;
+/**
+ * Stops all instances of the container and of each child container that was started. Dependents stop before their providers.
+ *
+ * The registrations stay. The container stays usable, and a later `start()` builds them again. `dispose()` clears the container.
+ * Rejects with the teardown errors.
+ *
+ * When `options.signal` aborts, it rejects with the reason and stops waiting. The container stays stopped: a later `start()` builds again.
+ * The services that did not stop yet stay in `stopping` until their cleanups settle.
+ *
+ * A call from the cleanup chain of the container or of a descendant cannot wait, because the stop waits for that cleanup.
+ * The same is true for a cleanup of a service that holds a service of the subtree, directly or through other instances.
+ * 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 at once. The stop continues.
+ */
+declare function stop$1(container: Container, options?: StopOptions): Promise<void>;
+/**
+ * Stores a listener for `eventKey`. The container owns it: `dispose(container)` removes it.
+ *
+ * injeca does not call the listener. The consumer reads the listeners with `listeners()` and runs them by its own rules.
+ * Returns a function that removes the listener.
+ */
+declare function listen<H extends (...args: never[]) => unknown>(container: Container, eventKey: EventKey, handler: H, metadata?: ListenerMetadata): () => void;
+/**
+ * Registers a provider and returns its typed key with `withdraw()` and `replace()`.
+ *
+ * Before `start()`, a second provide of the same name replaces the first registration. After `start()`, it throws `duplicate-service`.
+ * After `start()`, a new service builds and starts when its dependencies are available.
+ */
+declare function provide$1<T, Key extends string, Deps extends DependencyDeclarations>(container: Container, name: Key, option: ProvideOptionWithKeys<T, Deps>): Registration<Key, T, ResolveDependencyDeclaration<Deps>>;
+declare function provide$1<T, Key extends string, Deps extends DependencyDeclarations>(container: Container, option: ProvideOptionWithKeys<T, Deps> & {
+  autoNameStackIndex?: number;
+}): Registration<Key, T, ResolveDependencyDeclaration<Deps>>;
+declare function provide$1<D extends DependencyMap | undefined, T = any, Key extends string = string>(container: Container, name: Key, option: ProvideOption<T, D>): Registration<Key, T, D>;
+declare function provide$1<D extends DependencyMap | undefined, T = any, Key extends string = string>(container: Container, option: ProvideOption<T, D> & {
+  autoNameStackIndex?: number;
+}): Registration<Key, T, D>;
+declare function provide$1<T, Key extends string, Deps extends DependencyDeclarations>(container: Container, key: ProvidedKey<Key, T, DependencyMap | undefined>, option: ProvideOptionWithKeys<NoInfer<T>, Deps>): Registration<Key, T, ResolveDependencyDeclaration<Deps>>;
+declare function provide$1<T, Key extends string>(container: Container, key: ProvidedKey<Key, T, DependencyMap | undefined>, option: ProvideOption<NoInfer<T>, undefined>): Registration<Key, T, undefined>;
+interface ResolveOptions {
+  /**
+   * Ends the wait when the signal aborts. A timeout reason (`name === 'TimeoutError'`) rejects with `wait-timeout`, with the reason as `cause`.
+   * Another reason rejects as it is. Use `timeout(container, ms)` for a timeout on the container clock. There is no default.
+   */
+  signal?: AbortSignal;
+}
+/**
+ * Waits until the dependencies are available and returns their values. Before `start()`, it builds and starts them.
+ *
+ * Rejects when a required dependency fails. With `options.signal`, it rejects when the signal aborts. An aborted signal rejects at once.
+ * Each rejection removes the hidden resolver of the call. The values can become stale after a run-time change. Use it for one-time code.
+ */
+declare function resolve$1<Deps extends DependencyDeclarations>(container: Container, dependsOn: Deps, options?: ResolveOptions): Promise<ResolveDependencyDeclaration<Deps>>;
+/**
+ * Returns a signal that aborts after `ms` milliseconds of the clock of `container`.
+ *
+ * The reason is a `DOMException` with the name `TimeoutError`, as for `AbortSignal.timeout()`. Use it in place of `AbortSignal.timeout()`, because that one does not use the container clock.
+ * With the system clock, the timer does not keep a Node process alive.
+ */
+declare function timeout(container: Container, ms: number): AbortSignal;
+/** Returns a signal that aborts when `signal` aborts, or after `ms` milliseconds of the clock of `container`. Without `signal`, it is `timeout(container, ms)`. */
+declare function withTimeout(signal: AbortSignal | undefined, ms: number, container: Container): AbortSignal;
+/**
+ * Creates a transaction for `container`.
+ *
+ * `declare` reserves services. `provide` and `replace` add services. Nothing is visible to consumers before `commit()`.
+ * `commit()` builds the services in dependency order and publishes them in one batch. Then the `start` hooks run.
+ * A failed build publishes nothing. A disposal of the container during the transaction aborts it.
+ */
+declare function transaction(container: Container): Transaction;
+/**
+ * Returns the graph queries of `container`. They cover the container and its descendants. Each query is a pure read.
+ *
+ * A key resolves as for a consumer in the container: from the container and the exports of its children, then from each ancestor and the exports of its children.
+ * A key that only a descendant has resolves to the first such service.
+ */
+declare function graph(container: Container): Graph;
+/**
+ * Reads the value of a dependency now, without a wait. It is a pure read: it does not demand, build, or start a service.
+ *
+ * The dependency resolves as for a consumer in `container`: a key, `where(key, condition)`, or `firstAvailable(...)`. An `optional` marker has no effect.
+ * The result is the value with its status, or the reason why no value is available now. A `perConsumer` key has a value only after something demanded its service for `container`.
+ */
+declare function peek<D extends PeekDependency>(container: Container, dependency: D): PeekResult<PeekValue<D>>;
+/**
+ * Returns the current listeners for `eventKey` in `container` and its descendants, in registration order.
+ *
+ * Each entry has the handler, the owner record of the container that owns it, and its metadata.
+ * `H` is the handler type that the caller expects. injeca does not check it.
+ */
+declare function listeners<H = (...args: never[]) => unknown>(container: Container, eventKey: EventKey): readonly ListenerEntry<H>[];
+declare function setLogger(logger: Logger): void;
+/** Returns the root container of the global functions. Pass it as `parent` to make a child container. */
+declare function getContainer(): Container;
+/** Replaces the global container with a new one. `getContainer()` then returns the new one. It does not stop or dispose the old container. */
+declare function resetContainer(): void;
+declare function provide<T, Key extends string, Deps extends DependencyDeclarations>(name: Key, option: ProvideOptionWithKeys<T, Deps>): Registration<Key, T, ResolveDependencyDeclaration<Deps>>;
+declare function provide<D extends DependencyMap | undefined, T = any, Key extends string = string>(name: Key, option: ProvideOption<T, D>): Registration<Key, T, D>;
+declare function provide<T, Key extends string, Deps extends DependencyDeclarations>(option: ProvideOptionWithKeys<T, Deps>): Registration<Key, T, ResolveDependencyDeclaration<Deps>>;
+declare function provide<D extends DependencyMap | undefined, T = any, Key extends string = string>(option: ProvideOption<T, D>): Registration<Key, T, D>;
+declare function provide<T, Key extends string, Deps extends DependencyDeclarations>(key: ProvidedKey<Key, T, DependencyMap | undefined>, option: ProvideOptionWithKeys<NoInfer<T>, Deps>): Registration<Key, T, ResolveDependencyDeclaration<Deps>>;
+declare function provide<T, Key extends string>(key: ProvidedKey<Key, T, DependencyMap | undefined>, option: ProvideOption<NoInfer<T>, undefined>): Registration<Key, T, undefined>;
+declare function invoke<Deps extends DependencyDeclarations>(option: InvokeOptionWithKeys<Deps>): InvocationHandle;
+declare function invoke<D extends DependencyMap>(option: InvokeOption<D>): InvocationHandle;
+declare function resolve<Deps extends DependencyDeclarations>(dependsOn: Deps, options?: ResolveOptions): Promise<ResolveDependencyDeclaration<Deps>>;
+declare function start(options?: StartOptions): Promise<void>;
+declare function stop(options?: StopOptions): Promise<void>;
+export { dispose as A, defineKey as C, invoke$1 as D, where as E, EventKey as M, ListenerEntry as N, DisposeOptions as O, ListenerMetadata as P, stop$1 as S, optional as T, provide$1 as _, resolve as a, StopOptions as b, stop as c, graph as d, transaction as f, resolve$1 as g, ResolveOptions as h, resetContainer as i, effect$1 as j, createContainer as k, listeners as l, withTimeout as m, invoke as n, setLogger as o, timeout as p, provide as r, start as s, getContainer as t, peek as u, listen as v, firstAvailable as w, start$1 as x, StartOptions as y };
+//# sourceMappingURL=global-DPfe26g5.d.mts.map

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-DPfe26g5.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-B5N-d-TO.mjs";