@codefast/di 0.3.13-canary.4

package/dist/container.mjs

@@ -0,0 +1,406 @@
+import { AsyncModuleLoadError, CircularDependencyError, InternalError } from "./errors.mjs";
+import { BindingBuilder } from "./binding.mjs";
+import { getAutoRegistered } from "./decorators/injectable.mjs";
+import { SymbolMetadataReader } from "./metadata/symbol-metadata-reader.mjs";
+import { ContainerInspector } from "./inspector.mjs";
+import { AsyncModule } from "./module.mjs";
+import { BindingRegistry } from "./registry.mjs";
+import { DependencyResolver } from "./resolver.mjs";
+import { validateScopeRules } from "./scope-validation.mjs";
+import { ScopeManager } from "./scope.mjs";
+import { isDevelopmentOrTestEnvironment } from "./environment.mjs";
+//#region src/container.ts
+function resolveHintForBinding(binding) {
+	if (binding.bindingName !== void 0) return { name: binding.bindingName };
+	for (const [tagKey, tagValue] of binding.tags) return { tag: [tagKey, tagValue] };
+}
+/**
+* Default IoC container: registry + scoped caches + synchronous / asynchronous resolution.
+* @internal Implementation of {@link Container}; not part of the public package contract.
+*/
+var DefaultContainer = class DefaultContainer {
+	syncModuleStack = [];
+	asyncModuleStack = [];
+	loadedModules = /* @__PURE__ */ new Map();
+	devValidationRan = false;
+	constructor(ownRegistry, ownScopeManager, parent, resolver, metadataReader) {
+		this.ownRegistry = ownRegistry;
+		this.ownScopeManager = ownScopeManager;
+		this.parent = parent;
+		this.resolver = resolver;
+		this.metadataReader = metadataReader;
+	}
+	static create() {
+		const ownRegistry = new BindingRegistry();
+		const ownScopeManager = ScopeManager.createRoot();
+		const metadataReader = new SymbolMetadataReader();
+		const holder = { current: void 0 };
+		const container = new DefaultContainer(ownRegistry, ownScopeManager, void 0, new DependencyResolver({
+			lookup: (token) => {
+				const current = holder.current;
+				if (current === void 0) throw new InternalError("container is not initialized");
+				return current.lookupBindings(token);
+			},
+			scopeManager: ownScopeManager,
+			metadataReader
+		}), metadataReader);
+		holder.current = container;
+		return container;
+	}
+	/**
+	* Starts a fluent binding registered on this container when {@link BindingBuilder.build} runs.
+	*/
+	bind(token) {
+		return new BindingBuilder(token, void 0, {
+			register: (built) => {
+				this.invalidateDevValidationState();
+				this.ownRegistry.add(token, built);
+			},
+			update: (built) => {
+				this.invalidateDevValidationState();
+				this.ownRegistry.replaceById(built.id, built);
+			}
+		});
+	}
+	has(token, hint) {
+		const list = this.lookupBindings(token);
+		if (list === void 0 || list.length === 0) return false;
+		if (hint === void 0) return true;
+		return list.some((binding) => {
+			if (hint.name !== void 0 && binding.bindingName !== hint.name) return false;
+			if (hint.tag !== void 0) {
+				const tag = hint.tag;
+				if (binding.tags.get(tag[0]) !== tag[1]) return false;
+			}
+			return true;
+		});
+	}
+	unbind(tokenOrId) {
+		this.invalidateDevValidationState();
+		if (typeof tokenOrId === "string") {
+			this.ownScopeManager.releaseByBindingId(tokenOrId);
+			this.ownRegistry.removeById(tokenOrId);
+			return;
+		}
+		const owned = this.ownRegistry.get(tokenOrId);
+		if (owned !== void 0) for (const binding of owned) this.ownScopeManager.releaseBinding(binding);
+		this.ownRegistry.remove(tokenOrId);
+	}
+	async unbindAsync(tokenOrId) {
+		this.invalidateDevValidationState();
+		if (typeof tokenOrId === "string") {
+			await this.ownScopeManager.releaseByBindingIdAsync(tokenOrId);
+			this.ownRegistry.removeById(tokenOrId);
+			return;
+		}
+		const owned = this.ownRegistry.get(tokenOrId);
+		if (owned !== void 0) for (const binding of owned) await this.ownScopeManager.releaseBindingAsync(binding);
+		this.ownRegistry.remove(tokenOrId);
+	}
+	rebind(token) {
+		this.invalidateDevValidationState();
+		const owned = this.ownRegistry.get(token);
+		if (owned !== void 0) for (const binding of owned) this.ownScopeManager.releaseBinding(binding);
+		this.ownRegistry.remove(token);
+		return this.bind(token);
+	}
+	/**
+	* Registers bindings from synchronous modules. Re-loading a module already present on this
+	* container is a no-op (deduplication, spec §7.3 Phase 3). When {@link isDevelopmentOrTestEnvironment}
+	* is true, runs {@link validate} at most once after the registry changes.
+	*/
+	load(...modules) {
+		this.invalidateDevValidationState();
+		for (const syncModule of modules) {
+			if (syncModule instanceof AsyncModule) throw new AsyncModuleLoadError(syncModule.name);
+			this.ensureSyncModuleLoaded(syncModule);
+		}
+		this.maybeRunDevValidationOnce();
+	}
+	/**
+	* Like {@link load} but allows async modules. Re-loading is deduplicated the same way.
+	*/
+	async loadAsync(...modules) {
+		this.invalidateDevValidationState();
+		for (const moduleOrAsync of modules) if (moduleOrAsync instanceof AsyncModule) await this.ensureAsyncModuleLoaded(moduleOrAsync);
+		else this.ensureSyncModuleLoaded(moduleOrAsync);
+		this.maybeRunDevValidationOnce();
+	}
+	unload(...modules) {
+		this.invalidateDevValidationState();
+		for (const module of modules) {
+			const ownedBindingIds = this.loadedModules.get(module);
+			if (ownedBindingIds === void 0) throw new InternalError(`Module "${module.name}" is not loaded on this container.`);
+			for (const bindingId of [...ownedBindingIds].reverse()) {
+				this.ownScopeManager.releaseByBindingId(bindingId);
+				this.ownRegistry.removeById(bindingId);
+			}
+			this.loadedModules.delete(module);
+		}
+	}
+	async unloadAsync(...modules) {
+		this.invalidateDevValidationState();
+		for (const module of modules) {
+			const ownedBindingIds = this.loadedModules.get(module);
+			if (ownedBindingIds === void 0) throw new InternalError(`Module "${module.name}" is not loaded on this container.`);
+			for (const bindingId of [...ownedBindingIds].reverse()) {
+				await this.ownScopeManager.releaseByBindingIdAsync(bindingId);
+				this.ownRegistry.removeById(bindingId);
+			}
+			this.loadedModules.delete(module);
+		}
+	}
+	/**
+	* Resolves synchronously. Captive dependency (singleton holding scoped/transient) throws
+	* {@link ScopeViolationError} with binding ids and full resolution path. In dev/test, the first
+	* successful resolution also triggers a one-time static {@link validate} when not in production.
+	*/
+	resolve(key, hint) {
+		try {
+			return this.resolver.resolveRoot(key, hint);
+		} finally {
+			this.maybeRunDevValidationOnce();
+		}
+	}
+	/** Async variant of {@link resolve}; same dev/test validation and runtime scope enforcement. */
+	resolveAsync(key, hint) {
+		return this.resolver.resolveAsyncRoot(key, hint).finally(() => {
+			this.maybeRunDevValidationOnce();
+		});
+	}
+	resolveOptional(key, hint) {
+		try {
+			return this.resolver.resolveOptionalRoot(key, hint);
+		} finally {
+			this.maybeRunDevValidationOnce();
+		}
+	}
+	resolveAll(key, hint) {
+		try {
+			return this.resolver.resolveAllRoot(key, hint);
+		} finally {
+			this.maybeRunDevValidationOnce();
+		}
+	}
+	/**
+	* Async variant of {@link resolveAll}: safe for multi-bindings that mix sync and async factories
+	* (spec §5.2).
+	*/
+	resolveAllAsync(key, hint) {
+		return this.resolver.resolveAllAsyncRoot(key, hint).finally(() => {
+			this.maybeRunDevValidationOnce();
+		});
+	}
+	/**
+	* Eagerly resolves every registered `singleton` binding, including `async-dynamic` factories.
+	*/
+	async initializeAsync() {
+		for (const registryKey of this.collectAllRegistryKeysInHierarchy()) {
+			const list = this.lookupBindings(registryKey);
+			if (list === void 0) continue;
+			for (const binding of list) {
+				if (binding.scope !== "singleton") continue;
+				const hint = resolveHintForBinding(binding);
+				await this.resolveAsync(registryKey, hint);
+			}
+		}
+	}
+	invalidateDevValidationState() {
+		this.devValidationRan = false;
+	}
+	maybeRunDevValidationOnce() {
+		if (!isDevelopmentOrTestEnvironment()) return;
+		if (this.devValidationRan) return;
+		this.devValidationRan = true;
+		this.validate();
+	}
+	/**
+	* Validates static dependency scope rules: a singleton must not depend on scoped/transient
+	* class/factory/alias targets. Constant dependencies are always allowed.
+	*/
+	validate() {
+		validateScopeRules({
+			collectAllRegistryKeys: () => this.collectAllRegistryKeysInHierarchy(),
+			lookupBindings: (registryKey) => this.lookupBindings(registryKey),
+			getMetadataReader: () => this.metadataReader
+		});
+	}
+	/**
+	* Dev/debug snapshot of registered bindings and activation status (design spec §5.5).
+	*/
+	inspect() {
+		return this.createInspector().getSnapshot();
+	}
+	generateDependencyGraph(options) {
+		const inspector = this.createInspector();
+		if (options?.format === "json") return inspector.generateDependencyGraph(options);
+		return inspector.generateDotGraph(options);
+	}
+	loadAutoRegistered() {
+		const entries = getAutoRegistered();
+		let count = 0;
+		for (const { implementationClass, scope } of entries) {
+			const builder = this.bind(implementationClass).toSelf();
+			switch (scope) {
+				case "singleton":
+					builder.singleton();
+					break;
+				case "scoped":
+					builder.scoped();
+					break;
+				default: builder.transient();
+			}
+			count++;
+		}
+		return count;
+	}
+	[Symbol.dispose]() {
+		throw new InternalError("Container disposal is async. Use `await using container = Container.create()` or call `await container.dispose()` instead of `using`.");
+	}
+	createInspector() {
+		return new ContainerInspector({
+			collectAllRegistryKeys: () => this.collectAllRegistryKeysInHierarchy(),
+			lookupBindings: (token) => this.lookupBindings(token),
+			isBindingCached: (binding) => this.ownScopeManager.isBindingCached(binding),
+			metadataReader: this.metadataReader
+		});
+	}
+	collectAllRegistryKeysInHierarchy() {
+		const keys = /* @__PURE__ */ new Set();
+		this.accumulateRegistryKeysFromHierarchy(keys, this);
+		return [...keys];
+	}
+	accumulateRegistryKeysFromHierarchy(keys, container) {
+		if (container === void 0) return;
+		for (const entry of container.ownRegistry.listEntries()) keys.add(entry.key);
+		this.accumulateRegistryKeysFromHierarchy(keys, container.parent);
+	}
+	/**
+	* Child inherits parent bindings via lookup fallback and shares singleton instances,
+	* but receives an isolated scoped cache.
+	*/
+	createChild() {
+		const childRegistry = new BindingRegistry();
+		const childScope = this.ownScopeManager.createChildScope();
+		const holder = { current: void 0 };
+		const resolver = new DependencyResolver({
+			lookup: (token) => {
+				const current = holder.current;
+				if (current === void 0) throw new InternalError("child container is not initialized");
+				return current.lookupBindings(token);
+			},
+			scopeManager: childScope,
+			metadataReader: this.metadataReader
+		});
+		const child = new DefaultContainer(childRegistry, childScope, this, resolver, this.metadataReader);
+		holder.current = child;
+		return child;
+	}
+	lookupBindings(token) {
+		const own = this.ownRegistry.get(token);
+		if (own !== void 0 && own.length > 0) return own;
+		return this.parent?.lookupBindings(token);
+	}
+	async dispose() {
+		await this.ownScopeManager.disposeAsync();
+	}
+	[Symbol.asyncDispose]() {
+		return this.dispose();
+	}
+	bindForModule(owner) {
+		return (token) => new BindingBuilder(token, owner.name, {
+			register: (built) => {
+				this.invalidateDevValidationState();
+				this.ownRegistry.replaceKeyLastWins(token, built, (removed) => {
+					this.ownScopeManager.releaseBinding(removed);
+				});
+				this.recordBindingForModule(owner, built.id);
+			},
+			update: (built) => {
+				this.invalidateDevValidationState();
+				this.ownRegistry.replaceById(built.id, built);
+			}
+		});
+	}
+	recordBindingForModule(owner, id) {
+		const list = this.loadedModules.get(owner);
+		if (list === void 0) {
+			this.loadedModules.set(owner, [id]);
+			return;
+		}
+		list.push(id);
+	}
+	createSyncModuleBuilder(module) {
+		return {
+			import: (...deps) => {
+				for (const dep of deps) {
+					if (dep instanceof AsyncModule) throw new InternalError(`Module "${module.name}" cannot synchronously import async module "${dep.name}".`);
+					this.ensureSyncModuleLoaded(dep);
+				}
+			},
+			bind: this.bindForModule(module)
+		};
+	}
+	createAsyncModuleBuilder(module) {
+		const pendingImports = [];
+		return {
+			moduleBuilder: {
+				import: (...deps) => {
+					for (const dep of deps) if (dep instanceof AsyncModule) pendingImports.push(this.ensureAsyncModuleLoaded(dep));
+					else this.ensureSyncModuleLoaded(dep);
+				},
+				bind: this.bindForModule(module)
+			},
+			awaitImports: async () => {
+				if (pendingImports.length === 0) return;
+				await Promise.all(pendingImports);
+			}
+		};
+	}
+	ensureSyncModuleLoaded(module) {
+		if (this.loadedModules.has(module)) return;
+		if (this.syncModuleStack.includes(module)) throw new CircularDependencyError([...this.syncModuleStack.map((stackedModule) => stackedModule.name), module.name]);
+		this.syncModuleStack.push(module);
+		try {
+			this.loadedModules.set(module, []);
+			const moduleBuilder = this.createSyncModuleBuilder(module);
+			module.runSyncSetup(moduleBuilder);
+		} finally {
+			this.syncModuleStack.pop();
+		}
+	}
+	async ensureAsyncModuleLoaded(asyncModule) {
+		if (this.loadedModules.has(asyncModule)) return;
+		if (this.asyncModuleStack.includes(asyncModule)) throw new CircularDependencyError([...this.asyncModuleStack.map((stackedAsyncModule) => stackedAsyncModule.name), asyncModule.name]);
+		this.asyncModuleStack.push(asyncModule);
+		try {
+			this.loadedModules.set(asyncModule, []);
+			const { moduleBuilder, awaitImports } = this.createAsyncModuleBuilder(asyncModule);
+			await asyncModule.runAsyncSetup(moduleBuilder);
+			await awaitImports();
+		} finally {
+			this.asyncModuleStack.pop();
+		}
+	}
+};
+let Container;
+(function(_Container) {
+	function create() {
+		return DefaultContainer.create();
+	}
+	_Container.create = create;
+	function fromModules(...modules) {
+		const container = DefaultContainer.create();
+		container.load(...modules);
+		return container;
+	}
+	_Container.fromModules = fromModules;
+	async function fromModulesAsync(...modules) {
+		const container = DefaultContainer.create();
+		await container.loadAsync(...modules);
+		return container;
+	}
+	_Container.fromModulesAsync = fromModulesAsync;
+})(Container || (Container = {}));
+//#endregion
+export { Container };

package/dist/decorators/inject.d.mts

@@ -0,0 +1,24 @@
+import { Token } from "../token.mjs";
+import { Constructor, ResolveHint } from "../binding.mjs";
+import { InjectionDescriptor } from "../metadata/metadata-types.mjs";
+
+//#region src/decorators/inject.d.ts
+/** Options forwarded to the container when resolving an injected dependency. */
+type InjectOptions = ResolveHint;
+/**
+ * Creates an {@link InjectionDescriptor} for use in an `@injectable(deps)` array, or as an
+ * `accessor` field decorator for post-construction property injection.
+ *
+ * As a deps-array entry: `@injectable([inject(Logger, { name: 'file' })])`
+ * As an accessor decorator: `@inject(Logger) accessor logger!: LoggerService`
+ */
+declare function inject<Value>(token: Token<Value> | Constructor<Value>, optionsOrContext?: InjectOptions | ClassAccessorDecoratorContext): InjectionDescriptor<Value>;
+/**
+ * Same as {@link inject} but marks the dependency as optional — resolves to `undefined` instead
+ * of throwing {@link TokenNotBoundError} when no binding exists.
+ */
+declare function optional<Value>(token: Token<Value> | Constructor<Value>, options?: InjectOptions): InjectionDescriptor<Value>;
+/** Type-guard — returns `true` when `value` is an {@link InjectionDescriptor}. */
+declare function isInjectionDescriptor(value: unknown): value is InjectionDescriptor;
+//#endregion
+export { InjectOptions, inject, isInjectionDescriptor, optional };

package/dist/decorators/inject.mjs

@@ -0,0 +1,69 @@
+import { InternalError } from "../errors.mjs";
+import { CODEFAST_DI_ACCESSOR_INJECTIONS } from "../metadata/metadata-keys.mjs";
+//#region src/decorators/inject.ts
+/** Validates and normalises the `tag` option from {@link InjectOptions}; throws {@link InternalError} on bad input. */
+function normalizeTag(tag) {
+	if (tag === void 0) return;
+	if (!Array.isArray(tag) || tag.length !== 2) throw new InternalError(`@inject tag must be a tuple [tagKey, value] with length 2; received ${String(tag)}`);
+	const [tagName, value] = tag;
+	if (typeof tagName !== "string") throw new InternalError(`@inject tag key must be a string; received ${typeof tagName}`);
+	return [tagName, value];
+}
+/** Builds an {@link InjectionDescriptor} from a token, optional flag, and raw inject options. */
+function toDescriptor(token, optional, options) {
+	const normalizedTag = normalizeTag(options?.tag);
+	if (options?.name !== void 0) return {
+		token,
+		optional,
+		name: options.name
+	};
+	if (normalizedTag !== void 0) return {
+		token,
+		optional,
+		tag: normalizedTag
+	};
+	return {
+		token,
+		optional
+	};
+}
+/** Type guard — returns `true` when `value` is a TC39 `ClassAccessorDecoratorContext` (accessor field). */
+function isAccessorDecoratorContext(value) {
+	return typeof value === "object" && value !== null && "kind" in value && value.kind === "accessor";
+}
+/**
+* Creates an {@link InjectionDescriptor} for use in an `@injectable(deps)` array, or as an
+* `accessor` field decorator for post-construction property injection.
+*
+* As a deps-array entry: `@injectable([inject(Logger, { name: 'file' })])`
+* As an accessor decorator: `@inject(Logger) accessor logger!: LoggerService`
+*/
+function inject(token, optionsOrContext) {
+	if (isAccessorDecoratorContext(optionsOrContext)) {
+		const ctx = optionsOrContext;
+		const metaRecord = ctx.metadata;
+		const key = CODEFAST_DI_ACCESSOR_INJECTIONS;
+		if (!Array.isArray(metaRecord[key])) metaRecord[key] = [];
+		metaRecord[key].push({
+			name: String(ctx.name),
+			token,
+			optional: false
+		});
+		return;
+	}
+	return toDescriptor(token, false, optionsOrContext);
+}
+/**
+* Same as {@link inject} but marks the dependency as optional — resolves to `undefined` instead
+* of throwing {@link TokenNotBoundError} when no binding exists.
+*/
+function optional(token, options) {
+	return toDescriptor(token, true, options);
+}
+/** Type-guard — returns `true` when `value` is an {@link InjectionDescriptor}. */
+function isInjectionDescriptor(value) {
+	if (typeof value !== "object" || value === null) return false;
+	return "token" in value && "optional" in value;
+}
+//#endregion
+export { inject, isInjectionDescriptor, optional };

package/dist/decorators/injectable.d.mts

@@ -0,0 +1,40 @@
+import { Token } from "../token.mjs";
+import { BindingScope, Constructor } from "../binding.mjs";
+import { InjectionDescriptor } from "../metadata/metadata-types.mjs";
+
+//#region src/decorators/injectable.d.ts
+/**
+ * A single entry in the `deps` array passed to `@injectable()`.
+ * Can be a plain token/constructor (resolved with no hint) or an {@link InjectionDescriptor}
+ * produced by {@link inject} / {@link optional} when name, tag, or optional semantics are needed.
+ */
+type InjectableDependency = Token<unknown> | Constructor<unknown> | InjectionDescriptor<unknown>;
+/**
+ * Returns all classes decorated with `@injectable({ autoRegister: true })`.
+ * Pass to {@link Container.loadAutoRegistered} or iterate manually to bind them.
+ */
+declare function getAutoRegistered(): ReadonlyArray<{
+  implementationClass: Constructor<unknown>;
+  scope: BindingScope;
+}>;
+/**
+ * Stage 3 class decorator that writes constructor dependency metadata into `Symbol.metadata`.
+ *
+ * @param deps - Ordered list of constructor parameters; length must match the class arity.
+ * @param autoRegisterOptions - Optional auto-registration flags.
+ * @param autoRegisterOptions.autoRegister - When `true`, registers the class in {@link getAutoRegistered} at
+ *   class-definition time so {@link Container.loadAutoRegistered} can bind it automatically.
+ * @param autoRegisterOptions.scope - Scope used when auto-registering; defaults to `"transient"`.
+ *
+ * @example
+ * ```ts
+ * @injectable([Logger, inject(Config, { name: "app" })])
+ * class UserService { constructor(log: Logger, cfg: AppConfig) {} }
+ * ```
+ */
+declare function injectable(deps?: readonly InjectableDependency[], autoRegisterOptions?: {
+  autoRegister?: boolean;
+  scope?: BindingScope;
+}): <Class extends abstract new (...args: never[]) => unknown>(implementationClass: Class, context: ClassDecoratorContext<Class>) => void;
+//#endregion
+export { InjectableDependency, getAutoRegistered, injectable };

package/dist/decorators/injectable.mjs

@@ -0,0 +1,62 @@
+import { InternalError } from "../errors.mjs";
+import { CODEFAST_DI_CONSTRUCTOR_METADATA } from "../metadata/metadata-keys.mjs";
+import { isInjectionDescriptor } from "./inject.mjs";
+//#region src/decorators/injectable.ts
+const AUTO_REGISTER_REGISTRY = [];
+/**
+* Returns all classes decorated with `@injectable({ autoRegister: true })`.
+* Pass to {@link Container.loadAutoRegistered} or iterate manually to bind them.
+*/
+function getAutoRegistered() {
+	return AUTO_REGISTER_REGISTRY;
+}
+/** Converts a single `@injectable` deps-array entry into a {@link ParamMetadata} record. */
+function toParamMetadata(dependency, index) {
+	if (isInjectionDescriptor(dependency)) return {
+		index,
+		token: dependency.token,
+		optional: dependency.optional,
+		name: dependency.name,
+		tag: dependency.tag
+	};
+	return {
+		index,
+		token: dependency,
+		optional: false
+	};
+}
+/**
+* Stage 3 class decorator that writes constructor dependency metadata into `Symbol.metadata`.
+*
+* @param deps - Ordered list of constructor parameters; length must match the class arity.
+* @param autoRegisterOptions - Optional auto-registration flags.
+* @param autoRegisterOptions.autoRegister - When `true`, registers the class in {@link getAutoRegistered} at
+*   class-definition time so {@link Container.loadAutoRegistered} can bind it automatically.
+* @param autoRegisterOptions.scope - Scope used when auto-registering; defaults to `"transient"`.
+*
+* @example
+* ```ts
+* @injectable([Logger, inject(Config, { name: "app" })])
+* class UserService { constructor(log: Logger, cfg: AppConfig) {} }
+* ```
+*/
+function injectable(deps = [], autoRegisterOptions) {
+	return (implementationClass, context) => {
+		const declaredArity = implementationClass.length;
+		if (declaredArity !== deps.length) throw new InternalError(`Class "${String(context.name ?? implementationClass.name)}" declares ${String(declaredArity)} constructor parameters but @injectable(...) received ${String(deps.length)} dependency descriptors.`);
+		const payload = { params: deps.map((dependency, index) => toParamMetadata(dependency, index)) };
+		const metadataRecord = context.metadata;
+		metadataRecord[CODEFAST_DI_CONSTRUCTOR_METADATA] = payload;
+		if (autoRegisterOptions?.autoRegister === true) {
+			const scope = autoRegisterOptions.scope ?? "transient";
+			context.addInitializer(function() {
+				AUTO_REGISTER_REGISTRY.push({
+					implementationClass: this,
+					scope
+				});
+			});
+		}
+	};
+}
+//#endregion
+export { getAutoRegistered, injectable };

package/dist/decorators/lifecycle-decorators.d.mts

@@ -0,0 +1,13 @@
+//#region src/decorators/lifecycle-decorators.d.ts
+/**
+ * Stage 3 method decorator: marks a method to be called after the class is instantiated by the container.
+ * Order: construct → `@postConstruct()` → `.onActivation()` → cache.
+ */
+declare function postConstruct(): (target: () => unknown, context: ClassMethodDecoratorContext) => void;
+/**
+ * Stage 3 method decorator: marks a method to be called before the instance is destroyed by the container.
+ * Order: `.onDeactivation()` → `@preDestroy()`.
+ */
+declare function preDestroy(): (target: () => unknown, context: ClassMethodDecoratorContext) => void;
+//#endregion
+export { postConstruct, preDestroy };

package/dist/decorators/lifecycle-decorators.mjs

@@ -0,0 +1,34 @@
+import { CODEFAST_DI_LIFECYCLE_METADATA } from "../metadata/metadata-keys.mjs";
+//#region src/decorators/lifecycle-decorators.ts
+/**
+* Stage 3 method decorator: marks a method to be called after the class is instantiated by the container.
+* Order: construct → `@postConstruct()` → `.onActivation()` → cache.
+*/
+function postConstruct() {
+	return (_target, context) => {
+		const metaRecord = context.metadata;
+		const existing = metaRecord["codefast/di:lifecycle-metadata:v1"] ?? {};
+		if (existing.postConstruct !== void 0) throw new Error(`@postConstruct() is already defined as "${existing.postConstruct}" on this class.`);
+		metaRecord[CODEFAST_DI_LIFECYCLE_METADATA] = {
+			...existing,
+			postConstruct: String(context.name)
+		};
+	};
+}
+/**
+* Stage 3 method decorator: marks a method to be called before the instance is destroyed by the container.
+* Order: `.onDeactivation()` → `@preDestroy()`.
+*/
+function preDestroy() {
+	return (_target, context) => {
+		const metaRecord = context.metadata;
+		const existing = metaRecord["codefast/di:lifecycle-metadata:v1"] ?? {};
+		if (existing.preDestroy !== void 0) throw new Error(`@preDestroy() is already defined as "${existing.preDestroy}" on this class.`);
+		metaRecord[CODEFAST_DI_LIFECYCLE_METADATA] = {
+			...existing,
+			preDestroy: String(context.name)
+		};
+	};
+}
+//#endregion
+export { postConstruct, preDestroy };

package/dist/dependency-graph.d.mts

@@ -0,0 +1,35 @@
+import { RegistryKey } from "./registry.mjs";
+import { Binding, BindingIdentifier, ResolveHint } from "./binding.mjs";
+import { MetadataReader } from "./metadata/metadata-types.mjs";
+
+//#region src/dependency-graph.d.ts
+/** A directed edge in the static dependency graph produced by {@link collectStaticDependencyEdges}. */
+type StaticDependencyEdge = {
+  readonly fromBindingId: BindingIdentifier;
+  readonly toBindingId: BindingIdentifier;
+  readonly resolutionPath: readonly string[];
+  readonly edgeKind: "sync" | "async"; /** True when the resolved target binding carries a {@link BindingBuilder.when} predicate (runtime may skip this edge). */
+  readonly toBindingConditional: boolean; /** Constructor inject hint for this edge (named / tagged), when known statically. */
+  readonly injectHintLabel?: string; /** True when the consumer binding is an alias (rebind to another token). */
+  readonly isAliasEdge: boolean;
+};
+/** A single resolved dependency entry produced by {@link listResolvedDependencies}. */
+type ResolvedDependency = {
+  readonly binding: Binding<unknown>;
+  readonly path: readonly string[];
+  readonly injectHintLabel?: string;
+};
+/** Converts a {@link ResolveHint} to a human-readable edge label for graph output (`name: x` / `tag: k=v`). */
+declare function injectHintLabelFromResolveHint(hint: ResolveHint | undefined): string | undefined;
+/**
+ * Lists direct static dependencies (constructor metadata, `toResolved` tokens, alias targets).
+ * Factories (`toDynamic` / `toAsyncDynamic`) have no enumerable dependency keys.
+ */
+declare function listResolvedDependencies(consumer: Binding<unknown>, lookup: (key: RegistryKey) => readonly Binding<unknown>[] | undefined, reader: MetadataReader | undefined, pathPrefix: readonly string[]): readonly ResolvedDependency[];
+/**
+ * Flattens the direct dependencies of `consumer` into typed graph edges.
+ * Used by {@link ContainerInspector} to build DOT and JSON outputs.
+ */
+declare function collectStaticDependencyEdges(consumer: Binding<unknown>, lookup: (key: RegistryKey) => readonly Binding<unknown>[] | undefined, reader: MetadataReader | undefined, pathPrefix: readonly string[]): readonly StaticDependencyEdge[];
+//#endregion
+export { ResolvedDependency, StaticDependencyEdge, collectStaticDependencyEdges, injectHintLabelFromResolveHint, listResolvedDependencies };