alloy-di 1.4.0 → 2.0.0

package/README.md

@@ -1,13 +1,13 @@
 # alloy-di
 
-`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.
+`alloy-di` is a build-time dependency injection toolkit for TypeScript apps. It scans your TypeScript during build, generates a static container, and ships a tiny runtime so you get dependency injection without reflection overhead.
 
 ## Highlights
 
 - **Build-time graph** – services, scopes, and dependencies are resolved while bundling, so runtime work stays minimal.
-- **Visualize your DI graph** – enable the Vite plugin’s `visualize` option to emit a Mermaid diagram (`./alloy-di.mmd` by default) that captures scopes, lazy edges, and tokens for easy review.
+- **Visualize your DI graph** – enable the build plugin’s `visualize` option to emit a Mermaid diagram (`./alloy-di.mmd` by default) that captures scopes, lazy edges, and tokens for easy review.
 - **First-class lazy loading** – use `Lazy()` or provider-based lazy registrations to keep optional features in separate chunks.
-- **Framework agnostic** – works anywhere Vite runs: React, Vue, Svelte, SSR, libraries, and plain TS apps.
+- **Bundler support** – use the generated container from Vite, webpack, or Rspack applications.
 - **Type safe** – generates `serviceIdentifiers` and manifest declarations for precise inference.
 
 ## Install
@@ -51,13 +51,17 @@ pnpm add -D alloy-di
    const app = await container.get(serviceIdentifiers.AppService);
    ```
 
-> **Build tip:** The default Vite scaffold (`pnpm create vite@latest`) wires `"build": "tsc && vite build"`. Alloy writes its ambient declarations during `vite build`, so running `tsc` first can fail on fresh trees. Swap the order (`vite build && tsc`), or manually run `vite build` to generate the declarations first.
+> **Build tip:** The default Vite scaffold (`pnpm create vite@latest`) wires `"build": "tsc && vite build"`. Run `alloy generate` before type-checking so fresh checkouts and CI have Alloy's ambient declarations available, for example `"build": "alloy generate && tsc && vite build"`.
+
+By default Alloy scans `src` for decorated services. If your services live elsewhere, configure `sourceDirs` in the Vite plugin; `alloy generate` will reuse that config.
+
+Webpack and Rspack apps can use `alloy-di/webpack` or `alloy-di/rspack` with the same options. Run `alloy generate --bundler webpack` or `alloy generate --bundler rspack` before type-checking.
 
 Need manifests, providers, or testing utilities? See the docs site for complete guides.
 
 ## Visualize your dependency graph
 
-Enable the Vite plugin’s `visualize` option to have Alloy emit a Mermaid diagram that reflects every discovered service, scope, lazy edge, and token. By default the graph is written to `./alloy-di.mmd`, but you can customize the output path, color palette, or layout direction to fit your workflow.
+Enable the build plugin’s `visualize` option to have Alloy emit a Mermaid diagram that reflects every discovered service, scope, lazy edge, and token. By default the graph is written to `./alloy-di.mmd`, but you can customize the output path, color palette, or layout direction to fit your workflow.
 
 ```ts
 import { defineConfig } from "vite";
@@ -90,8 +94,9 @@ The site covers getting started, plugin options, manifest authoring, lazy loadin
 
 ## Examples in this repo
 
-- `packages/examples/app` – React + Vite app consuming decorated services, manifests, and providers.
+- `packages/examples/app-vite` – React + Vite app consuming decorated services, manifests, and providers.
+- `packages/examples/app-webpack-rspack` – the same React app source built with webpack and Rspack.
 - `packages/examples/library-internal` – monorepo library that emits `alloy.manifest.mjs` via the Rolldown plugin.
 - `packages/examples/library-external` – plain classes registered through providers.
 
-Clone the repo, run `pnpm install`, then `pnpm --filter @alloy-di/example-app dev` to explore.
+Clone the repo, run `pnpm install`, then `pnpm --filter @alloy-di/example-app-vite dev` to explore.

package/bin/alloy.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { runCli } from "../dist/cli.js";
+
+try {
+  await runCli();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/dist/cli.d.ts

@@ -0,0 +1,24 @@
+import { AlloyPluginOptions } from "./plugins/consumer-plugin.js";
+import { AlloyGenerateOptions, generate } from "./generate.js";
+//#region src/cli.d.ts
+type GenerateBundler = "vite" | "webpack" | "rspack" | "none";
+interface GenerateCliOptions {
+  root?: string;
+  configFile?: string;
+  bundler?: GenerateBundler;
+  mode?: string;
+  help?: boolean;
+}
+interface RunCliDependencies {
+  generate: typeof generate;
+  resolveGenerateOptions: typeof resolveGenerateOptions;
+  log: (message: string) => void;
+}
+declare function printUsage(log?: (message: string) => void): void;
+declare function readOptionValue(args: string[], index: number, optionName: string): string;
+declare function parseGenerateArgs(args: string[]): GenerateCliOptions;
+declare function getAlloyOptions(plugin: unknown): AlloyPluginOptions | undefined;
+declare function resolveGenerateOptions(cliOptions: GenerateCliOptions): Promise<AlloyGenerateOptions>;
+declare function runCli(args?: string[], deps?: RunCliDependencies): Promise<void>;
+//#endregion
+export { GenerateBundler, GenerateCliOptions, RunCliDependencies, getAlloyOptions, parseGenerateArgs, printUsage, readOptionValue, resolveGenerateOptions, runCli };

package/dist/cli.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+import { generate } from "./generate.js";
+import { ALLOY_PLUGIN_OPTIONS } from "./plugins/consumer-plugin.js";
+import { ALLOY_VITE_PLUGIN_OPTIONS } from "./plugins/vite-plugin/index.js";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+//#region src/cli.ts
+const defaultRunCliDependencies = {
+	generate,
+	resolveGenerateOptions,
+	log: (message) => console.log(message)
+};
+function printUsage(log = console.log) {
+	log(`Usage:
+  alloy generate [--root <dir>] [--config <file>] [--bundler <vite|webpack|rspack|none>] [--mode <mode>]
+
+Commands:
+  generate  Generate Alloy declaration files without bundling.
+
+Options:
+  --root    Project root. Defaults to the current working directory.
+  --config  Bundler config file to load. Pass "false" to skip config loading.
+  --bundler Config loader to use. Defaults to "vite" unless --config false is set.
+  --mode    Mode passed to webpack/Rspack config functions. Defaults to "production".`);
+}
+function readOptionValue(args, index, optionName) {
+	const value = args[index + 1];
+	if (!value || value.startsWith("-")) throw new Error(`[alloy] ${optionName} requires a value.`);
+	return value;
+}
+function parseGenerateArgs(args) {
+	const options = {};
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--root" || arg === "-r") {
+			options.root = readOptionValue(args, i, arg);
+			i++;
+		} else if (arg === "--config" || arg === "-c") {
+			options.configFile = readOptionValue(args, i, arg);
+			i++;
+		} else if (arg === "--bundler" || arg === "-b") {
+			const bundler = readOptionValue(args, i, arg);
+			if (bundler !== "vite" && bundler !== "webpack" && bundler !== "rspack" && bundler !== "none") throw new Error(`[alloy] --bundler must be one of "vite", "webpack", "rspack", or "none".`);
+			options.bundler = bundler;
+			i++;
+		} else if (arg === "--mode" || arg === "-m") {
+			options.mode = readOptionValue(args, i, arg);
+			i++;
+		} else if (arg === "--help" || arg === "-h") {
+			options.help = true;
+			return options;
+		} else throw new Error(`[alloy] Unknown option "${arg}".`);
+	}
+	return options;
+}
+function getAlloyOptions(plugin) {
+	if (!plugin || typeof plugin !== "object") return;
+	const candidate = plugin;
+	return candidate[ALLOY_PLUGIN_OPTIONS] ?? candidate[ALLOY_VITE_PLUGIN_OPTIONS];
+}
+async function resolveGenerateOptions(cliOptions) {
+	const root = cliOptions.root ? path.resolve(cliOptions.root) : process.cwd();
+	const bundler = resolveBundler(cliOptions);
+	if (bundler === "none") return { root };
+	if (bundler === "vite") return resolveViteGenerateOptions(cliOptions, root);
+	return resolveWebpackLikeGenerateOptions(cliOptions, root, bundler);
+}
+function resolveBundler(cliOptions) {
+	if (cliOptions.configFile === "false") return "none";
+	return cliOptions.bundler ?? "vite";
+}
+async function resolveViteGenerateOptions(cliOptions, root) {
+	let vite;
+	try {
+		vite = await import("vite");
+	} catch {
+		throw new Error("[alloy] Could not load Vite. Install vite or run with --config false and provide options programmatically.");
+	}
+	const inlineConfig = {
+		root,
+		configFile: cliOptions.configFile
+	};
+	const config = await vite.resolveConfig(inlineConfig, "build", "production", "production");
+	const alloyOptions = config.plugins.map((plugin) => getAlloyOptions(plugin)).find((options) => Boolean(options));
+	if (!alloyOptions) throw new Error("[alloy] Could not find alloy() in the resolved Vite plugins.");
+	return {
+		...alloyOptions,
+		root: config.root
+	};
+}
+async function resolveWebpackLikeGenerateOptions(cliOptions, root, bundler) {
+	const alloyOptions = normalizeWebpackLikeConfigs(await evaluateWebpackLikeConfig(await loadBundlerConfig(resolveBundlerConfigFile(root, bundler, cliOptions.configFile), bundler), cliOptions.mode)).flatMap((config) => Array.isArray(config.plugins) ? config.plugins : []).map((plugin) => getAlloyOptions(plugin)).find((options) => Boolean(options));
+	if (!alloyOptions) throw new Error(`[alloy] Could not find alloy() in the resolved ${bundlerLabel(bundler)} plugins.`);
+	return {
+		...alloyOptions,
+		root
+	};
+}
+function resolveBundlerConfigFile(root, bundler, configFile) {
+	if (configFile) return path.isAbsolute(configFile) ? configFile : path.resolve(root, configFile);
+	for (const extension of [
+		"js",
+		"mjs",
+		"cjs"
+	]) {
+		const candidate = path.resolve(root, `${bundler}.config.${extension}`);
+		try {
+			if (fsExists(candidate)) return candidate;
+		} catch {}
+	}
+	throw new Error(`[alloy] Could not find ${bundlerLabel(bundler)} config. Pass --config <file> or --config false.`);
+}
+function fsExists(filePath) {
+	return fs.existsSync(filePath);
+}
+async function loadBundlerConfig(configFile, bundler) {
+	if (/\.[cm]?ts$/i.test(configFile)) throw new Error(`[alloy] ${bundlerLabel(bundler)} TypeScript config loading is not supported by alloy generate yet. Use a JavaScript config wrapper or pass --config false.`);
+	try {
+		const imported = await import(pathToFileURL(configFile).href);
+		return imported.default ?? imported;
+	} catch (error) {
+		throw new Error(`[alloy] Could not load ${bundlerLabel(bundler)} config at ${configFile}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+	}
+}
+async function evaluateWebpackLikeConfig(config, mode = "production") {
+	if (typeof config !== "function") return config;
+	return config({
+		mode,
+		production: mode === "production"
+	}, {
+		mode,
+		env: { mode }
+	});
+}
+function normalizeWebpackLikeConfigs(config) {
+	return (Array.isArray(config) ? config : [config]).filter((candidate) => Boolean(candidate) && typeof candidate === "object");
+}
+function bundlerLabel(bundler) {
+	return bundler === "rspack" ? "Rspack" : "webpack";
+}
+async function runCli(args = process.argv.slice(2), deps = defaultRunCliDependencies) {
+	const [command, ...commandArgs] = args;
+	if (!command || command === "--help" || command === "-h") {
+		printUsage(deps.log);
+		return;
+	}
+	if (command !== "generate") throw new Error(`[alloy] Unknown command "${command}".`);
+	const cliOptions = parseGenerateArgs(commandArgs);
+	if (cliOptions.help) {
+		printUsage(deps.log);
+		return;
+	}
+	const options = await deps.resolveGenerateOptions(cliOptions);
+	const result = await deps.generate(options);
+	deps.log(`[alloy] Generated declarations for ${result.serviceCount} service(s) in ${result.declarationDir}.`);
+}
+function isMainModule() {
+	return process.argv[1] ? path.resolve(process.argv[1]) === fileURLToPath(import.meta.url) : false;
+}
+if (isMainModule()) try {
+	await runCli();
+} catch (error) {
+	console.error(error instanceof Error ? error.message : String(error));
+	process.exitCode = 1;
+}
+//#endregion
+export { getAlloyOptions, parseGenerateArgs, printUsage, readOptionValue, resolveGenerateOptions, runCli };

package/dist/generate.d.ts

@@ -0,0 +1,28 @@
+import { AlloyPluginOptions } from "./plugins/consumer-plugin.js";
+
+//#region src/generate.d.ts
+interface AlloyGenerateOptions extends AlloyPluginOptions {
+  /**
+   * Project root to scan. Defaults to `process.cwd()`.
+   */
+  root?: string;
+  /**
+   * Override the package name used for generated service identifier keys.
+   * Defaults to the nearest `package.json` name under `root`.
+   */
+  packageName?: string;
+}
+interface AlloyGenerateResult {
+  root: string;
+  declarationDir: string;
+  serviceCount: number;
+  manifestCount: number;
+}
+/**
+ * Generates Alloy's ambient TypeScript declarations without running a Vite
+ * build. This is intended for fresh checkouts and CI pipelines that type-check
+ * before bundling.
+ */
+declare function generate(options?: AlloyGenerateOptions): Promise<AlloyGenerateResult>;
+//#endregion
+export { AlloyGenerateOptions, AlloyGenerateResult, generate };

package/dist/generate.js

@@ -0,0 +1,46 @@
+import { normalizeImportPath } from "./plugins/core/utils.js";
+import { prepareContainerData, writeDeclarationArtifacts } from "./plugins/core/container-loader.js";
+import { DEFAULT_SOURCE_DIRS, createDiscoveryRuntimeForSourceDirs, readPackageName, toLazyServiceKey } from "./plugins/core/generation-inputs.js";
+import path from "node:path";
+//#region src/generate.ts
+/**
+* Generates Alloy's ambient TypeScript declarations without running a Vite
+* build. This is intended for fresh checkouts and CI pipelines that type-check
+* before bundling.
+*/
+async function generate(options = {}) {
+	const root = path.resolve(options.root ?? process.cwd());
+	const packageName = options.packageName ?? readPackageName(root);
+	const discoveryRuntime = createDiscoveryRuntimeForSourceDirs(root, options.sourceDirs ?? DEFAULT_SOURCE_DIRS, { factoryProviders: false });
+	const providerImportPaths = (options.providers ?? []).map((entry) => {
+		return normalizeImportPath(path.isAbsolute(entry) ? entry : path.resolve(root, entry));
+	});
+	const prepared = await prepareContainerData({
+		localMetas: Array.from(discoveryRuntime.discoveredClasses.values()),
+		lazyReferencedClassKeys: discoveryRuntime.lazyReferencedClassKeys,
+		manifests: options.manifests ?? [],
+		providerImportPaths,
+		factoryProviders: [],
+		lazyServiceKeys: new Set((options.lazyServices ?? []).map(toLazyServiceKey)),
+		packageName,
+		resolvedRoot: root,
+		containerDeclarationDir: options.containerDeclarationDir,
+		resolvedVisualization: null,
+		scopes: options.scopes
+	});
+	writeDeclarationArtifacts({
+		metas: prepared.metas,
+		loadedManifests: prepared.loadedManifests,
+		resolvedRoot: root,
+		containerDeclarationDir: options.containerDeclarationDir,
+		scopes: options.scopes
+	});
+	return {
+		root,
+		declarationDir: path.resolve(root, options.containerDeclarationDir ?? "./src"),
+		serviceCount: prepared.metas.length,
+		manifestCount: prepared.loadedManifests.length
+	};
+}
+//#endregion
+export { generate };

package/dist/lib/container.d.ts

@@ -1,8 +1,20 @@
 import { Constructor, Newable, Token } from "./types.js";
-import { ResolutionContext, ServiceScope } from "./scope.js";
 import { ServiceIdentifier } from "./service-identifiers.js";
+import { FactoryCacheEntry, FactoryPendingEntry, ResolutionContext, ServiceScope } from "./scope.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,17 +27,27 @@ 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;
   readonly parent: ResolutionContext | null;
   getCached(target: Constructor): unknown;
+  hasCached(target: Constructor): boolean;
   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.
    *
@@ -64,6 +86,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 +164,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 +213,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;
@@ -49,6 +53,9 @@ var Container = class {
 	getCached(target) {
 		return this.singletons.get(target);
 	}
+	hasCached(target) {
+		return this.singletons.has(target);
+	}
 	setCached(target, instance) {
 		this.singletons.set(target, instance);
 	}
@@ -67,6 +74,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 +151,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) {
@@ -150,8 +205,7 @@ var Container = class {
 	* @throws Error if a circular dependency is detected
 	*/
 	async resolve(target, resolutionStack, context) {
-		const overridden = this.instanceOverrides.get(target);
-		if (overridden) return overridden;
+		if (this.instanceOverrides.has(target)) return this.instanceOverrides.get(target);
 		if (resolutionStack.includes(target)) throw new DependencyResolutionError(`Circular dependency detected: ${[...resolutionStack.map((t) => t.name), target.name].join(" -> ")}`, {
 			target,
 			resolutionStack,
@@ -180,8 +234,7 @@ var Container = class {
 		return startingContext;
 	}
 	async resolveCached(target, metadata, resolutionStack, targetCtx) {
-		const cached = targetCtx.getCached(target);
-		if (cached) return cached;
+		if (targetCtx.hasCached(target)) return targetCtx.getCached(target);
 		const pending = targetCtx.getPending(target);
 		if (pending) return await pending;
 		const creation = this.createInstance(target, metadata.dependencies, resolutionStack, metadata.factory, targetCtx).then((instance) => {
@@ -292,7 +345,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 +353,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 +363,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/lazy.d.ts

@@ -14,6 +14,10 @@ interface Lazy<T> {
     factor?: number;
   };
 }
+/**
+ * Narrow an unknown value to a `Lazy` wrapper based on the hidden identifier symbol.
+ */
+declare function isLazy(value: unknown): value is Lazy<unknown>;
 /**
  * Helper type to extract the instance type from a Newable constructor.
  */
@@ -36,4 +40,4 @@ declare function Lazy<F extends () => Promise<Newable<any> | {
 }>>(importer: F, retry?: Lazy<any>["retry"]): Lazy<InferLazyType<F>>;
 declare function Lazy<T>(importer: Importer<T>, retry?: Lazy<T>["retry"]): Lazy<T>;
 //#endregion
-export { LAZY_IDENTIFIER, Lazy };
+export { LAZY_IDENTIFIER, Lazy, isLazy };