@codefast/di 0.5.0 → 0.6.1

package/src/{types.ts → core/types.ts}

@@ -1,15 +1,10 @@
-import type { Constructor } from "#/constructor-type";
-import type { Token } from "#/token";
+import type { Constructor } from "#/core/constructor-type";
+import type { BindingTag, TagKeyMask } from "#/core/tag";
+import type { Token } from "#/core/token";
 
 // Re-export for consumers that import from `#/types`
-export type { Constructor } from "#/constructor-type";
-
-/**
- * A single [tag, value] pair used in slot constraints and resolve options.
- *
- * @since 0.3.16-canary.0
- */
-export type BindingTag = readonly [tag: string, value: unknown];
+export type { Constructor } from "#/core/constructor-type";
+export type { BindingTag, TagKey, TagKeyMask } from "#/core/tag";
 
 /**
  * Token or class constructor used as a binding / injection / resolve key.
@@ -18,14 +13,14 @@ export type BindingTag = readonly [tag: string, value: unknown];
  */
 export type DependencyKey = Token<unknown> | Constructor;
 
-// ── BindingScope ────────────────────────────────────────────────────────────
+// ── BindingScope ─────────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
  * @since 0.3.16-canary.0
  */
 export type BindingScope = "singleton" | "transient" | "scoped";
 
-// ── BindingIdentifier ────────────────────────────────────────────────────────
+// ── BindingIdentifier ────────────────────────────────────────────────────────────────────────────────────────────────
 
 declare const BINDING_ID_BRAND: unique symbol;
 /**
@@ -33,14 +28,14 @@ declare const BINDING_ID_BRAND: unique symbol;
  */
 export type BindingIdentifier = string & { readonly [BINDING_ID_BRAND]: true };
 
-// ── BindingKind ───────────────────────────────────────────────────────────────
+// ── BindingKind ──────────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
  * @since 0.3.16-canary.0
  */
 export type BindingKind = "class" | "dynamic" | "dynamic-async" | "resolved" | "resolved-async" | "constant" | "alias";
 
-// ── Handlers ─────────────────────────────────────────────────────────────────
+// ── Handlers ─────────────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
  * @since 0.3.16-canary.0
@@ -52,22 +47,24 @@ export type ActivationHandler<Value> = (ctx: ResolutionContext, instance: Value)
  */
 export type DeactivationHandler<Value> = (instance: Value) => void | Promise<void>;
 
-// ── ResolveOptions ────────────────────────────────────────────────────────────
+// ── ResolveOptions ───────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
  * @since 0.3.16-canary.0
  */
 export interface ResolveOptions {
-  name?: string;
+  name?: string | undefined;
   /**
-   * Single-tag shorthand — semantics match including one pair in `tags`.
-   * Enables fast-path lookup alongside `tags`.
+   * Single-tag shorthand, equivalent to listing the one pair in `tags`.
+   *
+   * @remarks Reaches the same tagged index, so choosing it costs nothing. `InjectOptions` accepts it
+   * too and folds it into `tags`. Only `tags` expresses a request for more than one tag.
    */
-  tag?: BindingTag;
-  tags?: ReadonlyArray<BindingTag>;
+  tag?: BindingTag | undefined;
+  tags?: ReadonlyArray<BindingTag> | undefined;
 }
 
-// ── ResolutionFrame ──────────────────────────────────────────────────────
+// ── ResolutionFrame ──────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
  * @since 0.3.16-canary.0
@@ -80,10 +77,11 @@ export interface ResolutionFrame {
   readonly slot: {
     readonly name: string | undefined;
     readonly tags: ReadonlyArray<BindingTag>;
+    readonly keyMask: TagKeyMask;
   };
 }
 
-// ── ConstraintContext ─────────────────────────────────────────────────────────
+// ── ConstraintContext ────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
  * @since 0.3.16-canary.0
@@ -93,31 +91,36 @@ export interface ConstraintContext {
   readonly resolutionStack: ReadonlyArray<ResolutionFrame>;
   readonly parent: ResolutionFrame | undefined;
   readonly ancestors: ReadonlyArray<ResolutionFrame>;
-  readonly currentResolveOptions: ResolveOptions | undefined;
+  /** Readonly because one frozen object answers every resolve of a slot — a write would throw. */
+  readonly currentResolveOptions: Readonly<ResolveOptions> | undefined;
 }
 
-// ── ResolutionContext ─────────────────────────────────────────────────────────
+/**
+ * The predicate `when()` selects a binding by, and the shape every `when*` helper returns.
+ *
+ * @since 0.6.0
+ */
+export type BindingConstraint = (ctx: ConstraintContext) => boolean;
+
+// ── ResolutionContext ────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
  * @since 0.3.16-canary.0
  */
 export interface ResolutionContext {
-  resolve<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value;
-  resolveAsync<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value>;
-  resolveOptional<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined;
-  resolveOptionalAsync<const Value>(
+  resolve<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value;
+  resolveAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value>;
+  resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined;
+  resolveOptionalAsync<Value>(
     token: Token<Value> | Constructor<Value>,
     options?: ResolveOptions,
   ): Promise<Value | undefined>;
-  resolveAll<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value>;
-  resolveAllAsync<const Value>(
-    token: Token<Value> | Constructor<Value>,
-    options?: ResolveOptions,
-  ): Promise<Array<Value>>;
+  resolveAll<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value>;
+  resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Array<Value>>;
   readonly graph: ConstraintContext;
 }
 
-// ── TokenValue ────────────────────────────────────────────────────────────────
+// ── TokenValue ───────────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
  * @since 0.3.16-canary.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. */