@codefast/di 0.3.13 → 0.3.14-canary.1

package/dist/inspector.d.mts

@@ -4,36 +4,51 @@ 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. */
+/**
+ * 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}. */
+/**
+ * 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). */
+  /** Human-readable token/constructor label that owns this binding row. */readonly registryKeyLabel: string; /** Stable binding identifier. */
+  readonly bindingId: BindingIdentifier; /** Binding strategy kind. */
+  readonly kind: Binding<unknown>["kind"]; /** Declared binding scope. */
+  readonly scope: BindingScope; /** Cache/materialization status at snapshot time. */
+  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}. */
+/**
+ * Full debug snapshot returned by {@link Container.inspect}.
+ */
 type ContainerSnapshot = {
-  readonly bindings: readonly ContainerBindingSnapshot[];
+  /** Flat list of every visible binding row in the container hierarchy. */readonly bindings: readonly ContainerBindingSnapshot[];
 };
-/** Structured dependency graph returned by {@link Container.generateDependencyGraph} with `format: "json"`. */
+/**
+ * Canonical structured dependency graph returned by {@link Container.generateDependencyGraph}.
+ */
 type ContainerGraphJson = {
-  nodes: ContainerBindingSnapshot[];
+  /** Graph nodes (same shape as snapshot rows). */nodes: ContainerBindingSnapshot[]; /** Directed dependency edges between node binding ids. */
   edges: ReturnType<typeof collectStaticDependencyEdges>[number][];
 };
-/** Read-only view of the container internals exposed to {@link ContainerInspector}. */
+/**
+ * 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;
+  /** Enumerates every registry key visible to the inspector. */collectAllRegistryKeys(): readonly RegistryKey[]; /** Returns bindings for a given key, including hierarchy lookup behavior. */
+  lookupBindings(key: RegistryKey): readonly Binding<unknown>[] | undefined; /** Reports whether a binding currently has a cached scoped/singleton instance. */
+  isBindingCached(binding: Binding<unknown>): boolean; /** Metadata reader used for static constructor/lifecycle analysis. */
   metadataReader: MetadataReader | undefined;
 };
-/** Options for {@link Container.generateDependencyGraph}. */
-type DotGraphOptions = {
+/**
+ * Options for {@link Container.generateDependencyGraph}.
+ */
+type GraphOptions = {
   /**
    * When true, omit registry keys whose label starts with `CODEFAST_DI_` (framework-style tokens)
    * and any edges that would only connect hidden nodes.
@@ -41,36 +56,23 @@ type DotGraphOptions = {
   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.
+ * Reads the container's registry and scope-cache state to produce debug snapshots
+ * and canonical dependency-graph output (`nodes` + `edges`).
+ *
+ * Constructed internally by the container; advanced consumers can also 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.
+   * Collects all registered bindings into a flat, serialisable snapshot.
    */
-  generateDotGraph(options?: DotGraphOptions): string;
-  generateDependencyGraph(options?: DotGraphOptions & {
-    format?: "dot";
-  }): string;
-  generateDependencyGraph(options: DotGraphOptions & {
-    format: "json";
-  }): ContainerGraphJson;
-  generateDependencyGraphJsonTyped(options?: DotGraphOptions): ContainerGraphJson;
+  getSnapshot(): ContainerSnapshot;
   /**
-   * Produces a JSON graph representation with `nodes` and `edges`.
-   * @internal Use `generateDependencyGraph({ format: "json" })` for typed output.
+   * Builds the canonical JSON graph (`nodes` + `edges`).
    */
-  generateDependencyGraphJson(options?: DotGraphOptions): string;
+  generateDependencyGraph(options?: GraphOptions): ContainerGraphJson;
 }
 //#endregion
-export { BindingActivationStatus, ContainerBindingSnapshot, ContainerGraphJson, ContainerInspector, ContainerInspectorContext, ContainerSnapshot, DotGraphOptions };
+export { BindingActivationStatus, ContainerBindingSnapshot, ContainerGraphJson, ContainerInspector, ContainerInspectorContext, ContainerSnapshot, GraphOptions };

package/dist/inspector.mjs

@@ -1,65 +1,39 @@
 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. */
+/**
+* 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. */
+/**
+* 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. */
+/**
+* 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.
+* Reads the container's registry and scope-cache state to produce debug snapshots
+* and canonical dependency-graph output (`nodes` + `edges`).
+*
+* Constructed internally by the container; advanced consumers can also 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. */
+	/**
+	* Collects all registered bindings into a flat, serialisable snapshot.
+	*/
 	getSnapshot() {
 		const bindings = [];
 		const seen = /* @__PURE__ */ new Set();
@@ -87,102 +61,9 @@ var ContainerInspector = class {
 		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.
+	* Builds the canonical JSON graph (`nodes` + `edges`).
 	*/
-	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];
@@ -210,38 +91,6 @@ var ContainerInspector = class {
 			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

@@ -3,15 +3,30 @@ import { LifecycleMetadata } from "./metadata/metadata-types.mjs";
 
 //#region src/lifecycle.d.ts
 /**
- * Runs `onActivation` synchronously; rejects async activations on sync resolution paths.
+ * Duck-typed Promise check: returns `true` when `value` has a `then` method.
+ * Used throughout the lifecycle layer to guard against async return values on sync resolution paths.
+ */
+declare function isPromiseLike(value: unknown): value is Promise<unknown>;
+/**
+ * Runs `onActivation` synchronously on a newly constructed instance.
+ * If the handler returns a Promise during synchronous resolution, throws
+ * {@link AsyncResolutionError} — callers must use `resolveAsync` for async activation handlers.
+ *
+ * Lifecycle ordering: `construct` → `@postConstruct` → **`onActivation`** → cache.
  */
 declare function runActivation(binding: Binding<unknown>, instance: unknown, ctx: ResolutionContext, pathLabels: readonly string[]): unknown;
 /**
- * Reads lifecycle metadata directly from a constructor's Symbol.metadata.
+ * Reads lifecycle metadata ({@link LifecycleMetadata}) directly from a constructor's
+ * `Symbol.metadata` object. Bypasses the {@link MetadataReader} abstraction —
+ * used by the scope manager during deactivation when the reader is not available.
  */
 declare function readLifecycleMetadataFromCtor(implementationClass: Constructor<unknown>): LifecycleMetadata | undefined;
 /**
- * Runs the `@postConstruct()` method synchronously if present. Throws if it returns a Promise.
+ * Runs the `@postConstruct()` method synchronously if present.
+ * Throws {@link AsyncResolutionError} if the method returns a Promise — async lifecycle
+ * methods require `resolveAsync`.
+ *
+ * Lifecycle ordering: `construct` → **`@postConstruct`** → `onActivation` → cache.
  */
 declare function runPostConstruct(implementationClass: Constructor<unknown>, instance: unknown, pathLabels?: string[]): void;
 /**
@@ -19,16 +34,23 @@ declare function runPostConstruct(implementationClass: Constructor<unknown>, ins
  */
 declare function runPostConstructAsync(implementationClass: Constructor<unknown>, instance: unknown): Promise<void>;
 /**
- * Runs the `@preDestroy()` method synchronously if present. Throws if it returns a Promise.
+ * Runs the `@preDestroy()` method synchronously if present.
+ * Throws if the method returns a Promise — use `disposeAsync()` / `unloadAsync()` for async teardown.
+ *
+ * Lifecycle ordering: `onDeactivation` → **`@preDestroy`**.
  */
 declare function runPreDestroy(implementationClass: Constructor<unknown>, instance: unknown): void;
 /**
  * Runs the `@preDestroy()` method, awaiting if it returns a Promise.
+ *
+ * Lifecycle ordering: `onDeactivation` → **`@preDestroy`** (async variant).
  */
 declare function runPreDestroyAsync(implementationClass: Constructor<unknown>, instance: unknown): Promise<void>;
 /**
- * Runs `onActivation`, awaiting promises returned by the handler.
+ * Runs `onActivation`, awaiting if the handler returns a Promise.
+ *
+ * Lifecycle ordering: `construct` → `@postConstruct` → **`onActivation`** (async variant) → cache.
  */
 declare function runActivationAsync(binding: Binding<unknown>, instance: unknown, ctx: ResolutionContext, _pathLabels: readonly string[]): Promise<unknown>;
 //#endregion
-export { readLifecycleMetadataFromCtor, runActivation, runActivationAsync, runPostConstruct, runPostConstructAsync, runPreDestroy, runPreDestroyAsync };
+export { isPromiseLike, readLifecycleMetadataFromCtor, runActivation, runActivationAsync, runPostConstruct, runPostConstructAsync, runPreDestroy, runPreDestroyAsync };

package/dist/lifecycle.mjs

@@ -1,11 +1,19 @@
 import { AsyncResolutionError } from "./errors.mjs";
 import { CODEFAST_DI_LIFECYCLE_METADATA, decoratorMetadataObjectSymbol } from "./metadata/metadata-keys.mjs";
 //#region src/lifecycle.ts
+/**
+* Duck-typed Promise check: returns `true` when `value` has a `then` method.
+* Used throughout the lifecycle layer to guard against async return values on sync resolution paths.
+*/
 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.
+* Runs `onActivation` synchronously on a newly constructed instance.
+* If the handler returns a Promise during synchronous resolution, throws
+* {@link AsyncResolutionError} — callers must use `resolveAsync` for async activation handlers.
+*
+* Lifecycle ordering: `construct` → `@postConstruct` → **`onActivation`** → cache.
 */
 function runActivation(binding, instance, ctx, pathLabels) {
 	const handler = binding.onActivation;
@@ -16,7 +24,9 @@ function runActivation(binding, instance, ctx, pathLabels) {
 	return activationResult;
 }
 /**
-* Reads lifecycle metadata directly from a constructor's Symbol.metadata.
+* Reads lifecycle metadata ({@link LifecycleMetadata}) directly from a constructor's
+* `Symbol.metadata` object. Bypasses the {@link MetadataReader} abstraction —
+* used by the scope manager during deactivation when the reader is not available.
 */
 function readLifecycleMetadataFromCtor(implementationClass) {
 	const metadataObject = implementationClass[decoratorMetadataObjectSymbol()];
@@ -25,7 +35,11 @@ function readLifecycleMetadataFromCtor(implementationClass) {
 	return typeof raw === "object" && raw !== null ? raw : void 0;
 }
 /**
-* Runs the `@postConstruct()` method synchronously if present. Throws if it returns a Promise.
+* Runs the `@postConstruct()` method synchronously if present.
+* Throws {@link AsyncResolutionError} if the method returns a Promise — async lifecycle
+* methods require `resolveAsync`.
+*
+* Lifecycle ordering: `construct` → **`@postConstruct`** → `onActivation` → cache.
 */
 function runPostConstruct(implementationClass, instance, pathLabels) {
 	const meta = readLifecycleMetadataFromCtor(implementationClass);
@@ -33,8 +47,7 @@ function runPostConstruct(implementationClass, instance, pathLabels) {
 	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") {
+	if (isPromiseLike(lifecycleMethod.call(instance))) {
 		const labels = pathLabels ?? [];
 		throw new AsyncResolutionError(labels[labels.length - 1] ?? "(unknown)", labels, `@postConstruct() "${methodName}" returned a Promise during synchronous resolution`);
 	}
@@ -50,7 +63,10 @@ async function runPostConstructAsync(implementationClass, instance) {
 	await lifecycleMethod.call(instance);
 }
 /**
-* Runs the `@preDestroy()` method synchronously if present. Throws if it returns a Promise.
+* Runs the `@preDestroy()` method synchronously if present.
+* Throws if the method returns a Promise — use `disposeAsync()` / `unloadAsync()` for async teardown.
+*
+* Lifecycle ordering: `onDeactivation` → **`@preDestroy`**.
 */
 function runPreDestroy(implementationClass, instance) {
 	const meta = readLifecycleMetadataFromCtor(implementationClass);
@@ -58,11 +74,12 @@ function runPreDestroy(implementationClass, instance) {
 	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().`);
+	if (isPromiseLike(lifecycleMethod.call(instance))) throw new Error(`@preDestroy() "${methodName}" returned a Promise during synchronous disposal; use disposeAsync() / unloadAsync().`);
 }
 /**
 * Runs the `@preDestroy()` method, awaiting if it returns a Promise.
+*
+* Lifecycle ordering: `onDeactivation` → **`@preDestroy`** (async variant).
 */
 async function runPreDestroyAsync(implementationClass, instance) {
 	const meta = readLifecycleMetadataFromCtor(implementationClass);
@@ -72,7 +89,9 @@ async function runPreDestroyAsync(implementationClass, instance) {
 	await lifecycleMethod.call(instance);
 }
 /**
-* Runs `onActivation`, awaiting promises returned by the handler.
+* Runs `onActivation`, awaiting if the handler returns a Promise.
+*
+* Lifecycle ordering: `construct` → `@postConstruct` → **`onActivation`** (async variant) → cache.
 */
 async function runActivationAsync(binding, instance, ctx, _pathLabels) {
 	const handler = binding.onActivation;
@@ -80,4 +99,4 @@ async function runActivationAsync(binding, instance, ctx, _pathLabels) {
 	return await handler(ctx, instance);
 }
 //#endregion
-export { readLifecycleMetadataFromCtor, runActivation, runActivationAsync, runPostConstruct, runPostConstructAsync, runPreDestroy, runPreDestroyAsync };
+export { isPromiseLike, readLifecycleMetadataFromCtor, runActivation, runActivationAsync, runPostConstruct, runPostConstructAsync, runPreDestroy, runPreDestroyAsync };

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

@@ -1,16 +1,27 @@
 //#region src/metadata/metadata-keys.d.ts
 /**
- * Well-known key for Codefast DI constructor metadata on `Symbol.metadata`.
+ * Well-known property key for constructor injection metadata on `Symbol.metadata`.
+ * Written by `@injectable()`, read by `SymbolMetadataReader.getConstructorMetadata()`.
+ * The `:v1` suffix is a schema version — bump only when the `ConstructorMetadata` shape changes.
  */
 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. */
+/**
+ * Well-known property key for accessor-field injection metadata on `Symbol.metadata`.
+ * Written by `@inject()` when used as an accessor decorator; read during post-construction
+ * property injection by the resolver.
+ */
 declare const CODEFAST_DI_ACCESSOR_INJECTIONS = "codefast/di:accessor-injections:v1";
-/** Well-known key for lifecycle method names written by `@postConstruct()` / `@preDestroy()`. */
+/**
+ * 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.
+ * Returns the runtime symbol used to access TC39 decorator metadata on a class.
+ *
+ * Prefers the native `Symbol.metadata` when available (Stage 3 decorators); falls back to
+ * `Symbol.for("Symbol.metadata")` for Node/runtime versions that polyfill or partially
+ * implement the proposal. The fallback key is the de facto convention used by TypeScript
+ * and polyfill libraries.
  */
 declare function decoratorMetadataObjectSymbol(): symbol;
 //#endregion

package/dist/metadata/metadata-keys.mjs

@@ -1,16 +1,27 @@
 //#region src/metadata/metadata-keys.ts
 /**
-* Well-known key for Codefast DI constructor metadata on `Symbol.metadata`.
+* Well-known property key for constructor injection metadata on `Symbol.metadata`.
+* Written by `@injectable()`, read by `SymbolMetadataReader.getConstructorMetadata()`.
+* The `:v1` suffix is a schema version — bump only when the `ConstructorMetadata` shape changes.
 */
 const CODEFAST_DI_CONSTRUCTOR_METADATA = "codefast/di:constructor-metadata:v1";
-/** Well-known key for accessor field injection metadata written by `@inject` on `accessor` fields. */
+/**
+* Well-known property key for accessor-field injection metadata on `Symbol.metadata`.
+* Written by `@inject()` when used as an accessor decorator; read during post-construction
+* property injection by the resolver.
+*/
 const CODEFAST_DI_ACCESSOR_INJECTIONS = "codefast/di:accessor-injections:v1";
-/** Well-known key for lifecycle method names written by `@postConstruct()` / `@preDestroy()`. */
+/**
+* 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.
+* Returns the runtime symbol used to access TC39 decorator metadata on a class.
+*
+* Prefers the native `Symbol.metadata` when available (Stage 3 decorators); falls back to
+* `Symbol.for("Symbol.metadata")` for Node/runtime versions that polyfill or partially
+* implement the proposal. The fallback key is the de facto convention used by TypeScript
+* and polyfill libraries.
 */
 function decoratorMetadataObjectSymbol() {
 	return typeof Symbol.metadata === "symbol" ? Symbol.metadata : Symbol.for("Symbol.metadata");