@codefast/di 0.3.13-canary.4

package/dist/dependency-graph.mjs

@@ -0,0 +1,126 @@
+import { InternalError } from "./errors.mjs";
+import { registryKeyLabel, selectBindingForRegistry } from "./binding-select.mjs";
+//#region src/dependency-graph.ts
+/** Converts a tag value to a printable string for graph edge labels. */
+function formatTagValueForGraph(value) {
+	if (typeof value === "string") return value;
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return String(value);
+	}
+}
+/** Converts a {@link ResolveHint} to a human-readable edge label for graph output (`name: x` / `tag: k=v`). */
+function injectHintLabelFromResolveHint(hint) {
+	if (hint === void 0) return;
+	if (hint.name !== void 0) return `name: ${hint.name}`;
+	if (hint.tag !== void 0) {
+		const [tagKey, tagValue] = hint.tag;
+		return `tag: ${tagKey}=${formatTagValueForGraph(tagValue)}`;
+	}
+}
+/** Returns `"async"` when either the consumer or dependency binding is an `async-dynamic` factory. */
+function edgeKindFor(consumer, dependency) {
+	if (consumer.kind === "async-dynamic" || dependency.kind === "async-dynamic") return "async";
+	return "sync";
+}
+/**
+* Resolves the default (first matching, no hint) binding for `depKey`.
+* Returns `undefined` when the key has no registered bindings.
+*/
+function resolveDefaultBinding(lookup, depKey, pathPrefix) {
+	const label = registryKeyLabel(depKey);
+	const nextPath = [...pathPrefix, label];
+	const list = lookup(depKey);
+	if (list === void 0 || list.length === 0) return;
+	return selectBindingForRegistry(list, void 0, label, nextPath, void 0);
+}
+/**
+* Follows alias bindings until a non-alias binding is reached.
+* Returns the last reachable binding; stops if an alias target is unregistered.
+*/
+function expandAliasChain(lookup, start, pathPrefix) {
+	let current = start;
+	let path = pathPrefix;
+	while (current.kind === "alias") {
+		const next = resolveDefaultBinding(lookup, current.targetToken, path);
+		if (next === void 0) return current;
+		const label = registryKeyLabel(current.targetToken);
+		path = [...path, label];
+		current = next;
+	}
+	return current;
+}
+/**
+* Lists direct static dependencies (constructor metadata, `toResolved` tokens, alias targets).
+* Factories (`toDynamic` / `toAsyncDynamic`) have no enumerable dependency keys.
+*/
+function listResolvedDependencies(consumer, lookup, reader, pathPrefix) {
+	switch (consumer.kind) {
+		case "constant":
+		case "dynamic":
+		case "async-dynamic": return [];
+		case "alias": {
+			const binding = resolveDefaultBinding(lookup, consumer.targetToken, pathPrefix);
+			if (binding === void 0) return [];
+			const label = registryKeyLabel(consumer.targetToken);
+			const nextPath = [...pathPrefix, label];
+			return [{
+				binding: expandAliasChain(lookup, binding, nextPath),
+				path: nextPath,
+				injectHintLabel: void 0
+			}];
+		}
+		case "resolved": return consumer.dependencyTokens.map((tok) => {
+			const label = registryKeyLabel(tok);
+			const nextPath = [...pathPrefix, label];
+			const binding = resolveDefaultBinding(lookup, tok, pathPrefix);
+			if (binding === void 0) throw new InternalError(`Missing binding for dependency "${label}" while building dependency graph (resolution path: ${nextPath.join(" -> ")})`);
+			return {
+				binding: expandAliasChain(lookup, binding, nextPath),
+				path: nextPath,
+				injectHintLabel: void 0
+			};
+		});
+		case "class": {
+			if (reader === void 0) return [];
+			const meta = reader.getConstructorMetadata(consumer.implementationClass);
+			if (meta === void 0 || meta.params.length === 0) return [];
+			return meta.params.flatMap((param) => {
+				const tok = param.token;
+				const label = registryKeyLabel(tok);
+				const nextPath = [...pathPrefix, label];
+				const binding = resolveDefaultBinding(lookup, tok, pathPrefix);
+				if (binding === void 0) {
+					if (param.optional) return [];
+					throw new InternalError(`Missing binding for constructor parameter "${label}" while building dependency graph (resolution path: ${nextPath.join(" -> ")})`);
+				}
+				return [{
+					binding: expandAliasChain(lookup, binding, nextPath),
+					path: nextPath,
+					injectHintLabel: injectHintLabelFromResolveHint(param.name !== void 0 ? { name: param.name } : param.tag !== void 0 ? { tag: param.tag } : void 0)
+				}];
+			});
+		}
+		default: return consumer;
+	}
+}
+/**
+* Flattens the direct dependencies of `consumer` into typed graph edges.
+* Used by {@link ContainerInspector} to build DOT and JSON outputs.
+*/
+function collectStaticDependencyEdges(consumer, lookup, reader, pathPrefix) {
+	const deps = listResolvedDependencies(consumer, lookup, reader, pathPrefix);
+	const isAliasEdge = consumer.kind === "alias";
+	return deps.map((dep) => ({
+		fromBindingId: consumer.id,
+		toBindingId: dep.binding.id,
+		resolutionPath: dep.path,
+		edgeKind: edgeKindFor(consumer, dep.binding),
+		toBindingConditional: dep.binding.constraint !== void 0,
+		injectHintLabel: dep.injectHintLabel,
+		isAliasEdge
+	}));
+}
+//#endregion
+export { collectStaticDependencyEdges, injectHintLabelFromResolveHint, listResolvedDependencies };

package/dist/environment.d.mts

@@ -0,0 +1,14 @@
+//#region src/environment.d.ts
+/**
+ * Node-style production gate using `process.env.NODE_ENV`.
+ * When `process` is unavailable, this returns false (not treated as production).
+ */
+declare function isProductionEnvironment(): boolean;
+/**
+ * True when not in production: `development`, `test`, unset `NODE_ENV`, or any value other than `"production"`.
+ * The container uses this to run one-time static scope validation after load/resolve so graph issues surface
+ * during local work and CI tests (e.g. Vitest).
+ */
+declare function isDevelopmentOrTestEnvironment(): boolean;
+//#endregion
+export { isDevelopmentOrTestEnvironment, isProductionEnvironment };

package/dist/environment.mjs

@@ -0,0 +1,20 @@
+//#region src/environment.ts
+/**
+* Node-style production gate using `process.env.NODE_ENV`.
+* When `process` is unavailable, this returns false (not treated as production).
+*/
+function isProductionEnvironment() {
+	const processRef = globalThis.process;
+	if (processRef === void 0 || processRef === null) return false;
+	return processRef.env.NODE_ENV === "production";
+}
+/**
+* True when not in production: `development`, `test`, unset `NODE_ENV`, or any value other than `"production"`.
+* The container uses this to run one-time static scope validation after load/resolve so graph issues surface
+* during local work and CI tests (e.g. Vitest).
+*/
+function isDevelopmentOrTestEnvironment() {
+	return !isProductionEnvironment();
+}
+//#endregion
+export { isDevelopmentOrTestEnvironment, isProductionEnvironment };

package/dist/errors.d.mts

@@ -0,0 +1,100 @@
+import { Binding, BindingIdentifier, BindingScope, ResolveHint } from "./binding.mjs";
+
+//#region src/errors.d.ts
+/**
+ * Base error for all `@codefast/di` failures. Subclasses expose a stable, machine-readable `code`.
+ */
+declare abstract class DiError extends Error {
+  abstract readonly code: string;
+  constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Raised for internal programming errors — invalid library usage or unexpected state that
+ * indicates a bug in the caller (e.g. accessing an uninitialized container, misconfigured binding).
+ */
+declare class InternalError extends DiError {
+  readonly code = "INTERNAL_ERROR";
+}
+/**
+ * Raised when a name/tag filter matches no binding although other bindings exist for the token.
+ */
+declare class NoMatchingBindingError extends DiError {
+  readonly code = "NO_MATCHING_BINDING";
+  readonly tokenName: string;
+  readonly hint: ResolveHint;
+  readonly resolutionPath: readonly string[];
+  constructor(tokenName: string, hint: ResolveHint, resolutionPath: readonly string[], options?: ErrorOptions);
+}
+/**
+ * Raised when resolving a value for a token that has no binding.
+ */
+declare class TokenNotBoundError extends DiError {
+  readonly code = "TOKEN_NOT_BOUND";
+  readonly tokenName: string;
+  readonly resolutionPath: readonly string[];
+  constructor(tokenName: string, resolutionPath: readonly string[], options?: ErrorOptions);
+}
+/**
+ * Raised when the dependency graph contains a cycle during resolution.
+ */
+declare class CircularDependencyError extends DiError {
+  readonly code = "CIRCULAR_DEPENDENCY";
+  readonly resolutionPath: readonly string[];
+  readonly cycle: string[];
+  constructor(resolutionPath: readonly string[], options?: ErrorOptions);
+}
+/**
+ * Raised when a class binding requires `@injectable()` / `Symbol.metadata` constructor metadata but none is present.
+ */
+declare class MissingMetadataError extends DiError {
+  readonly code = "MISSING_METADATA";
+  readonly className: string;
+  readonly resolutionPath: readonly string[];
+  constructor(className: string, resolutionPath: readonly string[], options?: ErrorOptions);
+}
+/** Raised when `load()` is used with an async module. */
+declare class AsyncModuleLoadError extends DiError {
+  readonly code = "ASYNC_MODULE_LOAD";
+  readonly moduleName: string;
+  constructor(moduleName: string, options?: ErrorOptions);
+}
+/**
+ * Raised when `resolve()` is called on a binding chain that contains an async factory or
+ * an async `onActivation` handler. Use `resolveAsync()` / `resolveAllAsync()` instead.
+ */
+declare class AsyncResolutionError extends DiError {
+  readonly code = "ASYNC_RESOLUTION";
+  readonly tokenName: string;
+  readonly resolutionPath: readonly string[];
+  readonly reason: string;
+  constructor(tokenName: string, resolutionPath: readonly string[], reason: string, options?: ErrorOptions);
+}
+/** Structured payload attached to {@link ScopeViolationError}. */
+type ScopeViolationDetails = {
+  readonly consumerBindingId: BindingIdentifier;
+  readonly consumerKind: Binding<unknown>["kind"];
+  readonly consumerScope: BindingScope;
+  readonly consumerLabel?: string;
+  readonly dependencyBindingId: BindingIdentifier;
+  readonly dependencyKind: Binding<unknown>["kind"];
+  readonly dependencyScope: BindingScope;
+  readonly dependencyLabel?: string;
+  readonly resolutionPath: readonly string[];
+};
+/**
+ * Raised when a long-lived binding would capture a shorter-lived (scoped or transient) dependency
+ * (captive dependency). Constant value dependencies are excluded.
+ */
+declare class ScopeViolationError extends DiError {
+  readonly code = "SCOPE_VIOLATION";
+  readonly consumerBindingId: BindingIdentifier;
+  readonly consumerKind: Binding<unknown>["kind"];
+  readonly consumerScope: BindingScope;
+  readonly dependencyBindingId: BindingIdentifier;
+  readonly dependencyKind: Binding<unknown>["kind"];
+  readonly dependencyScope: BindingScope;
+  readonly resolutionPath: readonly string[];
+  constructor(details: ScopeViolationDetails, options?: ErrorOptions);
+}
+//#endregion
+export { AsyncModuleLoadError, AsyncResolutionError, CircularDependencyError, DiError, InternalError, MissingMetadataError, NoMatchingBindingError, ScopeViolationDetails, ScopeViolationError, TokenNotBoundError };

package/dist/errors.mjs

@@ -0,0 +1,152 @@
+//#region src/errors.ts
+/** Formats a resolution path array into a human-readable `"A -> B -> C"` string. */
+function formatResolutionPath(resolutionPath) {
+	return resolutionPath.length > 0 ? resolutionPath.join(" -> ") : "(empty)";
+}
+/** Serializes a {@link ResolveHint} to a debug string; never throws even for exotic values. */
+function safeSerializeHint(hint) {
+	if (hint === void 0) return "(none)";
+	try {
+		const parts = [];
+		if (hint.name !== void 0) parts.push(`name: ${String(hint.name)}`);
+		if (hint.tag !== void 0) {
+			const [tagKey, tagValue] = hint.tag;
+			parts.push(`tag: [${tagKey}, <${typeof tagValue}>]`);
+		}
+		return `{ ${parts.join(", ")} }`;
+	} catch {
+		return "(unserializable hint)";
+	}
+}
+/**
+* Base error for all `@codefast/di` failures. Subclasses expose a stable, machine-readable `code`.
+*/
+var DiError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = new.target.name;
+	}
+};
+/**
+* Raised for internal programming errors — invalid library usage or unexpected state that
+* indicates a bug in the caller (e.g. accessing an uninitialized container, misconfigured binding).
+*/
+var InternalError = class extends DiError {
+	code = "INTERNAL_ERROR";
+};
+/**
+* Raised when a name/tag filter matches no binding although other bindings exist for the token.
+*/
+var NoMatchingBindingError = class extends DiError {
+	code = "NO_MATCHING_BINDING";
+	tokenName;
+	hint;
+	resolutionPath;
+	constructor(tokenName, hint, resolutionPath, options) {
+		const pathText = resolutionPath.length > 0 ? resolutionPath.join(" -> ") : "(empty)";
+		const hintText = safeSerializeHint(hint);
+		super(`No binding matched resolve options ${hintText} for token "${tokenName}" (resolution path: ${pathText})`, options);
+		this.tokenName = tokenName;
+		this.hint = hint;
+		this.resolutionPath = resolutionPath;
+	}
+};
+/**
+* Raised when resolving a value for a token that has no binding.
+*/
+var TokenNotBoundError = class extends DiError {
+	code = "TOKEN_NOT_BOUND";
+	tokenName;
+	resolutionPath;
+	constructor(tokenName, resolutionPath, options) {
+		const pathText = formatResolutionPath(resolutionPath);
+		super(`Token not bound: ${tokenName} (resolution path: ${pathText})`, options);
+		this.tokenName = tokenName;
+		this.resolutionPath = resolutionPath;
+	}
+};
+/**
+* Raised when the dependency graph contains a cycle during resolution.
+*/
+var CircularDependencyError = class extends DiError {
+	code = "CIRCULAR_DEPENDENCY";
+	resolutionPath;
+	cycle;
+	constructor(resolutionPath, options) {
+		const pathText = formatResolutionPath(resolutionPath);
+		super(`Circular dependency detected: ${pathText}`, options);
+		this.resolutionPath = resolutionPath;
+		this.cycle = [...resolutionPath];
+	}
+};
+/**
+* Raised when a class binding requires `@injectable()` / `Symbol.metadata` constructor metadata but none is present.
+*/
+var MissingMetadataError = class extends DiError {
+	code = "MISSING_METADATA";
+	className;
+	resolutionPath;
+	constructor(className, resolutionPath, options) {
+		const pathText = formatResolutionPath(resolutionPath);
+		super(`Missing injectable constructor metadata for class "${className}" (resolution path: ${pathText})`, options);
+		this.className = className;
+		this.resolutionPath = resolutionPath;
+	}
+};
+/** Raised when `load()` is used with an async module. */
+var AsyncModuleLoadError = class extends DiError {
+	code = "ASYNC_MODULE_LOAD";
+	moduleName;
+	constructor(moduleName, options) {
+		super(`Cannot load async module "${moduleName}" synchronously; use loadAsync() or Container.fromModulesAsync().`, options);
+		this.moduleName = moduleName;
+	}
+};
+/**
+* Raised when `resolve()` is called on a binding chain that contains an async factory or
+* an async `onActivation` handler. Use `resolveAsync()` / `resolveAllAsync()` instead.
+*/
+var AsyncResolutionError = class extends DiError {
+	code = "ASYNC_RESOLUTION";
+	tokenName;
+	resolutionPath;
+	reason;
+	constructor(tokenName, resolutionPath, reason, options) {
+		const pathText = formatResolutionPath(resolutionPath);
+		super(`Cannot resolve "${tokenName}" synchronously: ${reason} (resolution path: ${pathText})`, options);
+		this.tokenName = tokenName;
+		this.resolutionPath = resolutionPath;
+		this.reason = reason;
+	}
+};
+/**
+* Raised when a long-lived binding would capture a shorter-lived (scoped or transient) dependency
+* (captive dependency). Constant value dependencies are excluded.
+*/
+var ScopeViolationError = class extends DiError {
+	code = "SCOPE_VIOLATION";
+	consumerBindingId;
+	consumerKind;
+	consumerScope;
+	dependencyBindingId;
+	dependencyKind;
+	dependencyScope;
+	resolutionPath;
+	constructor(details, options) {
+		const pathText = formatResolutionPath(details.resolutionPath);
+		const consumerLabel = details.consumerLabel ?? String(details.consumerBindingId);
+		const dependencyLabel = details.dependencyLabel ?? String(details.dependencyBindingId);
+		const consumerScopeLabel = details.consumerScope.charAt(0).toUpperCase() + details.consumerScope.slice(1);
+		const dependencyScopeLabel = details.dependencyScope.charAt(0).toUpperCase() + details.dependencyScope.slice(1);
+		super(`Scope Violation: ${consumerScopeLabel} "${consumerLabel}" cannot depend on ${dependencyScopeLabel} "${dependencyLabel}" (resolution path: ${pathText})`, options);
+		this.consumerBindingId = details.consumerBindingId;
+		this.consumerKind = details.consumerKind;
+		this.consumerScope = details.consumerScope;
+		this.dependencyBindingId = details.dependencyBindingId;
+		this.dependencyKind = details.dependencyKind;
+		this.dependencyScope = details.dependencyScope;
+		this.resolutionPath = details.resolutionPath;
+	}
+};
+//#endregion
+export { AsyncModuleLoadError, AsyncResolutionError, CircularDependencyError, DiError, InternalError, MissingMetadataError, NoMatchingBindingError, ScopeViolationError, TokenNotBoundError };

package/dist/index.d.mts

@@ -0,0 +1,10 @@
+import { Token, TokenValue, token } from "./token.mjs";
+import { ActivationHandler, BindingBuilder, BindingIdentifier, BindingScope, ConstraintContext, Constructor, DeactivationHandler, ResolveOptions } from "./binding.mjs";
+import { ContainerGraphJson, ContainerSnapshot } from "./inspector.mjs";
+import { AsyncModule, AsyncModuleBuilder, Module, ModuleBuilder } from "./module.mjs";
+import { Container } from "./container.mjs";
+import { InjectOptions, inject, isInjectionDescriptor, optional } from "./decorators/inject.mjs";
+import { InjectableDependency, getAutoRegistered, injectable } from "./decorators/injectable.mjs";
+import { postConstruct, preDestroy } from "./decorators/lifecycle-decorators.mjs";
+import { AsyncModuleLoadError, AsyncResolutionError, CircularDependencyError, DiError, InternalError, MissingMetadataError, NoMatchingBindingError, ScopeViolationDetails, ScopeViolationError, TokenNotBoundError } from "./errors.mjs";
+export { type ActivationHandler, AsyncModule, type AsyncModuleBuilder, AsyncModuleLoadError, AsyncResolutionError, type BindingBuilder, type BindingIdentifier, type BindingScope, CircularDependencyError, type ConstraintContext, type Constructor, Container, type ContainerGraphJson, type ContainerSnapshot, type DeactivationHandler, DiError, type InjectOptions, type InjectableDependency, InternalError, MissingMetadataError, Module, type ModuleBuilder, NoMatchingBindingError, type ResolveOptions, type ScopeViolationDetails, ScopeViolationError, type Token, TokenNotBoundError, type TokenValue, getAutoRegistered, inject, injectable, isInjectionDescriptor, optional, postConstruct, preDestroy, token };

package/dist/index.mjs

@@ -0,0 +1,8 @@
+import { AsyncModuleLoadError, AsyncResolutionError, CircularDependencyError, DiError, InternalError, MissingMetadataError, NoMatchingBindingError, ScopeViolationError, TokenNotBoundError } from "./errors.mjs";
+import { inject, isInjectionDescriptor, optional } from "./decorators/inject.mjs";
+import { getAutoRegistered, injectable } from "./decorators/injectable.mjs";
+import { AsyncModule, Module } from "./module.mjs";
+import { Container } from "./container.mjs";
+import { token } from "./token.mjs";
+import { postConstruct, preDestroy } from "./decorators/lifecycle-decorators.mjs";
+export { AsyncModule, AsyncModuleLoadError, AsyncResolutionError, CircularDependencyError, Container, DiError, InternalError, MissingMetadataError, Module, NoMatchingBindingError, ScopeViolationError, TokenNotBoundError, getAutoRegistered, inject, injectable, isInjectionDescriptor, optional, postConstruct, preDestroy, token };

package/dist/inspector.d.mts

@@ -0,0 +1,76 @@
+import { RegistryKey } from "./registry.mjs";
+import { Binding, BindingIdentifier, BindingScope } from "./binding.mjs";
+import { MetadataReader } from "./metadata/metadata-types.mjs";
+import { collectStaticDependencyEdges } from "./dependency-graph.mjs";
+
+//#region src/inspector.d.ts
+/** Whether a singleton/scoped binding's instance is currently held in the scope cache. */
+type BindingActivationStatus = "cached" | "not-cached" | "transient";
+/** Per-binding row inside a {@link ContainerSnapshot}. */
+type ContainerBindingSnapshot = {
+  readonly registryKeyLabel: string;
+  readonly bindingId: BindingIdentifier;
+  readonly kind: Binding<unknown>["kind"];
+  readonly scope: BindingScope;
+  readonly activationStatus: BindingActivationStatus; /** True when {@link BindingBuilder.when} was used (runtime predicate; static graph may still show edges). */
+  readonly hasConditionalConstraint: boolean;
+  readonly moduleId?: string;
+};
+/** Full debug snapshot returned by {@link Container.inspect}. */
+type ContainerSnapshot = {
+  readonly bindings: readonly ContainerBindingSnapshot[];
+};
+/** Structured dependency graph returned by {@link Container.generateDependencyGraph} with `format: "json"`. */
+type ContainerGraphJson = {
+  nodes: ContainerBindingSnapshot[];
+  edges: ReturnType<typeof collectStaticDependencyEdges>[number][];
+};
+/** Read-only view of the container internals exposed to {@link ContainerInspector}. */
+type ContainerInspectorContext = {
+  collectAllRegistryKeys(): readonly RegistryKey[];
+  lookupBindings(key: RegistryKey): readonly Binding<unknown>[] | undefined;
+  isBindingCached(binding: Binding<unknown>): boolean;
+  metadataReader: MetadataReader | undefined;
+};
+/** Options for {@link Container.generateDependencyGraph}. */
+type DotGraphOptions = {
+  /**
+   * When true, omit registry keys whose label starts with `CODEFAST_DI_` (framework-style tokens)
+   * and any edges that would only connect hidden nodes.
+   */
+  readonly hideInternals?: boolean;
+};
+/**
+ * Read-only introspection and Graphviz DOT export for a container graph.
+ */
+/**
+ * Reads the registry and scope-cache state to produce debug snapshots and dependency graphs.
+ * Instantiated internally by the container; advanced consumers can construct it directly via
+ * the `@codefast/di/inspector` subpath export.
+ */
+declare class ContainerInspector {
+  private readonly ctx;
+  constructor(ctx: ContainerInspectorContext);
+  /** Collects all registered bindings into a flat, serialisable snapshot. */
+  getSnapshot(): ContainerSnapshot;
+  /**
+   * Produces a Graphviz `digraph` string with HTML-label nodes and styled edges.
+   * Cycles are represented as ordinary edges (Graphviz renders them correctly).
+   * Pass `hideInternals: true` to suppress `CODEFAST_DI_`-prefixed tokens.
+   */
+  generateDotGraph(options?: DotGraphOptions): string;
+  generateDependencyGraph(options?: DotGraphOptions & {
+    format?: "dot";
+  }): string;
+  generateDependencyGraph(options: DotGraphOptions & {
+    format: "json";
+  }): ContainerGraphJson;
+  generateDependencyGraphJsonTyped(options?: DotGraphOptions): ContainerGraphJson;
+  /**
+   * Produces a JSON graph representation with `nodes` and `edges`.
+   * @internal Use `generateDependencyGraph({ format: "json" })` for typed output.
+   */
+  generateDependencyGraphJson(options?: DotGraphOptions): string;
+}
+//#endregion
+export { BindingActivationStatus, ContainerBindingSnapshot, ContainerGraphJson, ContainerInspector, ContainerInspectorContext, ContainerSnapshot, DotGraphOptions };