@codefast/di 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codefast/di",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Lightweight dependency injection primitives for Codefast",
   "keywords": [
     "codefast",
@@ -54,6 +54,66 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./ambient/active-container": {
+      "source": "./src/ambient/active-container.ts",
+      "types": "./dist/ambient/active-container.d.ts",
+      "import": "./dist/ambient/active-container.js"
+    },
+    "./container/binding-builders": {
+      "source": "./src/container/binding-builders.ts",
+      "types": "./dist/container/binding-builders.d.ts",
+      "import": "./dist/container/binding-builders.js"
+    },
+    "./container/container": {
+      "source": "./src/container/container.ts",
+      "types": "./dist/container/container.d.ts",
+      "import": "./dist/container/container.js"
+    },
+    "./core/binding": {
+      "source": "./src/core/binding.ts",
+      "types": "./dist/core/binding.d.ts",
+      "import": "./dist/core/binding.js"
+    },
+    "./core/binding-scope": {
+      "source": "./src/core/binding-scope.ts",
+      "types": "./dist/core/binding-scope.d.ts",
+      "import": "./dist/core/binding-scope.js"
+    },
+    "./core/constraint-requirement": {
+      "source": "./src/core/constraint-requirement.ts",
+      "types": "./dist/core/constraint-requirement.d.ts",
+      "import": "./dist/core/constraint-requirement.js"
+    },
+    "./core/constructor-type": {
+      "source": "./src/core/constructor-type.ts",
+      "types": "./dist/core/constructor-type.d.ts",
+      "import": "./dist/core/constructor-type.js"
+    },
+    "./core/module": {
+      "source": "./src/core/module.ts",
+      "types": "./dist/core/module.d.ts",
+      "import": "./dist/core/module.js"
+    },
+    "./core/registry": {
+      "source": "./src/core/registry.ts",
+      "types": "./dist/core/registry.d.ts",
+      "import": "./dist/core/registry.js"
+    },
+    "./core/tag": {
+      "source": "./src/core/tag.ts",
+      "types": "./dist/core/tag.d.ts",
+      "import": "./dist/core/tag.js"
+    },
+    "./core/token": {
+      "source": "./src/core/token.ts",
+      "types": "./dist/core/token.d.ts",
+      "import": "./dist/core/token.js"
+    },
+    "./core/types": {
+      "source": "./src/core/types.ts",
+      "types": "./dist/core/types.d.ts",
+      "import": "./dist/core/types.js"
+    },
     "./decorators/inject": {
       "source": "./src/decorators/inject.ts",
       "types": "./dist/decorators/inject.d.ts",
@@ -69,10 +129,25 @@
       "types": "./dist/decorators/lifecycle-decorators.d.ts",
       "import": "./dist/decorators/lifecycle-decorators.js"
     },
-    "./errors": {
-      "source": "./src/errors.ts",
-      "types": "./dist/errors.d.ts",
-      "import": "./dist/errors.js"
+    "./errors/diagnostics": {
+      "source": "./src/errors/diagnostics.ts",
+      "types": "./dist/errors/diagnostics.d.ts",
+      "import": "./dist/errors/diagnostics.js"
+    },
+    "./errors/errors": {
+      "source": "./src/errors/errors.ts",
+      "types": "./dist/errors/errors.d.ts",
+      "import": "./dist/errors/errors.js"
+    },
+    "./injection/descriptor": {
+      "source": "./src/injection/descriptor.ts",
+      "types": "./dist/injection/descriptor.d.ts",
+      "import": "./dist/injection/descriptor.js"
+    },
+    "./injection/resolve-options": {
+      "source": "./src/injection/resolve-options.ts",
+      "types": "./dist/injection/resolve-options.d.ts",
+      "import": "./dist/injection/resolve-options.js"
     },
     "./dependency-graph": {
       "source": "./src/introspection/dependency-graph.ts",
@@ -89,6 +164,11 @@
       "types": "./dist/introspection/graph-adapters/dot.d.ts",
       "import": "./dist/introspection/graph-adapters/dot.js"
     },
+    "./graph-adapters/mermaid": {
+      "source": "./src/introspection/graph-adapters/mermaid.ts",
+      "types": "./dist/introspection/graph-adapters/mermaid.d.ts",
+      "import": "./dist/introspection/graph-adapters/mermaid.js"
+    },
     "./graph-adapters/reactflow": {
       "source": "./src/introspection/graph-adapters/reactflow.ts",
       "types": "./dist/introspection/graph-adapters/reactflow.d.ts",
@@ -99,25 +179,85 @@
       "types": "./dist/introspection/inspector.d.ts",
       "import": "./dist/introspection/inspector.js"
     },
+    "./lifecycle/lifecycle-manager": {
+      "source": "./src/lifecycle/lifecycle-manager.ts",
+      "types": "./dist/lifecycle/lifecycle-manager.d.ts",
+      "import": "./dist/lifecycle/lifecycle-manager.js"
+    },
+    "./lifecycle/scope-manager": {
+      "source": "./src/lifecycle/scope-manager.ts",
+      "types": "./dist/lifecycle/scope-manager.d.ts",
+      "import": "./dist/lifecycle/scope-manager.js"
+    },
+    "./metadata/metadata-keys": {
+      "source": "./src/metadata/metadata-keys.ts",
+      "types": "./dist/metadata/metadata-keys.d.ts",
+      "import": "./dist/metadata/metadata-keys.js"
+    },
     "./metadata/metadata-reader-token": {
       "source": "./src/metadata/metadata-reader-token.ts",
       "types": "./dist/metadata/metadata-reader-token.d.ts",
       "import": "./dist/metadata/metadata-reader-token.js"
     },
-    "./module": {
-      "source": "./src/module.ts",
-      "types": "./dist/module.d.ts",
-      "import": "./dist/module.js"
+    "./metadata/metadata-types": {
+      "source": "./src/metadata/metadata-types.ts",
+      "types": "./dist/metadata/metadata-types.d.ts",
+      "import": "./dist/metadata/metadata-types.js"
+    },
+    "./metadata/symbol-metadata-reader": {
+      "source": "./src/metadata/symbol-metadata-reader.ts",
+      "types": "./dist/metadata/symbol-metadata-reader.d.ts",
+      "import": "./dist/metadata/symbol-metadata-reader.js"
+    },
+    "./metadata/verifying-metadata-reader": {
+      "source": "./src/metadata/verifying-metadata-reader.ts",
+      "types": "./dist/metadata/verifying-metadata-reader.d.ts",
+      "import": "./dist/metadata/verifying-metadata-reader.js"
+    },
+    "./resolution/cache/activation-need": {
+      "source": "./src/resolution/cache/activation-need.ts",
+      "types": "./dist/resolution/cache/activation-need.d.ts",
+      "import": "./dist/resolution/cache/activation-need.js"
+    },
+    "./resolution/cache/binding-lookup-cache": {
+      "source": "./src/resolution/cache/binding-lookup-cache.ts",
+      "types": "./dist/resolution/cache/binding-lookup-cache.d.ts",
+      "import": "./dist/resolution/cache/binding-lookup-cache.js"
+    },
+    "./resolution/cache/class-introspector": {
+      "source": "./src/resolution/cache/class-introspector.ts",
+      "types": "./dist/resolution/cache/class-introspector.d.ts",
+      "import": "./dist/resolution/cache/class-introspector.js"
+    },
+    "./resolution/context": {
+      "source": "./src/resolution/context.ts",
+      "types": "./dist/resolution/context.d.ts",
+      "import": "./dist/resolution/context.js"
+    },
+    "./resolution/path/resolution-path": {
+      "source": "./src/resolution/path/resolution-path.ts",
+      "types": "./dist/resolution/path/resolution-path.d.ts",
+      "import": "./dist/resolution/path/resolution-path.js"
+    },
+    "./resolution/plan/instantiation-plan": {
+      "source": "./src/resolution/plan/instantiation-plan.ts",
+      "types": "./dist/resolution/plan/instantiation-plan.d.ts",
+      "import": "./dist/resolution/plan/instantiation-plan.js"
+    },
+    "./resolution/resolver": {
+      "source": "./src/resolution/resolver.ts",
+      "types": "./dist/resolution/resolver.d.ts",
+      "import": "./dist/resolution/resolver.js"
     },
-    "./token": {
-      "source": "./src/token.ts",
-      "types": "./dist/token.d.ts",
-      "import": "./dist/token.js"
+    "./resolution/select/binding-select": {
+      "source": "./src/resolution/select/binding-select.ts",
+      "types": "./dist/resolution/select/binding-select.d.ts",
+      "import": "./dist/resolution/select/binding-select.js"
     },
-    "./types": {
-      "source": "./src/types.ts",
-      "types": "./dist/types.d.ts",
-      "import": "./dist/types.js"
+    "./resolution/select/constraints": {
+      "source": "./src/resolution/select/constraints.ts",
+      "types": "./dist/resolution/select/constraints.d.ts",
+      "import": "./dist/resolution/select/constraints.js"
     },
     "./package.json": "./package.json"
   },
@@ -128,13 +268,13 @@
     "@babel/core": "^8.0.1",
     "@babel/plugin-proposal-decorators": "8.0.2",
     "@rolldown/plugin-babel": "^0.2.3",
-    "@types/node": "^26.1.2",
+    "@types/node": "^26.2.0",
     "@vitest/coverage-v8": "^4.1.10",
     "expect-type": "^1.4.0",
-    "tsx": "^4.23.1",
+    "tsx": "^4.23.12",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10",
-    "@codefast/typescript-config": "0.5.0"
+    "@codefast/typescript-config": "0.6.0"
   },
   "engines": {
     "node": ">=26.0.0"

package/src/ambient/active-container.ts

@@ -0,0 +1,65 @@
+/** The container an `@inject` accessor initializer resolves from when it has no other handle. */
+import type { Container } from "#/container/container";
+import type { Token } from "#/core/token";
+import type { Constructor, ResolveOptions } from "#/core/types";
+
+/**
+ * Path-continuing resolution the engine installs while constructing a class with `@inject` accessors.
+ *
+ * @remarks Resolving through this keeps an accessor's dependencies on the live resolution path, so a
+ * cycle through an accessor surfaces as `CircularDependencyError` instead of unbounded recursion.
+ *
+ * @since 0.6.0
+ */
+export interface AmbientResolution {
+  resolve<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value;
+  resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined;
+}
+
+let activeContainer: Container | undefined;
+let activeResolution: AmbientResolution | undefined;
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function runWithContainer<Result>(container: Container, fn: () => Result): Result {
+  return runWithAmbientResolution(container, undefined, fn);
+}
+
+/**
+ * Engine-internal variant of {@link runWithContainer} that also installs a path-continuing resolver.
+ *
+ * @since 0.6.0
+ */
+export function runWithAmbientResolution<Result>(
+  container: Container,
+  resolution: AmbientResolution | undefined,
+  fn: () => Result,
+): Result {
+  const previousContainer = activeContainer;
+  const previousResolution = activeResolution;
+  activeContainer = container;
+  activeResolution = resolution;
+  try {
+    return fn();
+  } finally {
+    activeContainer = previousContainer;
+    activeResolution = previousResolution;
+  }
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function getActiveContainer(): Container | undefined {
+  return activeContainer;
+}
+
+/**
+ * The path-continuing resolution for the construction in flight, when the engine installed one.
+ *
+ * @since 0.6.0
+ */
+export function getAmbientResolution(): AmbientResolution | undefined {
+  return activeResolution;
+}

package/src/container/binding-builders.ts

@@ -1,7 +1,8 @@
 /**
  * The fluent chain `bind()` returns: it registers the binding and refines it in place.
  *
- * @see `ARCHITECTURE.md` — why one object plays every role, and what pins the ordering.
+ * @remarks One object plays every role in the chain; the return type of each step is what pins the
+ * order, so no runtime check has to.
  */
 import type {
   AliasBindingBuilder,
@@ -15,44 +16,38 @@ import type {
   SingletonBindingBuilder,
   SingletonLifecycleBuilder,
   TransientBindingBuilder,
-} from "#/binding";
-import { bindingSlotEquals, clearBindingFrame, createBinding, DEFAULT_BINDING_SLOT, refinableFields } from "#/binding";
-import type { InjectableDependency, ResolvedDependencyValue } from "#/decorators/inject";
-import { normalizeToDescriptor } from "#/decorators/inject";
-import { ChainNotRegisteredError, SelfBindingRequiresClassError } from "#/errors";
-import type { BindingRegistry } from "#/registry";
-import type { Token } from "#/token";
-import { tokenName } from "#/token";
+} from "#/core/binding";
+import { clearBindingFrame, createBinding, DEFAULT_BINDING_SLOT, refinableFields } from "#/core/binding";
+import type { BindingRegistry } from "#/core/registry";
+import type { BindingTag } from "#/core/tag";
+import { tagKeyMaskOf } from "#/core/tag";
+import type { Token } from "#/core/token";
+import { tokenName } from "#/core/token";
 import type {
   ActivationHandler,
+  BindingConstraint,
   BindingIdentifier,
   BindingScope,
-  ConstraintContext,
   Constructor,
   DeactivationHandler,
   ResolutionContext,
-} from "#/types";
-
-function updateSlotTag(slot: BindingSlot, tag: string, value: unknown): BindingSlot {
+} from "#/core/types";
+import { ChainNotRegisteredError, SelfBindingRequiresClassError } from "#/errors/errors";
+import type { InjectableDependency, ResolvedDependencyValue } from "#/injection/descriptor";
+import { normalizeToDescriptor } from "#/injection/descriptor";
+import type { ScopeManager } from "#/lifecycle/scope-manager";
+
+/** One criterion per key: re-tagging the same key replaces it rather than asking for both values. */
+function updateSlotTag(slot: BindingSlot, criterion: BindingTag): BindingSlot {
   const tags = [...slot.tags];
-  const existingIndex = tags.findIndex(([key]) => key === tag);
+  const existingIndex = tags.findIndex((existing) => existing.key === criterion.key);
   if (existingIndex === -1) {
-    tags.push([tag, value]);
+    tags.push(criterion);
   } else {
-    tags[existingIndex] = [tag, value];
+    tags[existingIndex] = criterion;
   }
-  return { ...slot, tags };
-}
-
-// True when re-adding `restored` would immediately be displaced again by `current`
-// (both slot-based with equal slots) — in that case the replacement was legitimate.
-function displacesRestoredBinding(current: Binding, restored: Binding): boolean {
-  const currentIsPurePredicate =
-    current.predicate !== undefined && current.slot.name === undefined && current.slot.tags.length === 0;
-  if (currentIsPurePredicate) {
-    return false;
-  }
-  return bindingSlotEquals(current.slot, restored.slot);
+  // Frozen like DEFAULT_BINDING_SLOT's list: frames and snapshots alias a slot's tags.
+  return { ...slot, tags: Object.freeze(tags), keyMask: tagKeyMaskOf(tags) };
 }
 
 /** Record a module's binding id, dropping the id the chain re-slotted away from. */
@@ -70,7 +65,7 @@ function trackBindingForModule(
   ids.push(id);
 }
 
-// ── Registration target ───────────────────────────────────────────────────────
+// ── Registration target ──────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
  * Where a chain registers, and on whose behalf.
@@ -82,10 +77,11 @@ function trackBindingForModule(
  */
 export interface BindingRegistration {
   readonly registry: BindingRegistry;
+  readonly scope: ScopeManager;
   readonly moduleBindingIds: Array<BindingIdentifier> | undefined;
 }
 
-// ── BindingChain ──────────────────────────────────────────────────────────────
+// ── BindingChain ─────────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
  * The one builder behind `bind()` and every `to*()` return type. Each interface exposes only the
@@ -109,6 +105,8 @@ export class BindingChain<Value>
   #binding: Binding<Value> | undefined;
   // Allocated only by a chain that actually displaces something — most never do.
   #displacedByChain: Array<Binding> | undefined;
+  // Registry version after this chain's last write — a mismatch means someone else wrote in between.
+  #versionAfterLastWrite = -1;
   readonly #token: Token<Value> | Constructor<Value>;
   readonly #registration: BindingRegistration;
 
@@ -134,7 +132,7 @@ export class BindingChain<Value>
     return this;
   }
 
-  // ── Registration ───────────────────────────────────────────────────────────
+  // ── Registration ───────────────────────────────────────────────────────────────────────────────────────────────────
 
   to(type: Constructor<Value>): BindingBuilder<Value> {
     return this.#register({ kind: "class", target: type, scope: "transient" });
@@ -187,37 +185,51 @@ export class BindingChain<Value>
     return this.#register({ kind: "alias", scope: "transient", target });
   }
 
-  // ── Refinement ─────────────────────────────────────────────────────────────
+  // ── Refinement ─────────────────────────────────────────────────────────────────────────────────────────────────────
 
   // Slot and predicate are what the registry indexes on, so a re-slot rebuilds the binding and
   // re-registers it — under the original id, keeping `id()` stable for the whole chain.
-  #reslot(slot: BindingSlot, predicate: ((ctx: ConstraintContext) => boolean) | undefined): this {
+  #reslot(slot: BindingSlot, predicate: BindingConstraint | undefined): this {
     const previous = this.#registered();
     this.#binding = createBinding(previous, previous.token, slot, predicate, previous.id);
     this.#commit(this.#binding, previous.id);
+    // The tracked-singleton list holds object references, and the re-slot just replaced the object.
+    this.#registration.scope.replaceSingleton(previous as Binding, this.#binding as Binding);
     return this;
   }
 
   #withScope(scope: BindingScope): this {
     const binding = this.#registered();
-    refinableFields(binding).scope = scope;
+    if (binding.scope !== scope) {
+      // An instance cached under the old scope must not survive the change — a later flip back
+      // to that scope would resurrect it.
+      this.#registration.scope.deleteSingleton(binding);
+      this.#registration.scope.deleteScoped(binding.id);
+      refinableFields(binding).scope = scope;
+    }
     // The frame reports the scope, so a resolve before this call memoized the previous one.
     clearBindingFrame(binding);
     this.#registration.registry.touch();
+    this.#versionAfterLastWrite = this.#registration.registry.version;
     return this;
   }
 
-  when(predicate: (ctx: ConstraintContext) => boolean): this {
-    return this.#reslot(this.#registered().slot, predicate);
+  // SPEC calls a candidate a binding that passes *all* of a chain's predicates, and the chain type
+  // reads as refinement, so a second `when()` narrows rather than replaces.
+  when(predicate: BindingConstraint): this {
+    const binding = this.#registered();
+    const previous = binding.predicate;
+
+    return this.#reslot(binding.slot, previous === undefined ? predicate : (ctx) => previous(ctx) && predicate(ctx));
   }
 
   whenNamed(name: string): this {
     return this.#reslot({ ...this.#registered().slot, name }, this.#registered().predicate);
   }
 
-  whenTagged(tag: string, value: unknown): this {
+  whenTagged(criterion: BindingTag): this {
     const binding = this.#registered();
-    return this.#reslot(updateSlotTag(binding.slot, tag, value), binding.predicate);
+    return this.#reslot(updateSlotTag(binding.slot, criterion), binding.predicate);
   }
 
   whenDefault(): this {
@@ -242,12 +254,14 @@ export class BindingChain<Value>
   onActivation(fn: ActivationHandler<Value>): this {
     refinableFields(this.#registered()).onActivation = fn;
     this.#registration.registry.touch();
+    this.#versionAfterLastWrite = this.#registration.registry.version;
     return this;
   }
 
   onDeactivation(fn: DeactivationHandler<Value>): this {
     refinableFields(this.#registered()).onDeactivation = fn;
     this.#registration.registry.touch();
+    this.#versionAfterLastWrite = this.#registration.registry.version;
     return this;
   }
 
@@ -255,10 +269,10 @@ export class BindingChain<Value>
     return this.#registered().id;
   }
 
-  // ── Registry ───────────────────────────────────────────────────────────────
+  // ── Registry ───────────────────────────────────────────────────────────────────────────────────────────────────────
 
   /**
-   * Register `binding`, first removing `previousId` when the chain is re-slotting.
+   * Registers `binding`, first removing `previousId` when the chain is re-slotting.
    *
    * @remarks A `when*()` that follows `to*()` re-slots an already-live binding and can displace one
    * the final shape would never conflict with. Those stay parked in `#displacedByChain` until the
@@ -271,24 +285,38 @@ export class BindingChain<Value>
     const registered = binding as Binding;
 
     if (previousId !== undefined) {
-      registry.removeById(previousId);
+      // A registry someone else wrote since this chain's last write invalidates the parked
+      // snapshot: restoring it could undo an unbind or shadow a newer binding.
+      if (registry.version !== this.#versionAfterLastWrite) {
+        this.#displacedByChain = undefined;
+      }
+      if (registry.removeById(previousId) === undefined) {
+        // The chain's binding is no longer live (unbound or displaced) — a refinement must not
+        // resurrect it, so the chain goes inert against the registry.
+        this.#displacedByChain = undefined;
+        this.#versionAfterLastWrite = registry.version;
+        return;
+      }
     }
     const displaced = registry.add(registered);
     if (displaced !== undefined) {
       (this.#displacedByChain ??= []).push(displaced);
     }
     if (previousId !== undefined && this.#displacedByChain !== undefined) {
-      this.#restoreNonConflicting(registered, this.#displacedByChain);
+      this.#restoreNonConflicting(this.#displacedByChain);
     }
     if (moduleBindingIds !== undefined) {
       trackBindingForModule(moduleBindingIds, registered.id, previousId);
     }
+    this.#versionAfterLastWrite = registry.version;
   }
 
-  #restoreNonConflicting(binding: Binding, displaced: Array<Binding>): void {
+  #restoreNonConflicting(displaced: Array<Binding>): void {
     for (let index = displaced.length - 1; index >= 0; index -= 1) {
       const candidate = displaced[index]!;
-      if (!displacesRestoredBinding(binding, candidate)) {
+      // A restore must never displace: a slot that has been re-occupied keeps its occupant, and
+      // the candidate stays parked.
+      if (!this.#registration.registry.hasSlotOccupant(candidate)) {
         this.#registration.registry.add(candidate);
         displaced.splice(index, 1);
       }