alloy-di 1.3.0 → 1.5.0

package/README.md

@@ -1,6 +1,6 @@
 # alloy-di
 
-`alloy-di` is a compile-time dependency injection toolkit for Vite. It scans your TypeScript during build, generates a static container, and ships a tiny runtime so you get dependency injection without reflection overhead.
+`alloy-di` is a build-time dependency injection toolkit for Vite. It scans your TypeScript during build, generates a static container, and ships a tiny runtime so you get dependency injection without reflection overhead.
 
 ## Highlights
 

package/dist/lib/container.d.ts

@@ -1,20 +1,52 @@
 import { Constructor, Newable, Token } from "./types.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.
  *
  * It stores metadata discovered at build time, resolves constructor dependencies,
  * performs singleton caching, and supports token-based value providers.
  */
-declare class Container {
+declare class Container implements ResolutionContext {
   private readonly singletons;
   private readonly pendingSingletons;
   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;
+  readonly parent: ResolutionContext | null;
+  getCached(target: Constructor): unknown;
+  setCached(target: Constructor, instance: unknown): void;
+  getPending(target: Constructor): Promise<unknown> | undefined;
+  setPending(target: Constructor, promise: Promise<unknown>): void;
+  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.
    *
@@ -23,6 +55,14 @@ declare class Container {
    */
   get<T>(target: Newable<T>): Promise<T>;
   get<T>(identifier: ServiceIdentifier<T>): Promise<T>;
+  /** @internal */
+  _registerScopeHierarchy(hierarchy: Record<string, string>): void;
+  /** @internal */
+  _validateScopeParent(childScope: ServiceScope, parentScope: ServiceScope): void;
+  /** @internal */
+  _resolveInContext<T>(target: Newable<T> | ServiceIdentifier<T>, context: ResolutionContext, options?: {
+    skipFactoryWarning?: boolean;
+  }): Promise<T>;
   /**
    * Provide a concrete instance override for a class constructor.
    * Used by test utilities to inject mocks/stubs without altering global metadata.
@@ -45,6 +85,23 @@ declare class Container {
    * @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.
@@ -62,10 +119,8 @@ declare class Container {
    * @throws Error if a circular dependency is detected
    */
   private resolve;
-  /**
-   * Resolve a singleton service with caching and in-flight creation coalescing.
-   */
-  private resolveSingleton;
+  private findContextForScope;
+  private resolveCached;
   /**
    * Instantiate a class by resolving and injecting all declared dependencies.
    * Handles factory-lazy services by importing the real class before instantiation.
@@ -108,9 +163,45 @@ declare class Container {
    */
   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.
    */
@@ -121,4 +212,4 @@ declare class Container {
   private getServiceMetadata;
 }
 //#endregion
-export { Container };
+export { Container, FactoryFn };

package/dist/lib/container.js

@@ -42,10 +42,77 @@ 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;
+	parent = null;
+	getCached(target) {
+		return this.singletons.get(target);
+	}
+	setCached(target, instance) {
+		this.singletons.set(target, instance);
+	}
+	getPending(target) {
+		return this.pendingSingletons.get(target);
+	}
+	setPending(target, promise) {
+		this.pendingSingletons.set(target, promise);
+	}
+	deletePending(target) {
+		this.pendingSingletons.delete(target);
+	}
+	getProvider(tokenId) {
+		return this.valueProviders.get(tokenId);
+	}
+	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);
+		return this.getByConstructor(targetOrIdentifier, this);
+	}
+	/** @internal */
+	_registerScopeHierarchy(hierarchy) {
+		for (const [child, parent] of Object.entries(hierarchy)) this.scopeHierarchy.set(child, parent);
+	}
+	/** @internal */
+	_validateScopeParent(childScope, parentScope) {
+		const declaredParent = this.scopeHierarchy.get(childScope);
+		if (declaredParent && declaredParent !== parentScope) throw new Error(`[alloy] Invalid scope hierarchy construction: scope '${String(childScope)}' is declared with parent '${String(declaredParent)}', but was constructed with parent scope '${String(parentScope)}'.`);
+	}
+	/** @internal */
+	async _resolveInContext(target, context, options) {
+		if (typeof target === "symbol") {
+			const ctor = getConstructorByIdentifier(target);
+			if (!ctor) throw new Error(`No service registered for identifier ${target.description ?? target.toString()}`);
+			return this.getByConstructor(ctor, context, { skipFactoryWarning: true });
+		}
+		return this.getByConstructor(target, context, options);
 	}
 	/**
 	* Provide a concrete instance override for a class constructor.
@@ -69,7 +136,7 @@ var Container = class {
 	async getByIdentifier(identifier) {
 		const ctor = getConstructorByIdentifier(identifier);
 		if (!ctor) throw new Error(`No service registered for identifier ${identifier.description ?? identifier.toString()}`);
-		return this.getByConstructor(ctor, { skipFactoryWarning: true });
+		return this.getByConstructor(ctor, this, { skipFactoryWarning: true });
 	}
 	/**
 	* Register a concrete value for an injection token at runtime.
@@ -81,16 +148,43 @@ 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, options) {
+	async getByConstructor(target, context, options) {
 		if (!options?.skipFactoryWarning) this.maybeWarnFactoryLazyConstructorUsage(target);
-		return this.resolve(target, []);
+		return this.resolve(target, [], context);
 	}
 	maybeWarnFactoryLazyConstructorUsage(target) {
 		if (!isDevEnvironment()) return;
@@ -107,7 +201,7 @@ var Container = class {
 	* @returns Promise resolving to the service instance
 	* @throws Error if a circular dependency is detected
 	*/
-	async resolve(target, resolutionStack) {
+	async resolve(target, resolutionStack, context) {
 		const overridden = this.instanceOverrides.get(target);
 		if (overridden) return overridden;
 		if (resolutionStack.includes(target)) throw new DependencyResolutionError(`Circular dependency detected: ${[...resolutionStack.map((t) => t.name), target.name].join(" -> ")}`, {
@@ -117,26 +211,40 @@ var Container = class {
 		});
 		const metadata = this.getServiceMetadata(target);
 		const nextStack = [...resolutionStack, target];
-		if (metadata.scope === ServiceScope.SINGLETON) return this.resolveSingleton(target, metadata, nextStack);
-		return this.createInstance(target, metadata.dependencies, nextStack, metadata.factory);
+		const targetCtx = this.findContextForScope(metadata.scope, context);
+		if (metadata.scope === ServiceScope.SINGLETON) return this.resolveCached(target, metadata, nextStack, targetCtx);
+		if (metadata.scope === ServiceScope.TRANSIENT) return this.createInstance(target, metadata.dependencies, nextStack, metadata.factory, targetCtx);
+		if (targetCtx.scopeName === metadata.scope) return this.resolveCached(target, metadata, nextStack, targetCtx);
+		return this.createInstance(target, metadata.dependencies, nextStack, metadata.factory, targetCtx);
 	}
-	/**
-	* Resolve a singleton service with caching and in-flight creation coalescing.
-	*/
-	async resolveSingleton(target, metadata, resolutionStack) {
-		const cached = this.singletons.get(target);
+	findContextForScope(scope, startingContext) {
+		if (scope === ServiceScope.SINGLETON) {
+			let current = startingContext;
+			while (current.parent) current = current.parent;
+			return current;
+		}
+		if (scope === ServiceScope.TRANSIENT) return startingContext;
+		let current = startingContext;
+		while (current) {
+			if (current.scopeName === scope) return current;
+			current = current.parent;
+		}
+		return startingContext;
+	}
+	async resolveCached(target, metadata, resolutionStack, targetCtx) {
+		const cached = targetCtx.getCached(target);
 		if (cached) return cached;
-		const pending = this.pendingSingletons.get(target);
+		const pending = targetCtx.getPending(target);
 		if (pending) return await pending;
-		const creation = this.createInstance(target, metadata.dependencies, resolutionStack, metadata.factory).then((instance) => {
-			this.singletons.set(target, instance);
+		const creation = this.createInstance(target, metadata.dependencies, resolutionStack, metadata.factory, targetCtx).then((instance) => {
+			targetCtx.setCached(target, instance);
 			return instance;
 		});
-		this.pendingSingletons.set(target, creation);
+		targetCtx.setPending(target, creation);
 		try {
 			return await creation;
 		} finally {
-			this.pendingSingletons.delete(target);
+			targetCtx.deletePending(target);
 		}
 	}
 	/**
@@ -149,9 +257,9 @@ var Container = class {
 	* @param factory - Optional lazy factory to import the real class
 	* @returns Promise resolving to the instantiated service
 	*/
-	async createInstance(target, dependencies, resolutionStack, factory) {
+	async createInstance(target, dependencies, resolutionStack, factory, context) {
 		const ctor = factory ? await this.importWithRetry(factory, target, resolutionStack) : target;
-		return new ctor(...await Promise.all(dependencies.map((param) => this.resolveParam(param, ctor, resolutionStack))));
+		return new ctor(...await Promise.all(dependencies.map((param) => this.resolveParam(param, ctor, resolutionStack, context))));
 	}
 	/**
 	* Resolve a single dependency entry, handling lazies, tokens, and constructors.
@@ -163,7 +271,7 @@ var Container = class {
 	* @returns Promise resolving to the dependency instance
 	* @throws Error if dependency type is invalid
 	*/
-	async resolveParam(param, target, resolutionStack) {
+	async resolveParam(param, target, resolutionStack, context) {
 		const classification = classifyDependency(param);
 		if (!classification) {
 			const stackPath = this.formatStackPath(target, resolutionStack);
@@ -176,10 +284,10 @@ var Container = class {
 		switch (classification.kind) {
 			case "lazy": {
 				const depClass = await this.importWithRetry(classification.lazy, target, resolutionStack);
-				return this.resolve(depClass, resolutionStack);
+				return this.resolve(depClass, resolutionStack, context);
 			}
-			case "token": return this.resolveTokenLike(classification.token, target, resolutionStack);
-			case "constructor": return this.resolve(classification.ctor, resolutionStack);
+			case "token": return this.resolveTokenLike(classification.token, target, resolutionStack, context);
+			case "constructor": return this.resolve(classification.ctor, resolutionStack, context);
 		}
 		return classification;
 	}
@@ -236,10 +344,16 @@ 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) {
-		if (this.valueProviders.has(tok.id)) return this.valueProviders.get(tok.id);
+	resolveTokenLike(tok, target, resolutionStack, context) {
+		let current = context;
+		while (current) {
+			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,
@@ -248,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/decorators.d.ts

@@ -1,6 +1,6 @@
 import { Newable, Token } from "./types.js";
-import { Lazy } from "./lazy.js";
 import { ServiceScope } from "./scope.js";
+import { Lazy } from "./lazy.js";
 
 //#region src/lib/decorators.d.ts
 /**

package/dist/lib/providers.d.ts

@@ -1,7 +1,7 @@
 import { Newable, Token } from "./types.js";
-import { Container } from "./container.js";
-import { Lazy } from "./lazy.js";
 import { ServiceScope } from "./scope.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

@@ -1,8 +1,44 @@
+import { Constructor } from "./types.js";
+
 //#region src/lib/scope.d.ts
 declare const ServiceScope: {
   readonly SINGLETON: "singleton";
   readonly TRANSIENT: "transient";
 };
-type ServiceScope = (typeof ServiceScope)[keyof typeof ServiceScope];
+interface AlloyScopes {
+  singleton: true;
+  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;
+  setCached(target: Constructor, instance: unknown): void;
+  getPending(target: Constructor): Promise<unknown> | undefined;
+  setPending(target: Constructor, promise: Promise<unknown>): void;
+  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 { ServiceScope };
+export { AlloyScopes, FactoryCacheEntry, FactoryPendingEntry, ResolutionContext, ServiceScope };