@codefast/di 0.3.13-canary.4

package/dist/inspector.mjs

@@ -0,0 +1,247 @@
+import { registryKeyLabel } from "./binding-select.mjs";
+import { collectStaticDependencyEdges } from "./dependency-graph.mjs";
+//#region src/inspector.ts
+/** Maps a binding's scope and cache state to a {@link BindingActivationStatus} label. */
+function activationStatusFor(binding, isCached) {
+	if (binding.scope === "transient") return "transient";
+	return isCached(binding) ? "cached" : "not-cached";
+}
+/** Escapes a string for use as a DOT `label="..."` attribute value. */
+function dotEscapeLabel(text) {
+	return text.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"").replaceAll("\n", "\\n");
+}
+/** Escapes a string for safe embedding inside a DOT HTML-label (`<...>`) table cell. */
+function dotEscapeHtml(text) {
+	return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;");
+}
+/** Returns the Graphviz node shape name for a given binding kind. */
+function nodeShapeForKind(kind) {
+	switch (kind) {
+		case "constant": return "ellipse";
+		case "class": return "box";
+		case "dynamic":
+		case "async-dynamic":
+		case "resolved": return "diamond";
+		case "alias": return "octagon";
+		default: return kind;
+	}
+}
+/** Returns DOT fill-color and style attributes that visually distinguish binding scopes. */
+function scopeVisualAttributes(scope) {
+	switch (scope) {
+		case "singleton": return "style=\"filled\", fillcolor=\"#FFD700\", penwidth=2";
+		case "scoped": return "style=\"filled\", fillcolor=\"#ADD8E6\"";
+		case "transient": return "style=\"dashed\"";
+		default: return scope;
+	}
+}
+/** Strips non-alphanumeric characters from a module name to produce a valid DOT subgraph identifier. */
+function sanitizeClusterId(moduleName) {
+	return moduleName.replace(/[^0-9a-zA-Z_]/g, "_");
+}
+/** Returns `true` when the label string belongs to a framework-internal registry key. */
+function registryKeyLabelIsInternal(label) {
+	return label.startsWith("CODEFAST_DI_");
+}
+/** Returns `true` when the registry key resolves to an internal framework label. */
+function isInternalRegistryKey(key) {
+	return registryKeyLabelIsInternal(registryKeyLabel(key));
+}
+/**
+* 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.
+*/
+var ContainerInspector = class {
+	constructor(ctx) {
+		this.ctx = ctx;
+	}
+	/** Collects all registered bindings into a flat, serialisable snapshot. */
+	getSnapshot() {
+		const bindings = [];
+		const seen = /* @__PURE__ */ new Set();
+		for (const registryKey of this.ctx.collectAllRegistryKeys()) {
+			const list = this.ctx.lookupBindings(registryKey);
+			if (list === void 0 || list.length === 0) continue;
+			const registryLabel = registryKeyLabel(registryKey);
+			for (const binding of list) {
+				if (seen.has(binding.id)) continue;
+				seen.add(binding.id);
+				const row = {
+					registryKeyLabel: registryLabel,
+					bindingId: binding.id,
+					kind: binding.kind,
+					scope: binding.scope,
+					activationStatus: activationStatusFor(binding, (bindingArg) => this.ctx.isBindingCached(bindingArg)),
+					hasConditionalConstraint: binding.constraint !== void 0
+				};
+				bindings.push(binding.moduleId === void 0 ? row : {
+					...row,
+					moduleId: binding.moduleId
+				});
+			}
+		}
+		return { bindings };
+	}
+	/**
+	* 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) {
+		const hideInternals = options?.hideInternals === true;
+		const fullSnapshot = this.getSnapshot();
+		const visibleRows = hideInternals ? fullSnapshot.bindings.filter((row) => !registryKeyLabelIsInternal(row.registryKeyLabel)) : fullSnapshot.bindings;
+		const allowedBindingIds = new Set(visibleRows.map((row) => row.bindingId));
+		const lines = [
+			"digraph codefast_di {",
+			"  rankdir=LR;",
+			"  graph [fontname=\"Arial\", fontsize=12, nodesep=0.8, ranksep=1.2];",
+			"  node  [fontname=\"Arial\", fontsize=12, shape=box, style=\"filled,rounded\", fillcolor=\"#F5F5F5\"];",
+			"  edge  [fontname=\"Arial\", fontsize=10];"
+		];
+		const byModule = /* @__PURE__ */ new Map();
+		for (const row of visibleRows) {
+			const key = row.moduleId;
+			const moduleGroup = byModule.get(key);
+			if (moduleGroup === void 0) byModule.set(key, [row]);
+			else moduleGroup.push(row);
+		}
+		const clusteredEntries = [...byModule.entries()].filter((entry) => entry[0] !== void 0);
+		const unclustered = byModule.get(void 0) ?? [];
+		const nodeAttributeLine = (row, indent) => {
+			const shape = nodeShapeForKind(row.kind);
+			const scopeAttrs = scopeVisualAttributes(row.scope);
+			const kindText = dotEscapeHtml(row.kind);
+			const nameText = dotEscapeHtml(row.registryKeyLabel);
+			const scopeText = dotEscapeHtml(`scope=${row.scope}`);
+			const whenRow = row.hasConditionalConstraint ? `      <TR><TD ALIGN="LEFT"><FONT POINT-SIZE="9" COLOR="#666666">when(...)</FONT></TD></TR>\n` : "";
+			const htmlLabel = [
+				"<",
+				"    <TABLE BORDER=\"0\" CELLPADDING=\"4\" CELLSPACING=\"0\">",
+				`      <TR><TD ALIGN="LEFT"><FONT POINT-SIZE="9" COLOR="#666666">${kindText}</FONT></TD></TR>`,
+				`      <TR><TD ALIGN="LEFT"><B>${nameText}</B></TD></TR>`,
+				`      <TR><TD ALIGN="LEFT"><FONT POINT-SIZE="9">${scopeText}</FONT></TD></TR>`,
+				whenRow.trimEnd(),
+				"    </TABLE>",
+				"  >"
+			].filter((line) => line.length > 0).join("\n");
+			return `${indent}"${row.bindingId}" [shape=${shape}, ${scopeAttrs}, label=${htmlLabel}];`;
+		};
+		for (const [moduleName, rows] of clusteredEntries) {
+			const clusterId = sanitizeClusterId(moduleName);
+			lines.push(`  subgraph cluster_${clusterId} {`);
+			lines.push(`    label="${dotEscapeLabel(moduleName)}";`);
+			lines.push(`    style=filled;`);
+			lines.push(`    fillcolor=lightgray;`);
+			for (const row of rows) lines.push(nodeAttributeLine(row, "    "));
+			lines.push(`  }`);
+		}
+		for (const row of unclustered) lines.push(nodeAttributeLine(row, "  "));
+		const emittedNodeIds = new Set(visibleRows.map((row) => row.bindingId));
+		const edgeSeen = /* @__PURE__ */ new Set();
+		for (const registryKey of this.ctx.collectAllRegistryKeys()) {
+			if (hideInternals && isInternalRegistryKey(registryKey)) continue;
+			const list = this.ctx.lookupBindings(registryKey);
+			if (list === void 0) continue;
+			const pathStart = [registryKeyLabel(registryKey)];
+			for (const consumerBinding of list) {
+				if (hideInternals && !allowedBindingIds.has(consumerBinding.id)) continue;
+				const edges = collectStaticDependencyEdges(consumerBinding, (dependencyKey) => this.ctx.lookupBindings(dependencyKey), this.ctx.metadataReader, pathStart);
+				for (const edge of edges) {
+					if (hideInternals && (!allowedBindingIds.has(edge.fromBindingId) || !allowedBindingIds.has(edge.toBindingId))) continue;
+					const edgeKey = `${edge.fromBindingId}->${edge.toBindingId}:${edge.edgeKind}:${edge.injectHintLabel ?? ""}`;
+					if (edgeSeen.has(edgeKey)) continue;
+					edgeSeen.add(edgeKey);
+					if (!emittedNodeIds.has(edge.fromBindingId)) {
+						emittedNodeIds.add(edge.fromBindingId);
+						lines.push(`  "${edge.fromBindingId}" [shape=box, style=dashed, label="(unlisted ${edge.fromBindingId})"];`);
+					}
+					if (!emittedNodeIds.has(edge.toBindingId)) {
+						emittedNodeIds.add(edge.toBindingId);
+						lines.push(`  "${edge.toBindingId}" [shape=box, style=dashed, label="(unlisted ${edge.toBindingId})"];`);
+					}
+					const labelParts = [];
+					if (edge.injectHintLabel !== void 0) labelParts.push(edge.injectHintLabel);
+					labelParts.push(edge.edgeKind);
+					if (edge.toBindingConditional) labelParts.push("conditional");
+					const edgeLabel = dotEscapeLabel(labelParts.join(" | "));
+					const pathLabel = dotEscapeLabel(edge.resolutionPath.join(" -> "));
+					const edgeStyle = edge.isAliasEdge ? ", style=dashed" : "";
+					lines.push(`  "${edge.fromBindingId}" -> "${edge.toBindingId}" [label="${edgeLabel}", xlabel="${pathLabel}"${edgeStyle}];`);
+				}
+			}
+		}
+		lines.push("}");
+		return lines.join("\n");
+	}
+	generateDependencyGraph(options) {
+		if (options?.format === "json") return this.generateDependencyGraphJsonTyped(options);
+		return this.generateDotGraph(options);
+	}
+	generateDependencyGraphJsonTyped(options) {
+		const hideInternals = options?.hideInternals === true;
+		const snapshot = this.getSnapshot();
+		const visibleNodes = hideInternals ? snapshot.bindings.filter((row) => !registryKeyLabelIsInternal(row.registryKeyLabel)) : [...snapshot.bindings];
+		const allowedBindingIds = new Set(visibleNodes.map((row) => row.bindingId));
+		const edges = [];
+		const edgeSeen = /* @__PURE__ */ new Set();
+		for (const registryKey of this.ctx.collectAllRegistryKeys()) {
+			if (hideInternals && isInternalRegistryKey(registryKey)) continue;
+			const list = this.ctx.lookupBindings(registryKey);
+			if (list === void 0) continue;
+			const pathStart = [registryKeyLabel(registryKey)];
+			for (const consumerBinding of list) {
+				if (hideInternals && !allowedBindingIds.has(consumerBinding.id)) continue;
+				for (const edge of collectStaticDependencyEdges(consumerBinding, (dependencyKey) => this.ctx.lookupBindings(dependencyKey), this.ctx.metadataReader, pathStart)) {
+					if (hideInternals && (!allowedBindingIds.has(edge.fromBindingId) || !allowedBindingIds.has(edge.toBindingId))) continue;
+					const edgeKey = `${edge.fromBindingId}->${edge.toBindingId}:${edge.edgeKind}:${edge.injectHintLabel ?? ""}`;
+					if (edgeSeen.has(edgeKey)) continue;
+					edgeSeen.add(edgeKey);
+					edges.push(edge);
+				}
+			}
+		}
+		return {
+			nodes: visibleNodes,
+			edges
+		};
+	}
+	/**
+	* Produces a JSON graph representation with `nodes` and `edges`.
+	* @internal Use `generateDependencyGraph({ format: "json" })` for typed output.
+	*/
+	generateDependencyGraphJson(options) {
+		const hideInternals = options?.hideInternals === true;
+		const snapshot = this.getSnapshot();
+		const visibleNodes = hideInternals ? snapshot.bindings.filter((row) => !registryKeyLabelIsInternal(row.registryKeyLabel)) : snapshot.bindings;
+		const allowedBindingIds = new Set(visibleNodes.map((row) => row.bindingId));
+		const edges = [];
+		const edgeSeen = /* @__PURE__ */ new Set();
+		for (const registryKey of this.ctx.collectAllRegistryKeys()) {
+			if (hideInternals && isInternalRegistryKey(registryKey)) continue;
+			const list = this.ctx.lookupBindings(registryKey);
+			if (list === void 0) continue;
+			const pathStart = [registryKeyLabel(registryKey)];
+			for (const consumerBinding of list) {
+				if (hideInternals && !allowedBindingIds.has(consumerBinding.id)) continue;
+				for (const edge of collectStaticDependencyEdges(consumerBinding, (dependencyKey) => this.ctx.lookupBindings(dependencyKey), this.ctx.metadataReader, pathStart)) {
+					if (hideInternals && (!allowedBindingIds.has(edge.fromBindingId) || !allowedBindingIds.has(edge.toBindingId))) continue;
+					const edgeKey = `${edge.fromBindingId}->${edge.toBindingId}:${edge.edgeKind}:${edge.injectHintLabel ?? ""}`;
+					if (edgeSeen.has(edgeKey)) continue;
+					edgeSeen.add(edgeKey);
+					edges.push(edge);
+				}
+			}
+		}
+		return JSON.stringify({
+			nodes: visibleNodes,
+			edges
+		});
+	}
+};
+//#endregion
+export { ContainerInspector };

package/dist/lifecycle.d.mts

@@ -0,0 +1,34 @@
+import { Binding, Constructor, ResolutionContext } from "./binding.mjs";
+import { LifecycleMetadata } from "./metadata/metadata-types.mjs";
+
+//#region src/lifecycle.d.ts
+/**
+ * Runs `onActivation` synchronously; rejects async activations on sync resolution paths.
+ */
+declare function runActivation(binding: Binding<unknown>, instance: unknown, ctx: ResolutionContext, pathLabels: readonly string[]): unknown;
+/**
+ * Reads lifecycle metadata directly from a constructor's Symbol.metadata.
+ */
+declare function readLifecycleMetadataFromCtor(implementationClass: Constructor<unknown>): LifecycleMetadata | undefined;
+/**
+ * Runs the `@postConstruct()` method synchronously if present. Throws if it returns a Promise.
+ */
+declare function runPostConstruct(implementationClass: Constructor<unknown>, instance: unknown, pathLabels?: string[]): void;
+/**
+ * Runs the `@postConstruct()` method, awaiting if it returns a Promise.
+ */
+declare function runPostConstructAsync(implementationClass: Constructor<unknown>, instance: unknown): Promise<void>;
+/**
+ * Runs the `@preDestroy()` method synchronously if present. Throws if it returns a Promise.
+ */
+declare function runPreDestroy(implementationClass: Constructor<unknown>, instance: unknown): void;
+/**
+ * Runs the `@preDestroy()` method, awaiting if it returns a Promise.
+ */
+declare function runPreDestroyAsync(implementationClass: Constructor<unknown>, instance: unknown): Promise<void>;
+/**
+ * Runs `onActivation`, awaiting promises returned by the handler.
+ */
+declare function runActivationAsync(binding: Binding<unknown>, instance: unknown, ctx: ResolutionContext, _pathLabels: readonly string[]): Promise<unknown>;
+//#endregion
+export { readLifecycleMetadataFromCtor, runActivation, runActivationAsync, runPostConstruct, runPostConstructAsync, runPreDestroy, runPreDestroyAsync };

package/dist/lifecycle.mjs

@@ -0,0 +1,83 @@
+import { AsyncResolutionError } from "./errors.mjs";
+import { CODEFAST_DI_LIFECYCLE_METADATA, decoratorMetadataObjectSymbol } from "./metadata/metadata-keys.mjs";
+//#region src/lifecycle.ts
+function isPromiseLike(value) {
+	return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
+}
+/**
+* Runs `onActivation` synchronously; rejects async activations on sync resolution paths.
+*/
+function runActivation(binding, instance, ctx, pathLabels) {
+	const handler = binding.onActivation;
+	if (handler === void 0) return instance;
+	const bindingLabel = pathLabels[pathLabels.length - 1] ?? "(unknown)";
+	const activationResult = handler(ctx, instance);
+	if (isPromiseLike(activationResult)) throw new AsyncResolutionError(bindingLabel, pathLabels, "onActivation returned a Promise during synchronous resolution");
+	return activationResult;
+}
+/**
+* Reads lifecycle metadata directly from a constructor's Symbol.metadata.
+*/
+function readLifecycleMetadataFromCtor(implementationClass) {
+	const metadataObject = implementationClass[decoratorMetadataObjectSymbol()];
+	if (typeof metadataObject !== "object" || metadataObject === null) return;
+	const raw = metadataObject[CODEFAST_DI_LIFECYCLE_METADATA];
+	return typeof raw === "object" && raw !== null ? raw : void 0;
+}
+/**
+* Runs the `@postConstruct()` method synchronously if present. Throws if it returns a Promise.
+*/
+function runPostConstruct(implementationClass, instance, pathLabels) {
+	const meta = readLifecycleMetadataFromCtor(implementationClass);
+	if (meta?.postConstruct === void 0) return;
+	const methodName = meta.postConstruct;
+	const lifecycleMethod = instance[methodName];
+	if (typeof lifecycleMethod !== "function") return;
+	const postConstructResult = lifecycleMethod.call(instance);
+	if (typeof postConstructResult === "object" && postConstructResult !== null && "then" in postConstructResult && typeof postConstructResult.then === "function") {
+		const labels = pathLabels ?? [];
+		throw new AsyncResolutionError(labels[labels.length - 1] ?? "(unknown)", labels, `@postConstruct() "${methodName}" returned a Promise during synchronous resolution`);
+	}
+}
+/**
+* Runs the `@postConstruct()` method, awaiting if it returns a Promise.
+*/
+async function runPostConstructAsync(implementationClass, instance) {
+	const meta = readLifecycleMetadataFromCtor(implementationClass);
+	if (meta?.postConstruct === void 0) return;
+	const lifecycleMethod = instance[meta.postConstruct];
+	if (typeof lifecycleMethod !== "function") return;
+	await lifecycleMethod.call(instance);
+}
+/**
+* Runs the `@preDestroy()` method synchronously if present. Throws if it returns a Promise.
+*/
+function runPreDestroy(implementationClass, instance) {
+	const meta = readLifecycleMetadataFromCtor(implementationClass);
+	if (meta?.preDestroy === void 0) return;
+	const methodName = meta.preDestroy;
+	const lifecycleMethod = instance[methodName];
+	if (typeof lifecycleMethod !== "function") return;
+	const preDestroyResult = lifecycleMethod.call(instance);
+	if (typeof preDestroyResult === "object" && preDestroyResult !== null && "then" in preDestroyResult && typeof preDestroyResult.then === "function") throw new Error(`@preDestroy() "${methodName}" returned a Promise during synchronous disposal; use disposeAsync() / unloadAsync().`);
+}
+/**
+* Runs the `@preDestroy()` method, awaiting if it returns a Promise.
+*/
+async function runPreDestroyAsync(implementationClass, instance) {
+	const meta = readLifecycleMetadataFromCtor(implementationClass);
+	if (meta?.preDestroy === void 0) return;
+	const lifecycleMethod = instance[meta.preDestroy];
+	if (typeof lifecycleMethod !== "function") return;
+	await lifecycleMethod.call(instance);
+}
+/**
+* Runs `onActivation`, awaiting promises returned by the handler.
+*/
+async function runActivationAsync(binding, instance, ctx, _pathLabels) {
+	const handler = binding.onActivation;
+	if (handler === void 0) return instance;
+	return await handler(ctx, instance);
+}
+//#endregion
+export { readLifecycleMetadataFromCtor, runActivation, runActivationAsync, runPostConstruct, runPostConstructAsync, runPreDestroy, runPreDestroyAsync };

package/dist/metadata/metadata-keys.d.mts

@@ -0,0 +1,17 @@
+//#region src/metadata/metadata-keys.d.ts
+/**
+ * Well-known key for Codefast DI constructor metadata on `Symbol.metadata`.
+ */
+declare const CODEFAST_DI_CONSTRUCTOR_METADATA = "codefast/di:constructor-metadata:v1";
+/** Well-known key for accessor field injection metadata written by `@inject` on `accessor` fields. */
+declare const CODEFAST_DI_ACCESSOR_INJECTIONS = "codefast/di:accessor-injections:v1";
+/** Well-known key for lifecycle method names written by `@postConstruct()` / `@preDestroy()`. */
+declare const CODEFAST_DI_LIFECYCLE_METADATA = "codefast/di:lifecycle-metadata:v1";
+/**
+ * Runtime symbol for the decorator metadata object (TC39 `Symbol.metadata`).
+ * Node may expose this only via `Symbol.for("Symbol.metadata")` until the global
+ * `Symbol.metadata` property is available.
+ */
+declare function decoratorMetadataObjectSymbol(): symbol;
+//#endregion
+export { CODEFAST_DI_ACCESSOR_INJECTIONS, CODEFAST_DI_CONSTRUCTOR_METADATA, CODEFAST_DI_LIFECYCLE_METADATA, decoratorMetadataObjectSymbol };

package/dist/metadata/metadata-keys.mjs

@@ -0,0 +1,19 @@
+//#region src/metadata/metadata-keys.ts
+/**
+* Well-known key for Codefast DI constructor metadata on `Symbol.metadata`.
+*/
+const CODEFAST_DI_CONSTRUCTOR_METADATA = "codefast/di:constructor-metadata:v1";
+/** Well-known key for accessor field injection metadata written by `@inject` on `accessor` fields. */
+const CODEFAST_DI_ACCESSOR_INJECTIONS = "codefast/di:accessor-injections:v1";
+/** Well-known key for lifecycle method names written by `@postConstruct()` / `@preDestroy()`. */
+const CODEFAST_DI_LIFECYCLE_METADATA = "codefast/di:lifecycle-metadata:v1";
+/**
+* Runtime symbol for the decorator metadata object (TC39 `Symbol.metadata`).
+* Node may expose this only via `Symbol.for("Symbol.metadata")` until the global
+* `Symbol.metadata` property is available.
+*/
+function decoratorMetadataObjectSymbol() {
+	return typeof Symbol.metadata === "symbol" ? Symbol.metadata : Symbol.for("Symbol.metadata");
+}
+//#endregion
+export { CODEFAST_DI_ACCESSOR_INJECTIONS, CODEFAST_DI_CONSTRUCTOR_METADATA, CODEFAST_DI_LIFECYCLE_METADATA, decoratorMetadataObjectSymbol };

package/dist/metadata/metadata-types.d.mts

@@ -0,0 +1,55 @@
+import { Token } from "../token.mjs";
+import { Constructor } from "../binding.mjs";
+
+//#region src/metadata/metadata-types.d.ts
+/** Metadata written per `accessor` field decorated with `@inject`; collected into `Symbol.metadata`. */
+type AccessorInjectionMetadata = {
+  readonly name: string;
+  readonly token: Token<unknown> | Constructor<unknown>;
+  readonly optional: boolean;
+  readonly resolveHint?: {
+    readonly name?: string;
+    readonly tag?: readonly [tag: string, value: unknown];
+  };
+};
+/** Lifecycle method names written by `@postConstruct()` / `@preDestroy()` into `Symbol.metadata`. */
+type LifecycleMetadata = {
+  readonly postConstruct?: string;
+  readonly preDestroy?: string;
+  readonly accessorInjections?: readonly AccessorInjectionMetadata[];
+};
+/**
+ * Per-parameter injection description collected by `@injectable()`.
+ */
+type ParamMetadata = {
+  readonly index: number;
+  readonly token: Token<unknown> | Constructor<unknown>;
+  readonly optional: boolean;
+  readonly name?: string;
+  readonly tag?: readonly [tag: string, value: unknown];
+};
+/**
+ * Resolved form of an `inject()` / `optional()` call: token + optional flag + optional resolve hint.
+ * Used both as a deps-array entry in `@injectable()` and as accessor-field injection metadata.
+ */
+type InjectionDescriptor<Value = unknown> = {
+  readonly token: Token<Value> | Constructor<Value>;
+  readonly optional: boolean;
+  readonly name?: string;
+  readonly tag?: readonly [tag: string, value: unknown];
+};
+/**
+ * Constructor injection shape stored on the class `Symbol.metadata` object.
+ */
+type ConstructorMetadata = {
+  readonly params: readonly ParamMetadata[];
+};
+/**
+ * Abstraction for reading DI metadata (section 6.4) without tying callers to `Symbol.metadata`.
+ */
+type MetadataReader = {
+  getConstructorMetadata(implementationClass: Constructor<unknown>): ConstructorMetadata | undefined;
+  getLifecycleMetadata?(implementationClass: Constructor<unknown>): LifecycleMetadata | undefined;
+};
+//#endregion
+export { AccessorInjectionMetadata, ConstructorMetadata, InjectionDescriptor, LifecycleMetadata, MetadataReader, ParamMetadata };

package/dist/metadata/metadata-types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/metadata/param-registry.d.mts

@@ -0,0 +1,16 @@
+import { Constructor } from "../binding.mjs";
+import { ParamMetadata } from "./metadata-types.mjs";
+
+//#region src/metadata/param-registry.d.ts
+/**
+ * Returns the pending `ParamMetadata` map for `implementationClass`, creating it on first access.
+ * Used by legacy parameter decorators that fire before the class decorator runs.
+ */
+declare function getOrCreatePendingMap(implementationClass: Constructor<unknown>): Map<number, ParamMetadata>;
+/**
+ * Removes and returns the pending map for `implementationClass` (transfer of ownership).
+ * Returns `undefined` if no pending entries exist.
+ */
+declare function takePendingMap(implementationClass: Constructor<unknown>): Map<number, ParamMetadata> | undefined;
+//#endregion
+export { getOrCreatePendingMap, takePendingMap };

package/dist/metadata/param-registry.mjs

@@ -0,0 +1,25 @@
+//#region src/metadata/param-registry.ts
+const pendingByConstructor = /* @__PURE__ */ new WeakMap();
+/**
+* Returns the pending `ParamMetadata` map for `implementationClass`, creating it on first access.
+* Used by legacy parameter decorators that fire before the class decorator runs.
+*/
+function getOrCreatePendingMap(implementationClass) {
+	let map = pendingByConstructor.get(implementationClass);
+	if (!map) {
+		map = /* @__PURE__ */ new Map();
+		pendingByConstructor.set(implementationClass, map);
+	}
+	return map;
+}
+/**
+* Removes and returns the pending map for `implementationClass` (transfer of ownership).
+* Returns `undefined` if no pending entries exist.
+*/
+function takePendingMap(implementationClass) {
+	const map = pendingByConstructor.get(implementationClass);
+	if (map) pendingByConstructor.delete(implementationClass);
+	return map;
+}
+//#endregion
+export { getOrCreatePendingMap, takePendingMap };

package/dist/metadata/symbol-metadata-reader.d.mts

@@ -0,0 +1,15 @@
+import { Constructor } from "../binding.mjs";
+import { ConstructorMetadata, LifecycleMetadata, MetadataReader } from "./metadata-types.mjs";
+
+//#region src/metadata/symbol-metadata-reader.d.ts
+/**
+ * Reads {@link ConstructorMetadata} from the standard `Symbol.metadata` object.
+ */
+declare class SymbolMetadataReader implements MetadataReader {
+  /** Reads constructor param metadata written by `@injectable()`. Returns `undefined` if none present. */
+  getConstructorMetadata(implementationClass: Constructor<unknown>): ConstructorMetadata | undefined;
+  /** Reads lifecycle method names written by `@postConstruct()` / `@preDestroy()`. Inherits from parent classes. */
+  getLifecycleMetadata(implementationClass: Constructor<unknown>): LifecycleMetadata | undefined;
+}
+//#endregion
+export { SymbolMetadataReader };

package/dist/metadata/symbol-metadata-reader.mjs

@@ -0,0 +1,32 @@
+import { CODEFAST_DI_CONSTRUCTOR_METADATA, CODEFAST_DI_LIFECYCLE_METADATA, decoratorMetadataObjectSymbol } from "./metadata-keys.mjs";
+//#region src/metadata/symbol-metadata-reader.ts
+/** Type guard — returns `true` when `value` has the shape of a {@link ConstructorMetadata} object. */
+function isConstructorMetadata(value) {
+	if (typeof value !== "object" || value === null || !("params" in value)) return false;
+	return Array.isArray(value.params);
+}
+/**
+* Reads {@link ConstructorMetadata} from the standard `Symbol.metadata` object.
+*/
+var SymbolMetadataReader = class {
+	/** Reads constructor param metadata written by `@injectable()`. Returns `undefined` if none present. */
+	getConstructorMetadata(implementationClass) {
+		const rawMetadata = implementationClass[decoratorMetadataObjectSymbol()];
+		if (typeof rawMetadata !== "object" || rawMetadata === null) return;
+		const metadataObject = rawMetadata;
+		if (!Object.hasOwn(metadataObject, "codefast/di:constructor-metadata:v1")) return;
+		const raw = metadataObject[CODEFAST_DI_CONSTRUCTOR_METADATA];
+		if (!isConstructorMetadata(raw)) return;
+		return raw;
+	}
+	/** Reads lifecycle method names written by `@postConstruct()` / `@preDestroy()`. Inherits from parent classes. */
+	getLifecycleMetadata(implementationClass) {
+		const metadataObject = implementationClass[decoratorMetadataObjectSymbol()];
+		if (typeof metadataObject !== "object" || metadataObject === null) return;
+		const raw = metadataObject[CODEFAST_DI_LIFECYCLE_METADATA];
+		if (typeof raw !== "object" || raw === null) return;
+		return raw;
+	}
+};
+//#endregion
+export { SymbolMetadataReader };

package/dist/module.d.mts

@@ -0,0 +1,60 @@
+import { Token } from "./token.mjs";
+import { BindingBuilder, Constructor } from "./binding.mjs";
+
+//#region src/module.d.ts
+/**
+ * Builder passed to synchronous module setup: register bindings and import other sync modules.
+ */
+type ModuleBuilder = {
+  readonly import: (...modules: Module[]) => void;
+  readonly bind: <Value>(key: Token<Value> | Constructor<Value>) => BindingBuilder<Value>;
+};
+/**
+ * Builder passed to async module setup.
+ */
+type AsyncModuleBuilder = {
+  readonly import: (...modules: (Module | AsyncModule)[]) => void;
+  readonly bind: <Value>(key: Token<Value> | Constructor<Value>) => BindingBuilder<Value>;
+};
+/**
+ * Immutable description of a bundle of bindings. A {@link Module} holds no runtime state and the
+ * same instance may be loaded into any number of containers independently (spec §7.3).
+ *
+ * The owning container is responsible for tracking which modules have been loaded and which
+ * binding ids each module produced; the module itself never sees a container reference.
+ */
+declare class Module {
+  readonly name: string;
+  private readonly syncSetup;
+  private constructor();
+  /**
+   * Defines a synchronous module.
+   * @param name - Human-readable label used in error messages and debug output.
+   * @param setup - Callback that registers bindings via the {@link ModuleBuilder}.
+   */
+  static create(name: string, setup: (builder: ModuleBuilder) => void): Module;
+  /**
+   * Defines an async module — use when setup requires awaiting (e.g. reading config, dynamic imports).
+   * Load with {@link Container.loadAsync} or {@link Container.fromModulesAsync}.
+   */
+  static createAsync(name: string, setup: (builder: AsyncModuleBuilder) => Promise<void>): AsyncModule;
+  /**
+   * @internal Invoked by the container while loading this module.
+   */
+  runSyncSetup(builder: ModuleBuilder): void;
+}
+/**
+ * An async module whose setup callback may `await` before registering bindings.
+ * Prefer {@link Module.createAsync} over constructing this class directly.
+ */
+declare class AsyncModule {
+  readonly name: string;
+  private readonly asyncSetup;
+  constructor(name: string, asyncSetup: (builder: AsyncModuleBuilder) => Promise<void>);
+  /**
+   * @internal Invoked by the container while loading this module.
+   */
+  runAsyncSetup(builder: AsyncModuleBuilder): Promise<void>;
+}
+//#endregion
+export { AsyncModule, AsyncModuleBuilder, Module, ModuleBuilder };