alloy-di 1.4.0 → 1.5.0

package/dist/lib/container.d.ts

@@ -1,8 +1,20 @@
 import { Constructor, Newable, Token } from "./types.js";
-import { ResolutionContext, ServiceScope } from "./scope.js";
+import { FactoryCacheEntry, FactoryPendingEntry, ResolutionContext, ServiceScope } from "./scope.js";
 import { ServiceIdentifier } from "./service-identifiers.js";
 
 //#region src/lib/container.d.ts
+/**
+ * The container-like surface a factory receives. Both the root `Container` and
+ * a `Scope` satisfy it, so a factory can resolve its own dependencies against
+ * whichever context owns its lifecycle (root for `singleton`, the scope for a
+ * custom-scoped factory).
+ */
+interface FactoryContext {
+  get<T>(target: Newable<T> | ServiceIdentifier<T>): Promise<T>;
+  getToken<T>(token: Token<T>): T;
+}
+/** A token-bound factory function executed at resolution time. */
+type FactoryFn<T = unknown> = (context: FactoryContext) => T | Promise<T>;
 /**
  * Runtime dependency injection container used by generated modules and tests.
  *
@@ -15,6 +27,10 @@ declare class Container implements ResolutionContext {
   private readonly instanceOverrides;
   private readonly metadataCache;
   private readonly valueProviders;
+  private readonly factoryRegistry;
+  private readonly factoryValues;
+  private readonly factoryPending;
+  private factoryGeneration;
   private readonly factoryWarningCache;
   private readonly scopeHierarchy;
   readonly scopeName: ServiceScope;
@@ -26,6 +42,11 @@ declare class Container implements ResolutionContext {
   deletePending(target: Constructor): void;
   getProvider(tokenId: symbol): unknown;
   hasProvider(tokenId: symbol): boolean;
+  getFactoryValue(tokenId: symbol): FactoryCacheEntry | undefined;
+  setFactoryValue(tokenId: symbol, generation: number, value: unknown): void;
+  getFactoryPending(tokenId: symbol): FactoryPendingEntry | undefined;
+  setFactoryPending(tokenId: symbol, generation: number, promise: Promise<unknown>): void;
+  deleteFactoryPending(tokenId: symbol, generation: number): void;
   /**
    * Resolve (and construct) the requested service.
    *
@@ -64,6 +85,23 @@ declare class Container implements ResolutionContext {
    * @param value - The value that should be injected when the token is requested.
    */
   provideValue<T>(token: Token<T>, value: T): void;
+  /**
+   * Register a factory function for an injection token. The factory runs at
+   * resolution time and receives the container so it can resolve its own
+   * dependencies.
+   *
+   * This is the imperative escape hatch backing the declarative `asFactory`
+   * provider; prefer `asFactory` + `applyProviders` for static registration.
+   *
+   * @param token - The token created via `createToken`.
+   * @param fn - Factory invoked with the resolving context; may be async.
+   * @param options.lifecycle - `singleton` (default, cached on the root),
+   *   `transient` (re-run on every resolution), or a custom scope name (cached
+   *   once per matching scope instance and disposed with it).
+   */
+  provideFactory<T>(token: Token<T>, fn: FactoryFn<T>, options?: {
+    lifecycle?: ServiceScope;
+  }): void;
   /**
    * Retrieve a provided value for a token from this container.
    * Throws if no provider is registered for the token.
@@ -125,9 +163,45 @@ declare class Container implements ResolutionContext {
    */
   private runImporterWithRetry;
   /**
-   * Resolve a token dependency via registered value providers.
+   * Resolve a token dependency via registered value providers or factories.
    */
   private resolveTokenLike;
+  /**
+   * Execute a token-bound factory according to its lifecycle, caching its
+   * result on the context that owns that lifecycle:
+   *
+   * - `transient`: run `fn` on every call against the current context; nothing
+   *   is cached.
+   * - `singleton`: cache on the root container.
+   * - custom scope: cache on the nearest ancestor context whose `scopeName`
+   *   matches; if none is active, fall back to transient behaviour (mirrors how
+   *   class resolution treats a custom scope with no matching context).
+   */
+  private resolveFactory;
+  /**
+   * Resolve a factory whose result is cached on `targetCtx`, keyed by token id.
+   * Mirrors `resolveCached` for classes: return the cached value, else coalesce
+   * concurrent first-resolutions onto a single `pending` promise, else run the
+   * factory and cache. `pending` is cleared in `finally` so a rejected factory
+   * can be retried rather than caching the failure.
+   */
+  private resolveFactoryCached;
+  /**
+   * Invoke a factory's function against the context that owns its lifecycle,
+   * with a best-effort synchronous re-entrancy guard.
+   *
+   * `executing` is set only for the synchronous duration of `fn(...)` — long
+   * enough to catch a factory that resolves its own token before returning (a
+   * synchronous self-cycle, or a synchronous mutual cycle between factories),
+   * but cleared the moment `fn` returns so that concurrent resolutions which
+   * legitimately coalesce on an in-flight result are never mistaken for a cycle.
+   *
+   * Known limitation: a factory that re-enters its own token *after* awaiting
+   * (an async cross-await self-reference) is indistinguishable from valid
+   * coalescing without async-context tracking, so that case is not caught here
+   * — it is documented in the factory-providers guide.
+   */
+  private runFactory;
   /**
    * Format a readable representation of the resolution stack for error messages.
    */
@@ -138,4 +212,4 @@ declare class Container implements ResolutionContext {
   private getServiceMetadata;
 }
 //#endregion
-export { Container };
+export { Container, FactoryFn };

package/dist/lib/container.js

@@ -42,6 +42,10 @@ var Container = class {
 	instanceOverrides = /* @__PURE__ */ new Map();
 	metadataCache = /* @__PURE__ */ new Map();
 	valueProviders = /* @__PURE__ */ new Map();
+	factoryRegistry = /* @__PURE__ */ new Map();
+	factoryValues = /* @__PURE__ */ new Map();
+	factoryPending = /* @__PURE__ */ new Map();
+	factoryGeneration = 0;
 	factoryWarningCache = /* @__PURE__ */ new WeakSet();
 	scopeHierarchy = /* @__PURE__ */ new Map();
 	scopeName = ServiceScope.SINGLETON;
@@ -67,6 +71,27 @@ var Container = class {
 	hasProvider(tokenId) {
 		return this.valueProviders.has(tokenId);
 	}
+	getFactoryValue(tokenId) {
+		return this.factoryValues.get(tokenId);
+	}
+	setFactoryValue(tokenId, generation, value) {
+		this.factoryValues.set(tokenId, {
+			generation,
+			value
+		});
+	}
+	getFactoryPending(tokenId) {
+		return this.factoryPending.get(tokenId);
+	}
+	setFactoryPending(tokenId, generation, promise) {
+		this.factoryPending.set(tokenId, {
+			generation,
+			promise
+		});
+	}
+	deleteFactoryPending(tokenId, generation) {
+		if (this.factoryPending.get(tokenId)?.generation === generation) this.factoryPending.delete(tokenId);
+	}
 	async get(targetOrIdentifier) {
 		if (typeof targetOrIdentifier === "symbol") return this.getByIdentifier(targetOrIdentifier);
 		return this.getByConstructor(targetOrIdentifier, this);
@@ -123,11 +148,38 @@ var Container = class {
 		this.valueProviders.set(token.id, value);
 	}
 	/**
+	* Register a factory function for an injection token. The factory runs at
+	* resolution time and receives the container so it can resolve its own
+	* dependencies.
+	*
+	* This is the imperative escape hatch backing the declarative `asFactory`
+	* provider; prefer `asFactory` + `applyProviders` for static registration.
+	*
+	* @param token - The token created via `createToken`.
+	* @param fn - Factory invoked with the resolving context; may be async.
+	* @param options.lifecycle - `singleton` (default, cached on the root),
+	*   `transient` (re-run on every resolution), or a custom scope name (cached
+	*   once per matching scope instance and disposed with it).
+	*/
+	provideFactory(token, fn, options) {
+		this.factoryRegistry.set(token.id, {
+			fn,
+			lifecycle: options?.lifecycle ?? ServiceScope.SINGLETON,
+			description: token.description,
+			generation: ++this.factoryGeneration,
+			executing: false
+		});
+	}
+	/**
 	* Retrieve a provided value for a token from this container.
 	* Throws if no provider is registered for the token.
 	*/
 	getToken(token) {
-		if (!this.valueProviders.has(token.id)) throw new Error(`No provider registered for token ${token.description ?? String(token.id)}`);
+		if (!this.valueProviders.has(token.id)) {
+			const label = token.description ?? String(token.id);
+			if (this.factoryRegistry.has(token.id)) throw new Error(`Token ${label} is registered as a factory provider, which cannot be retrieved synchronously via getToken(). Declare it as a dependency so it resolves through the async resolution path instead.`);
+			throw new Error(`No provider registered for token ${label}`);
+		}
 		return this.valueProviders.get(token.id);
 	}
 	async getByConstructor(target, context, options) {
@@ -292,7 +344,7 @@ var Container = class {
 		}
 	}
 	/**
-	* Resolve a token dependency via registered value providers.
+	* Resolve a token dependency via registered value providers or factories.
 	*/
 	resolveTokenLike(tok, target, resolutionStack, context) {
 		let current = context;
@@ -300,6 +352,8 @@ var Container = class {
 			if (current.hasProvider(tok.id)) return current.getProvider(tok.id);
 			current = current.parent;
 		}
+		const factory = this.factoryRegistry.get(tok.id);
+		if (factory) return this.resolveFactory(tok.id, factory, context);
 		const stackPath = this.formatStackPath(target, resolutionStack);
 		throw new DependencyResolutionError(`No provider registered for token ${tok.description ?? String(tok.id)} while resolving ${target.name}. Resolution stack: ${stackPath}`, {
 			target,
@@ -308,6 +362,75 @@ var Container = class {
 		});
 	}
 	/**
+	* Execute a token-bound factory according to its lifecycle, caching its
+	* result on the context that owns that lifecycle:
+	*
+	* - `transient`: run `fn` on every call against the current context; nothing
+	*   is cached.
+	* - `singleton`: cache on the root container.
+	* - custom scope: cache on the nearest ancestor context whose `scopeName`
+	*   matches; if none is active, fall back to transient behaviour (mirrors how
+	*   class resolution treats a custom scope with no matching context).
+	*/
+	resolveFactory(tokenId, descriptor, context) {
+		if (descriptor.lifecycle === ServiceScope.TRANSIENT) return this.runFactory(descriptor, context);
+		const targetCtx = this.findContextForScope(descriptor.lifecycle, context);
+		if (descriptor.lifecycle !== ServiceScope.SINGLETON && targetCtx.scopeName !== descriptor.lifecycle) return this.runFactory(descriptor, context);
+		return this.resolveFactoryCached(tokenId, descriptor, targetCtx);
+	}
+	/**
+	* Resolve a factory whose result is cached on `targetCtx`, keyed by token id.
+	* Mirrors `resolveCached` for classes: return the cached value, else coalesce
+	* concurrent first-resolutions onto a single `pending` promise, else run the
+	* factory and cache. `pending` is cleared in `finally` so a rejected factory
+	* can be retried rather than caching the failure.
+	*/
+	resolveFactoryCached(tokenId, descriptor, targetCtx) {
+		const generation = descriptor.generation;
+		const cached = targetCtx.getFactoryValue(tokenId);
+		if (cached?.generation === generation) return cached.value;
+		const pending = targetCtx.getFactoryPending(tokenId);
+		if (pending?.generation === generation) return pending.promise;
+		const creation = (async () => {
+			try {
+				const value = await this.runFactory(descriptor, targetCtx);
+				targetCtx.setFactoryValue(tokenId, generation, value);
+				return value;
+			} finally {
+				targetCtx.deleteFactoryPending(tokenId, generation);
+			}
+		})();
+		targetCtx.setFactoryPending(tokenId, generation, creation);
+		return creation;
+	}
+	/**
+	* Invoke a factory's function against the context that owns its lifecycle,
+	* with a best-effort synchronous re-entrancy guard.
+	*
+	* `executing` is set only for the synchronous duration of `fn(...)` — long
+	* enough to catch a factory that resolves its own token before returning (a
+	* synchronous self-cycle, or a synchronous mutual cycle between factories),
+	* but cleared the moment `fn` returns so that concurrent resolutions which
+	* legitimately coalesce on an in-flight result are never mistaken for a cycle.
+	*
+	* Known limitation: a factory that re-enters its own token *after* awaiting
+	* (an async cross-await self-reference) is indistinguishable from valid
+	* coalescing without async-context tracking, so that case is not caught here
+	* — it is documented in the factory-providers guide.
+	*/
+	runFactory(descriptor, context) {
+		if (descriptor.executing) {
+			const label = descriptor.description ?? "<token>";
+			throw new Error(`Circular factory dependency detected: the factory for token ${label} resolved its own token while it was still being constructed. Break the cycle by restructuring the factory or resolving the dependency lazily.`);
+		}
+		descriptor.executing = true;
+		try {
+			return descriptor.fn(context);
+		} finally {
+			descriptor.executing = false;
+		}
+	}
+	/**
 	* Format a readable representation of the resolution stack for error messages.
 	*/
 	formatStackPath(target, resolutionStack) {

package/dist/lib/providers.d.ts

@@ -1,6 +1,6 @@
 import { Newable, Token } from "./types.js";
 import { ServiceScope } from "./scope.js";
-import { Container } from "./container.js";
+import { Container, FactoryFn } from "./container.js";
 import { Lazy } from "./lazy.js";
 
 //#region src/lib/providers.d.ts
@@ -56,11 +56,19 @@ interface LazyServiceProviderDescriptor<T = unknown> {
   lifecycle: ProviderLifecycle;
   deps?: DependenciesOption;
 }
+/** Descriptor for a token-bound factory provider with an explicit lifecycle. */
+interface FactoryProviderDescriptor<T = unknown> {
+  kind: "factory";
+  token: Token<T>;
+  factory: FactoryFn<T>;
+  lifecycle: ProviderLifecycle;
+}
 /** Aggregate provider definitions for batch application. */
 interface ProviderDefinitions {
   values?: ValueProviderDescriptor[];
   services?: ServiceProviderDescriptor[];
   lazyServices?: LazyPlaceholder[];
+  factories?: FactoryProviderDescriptor[];
 }
 /**
  * Identity helper for provider definition blocks.
@@ -76,6 +84,22 @@ declare function asClass<T extends Newable<unknown>>(useClass: T, options: {
   lifecycle: ProviderLifecycle;
   deps?: DependenciesOption;
 }): ServiceProviderDescriptor<T>;
+/**
+ * Create a factory provider: bind a token to a function executed at resolution
+ * time. Mirrors `asClass` — a token, a factory function, and a lifecycle.
+ *
+ * The factory receives the resolving context and may be async, so it can
+ * resolve its own dependencies. `singleton` caches the result on the root;
+ * `transient` re-runs on every resolution; a custom scope caches once per
+ * matching scope instance and disposes the result with it.
+ *
+ * @param token Token the produced value is bound to (its type checks `factory`'s return).
+ * @param factory Function invoked with the resolving context; may be async.
+ * @param options.lifecycle Lifecycle scope (singleton, transient, or a custom scope).
+ */
+declare function asFactory<T>(token: Token<T>, factory: FactoryFn<T>, options: {
+  lifecycle: ProviderLifecycle;
+}): FactoryProviderDescriptor<T>;
 /**
  * Convenience lifecycle helpers for fluent provider creation.
  */
@@ -108,4 +132,4 @@ declare function asLazyClass<T, const TDeps extends DependenciesOption>(importer
  */
 declare function applyProviders(container: Container, definitions: ProviderDefinitions | ProviderDefinitions[]): void;
 //#endregion
-export { ProviderDefinitions, applyProviders, asClass, asLazyClass, asValue, defineProviders, lifecycle };
+export { FactoryProviderDescriptor, ProviderDefinitions, applyProviders, asClass, asFactory, asLazyClass, asValue, defineProviders, lifecycle };

package/dist/lib/providers.js

@@ -34,6 +34,27 @@ function asClass(useClass, options) {
 	};
 }
 /**
+* Create a factory provider: bind a token to a function executed at resolution
+* time. Mirrors `asClass` — a token, a factory function, and a lifecycle.
+*
+* The factory receives the resolving context and may be async, so it can
+* resolve its own dependencies. `singleton` caches the result on the root;
+* `transient` re-runs on every resolution; a custom scope caches once per
+* matching scope instance and disposes the result with it.
+*
+* @param token Token the produced value is bound to (its type checks `factory`'s return).
+* @param factory Function invoked with the resolving context; may be async.
+* @param options.lifecycle Lifecycle scope (singleton, transient, or a custom scope).
+*/
+function asFactory(token, factory, options) {
+	return {
+		kind: "factory",
+		token,
+		factory,
+		lifecycle: options.lifecycle
+	};
+}
+/**
 * Convenience lifecycle helpers for fluent provider creation.
 */
 const lifecycle = {
@@ -145,6 +166,7 @@ function applyProviders(container, definitions) {
 	detectProviderCycles(planEntries);
 	for (const definition of list) {
 		for (const valueProvider of definition.values ?? []) container.provideValue(valueProvider.token, valueProvider.value);
+		for (const factoryProvider of definition.factories ?? []) container.provideFactory(factoryProvider.token, factoryProvider.factory, { lifecycle: factoryProvider.lifecycle });
 		const registerService = (ctor, lifecycle, deps, factory) => {
 			dependenciesRegistry.set(ctor, {
 				scope: lifecycle,
@@ -161,4 +183,4 @@ function applyProviders(container, definitions) {
 	}
 }
 //#endregion
-export { applyProviders, asClass, asLazyClass, asValue, defineProviders, lifecycle };
+export { applyProviders, asClass, asFactory, asLazyClass, asValue, defineProviders, lifecycle };

package/dist/lib/scope.d.ts

@@ -10,6 +10,20 @@ interface AlloyScopes {
   transient: true;
 }
 type ServiceScope = keyof AlloyScopes;
+/**
+ * A cached factory result tagged with the `generation` of the descriptor that
+ * produced it. A mismatch against the current descriptor's generation (after a
+ * factory is re-registered) makes the entry stale, so it is recomputed.
+ */
+interface FactoryCacheEntry {
+  generation: number;
+  value: unknown;
+}
+/** An in-flight factory resolution tagged with its descriptor generation. */
+interface FactoryPendingEntry {
+  generation: number;
+  promise: Promise<unknown>;
+}
 interface ResolutionContext {
   readonly scopeName: ServiceScope;
   getCached(target: Constructor): unknown;
@@ -19,7 +33,12 @@ interface ResolutionContext {
   deletePending(target: Constructor): void;
   getProvider(tokenId: symbol): unknown;
   hasProvider(tokenId: symbol): boolean;
+  getFactoryValue(tokenId: symbol): FactoryCacheEntry | undefined;
+  setFactoryValue(tokenId: symbol, generation: number, value: unknown): void;
+  getFactoryPending(tokenId: symbol): FactoryPendingEntry | undefined;
+  setFactoryPending(tokenId: symbol, generation: number, promise: Promise<unknown>): void;
+  deleteFactoryPending(tokenId: symbol, generation: number): void;
   readonly parent: ResolutionContext | null;
 }
 //#endregion
-export { AlloyScopes, ResolutionContext, ServiceScope };
+export { AlloyScopes, FactoryCacheEntry, FactoryPendingEntry, ResolutionContext, ServiceScope };

package/dist/plugins/core/codegen.js

@@ -381,8 +381,8 @@ function generateContainerTypeDefinition(metas, pathResolver) {
 	for (const meta of metas) {
 		const importName = pool.claim(resolver.resolve(meta.className, meta.filePath));
 		const importPath = pathResolver(meta.filePath);
-		if (importName === meta.className) imports.push(`import { ${meta.className} } from '${importPath}';`);
-		else imports.push(`import { ${meta.className} as ${importName} } from '${importPath}';`);
+		if (importName === meta.className) imports.push(`  import { ${meta.className} } from '${importPath}';`);
+		else imports.push(`  import { ${meta.className} as ${importName} } from '${importPath}';`);
 		const exportKey = createIdentifierExportKey(meta, resolver);
 		interfaceMembers.push(`${exportKey}: ServiceIdentifier<${importName}>;`);
 	}

package/dist/plugins/core/container-loader.js

@@ -42,7 +42,7 @@ async function loadVirtualContainerModule(options) {
 		scopes: options.scopes
 	});
 	writeTypeDefinitions(metas, loadedManifests, options.resolvedRoot, options.containerDeclarationDir, options.scopes);
-	writeVisualizationArtifact(metas, lazyClassKeys, options.resolvedVisualization, options.scopes);
+	writeVisualizationArtifact(metas, lazyClassKeys, options.factoryProviders, options.resolvedVisualization, options.scopes);
 	return {
 		code,
 		moduleType: "js"
@@ -93,11 +93,12 @@ function resolveDeclarationImportPath(dtsDir, filePath) {
 	if (!rel.startsWith(".")) rel = "./" + rel;
 	return rel;
 }
-function writeVisualizationArtifact(metas, lazyReferencedClassKeys, resolvedVisualization, scopes) {
+function writeVisualizationArtifact(metas, lazyReferencedClassKeys, factoryProviders, resolvedVisualization, scopes) {
 	if (!resolvedVisualization) return;
 	const artifact = generateMermaidDiagram({
 		metas,
 		lazyClassKeys: new Set(lazyReferencedClassKeys),
+		factoryProviders,
 		options: resolvedVisualization.mermaidOptions,
 		scopes
 	});

package/dist/plugins/core/discovery-runtime.js

@@ -34,31 +34,46 @@ function lazyKeysSignature(keys) {
 	if (!keys || keys.size === 0) return "";
 	return Array.from(keys).toSorted().join("|");
 }
+function factoryProvidersSignature(providers) {
+	return JSON.stringify((providers ?? []).map((provider) => ({
+		filePath: provider.filePath,
+		tokenExpression: provider.tokenExpression,
+		tokenLabel: provider.tokenLabel,
+		lifecycle: provider.lifecycle
+	})));
+}
 function createDiscoveryRuntime() {
 	const discovery = createDiscoveryStore();
 	const discoveredClasses = /* @__PURE__ */ new Map();
 	const lazyReferencedClassKeys = /* @__PURE__ */ new Set();
+	const factoryProvidersByFile = /* @__PURE__ */ new Map();
 	return {
 		discoveredClasses,
 		lazyReferencedClassKeys,
-		processUpdate(id, code) {
-			const { metas, lazyClassKeys, previousMetas, previousLazyClassKeys } = discovery.updateFile(id, code);
+		factoryProvidersByFile,
+		processUpdate(id, code, options) {
+			const trackFactoryProviders = options?.factoryProviders ?? true;
+			const { metas, lazyClassKeys, factoryProviders, previousMetas, previousLazyClassKeys, previousFactoryProviders } = discovery.updateFile(id, code, { factoryProviders: trackFactoryProviders });
 			if (previousMetas) for (const meta of previousMetas) discoveredClasses.delete(createClassKey(meta.filePath, meta.className));
 			for (const meta of metas) discoveredClasses.set(createClassKey(meta.filePath, meta.className), meta);
 			if (previousLazyClassKeys) for (const key of previousLazyClassKeys) lazyReferencedClassKeys.delete(key);
 			if (lazyClassKeys.size) for (const key of lazyClassKeys) lazyReferencedClassKeys.add(key);
-			return metasSignature(previousMetas ?? []) !== metasSignature(metas) || lazyKeysSignature(previousLazyClassKeys) !== lazyKeysSignature(lazyClassKeys);
+			if (trackFactoryProviders && factoryProviders.length) factoryProvidersByFile.set(id, factoryProviders);
+			else factoryProvidersByFile.delete(id);
+			return metasSignature(previousMetas ?? []) !== metasSignature(metas) || lazyKeysSignature(previousLazyClassKeys) !== lazyKeysSignature(lazyClassKeys) || trackFactoryProviders && factoryProvidersSignature(previousFactoryProviders) !== factoryProvidersSignature(factoryProviders);
 		},
 		removeDiscoveredFile(file) {
 			const removed = discovery.removeFile(file);
 			if (removed.previousMetas) for (const meta of removed.previousMetas) discoveredClasses.delete(createClassKey(meta.filePath, meta.className));
 			if (removed.previousLazyClassKeys) for (const key of removed.previousLazyClassKeys) lazyReferencedClassKeys.delete(key);
-			return Boolean(removed.previousMetas?.length || removed.previousLazyClassKeys?.size);
+			factoryProvidersByFile.delete(file);
+			return Boolean(removed.previousMetas?.length || removed.previousLazyClassKeys?.size || removed.previousFactoryProviders?.length);
 		},
 		clear() {
 			discovery.clear();
 			discoveredClasses.clear();
 			lazyReferencedClassKeys.clear();
+			factoryProvidersByFile.clear();
 		}
 	};
 }

package/dist/plugins/core/discovery-store.js

@@ -19,6 +19,7 @@ function hashContent(code) {
 function createDiscoveryStore(options = {}) {
 	const fileMetas = /* @__PURE__ */ new Map();
 	const fileLazyRefs = /* @__PURE__ */ new Map();
+	const fileFactoryProviders = /* @__PURE__ */ new Map();
 	const fileContentHashes = /* @__PURE__ */ new Map();
 	const fileSources = options.trackSources ? /* @__PURE__ */ new Map() : void 0;
 	/**
@@ -28,28 +29,36 @@ function createDiscoveryStore(options = {}) {
 	* @param id - Module identifier or path.
 	* @param code - Current file contents to analyze.
 	*/
-	function updateFile(id, code) {
+	function updateFile(id, code, options) {
+		const scanFactoryProviders = options?.factoryProviders ?? true;
 		const previousMetas = fileMetas.get(id);
 		const previousLazyClassKeys = fileLazyRefs.get(id);
-		const contentHash = hashContent(code);
+		const previousFactoryProviders = fileFactoryProviders.get(id);
+		const contentHash = hashContent(`${scanFactoryProviders ? "factory:1" : "factory:0"}\0${code}`);
 		if (fileContentHashes.get(id) === contentHash) return {
 			metas: previousMetas ?? [],
 			lazyClassKeys: new Set(previousLazyClassKeys),
+			factoryProviders: previousFactoryProviders ?? [],
 			previousMetas,
-			previousLazyClassKeys
+			previousLazyClassKeys,
+			previousFactoryProviders
 		};
 		fileContentHashes.set(id, contentHash);
 		if (fileSources) fileSources.set(id, code);
-		const { metas, lazyClassKeys } = scanSource(code, id);
+		const { metas, lazyClassKeys, factoryProviders } = scanSource(code, id, { factoryProviders: scanFactoryProviders });
 		if (metas.length) fileMetas.set(id, metas);
 		else fileMetas.delete(id);
 		if (lazyClassKeys.size) fileLazyRefs.set(id, lazyClassKeys);
 		else fileLazyRefs.delete(id);
+		if (factoryProviders.length) fileFactoryProviders.set(id, factoryProviders);
+		else fileFactoryProviders.delete(id);
 		return {
 			metas,
 			lazyClassKeys,
+			factoryProviders,
 			previousMetas,
-			previousLazyClassKeys
+			previousLazyClassKeys,
+			previousFactoryProviders
 		};
 	}
 	/**
@@ -60,13 +69,16 @@ function createDiscoveryStore(options = {}) {
 	function removeFile(id) {
 		const previousMetas = fileMetas.get(id);
 		const previousLazyClassKeys = fileLazyRefs.get(id);
+		const previousFactoryProviders = fileFactoryProviders.get(id);
 		fileMetas.delete(id);
 		fileLazyRefs.delete(id);
+		fileFactoryProviders.delete(id);
 		fileContentHashes.delete(id);
 		if (fileSources) fileSources.delete(id);
 		return {
 			previousMetas,
-			previousLazyClassKeys
+			previousLazyClassKeys,
+			previousFactoryProviders
 		};
 	}
 	/**
@@ -75,12 +87,14 @@ function createDiscoveryStore(options = {}) {
 	function clear() {
 		fileMetas.clear();
 		fileLazyRefs.clear();
+		fileFactoryProviders.clear();
 		fileContentHashes.clear();
 		fileSources?.clear();
 	}
 	return {
 		fileMetas,
 		fileLazyRefs,
+		fileFactoryProviders,
 		fileSources,
 		updateFile,
 		removeFile,

package/dist/plugins/core/scanner.js

@@ -1,4 +1,5 @@
 import { createClassKey, createSymbolKey } from "./utils.js";
+import { ServiceScope } from "../../lib/scope.js";
 import { extractServiceMetadata } from "./decorators.js";
 import { processLazyCall, resolveModuleSpecifierCandidates } from "./lazy.js";
 import fs from "node:fs";
@@ -41,17 +42,23 @@ function collectFileImports(sourceFile) {
 * discovery results: decorators require an `@` and lazy references require
 * the `Lazy` identifier.
 */
-function mayContainDiscoverableSyntax(code) {
-	return code.includes("@") || code.includes("Lazy");
+function shouldScanFactoryProviders(options) {
+	return options?.factoryProviders ?? true;
 }
-function scanSource(code, id) {
-	if (!mayContainDiscoverableSyntax(code)) return {
+function mayContainDiscoverableSyntax(code, options) {
+	return code.includes("@") || code.includes("Lazy") || shouldScanFactoryProviders(options) && code.includes("asFactory");
+}
+function scanSource(code, id, options) {
+	const scanFactoryProviders = shouldScanFactoryProviders(options);
+	if (!mayContainDiscoverableSyntax(code, options)) return {
 		metas: [],
-		lazyClassKeys: /* @__PURE__ */ new Set()
+		lazyClassKeys: /* @__PURE__ */ new Set(),
+		factoryProviders: []
 	};
 	const sourceFile = ts.createSourceFile(id, code, ts.ScriptTarget.ESNext, true);
 	const discovered = /* @__PURE__ */ new Map();
 	const lazyRefs = /* @__PURE__ */ new Set();
+	const factoryProviders = [];
 	const fileImports = collectFileImports(sourceFile);
 	const decoratorResolutionCache = /* @__PURE__ */ new Map();
 	const visit = (node) => {
@@ -62,15 +69,72 @@ function scanSource(code, id) {
 			discovered,
 			decoratorResolutionCache
 		});
-		else if (ts.isCallExpression(node)) processLazyCall(node, id, sourceFile, lazyRefs);
+		else if (ts.isCallExpression(node)) {
+			processLazyCall(node, id, sourceFile, lazyRefs);
+			if (scanFactoryProviders) handleFactoryProviderCall(node, {
+				id,
+				sourceFile,
+				fileImports,
+				factoryProviders
+			});
+		}
 		ts.forEachChild(node, visit);
 	};
 	ts.forEachChild(sourceFile, visit);
 	return {
 		metas: Array.from(discovered.values()),
-		lazyClassKeys: lazyRefs
+		lazyClassKeys: lazyRefs,
+		factoryProviders
 	};
 }
+function handleFactoryProviderCall(node, context) {
+	if (!isAlloyRuntimeHelper(node.expression, "asFactory", context.fileImports)) return;
+	const tokenArg = node.arguments[0];
+	if (!tokenArg) return;
+	context.factoryProviders.push({
+		filePath: context.id,
+		tokenExpression: tokenArg.getText(context.sourceFile),
+		tokenLabel: createFactoryTokenLabel(tokenArg, context.sourceFile),
+		lifecycle: extractFactoryLifecycle(node.arguments[2])
+	});
+}
+function isAlloyRuntimeHelper(expression, helperName, fileImports) {
+	if (ts.isIdentifier(expression)) {
+		const importInfo = fileImports.get(expression.text);
+		return Boolean(importInfo && !importInfo.isTypeOnly && importInfo.path === ALLOY_RUNTIME_MODULE && (importInfo.originalName ?? expression.text) === helperName);
+	}
+	if (ts.isPropertyAccessExpression(expression) && ts.isIdentifier(expression.expression)) {
+		const importInfo = fileImports.get(expression.expression.text);
+		return Boolean(importInfo && !importInfo.isTypeOnly && importInfo.path === ALLOY_RUNTIME_MODULE && importInfo.originalName === "*" && expression.name.text === helperName);
+	}
+	return false;
+}
+function createFactoryTokenLabel(tokenArg, sourceFile) {
+	if (ts.isIdentifier(tokenArg)) return tokenArg.text;
+	return tokenArg.getText(sourceFile);
+}
+function extractFactoryLifecycle(optionsArg) {
+	if (!optionsArg || !ts.isObjectLiteralExpression(optionsArg)) return ServiceScope.SINGLETON;
+	for (const prop of optionsArg.properties) {
+		if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) continue;
+		if (prop.name.text !== "lifecycle") continue;
+		return lifecycleExpressionToScope(prop.initializer);
+	}
+	return ServiceScope.SINGLETON;
+}
+function lifecycleExpressionToScope(expression) {
+	if (ts.isStringLiteralLike(expression)) return expression.text;
+	if (ts.isCallExpression(expression)) {
+		const callTarget = expression.expression;
+		if (ts.isPropertyAccessExpression(callTarget) && (callTarget.name.text === "singleton" || callTarget.name.text === "transient")) return callTarget.name.text;
+	}
+	if (ts.isPropertyAccessExpression(expression)) {
+		const member = expression.name.text;
+		if (member === "SINGLETON") return ServiceScope.SINGLETON;
+		if (member === "TRANSIENT") return ServiceScope.TRANSIENT;
+	}
+	return ServiceScope.SINGLETON;
+}
 function handleClassDeclaration(node, context) {
 	if (!node.name) return;
 	const decoratorMatch = findServiceDecorator(node, context.sourceFile, context.fileImports, context.id, context.decoratorResolutionCache);

package/dist/plugins/core/visualizer.js

@@ -49,7 +49,7 @@ const RESERVED_IDENTIFIERS = new Set([
 * @param input - Discovered metadata, optional lazy keys, and rendering options.
 * @returns The rendered diagram plus simple counts useful for reporting.
 */
-function generateMermaidDiagram({ metas, lazyClassKeys, options, scopes }) {
+function generateMermaidDiagram({ metas, lazyClassKeys, factoryProviders, options, scopes }) {
 	const mergedOptions = {
 		...DEFAULT_OPTIONS,
 		...options,
@@ -69,6 +69,7 @@ function generateMermaidDiagram({ metas, lazyClassKeys, options, scopes }) {
 	const nodesByClassName = /* @__PURE__ */ new Map();
 	const nodesByFilePath = /* @__PURE__ */ new Map();
 	const tokenNodes = /* @__PURE__ */ new Map();
+	const factoryNodes = /* @__PURE__ */ new Map();
 	const nodeByMeta = /* @__PURE__ */ new Map();
 	metas.forEach((meta, index) => {
 		const key = createClassKey(meta.filePath, meta.className);
@@ -94,6 +95,7 @@ function generateMermaidDiagram({ metas, lazyClassKeys, options, scopes }) {
 		pathBucket.push(node);
 		nodesByFilePath.set(normalizedPath, pathBucket);
 	});
+	for (const provider of factoryProviders ?? []) ensureFactoryNode(factoryNodes, provider);
 	const edges = [];
 	const edgeKeys = /* @__PURE__ */ new Set();
 	metas.forEach((meta) => {
@@ -105,7 +107,7 @@ function generateMermaidDiagram({ metas, lazyClassKeys, options, scopes }) {
 			if (!identifiers.length) continue;
 			const targets = /* @__PURE__ */ new Map();
 			for (const ident of identifiers) {
-				const resolvedTargets = resolveTargetsForIdentifier(ident, dep.expression, meta, nodesByClassName, nodesByFilePath, tokenNodes);
+				const resolvedTargets = resolveTargetsForIdentifier(ident, dep.expression, meta, nodesByClassName, nodesByFilePath, tokenNodes, factoryNodes);
 				for (const target of resolvedTargets) {
 					if (target.id === sourceNode.id) continue;
 					targets.set(target.id, target);
@@ -140,10 +142,14 @@ function generateMermaidDiagram({ metas, lazyClassKeys, options, scopes }) {
 			lines.push(`  %% Scope stability: ⚠️ ${VIOLATION_EDGE_COLOR} edge = captive dependency (longer-lived service depends on shorter-lived scope)`);
 		}
 	}
-	const allNodes = [...serviceNodes, ...Array.from(tokenNodes.values())];
+	const allNodes = [
+		...serviceNodes,
+		...Array.from(factoryNodes.values()),
+		...Array.from(tokenNodes.values())
+	];
 	const groupedNodes = /* @__PURE__ */ new Map();
 	const ungroupedNodes = [];
-	for (const node of allNodes) if (node.type === "service" && node.scope && customScopes.has(node.scope)) {
+	for (const node of allNodes) if ((node.type === "service" || node.type === "factory") && node.scope && customScopes.has(node.scope)) {
 		const bucket = groupedNodes.get(node.scope) ?? [];
 		bucket.push(node);
 		groupedNodes.set(node.scope, bucket);
@@ -179,7 +185,8 @@ function generateMermaidDiagram({ metas, lazyClassKeys, options, scopes }) {
 		diagram: lines.join("\n"),
 		nodeCount: allNodes.length,
 		edgeCount: edges.length,
-		tokenCount: tokenNodes.size
+		tokenCount: tokenNodes.size,
+		factoryCount: factoryNodes.size
 	};
 }
 /**
@@ -216,12 +223,14 @@ function scopeCode(node) {
 }
 /**
 * True when an edge captures a shorter-lived dependency in a longer-lived host,
-* per the declared hierarchy. Only service-to-service edges with known scopes
-* are considered, and only when a custom hierarchy is configured.
+* per the declared hierarchy. Service dependencies on scoped factory providers
+* are checked too: factory bodies are opaque, but the factory result lifecycle
+* is known and can still be captive.
 */
 function isStabilityViolation(from, to, scopes) {
 	if (!scopes) return false;
-	if (from.type !== "service" || to.type !== "service") return false;
+	if (from.type !== "service") return false;
+	if (to.type !== "service" && to.type !== "factory") return false;
 	if (!from.scope || !to.scope) return false;
 	return !isDependencyAllowed(from.scope, to.scope, scopes);
 }
@@ -238,6 +247,7 @@ function describeEdge(from, to) {
 */
 function nodeFill(node, opts) {
 	if (node.type === "token") return `fill:${opts.tokenNodeFill}`;
+	if (node.type === "factory") return `fill:${opts.factoryNodeFill}`;
 	if (node.hasFactory) return `fill:${opts.factoryNodeFill}`;
 	if (node.isLazyOnly) return `fill:${opts.lazyNodeFill}`;
 	const scopeFill = node.scope ? opts.scopeColors[node.scope] : void 0;
@@ -278,14 +288,17 @@ function inferIdentifiersFromExpression(expression) {
 /**
 * Resolves a dependency identifier to known service nodes, or creates a token node when unresolved.
 */
-function resolveTargetsForIdentifier(identifier, fallbackExpression, meta, nodesByClassName, nodesByFilePath, tokenNodes) {
+function resolveTargetsForIdentifier(identifier, fallbackExpression, meta, nodesByClassName, nodesByFilePath, tokenNodes, factoryNodes) {
 	const serviceMatches = resolveServiceTargets(identifier, meta, nodesByClassName, nodesByFilePath);
 	if (serviceMatches.length) {
 		const deduped = /* @__PURE__ */ new Map();
 		for (const node of serviceMatches) deduped.set(node.id, node);
 		return Array.from(deduped.values());
 	}
-	return [ensureTokenNode(tokenNodes, createTokenLabel(identifier || fallbackExpression))];
+	const tokenLabel = createTokenLabel(identifier || fallbackExpression);
+	const factoryNode = factoryNodes.get(tokenLabel);
+	if (factoryNode) return [factoryNode];
+	return [ensureTokenNode(tokenNodes, tokenLabel)];
 }
 /**
 * Attempts to find service nodes that match an identifier via import metadata or class names.
@@ -340,6 +353,23 @@ function ensureTokenNode(tokenNodes, label) {
 	tokenNodes.set(label, node);
 	return node;
 }
+function ensureFactoryNode(factoryNodes, provider) {
+	const label = createTokenLabel(provider.tokenLabel || provider.tokenExpression);
+	const existing = factoryNodes.get(label);
+	if (existing) return existing;
+	const node = {
+		id: sanitizeMermaidId(`factory:${provider.filePath}:${provider.tokenExpression}`, factoryNodes.size),
+		label: `Factory: ${label}`,
+		key: label,
+		scope: provider.lifecycle,
+		type: "factory",
+		isLazyOnly: false,
+		hasFactory: true,
+		filePath: normalizeImportPath(provider.filePath)
+	};
+	factoryNodes.set(label, node);
+	return node;
+}
 /**
 * Condenses arbitrary strings into stable token labels, truncating overly long values.
 */

package/dist/plugins/vite-plugin/index.js

@@ -26,6 +26,7 @@ function alloy(options = {}) {
 	let isDevMode;
 	const lazyServiceKeys = new Set((options.lazyServices ?? []).map(toLazyServiceKey));
 	const discoveryRuntime = createDiscoveryRuntime();
+	const shouldTrackFactoryProviders = () => Boolean(resolvedVisualization);
 	return {
 		name: "vite-plugin-alloy",
 		enforce: "pre",
@@ -59,7 +60,7 @@ function alloy(options = {}) {
 				exclude: [/\.d\.ts$/i, /node_modules/]
 			} },
 			handler(code, id) {
-				discoveryRuntime.processUpdate(id, code);
+				discoveryRuntime.processUpdate(id, code, { factoryProviders: shouldTrackFactoryProviders() });
 				return null;
 			}
 		},
@@ -76,7 +77,7 @@ function alloy(options = {}) {
 				} catch {
 					return;
 				}
-				discoveryChanged = discoveryRuntime.processUpdate(file, code);
+				discoveryChanged = discoveryRuntime.processUpdate(file, code, { factoryProviders: shouldTrackFactoryProviders() });
 			}
 			if (!discoveryChanged) return;
 			invalidateContainerModule(ctx.server, resolvedVirtualModuleId);
@@ -85,11 +86,17 @@ function alloy(options = {}) {
 		},
 		buildStart() {
 			discoveryRuntime.clear();
-			for (const ref of providerModuleRefs) this.addWatchFile(ref.absPath);
+			for (const ref of providerModuleRefs) {
+				this.addWatchFile(ref.absPath);
+				if (shouldTrackFactoryProviders()) try {
+					const code = fs.readFileSync(ref.absPath, "utf-8");
+					discoveryRuntime.processUpdate(ref.absPath, code, { factoryProviders: true });
+				} catch {}
+			}
 			const files = walkSync(path.join(resolvedRoot, "src"));
 			for (const file of files) if (/\.(tsx?|ts)$/i.test(file) && !file.endsWith(".d.ts")) try {
 				const code = fs.readFileSync(file, "utf-8");
-				discoveryRuntime.processUpdate(file, code);
+				discoveryRuntime.processUpdate(file, code, { factoryProviders: shouldTrackFactoryProviders() });
 			} catch {}
 		},
 		load: {
@@ -101,6 +108,7 @@ function alloy(options = {}) {
 					lazyReferencedClassKeys: discoveryRuntime.lazyReferencedClassKeys,
 					manifests: options.manifests ?? [],
 					providerImportPaths: providerModuleRefs.map((ref) => ref.importPath),
+					factoryProviders: shouldTrackFactoryProviders() ? Array.from(discoveryRuntime.factoryProvidersByFile.values()).flat() : [],
 					lazyServiceKeys,
 					packageName,
 					resolvedRoot,

package/dist/runtime.d.ts

@@ -1,9 +1,9 @@
 import { Newable, Token, createToken } from "./lib/types.js";
 import { AlloyScopes, ResolutionContext, ServiceScope } from "./lib/scope.js";
 import { ServiceIdentifier, clearServiceIdentifierRegistry, getConstructorByIdentifier, getServiceIdentifier, registerServiceIdentifier } from "./lib/service-identifiers.js";
-import { Container } from "./lib/container.js";
+import { Container, FactoryFn } from "./lib/container.js";
 import { EnvDetectionOverrides, setEnvDetectionOverrides } from "./lib/env-detection.js";
 import { LAZY_IDENTIFIER, Lazy } from "./lib/lazy.js";
 import { Injectable, Singleton, assertDeps, dependenciesRegistry, deps } from "./lib/decorators.js";
-import { ProviderDefinitions, applyProviders, asClass, asLazyClass, asValue, defineProviders, lifecycle } from "./lib/providers.js";
-export { type AlloyScopes, Container, type EnvDetectionOverrides, Injectable, LAZY_IDENTIFIER, Lazy, type Lazy as LazyInterface, type Newable, type ProviderDefinitions, type ResolutionContext, type ServiceIdentifier, ServiceScope, Singleton, type Token, applyProviders, asClass, asLazyClass, asValue, assertDeps, clearServiceIdentifierRegistry, createToken, defineProviders, dependenciesRegistry, deps, getConstructorByIdentifier, getServiceIdentifier, lifecycle, registerServiceIdentifier, setEnvDetectionOverrides };
+import { FactoryProviderDescriptor, ProviderDefinitions, applyProviders, asClass, asFactory, asLazyClass, asValue, defineProviders, lifecycle } from "./lib/providers.js";
+export { type AlloyScopes, Container, type EnvDetectionOverrides, type FactoryFn, type FactoryProviderDescriptor, Injectable, LAZY_IDENTIFIER, Lazy, type Lazy as LazyInterface, type Newable, type ProviderDefinitions, type ResolutionContext, type ServiceIdentifier, ServiceScope, Singleton, type Token, applyProviders, asClass, asFactory, asLazyClass, asValue, assertDeps, clearServiceIdentifierRegistry, createToken, defineProviders, dependenciesRegistry, deps, getConstructorByIdentifier, getServiceIdentifier, lifecycle, registerServiceIdentifier, setEnvDetectionOverrides };

package/dist/runtime.js

@@ -5,5 +5,5 @@ import { Injectable, Singleton, assertDeps, dependenciesRegistry, deps } from ".
 import { clearServiceIdentifierRegistry, getConstructorByIdentifier, getServiceIdentifier, registerServiceIdentifier } from "./lib/service-identifiers.js";
 import { setEnvDetectionOverrides } from "./lib/env-detection.js";
 import { Container } from "./lib/container.js";
-import { applyProviders, asClass, asLazyClass, asValue, defineProviders, lifecycle } from "./lib/providers.js";
-export { Container, Injectable, LAZY_IDENTIFIER, Lazy, ServiceScope, Singleton, applyProviders, asClass, asLazyClass, asValue, assertDeps, clearServiceIdentifierRegistry, createToken, defineProviders, dependenciesRegistry, deps, getConstructorByIdentifier, getServiceIdentifier, lifecycle, registerServiceIdentifier, setEnvDetectionOverrides };
+import { applyProviders, asClass, asFactory, asLazyClass, asValue, defineProviders, lifecycle } from "./lib/providers.js";
+export { Container, Injectable, LAZY_IDENTIFIER, Lazy, ServiceScope, Singleton, applyProviders, asClass, asFactory, asLazyClass, asValue, assertDeps, clearServiceIdentifierRegistry, createToken, defineProviders, dependenciesRegistry, deps, getConstructorByIdentifier, getServiceIdentifier, lifecycle, registerServiceIdentifier, setEnvDetectionOverrides };

package/dist/scopes.d.ts

@@ -1,5 +1,5 @@
 import { Constructor, Newable, Token } from "./lib/types.js";
-import { ResolutionContext, ServiceScope } from "./lib/scope.js";
+import { FactoryCacheEntry, FactoryPendingEntry, ResolutionContext, ServiceScope } from "./lib/scope.js";
 import { ServiceIdentifier } from "./lib/service-identifiers.js";
 import { Container } from "./lib/container.js";
 
@@ -14,6 +14,8 @@ declare class Scope implements ResolutionContext {
   private readonly cached;
   private readonly pending;
   private readonly valueProviders;
+  private readonly factoryValues;
+  private readonly factoryPending;
   private readonly activeChildren;
   private readonly instantiatedInstances;
   constructor(parent: ResolutionContext, scopeName: ServiceScope);
@@ -29,6 +31,11 @@ declare class Scope implements ResolutionContext {
   deletePending(target: Constructor): void;
   getProvider(tokenId: symbol): unknown;
   hasProvider(tokenId: symbol): boolean;
+  getFactoryValue(tokenId: symbol): FactoryCacheEntry | undefined;
+  setFactoryValue(tokenId: symbol, generation: number, value: unknown): void;
+  getFactoryPending(tokenId: symbol): FactoryPendingEntry | undefined;
+  setFactoryPending(tokenId: symbol, generation: number, promise: Promise<unknown>): void;
+  deleteFactoryPending(tokenId: symbol, generation: number): void;
   /**
    * Register a value provider for a token scoped to this context.
    */

package/dist/scopes.js

@@ -9,6 +9,8 @@ var Scope = class Scope {
 	cached = /* @__PURE__ */ new Map();
 	pending = /* @__PURE__ */ new Map();
 	valueProviders = /* @__PURE__ */ new Map();
+	factoryValues = /* @__PURE__ */ new Map();
+	factoryPending = /* @__PURE__ */ new Map();
 	activeChildren = /* @__PURE__ */ new Set();
 	instantiatedInstances = [];
 	constructor(parent, scopeName) {
@@ -48,6 +50,28 @@ var Scope = class Scope {
 		if (this.valueProviders.has(tokenId)) return true;
 		return this.parent.hasProvider(tokenId);
 	}
+	getFactoryValue(tokenId) {
+		return this.factoryValues.get(tokenId);
+	}
+	setFactoryValue(tokenId, generation, value) {
+		this.factoryValues.set(tokenId, {
+			generation,
+			value
+		});
+		this.instantiatedInstances.push(value);
+	}
+	getFactoryPending(tokenId) {
+		return this.factoryPending.get(tokenId);
+	}
+	setFactoryPending(tokenId, generation, promise) {
+		this.factoryPending.set(tokenId, {
+			generation,
+			promise
+		});
+	}
+	deleteFactoryPending(tokenId, generation) {
+		if (this.factoryPending.get(tokenId)?.generation === generation) this.factoryPending.delete(tokenId);
+	}
 	/**
 	* Register a value provider for a token scoped to this context.
 	*/
@@ -111,6 +135,8 @@ var Scope = class Scope {
 			this.cached.clear();
 			this.pending.clear();
 			this.valueProviders.clear();
+			this.factoryValues.clear();
+			this.factoryPending.clear();
 			if (this.parent instanceof Scope) this.parent.activeChildren.delete(this);
 		}
 		if (errors.length > 0) {

package/dist/test.d.ts

@@ -1,22 +1,38 @@
 import { Newable, Token, createToken } from "./lib/types.js";
+import { ServiceScope } from "./lib/scope.js";
 import { ServiceIdentifier } from "./lib/service-identifiers.js";
-import { Container } from "./lib/container.js";
+import { Container, FactoryFn } from "./lib/container.js";
 import { ProviderDefinitions } from "./lib/providers.js";
+import { Scope } from "./scopes.js";
 import { MockOf } from "./lib/testing/mocking.js";
 import { vi } from "vitest";
 
 //#region src/test.d.ts
+type FactoryOverrideSpec<T = unknown> = [token: Token<T>, factory: FactoryFn<T>, options?: {
+  lifecycle?: ServiceScope;
+}];
+type TestScopeHierarchy = Record<string, {
+  parent?: ServiceScope;
+}>;
 interface OverrideSpec {
   /** Class constructor instance overrides */
   instances?: Array<[Newable<unknown>, unknown]>;
   /** Token value overrides */
   tokens?: Array<[Token<unknown>, unknown]>;
+  /**
+   * Token factory overrides. These are explicit token-keyed overrides and are
+   * not affected by autoMock, which only mocks class constructor dependencies.
+   * Token value overrides still take precedence for the same token.
+   */
+  factories?: FactoryOverrideSpec[];
 }
 interface CreateTestContainerOptions {
   overrides?: OverrideSpec;
   autoMock?: boolean;
   target?: Newable<unknown>;
   providers?: ProviderDefinitions | ProviderDefinitions[];
+  /** Custom scope hierarchy for tests, matching alloy({ scopes }) shape. */
+  scopes?: TestScopeHierarchy;
 }
 interface TestContainerHandle {
   container: Container;
@@ -26,6 +42,16 @@ interface TestContainerHandle {
   getToken<T>(token: Token<T>): T;
   /** Provide a token value into the container */
   provideToken?<T>(token: Token<T>, value: T): void;
+  /** Provide a token factory into the container */
+  provideFactory?<T>(token: Token<T>, factory: FactoryFn<T>, options?: {
+    lifecycle?: ServiceScope;
+  }): void;
+  /** Alias for provideFactory when replacing an existing test factory. */
+  overrideFactory?<T>(token: Token<T>, factory: FactoryFn<T>, options?: {
+    lifecycle?: ServiceScope;
+  }): void;
+  /** Create a scope under the test container. */
+  createScope?(scopeName: ServiceScope): Scope;
   /** Placeholder restore hook (future phases may implement overlay stacks). */
   restore(): void;
   /** Retrieve a single class mock (if autoMock enabled). */
@@ -39,12 +65,20 @@ interface TestContainerHandle {
 }
 /**
  * Create a test-focused container with manual overrides.
- * - Does not perform auto-mocking (Phase 2 will expand this).
+ * - Auto-mocking, when enabled, only mocks class constructor dependencies.
+ * - Token factories are explicit overrides and are applied after provider blocks.
  */
 declare function createTestContainer(opts?: CreateTestContainerOptions | OverrideSpec): TestContainerHandle & {
   getMock<T>(ctor: Newable<T>): MockOf<T> | undefined;
   getMocks<T extends readonly Newable<unknown>[]>(ctors: T): { [K in keyof T]: T[K] extends Newable<infer I> ? MockOf<I> | undefined : never };
   provideToken<T>(token: Token<T>, value: T): void;
+  provideFactory<T>(token: Token<T>, factory: FactoryFn<T>, options?: {
+    lifecycle?: ServiceScope;
+  }): void;
+  overrideFactory<T>(token: Token<T>, factory: FactoryFn<T>, options?: {
+    lifecycle?: ServiceScope;
+  }): void;
+  createScope(scopeName: ServiceScope): Scope;
 };
 //#endregion
-export { CreateTestContainerOptions, type MockOf, OverrideSpec, TestContainerHandle, createTestContainer, createToken };
+export { CreateTestContainerOptions, FactoryOverrideSpec, type MockOf, OverrideSpec, TestContainerHandle, TestScopeHierarchy, createTestContainer, createToken };

package/dist/test.js

@@ -3,18 +3,27 @@ import { Container } from "./lib/container.js";
 import { applyProviders } from "./lib/providers.js";
 import { restoreRegistry, snapshotRegistry } from "./lib/testing/registry.js";
 import { applyAutoMocks } from "./lib/testing/mocking.js";
+import { createScope } from "./scopes.js";
 //#region src/test.ts
+function normalizeScopeHierarchy(scopes) {
+	const hierarchy = {};
+	for (const [scopeName, config] of Object.entries(scopes)) hierarchy[scopeName] = config.parent ?? "singleton";
+	return hierarchy;
+}
 /**
 * Create a test-focused container with manual overrides.
-* - Does not perform auto-mocking (Phase 2 will expand this).
+* - Auto-mocking, when enabled, only mocks class constructor dependencies.
+* - Token factories are explicit overrides and are applied after provider blocks.
 */
 function createTestContainer(opts) {
-	const isLegacy = !!opts && !("autoMock" in opts) && !("target" in opts) && !("overrides" in opts);
+	const isLegacy = !!opts && !("autoMock" in opts) && !("target" in opts) && !("overrides" in opts) && !("providers" in opts) && !("scopes" in opts);
 	const normalizedOpts = isLegacy ? { overrides: opts } : opts ?? {};
 	const overrides = normalizedOpts.overrides ?? (isLegacy ? opts : void 0);
 	const container = new Container();
 	const snapshot = snapshotRegistry();
+	if (normalizedOpts.scopes) container._registerScopeHierarchy(normalizeScopeHierarchy(normalizedOpts.scopes));
 	if (normalizedOpts.providers) applyProviders(container, normalizedOpts.providers);
+	for (const [tok, factory, options] of overrides?.factories ?? []) container.provideFactory(tok, factory, options);
 	for (const [tok, value] of overrides?.tokens ?? []) container.provideValue(tok, value);
 	const overriddenCtors = new Set(overrides?.instances?.map(([c]) => c) ?? []);
 	for (const [ctor, instance] of overrides?.instances ?? []) container.overrideInstance(ctor, instance);
@@ -39,6 +48,15 @@ function createTestContainer(opts) {
 		provideToken: (token, value) => {
 			container.provideValue(token, value);
 		},
+		provideFactory: (token, factory, options) => {
+			container.provideFactory(token, factory, options);
+		},
+		overrideFactory: (token, factory, options) => {
+			container.provideFactory(token, factory, options);
+		},
+		createScope: (scopeName) => {
+			return createScope(container, scopeName);
+		},
 		getMock: (ctor) => {
 			return mocks?.get(ctor) ?? void 0;
 		},

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/entry-points.test.ts","../src/fixture-subpaths.test.ts","../src/rollup.ts","../src/runtime.ts","../src/scopes.ts","../src/test.ts","../src/vite.ts","../src/lib/container.identifiers.test.ts","../src/lib/container.internals.test.ts","../src/lib/container.test.ts","../src/lib/container.testing-features.test.ts","../src/lib/container.ts","../src/lib/decorators.runtime.test.ts","../src/lib/decorators.test-d.ts","../src/lib/decorators.ts","../src/lib/dependency-error.ts","../src/lib/env-detection.test.ts","../src/lib/env-detection.ts","../src/lib/lazy-retry.test.ts","../src/lib/lazy.ts","../src/lib/providers.test.ts","../src/lib/providers.ts","../src/lib/scope.ts","../src/lib/scopes.test.ts","../src/lib/service-identifiers.test.ts","../src/lib/service-identifiers.ts","../src/lib/tokens.test.ts","../src/lib/types.ts","../src/lib/testing/mocking.test.ts","../src/lib/testing/mocking.ts","../src/lib/testing/registry.test.ts","../src/lib/testing/registry.ts","../src/plugins/core/codegen.test.ts","../src/plugins/core/codegen.ts","../src/plugins/core/container-loader.test.ts","../src/plugins/core/container-loader.ts","../src/plugins/core/decorators.helpers.test.ts","../src/plugins/core/decorators.ts","../src/plugins/core/discovery-runtime.ts","../src/plugins/core/discovery-store.test.ts","../src/plugins/core/discovery-store.ts","../src/plugins/core/identifier-resolver.test.ts","../src/plugins/core/identifier-resolver.ts","../src/plugins/core/lazy-utils.ts","../src/plugins/core/lazy.helpers.test.ts","../src/plugins/core/lazy.ts","../src/plugins/core/manifest-utils.ts","../src/plugins/core/manifest-utils.validation.test.ts","../src/plugins/core/scanner.test.ts","../src/plugins/core/scanner.ts","../src/plugins/core/scopes-validation.test.ts","../src/plugins/core/scopes-validation.ts","../src/plugins/core/types.ts","../src/plugins/core/utils.ts","../src/plugins/core/utils.walk.test.ts","../src/plugins/core/utils.write.test.ts","../src/plugins/core/visualization-utils.ts","../src/plugins/core/visualizer.test.ts","../src/plugins/core/visualizer.ts","../src/plugins/rollup-plugin/barrel-exports.test.ts","../src/plugins/rollup-plugin/barrel-exports.ts","../src/plugins/rollup-plugin/build-utils.test.ts","../src/plugins/rollup-plugin/build-utils.ts","../src/plugins/rollup-plugin/dependency-resolution.test.ts","../src/plugins/rollup-plugin/dependency-resolution.ts","../src/plugins/rollup-plugin/index.test.ts","../src/plugins/rollup-plugin/index.ts","../src/plugins/rollup-plugin/manifest-deps.test.ts","../src/plugins/rollup-plugin/manifest-deps.ts","../src/plugins/rollup-plugin/package-exports.test.ts","../src/plugins/rollup-plugin/package-exports.ts","../src/plugins/rollup-plugin/types.ts","../src/plugins/vite-plugin/duplicate-registrations.test.ts","../src/plugins/vite-plugin/index.ts","../src/plugins/vite-plugin/lazy-services.test.ts","../src/plugins/vite-plugin/lifecycle-and-hmr.test.ts","../src/plugins/vite-plugin/module-generation.test.ts","../src/plugins/vite-plugin/module-invalidation.ts","../src/plugins/vite-plugin/test-utils.ts","../src/plugins/vite-plugin/transform-guards.test.ts","../src/plugins/vite-plugin/visualization-option.test.ts"],"version":"6.0.3"}
+{"root":["../src/entry-points.test.ts","../src/fixture-subpaths.test.ts","../src/rollup.ts","../src/runtime.ts","../src/scopes.ts","../src/test.test.ts","../src/test.ts","../src/vite.ts","../src/lib/container.factories-scoped.test.ts","../src/lib/container.factories.test.ts","../src/lib/container.identifiers.test.ts","../src/lib/container.internals.test.ts","../src/lib/container.test.ts","../src/lib/container.testing-features.test.ts","../src/lib/container.ts","../src/lib/decorators.runtime.test.ts","../src/lib/decorators.test-d.ts","../src/lib/decorators.ts","../src/lib/dependency-error.ts","../src/lib/env-detection.test.ts","../src/lib/env-detection.ts","../src/lib/lazy-retry.test.ts","../src/lib/lazy.ts","../src/lib/providers.test.ts","../src/lib/providers.ts","../src/lib/scope.ts","../src/lib/scopes.test.ts","../src/lib/service-identifiers.test.ts","../src/lib/service-identifiers.ts","../src/lib/tokens.test.ts","../src/lib/types.ts","../src/lib/testing/mocking.test.ts","../src/lib/testing/mocking.ts","../src/lib/testing/registry.test.ts","../src/lib/testing/registry.ts","../src/plugins/core/codegen.test.ts","../src/plugins/core/codegen.ts","../src/plugins/core/container-loader.test.ts","../src/plugins/core/container-loader.ts","../src/plugins/core/decorators.helpers.test.ts","../src/plugins/core/decorators.ts","../src/plugins/core/discovery-runtime.ts","../src/plugins/core/discovery-store.test.ts","../src/plugins/core/discovery-store.ts","../src/plugins/core/identifier-resolver.test.ts","../src/plugins/core/identifier-resolver.ts","../src/plugins/core/lazy-utils.ts","../src/plugins/core/lazy.helpers.test.ts","../src/plugins/core/lazy.ts","../src/plugins/core/manifest-utils.ts","../src/plugins/core/manifest-utils.validation.test.ts","../src/plugins/core/scanner.test.ts","../src/plugins/core/scanner.ts","../src/plugins/core/scopes-validation.test.ts","../src/plugins/core/scopes-validation.ts","../src/plugins/core/types.ts","../src/plugins/core/utils.ts","../src/plugins/core/utils.walk.test.ts","../src/plugins/core/utils.write.test.ts","../src/plugins/core/visualization-utils.ts","../src/plugins/core/visualizer.test.ts","../src/plugins/core/visualizer.ts","../src/plugins/rollup-plugin/barrel-exports.test.ts","../src/plugins/rollup-plugin/barrel-exports.ts","../src/plugins/rollup-plugin/build-utils.test.ts","../src/plugins/rollup-plugin/build-utils.ts","../src/plugins/rollup-plugin/dependency-resolution.test.ts","../src/plugins/rollup-plugin/dependency-resolution.ts","../src/plugins/rollup-plugin/index.test.ts","../src/plugins/rollup-plugin/index.ts","../src/plugins/rollup-plugin/manifest-deps.test.ts","../src/plugins/rollup-plugin/manifest-deps.ts","../src/plugins/rollup-plugin/package-exports.test.ts","../src/plugins/rollup-plugin/package-exports.ts","../src/plugins/rollup-plugin/types.ts","../src/plugins/vite-plugin/duplicate-registrations.test.ts","../src/plugins/vite-plugin/index.ts","../src/plugins/vite-plugin/lazy-services.test.ts","../src/plugins/vite-plugin/lifecycle-and-hmr.test.ts","../src/plugins/vite-plugin/module-generation.test.ts","../src/plugins/vite-plugin/module-invalidation.ts","../src/plugins/vite-plugin/test-utils.ts","../src/plugins/vite-plugin/transform-guards.test.ts","../src/plugins/vite-plugin/visualization-option.test.ts"],"version":"6.0.3"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alloy-di",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "A build-time dependency injection plugin for Vite",
   "keywords": [
     "dependency-injection",