Error hierarchy

Mental model. Every error the library throws extends one abstract class, DiError, and carries a machine-readable code plus the context fields a human needs to act. A catch (error) { if (error instanceof DiError) … } catches all of them; a switch on code tells them apart without string-matching messages.

Normative. Every error extends DiError — an abstract class that forces each subclass to declare a code string (machine-readable), alongside a message carrying enough context for a human reader.

Exact shape: src/errors.ts — every class above, plus ScopeViolationDetails.

A message names what went wrong and, where the library can know it, the way out — every misuse error does; a few report a state rather than a remedy (CircularDependencyError names the cycle, ScopeViolationError the path, DisposedContainerError the disposal). Two representative examples:

No binding for 'app:Logger' matching {"name":"file"}. Available slots: [default, name:console].

Token 'app:Api' requires async resolution because 'app:Database' in its dependency
chain has an async factory. Use container.resolveAsync(app:Api).

TokenNotBoundError and NoMatchingBindingError carry path: the token names from the outermost request down to the one that missed, alias hops included — [tokenName] for a miss on the token asked for, which the message then leaves out. Their message ends with Path: a → b → c otherwise. validate() raises both, and CircularDependencyError, for a singleton graph that cannot resolve, with the path from that singleton.

ScopeViolationError is raised by validate() alone: a resolve does not check scopes, so a singleton that captures a transient resolves silently, and one that captures a scoped binding from the root fails with MissingScopeContextError instead.

The boundary between a library bug and a caller error

Normative. InternalError means the library is broken — a consumer catching one has caught a library bug. No user-caused error may therefore carry that type.

Three errors in the table exist precisely because of that rule: AmbiguousBindingError (predicates that do not exclude each other), StaticMemberDecoratorError, and ChainNotRegisteredError — each is caller misuse, so each has its own type rather than InternalError.

Errors for callers outside the type system. ChainNotRegisteredError and SelfBindingRequiresClassError are nearly unreachable from TypeScript: the chain's return types (Fluent chain) and the type of bind() already block most of the way. They exist for JavaScript callers, or callers who have cast through the types — so that misuse fails loudly instead of silently doing nothing — and they belong to the DiError taxonomy so that a catch (error) { if (error instanceof DiError) … } does not let them escape.

Why static members are an error. StaticMemberDecoratorError exists because all three of those decorators act on an instance: @inject resolves through the container active while the instance is being constructed, and @postConstruct/@preDestroy bracket one instance's lifecycle. A static member belongs to the class, and the container does not construct classes.

MissingMetadataError vs InvalidMetadataError

Missing metadata is a class the container was never told about; invalid metadata is a reader answering wrongly.

Normative.

• Only a user-supplied reader is checked — the default decorator reader writes the very metadata it reads back, so there is nothing to check, and a container given no custom reader has nothing to answer for.
• The check runs once per (reader, class) pair per process, and only over the fields the consumer dereferences (params, and each entry's token).
• The lifecycle answer also lands in InvalidMetadataError, with a different reason: if the reader names a postConstruct/preDestroy method the instance does not have, it is reported ("lifecycle method 'strat' is not a method on the instance") rather than swallowed. The class name is taken from the instance itself at the throw site, so the happy path carries no extra argument.

A silently skipped hook is a failure the caller cannot see — which is why the lifecycle case is reported rather than swallowed.

AsyncActivationError vs AsyncResolutionError

Both come from the rule in ActivationHandler and DeactivationHandler — a hook returning a Promise means the resolve must be resolveAsync(). The difference is where the async source sits:

• AsyncResolutionError — the source is a binding's factory, known at the point the binding is selected.
• AsyncActivationError — the source is a hook, which only reveals itself after the instance has been created. The container cannot know in advance. hookKind says whether it was postConstruct or onActivation; methodName pins the exact method when a class has several @postConstruct().

The hook has already run when the error is thrown. A hook cannot be inspected for asyncness before it is called, so when AsyncActivationError or AsyncDeactivationError is raised on a sync lane, the hook body has already executed and returned a Promise. The container adopts that promise (attaching a no-op rejection handler) so a hook that rejects cannot become an unhandled rejection — but any side effect the hook performed has happened. Retry the operation on the async lane (resolveAsync / unbindAsync), which awaits the hook properly.