@codefast/di 0.3.14-canary.0 → 0.3.14-canary.2

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @codefast/di
 
+## 0.3.14-canary.2
+
+### Patch Changes
+
+- [`4435cfb`](https://github.com/codefastlabs/codefast/commit/4435cfbf4883d018c29942aa571422bb95f73f97) Thanks [@thevuong](https://github.com/thevuong)! - refactor(di): enhance binding key generation and simplify transient binding logic
+
+- [`427bff6`](https://github.com/codefastlabs/codefast/commit/427bff64196ba62ccfcf1e893d93714875b7b42e) Thanks [@thevuong](https://github.com/thevuong)! - refactor(di): update predicates and improve documentation
+
+- [`408a9ad`](https://github.com/codefastlabs/codefast/commit/408a9ad5903eb7f1f15ebc576017d2122a18722f) Thanks [@thevuong](https://github.com/thevuong)! - refactor(di): improve binding resolution logic in DefaultContainer and BindingRegistry
+
+- [`4957e0e`](https://github.com/codefastlabs/codefast/commit/4957e0e8b4b2428447ef11380397b03deef0b092) Thanks [@thevuong](https://github.com/thevuong)! - fix(vitest): update test file patterns to use .test extension
+
+- [`4601be2`](https://github.com/codefastlabs/codefast/commit/4601be25746e628c7d74cebaa9ee362e80301a19) Thanks [@thevuong](https://github.com/thevuong)! - feat(di): implement fast resolution mechanism in DefaultContainer
+
+- [`568f370`](https://github.com/codefastlabs/codefast/commit/568f370143b5951fa018472ba6e882d8d599f5e7) Thanks [@thevuong](https://github.com/thevuong)! - refactor(di): enhance transient binding handling in DependencyResolver
+
+- [`ea57eab`](https://github.com/codefastlabs/codefast/commit/ea57eab321f4e57361520de3d6356abf900acbf8) Thanks [@thevuong](https://github.com/thevuong)! - refactor(benchmarks): enhance binding resolution and improve transient binding handling
+
+## 0.3.14-canary.1
+
+### Patch Changes
+
+- [`2097bf6`](https://github.com/codefastlabs/codefast/commit/2097bf6c81639506c4c7f3f8a9a0f72bdb49ea49) Thanks [@thevuong](https://github.com/thevuong)! - refactor(di): update generateDependencyGraph method for improved clarity and functionality
+
+- [`0720553`](https://github.com/codefastlabs/codefast/commit/0720553f01bfae88725c1688efaf608e2cf45493) Thanks [@thevuong](https://github.com/thevuong)! - feat(di): add graph adapters for visualization formats
+
+- [`ab92dc7`](https://github.com/codefastlabs/codefast/commit/ab92dc7e5d864727bb5dcb1f2a3d08660c4112e8) Thanks [@thevuong](https://github.com/thevuong)! - refactor(di): enhance type definitions and documentation for clarity
+
 ## 0.3.14-canary.0
 
 ### Patch Changes

package/README.md

@@ -93,32 +93,42 @@ yarn add @codefast/di
 ## Quick Start
 
 ```typescript
-import { Container, inject, injectable, token } from "@codefast/di";
+import { Container, injectable, token } from "@codefast/di";
 
 interface Logger {
-  log(message: string): void;
+  info(message: string): void;
 }
 
 const LoggerToken = token<Logger>("Logger");
 
 @injectable([LoggerToken])
-class AppService {
+class CheckoutService {
   constructor(private readonly logger: Logger) {}
 
-  run(): void {
-    this.logger.log("App started");
+  complete(orderId: string): void {
+    this.logger.info(`Order ${orderId} completed`);
   }
 }
 
 const container = Container.create();
 
-container.bind(LoggerToken).toConstantValue({ log: console.log });
-container.bind(AppService).toSelf().singleton();
+// Production wiring
+container.bind(LoggerToken).toConstantValue({
+  info: (message) => console.log(`[prod] ${message}`),
+});
+container.bind(CheckoutService).toSelf();
+
+container.resolve(CheckoutService).complete("ORD-1001");
 
-container.resolve(AppService).run(); // "App started"
+// Same service, test wiring
+container.rebind(LoggerToken).toConstantValue({
+  info: (message) => console.log(`[test] ${message}`),
+});
+
+container.resolve(CheckoutService).complete("ORD-1002");
 ```
 
-The `@injectable([LoggerToken])` call lists constructor dependencies in order. Wrap an entry with `inject(token, options)` or `optional(token, options)` when you need a named/tagged hint or optional semantics.
+`@injectable([...])` lists constructor dependencies in order. The key idea: business classes (`CheckoutService`) stay unchanged while behavior swaps by rebinding infrastructure (`LoggerToken`) per environment.
 
 ---
 
@@ -217,8 +227,8 @@ Multiple bindings can share the same token. A constraint picks the right one at
 **Named**
 
 ```typescript
-container.bind(LoggerToken).whenNamed("file").toConstantValue(fileLogger);
-container.bind(LoggerToken).whenNamed("console").toConstantValue(consoleLogger);
+container.bind(LoggerToken).toConstantValue(fileLogger).whenNamed("file");
+container.bind(LoggerToken).toConstantValue(consoleLogger).whenNamed("console");
 
 container.resolve(LoggerToken, { name: "file" });
 ```
@@ -226,8 +236,8 @@ container.resolve(LoggerToken, { name: "file" });
 **Tagged** — the hint is a tuple `[tag, value]`:
 
 ```typescript
-container.bind(StorageToken).whenTagged("provider", "s3").to(S3Storage);
-container.bind(StorageToken).whenTagged("provider", "local").to(LocalStorage);
+container.bind(StorageToken).to(S3Storage).whenTagged("provider", "s3");
+container.bind(StorageToken).to(LocalStorage).whenTagged("provider", "local");
 
 container.resolve(StorageToken, { tag: ["provider", "s3"] });
 ```
@@ -235,9 +245,9 @@ container.resolve(StorageToken, { tag: ["provider", "s3"] });
 **Predicate** — inspect the full resolution graph:
 
 ```typescript
-import { whenAnyAncestorIs, whenParentIs, whenTargetTagged } from "@codefast/di";
+import { whenAnyAncestorIs, whenParentIs, whenParentTagged } from "@codefast/di/constraints";
 
-container.bind(LoggerToken).when(whenParentIs(DiagnosticsService)).toConstantValue(verboseLogger);
+container.bind(LoggerToken).toConstantValue(verboseLogger).when(whenParentIs(DiagnosticsService));
 ```
 
 Built-in predicates:
@@ -246,7 +256,7 @@ Built-in predicates:
 | ------------------------------ | --------------------------------------------------------------------------- |
 | `whenParentIs(key)`            | the direct parent binding was registered for `key`.                         |
 | `whenAnyAncestorIs(key)`       | any ancestor binding on the materialization stack was registered for `key`. |
-| `whenTargetTagged(tag, value)` | the immediate parent binding carries `tag` with `value`.                    |
+| `whenParentTagged(tag, value)` | the immediate parent binding carries `tag` with `value`.                    |
 
 For anything else, pass a custom `(ctx: ConstraintContext) => boolean` to `.when(predicate)`.
 
@@ -435,12 +445,21 @@ Control the environment heuristic via `NODE_ENV` — see `isDevelopmentOrTestEnv
 ### Introspection
 
 ```typescript
+import { toCytoscapeGraph } from "@codefast/di/graph-adapters/cytoscape";
+import { toDotGraph } from "@codefast/di/graph-adapters/dot";
+import { toReactFlowGraph } from "@codefast/di/graph-adapters/reactflow";
+
 const snapshot = container.inspect();
-const dot = container.generateDependencyGraph({ hideInternals: true });
-const json = container.generateDependencyGraph({ format: "json" });
+const json = container.generateDependencyGraph({ hideInternals: true });
+const dot = toDotGraph(json);
+
+// Adapters are pure converters from the canonical JSON graph.
+const cytoscape = toCytoscapeGraph(json);
+const reactflow = toReactFlowGraph(json);
 ```
 
-`generateDependencyGraph` returns a Graphviz DOT string by default, or a typed `ContainerGraphJson` when `format: "json"` is passed.
+`generateDependencyGraph` always returns the canonical typed `ContainerGraphJson` (`nodes` + `edges`).
+Keep visualization adapters (`toDotGraph`, `toCytoscapeGraph`, `toReactFlowGraph`, or your own converters) outside container/inspector core APIs and import them from direct subpaths under `@codefast/di/graph-adapters/*`.
 
 ### Disposal
 
@@ -464,22 +483,21 @@ Sync `using` is intentionally rejected: calling `Symbol.dispose` throws. Use `aw
 
 Modules bundle related bindings into reusable units. A module holds no runtime state and can be loaded into any number of containers.
 
-Inside module setup, binding semantics depend on whether a disambiguator is present before `to*()`:
+Use the same fluent order everywhere (including inside modules): `bind(token).to*(…).when*(…).scope()…`.
 
-- `api.bind(Token).to*(...)` uses last-wins for that token.
-- `api.bind(Token).whenNamed(...)` / `.whenTagged(...)` / `.when(...)` **before** `to*()` appends another multi-binding entry.
-- `api.bind(Token).to*(...).whenNamed(...)` updates only that single built binding; it does not switch later lines into append mode.
+- Register **multiple** implementations for one token with separate chains, e.g. `api.bind(T).to(A).whenNamed("a")` and `api.bind(T).to(B).whenNamed("b")`.
+- **Last-wins** applies per slot (default vs named vs tag-set), as in the main container API.
 
 ```typescript
 import { Container, Module } from "@codefast/di";
 
-const InfraModule = Module.create("Infra", (api) => {
+const InfrastructureModule = Module.create("Infra", (api) => {
   api.bind(LoggerToken).toConstantValue(console);
   api.bind(ConfigToken).toConstantValue(loadConfig());
 });
 
 const AppModule = Module.create("App", (api) => {
-  api.import(InfraModule);
+  api.import(InfrastructureModule);
   api.bind(UserRepository).toSelf().singleton();
   api.bind(UserServiceToken).to(UserService).transient();
 });
@@ -501,7 +519,7 @@ const container = await Container.fromModulesAsync(DbModule, AppModule);
 Load and unload on an existing container:
 
 ```typescript
-container.load(InfraModule, AppModule);
+container.load(InfrastructureModule, AppModule);
 await container.loadAsync(DbModule);
 
 container.unload(AppModule);
@@ -560,17 +578,24 @@ The root entry re-exports the full public API. Subpath exports are provided for
 | `@codefast/di/decorators/inject`               | `inject`, `optional`, `injectAll`, `isInjectionDescriptor`       |
 | `@codefast/di/decorators/injectable`           | `@injectable`, `getAutoRegistered`                               |
 | `@codefast/di/decorators/lifecycle-decorators` | `@postConstruct`, `@preDestroy`                                  |
-| `@codefast/di/constraints`                     | `whenParentIs`, `whenAnyAncestorIs`, `whenTargetTagged`          |
+| `@codefast/di/constraints`                     | `whenParentIs`, `whenAnyAncestorIs`, `whenParentTagged`          |
 | `@codefast/di/registry`                        | `BindingRegistry`                                                |
 | `@codefast/di/resolver`                        | `DependencyResolver` internals                                   |
 | `@codefast/di/scope`                           | `ScopeManager`                                                   |
-| `@codefast/di/scope-validation`                | `validateScopeRules`                                             |
 | `@codefast/di/lifecycle`                       | Activation/deactivation runners                                  |
 | `@codefast/di/dependency-graph`                | Dependency-edge collection helpers                               |
+| `@codefast/di/graph-adapters/cytoscape`        | Cytoscape adapter for `ContainerGraphJson`                       |
+| `@codefast/di/graph-adapters/dot`              | DOT adapter for `ContainerGraphJson`                             |
+| `@codefast/di/graph-adapters/reactflow`        | React Flow adapter for `ContainerGraphJson`                      |
+| `@codefast/di/graph-adapters/types`            | Shared graph adapter type definitions                            |
 | `@codefast/di/inspector`                       | `ContainerInspector`, snapshot + graph types                     |
 | `@codefast/di/errors`                          | Full `DiError` hierarchy                                         |
 | `@codefast/di/environment`                     | `isDevelopmentOrTestEnvironment`, `isProductionEnvironment`      |
-| `@codefast/di/metadata/*`                      | Metadata keys, types, readers, parameter registry                |
+| `@codefast/di/metadata/metadata-keys`          | Metadata symbol keys                                             |
+| `@codefast/di/metadata/metadata-types`         | Metadata type definitions                                        |
+| `@codefast/di/metadata/param-registry`         | Constructor parameter metadata registry                          |
+| `@codefast/di/metadata/symbol-metadata-reader` | Symbol metadata reader utilities                                 |
+| `@codefast/di/package.json`                    | Package metadata                                                 |
 
 See `package.json → exports` for the authoritative list.
 

package/dist/binding-scope.d.mts

@@ -0,0 +1,11 @@
+import { BindingScope } from "./types.mjs";
+import { Binding } from "./binding.mjs";
+
+//#region src/binding-scope.d.ts
+/**
+ * Runtime scope used for validation and introspection. Alias bindings are treated as transient
+ * because they defer scope to the aliased target at resolve time.
+ */
+declare function effectiveBindingScope(binding: Binding): BindingScope;
+//#endregion
+export { effectiveBindingScope };

package/dist/binding-scope.mjs

@@ -0,0 +1,19 @@
+//#region src/binding-scope.ts
+/**
+* Runtime scope used for validation and introspection. Alias bindings are treated as transient
+* because they defer scope to the aliased target at resolve time.
+*/
+function effectiveBindingScope(binding) {
+	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: return binding;
+	}
+}
+//#endregion
+export { effectiveBindingScope };

package/dist/binding-select.d.mts

@@ -1,33 +1,15 @@
-import { Token } from "./token.mjs";
-import { RegistryKey } from "./registry.mjs";
-import { Binding, ConstraintContext, Constructor, ResolveHint } from "./binding.mjs";
+import { ConstraintContext, ResolveOptions } from "./types.mjs";
+import { Binding } from "./binding.mjs";
 
 //#region src/binding-select.d.ts
 /**
- * Returns a human-readable label for a token or constructor (used in error messages and graph output).
+ * Select a single candidate from a list of bindings using slot matching + predicates.
+ * Returns undefined if no match, throws AmbiguousBindingError if multiple match.
  */
-declare function registryKeyLabel(key: Token<unknown> | Constructor<unknown>): string;
+declare function selectBinding(bindings: readonly Binding[], hint: ResolveOptions | undefined, ctx: ConstraintContext, tName: string): Binding | undefined;
 /**
- * Narrows a binding list by applying name/tag hints and `when()` constraint predicates.
- *
- * Filtering order: name filter → tag filter → constraint predicate. Bindings without a
- * constraint predicate always pass the constraint stage. Returns the surviving candidates
- * (may be empty).
+ * Select all candidates matching hint + predicates.
  */
-declare function filterMatchingBindings(bindings: readonly Binding<unknown>[], hint: ResolveHint | undefined, constraintCtx: ConstraintContext | undefined): readonly Binding<unknown>[];
-/**
- * Selects exactly one binding from the provided list, applying hint and constraint filtering.
- *
- * @throws {@link TokenNotBoundError} — `bindings` list is empty, or no candidate survives
- *   filtering without a name/tag hint.
- * @throws {@link NoMatchingBindingError} — a name/tag hint was provided but no candidate matched.
- * @throws {@link InternalError} — multiple candidates survive filtering (ambiguous binding).
- */
-declare function selectBindingForRegistry(bindings: readonly Binding<unknown>[], hint: ResolveHint | undefined, tokenLabel: string, pathLabels: readonly string[], constraintCtx: ConstraintContext | undefined): Binding<unknown>;
-/**
- * Convenience wrapper: looks up bindings for `key` and selects the default (no-hint,
- * no-constraint) binding. Throws {@link TokenNotBoundError} if the key is unregistered.
- */
-declare function selectDefaultBindingForKey(lookup: (key: RegistryKey) => readonly Binding<unknown>[] | undefined, key: RegistryKey, pathPrefix: readonly string[]): Binding<unknown>;
+declare function selectAllBindings(bindings: readonly Binding[], hint: ResolveOptions | undefined, ctx: ConstraintContext): Binding[];
 //#endregion
-export { filterMatchingBindings, registryKeyLabel, selectBindingForRegistry, selectDefaultBindingForKey };
+export { selectAllBindings, selectBinding };

package/dist/binding-select.mjs

@@ -1,61 +1,68 @@
-import { InternalError, NoMatchingBindingError, TokenNotBoundError } from "./errors.mjs";
+import { AmbiguousBindingError } from "./errors.mjs";
 //#region src/binding-select.ts
 /**
-* Returns a human-readable label for a token or constructor (used in error messages and graph output).
+* Select a single candidate from a list of bindings using slot matching + predicates.
+* Returns undefined if no match, throws AmbiguousBindingError if multiple match.
 */
-function registryKeyLabel(key) {
-	if (typeof key === "function") return key.name.length > 0 ? key.name : "(anonymous class)";
-	return key.name.trim().length > 0 ? key.name : "(anonymous token)";
+function selectBinding(bindings, hint, ctx, tName) {
+	const candidates = filterBindings(bindings, hint, ctx);
+	if (candidates.length === 0) return;
+	if (candidates.length === 1) return candidates[0];
+	throw new AmbiguousBindingError(tName, candidates.map((c) => c.id));
 }
 /**
-* Narrows a binding list by applying name/tag hints and `when()` constraint predicates.
-*
-* Filtering order: name filter → tag filter → constraint predicate. Bindings without a
-* constraint predicate always pass the constraint stage. Returns the surviving candidates
-* (may be empty).
+* Select all candidates matching hint + predicates.
 */
-function filterMatchingBindings(bindings, hint, constraintCtx) {
-	let candidates = bindings;
-	if (hint?.name !== void 0) candidates = candidates.filter((binding) => binding.bindingName === hint.name);
-	if (hint?.tag !== void 0) {
-		const [tagKey, tagValue] = hint.tag;
-		candidates = candidates.filter((binding) => Object.is(binding.tags.get(tagKey), tagValue));
-	}
-	if (constraintCtx !== void 0) candidates = candidates.filter((binding) => binding.constraint === void 0 || binding.constraint(constraintCtx));
-	return candidates;
+function selectAllBindings(bindings, hint, ctx) {
+	return filterBindings(bindings, hint, ctx, "all");
 }
-/**
-* Selects exactly one binding from the provided list, applying hint and constraint filtering.
-*
-* @throws {@link TokenNotBoundError} — `bindings` list is empty, or no candidate survives
-*   filtering without a name/tag hint.
-* @throws {@link NoMatchingBindingError} — a name/tag hint was provided but no candidate matched.
-* @throws {@link InternalError} — multiple candidates survive filtering (ambiguous binding).
-*/
-function selectBindingForRegistry(bindings, hint, tokenLabel, pathLabels, constraintCtx) {
-	if (bindings.length === 0) throw new TokenNotBoundError(tokenLabel, [...pathLabels]);
-	const candidates = filterMatchingBindings(bindings, hint, constraintCtx);
-	if (candidates.length === 1) {
-		const [only] = candidates;
-		if (only === void 0) throw new InternalError(`Internal: expected binding candidate for "${tokenLabel}" (resolution path: ${pathLabels.join(" -> ")})`);
-		return only;
+function filterBindings(bindings, hint, ctx, mode = "single") {
+	if (hint === void 0) {
+		const resultWithoutHint = [];
+		if (mode === "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 === void 0 && slot.tags.length === 0 && matchesPredicate(binding, ctx)) resultWithoutHint.push(binding);
+		}
+		return resultWithoutHint;
 	}
-	if (candidates.length === 0) {
-		if (hint !== void 0 && (hint.name !== void 0 || hint.tag !== void 0)) throw new NoMatchingBindingError(tokenLabel, hint, [...pathLabels]);
-		throw new TokenNotBoundError(tokenLabel, [...pathLabels]);
+	const result = [];
+	for (const binding of bindings) if ((mode === "all" ? matchesSlotForResolveAll(binding, hint) : matchesSlot(binding, hint)) && matchesPredicate(binding, ctx)) result.push(binding);
+	return result;
+}
+function matchesSlotForResolveAll(binding, hint) {
+	if (!(hint !== void 0 && (hint.name !== void 0 || hint.tags !== void 0 && hint.tags.length > 0 || hint.tag !== void 0))) return true;
+	return matchesSlot(binding, hint);
+}
+function matchesSlot(binding, hint) {
+	const slot = binding.slot;
+	const hintName = hint?.name;
+	const hintTags = hint?.tags;
+	const singleHintTag = hint?.tag;
+	const hasHintTags = (hintTags?.length ?? 0) > 0 || singleHintTag !== void 0;
+	if (slot.name !== void 0) {
+		if (hintName === void 0) return false;
+		if (slot.name !== hintName) return false;
+	} else if (hintName !== void 0) return false;
+	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) return false;
+	return true;
+}
+function matchHintTag(tagKey, tagValue, hintTags, singleHintTag) {
+	if (singleHintTag !== void 0 && singleHintTag[0] === tagKey && Object.is(singleHintTag[1], tagValue)) return true;
+	if (hintTags === void 0 || 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;
 	}
-	throw new InternalError(`Ambiguous binding for "${tokenLabel}": ${String(candidates.length)} candidates matched after applying ResolveHint (resolution path: ${pathLabels.join(" -> ")})`);
+	return false;
 }
-/**
-* Convenience wrapper: looks up bindings for `key` and selects the default (no-hint,
-* no-constraint) binding. Throws {@link TokenNotBoundError} if the key is unregistered.
-*/
-function selectDefaultBindingForKey(lookup, key, pathPrefix) {
-	const label = registryKeyLabel(key);
-	const nextPath = [...pathPrefix, label];
-	const bindings = lookup(key);
-	if (bindings === void 0 || bindings.length === 0) throw new TokenNotBoundError(label, nextPath);
-	return selectBindingForRegistry(bindings, void 0, label, nextPath, void 0);
+function matchesPredicate(binding, ctx) {
+	if (binding.predicate === void 0) return true;
+	return binding.predicate(ctx);
 }
 //#endregion
-export { filterMatchingBindings, registryKeyLabel, selectBindingForRegistry, selectDefaultBindingForKey };
+export { selectAllBindings, selectBinding };