@codefast/di 0.5.0-canary.9 → 0.6.0

package/src/decorators/inject.ts

@@ -1,137 +1,33 @@
-import { InternalError, MissingContainerContextError } from "#/errors";
+import { getActiveContainer, getAmbientResolution } from "#/ambient/active-container";
+/** `@inject` — the accessor-decorator channel, resolving from the ambient container. */
+import type { Token } from "#/core/token";
+import type { Constructor } from "#/core/types";
+import { MissingContainerContextError, StaticMemberDecoratorError } from "#/errors/errors";
+import type { InjectionDescriptor, InjectOptions } from "#/injection/descriptor";
+import { buildInjectionDescriptor } from "#/injection/descriptor";
+import { injectionSlotToResolveOptions } from "#/injection/resolve-options";
 import { INJECT_ACCESSOR_KEY } from "#/metadata/metadata-keys";
-import { getActiveContainer } from "#/resolution/environment";
-import { injectionSlotToResolveOptions } from "#/resolution/resolve-options";
-import type { Token } from "#/token";
-import type { BindingTag, Constructor, TokenValue } from "#/types";
-
-// ── InjectionDescriptor ───────────────────────────────────────────────────────
-
-/**
- * @since 0.3.16-canary.0
- */
-export interface InjectOptions {
-  name?: string;
-  tags?: ReadonlyArray<BindingTag>;
-}
-
-/**
- * @since 0.3.16-canary.0
- */
-export interface InjectionDescriptor<Value = unknown> {
-  readonly token: Token<Value> | Constructor<Value>;
-  readonly optional: boolean;
-  readonly multi: boolean;
-  readonly name?: string;
-  readonly tags?: ReadonlyArray<BindingTag>;
-}
-
-/**
- * @since 0.3.16-canary.0
- */
-export type InjectableDependency<Value = unknown> = Token<Value> | Constructor<Value> | InjectionDescriptor<Value>;
 
 /**
- * The value a factory receives for one declared dependency.
- *
- * @remarks `optional()` and `injectAll()` fold their effect into the descriptor's own type
- * parameter, so reading it back is enough; bare tokens fall through to {@link TokenValue}.
+ * The name of the class being constructed, or `undefined` when there is none to report.
  *
- * @since 0.5.0-canary.7
+ * @remarks Two ways there is none: an anonymous class expression has an empty `name`, and an
+ * instance whose prototype chain answers no `constructor` has nothing to read. Narrowed rather than
+ * asserted — the value arrives as `unknown` and the platform makes no promise about it.
  */
-export type ResolvedDependencyValue<Dependency> =
-  Dependency extends InjectionDescriptor<infer Value> ? Value : TokenValue<Dependency>;
-
-/**
- * @since 0.3.16-canary.0
- */
-export function isInjectionDescriptor(value: unknown): value is InjectionDescriptor {
-  if (value === null || value === undefined) {
-    return false;
+function classNameOf(instance: unknown): string | undefined {
+  if (typeof instance !== "object" || instance === null) {
+    return undefined;
   }
-  const type = typeof value;
-  // inject() returns a function (dual-role), so must check both object and function
-  if (type !== "object" && type !== "function") {
-    return false;
+  const constructor: unknown = Reflect.get(instance, "constructor");
+  if (typeof constructor !== "function" || constructor.name === "") {
+    return undefined;
   }
-  return (
-    "token" in (value as object) &&
-    "optional" in (value as object) &&
-    "multi" in (value as object) &&
-    typeof (value as InjectionDescriptor).optional === "boolean" &&
-    typeof (value as InjectionDescriptor).multi === "boolean"
-  );
-}
 
-/**
- * @since 0.3.16-canary.0
- */
-export function normalizeToDescriptor(dependency: InjectableDependency): InjectionDescriptor {
-  if (isInjectionDescriptor(dependency)) {
-    return materializeInjectionDescriptor(dependency);
-  }
-  return { token: dependency as Token<unknown> | Constructor, optional: false, multi: false };
+  return constructor.name;
 }
 
-/**
- * Dual-role `inject()` values are functions: [[Function]].name must not be treated as a DI slot name.
- * Only enumerable own `name` / `tags` from `Object.defineProperties` are real injection options.
- */
-function materializeInjectionDescriptor(dependency: InjectionDescriptor): InjectionDescriptor {
-  if (typeof dependency !== "function") {
-    return dependency;
-  }
-  const dualRole = dependency as InjectionDescriptor & ((...args: Array<unknown>) => unknown);
-  const base: Pick<InjectionDescriptor, "token" | "optional" | "multi"> = {
-    token: dualRole.token,
-    optional: dualRole.optional,
-    multi: dualRole.multi,
-  };
-  const nameDesc = Object.getOwnPropertyDescriptor(dualRole, "name");
-  const tagsDesc = Object.getOwnPropertyDescriptor(dualRole, "tags");
-  const explicitName = nameDesc?.enumerable === true && typeof nameDesc.value === "string" ? nameDesc.value : undefined;
-  const explicitTags = tagsDesc?.enumerable === true ? tagsDesc.value : undefined;
-
-  if (explicitName !== undefined && explicitTags !== undefined) {
-    return {
-      ...base,
-      name: explicitName,
-      tags: explicitTags as NonNullable<InjectionDescriptor["tags"]>,
-    };
-  }
-  if (explicitName !== undefined) {
-    return { ...base, name: explicitName };
-  }
-  if (explicitTags !== undefined) {
-    return { ...base, tags: explicitTags as NonNullable<InjectionDescriptor["tags"]> };
-  }
-  return base;
-}
-
-function withOptions<DescValue>(
-  base: Pick<InjectionDescriptor<DescValue>, "token" | "optional" | "multi">,
-  options: InjectOptions | undefined,
-): InjectionDescriptor<DescValue> {
-  if (options?.name !== undefined && options.tags !== undefined) {
-    return { ...base, name: options.name, tags: options.tags };
-  }
-  if (options?.name !== undefined) {
-    return { ...base, name: options.name };
-  }
-  if (options?.tags !== undefined) {
-    return { ...base, tags: options.tags };
-  }
-  return base;
-}
-
-function buildInjectionDescriptor<const Value>(
-  token: Token<Value> | Constructor<Value>,
-  options?: InjectOptions,
-): InjectionDescriptor<Value> {
-  return withOptions({ token, optional: false, multi: false }, options);
-}
-
-// ── inject() — dual-role ──────────────────────────────────────────────────────
+// ── inject() — dual-role ─────────────────────────────────────────────────────────────────────────────────────────────
 
 type ClassAccessorDecorator<This, Value> = (
   target: ClassAccessorDecoratorTarget<This, Value>,
@@ -141,23 +37,26 @@ type ClassAccessorDecorator<This, Value> = (
 /**
  * @since 0.3.16-canary.0
  */
-export function inject<const Value>(
+export function inject<Value>(
   token: Token<Value> | Constructor<Value>,
   options?: InjectOptions,
 ): InjectionDescriptor<Value> & ClassAccessorDecorator<unknown, Value> {
   const descriptor = buildInjectionDescriptor(token, options);
+  // Derived from the descriptor, not from `options`: the descriptor is where the tag shorthand has
+  // already been folded. Built once here rather than per constructed instance.
+  const resolveOptions = injectionSlotToResolveOptions(descriptor);
 
   const decoratorFn = (
     _target: ClassAccessorDecoratorTarget<unknown, Value>,
     context: ClassAccessorDecoratorContext<unknown, Value>,
   ): ClassAccessorDecoratorResult<unknown, Value> => {
     if (context.static) {
-      throw new InternalError(
-        "@inject() on static accessors is not supported; only instance accessors participate in runWithContainer-based property injection.",
-      );
+      throw new StaticMemberDecoratorError("inject", String(context.name));
     }
     const meta = context.metadata as Record<string | symbol, unknown>;
-    if (!Array.isArray(meta[INJECT_ACCESSOR_KEY])) {
+    // Own bucket only: the metadata record inherits the base class's, and pushing into an inherited
+    // array would register this accessor on the base class instead.
+    if (!Object.hasOwn(meta, INJECT_ACCESSOR_KEY) || !Array.isArray(meta[INJECT_ACCESSOR_KEY])) {
       meta[INJECT_ACCESSOR_KEY] = [];
     }
     (meta[INJECT_ACCESSOR_KEY] as Array<{ key: string | symbol; descriptor: InjectionDescriptor }>).push({
@@ -166,17 +65,20 @@ export function inject<const Value>(
     });
 
     context.addInitializer(function (this: unknown) {
+      // Prefer the engine's path-continuing resolver: it keeps this accessor's dependencies on the
+      // live resolution path, so a cycle through an accessor is detected instead of recursing.
+      const ambient = getAmbientResolution();
+      if (ambient !== undefined) {
+        const value = descriptor.optional
+          ? ambient.resolveOptional(token, resolveOptions)
+          : ambient.resolve(token, resolveOptions);
+        context.access.set(this, value as Value);
+        return;
+      }
       const container = getActiveContainer();
       if (container === undefined) {
-        throw new MissingContainerContextError(String(context.name));
+        throw new MissingContainerContextError(classNameOf(this), context.name);
       }
-      const resolveOptions =
-        options === undefined
-          ? undefined
-          : injectionSlotToResolveOptions({
-              ...(options.name !== undefined ? { name: options.name } : {}),
-              ...(options.tags !== undefined ? { tags: options.tags } : {}),
-            });
       const value = descriptor.optional
         ? container.resolveOptional(token, resolveOptions)
         : container.resolve(token, resolveOptions);
@@ -195,41 +97,3 @@ export function inject<const Value>(
 
   return decoratorFn as InjectionDescriptor<Value> & ClassAccessorDecorator<unknown, Value>;
 }
-
-// ── optional() ────────────────────────────────────────────────────────────────
-
-/**
- * @since 0.3.16-canary.0
- */
-export function optional<const Value>(
-  token: Token<Value> | Constructor<Value>,
-  options?: InjectOptions,
-): InjectionDescriptor<Value | undefined> {
-  return withOptions(
-    {
-      token: token as Token<Value | undefined> | Constructor<Value | undefined>,
-      optional: true,
-      multi: false,
-    },
-    options,
-  );
-}
-
-// ── injectAll() ───────────────────────────────────────────────────────────────
-
-/**
- * @since 0.3.16-canary.0
- */
-export function injectAll<const Value>(
-  token: Token<Value> | Constructor<Value>,
-  options?: InjectOptions,
-): InjectionDescriptor<Array<Value>> {
-  return withOptions(
-    {
-      token: token as Token<Array<Value>> | Constructor<Array<Value>>,
-      optional: false,
-      multi: true,
-    },
-    options,
-  );
-}

package/src/decorators/injectable.ts

@@ -1,10 +1,10 @@
-import type { InjectableDependency } from "#/decorators/inject";
-import { normalizeToDescriptor } from "#/decorators/inject";
+import type { BindingScope, Constructor } from "#/core/types";
+import type { InjectableDependency, ResolvedDependencyValue } from "#/injection/descriptor";
+import { normalizeToDescriptor } from "#/injection/descriptor";
 import { INJECTABLE_KEY } from "#/metadata/metadata-keys";
 import type { ParamMetadata } from "#/metadata/metadata-types";
-import type { BindingScope, Constructor } from "#/types";
 
-// ── AutoRegisterRegistry ──────────────────────────────────────────────────────
+// ── AutoRegisterRegistry ─────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
  * @since 0.3.16-canary.0
@@ -29,26 +29,56 @@ export function createAutoRegisterRegistry(): AutoRegisterRegistry {
   };
 }
 
-// ── InjectableOptions ─────────────────────────────────────────────────────────
+// ── InjectableOptions ────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
  * @since 0.3.16-canary.0
  */
 export interface InjectableOptions {
-  autoRegister?: AutoRegisterRegistry;
-  scope?: BindingScope;
+  autoRegister?: AutoRegisterRegistry | undefined;
+  scope?: BindingScope | undefined;
 }
 
-// ── @injectable() ─────────────────────────────────────────────────────────────
+// ── @injectable() ────────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
+ * The parameters a constructor is handed, given what its `deps` declare.
+ *
+ * @remarks Reuses the same reading a `toResolved` factory gets, so `injectAll` arrives as an array
+ * and `optional` as possibly undefined in both places.
+ */
+type InjectedParameters<Deps extends ReadonlyArray<InjectableDependency>> = {
+  -readonly [Index in keyof Deps]: ResolvedDependencyValue<Deps[Index]>;
+};
+
+/**
+ * Declare a class injectable, and what its constructor is to be handed.
+ *
  * @since 0.3.16-canary.0
  */
+export function injectable(): (target: unknown, context: ClassDecoratorContext) => void;
+
+/**
+ * @remarks Declaring dependencies constrains the class: the decorator only accepts one whose
+ * constructor takes exactly what `deps` resolve to, in that order. A class taking fewer parameters
+ * than `deps` declares still satisfies it, which is the one mismatch TypeScript's arity rules let
+ * through — the surplus dependency is resolved and discarded.
+ *
+ * @since 0.3.16-canary.0
+ */
+export function injectable<const Deps extends ReadonlyArray<InjectableDependency>>(
+  deps: Deps,
+  options?: InjectableOptions,
+): (target: abstract new (...args: InjectedParameters<Deps>) => unknown, context: ClassDecoratorContext) => void;
+
+/**
+ * @since 0.6.0
+ */
 export function injectable(
   deps?: ReadonlyArray<InjectableDependency>,
   options?: InjectableOptions,
-): (target: unknown, context: ClassDecoratorContext) => void {
-  return function (target: unknown, context: ClassDecoratorContext): void {
+): (target: never, context: ClassDecoratorContext) => void {
+  return function (target: never, context: ClassDecoratorContext): void {
     const parameterMetadataList: Array<ParamMetadata> = (deps ?? []).map((dependency, index) => {
       const descriptor = normalizeToDescriptor(dependency);
       const baseParameterMetadata: Pick<ParamMetadata, "index" | "token" | "optional" | "multi"> = {

package/src/decorators/lifecycle-decorators.ts

@@ -1,51 +1,39 @@
-import { InternalError } from "#/errors";
+import { StaticMemberDecoratorError } from "#/errors/errors";
 import { LIFECYCLE_KEY } from "#/metadata/metadata-keys";
 import type { MutableLifecycleMetadata } from "#/metadata/metadata-types";
 
-function appendUniqueMethod(
-  metadata: MutableLifecycleMetadata,
-  phase: "postConstruct" | "preDestroy",
-  methodName: string,
-): void {
-  if (!metadata[phase].includes(methodName)) {
-    metadata[phase].push(methodName);
-  }
-}
+type MethodDecorator = (target: unknown, context: ClassMethodDecoratorContext) => void;
 
-/**
- * @since 0.3.16-canary.0
- */
-export function postConstruct(): (target: unknown, context: ClassMethodDecoratorContext) => void {
+/** Records the decorated method under one lifecycle phase; both decorators differ only in that phase. */
+function recordLifecycleMethod(phase: "postConstruct" | "preDestroy"): MethodDecorator {
   return function (target: unknown, context: ClassMethodDecoratorContext): void {
     if (context.static) {
-      throw new InternalError(
-        "@postConstruct() applies to instance methods only; static methods are not invoked during instance lifecycle.",
-      );
+      throw new StaticMemberDecoratorError(phase, String(context.name));
     }
-    const methodName = String(context.name);
     const meta = context.metadata as Record<string | symbol, unknown>;
-    if (!meta[LIFECYCLE_KEY]) {
+    // Own bucket only: `context.metadata` inherits the base class's record, and writing through an
+    // inherited bucket would register this hook on the base class instead.
+    if (!Object.hasOwn(meta, LIFECYCLE_KEY)) {
       meta[LIFECYCLE_KEY] = { postConstruct: [], preDestroy: [] };
     }
-    appendUniqueMethod(meta[LIFECYCLE_KEY] as MutableLifecycleMetadata, "postConstruct", methodName);
+    const lifecycle = meta[LIFECYCLE_KEY] as MutableLifecycleMetadata;
+    const methodName = String(context.name);
+    if (!lifecycle[phase].includes(methodName)) {
+      lifecycle[phase].push(methodName);
+    }
   };
 }
 
 /**
  * @since 0.3.16-canary.0
  */
-export function preDestroy(): (target: unknown, context: ClassMethodDecoratorContext) => void {
-  return function (target: unknown, context: ClassMethodDecoratorContext): void {
-    if (context.static) {
-      throw new InternalError(
-        "@preDestroy() applies to instance methods only; static methods are not invoked during instance teardown.",
-      );
-    }
-    const methodName = String(context.name);
-    const meta = context.metadata as Record<string | symbol, unknown>;
-    if (!meta[LIFECYCLE_KEY]) {
-      meta[LIFECYCLE_KEY] = { postConstruct: [], preDestroy: [] };
-    }
-    appendUniqueMethod(meta[LIFECYCLE_KEY] as MutableLifecycleMetadata, "preDestroy", methodName);
-  };
+export function postConstruct(): MethodDecorator {
+  return recordLifecycleMethod("postConstruct");
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function preDestroy(): MethodDecorator {
+  return recordLifecycleMethod("preDestroy");
 }

package/src/{resolution → errors}/diagnostics.ts

@@ -25,6 +25,8 @@ export const RESOLUTION_DIAGNOSTICS: unique symbol = Symbol("di:resolution-diagn
 export interface ResolutionDiagnostics {
   /** Bindings with a compiled instantiation plan. */
   readonly compiledPlanCount: number;
+  /** Bindings with a compiled async instantiation plan. */
+  readonly compiledAsyncPlanCount: number;
   /** Contexts held by the depth-indexed sync pool. */
   readonly syncContextPoolSize: number;
   /** Scoped instances currently cached by this container's scope manager. */

package/src/{errors.ts → errors/errors.ts}

@@ -1,4 +1,4 @@
-import type { BindingIdentifier, BindingScope, ResolveOptions } from "#/types";
+import type { BindingIdentifier, BindingScope, ResolveOptions } from "#/core/types";
 
 /**
  * @since 0.3.16-canary.0
@@ -36,6 +36,19 @@ export class TokenNotBoundError extends DiError {
   }
 }
 
+// Options carry caller values a tag may hold — a bigint or a circular object must not make the
+// diagnostic itself throw and mask the real error.
+function describeResolveOptions(options: ResolveOptions): string {
+  try {
+    return (
+      JSON.stringify(options, (_key, value: unknown) => (typeof value === "bigint" ? `${String(value)}n` : value)) ??
+      "undefined"
+    );
+  } catch {
+    return "[unserializable options]";
+  }
+}
+
 /**
  * @since 0.3.16-canary.0
  */
@@ -46,7 +59,7 @@ export class NoMatchingBindingError extends DiError {
   readonly availableSlots: Array<string>;
 
   constructor(tokenName: string, options: ResolveOptions, availableSlots: Array<string>) {
-    const optionsString = JSON.stringify(options);
+    const optionsString = describeResolveOptions(options);
     const slotsStr = availableSlots.join(", ");
     super(`No binding for '${tokenName}' matching ${optionsString}. Available slots: [${slotsStr}].`);
     this.tokenName = tokenName;
@@ -90,12 +103,16 @@ export class CircularDependencyError extends DiError {
  */
 export class AsyncResolutionError extends DiError {
   readonly code = "ASYNC_RESOLUTION";
+  /** The token the caller asked for — what `resolveAsync` has to be called with. */
   readonly tokenName: string;
+  /** The token whose factory is async: `tokenName` itself unless a dependency forced it. */
   readonly asyncSourceToken: string;
 
-  constructor(tokenName: string, asyncSourceToken: string) {
+  constructor(tokenName: string, asyncSourceToken: string = tokenName) {
     super(
-      `Token '${tokenName}' requires async resolution because '${asyncSourceToken}' in its dependency chain has an async factory. Use container.resolveAsync(${tokenName}).`,
+      asyncSourceToken === tokenName
+        ? `Token '${tokenName}' requires async resolution because its factory is async. Use container.resolveAsync(${tokenName}).`
+        : `Token '${tokenName}' requires async resolution because '${asyncSourceToken}' in its dependency chain has an async factory. Use container.resolveAsync(${tokenName}).`,
     );
     this.tokenName = tokenName;
     this.asyncSourceToken = asyncSourceToken;
@@ -141,6 +158,98 @@ export class ScopeViolationError extends DiError {
   }
 }
 
+/**
+ * A `…TaggedAll` constraint built from a criteria list with nothing in it.
+ *
+ * @remarks Reported where the list is passed rather than where it fails to match, because it does
+ * not fail to match — "carries all of no criteria" holds for any ancestor, so the constraint quietly
+ * becomes a weaker one that still outranks an unconstrained binding.
+ *
+ * @since 0.6.0
+ */
+export class EmptyTagCriteriaError extends DiError {
+  readonly code = "EMPTY_TAG_CRITERIA";
+  readonly helperName: string;
+
+  constructor(helperName: string) {
+    super(
+      `${helperName}() was given no criteria. An empty list matches any ancestor, which is not what the call says — pass the criteria to require, or drop the constraint if there are none.`,
+    );
+    this.helperName = helperName;
+  }
+}
+
+/**
+ * A constraint waiting on a slot name that nothing in the container chain declares.
+ *
+ * @remarks A name is a bare string, so a typo produces a constraint that is never satisfied and
+ * never reported. Reported by `validate()` rather than at bind time, because the binding carrying
+ * the name may be registered after the constraint is built.
+ *
+ * @since 0.6.0
+ */
+export class UnreachableConstraintError extends DiError {
+  readonly code = "UNREACHABLE_CONSTRAINT";
+  readonly tokenName: string;
+  readonly requiredName: string;
+  readonly helperName: string;
+
+  constructor(tokenName: string, requiredName: string, helperName: string) {
+    super(
+      `The binding for '${tokenName}' is constrained by ${helperName}('${requiredName}'), but no binding in this container or its ancestors declares the slot name '${requiredName}', so the constraint can never hold. Name the slot with .whenNamed('${requiredName}') on the binding it should match, or correct the name here.`,
+    );
+    this.tokenName = tokenName;
+    this.requiredName = requiredName;
+    this.helperName = helperName;
+  }
+}
+
+/**
+ * A container-level lifecycle hook whose token nothing is bound to, so it can never run.
+ *
+ * @remarks Hooks are keyed by token identity, which makes a class that is only ever a `to()` target
+ * look like a token and match nothing. Reported by `validate()` rather than at registration, because
+ * binding after registering the hook is a supported order.
+ *
+ * @since 0.6.0
+ */
+export class UnreachableLifecycleHookError extends DiError {
+  readonly code = "UNREACHABLE_LIFECYCLE_HOOK";
+  readonly tokenName: string;
+  readonly phase: "onActivation" | "onDeactivation";
+
+  constructor(tokenName: string, phase: "onActivation" | "onDeactivation") {
+    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.`,
+    );
+    this.tokenName = tokenName;
+    this.phase = phase;
+  }
+}
+
+/**
+ * A {@link MetadataReader} described a class with something the container cannot use.
+ *
+ * @remarks Separate from {@link MissingMetadataError}: absent metadata is a class the container was
+ * never told about, while invalid metadata is a reader that answered wrongly. Covers both the
+ * constructor answer and the lifecycle one, since only the `reason` differs.
+ *
+ * @since 0.6.0
+ */
+export class InvalidMetadataError extends DiError {
+  readonly code = "INVALID_METADATA";
+  readonly targetName: string;
+  readonly reason: string;
+
+  constructor(targetName: string, reason: string) {
+    super(
+      `MetadataReader returned invalid metadata for class '${targetName}': ${reason}. Check the reader bound to MetadataReaderToken or passed to Container.create().`,
+    );
+    this.targetName = targetName;
+    this.reason = reason;
+  }
+}
+
 /**
  * @since 0.3.16-canary.0
  */
@@ -198,17 +307,29 @@ export class MissingScopeContextError extends DiError {
 }
 
 /**
+ * An `@inject` accessor initialized with no container context open.
+ *
+ * @remarks Carries the class and the accessor separately: a nameless class is possible (an anonymous
+ * class expression has an empty `name`), and a message that claims a class it does not have is what
+ * sent readers looking for a class called `clock`.
+ *
  * @since 0.3.16-canary.0
  */
 export class MissingContainerContextError extends DiError {
   readonly code = "MISSING_CONTAINER_CONTEXT";
-  readonly targetName: string;
+  /** The class being constructed, or `undefined` when it has no readable name. */
+  readonly className: string | undefined;
+  readonly accessorName: string | symbol;
 
-  constructor(targetName: string) {
+  constructor(className: string | undefined, accessorName: string | symbol) {
+    const accessor = `@inject accessor '${String(accessorName)}'`;
     super(
-      `Class '${targetName}' has @inject accessor fields but was instantiated outside a container context. Resolve it via container.resolve(${targetName}) instead.`,
+      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().`,
     );
-    this.targetName = targetName;
+    this.className = className;
+    this.accessorName = accessorName;
   }
 }
 
@@ -265,6 +386,29 @@ export class SelfBindingRequiresClassError extends DiError {
   }
 }
 
+/**
+ * A decorator that acts on one instance was applied to a static member.
+ *
+ * @remarks Instance-only by construction: `@inject` resolves through the container active while an
+ * instance is built, and `@postConstruct`/`@preDestroy` bracket one instance's lifecycle. A static
+ * member belongs to the class, which no container constructs.
+ *
+ * @since 0.6.0
+ */
+export class StaticMemberDecoratorError extends DiError {
+  readonly code = "STATIC_MEMBER_DECORATOR";
+  readonly decoratorName: string;
+  readonly memberName: string;
+
+  constructor(decoratorName: string, memberName: string) {
+    super(
+      `@${decoratorName}() applies to instance members only, and '${memberName}' is static. Move it to an instance member, or read the value from the container where the static member is used.`,
+    );
+    this.decoratorName = decoratorName;
+    this.memberName = memberName;
+  }
+}
+
 /**
  * @since 0.3.16-canary.0
  */