@codefast/di 0.3.16-canary.2 → 0.3.16-canary.3

package/dist/resolve-options.mjs

@@ -1,4 +1,12 @@
 //#region src/resolve-options.ts
+/** Shared core: build a ResolveOptions from already-normalised name + tags. */
+function buildOptions(name, tags) {
+	if (name === void 0 && tags === void 0) return;
+	const options = {};
+	if (name !== void 0) options.name = name;
+	if (tags !== void 0) options.tags = tags;
+	return options;
+}
 /**
 * Builds a {@link ResolveOptions} safe for `exactOptionalPropertyTypes`:
 * omits keys instead of assigning `undefined`.
@@ -6,10 +14,7 @@
 * @since 0.3.16-canary.0
 */
 function injectionSlotToResolveOptions(injectionSlot) {
-	const options = {};
-	if (injectionSlot.name !== void 0) options.name = injectionSlot.name;
-	if (injectionSlot.tags !== void 0) options.tags = injectionSlot.tags;
-	return options.name !== void 0 || options.tags !== void 0 ? options : void 0;
+	return buildOptions(injectionSlot.name, injectionSlot.tags);
 }
 /**
 * Hint from a binding {@link BindingSlot} (tags may be empty; omits when nothing to match).
@@ -17,10 +22,7 @@ function injectionSlotToResolveOptions(injectionSlot) {
 * @since 0.3.16-canary.0
 */
 function bindingSlotToResolveOptions(bindingSlot) {
-	const options = {};
-	if (bindingSlot.name !== void 0) options.name = bindingSlot.name;
-	if (bindingSlot.tags.length > 0) options.tags = bindingSlot.tags;
-	return options.name !== void 0 || options.tags !== void 0 ? options : void 0;
+	return buildOptions(bindingSlot.name, bindingSlot.tags.length > 0 ? bindingSlot.tags : void 0);
 }
 //#endregion
 export { bindingSlotToResolveOptions, injectionSlotToResolveOptions };

package/dist/resolver.d.mts

@@ -82,6 +82,11 @@ declare class DependencyResolver {
   private _getResolutionFrame;
   private _needsActivation;
   private _refreshClassPostConstructCache;
+  /**
+   * Refreshes the post-construct cache for class bindings on first instantiation and
+   * returns the (possibly updated) shouldActivate flag.
+   */
+  private _refreshActivationCacheIfNeeded;
   private _requiresResolutionContext;
   private _acquireSyncResolutionContext;
 }

package/dist/resolver.mjs

@@ -176,13 +176,7 @@ var DependencyResolver = class {
 		try {
 			const resolutionCtx = needsActivation || this._requiresResolutionContext(binding) ? this._acquireSyncResolutionContext(resolutionPath, resolutionStack, hint) : void 0;
 			const instance = this._instantiateSync(binding, resolutionCtx, resolutionPath, resolutionStack);
-			let shouldActivate = needsActivation;
-			if (binding.kind === "class" && this._classHasPostConstruct.get(binding.target) === void 0) {
-				this._refreshClassPostConstructCache(binding.target);
-				this._activationNeedByBindingId.delete(binding.id);
-				shouldActivate = this._needsActivation(binding);
-			}
-			const activated = shouldActivate ? this._lifecycle.runActivationSync(resolutionCtx, binding, instance, this._metadataReader) : instance;
+			const activated = this._refreshActivationCacheIfNeeded(binding, needsActivation) ? this._lifecycle.runActivationSync(resolutionCtx, binding, instance, this._metadataReader) : instance;
 			if (scope === "singleton") this._scope.setSingleton(binding.id, activated);
 			else if (scope === "scoped") this._scope.setScoped(binding.id, activated);
 			return activated;
@@ -351,13 +345,7 @@ var DependencyResolver = class {
 			if (scope === "singleton") {
 				const createSingletonPromise = async () => {
 					const instance = await this._instantiateAsync(binding, resolutionCtx, resolutionPath, resolutionStack);
-					let shouldActivate = needsActivation;
-					if (binding.kind === "class" && this._classHasPostConstruct.get(binding.target) === void 0) {
-						this._refreshClassPostConstructCache(binding.target);
-						this._activationNeedByBindingId.delete(binding.id);
-						shouldActivate = this._needsActivation(binding);
-					}
-					const activated = shouldActivate ? await this._lifecycle.runActivation(resolutionCtx, binding, instance, this._metadataReader) : instance;
+					const activated = this._refreshActivationCacheIfNeeded(binding, needsActivation) ? await this._lifecycle.runActivation(resolutionCtx, binding, instance, this._metadataReader) : instance;
 					this._scope.setSingleton(binding.id, activated);
 					this._scope.clearInflight(binding.id);
 					return activated;
@@ -370,13 +358,7 @@ var DependencyResolver = class {
 				return await singletonPromise;
 			}
 			const instance = await this._instantiateAsync(binding, resolutionCtx, resolutionPath, resolutionStack);
-			let shouldActivate = needsActivation;
-			if (binding.kind === "class" && this._classHasPostConstruct.get(binding.target) === void 0) {
-				this._refreshClassPostConstructCache(binding.target);
-				this._activationNeedByBindingId.delete(binding.id);
-				shouldActivate = this._needsActivation(binding);
-			}
-			const activated = shouldActivate ? await this._lifecycle.runActivation(resolutionCtx, binding, instance, this._metadataReader) : instance;
+			const activated = this._refreshActivationCacheIfNeeded(binding, needsActivation) ? await this._lifecycle.runActivation(resolutionCtx, binding, instance, this._metadataReader) : instance;
 			if (scope === "scoped") this._scope.setScoped(binding.id, activated);
 			return activated;
 		} finally {
@@ -754,6 +736,18 @@ var DependencyResolver = class {
 		const hasPostConstruct = lifecycle !== void 0 && lifecycle.postConstruct !== void 0 && lifecycle.postConstruct.length > 0;
 		this._classHasPostConstruct.set(target, hasPostConstruct);
 	}
+	/**
+	* Refreshes the post-construct cache for class bindings on first instantiation and
+	* returns the (possibly updated) shouldActivate flag.
+	*/
+	_refreshActivationCacheIfNeeded(binding, needsActivation) {
+		if (binding.kind === "class" && this._classHasPostConstruct.get(binding.target) === void 0) {
+			this._refreshClassPostConstructCache(binding.target);
+			this._activationNeedByBindingId.delete(binding.id);
+			return this._needsActivation(binding);
+		}
+		return needsActivation;
+	}
 	_requiresResolutionContext(binding) {
 		return binding.kind === "dynamic" || binding.kind === "dynamic-async";
 	}

package/dist/types.d.mts

@@ -2,6 +2,12 @@ import { Constructor } from "./constructor-type.mjs";
 import { Token } from "./token.mjs";
 
 //#region src/types.d.ts
+/**
+ * A single [tag, value] pair used in slot constraints and resolve hints.
+ *
+ * @since 0.3.16-canary.0
+ */
+type BindingTag = readonly [tag: string, value: unknown];
 /**
  * Token or class constructor used as a binding / injection / resolve key.
  *
@@ -40,8 +46,8 @@ interface ResolveOptions {
    * Single-tag shorthand — semantics match including one pair in `tags`.
    * Enables fast-path lookup alongside `tags`.
    */
-  tag?: readonly [tag: string, value: unknown];
-  tags?: ReadonlyArray<readonly [tag: string, value: unknown]>;
+  tag?: BindingTag;
+  tags?: ReadonlyArray<BindingTag>;
 }
 /**
  * @since 0.3.16-canary.0
@@ -53,7 +59,7 @@ interface ResolutionFrame {
   readonly kind: BindingKind;
   readonly slot: {
     readonly name: string | undefined;
-    readonly tags: ReadonlyArray<readonly [tag: string, value: unknown]>;
+    readonly tags: ReadonlyArray<BindingTag>;
   };
 }
 /**
@@ -83,4 +89,4 @@ interface ResolutionContext {
  */
 type TokenValue<Type> = Type extends Token<infer Value> ? Value : Type extends Constructor<infer Value> ? Value : never;
 //#endregion
-export { ActivationHandler, BindingIdentifier, BindingKind, BindingScope, ConstraintContext, type Constructor, DeactivationHandler, DependencyKey, ResolutionContext, ResolutionFrame, ResolveOptions, TokenValue };
+export { ActivationHandler, BindingIdentifier, BindingKind, BindingScope, BindingTag, ConstraintContext, type Constructor, DeactivationHandler, DependencyKey, ResolutionContext, ResolutionFrame, ResolveOptions, TokenValue };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codefast/di",
-  "version": "0.3.16-canary.2",
+  "version": "0.3.16-canary.3",
   "description": "Lightweight dependency injection primitives for Codefast",
   "keywords": [
     "codefast",
@@ -18,6 +18,7 @@
   },
   "files": [
     "dist",
+    "src",
     "CHANGELOG.md",
     "README.md",
     "LICENSE"
@@ -45,122 +46,147 @@
   },
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/index.d.mts",
       "import": "./dist/index.mjs"
     },
     "./binding": {
+      "source": "./src/binding.ts",
       "types": "./dist/binding.d.mts",
       "import": "./dist/binding.mjs"
     },
     "./binding-scope": {
+      "source": "./src/binding-scope.ts",
       "types": "./dist/binding-scope.d.mts",
       "import": "./dist/binding-scope.mjs"
     },
     "./binding-select": {
+      "source": "./src/binding-select.ts",
       "types": "./dist/binding-select.d.mts",
       "import": "./dist/binding-select.mjs"
     },
     "./constraints": {
+      "source": "./src/constraints.ts",
       "types": "./dist/constraints.d.mts",
       "import": "./dist/constraints.mjs"
     },
     "./constructor-type": {
+      "source": "./src/constructor-type.ts",
       "types": "./dist/constructor-type.d.mts",
       "import": "./dist/constructor-type.mjs"
     },
     "./container": {
+      "source": "./src/container.ts",
       "types": "./dist/container.d.mts",
       "import": "./dist/container.mjs"
     },
     "./decorators/inject": {
+      "source": "./src/decorators/inject.ts",
       "types": "./dist/decorators/inject.d.mts",
       "import": "./dist/decorators/inject.mjs"
     },
     "./decorators/injectable": {
+      "source": "./src/decorators/injectable.ts",
       "types": "./dist/decorators/injectable.d.mts",
       "import": "./dist/decorators/injectable.mjs"
     },
     "./decorators/lifecycle-decorators": {
+      "source": "./src/decorators/lifecycle-decorators.ts",
       "types": "./dist/decorators/lifecycle-decorators.d.mts",
       "import": "./dist/decorators/lifecycle-decorators.mjs"
     },
     "./dependency-graph": {
+      "source": "./src/dependency-graph.ts",
       "types": "./dist/dependency-graph.d.mts",
       "import": "./dist/dependency-graph.mjs"
     },
     "./environment": {
+      "source": "./src/environment.ts",
       "types": "./dist/environment.d.mts",
       "import": "./dist/environment.mjs"
     },
     "./errors": {
+      "source": "./src/errors.ts",
       "types": "./dist/errors.d.mts",
       "import": "./dist/errors.mjs"
     },
     "./graph-adapters/cytoscape": {
+      "source": "./src/graph-adapters/cytoscape.ts",
       "types": "./dist/graph-adapters/cytoscape.d.mts",
       "import": "./dist/graph-adapters/cytoscape.mjs"
     },
     "./graph-adapters/dot": {
+      "source": "./src/graph-adapters/dot.ts",
       "types": "./dist/graph-adapters/dot.d.mts",
       "import": "./dist/graph-adapters/dot.mjs"
     },
     "./graph-adapters/reactflow": {
+      "source": "./src/graph-adapters/reactflow.ts",
       "types": "./dist/graph-adapters/reactflow.d.mts",
       "import": "./dist/graph-adapters/reactflow.mjs"
     },
-    "./graph-adapters/types": {
-      "types": "./dist/graph-adapters/types.d.mts",
-      "import": "./dist/graph-adapters/types.mjs"
-    },
     "./inspector": {
+      "source": "./src/inspector.ts",
       "types": "./dist/inspector.d.mts",
       "import": "./dist/inspector.mjs"
     },
     "./lifecycle": {
+      "source": "./src/lifecycle.ts",
       "types": "./dist/lifecycle.d.mts",
       "import": "./dist/lifecycle.mjs"
     },
     "./metadata/metadata-keys": {
+      "source": "./src/metadata/metadata-keys.ts",
       "types": "./dist/metadata/metadata-keys.d.mts",
       "import": "./dist/metadata/metadata-keys.mjs"
     },
     "./metadata/metadata-reader-token": {
+      "source": "./src/metadata/metadata-reader-token.ts",
       "types": "./dist/metadata/metadata-reader-token.d.mts",
       "import": "./dist/metadata/metadata-reader-token.mjs"
     },
     "./metadata/metadata-types": {
+      "source": "./src/metadata/metadata-types.ts",
       "types": "./dist/metadata/metadata-types.d.mts",
       "import": "./dist/metadata/metadata-types.mjs"
     },
     "./metadata/symbol-metadata-reader": {
+      "source": "./src/metadata/symbol-metadata-reader.ts",
       "types": "./dist/metadata/symbol-metadata-reader.d.mts",
       "import": "./dist/metadata/symbol-metadata-reader.mjs"
     },
     "./module": {
+      "source": "./src/module.ts",
       "types": "./dist/module.d.mts",
       "import": "./dist/module.mjs"
     },
     "./registry": {
+      "source": "./src/registry.ts",
       "types": "./dist/registry.d.mts",
       "import": "./dist/registry.mjs"
     },
     "./resolve-options": {
+      "source": "./src/resolve-options.ts",
       "types": "./dist/resolve-options.d.mts",
       "import": "./dist/resolve-options.mjs"
     },
     "./resolver": {
+      "source": "./src/resolver.ts",
       "types": "./dist/resolver.d.mts",
       "import": "./dist/resolver.mjs"
     },
     "./scope": {
+      "source": "./src/scope.ts",
       "types": "./dist/scope.d.mts",
       "import": "./dist/scope.mjs"
     },
     "./token": {
+      "source": "./src/token.ts",
       "types": "./dist/token.d.mts",
       "import": "./dist/token.mjs"
     },
     "./types": {
+      "source": "./src/types.ts",
       "types": "./dist/types.d.mts",
       "import": "./dist/types.mjs"
     },
@@ -170,20 +196,20 @@
     "access": "public"
   },
   "devDependencies": {
-    "@babel/plugin-proposal-decorators": "^7.29.0",
+    "@babel/plugin-proposal-decorators": "8.0.0-rc.6",
     "@rolldown/plugin-babel": "^0.2.3",
-    "@types/node": "^25.7.0",
-    "@typescript/native-preview": "7.0.0-dev.20260514.1",
-    "@vitest/coverage-v8": "^4.1.6",
+    "@types/node": "^25.9.1",
+    "@typescript/native-preview": "7.0.0-dev.20260526.1",
+    "@vitest/coverage-v8": "^4.1.7",
     "expect-type": "^1.3.0",
     "tsdown": "^0.22.0",
-    "tsx": "^4.22.0",
+    "tsx": "^4.22.3",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.6",
-    "@codefast/typescript-config": "0.3.16-canary.2"
+    "vitest": "^4.1.7",
+    "@codefast/typescript-config": "0.3.16-canary.3"
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=24.0.0"
   },
   "scripts": {
     "build": "tsdown",

package/src/binding-scope.ts

@@ -0,0 +1,26 @@
+import type { Binding } from "#/binding";
+import type { BindingScope } from "#/types";
+
+/**
+ * Runtime scope used for validation and introspection. Alias bindings are treated as transient
+ * because they defer scope to the aliased target at resolve time.
+ *
+ * @since 0.3.16-canary.0
+ */
+export function effectiveBindingScope(binding: Binding): BindingScope {
+  switch (binding.kind) {
+    case "alias":
+      return "transient";
+    case "class":
+    case "constant":
+    case "dynamic":
+    case "dynamic-async":
+    case "resolved":
+    case "resolved-async":
+      return binding.scope;
+    default: {
+      const exhaustive: never = binding;
+      return exhaustive;
+    }
+  }
+}

package/src/binding-select.ts

@@ -0,0 +1,167 @@
+import type { Binding } from "#/binding";
+import type { BindingTag, ConstraintContext, ResolveOptions } from "#/types";
+import { AmbiguousBindingError } from "#/errors";
+
+/**
+ * Select a single candidate from a list of bindings using slot matching + predicates.
+ * Returns undefined if no match, throws AmbiguousBindingError if multiple match.
+ *
+ * @since 0.3.16-canary.0
+ */
+export function selectBinding(
+  bindings: ReadonlyArray<Binding>,
+  hint: ResolveOptions | undefined,
+  ctx: ConstraintContext,
+  tokenDisplayName: string,
+): Binding | undefined {
+  const candidates = filterBindings(bindings, hint, ctx);
+  if (candidates.length === 0) {
+    return undefined;
+  }
+  if (candidates.length === 1) {
+    return candidates[0];
+  }
+  // Multiple candidates — check if any is unambiguous (slot-based selection)
+  // Slot-based bindings already have last-wins applied in registry, so
+  // multiple candidates here means ambiguous predicate-only bindings
+  throw new AmbiguousBindingError(
+    tokenDisplayName,
+    candidates.map((c) => c.id),
+  );
+}
+
+/**
+ * Select all candidates matching hint + predicates.
+ *
+ * @since 0.3.16-canary.0
+ */
+export function selectAllBindings(
+  bindings: ReadonlyArray<Binding>,
+  hint: ResolveOptions | undefined,
+  ctx: ConstraintContext,
+): Array<Binding> {
+  return filterBindings(bindings, hint, ctx, "all");
+}
+
+function filterBindings(
+  bindings: ReadonlyArray<Binding>,
+  hint: ResolveOptions | undefined,
+  ctx: ConstraintContext,
+  selectionMode: "single" | "all" = "single",
+): Array<Binding> {
+  if (hint === undefined) {
+    const resultWithoutHint: Array<Binding> = [];
+    if (selectionMode === "all") {
+      for (const binding of bindings) {
+        if (matchesPredicate(binding, ctx)) {
+          resultWithoutHint.push(binding);
+        }
+      }
+    } else {
+      for (const binding of bindings) {
+        const slot = binding.slot;
+        if (slot.name === undefined && slot.tags.length === 0 && matchesPredicate(binding, ctx)) {
+          resultWithoutHint.push(binding);
+        }
+      }
+    }
+    return resultWithoutHint;
+  }
+
+  const result: Array<Binding> = [];
+  for (const binding of bindings) {
+    const slotMatched =
+      selectionMode === "all"
+        ? matchesSlotForResolveAll(binding, hint)
+        : matchesSlot(binding, hint);
+    if (slotMatched && matchesPredicate(binding, ctx)) {
+      result.push(binding);
+    }
+  }
+  return result;
+}
+
+function matchesSlotForResolveAll(binding: Binding, hint: ResolveOptions | undefined): boolean {
+  const hasExplicitSlotFilter =
+    hint !== undefined &&
+    (hint.name !== undefined ||
+      (hint.tags !== undefined && hint.tags.length > 0) ||
+      hint.tag !== undefined);
+  if (!hasExplicitSlotFilter) {
+    return true;
+  }
+  return matchesSlot(binding, hint);
+}
+
+function matchesSlot(binding: Binding, hint: ResolveOptions | undefined): boolean {
+  const slot = binding.slot;
+  const hintName = hint?.name;
+  const hintTags = hint?.tags;
+  const singleHintTag = hint?.tag;
+  const hasHintTags = (hintTags?.length ?? 0) > 0 || singleHintTag !== undefined;
+
+  // Match by name
+  if (slot.name !== undefined) {
+    if (hintName === undefined) {
+      return false;
+    }
+    if (slot.name !== hintName) {
+      return false;
+    }
+  } else if (hintName !== undefined) {
+    // Binding has no name but hint requests a specific name — no match
+    return false;
+  }
+
+  // Match by tags — binding's tags must all be present in hint
+  if (slot.tags.length > 0) {
+    if (!hasHintTags) {
+      return false;
+    }
+    for (const [tagKey, tagValue] of slot.tags) {
+      if (!matchHintTag(tagKey, tagValue, hintTags, singleHintTag)) {
+        return false;
+      }
+    }
+  } else if (hasHintTags) {
+    // Binding has no tags but hint requires tags — no match for tagged slots
+    // But: default slot (no tags, no name) can match when hint has tags if there are no tag-slotted bindings
+    // Actually per spec: resolveAll with tags only returns bindings that have those tags
+    // and resolve with tags requires exact match
+    return false;
+  }
+
+  return true;
+}
+
+function matchHintTag(
+  tagKey: string,
+  tagValue: unknown,
+  hintTags: ReadonlyArray<BindingTag> | undefined,
+  singleHintTag: BindingTag | undefined,
+): boolean {
+  if (
+    singleHintTag !== undefined &&
+    singleHintTag[0] === tagKey &&
+    Object.is(singleHintTag[1], tagValue)
+  ) {
+    return true;
+  }
+  if (hintTags === undefined || hintTags.length === 0) {
+    return false;
+  }
+  for (let index = 0; index < hintTags.length; index += 1) {
+    const hintTag = hintTags[index]!;
+    if (hintTag[0] === tagKey && Object.is(hintTag[1], tagValue)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function matchesPredicate(binding: Binding, ctx: ConstraintContext): boolean {
+  if (binding.predicate === undefined) {
+    return true;
+  }
+  return binding.predicate(ctx);
+}