di-bag 0.2.0 → 0.3.0

package/docs/agent/api-card.md

@@ -0,0 +1,337 @@
+<!-- Generated by npm run docs:generate from JSDoc in src/ and tools/docs/api-card-tasks.json. Do not edit. -->
+
+# API card {#api-card}
+
+Every runtime call of `di-bag`: its summary, the codes it can raise, and an example that type-checks.
+An example without an import line uses `import { DiBag } from 'di-bag';`. The rules are in
+[AGENTS.md](../../AGENTS.md); each code links to its section in [errors.md](errors.md).
+
+## One way per task {#one-way-per-task}
+
+| Task | Call |
+| --- | --- |
+| Start a graph | [`DiBag.createBuilder()`](#dibag-createbuilder) |
+| Register a service | [`builder.register(more)`](#builder-register) |
+| Attach cleanup | [`DiBag.withDisposal(create, dispose)`](#dibag-withdisposal) |
+| Choose a lifetime | [`DiBag.withLifetime(registration, lifetime)`](#dibag-withlifetime) |
+| Seal a module | [`builder.buildModule(keys, options?)`](#builder-buildmodule) |
+| Install a module | [`builder.installModule(module)`](#builder-installmodule) |
+| Check the graph on its own line | [`builder.verifyGraph()`](#builder-verifygraph) |
+| Build a bag | [`builder.build()`](#builder-build) |
+| Replace for a test | [`bag.fork(keys, overrides)`](#bag-fork) |
+| Open a scope | [`bag.createScope()`](#bag-createscope) |
+| Resolve | [`bag.resolve(token)`](#bag-resolve) |
+| Close | [`bag.close(options?)`](#bag-close) |
+
+## DiBag facade {#dibag-facade}
+
+### `DiBag.withConfiguration(options)` {#dibag-withconfiguration}
+Return a facade with inherited runtime settings and appended observers. Throws: [`DI_BAG_INVALID_CONFIGURATION`](errors.md#di-bag-invalid-configuration).
+```ts
+const Observed = DiBag.withConfiguration({
+  observers: [{ onEvent: event => console.log(event.kind), onError: failure => console.error(failure.error) }],
+});
+```
+
+### `DiBag.fromFactory(callback, options)` {#dibag-fromfactory}
+Describe a named-dependency factory with an explicit acquisition mode or the acquisition's abort signal. Throws: [`DI_BAG_INVALID_FACTORY`](errors.md#di-bag-invalid-factory), [`DI_BAG_INVALID_ACQUISITION_MODE`](errors.md#di-bag-invalid-acquisition-mode).
+```ts
+type Query = { then(done: (rows: string[]) => void): void };
+const query = DiBag.fromFactory((): Query => ({ then: done => done([]) }), { acquisitionMode: 'raw' });
+```
+
+### `DiBag.token(key)` {#dibag-token}
+Create a typed token from a unique symbol; `.of<Service>()` fixes its service type. Throws: [`DI_BAG_INVALID_TOKEN`](errors.md#di-bag-invalid-token).
+```ts
+const clockKey = Symbol('clock');
+const clock = DiBag.token(clockKey).of<{ now(): number }>();
+```
+
+### `DiBag.optional(token)` {#dibag-optional}
+Create a positional dependency that yields `undefined` only when the token is unregistered. Throws: [`DI_BAG_INVALID_TOKEN`](errors.md#di-bag-invalid-token).
+```ts
+const clockKey = Symbol('clock');
+const clock = DiBag.token(clockKey).of<{ now(): number }>();
+const stamp = DiBag.fromFunction([DiBag.optional(clock)], source => source?.now() ?? 0);
+```
+
+### `DiBag.lazy(token)` {#dibag-lazy}
+Create a positional dependency supplied as a function that resolves the token when called. Throws: [`DI_BAG_INVALID_TOKEN`](errors.md#di-bag-invalid-token).
+```ts
+const clockKey = Symbol('clock');
+const clock = DiBag.token(clockKey).of<{ now(): number }>();
+const stamp = DiBag.fromFunction([DiBag.lazy(clock)], getClock => () => getClock().now());
+```
+
+### `DiBag.all(token)` {#dibag-all}
+Create a positional dependency containing every contribution to a collection token, in order. Throws: [`DI_BAG_INVALID_TOKEN`](errors.md#di-bag-invalid-token).
+```ts
+const toolsKey = Symbol('tools');
+const tools = DiBag.token(toolsKey).of<string>();
+const menu = DiBag.fromFunction([DiBag.all(tools)], names => names.join(', '));
+```
+
+### `DiBag.fromPlugin(dependencies, plugin, options)` {#dibag-fromplugin}
+Validate an unknown plugin descriptor now and its acquired output at acquisition. Throws: [`DI_BAG_INVALID_TOKEN`](errors.md#di-bag-invalid-token), [`DI_BAG_INVALID_PLUGIN_OPTIONS`](errors.md#di-bag-invalid-plugin-options), [`DI_BAG_PLUGIN_VALIDATION`](errors.md#di-bag-plugin-validation).
+```ts
+declare const descriptor: unknown;
+const greeter = DiBag.fromPlugin([], descriptor, {
+  acquisitionMode: 'raw',
+  validate: (value): value is () => string => typeof value === 'function',
+});
+```
+
+### `DiBag.fromFunction(tokens, callback, ...modeOptions)` {#dibag-fromfunction}
+Adapt a positional function whose parameters receive the listed tokens' services. Throws: [`DI_BAG_INVALID_TOKEN`](errors.md#di-bag-invalid-token), [`DI_BAG_INVALID_FUNCTION`](errors.md#di-bag-invalid-function), [`DI_BAG_INVALID_ACQUISITION_MODE`](errors.md#di-bag-invalid-acquisition-mode).
+```ts
+const clockKey = Symbol('clock');
+const clock = DiBag.token(clockKey).of<{ now(): number }>();
+const stamp = DiBag.fromFunction([clock], source => new Date(source.now()).toISOString());
+```
+
+### `DiBag.fromClass(tokens, constructor, ...modeOptions)` {#dibag-fromclass}
+Adapt a class whose constructor parameters receive the listed tokens' services. Throws: [`DI_BAG_INVALID_TOKEN`](errors.md#di-bag-invalid-token), [`DI_BAG_INVALID_CONSTRUCTOR`](errors.md#di-bag-invalid-constructor), [`DI_BAG_INVALID_ACQUISITION_MODE`](errors.md#di-bag-invalid-acquisition-mode).
+```ts
+class Greeter { constructor(readonly greeting: string) {} }
+const greetingKey = Symbol('greeting');
+const greeter = DiBag.fromClass([DiBag.token(greetingKey).of<string>()], Greeter);
+```
+
+### `DiBag.createBuilder()` {#dibag-createbuilder}
+Begin an empty immutable graph; `build` creates its owning bag, `buildModule` seals a reusable module.
+```ts
+const bag = DiBag.createBuilder().register({ greeting: () => 'hello' }).build();
+```
+
+### `DiBag.withDisposal(create, dispose)` {#dibag-withdisposal}
+Make the bag own a factory's value and run `dispose` on it when the bag closes. Throws: [`DI_BAG_INVALID_REGISTRATION`](errors.md#di-bag-invalid-registration).
+```ts
+const bag = DiBag.createBuilder()
+  .register({ controller: DiBag.withDisposal(() => new AbortController(), controller => controller.abort()) })
+  .build();
+await bag.close();
+```
+
+### `DiBag.withLifetime(registration, lifetime)` {#dibag-withlifetime}
+Select `root`, `scoped` (the default), or `transient` caching for a registration. Throws: [`DI_BAG_INVALID_LIFETIME`](errors.md#di-bag-invalid-lifetime), [`DI_BAG_INVALID_REGISTRATION`](errors.md#di-bag-invalid-registration).
+```ts
+const bag = DiBag.createBuilder()
+  .register({ cache: DiBag.withLifetime(() => new Map<string, string>(), 'root') })
+  .build();
+```
+
+### `DiBag.withMetadata(registration, options)` {#dibag-withmetadata}
+Attach static registration metadata, or per-acquisition metadata in direct or awaited mode. Throws: [`DI_BAG_INVALID_METADATA`](errors.md#di-bag-invalid-metadata), [`DI_BAG_DUPLICATE_METADATA`](errors.md#di-bag-duplicate-metadata), [`DI_BAG_INVALID_REGISTRATION`](errors.md#di-bag-invalid-registration).
+```ts
+const greeting = DiBag.withMetadata(() => 'hello', { static: { owner: 'greeting' } });
+```
+
+### `DiBag.transformService(registration, options)` {#dibag-transformservice}
+Transform the exposed service while retaining dependencies, metadata, lifetime, and existing ownership. Throws: [`DI_BAG_INVALID_TRANSFORM`](errors.md#di-bag-invalid-transform), [`DI_BAG_INVALID_ACQUISITION_MODE`](errors.md#di-bag-invalid-acquisition-mode), [`DI_BAG_INVALID_REGISTRATION`](errors.md#di-bag-invalid-registration).
+```ts
+const shout = DiBag.transformService(() => 'hello', { mode: 'direct', transform: text => text.toUpperCase() });
+```
+
+## Builder {#builder}
+
+### `builder.register(more)` {#builder-register}
+Add new string-named registrations. Throws: [`DI_BAG_INVALID_REGISTRATION`](errors.md#di-bag-invalid-registration), [`DI_BAG_DUPLICATE_REGISTRATION`](errors.md#di-bag-duplicate-registration), [`DI_BAG_INVALID_TOKEN`](errors.md#di-bag-invalid-token).
+```ts
+type Clock = { now(): number };
+const builder = DiBag.createBuilder()
+  .register({ clock: (): Clock => ({ now: () => Date.now() }) })
+  .register({ stamp: ({ clock }: { clock: Clock }) => clock.now() });
+```
+
+### `builder.alias(destination, target)` {#builder-alias}
+Add another lookup name or token for an existing service. Throws: [`DI_BAG_INVALID_TOKEN`](errors.md#di-bag-invalid-token), [`DI_BAG_DUPLICATE_REGISTRATION`](errors.md#di-bag-duplicate-registration), [`DI_BAG_INVALID_ALIAS`](errors.md#di-bag-invalid-alias).
+```ts
+const builder = DiBag.createBuilder().register({ clock: () => Date.now() }).alias('now', 'clock');
+```
+
+### `builder.contribute(token, registration)` {#builder-contribute}
+Append a provider to a typed-token collection. Throws: [`DI_BAG_INVALID_TOKEN`](errors.md#di-bag-invalid-token), [`DI_BAG_INVALID_REGISTRATION`](errors.md#di-bag-invalid-registration).
+```ts
+const toolsKey = Symbol('tools');
+const tools = DiBag.token(toolsKey).of<string>();
+const builder = DiBag.createBuilder().contribute(tools, () => 'search').contribute(tools, () => 'fetch');
+```
+
+### `builder.replace(key, registration)` {#builder-replace}
+Replace an existing string-named registration with a dependency-free factory. Throws: [`DI_BAG_INVALID_REPLACEMENT`](errors.md#di-bag-invalid-replacement), [`DI_BAG_INVALID_REGISTRATION`](errors.md#di-bag-invalid-registration), [`DI_BAG_INVALID_TOKEN`](errors.md#di-bag-invalid-token).
+```ts
+const builder = DiBag.createBuilder().register({ clock: () => Date.now() }).replace('clock', () => 0);
+```
+
+### `builder.installModule(module)` {#builder-installmodule}
+Install a sealed module, allocating fresh private bindings for this installation. Throws: [`DI_BAG_INVALID_MODULE`](errors.md#di-bag-invalid-module), [`DI_BAG_DUPLICATE_REGISTRATION`](errors.md#di-bag-duplicate-registration).
+```ts
+const greeting = DiBag.createBuilder()
+  .register({ greet: ({ name }: { name: string }) => `hello, ${name}` })
+  .buildModule(['greet']);
+const bag = DiBag.createBuilder().installModule(greeting).register({ name: () => 'Ada' }).build();
+```
+
+### `builder.verifyGraph()` {#builder-verifygraph}
+Report at the type level why this graph would not build; the runtime call does nothing.
+```ts
+const builder = DiBag.createBuilder().register({ greeting: () => 'hello' });
+builder.verifyGraph() satisfies void;
+```
+
+### `builder.buildModule(keys, options?)` {#builder-buildmodule}
+Seal this graph as a reusable module and select its public names and typed tokens. Throws: [`DI_BAG_INVALID_EXPORT`](errors.md#di-bag-invalid-export), [`DI_BAG_INVALID_TOKEN`](errors.md#di-bag-invalid-token).
+```ts
+const orders = DiBag.createBuilder()
+  .register({ repository: () => new Map<string, number>() })
+  .register({ placeOrder: ({ repository }: { repository: Map<string, number> }) => (id: string) => repository.set(id, 1) })
+  .buildModule(['placeOrder'], { label: 'orders' });
+// Errors and inspectGraph() name the private binding 'orders/repository'.
+const app = DiBag.createBuilder().installModule(orders).build();
+```
+
+### `builder.build()` {#builder-build}
+Finish a complete graph as a lazy bag. Throws: [`DI_BAG_CLASSIFIER_REQUIRED`](errors.md#di-bag-classifier-required).
+```ts
+const bag = DiBag.createBuilder().register({ greeting: () => 'hello' }).build();
+await bag.close();
+```
+
+### `builder.buildAndStart(keys, options?)` {#builder-buildandstart}
+Create a fresh bag and acquire selected services before returning it. Throws: [`DI_BAG_STARTUP_FAILED`](errors.md#di-bag-startup-failed), [`DI_BAG_STARTUP_CANCELLED`](errors.md#di-bag-startup-cancelled), [`DI_BAG_INVALID_STARTUP`](errors.md#di-bag-invalid-startup), [`DI_BAG_INVALID_TOKEN`](errors.md#di-bag-invalid-token), [`DI_BAG_CLASSIFIER_REQUIRED`](errors.md#di-bag-classifier-required).
+```ts
+const bag = await DiBag.createBuilder()
+  .register({ db: async () => ({ ping: () => true }) })
+  .buildAndStart(['db'], { timeoutMs: 5_000 });
+```
+
+## Bag {#bag}
+
+### `bag.resolve(token)` {#bag-resolve}
+Resolve a named or typed-token service, acquiring it lazily when needed. Throws: [`DI_BAG_CLOSING`](errors.md#di-bag-closing), [`DI_BAG_CLOSED`](errors.md#di-bag-closed), [`DI_BAG_INVALID_TOKEN`](errors.md#di-bag-invalid-token), [`DI_BAG_MISSING_REGISTRATION`](errors.md#di-bag-missing-registration), [`DI_BAG_MISSING_DEPENDENCY`](errors.md#di-bag-missing-dependency), [`DI_BAG_CYCLE`](errors.md#di-bag-cycle), [`DI_BAG_LIFETIME_DEPENDENCY`](errors.md#di-bag-lifetime-dependency), [`DI_BAG_INVALID_DEPENDENCY_ACCESS`](errors.md#di-bag-invalid-dependency-access), [`DI_BAG_STRUCTURAL_THENABLE`](errors.md#di-bag-structural-thenable), [`DI_BAG_INVALID_CLASSIFIER_RESULT`](errors.md#di-bag-invalid-classifier-result), [`DI_BAG_INVALID_METADATA`](errors.md#di-bag-invalid-metadata), [`DI_BAG_PLUGIN_VALIDATION`](errors.md#di-bag-plugin-validation).
+```ts
+const bag = DiBag.createBuilder().register({ greeting: () => 'hello' }).build();
+const greeting: string = bag.resolve('greeting');
+```
+
+### `bag.resolveAll(token)` {#bag-resolveall}
+Resolve every contribution for a typed token in declaration and installation order. Throws: [`DI_BAG_CLOSING`](errors.md#di-bag-closing), [`DI_BAG_CLOSED`](errors.md#di-bag-closed), [`DI_BAG_INVALID_TOKEN`](errors.md#di-bag-invalid-token).
+```ts
+const toolsKey = Symbol('tools');
+const tools = DiBag.token(toolsKey).of<string>();
+const bag = DiBag.createBuilder().contribute(tools, () => 'search').contribute(tools, () => 'fetch').build();
+const names: readonly string[] = bag.resolveAll(tools);
+```
+
+### `bag.inspectAll(token)` {#bag-inspectall}
+Inspect every contribution for a token without running its factories. Throws: [`DI_BAG_INVALID_TOKEN`](errors.md#di-bag-invalid-token).
+```ts
+const toolsKey = Symbol('tools');
+const tools = DiBag.token(toolsKey).of<string>();
+const bag = DiBag.createBuilder().contribute(tools, () => 'search').build();
+const labels = bag.inspectAll(tools).map(snapshot => snapshot.label);
+```
+
+### `bag.inspect(token)` {#bag-inspect}
+Inspect static metadata and copied acquisition state without resolving a service. Throws: [`DI_BAG_INVALID_TOKEN`](errors.md#di-bag-invalid-token), [`DI_BAG_MISSING_REGISTRATION`](errors.md#di-bag-missing-registration), [`DI_BAG_CYCLE`](errors.md#di-bag-cycle).
+```ts
+const bag = DiBag.createBuilder().register({ greeting: () => 'hello' }).build();
+const acquired = bag.inspect('greeting').acquisitions.length;
+```
+
+### `bag.inspectGraph()` {#bag-inspectgraph}
+Describe every binding this bag can resolve and the dependency edges observed so far.
+```ts
+const bag = DiBag.createBuilder().register({ greeting: () => 'hello' }).build();
+const labels = bag.inspectGraph().bindings.map(binding => binding.label);
+```
+
+### `bag.createScope()` {#bag-createscope}
+Create a tracked child with the same graph and fresh scoped acquisitions. Throws: [`DI_BAG_INVALID_SCOPE`](errors.md#di-bag-invalid-scope), [`DI_BAG_INVALID_TOKEN`](errors.md#di-bag-invalid-token), [`DI_BAG_CLOSING`](errors.md#di-bag-closing), [`DI_BAG_CLOSED`](errors.md#di-bag-closed), [`DI_BAG_INVALID_REGISTRATION`](errors.md#di-bag-invalid-registration), [`DI_BAG_CLASSIFIER_REQUIRED`](errors.md#di-bag-classifier-required).
+```ts
+const app = DiBag.createBuilder().register({ requestId: () => Math.random() }).build();
+const request = app.createScope();
+const id: number = request.resolve('requestId');
+await request.close();
+```
+
+### `bag.fork(keys, overrides)` {#bag-fork}
+Create an independent bag with selected replacements, the way tests substitute dependencies. Throws: [`DI_BAG_CLOSING`](errors.md#di-bag-closing), [`DI_BAG_CLOSED`](errors.md#di-bag-closed), [`DI_BAG_INVALID_OVERRIDE`](errors.md#di-bag-invalid-override), [`DI_BAG_INVALID_TOKEN`](errors.md#di-bag-invalid-token), [`DI_BAG_INVALID_REGISTRATION`](errors.md#di-bag-invalid-registration), [`DI_BAG_CLASSIFIER_REQUIRED`](errors.md#di-bag-classifier-required).
+```ts
+type Clock = { now(): number };
+const app = DiBag.createBuilder().register({ clock: (): Clock => ({ now: () => Date.now() }) }).build();
+const test = app.fork(['clock'], { clock: (): Clock => ({ now: () => 0 }) });
+await test.close();
+```
+
+### `bag.close(options?)` {#bag-close}
+Close this bag, drain in-flight work, and dispose owned resources once. Throws: [`DI_BAG_CLEANUP_FAILED`](errors.md#di-bag-cleanup-failed), [`DI_BAG_CLOSE_FAILED`](errors.md#di-bag-close-failed), [`DI_BAG_CLOSE_TIMEOUT`](errors.md#di-bag-close-timeout), [`DI_BAG_CLOSE_ABORTED`](errors.md#di-bag-close-aborted), [`DI_BAG_INVALID_CLOSE`](errors.md#di-bag-invalid-close).
+```ts
+const bag = DiBag.createBuilder().register({ value: () => 1 }).build();
+await bag.close({ timeoutMs: 10_000, signal: AbortSignal.timeout(15_000) });
+```
+
+## Errors {#errors}
+
+### `DiBagPluginValidationError` {#dibagpluginvalidationerror}
+A plugin descriptor or its acquired output failed validation at the checked plugin boundary. Code: [`DI_BAG_PLUGIN_VALIDATION`](errors.md#di-bag-plugin-validation).
+```ts
+import { DiBag, DiBagPluginValidationError } from 'di-bag';
+
+try {
+  DiBag.fromPlugin([], { apiVersion: 2 }, { acquisitionMode: 'raw', validate: (value): value is string => typeof value === 'string' });
+} catch (error) {
+  if (error instanceof DiBagPluginValidationError) console.error(error.phase, error.reason);
+}
+```
+
+### `DiBagCleanupError` {#dibagcleanuperror}
+One or more disposers failed during `close()`; every cleanup was still attempted. Code: [`DI_BAG_CLEANUP_FAILED`](errors.md#di-bag-cleanup-failed).
+```ts
+import { DiBag, DiBagCleanupError } from 'di-bag';
+
+const bag = DiBag.createBuilder().register({ value: () => 1 }).build();
+await bag.close().catch((error: unknown) => {
+  if (error instanceof DiBagCleanupError) for (const failure of error.failures) console.error(failure.label, failure.error);
+});
+```
+
+### `DiBagStartupError` {#dibagstartuperror}
+`buildAndStart` failed to acquire a selected service; the new bag has already released its resources. Code: [`DI_BAG_STARTUP_FAILED`](errors.md#di-bag-startup-failed).
+```ts
+import { DiBag, DiBagStartupError } from 'di-bag';
+
+const builder = DiBag.createBuilder().register({ db: async (): Promise<number> => { throw new Error('offline'); } });
+try {
+  await builder.buildAndStart(['db']);
+} catch (error) {
+  if (error instanceof DiBagStartupError) console.error(error.cause, error.cleanupFailures);
+}
+```
+
+### `DiBagStartupCancelledError` {#dibagstartupcancellederror}
+`buildAndStart` stopped waiting on abort or timeout; `cleanupPromise` settles when the partial bag is released. Code: [`DI_BAG_STARTUP_CANCELLED`](errors.md#di-bag-startup-cancelled).
+```ts
+import { DiBag, DiBagStartupCancelledError } from 'di-bag';
+
+const builder = DiBag.createBuilder().register({ db: () => new Promise<number>(() => {}) });
+try {
+  await builder.buildAndStart(['db'], { timeoutMs: 1_000 });
+} catch (error) {
+  if (error instanceof DiBagStartupCancelledError) await error.cleanupPromise;
+}
+```
+
+### `DiBagCloseCancelledError` {#dibagclosecancellederror}
+A `close({ timeoutMs, signal })` wait stopped before cleanup finished; cleanup keeps running. Code: [`DI_BAG_CLOSE_TIMEOUT`](errors.md#di-bag-close-timeout), [`DI_BAG_CLOSE_ABORTED`](errors.md#di-bag-close-aborted).
+```ts
+import { DiBag, DiBagCloseCancelledError } from 'di-bag';
+
+const bag = DiBag.createBuilder().register({ value: () => 1 }).build();
+try {
+  await bag.close({ timeoutMs: 5_000 });
+} catch (error) {
+  if (error instanceof DiBagCloseCancelledError) console.error(error.details.pending);
+  throw error;
+}
+```