@codefast/di 0.10.1 → 0.11.0

package/dist/errors/errors.d.ts

@@ -7,7 +7,7 @@ import type { BindingIdentifier, BindingScope, ResolveOptions } from "#core/type
  */
 export declare abstract class DiError extends Error {
     abstract readonly code: string;
-    constructor(message: string);
+    abstract readonly name: string;
 }
 /**
  * An internal assertion failure — a library bug, never caller misuse.
@@ -15,6 +15,7 @@ export declare abstract class DiError extends Error {
  * @since 0.3.16-canary.0
  */
 export declare class InternalError extends DiError {
+    readonly name = "InternalError";
     readonly code = "INTERNAL_ERROR";
     constructor(message: string);
 }
@@ -24,6 +25,7 @@ export declare class InternalError extends DiError {
  * @since 0.3.16-canary.0
  */
 export declare class TokenNotBoundError extends DiError {
+    readonly name = "TokenNotBoundError";
     readonly code = "TOKEN_NOT_BOUND";
     readonly tokenName: string;
     constructor(tokenName: string);
@@ -34,6 +36,7 @@ export declare class TokenNotBoundError extends DiError {
  * @since 0.3.16-canary.0
  */
 export declare class NoMatchingBindingError extends DiError {
+    readonly name = "NoMatchingBindingError";
     readonly code = "NO_MATCHING_BINDING";
     readonly tokenName: string;
     readonly options: ResolveOptions;
@@ -46,6 +49,7 @@ export declare class NoMatchingBindingError extends DiError {
  * @since 0.3.16-canary.0
  */
 export declare class AmbiguousBindingError extends DiError {
+    readonly name = "AmbiguousBindingError";
     readonly code = "AMBIGUOUS_BINDING";
     readonly tokenName: string;
     readonly candidateIds: ReadonlyArray<BindingIdentifier>;
@@ -57,6 +61,7 @@ export declare class AmbiguousBindingError extends DiError {
  * @since 0.3.16-canary.0
  */
 export declare class CircularDependencyError extends DiError {
+    readonly name = "CircularDependencyError";
     readonly code = "CIRCULAR_DEPENDENCY";
     readonly cycle: Array<string>;
     constructor(cycle: Array<string>);
@@ -67,6 +72,7 @@ export declare class CircularDependencyError extends DiError {
  * @since 0.3.16-canary.0
  */
 export declare class AsyncResolutionError extends DiError {
+    readonly name = "AsyncResolutionError";
     readonly code = "ASYNC_RESOLUTION";
     /** The token the caller asked for — what `resolveAsync` has to be called with. */
     readonly tokenName: string;
@@ -80,6 +86,7 @@ export declare class AsyncResolutionError extends DiError {
  * @since 0.3.16-canary.0
  */
 export declare class AsyncDeactivationError extends DiError {
+    readonly name = "AsyncDeactivationError";
     readonly code = "ASYNC_DEACTIVATION";
     readonly tokenName: string;
     constructor(tokenName: string);
@@ -102,6 +109,7 @@ export interface ScopeViolationDetails {
  * @since 0.3.16-canary.0
  */
 export declare class ScopeViolationError extends DiError {
+    readonly name = "ScopeViolationError";
     readonly code = "SCOPE_VIOLATION";
     readonly details: ScopeViolationDetails;
     constructor(details: ScopeViolationDetails);
@@ -116,6 +124,7 @@ export declare class ScopeViolationError extends DiError {
  * @since 0.6.0
  */
 export declare class EmptyTagCriteriaError extends DiError {
+    readonly name = "EmptyTagCriteriaError";
     readonly code = "EMPTY_TAG_CRITERIA";
     readonly helperName: string;
     constructor(helperName: string);
@@ -130,6 +139,7 @@ export declare class EmptyTagCriteriaError extends DiError {
  * @since 0.6.0
  */
 export declare class UnreachableConstraintError extends DiError {
+    readonly name = "UnreachableConstraintError";
     readonly code = "UNREACHABLE_CONSTRAINT";
     readonly tokenName: string;
     readonly requiredName: string;
@@ -148,10 +158,13 @@ export declare class UnreachableConstraintError extends DiError {
  * @since 0.6.0
  */
 export declare class UnreachableLifecycleHookError extends DiError {
+    readonly name = "UnreachableLifecycleHookError";
     readonly code = "UNREACHABLE_LIFECYCLE_HOOK";
     readonly tokenName: string;
     readonly phase: "onActivation" | "onDeactivation";
-    constructor(tokenName: string, phase: "onActivation" | "onDeactivation");
+    /** Nothing binds the token, or — for a deactivation hook — every binding it has is transient or scoped. */
+    readonly reason: "unbound" | "no-deactivatable-binding";
+    constructor(tokenName: string, phase: "onActivation" | "onDeactivation", reason?: "unbound" | "no-deactivatable-binding");
 }
 /**
  * A {@link MetadataReader} described a class with something the container cannot use.
@@ -163,6 +176,7 @@ export declare class UnreachableLifecycleHookError extends DiError {
  * @since 0.6.0
  */
 export declare class InvalidMetadataError extends DiError {
+    readonly name = "InvalidMetadataError";
     readonly code = "INVALID_METADATA";
     readonly targetName: string;
     readonly reason: string;
@@ -174,9 +188,13 @@ export declare class InvalidMetadataError extends DiError {
  * @since 0.3.16-canary.0
  */
 export declare class MissingMetadataError extends DiError {
+    readonly name = "MissingMetadataError";
     readonly code = "MISSING_METADATA";
     readonly targetName: string;
-    constructor(targetName: string);
+    constructor(targetName: string, inheritedFrom?: {
+        readonly baseName: string;
+        readonly dependencyCount: number;
+    });
 }
 /**
  * A sync `load()` given a module that needs async setup.
@@ -184,6 +202,7 @@ export declare class MissingMetadataError extends DiError {
  * @since 0.3.16-canary.0
  */
 export declare class AsyncModuleLoadError extends DiError {
+    readonly name = "AsyncModuleLoadError";
     readonly code = "ASYNC_MODULE_LOAD";
     readonly moduleName: string;
     constructor(moduleName: string);
@@ -194,6 +213,7 @@ export declare class AsyncModuleLoadError extends DiError {
  * @since 0.3.16-canary.0
  */
 export declare class SyncDisposalNotSupportedError extends DiError {
+    readonly name = "SyncDisposalNotSupportedError";
     readonly code = "SYNC_DISPOSAL_NOT_SUPPORTED";
     constructor();
 }
@@ -203,6 +223,7 @@ export declare class SyncDisposalNotSupportedError extends DiError {
  * @since 0.3.16-canary.0
  */
 export declare class MissingScopeContextError extends DiError {
+    readonly name = "MissingScopeContextError";
     readonly code = "MISSING_SCOPE_CONTEXT";
     readonly tokenName: string;
     constructor(tokenName: string);
@@ -217,6 +238,7 @@ export declare class MissingScopeContextError extends DiError {
  * @since 0.3.16-canary.0
  */
 export declare class MissingContainerContextError extends DiError {
+    readonly name = "MissingContainerContextError";
     readonly code = "MISSING_CONTAINER_CONTEXT";
     /** The class being constructed, or `undefined` when it has no readable name. */
     readonly className: string | undefined;
@@ -232,6 +254,7 @@ export declare class MissingContainerContextError extends DiError {
  * @since 0.10.0
  */
 export declare class ChainAlreadyRegisteredError extends DiError {
+    readonly name = "ChainAlreadyRegisteredError";
     readonly code = "CHAIN_ALREADY_REGISTERED";
     readonly tokenName: string;
     constructor(tokenName: string);
@@ -245,6 +268,7 @@ export declare class ChainAlreadyRegisteredError extends DiError {
  * @since 0.10.0
  */
 export declare class ManyBindingSlotError extends DiError {
+    readonly name = "ManyBindingSlotError";
     readonly code = "MANY_BINDING_SLOT";
     readonly tokenName: string;
     constructor(tokenName: string);
@@ -259,6 +283,7 @@ export declare class ManyBindingSlotError extends DiError {
  * @since 0.10.0
  */
 export declare class ChainNotRegisteredError extends DiError {
+    readonly name = "ChainNotRegisteredError";
     readonly code = "CHAIN_NOT_REGISTERED";
     readonly tokenName: string;
     constructor(tokenName: string);
@@ -269,6 +294,7 @@ export declare class ChainNotRegisteredError extends DiError {
  * @since 0.3.16-canary.0
  */
 export declare class RebindUnboundTokenError extends DiError {
+    readonly name = "RebindUnboundTokenError";
     readonly code = "REBIND_UNBOUND_TOKEN";
     readonly tokenName: string;
     constructor(tokenName: string);
@@ -279,6 +305,7 @@ export declare class RebindUnboundTokenError extends DiError {
  * @since 0.5.0-canary.9
  */
 export declare class SelfBindingRequiresClassError extends DiError {
+    readonly name = "SelfBindingRequiresClassError";
     readonly code = "SELF_BINDING_REQUIRES_CLASS";
     readonly tokenName: string;
     constructor(tokenName: string);
@@ -293,17 +320,63 @@ export declare class SelfBindingRequiresClassError extends DiError {
  * @since 0.6.0
  */
 export declare class StaticMemberDecoratorError extends DiError {
+    readonly name = "StaticMemberDecoratorError";
     readonly code = "STATIC_MEMBER_DECORATOR";
     readonly decoratorName: string;
     readonly memberName: string;
     constructor(decoratorName: string, memberName: string);
 }
+/**
+ * A `@postConstruct` or `@preDestroy` on a method whose key is a symbol, which the lifecycle reader cannot name.
+ *
+ * @remarks Reported at decoration rather than at resolve, so the error points at the declaration
+ * instead of a `MetadataReader` the caller never configured.
+ *
+ * @since 0.11.0
+ */
+export declare class SymbolKeyedLifecycleError extends DiError {
+    readonly name = "SymbolKeyedLifecycleError";
+    readonly code = "SYMBOL_KEYED_LIFECYCLE";
+    readonly decoratorName: string;
+    readonly memberName: string;
+    constructor(decoratorName: string, memberName: string);
+}
+/**
+ * A decorator handed no metadata object, because the runtime has no `Symbol.metadata` to key one by.
+ *
+ * @remarks TypeScript compiles `context.metadata` to `undefined` when `Symbol.metadata` is missing, so
+ * the fix is installing it before any decorated class is defined — the key this library reads.
+ *
+ * @since 0.11.0
+ */
+export declare class MissingDecoratorMetadataError extends DiError {
+    readonly name = "MissingDecoratorMetadataError";
+    readonly code = "MISSING_DECORATOR_METADATA";
+    readonly decoratorName: string;
+    constructor(decoratorName: string);
+}
+/**
+ * A `binding()` definition no chain could spell: no strategy, several, or a key its strategy does not allow.
+ *
+ * @remarks Raised where the declaration is written, for callers the compiler cannot reach, so a
+ * declared module that was built can always be loaded.
+ *
+ * @since 0.11.0
+ */
+export declare class InvalidBindingDeclarationError extends DiError {
+    readonly name = "InvalidBindingDeclarationError";
+    readonly code = "INVALID_BINDING_DECLARATION";
+    readonly tokenName: string;
+    readonly reason: string;
+    constructor(tokenName: string, reason: string);
+}
 /**
  * An operation attempted on a container that has already been disposed.
  *
  * @since 0.3.16-canary.0
  */
 export declare class DisposedContainerError extends DiError {
+    readonly name = "DisposedContainerError";
     readonly code = "DISPOSED_CONTAINER";
     constructor();
 }
@@ -313,6 +386,7 @@ export declare class DisposedContainerError extends DiError {
  * @since 0.3.16-canary.0
  */
 export declare class AsyncActivationError extends DiError {
+    readonly name = "AsyncActivationError";
     readonly code = "ASYNC_ACTIVATION";
     readonly tokenName: string;
     readonly hookKind: "postConstruct" | "onActivation";

package/dist/errors/errors.js

@@ -5,10 +5,6 @@ import { slotName } from "#core/tag";
  * @since 0.3.16-canary.0
  */
 export class DiError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = this.constructor.name;
-    }
 }
 /**
  * An internal assertion failure — a library bug, never caller misuse.
@@ -16,6 +12,7 @@ export class DiError extends Error {
  * @since 0.3.16-canary.0
  */
 export class InternalError extends DiError {
+    name = "InternalError";
     code = "INTERNAL_ERROR";
     constructor(message) {
         super(message);
@@ -27,6 +24,7 @@ export class InternalError extends DiError {
  * @since 0.3.16-canary.0
  */
 export class TokenNotBoundError extends DiError {
+    name = "TokenNotBoundError";
     code = "TOKEN_NOT_BOUND";
     tokenName;
     constructor(tokenName) {
@@ -75,6 +73,7 @@ function describeResolveOptions(options) {
  * @since 0.3.16-canary.0
  */
 export class NoMatchingBindingError extends DiError {
+    name = "NoMatchingBindingError";
     code = "NO_MATCHING_BINDING";
     tokenName;
     options;
@@ -94,6 +93,7 @@ export class NoMatchingBindingError extends DiError {
  * @since 0.3.16-canary.0
  */
 export class AmbiguousBindingError extends DiError {
+    name = "AmbiguousBindingError";
     code = "AMBIGUOUS_BINDING";
     tokenName;
     candidateIds;
@@ -109,6 +109,7 @@ export class AmbiguousBindingError extends DiError {
  * @since 0.3.16-canary.0
  */
 export class CircularDependencyError extends DiError {
+    name = "CircularDependencyError";
     code = "CIRCULAR_DEPENDENCY";
     cycle;
     constructor(cycle) {
@@ -122,6 +123,7 @@ export class CircularDependencyError extends DiError {
  * @since 0.3.16-canary.0
  */
 export class AsyncResolutionError extends DiError {
+    name = "AsyncResolutionError";
     code = "ASYNC_RESOLUTION";
     /** The token the caller asked for — what `resolveAsync` has to be called with. */
     tokenName;
@@ -141,6 +143,7 @@ export class AsyncResolutionError extends DiError {
  * @since 0.3.16-canary.0
  */
 export class AsyncDeactivationError extends DiError {
+    name = "AsyncDeactivationError";
     code = "ASYNC_DEACTIVATION";
     tokenName;
     constructor(tokenName) {
@@ -154,6 +157,7 @@ export class AsyncDeactivationError extends DiError {
  * @since 0.3.16-canary.0
  */
 export class ScopeViolationError extends DiError {
+    name = "ScopeViolationError";
     code = "SCOPE_VIOLATION";
     details;
     constructor(details) {
@@ -171,6 +175,7 @@ export class ScopeViolationError extends DiError {
  * @since 0.6.0
  */
 export class EmptyTagCriteriaError extends DiError {
+    name = "EmptyTagCriteriaError";
     code = "EMPTY_TAG_CRITERIA";
     helperName;
     constructor(helperName) {
@@ -188,6 +193,7 @@ export class EmptyTagCriteriaError extends DiError {
  * @since 0.6.0
  */
 export class UnreachableConstraintError extends DiError {
+    name = "UnreachableConstraintError";
     code = "UNREACHABLE_CONSTRAINT";
     tokenName;
     requiredName;
@@ -215,13 +221,19 @@ export class UnreachableConstraintError extends DiError {
  * @since 0.6.0
  */
 export class UnreachableLifecycleHookError extends DiError {
+    name = "UnreachableLifecycleHookError";
     code = "UNREACHABLE_LIFECYCLE_HOOK";
     tokenName;
     phase;
-    constructor(tokenName, phase) {
-        super(`${phase}() is registered for '${tokenName}', which nothing is bound to in this container or its ancestors, so the hook can never run. Bind the token, or — if '${tokenName}' is a class you bound as an implementation via .to(${tokenName}) — register the hook against the token you bound instead.`);
+    /** Nothing binds the token, or — for a deactivation hook — every binding it has is transient or scoped. */
+    reason;
+    constructor(tokenName, phase, reason = "unbound") {
+        super(reason === "unbound"
+            ? `${phase}() is registered for '${tokenName}', which nothing is bound to in this container or its ancestors, so the hook can never run. Bind the token, or — if '${tokenName}' is a class you bound as an implementation via .to(${tokenName}) — register the hook against the token you bound instead.`
+            : `${phase}() is registered for '${tokenName}', whose every binding in this container and its ancestors is transient or scoped, so the hook can never run: only a singleton or a constant is deactivated. Make one of its bindings a singleton, or drop the hook.`);
         this.tokenName = tokenName;
         this.phase = phase;
+        this.reason = reason;
     }
 }
 /**
@@ -234,6 +246,7 @@ export class UnreachableLifecycleHookError extends DiError {
  * @since 0.6.0
  */
 export class InvalidMetadataError extends DiError {
+    name = "InvalidMetadataError";
     code = "INVALID_METADATA";
     targetName;
     reason;
@@ -249,10 +262,13 @@ export class InvalidMetadataError extends DiError {
  * @since 0.3.16-canary.0
  */
 export class MissingMetadataError extends DiError {
+    name = "MissingMetadataError";
     code = "MISSING_METADATA";
     targetName;
-    constructor(targetName) {
-        super(`Class '${targetName}' is missing @injectable() decorator. Add @injectable([...deps]) or use toDynamic()/toResolved() instead.`);
+    constructor(targetName, inheritedFrom) {
+        super(inheritedFrom === undefined
+            ? `Class '${targetName}' is missing @injectable() decorator. Add @injectable([...deps]) or use toDynamic()/toResolved() instead.`
+            : `Class '${targetName}' inherits ${String(inheritedFrom.dependencyCount)} declared constructor ${inheritedFrom.dependencyCount === 1 ? "dependency" : "dependencies"} from '${inheritedFrom.baseName}' but declares none of its own. Add @injectable([...deps]) to '${targetName}' — @injectable([]) if it takes none — or bind it with toDynamic()/toResolved().`);
         this.targetName = targetName;
     }
 }
@@ -262,6 +278,7 @@ export class MissingMetadataError extends DiError {
  * @since 0.3.16-canary.0
  */
 export class AsyncModuleLoadError extends DiError {
+    name = "AsyncModuleLoadError";
     code = "ASYNC_MODULE_LOAD";
     moduleName;
     constructor(moduleName) {
@@ -275,6 +292,7 @@ export class AsyncModuleLoadError extends DiError {
  * @since 0.3.16-canary.0
  */
 export class SyncDisposalNotSupportedError extends DiError {
+    name = "SyncDisposalNotSupportedError";
     code = "SYNC_DISPOSAL_NOT_SUPPORTED";
     constructor() {
         super("Container cannot be disposed synchronously because onDeactivation handlers may be async. Use `await using` or call container.dispose() explicitly.");
@@ -286,6 +304,7 @@ export class SyncDisposalNotSupportedError extends DiError {
  * @since 0.3.16-canary.0
  */
 export class MissingScopeContextError extends DiError {
+    name = "MissingScopeContextError";
     code = "MISSING_SCOPE_CONTEXT";
     tokenName;
     constructor(tokenName) {
@@ -303,6 +322,7 @@ export class MissingScopeContextError extends DiError {
  * @since 0.3.16-canary.0
  */
 export class MissingContainerContextError extends DiError {
+    name = "MissingContainerContextError";
     code = "MISSING_CONTAINER_CONTEXT";
     /** The class being constructed, or `undefined` when it has no readable name. */
     className;
@@ -310,8 +330,8 @@ export class MissingContainerContextError extends DiError {
     constructor(className, accessorName) {
         const accessor = `@inject accessor '${String(accessorName)}'`;
         super(className === undefined
-            ? `An ${accessor} was initialized outside a container context. Resolve its class through a container, or open a context with runWithContainer().`
-            : `Class '${className}' has an ${accessor} but was constructed outside a container context. Resolve it via container.resolve(${className}), or open a context with runWithContainer().`);
+            ? `An ${accessor} was initialized outside a container context. Resolve its class through a container, or open a synchronous context with runWithContainer() (the context does not survive an await).`
+            : `Class '${className}' has an ${accessor} but was constructed outside a container context. Resolve it via container.resolve(${className}), or open a synchronous context with runWithContainer() (the context does not survive an await).`);
         this.className = className;
         this.accessorName = accessorName;
     }
@@ -325,6 +345,7 @@ export class MissingContainerContextError extends DiError {
  * @since 0.10.0
  */
 export class ChainAlreadyRegisteredError extends DiError {
+    name = "ChainAlreadyRegisteredError";
     code = "CHAIN_ALREADY_REGISTERED";
     tokenName;
     constructor(tokenName) {
@@ -341,6 +362,7 @@ export class ChainAlreadyRegisteredError extends DiError {
  * @since 0.10.0
  */
 export class ManyBindingSlotError extends DiError {
+    name = "ManyBindingSlotError";
     code = "MANY_BINDING_SLOT";
     tokenName;
     constructor(tokenName) {
@@ -358,6 +380,7 @@ export class ManyBindingSlotError extends DiError {
  * @since 0.10.0
  */
 export class ChainNotRegisteredError extends DiError {
+    name = "ChainNotRegisteredError";
     code = "CHAIN_NOT_REGISTERED";
     tokenName;
     constructor(tokenName) {
@@ -371,6 +394,7 @@ export class ChainNotRegisteredError extends DiError {
  * @since 0.3.16-canary.0
  */
 export class RebindUnboundTokenError extends DiError {
+    name = "RebindUnboundTokenError";
     code = "REBIND_UNBOUND_TOKEN";
     tokenName;
     constructor(tokenName) {
@@ -384,6 +408,7 @@ export class RebindUnboundTokenError extends DiError {
  * @since 0.5.0-canary.9
  */
 export class SelfBindingRequiresClassError extends DiError {
+    name = "SelfBindingRequiresClassError";
     code = "SELF_BINDING_REQUIRES_CLASS";
     tokenName;
     constructor(tokenName) {
@@ -401,6 +426,7 @@ export class SelfBindingRequiresClassError extends DiError {
  * @since 0.6.0
  */
 export class StaticMemberDecoratorError extends DiError {
+    name = "StaticMemberDecoratorError";
     code = "STATIC_MEMBER_DECORATOR";
     decoratorName;
     memberName;
@@ -410,12 +436,68 @@ export class StaticMemberDecoratorError extends DiError {
         this.memberName = memberName;
     }
 }
+/**
+ * A `@postConstruct` or `@preDestroy` on a method whose key is a symbol, which the lifecycle reader cannot name.
+ *
+ * @remarks Reported at decoration rather than at resolve, so the error points at the declaration
+ * instead of a `MetadataReader` the caller never configured.
+ *
+ * @since 0.11.0
+ */
+export class SymbolKeyedLifecycleError extends DiError {
+    name = "SymbolKeyedLifecycleError";
+    code = "SYMBOL_KEYED_LIFECYCLE";
+    decoratorName;
+    memberName;
+    constructor(decoratorName, memberName) {
+        super(`@${decoratorName}() does not support a symbol-keyed method ('${memberName}'). Give the lifecycle method a string name.`);
+        this.decoratorName = decoratorName;
+        this.memberName = memberName;
+    }
+}
+/**
+ * A decorator handed no metadata object, because the runtime has no `Symbol.metadata` to key one by.
+ *
+ * @remarks TypeScript compiles `context.metadata` to `undefined` when `Symbol.metadata` is missing, so
+ * the fix is installing it before any decorated class is defined — the key this library reads.
+ *
+ * @since 0.11.0
+ */
+export class MissingDecoratorMetadataError extends DiError {
+    name = "MissingDecoratorMetadataError";
+    code = "MISSING_DECORATOR_METADATA";
+    decoratorName;
+    constructor(decoratorName) {
+        super(`@${decoratorName}() received no decorator metadata: this runtime has no Symbol.metadata. Install it before any decorated class is defined, e.g. in a module imported first: (Symbol as { metadata?: symbol }).metadata ??= Symbol.for("Symbol.metadata");`);
+        this.decoratorName = decoratorName;
+    }
+}
+/**
+ * A `binding()` definition no chain could spell: no strategy, several, or a key its strategy does not allow.
+ *
+ * @remarks Raised where the declaration is written, for callers the compiler cannot reach, so a
+ * declared module that was built can always be loaded.
+ *
+ * @since 0.11.0
+ */
+export class InvalidBindingDeclarationError extends DiError {
+    name = "InvalidBindingDeclarationError";
+    code = "INVALID_BINDING_DECLARATION";
+    tokenName;
+    reason;
+    constructor(tokenName, reason) {
+        super(`Invalid binding declaration for '${tokenName}': ${reason}.`);
+        this.tokenName = tokenName;
+        this.reason = reason;
+    }
+}
 /**
  * An operation attempted on a container that has already been disposed.
  *
  * @since 0.3.16-canary.0
  */
 export class DisposedContainerError extends DiError {
+    name = "DisposedContainerError";
     code = "DISPOSED_CONTAINER";
     constructor() {
         super("Cannot perform operations on a disposed container.");
@@ -427,6 +509,7 @@ export class DisposedContainerError extends DiError {
  * @since 0.3.16-canary.0
  */
 export class AsyncActivationError extends DiError {
+    name = "AsyncActivationError";
     code = "ASYNC_ACTIVATION";
     tokenName;
     hookKind;

package/dist/index.d.ts

@@ -13,6 +13,8 @@ export type { BindingSnapshot, ContainerSnapshot } from "#introspection/inspecto
 export type { ContainerGraphJson, GraphEdge, GraphNode, GraphOptions } from "#introspection/dependency-graph";
 export { AsyncModule, isSyncModule, Module, SyncModule } from "#core/module";
 export type { AsyncModuleBuilder, ModuleBuilder } from "#core/module";
+export { binding } from "#core/binding-declaration";
+export type { BindingDeclaration, BindingDefinition } from "#core/binding-declaration";
 export { inject } from "#decorators/inject";
 export { injectAll, isInjectionDescriptor, optional } from "#injection/descriptor";
 export type { InjectionDescriptor, InjectOptions } from "#injection/descriptor";
@@ -25,7 +27,7 @@ export { MetadataReaderToken } from "#metadata/metadata-reader-token";
 export type { ConstructorMetadata, LifecycleMetadata, MetadataReader, MutableLifecycleMetadata, ParamMetadata, } from "#metadata/metadata-types";
 export { defaultMetadataReader, SymbolMetadataReader } from "#metadata/symbol-metadata-reader";
 export { whenAnyAncestorIs, whenAnyAncestorNamed, whenAnyAncestorTagged, whenAnyAncestorTaggedAll, whenNoAncestorIs, whenNoParentIs, whenParentIs, whenParentNamed, whenParentTagged, whenParentTaggedAll, } from "#resolution/select/constraints";
-export { AmbiguousBindingError, AsyncActivationError, AsyncDeactivationError, AsyncModuleLoadError, AsyncResolutionError, ChainAlreadyRegisteredError, ChainNotRegisteredError, ManyBindingSlotError, CircularDependencyError, DiError, DisposedContainerError, InternalError, InvalidMetadataError, MissingContainerContextError, MissingMetadataError, MissingScopeContextError, NoMatchingBindingError, RebindUnboundTokenError, ScopeViolationError, SelfBindingRequiresClassError, StaticMemberDecoratorError, SyncDisposalNotSupportedError, EmptyTagCriteriaError, TokenNotBoundError, UnreachableConstraintError, UnreachableLifecycleHookError, } from "#errors/errors";
+export { AmbiguousBindingError, AsyncActivationError, AsyncDeactivationError, AsyncModuleLoadError, AsyncResolutionError, ChainAlreadyRegisteredError, ChainNotRegisteredError, ManyBindingSlotError, CircularDependencyError, DiError, DisposedContainerError, InternalError, InvalidBindingDeclarationError, InvalidMetadataError, MissingContainerContextError, MissingDecoratorMetadataError, MissingMetadataError, MissingScopeContextError, NoMatchingBindingError, RebindUnboundTokenError, ScopeViolationError, SelfBindingRequiresClassError, StaticMemberDecoratorError, SymbolKeyedLifecycleError, SyncDisposalNotSupportedError, EmptyTagCriteriaError, TokenNotBoundError, UnreachableConstraintError, UnreachableLifecycleHookError, } from "#errors/errors";
 export type { ScopeViolationDetails } from "#errors/errors";
 export { toDotGraph } from "#introspection/graph-adapters/dot";
 export { toCytoscapeGraph } from "#introspection/graph-adapters/cytoscape";

package/dist/index.js

@@ -12,6 +12,7 @@ export { getActiveContainer, runWithContainer } from "#ambient/active-container"
 export { bindingSlotToResolveOptions, injectionSlotToResolveOptions, resolveOptionsForSlot, } from "#injection/resolve-options";
 // Module
 export { AsyncModule, isSyncModule, Module, SyncModule } from "#core/module";
+export { binding } from "#core/binding-declaration";
 // Decorators
 export { inject } from "#decorators/inject";
 export { injectAll, isInjectionDescriptor, optional } from "#injection/descriptor";
@@ -25,7 +26,7 @@ export { defaultMetadataReader, SymbolMetadataReader } from "#metadata/symbol-me
 // Constraints — contextual injection predicates for .when()
 export { whenAnyAncestorIs, whenAnyAncestorNamed, whenAnyAncestorTagged, whenAnyAncestorTaggedAll, whenNoAncestorIs, whenNoParentIs, whenParentIs, whenParentNamed, whenParentTagged, whenParentTaggedAll, } from "#resolution/select/constraints";
 // Errors
-export { AmbiguousBindingError, AsyncActivationError, AsyncDeactivationError, AsyncModuleLoadError, AsyncResolutionError, ChainAlreadyRegisteredError, ChainNotRegisteredError, ManyBindingSlotError, CircularDependencyError, DiError, DisposedContainerError, InternalError, InvalidMetadataError, MissingContainerContextError, MissingMetadataError, MissingScopeContextError, NoMatchingBindingError, RebindUnboundTokenError, ScopeViolationError, SelfBindingRequiresClassError, StaticMemberDecoratorError, SyncDisposalNotSupportedError, EmptyTagCriteriaError, TokenNotBoundError, UnreachableConstraintError, UnreachableLifecycleHookError, } from "#errors/errors";
+export { AmbiguousBindingError, AsyncActivationError, AsyncDeactivationError, AsyncModuleLoadError, AsyncResolutionError, ChainAlreadyRegisteredError, ChainNotRegisteredError, ManyBindingSlotError, CircularDependencyError, DiError, DisposedContainerError, InternalError, InvalidBindingDeclarationError, InvalidMetadataError, MissingContainerContextError, MissingDecoratorMetadataError, MissingMetadataError, MissingScopeContextError, NoMatchingBindingError, RebindUnboundTokenError, ScopeViolationError, SelfBindingRequiresClassError, StaticMemberDecoratorError, SymbolKeyedLifecycleError, SyncDisposalNotSupportedError, EmptyTagCriteriaError, TokenNotBoundError, UnreachableConstraintError, UnreachableLifecycleHookError, } from "#errors/errors";
 // Graph adapters — render `generateDependencyGraph()` output for common viewers
 export { toDotGraph } from "#introspection/graph-adapters/dot";
 export { toCytoscapeGraph } from "#introspection/graph-adapters/cytoscape";

package/dist/injection/descriptor.js

@@ -4,12 +4,8 @@
  * @since 0.3.16-canary.0
  */
 export function isInjectionDescriptor(value) {
-    if (value === null || value === undefined) {
-        return false;
-    }
-    const type = typeof value;
-    // inject() returns a function (dual-role), so must check both object and function
-    if (type !== "object" && type !== "function") {
+    // inject() returns a function (dual-role), so both an object and a function qualify.
+    if ((typeof value !== "object" && typeof value !== "function") || value === null) {
         return false;
     }
     return ("token" in value &&
@@ -106,7 +102,7 @@ export function buildInjectionDescriptor(token, options) {
  */
 export function optional(token, options) {
     return withOptions({
-        token: token,
+        token,
         optional: true,
         multi: false,
     }, options);

package/dist/injection/resolve-options.js

@@ -49,15 +49,17 @@ function loneNameCriterionOf(options) {
 }
 /** Shared core: build a ResolveOptions from already-normalised name + tags. */
 function buildOptions(name, tags) {
-    if (name === undefined && tags === undefined) {
+    // An empty criterion list selects nothing, so it states no criterion at all.
+    const criteria = tags !== undefined && tags.length > 0 ? tags : undefined;
+    if (name === undefined && criteria === undefined) {
         return undefined;
     }
     const options = {};
     if (name !== undefined) {
         options.name = name;
     }
-    if (tags !== undefined) {
-        options.tags = tags;
+    if (criteria !== undefined) {
+        options.tags = criteria;
     }
     return options;
 }
@@ -85,7 +87,7 @@ const MEMOIZED_SINGLE_CRITERION = Symbol("di:single-criterion");
  */
 export function resolveOptionsForSlot(injectionSlot) {
     const { name, tags } = injectionSlot;
-    if (name === undefined && tags === undefined) {
+    if (name === undefined && (tags === undefined || tags.length === 0)) {
         return undefined;
     }
     const slot = injectionSlot;

package/dist/introspection/dependency-graph.d.ts

@@ -49,8 +49,13 @@ export interface GraphOptions {
     readonly includeParent?: boolean | undefined;
 }
 /**
- * Builds the JSON dependency graph of a registry's bindings, optionally including the parent's.
+ * Builds the JSON dependency graph of a registry's bindings, optionally including its ancestors'.
+ *
+ * @param registry - The registry whose bindings the graph is for.
+ * @param metadataReader - The reader class dependencies are read through.
+ * @param options - Whether the ancestors' bindings join the graph.
+ * @param ancestorRegistries - The ancestor containers' registries, nearest first.
  *
  * @since 0.3.16-canary.0
  */
-export declare function buildDependencyGraph(registry: BindingRegistry, metadataReader: MetadataReader, options: GraphOptions | undefined, parentRegistry?: BindingRegistry): ContainerGraphJson;
+export declare function buildDependencyGraph(registry: BindingRegistry, metadataReader: MetadataReader, options: GraphOptions | undefined, ancestorRegistries?: ReadonlyArray<BindingRegistry>): ContainerGraphJson;