@codefast/di 0.10.1 → 0.12.0

package/dist/{errors/errors.d.ts → 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;
@@ -224,14 +246,16 @@ export declare class MissingContainerContextError extends DiError {
     constructor(className: string | undefined, accessorName: string | symbol);
 }
 /**
- * A second `to*()` on a chain that already registered its binding.
+ * A slot step or a second `to*()` on a chain that already registered its binding.
  *
- * @remarks A chain is its binding, so it registers exactly once; a token bound twice is two `bind()`
- * calls, the second of which displaces the first under slot last-wins.
+ * @remarks A chain is its binding and registers exactly once, in its final shape, so its slot is
+ * settled by `to*()`; a token bound twice is two `bind()` calls, the second of which displaces the
+ * first under slot last-wins.
  *
  * @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,20 +269,22 @@ 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);
 }
 /**
- * A fluent chain was refined before a `to*()` call gave it a binding to refine.
+ * A scope, a lifecycle hook or `id()` asked of a fluent chain before a `to*()` call registered its binding.
  *
  * @remarks The builder types make this unreachable from TypeScript — `bind()` returns
- * `BindToBuilder`, which exposes only `to*()`. It exists for JavaScript callers and for anyone who
- * casts past the types, so the misuse fails loudly instead of mutating nothing.
+ * `BindToBuilder`, which exposes only the slot steps and `to*()`. It exists for JavaScript callers and
+ * for anyone who casts past the types, so the misuse fails loudly instead of mutating nothing.
  *
  * @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 +295,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 +306,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 +321,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 +387,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 → 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,25 +330,27 @@ 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;
     }
 }
 /**
- * A second `to*()` on a chain that already registered its binding.
+ * A slot step or a second `to*()` on a chain that already registered its binding.
  *
- * @remarks A chain is its binding, so it registers exactly once; a token bound twice is two `bind()`
- * calls, the second of which displaces the first under slot last-wins.
+ * @remarks A chain is its binding and registers exactly once, in its final shape, so its slot is
+ * settled by `to*()`; a token bound twice is two `bind()` calls, the second of which displaces the
+ * first under slot last-wins.
  *
  * @since 0.10.0
  */
 export class ChainAlreadyRegisteredError extends DiError {
+    name = "ChainAlreadyRegisteredError";
     code = "CHAIN_ALREADY_REGISTERED";
     tokenName;
     constructor(tokenName) {
-        super(`The binding for token '${tokenName}' is already registered on this chain. Call bind() again to register another binding for the token.`);
+        super(`The binding for token '${tokenName}' is already registered on this chain, so its slot is final. Declare when*() and many() before to*(), or call bind() again to register another binding for the token.`);
         this.tokenName = tokenName;
     }
 }
@@ -341,6 +363,7 @@ export class ChainAlreadyRegisteredError extends DiError {
  * @since 0.10.0
  */
 export class ManyBindingSlotError extends DiError {
+    name = "ManyBindingSlotError";
     code = "MANY_BINDING_SLOT";
     tokenName;
     constructor(tokenName) {
@@ -349,15 +372,16 @@ export class ManyBindingSlotError extends DiError {
     }
 }
 /**
- * A fluent chain was refined before a `to*()` call gave it a binding to refine.
+ * A scope, a lifecycle hook or `id()` asked of a fluent chain before a `to*()` call registered its binding.
  *
  * @remarks The builder types make this unreachable from TypeScript — `bind()` returns
- * `BindToBuilder`, which exposes only `to*()`. It exists for JavaScript callers and for anyone who
- * casts past the types, so the misuse fails loudly instead of mutating nothing.
+ * `BindToBuilder`, which exposes only the slot steps and `to*()`. It exists for JavaScript callers and
+ * for anyone who casts past the types, so the misuse fails loudly instead of mutating nothing.
  *
  * @since 0.10.0
  */
 export class ChainNotRegisteredError extends DiError {
+    name = "ChainNotRegisteredError";
     code = "CHAIN_NOT_REGISTERED";
     tokenName;
     constructor(tokenName) {
@@ -371,6 +395,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 +409,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 +427,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 +437,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 +510,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

@@ -3,30 +3,34 @@ export { token, tokenName } from "#core/token";
 export type { SlotNamesOf, Token } from "#core/token";
 export { coversTagKeys, NO_TAG_KEYS, slotName, tag, tagKeyMaskOf } from "#core/tag";
 export type { TagKey, TagKeyMask } from "#core/tag";
-export type { AliasBindingBuilder, BindToBuilder, BindingBuilder, ConstantBindingBuilder, ScopedBindingBuilder, SingletonBindingBuilder, SingletonLifecycleBuilder, SlotConstrainedBuilder, TransientBindingBuilder, } from "#core/binding";
+export type { AliasBindingBuilder, BindToBuilder, BindingBuilder, ConstantBindingBuilder, ScopedBindingBuilder, SingletonBindingBuilder, SingletonLifecycleBuilder, SlotConstrainedBuilder, TransientBindingBuilder, } from "#core/binding-builders";
 export { Container } from "#container/container";
 export type { Container as ContainerInterface, ContainerOptions, ContainerStatic } from "#container/container";
-export { getActiveContainer, runWithContainer } from "#ambient/active-container";
-export { bindingSlotToResolveOptions, injectionSlotToResolveOptions, resolveOptionsForSlot, } from "#injection/resolve-options";
-export type { DependencySlot } from "#injection/resolve-options";
+export { getActiveContainer, runWithContainer } from "#ambient-container";
+export { bindingSlotToResolveOptions, injectionSlotToResolveOptions, resolveOptionsForSlot, } from "#injection/dependency-slot";
+export type { DependencySlot } from "#injection/dependency-slot";
 export type { BindingSnapshot, ContainerSnapshot } from "#introspection/inspector";
+export type { CandidateExplanation, CandidateVerdict, ExplainOptions, ExplanationOutcome, ExplanationStep, ResolutionExplanation, SelectionRule, } from "#introspection/explanation";
+export type { CandidateRule } from "#resolution/select/candidates";
 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";
 export { injectable } from "#decorators/injectable";
 export type { InjectableDependency, InjectableOptions } from "#decorators/injectable";
-export { postConstruct, preDestroy } from "#decorators/lifecycle-decorators";
+export { postConstruct, preDestroy } from "#decorators/lifecycle";
 export { createAutoRegisterRegistry } from "#decorators/injectable";
 export type { AutoRegisterRegistry } from "#decorators/injectable";
-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 { MetadataReaderToken } from "#metadata/reader-token";
+export type { ConstructorMetadata, LifecycleMetadata, MetadataReader, MutableLifecycleMetadata, ParamMetadata, } from "#metadata/types";
+export { defaultMetadataReader, SymbolMetadataReader } from "#metadata/symbol-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 type { ScopeViolationDetails } 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";
+export type { ScopeViolationDetails } from "#errors";
 export { toDotGraph } from "#introspection/graph-adapters/dot";
 export { toCytoscapeGraph } from "#introspection/graph-adapters/cytoscape";
 export type { CytoscapeEdge, CytoscapeElements, CytoscapeNode } from "#introspection/graph-adapters/cytoscape";