di-bag 0.2.0 → 0.4.0

package/dist/acquisition.js

@@ -5,6 +5,19 @@ const errors_1 = require("./errors");
 const errors_2 = require("./errors");
 const provider_execution_1 = require("./provider-execution");
 const acquisition_family_1 = require("./acquisition-family");
+/**
+ * The reason a close() without a cause aborts with. Built once at load: an error
+ * created inside close() keeps an unformatted stack whose frames retain the
+ * closing callbacks, and through them the scope and its graph, on every signal an
+ * application kept after the bag closed. It stays a plain `AbortError`, so its
+ * legacy numeric `code` is what an automatic abort reason had; the message names
+ * the diagnostic.
+ */
+const closingReason = (() => {
+    const reason = new DOMException((0, errors_1.diagnosticMessage)('DI_BAG_CLOSING', 'bag is closing'), 'AbortError');
+    void reason.stack; // format the load-time frames now, so nothing is retained lazily
+    return Object.freeze(reason);
+})();
 /** Mutable, runtime-local attempts. Binding descriptions never carry ownership. */
 class ScopeAcquisitions {
     graph;
@@ -21,7 +34,6 @@ class ScopeAcquisitions {
     state = 'open';
     closing;
     controller;
-    acquisitionContext;
     cancellationStarted = false;
     cancellationCause;
     shared;
@@ -132,20 +144,43 @@ class ScopeAcquisitions {
         this.closing = Promise.resolve().then(() => {
             // Every descendant admission gate is closed before abort listeners run.
             this.cancellationStarted = true;
-            this.cancellationCause = cause;
-            this.controller?.abort(cause);
+            this.cancellationCause = cause === undefined ? closingReason : cause;
+            this.controller?.abort(this.cancellationCause);
             return this.disposeAll(beforeDispose);
         });
         return this.closing;
     }
-    getContext() {
-        if (!this.acquisitionContext) {
+    /** Labels of this scope's running disposers and of acquisitions close is still draining. */
+    collectProgress(pending, acquiring) {
+        for (const attempt of this.attempts.values()) {
+            if (attempt.state === 'disposing' || this.retired.has(attempt.id) || attempt.execution.rollingBack)
+                pending.push(attempt.label);
+            else if (attempt.state === 'creating' || attempt.state === 'pending')
+                acquiring.push(attempt.label);
+        }
+    }
+    /** One controller per scope; every acquisition observes the same cancellation. */
+    cancellationSignal() {
+        if (!this.controller) {
             this.controller = new AbortController();
             if (this.cancellationStarted)
                 this.controller.abort(this.cancellationCause);
-            this.acquisitionContext = Object.freeze({ signal: this.controller.signal });
         }
-        return this.acquisitionContext;
+        return this.controller.signal;
+    }
+    /**
+     * The signal is scope-wide; deferred cleanup is local to this attempt, so each
+     * contextual acquisition receives its own frozen context. The context captures
+     * only its disposer stack, never the execution or this scope, so an
+     * application that retains it past `close()` retains nothing else. Built here
+     * rather than in `resolveBinding` for the same reason: every closure of a
+     * function shares one scope, and a factory can retain the dependency proxy.
+     */
+    acquisitionContext(disposers) {
+        return Object.freeze({
+            signal: this.cancellationSignal(),
+            pushDisposer: (disposer) => { disposers.push(disposer); },
+        });
     }
     resolveBinding(bindingId, from, path = []) {
         // Sharing an alias borrows its lexical parent graph before following targets.
@@ -262,6 +297,7 @@ class ScopeAcquisitions {
         this.observeAttempt(attempt, 'acquisition-started');
         this.family.enter(attempt);
         const directSource = !description.contextual && !description.operations.length;
+        const { disposers } = execution;
         try {
             let value;
             if (directSource) {
@@ -270,7 +306,7 @@ class ScopeAcquisitions {
                 execution.publishSource(value, description);
             }
             else {
-                value = execution.evaluate(description, deps, () => this.getContext());
+                value = execution.evaluate(description, deps, disposers && this.acquisitionContext(disposers));
             }
             attempt.exposed = value;
             attempt.state = attempt.execution.state;

package/dist/alias-types.d.ts

@@ -6,14 +6,23 @@ import type { Singleton, Unsatisfied } from './types';
 export type AliasSelection = string | TokenBase;
 export type AliasAdmission<T> = Singleton<T> extends true ? unknown : ValidToken<T> extends true ? unknown : Unsatisfied<'alias requires one singleton name or genuine token', {}>;
 export type AliasTarget<R extends Registrations, T> = T extends string ? T extends keyof R ? unknown : Unsatisfied<'alias requires an existing named target', {}> : [WrongToken<T, R>] extends [never] ? unknown : Unsatisfied<'token dependency has an incompatible or opaque contract', {}>;
-/** Resolve the service type exposed by a possible alias target. */
+/**
+ * Resolve the service type exposed by a possible alias target.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#give-a-dependency-another-lookup-name
+ */
 export type AliasOutput<R extends Registrations, T> = T extends string ? T extends keyof R ? ProviderOutput<R[T]> : never : TokenService<T>;
 export type AliasDestination<R extends Registrations, D, T> = D extends TokenBase ? [AliasOutput<R, T>] extends [TokenService<D>] ? unknown : Unsatisfied<'alias output is not assignable to destination service', {}> : unknown;
-/** A provider contract that forwards a destination to a canonical target acquisition. */
+/**
+ * A provider contract that forwards a destination to a canonical target acquisition.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#give-a-dependency-another-lookup-name
+ */
 export type AliasRegistration<R extends Registrations, D, T> = Provider<(this: void, deps: T extends string ? Record<T, AliasOutput<R, T>> : Record<never, never>) => AliasOutput<R, T>, Readonly<object>, readonly unknown[], TokenDependencyContract<T extends TokenBase ? readonly [T] : readonly [], D extends TokenBase ? D : never> & {
     readonly alias: SelectionKey<T>;
 }, unknown>;
-/** The single registration-map entry introduced by an alias operation. */
+/**
+ * The single registration-map entry introduced by an alias operation.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#give-a-dependency-another-lookup-name
+ */
 export type AliasEntries<R extends Registrations, D, T> = Record<SelectionKey<D>, AliasRegistration<R, D, T>>;
 /** Reflected generic methods cannot introduce a checked singleton destination. */
 export type AliasEntry<R extends Registrations, D, T> = unknown extends AliasAdmission<D> & AliasAdmission<T> ? {

package/dist/composition-report.d.ts

@@ -1,13 +1,14 @@
 import type { Builder } from './di-bag';
 import type { CheckedLifetimes } from './lifetime-types';
 import type { CheckedConstraints, CompleteConstraints, NeedConstraint } from './module-types';
-import type { CheckDependencyCompatibility, CheckDependencyCompleteness, Entry, RegistrationsFromEntries } from './types';
+import type { CheckDependencyCompatibility, CheckDependencyCompleteness, ConsumerReport, Entry, RegistrationsFromEntries } from './types';
 type ReportOf<Check> = unknown extends Check ? never : Check;
-type Reports<E extends Entry, C extends NeedConstraint> = ReportOf<CheckDependencyCompatibility<RegistrationsFromEntries<E>>> | ReportOf<CheckDependencyCompleteness<RegistrationsFromEntries<E>>> | ReportOf<CheckedConstraints<C, RegistrationsFromEntries<E>>> | ReportOf<CompleteConstraints<C, RegistrationsFromEntries<E>>> | ReportOf<CheckedLifetimes<RegistrationsFromEntries<E>, C>>;
+type Reports<E extends Entry, C extends NeedConstraint> = ReportOf<ConsumerReport<CheckDependencyCompatibility<RegistrationsFromEntries<E>>>> | ReportOf<CheckDependencyCompleteness<RegistrationsFromEntries<E>>> | ReportOf<ConsumerReport<CheckedConstraints<C, RegistrationsFromEntries<E>>>> | ReportOf<CompleteConstraints<C, RegistrationsFromEntries<E>>> | ReportOf<CheckedLifetimes<RegistrationsFromEntries<E>, C>>;
 /**
  * The compile-time verdict for a builder: `void` when `build()` would be accepted,
  * otherwise the same failure `build()` reports, including its details.
  * Read it through `builder.verifyGraph() satisfies void;` or as `CompositionReport<typeof builder>`.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#read-compile-time-rejections
  */
 export type CompositionReport<B> = B extends Builder<infer E, infer C> ? [Reports<E, C>] extends [never] ? void : Reports<E, C> : never;
 export {};

package/dist/composition.d.ts

@@ -4,12 +4,18 @@ import type { DependencyReference } from './dependency-references';
 import type { TokenArguments, ReferenceGraph, DependencyTupleAdmission } from './token-types';
 import type { Unsatisfied } from './types';
 type OutputFactory<O> = () => O;
-/** Compile-time admission that checks supplied token values against a callable's parameter tuple. */
+/**
+ * Compile-time admission that checks supplied token values against a callable's parameter tuple.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#adapt-classes-and-positional-functions
+ */
 export type CompositionArguments<A extends readonly unknown[], P extends readonly unknown[]> = [A] extends [P] ? unknown : Unsatisfied<'composition arguments must match the declared parameter tuple', {
     supplied: A;
     parameters: P;
 }>;
-/** A receiver-free positional callback matching the values supplied by a dependency tuple. */
+/**
+ * A receiver-free positional callback matching the values supplied by a dependency tuple.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#adapt-classes-and-positional-functions
+ */
 export type CompositionFunction<T extends readonly DependencyReference[], O = unknown> = TokenArguments<T> extends [...infer A] ? (this: void, ...args: A) => O : never;
 /**
  * Adapt a positional function without awaiting its arguments or return value.

package/dist/contribution-types.d.ts

@@ -1,21 +1,25 @@
 import type { Registration, Registrations } from './registration';
 import type { TokenBase, TokenKey, TokenService } from './tokens';
 import type { ValidToken, TokenTupleAdmission, BindingOutput } from './token-types';
-import type { CheckDependencyCompatibility, CheckDependencyCompleteness, Unsatisfied, Entry, RegistrationsFromEntries } from './types';
+import type { CheckDependencyCompatibility, CheckDependencyCompleteness, SeeErrors, Unsatisfied, Entry, RegistrationsFromEntries } from './types';
 import type { ProviderCollectionTokens } from './provider';
 import type { Module } from './module';
 import type { RegistrationConstraints, PublicProvider, NeedConstraint, CheckedConstraints } from './module-types';
-import type { LexicalContext, ModuleScope, Enclosed, RenamedContext } from './lifetime-types';
 declare const contributionSite: unique symbol;
-/** Each union member retains one independently checked provider and its group. */
-export type Contribution<T extends TokenBase = TokenBase, V extends Registration = Registration, L = undefined> = {
+/**
+ * Each union member retains one independently checked provider and its group.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#compose-an-ordered-collection
+ */
+export type Contribution<T extends TokenBase = TokenBase, V extends Registration = Registration> = {
     readonly kind: 'contribution';
     readonly token: T;
     readonly registration: V;
-    readonly context: L;
 };
-/** The erased contribution contract retained by checked builders and modules. */
-export type ContributionConstraint = Contribution<TokenBase, Registration, unknown>;
+/**
+ * The erased contribution contract retained by checked builders and modules.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#compose-an-ordered-collection
+ */
+export type ContributionConstraint = Contribution<TokenBase, Registration>;
 type Groups<C> = Extract<C, ContributionConstraint>;
 type Same<A, B> = [A] extends [B] ? [B] extends [A] ? true : false : false;
 type WrongMember<T, G> = G extends ContributionConstraint ? TokenKey<T> extends TokenKey<G['token']> ? Same<T, G['token']> extends true ? never : TokenKey<T> : never : never;
@@ -33,25 +37,29 @@ type AllNeeds<C, A extends Registrations> = ProviderCollectionTokens<A[keyof A]>
     token: infer T;
 } ? T : never);
 type GroupErrors<C, A extends Registrations> = WrongGroup<Groups<C>['token'] | AllNeeds<C, A>, C>;
-export type CheckedContributions<C, A extends Registrations> = [Groups<C>] extends [never] ? unknown : [GroupErrors<C, A>] extends [never] ? [WrongProvider<C, A>] extends [never] ? unknown : Unsatisfied<'contribution service is incompatible with its consumer dependency contract', {
+export type CheckedContributions<C, A extends Registrations> = [Groups<C>] extends [never] ? unknown : [GroupErrors<C, A>] extends [never] ? [WrongProvider<C, A>] extends [never] ? unknown : Unsatisfied<`contribution service is incompatible with its consumer dependency contract${SeeErrors<'unsatisfied-consumer'>}`, {
     readonly failures: ContributionFailures<WrongProvider<C, A>, A>;
 }> : Unsatisfied<'collection token has an incompatible or opaque contract', {}>;
-export type CompleteContributions<C, A extends Registrations> = [MissingProvider<C, A>] extends [never] ? unknown : Unsatisfied<'required service registrations are missing', {
+export type CompleteContributions<C, A extends Registrations> = [MissingProvider<C, A>] extends [never] ? unknown : Unsatisfied<`required service registrations are missing${SeeErrors<'missing-service'>}`, {
     readonly contributions: MissingProvider<C, A>;
 }>;
 /**
- * Retain a contribution's provider checks and lexical private-service context when
- * its builder seals. A contribution retained from an inner installation is already
- * projected; sealing only encloses its scope in this module's scope.
+ * Retain a contribution's projected provider and its checked needs when its builder seals.
+ * Lifetime reach is retained separately as compact obligations. A contribution retained
+ * from an inner installation is already projected and has no needs left to re-scope.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#compose-an-ordered-collection
+ */
+export type ModuleContributionConstraints<C, R extends Registrations, P extends keyof R> = C extends ContributionConstraint ? Contribution<C['token'], PublicProvider<C['registration']>> | RegistrationConstraints<C['registration'], R, P> : never;
+/**
+ * Project a module's typed-token collections as readonly service arrays.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#compose-an-ordered-collection
  */
-export type ModuleContributionConstraints<C, R extends Registrations, P extends keyof R> = C extends ContributionConstraint ? C['context'] extends LexicalContext ? Contribution<C['token'], C['registration'], Enclosed<C['context'], ModuleScope<R, P>>> : Contribution<C['token'], PublicProvider<C['registration']>, ModuleScope<R, P> & {
-    readonly registration: C['registration'];
-}> | RegistrationConstraints<C['registration'], R, P> : never;
-export type RenamedContribution<C extends ContributionConstraint, Old extends string, New extends string> = C['context'] extends LexicalContext ? Contribution<C['token'], C['registration'], RenamedContext<C['context'], Old, New>> : C;
-/** Project a module's typed-token collections as readonly service arrays. */
 export type ModuleContributions<M> = M extends Module<infer _P, infer _R, infer C, infer _D> ? Readonly<{
     [T in Groups<C>['token'] as TokenKey<T>]: ReadonlyArray<TokenService<T>>;
 }> : never;
-/** The checked generic `contribute` callable exposed by a builder. */
+/**
+ * The checked generic `contribute` callable exposed by a builder.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#compose-an-ordered-collection
+ */
 export type BuilderContribute<E extends Entry, C extends NeedConstraint> = <T extends TokenBase, V extends Registration>(token: T & TokenTupleAdmission<readonly [T]>, registration: V & Registration & BindingOutput<NoInfer<T>, NoInfer<V>> & CheckedConstraints<C | Contribution<NoInfer<T>, NoInfer<V>>, RegistrationsFromEntries<E>>, ...invalid: [T] extends [never] ? [never] : [V] extends [never] ? [never] : []) => import('./di-bag').Builder<E, C | Contribution<T, V>>;
 export {};

package/dist/dependency-references.d.ts

@@ -7,13 +7,25 @@ declare class ReferenceBase {
 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. */
+/**
+ * A positional dependency that yields the token service or `undefined` when unbound.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#declare-optional-and-lazy-dependencies
+ */
 export type OptionalDependency<T extends TokenBase> = DependencyHandle<T, 'optional'>;
-/** A positional dependency that yields all contributions for a token as a readonly array. */
+/**
+ * A positional dependency that yields all contributions for a token as a readonly array.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#compose-an-ordered-collection
+ */
 export type CollectionDependency<T extends TokenBase> = DependencyHandle<T, 'all'>;
-/** A positional dependency that yields a function which resolves the token on demand. */
+/**
+ * A positional dependency that yields a function which resolves the token on demand.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#declare-optional-and-lazy-dependencies
+ */
 export type LazyDependency<T extends TokenBase> = DependencyHandle<T, 'lazy'>;
-/** A typed token or one of the positional dependency-reference handles. */
+/**
+ * A typed token or one of the positional dependency-reference handles.
+ * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#adapt-classes-and-positional-functions
+ */
 export type DependencyReference = TokenBase | ReferenceBase;
 type ReferenceParts<R> = R extends {
     readonly [referenceInvariant]: (...args: never[]) => [infer T extends TokenBase, infer K];