di-bag 0.1.0

package/dist/dependency-references.d.ts

@@ -0,0 +1,52 @@
+import type { TokenBase, TokenService } from './tokens';
+import type { TokenTupleAdmission, ValidToken } from './token-types';
+declare const referenceInvariant: unique symbol;
+declare class ReferenceBase {
+    private readonly nominal;
+}
+declare class DependencyHandle<T extends TokenBase, K extends 'optional' | 'lazy' | 'all'> extends ReferenceBase {
+    readonly [referenceInvariant]: (value: [T, K]) => [T, K];
+}
+/** A positional dependency that yields the token service or `undefined` when unbound. */
+export type OptionalDependency<T extends TokenBase> = DependencyHandle<T, 'optional'>;
+/** A positional dependency that yields all contributions for a token as a readonly array. */
+export type CollectionDependency<T extends TokenBase> = DependencyHandle<T, 'all'>;
+/** A positional dependency that yields a function which resolves the token on demand. */
+export type LazyDependency<T extends TokenBase> = DependencyHandle<T, 'lazy'>;
+/** A typed token or one of the positional dependency-reference handles. */
+export type DependencyReference = TokenBase | ReferenceBase;
+type ReferenceParts<R> = R extends {
+    readonly [referenceInvariant]: (...args: never[]) => [infer T extends TokenBase, infer K];
+} ? [T, K] : never;
+export type DependencyToken<R> = R extends TokenBase ? R : ReferenceParts<R>[0];
+export type DependencyKind<R> = R extends TokenBase ? 'required' : ReferenceParts<R>[1];
+export type DependencyValue<R> = R extends TokenBase ? TokenService<R> : ReferenceParts<R> extends [infer T, infer K] ? K extends 'optional' ? TokenService<T> | undefined : K extends 'lazy' ? () => TokenService<T> : K extends 'all' ? ReadonlyArray<TokenService<T>> : never : never;
+export type ValidDependency<R> = [R] extends [never] ? false : ValidToken<R> extends true ? true : R extends ReferenceBase ? ValidToken<DependencyToken<R>> : false;
+export interface ArgumentReference {
+    readonly slot: symbol;
+    readonly key: symbol;
+    readonly kind: 'required' | 'optional' | 'lazy' | 'all';
+}
+/**
+ * Describe a positional dependency that supplies `undefined` only when the token is unbound.
+ * A present `undefined` value and acquisition failures remain present dependency results.
+ * @param token - The genuine typed token to read optionally.
+ * @returns An immutable reference accepted by positional provider adapters.
+ */
+export declare function optional<T extends TokenBase>(token: T & TokenTupleAdmission<readonly [T]>, ...invalid: [T] extends [never] ? [TokenTupleAdmission<readonly [T]>] : []): OptionalDependency<T>;
+/**
+ * Describe a positional dependency supplied as an on-demand lookup function.
+ * Each invocation follows the target lifetime and records its dependency edge then.
+ * @param token - The genuine typed token to resolve lazily.
+ * @returns An immutable lazy reference accepted by positional provider adapters.
+ */
+export declare function lazy<T extends TokenBase>(token: T & TokenTupleAdmission<readonly [T]>, ...invalid: [T] extends [never] ? [TokenTupleAdmission<readonly [T]>] : []): LazyDependency<T>;
+/**
+ * Describe a positional dependency containing every contribution for a token.
+ * @param token - The genuine collection token.
+ * @returns An immutable reference that supplies a fresh frozen array, including when empty.
+ */
+export declare function all<T extends TokenBase>(token: T & TokenTupleAdmission<readonly [T]>, ...invalid: [T] extends [never] ? [TokenTupleAdmission<readonly [T]>] : []): CollectionDependency<T>;
+/** Indexed snapshots ignore tuple iterators and retain only authenticated records. */
+export declare function snapshotReferences(value: unknown): readonly ArgumentReference[];
+export {};

package/dist/dependency-references.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.optional = optional;
+exports.lazy = lazy;
+exports.all = all;
+exports.snapshotReferences = snapshotReferences;
+const errors_1 = require("./errors");
+const tokens_1 = require("./tokens");
+class ReferenceBase {
+}
+class DependencyHandle extends ReferenceBase {
+}
+const references = new WeakMap();
+function reference(token, kind) {
+    const key = (0, tokens_1.readTokenKey)(token);
+    const handle = new DependencyHandle();
+    references.set(handle, Object.freeze({ key, kind }));
+    Object.freeze(handle);
+    return handle;
+}
+/**
+ * Describe a positional dependency that supplies `undefined` only when the token is unbound.
+ * A present `undefined` value and acquisition failures remain present dependency results.
+ * @param token - The genuine typed token to read optionally.
+ * @returns An immutable reference accepted by positional provider adapters.
+ */
+function optional(token, ...invalid) { return reference(token, 'optional'); }
+/**
+ * Describe a positional dependency supplied as an on-demand lookup function.
+ * Each invocation follows the target lifetime and records its dependency edge then.
+ * @param token - The genuine typed token to resolve lazily.
+ * @returns An immutable lazy reference accepted by positional provider adapters.
+ */
+function lazy(token, ...invalid) { return reference(token, 'lazy'); }
+/**
+ * Describe a positional dependency containing every contribution for a token.
+ * @param token - The genuine collection token.
+ * @returns An immutable reference that supplies a fresh frozen array, including when empty.
+ */
+function all(token, ...invalid) { return reference(token, 'all'); }
+/** Indexed snapshots ignore tuple iterators and retain only authenticated records. */
+function snapshotReferences(value) {
+    if (!Array.isArray(value))
+        throw (0, errors_1.libraryError)('DI_BAG_INVALID_TOKEN', 'tokens must be a tuple', { operation: 'token' });
+    const selected = [];
+    const length = value.length;
+    for (let index = 0; index < length; index++)
+        selected[index] = value[index];
+    return Object.freeze(selected.map(handle => {
+        const retained = typeof handle === 'object' && handle !== null ? references.get(handle) : undefined;
+        return Object.freeze({ slot: Symbol('argument'), key: retained?.key ?? (0, tokens_1.readTokenKey)(handle), kind: retained?.kind ?? 'required' });
+    }));
+}

package/dist/di-bag.d.ts

@@ -0,0 +1,247 @@
+import type { ObserverOptions } from './observers';
+import type { BuilderContribute, CollectionMember } from './contribution-types';
+import type { AliasSelection, AliasAdmission, AliasTarget, AliasDestination, AliasEntry, AliasEntries } from './alias-types';
+import { optional, lazy, all } from './dependency-references';
+import { withDisposal } from './registration';
+import type { FactoryWithDisposal, Factory, Registration, Registrations } from './registration';
+import { BindingGraph, BagRuntime } from './runtime';
+import type { Module } from './module';
+import type { CheckedConstraints, CompleteConstraints, ExternalRequirements, IncrementalConstraints, ModulePublicProviders, ModuleSealedConstraints, NeedConstraint } from './module-types';
+import type { CheckedLifetimes } from './lifetime-types';
+import { withLifetime } from './lifetime';
+import { fromFactory } from './acquisition-context';
+import type { ScopeOptions, DisjointScopeSelection, UnsharedAliases, ScopedAliases } from './scope-types';
+import type { CheckedScopeLifetimes } from './lifetime-types';
+import type { StartupOptions } from './startup';
+import { withMetadata, transformService } from './provider';
+import { fromFunction, fromClass } from './composition';
+import type { RuntimeContext, RuntimeOptions } from './acquisition-mode';
+import type { ProviderRegistrationMetadata, ProviderAcquisitionMetadata } from './provider';
+import type { RegistrationSnapshot } from './inspection';
+import { token } from './tokens';
+import type { PluginProviderFactory } from './plugins';
+import type { TokenBase, TokenKey, TokenService } from './tokens';
+import type { TokenBinding, BindingOutput, TokenMember, TokenTupleAdmission, SelectionKey, ReboundSelection } from './token-types';
+import type { BuilderReplacementRegistration, ReplacementAdmission, ReplacedEntries, ZeroDependencyAdmission } from './replacement-types';
+import type { CheckDependencyCompatibility, CheckDependencyCompleteness, RegistrationEntries, Entry, EntryKeys, OverrideFactoryContext, RegistrationsFromEntries, IncrementalChecked, Introduces, IntroducesKeys, OverrideRegistrations, Overrides, ServicesOf, ReplacementKeyOf, ReplacementOutput, SelectedRegistrations, Selection, NamedAdmission } from './types';
+type ReplacementFactory<O> = (this: void) => O;
+declare const constraintInvariant: unique symbol;
+/**
+ * A resolving container with lazy acquisition, caching, and independent resource ownership.
+ *
+ * Create bags through {@link DiBagApi.createBuilder} followed by {@link Builder.build} or
+ * {@link Builder.buildAndStart}; the class is exported as a type and has no public constructor.
+ */
+declare class Bag<R extends Registrations, C extends NeedConstraint = never> {
+    #private;
+    private readonly context;
+    /** @internal */
+    readonly [constraintInvariant]: (value: C) => C;
+    constructor(graph: BindingGraph, context: RuntimeContext, runtime?: BagRuntime);
+    /**
+     * Resolve a named or typed-token service, acquiring it lazily when needed.
+     * Scoped and root services are cached according to their lifetime; transient services
+     * create a new acquisition for each call. Promise-valued services keep their identity.
+     * @param token - An existing public string name or typed token.
+     * @returns The service exposed by the selected registration.
+     * @throws If the bag is closing, the token is invalid, acquisition fails, or a runtime cycle is found.
+     */
+    resolve<K extends (keyof R & string) | TokenBase>(token: K & ([K] extends [string] ? unknown : TokenMember<R, K>)): ServicesOf<R>[SelectionKey<K> & keyof R];
+    /**
+     * Resolve every contribution for a typed token in declaration and installation order.
+     * @param token - The collection token whose contributions to acquire.
+     * @returns A fresh frozen array; an unpopulated collection returns an empty array.
+     * @throws If the bag is closing, the token is invalid, or a contribution fails.
+     */
+    resolveAll<T extends TokenBase>(token: T & TokenTupleAdmission<readonly [T]> & CollectionMember<T, C>, ...invalid: [T] extends [never] ? [never] : []): ReadonlyArray<TokenService<T>>;
+    /**
+     * Inspect every contribution for a token without running its factories.
+     * @param token - The collection token to inspect.
+     * @returns Frozen snapshots in contribution order.
+     */
+    inspectAll<T extends TokenBase>(token: T & TokenTupleAdmission<readonly [T]> & CollectionMember<T, C>, ...invalid: [T] extends [never] ? [never] : []): readonly RegistrationSnapshot<object, readonly unknown[]>[];
+    /**
+     * Inspect static metadata and copied acquisition state without resolving a service.
+     * @param token - An existing public string name or typed token.
+     * @returns A frozen point-in-time snapshot. Application-owned metadata payloads are not frozen.
+     */
+    inspect<K extends (keyof R & string) | TokenBase>(token: K & ([K] extends [string] ? unknown : TokenMember<R, K>)): RegistrationSnapshot<ProviderRegistrationMetadata<R[SelectionKey<K> & keyof R]>, ProviderAcquisitionMetadata<R[SelectionKey<K> & keyof R]>>;
+    /**
+     * Create a tracked child that borrows selected parent acquisitions.
+     * @param options - A checked selection of non-transient services to share lazily.
+     * @returns A child owned by this bag; closing the parent closes the child first.
+     */
+    createScope<const S extends readonly unknown[]>(options: ScopeOptions<R, S>): Bag<ScopedAliases<R, R, S>, C>;
+    /**
+     * Create a tracked child with selected replacements and optional parent sharing.
+     * @param keys - Existing names or tokens to replace in the child.
+     * @param overrides - Own registration properties for every selected key.
+     * @param options - A disjoint selection of non-transient parent acquisitions to share.
+     * @returns A child with fresh scoped acquisitions and ownership for unshared services.
+     * @throws If the runtime selections, overrides, or sharing options are invalid.
+     */
+    createScope<const K extends readonly unknown[], O extends OverrideFactoryContext<R, K, O>, const S extends readonly unknown[] = readonly []>(keys: K & Selection<R, K, 'createScope'>, overrides: O & object & Record<SelectionKey<K[number]>, Registration> & Overrides<R, SelectedRegistrations<K, O>> & CheckDependencyCompatibility<OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>> & CheckDependencyCompleteness<OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>> & CheckedConstraints<C, OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>> & CompleteConstraints<C, OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>> & CheckedScopeLifetimes<NoInfer<ScopedAliases<OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>, R, S>>, NoInfer<SelectedRegistrations<K, O>>, C>, options?: ScopeOptions<R, S> & DisjointScopeSelection<K, S>): Bag<ScopedAliases<OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>, R, S>, C>;
+    /**
+     * Create a tracked child with the same graph and fresh scoped acquisitions.
+     * @returns A child that is closed before its parent finishes closing.
+     */
+    createScope(): Bag<UnsharedAliases<R>, C>;
+    /**
+     * Create an independent bag with the same graph and fresh instances.
+     * @returns A new ownership family that must be closed separately.
+     */
+    fork(this: Bag<R, C> & CheckedLifetimes<UnsharedAliases<R>, C>): Bag<UnsharedAliases<R>, C>;
+    /**
+     * Create an independent bag with selected replacements.
+     * @param keys - Existing names or tokens to replace.
+     * @param overrides - Own registration properties for every selected key.
+     * @returns A fresh ownership family whose graph uses the checked replacements.
+     * @throws If a selected key is absent or lacks an own override.
+     */
+    fork<const K extends readonly unknown[], O extends OverrideFactoryContext<R, K, O>>(keys: K & Selection<R, K>, overrides: O & object & Record<SelectionKey<K[number]>, Registration> & Overrides<R, SelectedRegistrations<K, O>> & CheckDependencyCompatibility<OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>> & CheckDependencyCompleteness<OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>> & CheckedConstraints<C, OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>> & CompleteConstraints<C, OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>> & CheckedLifetimes<UnsharedAliases<OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>>, C>): Bag<UnsharedAliases<OverrideRegistrations<R, ReboundSelection<R, SelectedRegistrations<K, O>>>>, C>;
+    /**
+     * Close this bag, drain in-flight work, and dispose owned resources once.
+     * Dependents are disposed before dependencies; remaining independent acquisitions use
+     * reverse acquisition order. Repeated calls return the same promise.
+     * @returns The shared shutdown promise.
+     * @throws {@link DiBagCleanupError} when one or more disposers fail after all cleanup is attempted.
+     */
+    close(): Promise<void>;
+}
+/**
+ * An immutable, type-checked graph builder. Every operation returns a new builder.
+ * Create one with {@link DiBagApi.createBuilder}. The same builder value can
+ * {@link Builder.build} a bag once its graph is complete, or
+ * {@link Builder.buildModule} a reusable module whose unmet dependencies become
+ * requirements the installing host must satisfy.
+ */
+declare class Builder<E extends Entry, C extends NeedConstraint = never> {
+    #private;
+    private readonly context;
+    /** @internal */
+    readonly [constraintInvariant]: (value: readonly [E, C]) => readonly [E, C];
+    constructor(graph: BindingGraph, context: RuntimeContext);
+    /**
+     * Add new string-named registrations.
+     * @param more - A finite object whose own string keys are service names and values are registrations.
+     * @returns A new builder containing snapshots of the supplied registrations.
+     * @throws If the input is malformed, contains a non-string key, or duplicates a public name.
+     */
+    register<N extends {
+        [K in keyof N]: Registration;
+    }>(more: N & Registrations & ([N] extends [never] ? never : NamedAdmission<N> & IntroducesKeys<EntryKeys<E>, keyof N> & IncrementalChecked<E, N> & CheckedConstraints<C, OverrideRegistrations<RegistrationsFromEntries<E>, N>>)): Builder<E | RegistrationEntries<N>, C>;
+    /**
+     * Register a provider to a typed token.
+     * @param token - A new typed token identity.
+     * @param registration - A registration whose exposed output satisfies the token service type.
+     * @returns A new builder retaining the provider's metadata, lifetime, dependencies, and ownership stages.
+     */
+    register<T extends TokenBase, V extends Registration>(token: T & TokenTupleAdmission<readonly [T]> & IntroducesKeys<EntryKeys<E>, TokenKey<T>>, registration: V & Registration & BindingOutput<NoInfer<T>, NoInfer<V>> & IncrementalChecked<E, Record<TokenKey<T>, TokenBinding<NoInfer<T>, NoInfer<V>>>> & CheckedConstraints<C, OverrideRegistrations<RegistrationsFromEntries<E>, Record<TokenKey<T>, TokenBinding<NoInfer<T>, NoInfer<V>>>>>): Builder<E | {
+        key: TokenKey<T>;
+        registration: TokenBinding<T, V>;
+    }, C>;
+    /**
+     * Add another lookup name or token for an existing service.
+     * @param destination - A new string name or typed token.
+     * @param target - The existing name or token whose canonical acquisition is reused.
+     * @returns A new builder; aliases add no cache or ownership of their own.
+     */
+    alias<const D extends AliasSelection, const T extends AliasSelection>(destination: D & (unknown extends AliasAdmission<D> ? Introduces<RegistrationsFromEntries<E>, AliasEntries<RegistrationsFromEntries<E>, D, T>> : AliasAdmission<D>), target: T & AliasAdmission<T> & (unknown extends AliasAdmission<T> ? AliasTarget<RegistrationsFromEntries<E>, T> & AliasDestination<RegistrationsFromEntries<E>, NoInfer<D>, T> : unknown) & (unknown extends AliasAdmission<D> & AliasAdmission<T> ? IncrementalChecked<E, AliasEntries<RegistrationsFromEntries<E>, NoInfer<D>, NoInfer<T>>> & CheckedConstraints<C, OverrideRegistrations<RegistrationsFromEntries<E>, AliasEntries<RegistrationsFromEntries<E>, NoInfer<D>, NoInfer<T>>>> : unknown), ...invalid: [D] extends [never] ? [never] : [T] extends [never] ? [never] : []): Builder<E | AliasEntry<RegistrationsFromEntries<E>, D, T>, C>;
+    /**
+     * Append a provider to a typed-token collection.
+     * @param token - The collection's typed token.
+     * @param registration - A registration whose output satisfies the token service type.
+     * @returns A new builder preserving contribution order.
+     */
+    readonly contribute: BuilderContribute<E, C>;
+    /**
+     * Replace an existing string-named registration with a dependency-free factory.
+     * @param key - One existing string-literal service name.
+     * @param registration - The replacement, checked against every surviving consumer.
+     * @returns A new builder with the replacement.
+     * @typeParam V - The exact replacement factory or disposable-factory type.
+     */
+    replace<const K extends string, V extends (ReplacementFactory<ReplacementOutput<NoInfer<RegistrationsFromEntries<E>>, K, C>>) | FactoryWithDisposal<ReplacementFactory<ReplacementOutput<NoInfer<RegistrationsFromEntries<E>>, K, C>>>>(key: K & ReplacementKeyOf<EntryKeys<E>, K>, registration: V & (Factory | FactoryWithDisposal<Factory>) & ZeroDependencyAdmission<NoInfer<V>> & CheckedConstraints<C, OverrideRegistrations<RegistrationsFromEntries<E>, Record<K, NoInfer<V>>>>): Builder<Exclude<E, {
+        key: K;
+    }> | {
+        key: K;
+        registration: V;
+    }, C>;
+    /**
+     * Replace an existing named or typed-token registration.
+     * @param key - The single existing name or token to replace.
+     * @param registration - A replacement compatible with the token and known consumers.
+     * @returns A new builder with the replacement and its inferred service type.
+     */
+    replace<const K extends string | TokenBase, V extends Registration>(key: K & NoInfer<ReplacementAdmission<RegistrationsFromEntries<E>, K>>, registration: V & Registration & BuilderReplacementRegistration<E, C, NoInfer<K>, V>): Builder<ReplacedEntries<E, K, V>, C>;
+    /**
+     * Install a sealed module, allocating fresh private bindings for this installation.
+     * @param module - A module whose public names do not collide and whose external requirements remain checkable.
+     * @returns A new builder exposing only the module's selected exports.
+     */
+    installModule<P extends object, R extends object, MC extends NeedConstraint, D extends Registrations>(module: Module<P, R, MC, D> & IntroducesKeys<EntryKeys<E>, keyof D> & IncrementalChecked<E, D> & IncrementalConstraints<C, MC, RegistrationsFromEntries<E>, D>): Builder<E | RegistrationEntries<D>, C | MC>;
+    /**
+     * Seal this graph as a reusable module and select its public names and typed tokens.
+     * Unselected registrations stay private to each installation; unmet dependencies
+     * become requirements of the module. Installed modules nest: their private
+     * bindings and retained constraints are re-scoped inside this module.
+     * @param keys - A finite tuple of existing names or tokens; an empty tuple is allowed.
+     * @returns An immutable module that can be renamed or installed in another builder.
+     * @throws If the selection is not a tuple or contains an absent name or token.
+     */
+    buildModule<const K extends readonly unknown[]>(keys: K & Selection<RegistrationsFromEntries<E>, K, 'buildModule'>): Module<Pick<ServicesOf<RegistrationsFromEntries<E>>, Extract<SelectionKey<K[number]>, keyof RegistrationsFromEntries<E>>>, ExternalRequirements<ModuleSealedConstraints<E, C, Extract<SelectionKey<K[number]>, keyof RegistrationsFromEntries<E>>>>, ModuleSealedConstraints<E, C, Extract<SelectionKey<K[number]>, keyof RegistrationsFromEntries<E>>>, ModulePublicProviders<RegistrationsFromEntries<E>, Extract<SelectionKey<K[number]>, keyof RegistrationsFromEntries<E>>>>;
+    /**
+     * Finish a complete graph as a lazy bag.
+     * @returns A fresh bag that owns the acquisitions it creates.
+     * @throws At runtime if automatic acquisition is used without a configured Promise classifier.
+     */
+    build(this: Builder<E, C> & CheckDependencyCompleteness<RegistrationsFromEntries<E>> & CompleteConstraints<C, RegistrationsFromEntries<E>> & CheckedLifetimes<RegistrationsFromEntries<E>, C>): Bag<RegistrationsFromEntries<E>, C>;
+    /**
+     * Create a fresh bag and acquire selected services before returning it.
+     * @param keys - A finite tuple of existing names or typed tokens to make ready.
+     * @param options - Optional cancellation signal, positive timeout, and parallel, sequential, or positive safe integer bounded scheduling.
+     * @returns A promise for the new bag after every selected final stage is ready.
+     * @throws {@link DiBagStartupError} after rollback on acquisition failure, or
+     * {@link DiBagStartupCancelledError} promptly on abort or timeout.
+     */
+    buildAndStart<const K extends readonly unknown[]>(this: Builder<E, C> & CheckDependencyCompleteness<RegistrationsFromEntries<E>> & CompleteConstraints<C, RegistrationsFromEntries<E>> & CheckedLifetimes<RegistrationsFromEntries<E>, C>, keys: K & Selection<RegistrationsFromEntries<E>, K, 'buildAndStart'>, options?: StartupOptions): Promise<Bag<RegistrationsFromEntries<E>, C>>;
+}
+export type { Bag, Builder };
+/** Immutable facade configuration. Observers append in the supplied order. */
+export interface ConfigurationOptions {
+    readonly runtime?: RuntimeOptions;
+    readonly observers?: readonly ObserverOptions[];
+}
+/** The immutable public entry surface used by {@link DiBag} and derived facades. */
+export interface DiBagApi {
+    /** Return a facade with inherited runtime settings and appended observers. */
+    withConfiguration: (options: ConfigurationOptions) => DiBagApi;
+    /** Describe a named-dependency factory, optionally receiving acquisition context. */
+    fromFactory: typeof fromFactory;
+    /** Create a nominal typed token with a diagnostic label. */
+    token: typeof token;
+    /** Create a positional dependency that yields undefined only when unregistered. */
+    optional: typeof optional;
+    /** Create a positional dependency resolved on demand by the receiving service. */
+    lazy: typeof lazy;
+    /** Create a positional dependency containing ordered collection contributions. */
+    all: typeof all;
+    /** Validate an unknown plugin descriptor and its acquired output at a checked boundary. */
+    fromPlugin: PluginProviderFactory;
+    /** Adapt a positional function with strict dependency tuple and argument checking. */
+    fromFunction: typeof fromFunction;
+    /** Adapt a concrete constructor with positional dependency injection. */
+    fromClass: typeof fromClass;
+    /** Begin an empty immutable graph; build creates its owning bag, buildModule seals a reusable module. */
+    createBuilder: () => Builder<never>;
+    /** Attach owned-value cleanup while retaining earlier disposal stages. */
+    withDisposal: typeof withDisposal;
+    /** Select root, scoped, or transient caching within an ownership family. */
+    withLifetime: typeof withLifetime;
+    /** Attach registration metadata and ordered acquisition metadata in direct or awaited mode. */
+    withMetadata: typeof withMetadata;
+    /** Transform the exposed service while retaining dependencies, metadata, lifetime, and existing ownership. */
+    transformService: typeof transformService;
+}
+/** The portable, immutable DI Bag facade. Configure `auto` acquisition or use explicit modes. */
+export declare const DiBag: DiBagApi;

package/dist/di-bag.js

@@ -0,0 +1,211 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiBag = void 0;
+const errors_1 = require("./errors");
+const observers_1 = require("./observers");
+const contributions_1 = require("./contributions");
+const aliases_1 = require("./aliases");
+const dependency_references_1 = require("./dependency-references");
+const registration_1 = require("./registration");
+const runtime_1 = require("./runtime");
+const module_1 = require("./module");
+const lifetime_1 = require("./lifetime");
+const acquisition_context_1 = require("./acquisition-context");
+const startup_1 = require("./startup");
+const scope_selection_1 = require("./scope-selection");
+const provider_1 = require("./provider");
+const composition_1 = require("./composition");
+const acquisition_mode_1 = require("./acquisition-mode");
+const tokens_1 = require("./tokens");
+const plugins_1 = require("./plugins");
+/**
+ * A resolving container with lazy acquisition, caching, and independent resource ownership.
+ *
+ * Create bags through {@link DiBagApi.createBuilder} followed by {@link Builder.build} or
+ * {@link Builder.buildAndStart}; the class is exported as a type and has no public constructor.
+ */
+class Bag {
+    context;
+    #graph;
+    #runtime;
+    constructor(graph, context, runtime) {
+        this.context = context;
+        this.#graph = graph;
+        this.#runtime = runtime ?? new runtime_1.BagRuntime(graph, context);
+    }
+    resolve(token) {
+        return this.#runtime.resolve(typeof token === 'string' ? token : (0, tokens_1.readTokenKey)(token));
+    }
+    resolveAll(token) { return this.#runtime.resolveAll((0, tokens_1.readTokenKey)(token)); }
+    inspectAll(token) { return this.#runtime.inspectAll((0, tokens_1.readTokenKey)(token)); }
+    inspect(token) {
+        return this.#runtime.inspect(typeof token === 'string' ? token : (0, tokens_1.readTokenKey)(token));
+    }
+    createScope(...args) {
+        this.#runtime.assertOpen();
+        const { graph, shared } = (0, scope_selection_1.selectScope)(this.#graph, args, key => this.#runtime.isTransient(key));
+        return new Bag(graph, this.context, this.#runtime.scope(graph, shared));
+    }
+    fork(keys, overrides) {
+        this.#runtime.assertOpen();
+        if (keys === undefined && overrides === undefined) {
+            return new Bag(this.#graph, this.context);
+        }
+        if (!Array.isArray(keys) ||
+            typeof overrides !== 'object' ||
+            overrides === null) {
+            throw (0, errors_1.libraryError)('DI_BAG_INVALID_OVERRIDE', 'fork requires selected keys and an override object', { operation: 'fork' });
+        }
+        // Snapshot indexed entries before override getters can mutate the tuple.
+        // A tuple's custom iterator need not enumerate its declared indexed keys.
+        const selectedKeys = [];
+        const length = keys.length;
+        for (let index = 0; index < length; index++) {
+            selectedKeys[index] = keys[index];
+        }
+        if (selectedKeys.length === 0)
+            return new Bag(this.#graph, this.context);
+        const publicKeys = selectedKeys.map(value => typeof value === 'string' ? value : (0, tokens_1.readTokenKey)(value));
+        for (const token of publicKeys) {
+            if (!this.#graph.hasPublic(token)) {
+                throw (0, errors_1.libraryError)('DI_BAG_INVALID_OVERRIDE', `fork accepts existing names or typed tokens only: ${String(token)}`, { operation: 'fork' });
+            }
+            if (!Object.hasOwn(overrides, token)) {
+                throw (0, errors_1.libraryError)('DI_BAG_INVALID_OVERRIDE', `missing override: ${String(token)}`, { operation: 'fork' });
+            }
+        }
+        const selectedBindings = [];
+        for (const token of publicKeys) {
+            const registration = Reflect.get(overrides, token);
+            (0, registration_1.normalize)(registration);
+            selectedBindings.push([token, registration]);
+        }
+        return new Bag(this.#graph.withPublicBindings(selectedBindings), this.context);
+    }
+    /**
+     * Close this bag, drain in-flight work, and dispose owned resources once.
+     * Dependents are disposed before dependencies; remaining independent acquisitions use
+     * reverse acquisition order. Repeated calls return the same promise.
+     * @returns The shared shutdown promise.
+     * @throws {@link DiBagCleanupError} when one or more disposers fail after all cleanup is attempted.
+     */
+    close() {
+        return this.#runtime.close();
+    }
+}
+/**
+ * An immutable, type-checked graph builder. Every operation returns a new builder.
+ * Create one with {@link DiBagApi.createBuilder}. The same builder value can
+ * {@link Builder.build} a bag once its graph is complete, or
+ * {@link Builder.buildModule} a reusable module whose unmet dependencies become
+ * requirements the installing host must satisfy.
+ */
+class Builder {
+    context;
+    #graph;
+    constructor(graph, context) {
+        this.context = context;
+        this.#graph = graph;
+    }
+    register(moreOrToken, registration) {
+        if (arguments.length === 1) {
+            const snapshot = (0, registration_1.snapshotAdd)(moreOrToken, key => this.#graph.hasPublic(key));
+            return new Builder(this.#graph.withPublicRegistrations(snapshot), this.context);
+        }
+        const key = (0, tokens_1.readTokenKey)(moreOrToken);
+        if (this.#graph.hasPublic(key))
+            throw (0, errors_1.libraryError)('DI_BAG_DUPLICATE_REGISTRATION', `duplicate registration: ${String(key)}`, { operation: 'register', key });
+        return new Builder(this.#graph.withPublicBinding(key, (0, provider_1.withTokenBinding)(moreOrToken, registration)), this.context);
+    }
+    /**
+     * Add another lookup name or token for an existing service.
+     * @param destination - A new string name or typed token.
+     * @param target - The existing name or token whose canonical acquisition is reused.
+     * @returns A new builder; aliases add no cache or ownership of their own.
+     */
+    alias(destination, target, ...invalid) {
+        const [key, registration] = (0, aliases_1.aliasEntry)(destination, target, key => this.#graph.hasPublic(key));
+        return new Builder(this.#graph.withPublicBinding(key, registration), this.context);
+    }
+    /**
+     * Append a provider to a typed-token collection.
+     * @param token - The collection's typed token.
+     * @param registration - A registration whose output satisfies the token service type.
+     * @returns A new builder preserving contribution order.
+     */
+    // A named callable keeps extracted generic methods nameable in consumer declarations.
+    contribute = ((token, registration) => {
+        const [key, value] = (0, contributions_1.contributionEntry)(token, registration);
+        return new Builder(this.#graph.withContribution(key, value), this.context);
+    });
+    replace(selection, registration) {
+        const key = typeof selection === 'string' ? selection : (0, tokens_1.readTokenKey)(selection);
+        if (!this.#graph.hasPublic(key)) {
+            throw (0, errors_1.libraryError)('DI_BAG_INVALID_REPLACEMENT', `replace accepts existing names or typed tokens only: ${String(key)}`, { operation: 'replace', key });
+        }
+        (0, registration_1.normalize)(registration);
+        return new Builder(this.#graph.withPublicBinding(key, registration), this.context);
+    }
+    /**
+     * Install a sealed module, allocating fresh private bindings for this installation.
+     * @param module - A module whose public names do not collide and whose external requirements remain checkable.
+     * @returns A new builder exposing only the module's selected exports.
+     */
+    installModule(module) {
+        return new Builder(this.#graph.withInstallation((0, module_1.moduleGraph)(module)), this.context);
+    }
+    /**
+     * Seal this graph as a reusable module and select its public names and typed tokens.
+     * Unselected registrations stay private to each installation; unmet dependencies
+     * become requirements of the module. Installed modules nest: their private
+     * bindings and retained constraints are re-scoped inside this module.
+     * @param keys - A finite tuple of existing names or tokens; an empty tuple is allowed.
+     * @returns An immutable module that can be renamed or installed in another builder.
+     * @throws If the selection is not a tuple or contains an absent name or token.
+     */
+    buildModule(keys) {
+        return (0, module_1.sealModule)(this.#graph, keys);
+    }
+    /**
+     * Finish a complete graph as a lazy bag.
+     * @returns A fresh bag that owns the acquisitions it creates.
+     * @throws At runtime if automatic acquisition is used without a configured Promise classifier.
+     */
+    build() {
+        return new Bag(this.#graph, this.context);
+    }
+    /**
+     * Create a fresh bag and acquire selected services before returning it.
+     * @param keys - A finite tuple of existing names or typed tokens to make ready.
+     * @param options - Optional cancellation signal, positive timeout, and parallel, sequential, or positive safe integer bounded scheduling.
+     * @returns A promise for the new bag after every selected final stage is ready.
+     * @throws {@link DiBagStartupError} after rollback on acquisition failure, or
+     * {@link DiBagStartupCancelledError} promptly on abort or timeout.
+     */
+    async buildAndStart(keys, options) {
+        const runtime = await (0, startup_1.startRuntime)(this.#graph, this.context, keys, options);
+        return new Bag(this.#graph, this.context, runtime);
+    }
+}
+function facade(context) {
+    return Object.freeze({
+        withConfiguration: (options) => {
+            if (typeof options !== 'object' || options === null || Array.isArray(options))
+                throw (0, errors_1.libraryTypeError)('DI_BAG_INVALID_CONFIGURATION', 'withConfiguration requires an options object', { operation: 'withConfiguration' });
+            const { runtime, observers } = options;
+            let configured = runtime === undefined ? context : (0, acquisition_mode_1.runtimeContext)(runtime, context);
+            if (observers !== undefined) {
+                if (!Array.isArray(observers))
+                    throw (0, errors_1.libraryTypeError)('DI_BAG_INVALID_CONFIGURATION', 'withConfiguration observers must be an array', { operation: 'withConfiguration' });
+                for (const observer of observers)
+                    configured = Object.freeze({ ...configured, observers: observers_1.LifecycleObservers.append(configured.observers, observer) });
+            }
+            return facade(configured);
+        },
+        fromFactory: acquisition_context_1.fromFactory, token: tokens_1.token, optional: dependency_references_1.optional, lazy: dependency_references_1.lazy, all: dependency_references_1.all, fromPlugin: plugins_1.fromPlugin, fromFunction: composition_1.fromFunction, fromClass: composition_1.fromClass,
+        createBuilder: () => new Builder(new runtime_1.BindingGraph(), context),
+        withDisposal: registration_1.withDisposal, withLifetime: lifetime_1.withLifetime, withMetadata: provider_1.withMetadata, transformService: provider_1.transformService,
+    });
+}
+/** The portable, immutable DI Bag facade. Configure `auto` acquisition or use explicit modes. */
+exports.DiBag = facade(acquisition_mode_1.unconfigured);

package/dist/errors.d.ts

@@ -0,0 +1,66 @@
+/** Stable category for a diagnostic created by DI Bag itself. */
+export type DiBagErrorCode = `DI_BAG_${string}`;
+/** Structured library diagnostics. Application-owned payloads retain their identity. */
+export interface DiBagDiagnostic {
+    readonly code: DiBagErrorCode;
+    readonly details: Readonly<Record<string, unknown>>;
+}
+/** Attach only at library-owned error creation sites; never modify application errors. */
+export declare function diagnostic<E extends Error>(error: E, code: DiBagErrorCode, details?: Readonly<Record<string, unknown>>): E & DiBagDiagnostic;
+export declare function libraryError(code: DiBagErrorCode, message: string, details?: Readonly<Record<string, unknown>>): Error & DiBagDiagnostic;
+export declare function libraryTypeError(code: DiBagErrorCode, message: string, details?: Readonly<Record<string, unknown>>): TypeError & DiBagDiagnostic;
+/** One disposer failure, associated with the acquisition that owned it. */
+export interface CleanupFailure {
+    readonly acquisitionId: symbol;
+    readonly bindingId: symbol;
+    readonly label: string;
+    readonly error: unknown;
+}
+/** A plugin descriptor or produced value crossed the checked plugin boundary. */
+export declare class DiBagPluginValidationError extends Error {
+    readonly phase: 'descriptor' | 'output';
+    readonly reason: string;
+    readonly code: 'DI_BAG_PLUGIN_VALIDATION';
+    readonly details: Readonly<Record<string, unknown>>;
+    /**
+     * @param phase - Whether descriptor authentication or output validation failed.
+     * @param reason - A stable description of the rejected boundary condition.
+     */
+    constructor(phase: 'descriptor' | 'output', reason: string);
+}
+/** Original cleanup causes and detached acquisition diagnostics, in attempt order. */
+export declare class DiBagCleanupError extends AggregateError {
+    readonly code: 'DI_BAG_CLEANUP_FAILED';
+    readonly details: Readonly<Record<string, unknown>>;
+    /** Frozen cleanup failures in finalizer invocation order. */
+    readonly failures: readonly CleanupFailure[];
+    /** @param failures - Structured failures whose original errors also populate `AggregateError.errors`. */
+    constructor(failures: readonly CleanupFailure[]);
+}
+/** Acquisition failure after the new bag has finished releasing its resources. */
+export declare class DiBagStartupError extends Error {
+    readonly cleanupError?: unknown | undefined;
+    readonly code: 'DI_BAG_STARTUP_FAILED';
+    readonly details: Readonly<Record<string, unknown>>;
+    /** Frozen rollback disposal failures in invocation order. */
+    readonly cleanupFailures: readonly CleanupFailure[];
+    /**
+     * @param cause - The original selected-service acquisition failure.
+     * @param cleanupFailures - Structured failures collected while rolling back the new bag.
+     * @param cleanupError - The complete shutdown error, when rollback itself rejected.
+     */
+    constructor(cause: unknown, cleanupFailures: readonly CleanupFailure[], cleanupError?: unknown | undefined);
+}
+/** Prompt cancellation; cleanup remains awaitable for uncooperative factories. */
+export declare class DiBagStartupCancelledError extends Error {
+    readonly reason: 'aborted' | 'timeout';
+    readonly cleanupPromise: Promise<void>;
+    readonly code: 'DI_BAG_STARTUP_CANCELLED';
+    readonly details: Readonly<Record<string, unknown>>;
+    /**
+     * @param reason - Whether an external abort or startup timeout cancelled the wait.
+     * @param cause - The abort reason or generated timeout error.
+     * @param cleanupPromise - Eventual shutdown of the partially started bag; cancellation does not await it.
+     */
+    constructor(reason: 'aborted' | 'timeout', cause: unknown, cleanupPromise: Promise<void>);
+}