@fnioc/di 3.0.0 → 4.0.1

package/README.md

@@ -10,7 +10,7 @@ No decorators. No `reflect-metadata`. No runtime type introspection. Feed it str
 
 The entry point. `Root` is the root scope's name (the app-lifetime scope singletons bind to, default `"singleton"`); `Children` is the union of declarable child-scope names. Scopes are `Root | Children`. Transient (no cache, fresh instance on every resolve) is the default — there is no `"transient"` scope; the absence of `.as()` is what makes a registration transient.
 
-```typescript
+```ts
 import { DiBuilder } from "@fnioc/di";
 
 const services = new DiBuilder<"singleton", "request">();
@@ -22,7 +22,7 @@ Registration is append-only: each token holds a **list** of registrations in reg
 
 Register a concrete implementation against an interface token. The transformer rewrites `add<IFoo>(Foo)` to `add("pkg:IFoo", Foo)` at build time. Hand-fed consumers pass the token string directly.
 
-```typescript
+```ts
 // With transformer (author form):
 services.add<ILogger>(ConsoleLogger).as<"singleton">();
 services.add<IUserRepo>(SqlUserRepo).as<"request">();
@@ -38,13 +38,24 @@ The type constraint on `Concrete` is `new (...args: any[]) => Interface` — pla
 
 `.as<S>()` checks at compile time that `S` is a declared scope name. Passing an undeclared string is a type error.
 
+### `add<I>(Concrete, sig)` — registration-time signature override
+
+For third-party classes (ctor not editable) or generic instantiations the transformer cannot infer, supply a positional override array alongside the class:
+
+```ts
+add<ICache>(RedisCache, ["pkg:IRedisClient", undefined, "pkg:ILogger"]);
+```
+
+`sig` is `readonly (DepSlot | undefined)[]` — a positional sparse override over the transformer-generated signature. A `DepSlot` at a position overrides the generated token there; `undefined` keeps the generated token. Use explicit `undefined` rather than sparse elision (no-sparse-arrays).
+
+Pure token users (no transformer) supply a complete signature via `forCtor(C).signature(...)` instead.
+
 ### `add(token, { useFactory })` and `add(token, { useValue })`
 
 The same `add` surface also takes factory and value specs — registration paths that bypass the dep-metadata system entirely. Recommended for test doubles, third-party instances, and plugin-less consumers. Both return the builder for chaining.
 
-```typescript
-// Factory: receives the scope, returns the instance. An optional `scope`
-// caches the result at the matching ancestor (singleton-style).
+```ts
+// Factory: receives the scope, returns the instance.
 services.add("pkg:IDb", {
   useFactory: (c) => new PostgresDb(c.resolve<IConfig>("pkg:IConfig")),
   scope: "singleton",
@@ -58,7 +69,7 @@ services.add("pkg:ICache", {
 
 A `useFactory` with `scope: "singleton"` runs once and caches the result; without a `scope` it runs on every resolve (transient). `useValue` is always the same reference.
 
-To override a registration for a specific context (e.g. a test double), register a later spec for the same token on the `DiBuilder` before calling `build()`. The registration map is append-only and last-registration-wins, so a later `.add(token, ...)` / `.addFactory(token, ...)` / `.addValue(token, ...)` call shadows the earlier one without deleting it. The map seals at `build()` — no post-build mutation is possible.
+To override a registration for a specific context (e.g. a test double), register a later spec for the same token on the `DiBuilder` before calling `build()`. The registration map is append-only and last-registration-wins. The map seals at `build()` — no post-build mutation is possible.
 
 ---
 
@@ -66,7 +77,7 @@ To override a registration for a specific context (e.g. a test double), register
 
 Scopes form a parent-linked chain. The root scope is a real, app-lifetime object — minted by `build()`, never auto-created by the container. Child scopes nest from a scope via `createScope`.
 
-```typescript
+```ts
 const root = services.build();             // app lifetime — named by Root
 const req  = root.createScope("request");  // per HTTP request
 ```
@@ -89,7 +100,7 @@ const req  = root.createScope("request");  // per HTTP request
 
 The critical correctness rule: deps are resolved **relative to the scope that will own the instance**, not the scope that triggered the resolve.
 
-```typescript
+```ts
 const services = new DiBuilder<"singleton", "request">();
 services.add<ICache>(RedisCache).as<"singleton">();
 services.add<IUserContext>(HttpUserContext).as<"request">();
@@ -114,9 +125,9 @@ This mirrors `Microsoft.Extensions.DependencyInjection`'s scope-validation disci
 
 ## Greedy overload selection
 
-When a constructor has multiple registered signatures (stacked `@signature` decorators or chained `forCtor.signature()` calls), the engine selects by scanning **longest → shortest** and picking the first signature where every non-hole parameter token is satisfiable (registered in the container). Equal-arity ties break by registration order.
+When a constructor has multiple registered signatures (stacked `@signature` decorators or chained `forCtor.signature()` calls), the engine selects by scanning **longest → shortest** and picking the first signature where every resolvable parameter token is satisfiable (registered in the container). Equal-arity ties break by registration order.
 
-```typescript
+```ts
 // Two overloads: prefer the one with ILogger if available
 @signature("pkg:ILogger", "pkg:IDb")
 @signature("pkg:IDb")
@@ -144,7 +155,7 @@ Circular dependency detected:
 
 Closing a scope disposes the instances it owns in **reverse construction order**. Only instances implementing the native TC39 disposal contract are disposed.
 
-```typescript
+```ts
 // Sync disposal
 scope.dispose(): void
 
@@ -168,7 +179,7 @@ Instances owned by ancestor scopes are disposed when those scopes close, not whe
 
 The container never awaits. Async is expressed as `Promise<T>` values through the sync channel.
 
-```typescript
+```ts
 // Register an async factory
 services.add("pkg:IDb", {
   useFactory: async (c) => {
@@ -197,11 +208,11 @@ The transformer unwraps `Promise<X>` at dep-extraction: a parameter typed `Promi
 
 A constructor parameter whose type annotation is an inline function type returning a registered interface is injected as a **factory** — a callable that builds the target on demand — rather than a resolved instance.
 
-```typescript
+```ts
 // IDb is a registered class. This parameter receives a callable:
 constructor(makeDb: () => IDb) { ... }
 
-// Partial factory — the target ctor has holes the caller fills:
+// Partial factory — the caller fills caller-supplied params:
 constructor(makeRepo: (tableName: string) => IUserRepo) { ... }
 ```
 
@@ -209,7 +220,7 @@ constructor(makeRepo: (tableName: string) => IUserRepo) { ... }
 
 A **named** callable interface is NOT treated as a factory — it resolves as a normal service keyed on that interface's own token:
 
-```typescript
+```ts
 interface IDbFactory { (): IDb }
 
 // Resolves as the "pkg:IDbFactory" token, not a factory for IDb
@@ -218,13 +229,29 @@ constructor(dbFactory: IDbFactory) { ... }
 
 Name the interface to opt out of factory interpretation whenever your function-typed service should itself be a registered dep.
 
+### `resolveFactory(type, params?)`
+
+Resolve a factory callable for the token rather than an instance:
+
+```ts
+// Without params → strict zero-arg () => T; every slot must resolve from the container
+const makeDb = scope.resolveFactory("pkg:IDb");
+const db = makeDb(); // all deps resolved from container
+
+// With params → factory (...params) => T; named tokens filled by caller, rest from container
+const makeRepo = scope.resolveFactory("pkg:IUserRepo", ["app:tableName"]);
+const repo = makeRepo("users"); // tableName filled by caller; ILogger, IDb from container
+```
+
+`params` is the complete authored-order list of caller-supplied token strings, matched by token (first-occurrence, left-to-right). Passing `params` pins the factory's shape — it no longer drifts as registration state changes.
+
 ### Partial / positional factories
 
-The injected callable exposes **only the target constructor's unregistered parameters**, in their relative order. Registered deps are resolved by the container at call time; holes and unregistered params are filled positionally by caller-supplied arguments.
+The injected callable exposes **only the target constructor's caller-supplied parameters**, in their relative order. Registered deps are resolved by the container at call time.
 
-```typescript
+```ts
 // IUserRepo concrete: constructor(log: ILogger, tableName: string, db: IDb)
-// ILogger and IDb are registered; tableName is not (a hole).
+// ILogger and IDb are registered; tableName is not registered (caller-supplied).
 // Injected factory type: (tableName: string) => IUserRepo
 
 class RequestHandler {
@@ -237,7 +264,7 @@ class RequestHandler {
 }
 ```
 
-There are no Ramda-style placeholders. The factory's call arity is exactly the count of unregistered parameters; the caller never sees the full constructor shape.
+There are no Ramda-style placeholders. The factory's call arity is exactly the count of caller-supplied parameters; the caller never sees the full constructor shape.
 
 ### Lifetime semantics
 
@@ -245,10 +272,10 @@ The injected factory is a closure captured at injection time, referencing the ow
 
 | Factory kind | Lifetime behavior |
 |---|---|
-| **Zero-arg** (`() => IFoo`, no holes or unregistered params) | Routes through normal `resolve` — respects the target's registered lifetime. A singleton target returns the same instance on every call; a transient target yields a fresh one. |
-| **Parameterized** (caller args fill holes or unregistered params) | Builds a **fresh instance on every call**, bypassing the instance cache. Caller args differ per invocation, so caching would be wrong — two calls with different arguments must not collapse to one cached instance. |
+| **Zero-arg** (`() => IFoo`, no caller-supplied params) | Routes through normal `resolve` — respects the target's registered lifetime. A singleton target returns the same instance on every call; a transient target yields a fresh one. |
+| **Parameterized** (caller args fill caller-supplied params) | Builds a **fresh instance on every call**, bypassing the instance cache. Caller args differ per invocation, so caching would be wrong — two calls with different arguments must not collapse to one cached instance. |
 
-The captive-dependency rule (§5.4) holds at call time: the target's own deps are resolved relative to the scope that owns the factory-holding instance. A factory captured by a singleton that tries to build a request-scoped target still throws `MissingScopeError` when invoked.
+The captive-dependency rule holds at call time: the target's own deps are resolved relative to the scope that owns the factory-holding instance. A factory captured by a singleton that tries to build a request-scoped target still throws `MissingScopeError` when invoked.
 
 ### `FactoryTargetError`
 
@@ -263,6 +290,23 @@ Note: `FactoryTargetError` is thrown when the factory callable is constructed (a
 
 ---
 
+## Union slots
+
+A `Union` dep slot tries each member in declaration order and resolves to the first registered one. Throw if none resolves.
+
+```ts
+import { union } from "@fnioc/di";
+
+forCtor(Handler).signature(
+  union("pkg:IRedis", "pkg:IMemoryCache"),
+  "pkg:ILogger",
+);
+```
+
+Token users construct `Union` slots with `union(...)`. Transformer users write an inline `A | B` annotation and the transformer lowers it automatically. See [`@fnioc/transformer`](../transformer/README.md) for the named-vs-inline distinction.
+
+---
+
 ## API reference
 
 ### `DiBuilder<Root, Children>`
@@ -270,7 +314,8 @@ Note: `FactoryTargetError` is thrown when the factory callable is constructed (a
 | Member | Signature | Description |
 |---|---|---|
 | `add<I>(Concrete)` | `(ctor: new (...) => I) => AddBuilder` | Register a concrete class against interface `I`. |
-| `.as<S>()` | `(scope: S) → void` | Set the lifetime scope. No call → transient. |
+| `add<I>(Concrete, sig)` | `(ctor, sig: readonly (DepSlot \| undefined)[]) => AddBuilder` | Register with a positional signature override. |
+| `.as<S>()` | `(scope: S) => void` | Set the lifetime scope. No call → transient. |
 | `add(token, ctor)` | `(token: string, ctor) => AddBuilder` | Class registration (lowered form). |
 | `addFactory(token, factory)` | `(token: string, factory: (sp: Resolver) => T) => AddBuilder` | Factory registration. No dep metadata required — the factory receives the live `Resolver`. |
 | `addValue(token, value)` | `(token: string, value: unknown) => void` | Value registration. A pre-built instance, re-used as-is. |
@@ -283,7 +328,7 @@ Implements `Resolver` + `ScopeFactory` + `Disposable` / `AsyncDisposable`.
 | Member | Signature | Description |
 |---|---|---|
 | `resolve<T>(token)` | `(token: string) => T` | Resolve an instance. Throws on captive-dep violation, missing scope ancestor, or cycle. |
-| `resolveFactory(token)` | `(token: string) => (...args) => T` | Resolve a factory callable for the token rather than an instance. |
+| `resolveFactory(type, params?)` | `(type: string, params?: readonly string[]) => (...args) => T` | Resolve a factory callable. Without `params`, strict zero-arg `() => T`; with `params`, `(...params) => T` matched by token. |
 | `createScope(name)` | `(name: Scopes) => ServiceProvider<Scopes>` | Create a nested child scope. |
 | `dispose()` | `() => void` | Sync close. Throws if any owned instance has async-only disposal. |
 | `disposeAsync()` | `() => Promise<void>` | Async close. |

package/dist/index.d.ts

@@ -5,24 +5,6 @@ interface Ctor$1<in Args extends readonly any[] = any[], out Instance = any> {
   prototype: Instance;
 }
 
-/**
- * The hole sentinel: marks a constructor parameter as caller-supplied rather
- * than container-resolved.
- *
- * Used in signatures to communicate "this position is a hole — the factory
- * caller supplies this argument, not the DI container." Detected by identity
- * (`slot === hole`), and `null` is the sentinel value: it is exactly what the
- * transformer emits for a hole slot, so the authoring surface and the lowered
- * output agree on one representation.
- *
- * @example
- * ```ts
- * @signature("pkg:ILogger", hole, "pkg:IDb")
- * class SqlRepo { constructor(log: ILogger, tableName: string, db: IDb) { ... } }
- * ```
- */
-declare const hole: null;
-
 /**
  * Anything dependency metadata can be attached to: a class constructor (its
  * deps are the ctor parameters) or a factory function (its deps are the call
@@ -40,12 +22,16 @@ type DepTarget = Ctor$1 | Func$1<never[], unknown>;
 type Token = string;
 /**
  * Marks a constructor parameter to be injected as a *factory* producing the
- * registered token `factory`, rather than a resolved instance. The factory's
- * own call signature is the target ctor's unregistered params, partitioned at
- * resolve time.
+ * registered type token, rather than a resolved instance. The factory's own
+ * call signature is determined by the caller-supplied `params` list.
+ *
+ * `type` is the token of the produced type T (replaces the former `.factory` field).
+ * `params` is the complete, authored-order list of caller-supplied parameter tokens;
+ * when present it pins the factory shape so it no longer drifts with registration state.
  */
 interface FactoryRef {
-    readonly factory: Token;
+    readonly type: Token;
+    readonly params?: readonly Token[];
 }
 /**
  * Marks a parameter to be injected with the live resolution scope itself,
@@ -58,20 +44,28 @@ interface FactoryRef {
 interface ScopeRef {
     readonly scope: true;
 }
+/**
+ * A set of alternative dependency slots tried in declaration order (first
+ * resolvable member wins). If no member is resolvable, resolution throws.
+ * Each member is itself a `DepSlot` — nesting is allowed.
+ */
+interface Union {
+    readonly union: readonly DepSlot[];
+}
 /**
  * One positional slot in a constructor / factory signature:
  *   - a `Token` string  — a container-resolved dependency,
- *   - the `hole` sentinel — a caller-supplied parameter,
- *   - a `FactoryRef` — a factory-injected parameter (see `FactoryRef`), or
- *   - a `ScopeRef` — the live resolution scope (see `ScopeRef`).
+ *   - a `FactoryRef`    — a factory-injected parameter (see `FactoryRef`),
+ *   - a `ScopeRef`      — the live resolution scope (see `ScopeRef`), or
+ *   - a `Union`         — member-level alternatives tried in order.
  */
-type DepSlot = Token | typeof hole | FactoryRef | ScopeRef;
+type DepSlot = Token | FactoryRef | ScopeRef | Union;
 /**
  * Per-constructor dependency metadata stored in the global WeakMap.
  *
  * `signatures` is an array of arrays: each element is one constructor signature
- * (for overload support). `signatures[i][j]` is the `DepSlot` — a token, the
- * `hole` sentinel, or a `FactoryRef` — for constructor parameter `j` of
+ * (for overload support). `signatures[i][j]` is the `DepSlot` — a token, a
+ * `FactoryRef`, a `ScopeRef`, or a `Union` — for constructor parameter `j` of
  * overload `i`.
  */
 interface DepRecord {
@@ -92,7 +86,7 @@ interface DepRecord {
  *                   prototype-chain walk — subclasses do NOT inherit the
  *                   parent's record).
  * @param signatures An array of signatures; each signature is a positional array
- *                   of DepSlot (Token | hole | FactoryRef | ScopeRef) parallel to
+ *                   of DepSlot (Token | FactoryRef | ScopeRef | Union) parallel to
  *                   the target's parameter list.
  */
 declare function defineDeps(target: DepTarget, signatures: readonly (readonly DepSlot[])[]): void;
@@ -126,8 +120,8 @@ declare function signature(...tokens: readonly DepSlot[]): Func$1<[Ctor$1, Class
 interface ForCtorBuilder {
     /**
      * Appends one constructor signature (a positional array of DepSlot —
-     * Token | hole | FactoryRef) to the ctor's dependency metadata. Returns
-     * `this` for chaining.
+     * Token | FactoryRef | ScopeRef | Union) to the ctor's dependency metadata.
+     * Returns `this` for chaining.
      *
      * Each `.signature(...)` call is one overload. Chaining two calls is
      * equivalent to stacking two `@signature` decorators.
@@ -147,6 +141,44 @@ interface ForCtorBuilder {
  */
 declare function forCtor(ctor: Ctor$1): ForCtorBuilder;
 
+/**
+ * @fnioc/core — the immutable substrate and dependency-metadata format.
+ *
+ * Exports:
+ *   - `Token`          — string alias for a DI key
+ *   - `FactoryRef`     — marks a signature slot as a factory-injected parameter
+ *   - `ScopeRef`       — marks a signature slot as the live resolution scope
+ *   - `Union`          — member-level alternative slots tried in declaration order
+ *   - `DepSlot`        — one positional slot: Token | FactoryRef | ScopeRef | Union
+ *   - `Inject`         — compile-time brand that pins a token for one arg
+ *   - `DepTarget`      — a ctor or factory function metadata attaches to
+ *   - `DepRecord`      — shape of per-constructor metadata in the WeakMap
+ *   - `defineDeps`     — the single write path into the global WeakMap
+ *   - `getDeps`        — the read path (consumed by @fnioc/di)
+ *   - `union`          — runtime helper: constructs a Union slot from member slots
+ *   - `isFactoryRef`   — type guard for FactoryRef slots
+ *   - `isScopeRef`     — type guard for ScopeRef slots
+ *   - `isUnionSlot`    — type guard for Union slots
+ *   - `signature`      — TC39 class decorator factory
+ *   - `ForCtorBuilder` — return type of `forCtor`
+ *   - `forCtor`        — fluent free-function for third-party classes
+ */
+
+/**
+ * Constructs a `Union` slot — a set of alternative dependency slots tried in
+ * declaration order. The first resolvable member wins; if none is resolvable,
+ * resolution throws.
+ *
+ * @example
+ * ```ts
+ * forCtor(Handler).signature(
+ *   union("pkg:IRedis", "pkg:IMemoryCache"),
+ *   "pkg:ILogger",
+ * );
+ * ```
+ */
+declare function union(...slots: DepSlot[]): Union;
+
 type Func<in Args extends readonly any[] = any[], out Return = any> = (...args: Args) => Return;
 
 interface Ctor<in Args extends readonly any[] = any[], out Instance = any> {
@@ -217,11 +249,14 @@ interface Resolver {
     resolve<T>(token: Token): T;
     resolve(token: Token): unknown;
     /**
-     * Returns a FACTORY for the token rather than an instance — the resolve-site
-     * mirror of a `FactoryRef` ctor param. The authored `resolve<(a: A) => T>()`
-     * (a function-typed type arg) lowers to this.
+     * Returns a FACTORY for `type` rather than an instance. When `params` is
+     * absent or empty, returns a strict zero-arg `() => T` — every ctor slot must
+     * resolve from the container. When `params` is present, it is the complete
+     * authored-order list of caller-supplied parameter tokens; the returned factory
+     * has shape `(...params) => T`. The authored `resolve<(a: A) => T>()` lowers
+     * to `resolveFactory("pkg:T", ["pkg:A"])`.
      */
-    resolveFactory(token: Token): unknown;
+    resolveFactory(type: Token, params?: readonly Token[]): unknown;
 }
 /**
  * The scope-creation surface. Injected into factory parameters typed
@@ -313,14 +348,14 @@ declare class ServiceProvider<S extends string = string> implements Resolver, Sc
     resolve<T>(token: Token): T;
     resolve(token: Token): unknown;
     /**
-     * Returns a FACTORY for `token` rather than an instance — the resolve-site
-     * mirror of a `FactoryRef` ctor param. The authored `resolve<(a: A) => T>()`
-     * lowers here. The returned callable exposes the target's UNREGISTERED /
-     * caller-supplied parameters in order (PRD §7 "Partial / positional
-     * factories"); a fully-resolvable target yields a zero-arg lazy factory that
-     * respects the target's registered lifetime.
+     * Returns a FACTORY for `type` rather than an instance. When `params` is
+     * absent or empty, returns a strict zero-arg `() => T` — every ctor slot must
+     * resolve from the container (an unresolvable slot throws). When `params` is
+     * present, it is the complete authored-order list of caller-supplied parameter
+     * tokens; the returned factory has shape `(...params) => T`. The authored
+     * `resolve<(a: A) => T>()` lowers to `resolveFactory("pkg:T", ["pkg:A"])`.
      */
-    resolveFactory(token: Token): unknown;
+    resolveFactory(type: Token, params?: readonly Token[]): unknown;
     /**
      * Returns the most-recent registration for `token` from the sealed map.
      * The sealed map is shared across all providers in the tree; local overrides
@@ -375,32 +410,45 @@ declare class ServiceProvider<S extends string = string> implements Resolver, Sc
     /**
      * Builds the callable injected for a `FactoryRef` parameter.
      *
-     * The target ctor's signature is partitioned at CALL time against the live
-     * registration map: each slot that is a registered token is resolved; each
-     * slot that is an unregistered token or a `hole` takes the next
-     * caller-supplied argument, positionally. The injected callable therefore
-     * exposes only the target's unregistered parameters, in their relative order.
+     * When `ref.params` is absent or empty, the factory is STRICT: every ctor slot
+     * of the target must resolve from the container. An unresolvable slot throws at
+     * build time (via `selectSignature`). The result is a zero-arg `() => T` that
+     * respects the target's registered lifetime.
+     *
+     * When `ref.params` is present, it is the COMPLETE authored-order list of
+     * caller-supplied parameter tokens. The caller-supplied set is pinned to those
+     * tokens (by first-occurrence left-to-right matching against ctor slots). A
+     * slot token that appears in `params` is caller-supplied even if it is also
+     * registered (caller wins). A slot that is neither claimed by `params` nor
+     * resolvable from the container → error. The factory shape is exactly
+     * `(...params) => T`; a fresh instance is built on every call (bypassing the
+     * instance cache — caller args differ per call so caching would be wrong).
      *
      * Lifetime semantics:
-     *   - A ZERO-ARG factory routes through the normal `resolve` path, so it
-     *     RESPECTS the target's registered lifetime.
-     *   - A PARAMETERIZED factory constructs a FRESH instance on every call and
-     *     BYPASSES the instance cache. Caller args differ per call, so caching
-     *     would be wrong.
+     *   - A ZERO-ARG (no-params) factory routes through the normal `resolve` path
+     *     and RESPECTS the target's registered lifetime.
+     *   - A PARAMETERIZED factory constructs a FRESH instance every call.
      *
      * The closure captures `owningFrame`. §5.4 holds at call time: the target's
      * deps resolve relative to the scope that owns the factory-holding instance.
      */
     private makeFactory;
     /**
-     * Builds a factory target, partitioning its already-selected signature
-     * against the live registration map: a registered token is resolved; a
-     * `ScopeRef` is the live provider view; a `FactoryRef` is injected; an
-     * unregistered token or a `hole` takes the next caller-supplied argument
-     * positionally. A class target is `new`ed, a factory target is called.
-     * Always a fresh result — a parameterized factory bypasses the instance cache.
-     * Runs on a fresh cycle stack since the factory is invoked outside the
+     * Builds a factory target with the params-driven caller-supplied partition.
+     *
+     * `callerParams` is the authored-order list of tokens whose values are
+     * supplied by the caller (from the `FactoryRef.params` list). Each ctor slot
+     * whose token appears in `callerParams` (first-occurrence left-to-right match)
+     * takes the corresponding `callArgs` value; every other slot resolves from the
+     * container. A slot that is neither claimed nor resolvable → error (the factory
+     * cannot be built). A claimed slot that is also registered → caller wins.
+     *
+     * Always builds a fresh result — a parameterized factory bypasses the instance
+     * cache. Runs on a fresh cycle stack since the factory is invoked outside the
      * original resolve.
+     *
+     * `signature` may be `undefined` when the target has no DepRecord (zero-arg
+     * ctor or record-less factory) — in that case args is empty.
      */
     private buildPartitioned;
     /**
@@ -408,12 +456,12 @@ declare class ServiceProvider<S extends string = string> implements Resolver, Sc
      * the first SATISFIABLE one. A slot is satisfiable when it is:
      *
      *   - a `FactoryRef` — always satisfiable; injected as a callable;
-     *   - a `ScopeRef` — always satisfiable; filled with the live provider view; or
+     *   - a `ScopeRef` — always satisfiable; filled with the live provider view;
+     *   - a `Union` — satisfiable iff at least one member is resolvable; or
      *   - a string token whose registration exists in the sealed map.
      *
-     * A `hole` (`null`) is NOT satisfiable on a direct resolve. An unregistered
-     * string token is also not satisfiable. Equal-arity ties break by registration
-     * order. None satisfiable ⇒ throw naming the unsatisfiable tokens.
+     * An unregistered string token is not satisfiable. Equal-arity ties break by
+     * registration order. None satisfiable ⇒ throw naming the unsatisfiable tokens.
      */
     private selectSignature;
     /**
@@ -425,11 +473,29 @@ declare class ServiceProvider<S extends string = string> implements Resolver, Sc
      */
     private selectTargetSignature;
     /**
-     * True when `slot` is a registered string token in the sealed map. A hole
-     * (`null`), `FactoryRef`, or `ScopeRef` is not a registered token, so it is
-     * never "resolvable" in this sense.
+     * True when `slot` is a registered string token in the sealed map. A
+     * `FactoryRef`, `ScopeRef`, or `Union` is not tested here — use
+     * `isResolvableSlot` for a full slot check.
      */
     private isResolvable;
+    /**
+     * True when a slot is resolvable in ANY form:
+     *   - `FactoryRef` / `ScopeRef` — always satisfiable (injected);
+     *   - `Union` — satisfiable iff at least one member is resolvable (recursive);
+     *   - string token — registered in the sealed map.
+     */
+    private isResolvableSlot;
+    /**
+     * Resolves a `Union` slot: tries each member in declaration order and returns
+     * the first resolvable one. If no member is resolvable, throws
+     * `NoSatisfiableUnionError`.
+     */
+    private resolveUnion;
+    /**
+     * Resolves a single `DepSlot` to its value, dispatching on slot kind.
+     * Used by `resolveUnion` to recurse into members.
+     */
+    private resolveSlot;
     /**
      * Closes this provider synchronously, disposing the instances its scope frame
      * owns in REVERSE construction order. Only native `Disposable` instances are
@@ -620,6 +686,14 @@ declare class FactoryTargetError extends DiError {
     readonly reason: "unregistered" | "not-a-class";
     constructor(factoryToken: Token, reason: "unregistered" | "not-a-class");
 }
+/**
+ * A `Union` slot was encountered during resolution but none of its member slots
+ * was resolvable. Resolution cannot proceed without at least one registered member.
+ */
+declare class NoSatisfiableUnionError extends DiError {
+    readonly members: readonly DepSlot[];
+    constructor(members: readonly DepSlot[]);
+}
 /**
  * Sync `dispose()` was called on a scope that owns a Promise-valued (thenable)
  * cached instance. A pending Promise cannot be disposed synchronously — the
@@ -629,5 +703,5 @@ declare class AsyncDisposalRequiredError extends DiError {
     constructor();
 }
 
-export { AsyncDisposalRequiredError, CircularDependencyError, DiBuilder, DiError, FactoryTargetError, MissingMetadataError, MissingScopeError, NoSatisfiableSignatureError, Scope, ServiceProvider, UnregisteredTokenError, defineDeps, forCtor, hole, signature };
-export type { AddBuilder, ClassRegistration, Ctor, DepRecord, Factory, FactoryRegistration, ForCtorBuilder, Lifetime, Registration, ResolveScope, Resolver, ScopeFactory, Token, ValueRegistration };
+export { AsyncDisposalRequiredError, CircularDependencyError, DiBuilder, DiError, FactoryTargetError, MissingMetadataError, MissingScopeError, NoSatisfiableSignatureError, NoSatisfiableUnionError, Scope, ServiceProvider, UnregisteredTokenError, defineDeps, forCtor, signature, union };
+export type { AddBuilder, ClassRegistration, Ctor, DepRecord, Factory, FactoryRegistration, ForCtorBuilder, Lifetime, Registration, ResolveScope, Resolver, ScopeFactory, Token, Union, ValueRegistration };

package/dist/index.js

@@ -1,26 +1,54 @@
 // ../core/src/store.ts
-var hole = null;
 var GLOBAL_KEY = Symbol.for("fnioc:deps");
 var globals = globalThis;
 var store = globals[GLOBAL_KEY] ??= new Map;
+
 // ../core/src/defineDeps.ts
 function isFactoryRef(slot) {
-  return typeof slot === "object" && slot !== null && typeof slot.factory === "string";
+  return typeof slot === "object" && slot !== null && typeof slot.type === "string";
 }
 function isScopeRef(slot) {
   return typeof slot === "object" && slot !== null && slot.scope === true;
 }
+function isUnionSlot(slot) {
+  return typeof slot === "object" && slot !== null && Array.isArray(slot.union);
+}
 function slotsEqual(a, b) {
   const aIsRef = isFactoryRef(a);
   const bIsRef = isFactoryRef(b);
   if (aIsRef || bIsRef) {
-    return aIsRef && bIsRef && a.factory === b.factory;
+    if (!aIsRef || !bIsRef)
+      return false;
+    if (a.type !== b.type)
+      return false;
+    const aParams = a.params ?? [];
+    const bParams = b.params ?? [];
+    if (aParams.length !== bParams.length)
+      return false;
+    for (let i = 0;i < aParams.length; i++) {
+      if (aParams[i] !== bParams[i])
+        return false;
+    }
+    return true;
   }
   const aIsScope = isScopeRef(a);
   const bIsScope = isScopeRef(b);
   if (aIsScope || bIsScope) {
     return aIsScope && bIsScope;
   }
+  const aIsUnion = isUnionSlot(a);
+  const bIsUnion = isUnionSlot(b);
+  if (aIsUnion || bIsUnion) {
+    if (!aIsUnion || !bIsUnion)
+      return false;
+    if (a.union.length !== b.union.length)
+      return false;
+    for (let i = 0;i < a.union.length; i++) {
+      if (!slotsEqual(a.union[i], b.union[i]))
+        return false;
+    }
+    return true;
+  }
   return a === b;
 }
 function signaturesEqual(a, b) {
@@ -65,6 +93,12 @@ function forCtor(ctor) {
   };
   return builder;
 }
+
+// ../core/src/index.ts
+function union(...slots) {
+  return { union: slots };
+}
+
 // src/errors.ts
 class DiError extends Error {
   constructor(message) {
@@ -134,6 +168,15 @@ class FactoryTargetError extends DiError {
   }
 }
 
+class NoSatisfiableUnionError extends DiError {
+  members;
+  constructor(members) {
+    const memberList = members.map((m) => typeof m === "string" ? `"${m}"` : JSON.stringify(m)).join(", ");
+    super(`No satisfiable union member found. Tried: [${memberList}]. ` + `Register at least one of the union members before resolving.`);
+    this.members = members;
+  }
+}
+
 class AsyncDisposalRequiredError extends DiError {
   constructor() {
     super(`Cannot dispose synchronously: this scope owns a Promise-valued ` + `instance (an async useFactory result). Awaiting it is required ` + `before disposal — call disposeAsync() instead of dispose().`);
@@ -150,12 +193,9 @@ function isAsyncDisposable(value) {
 function isThenable(value) {
   return value != null && (typeof value === "object" || typeof value === "function") && typeof value.then === "function";
 }
-function isFactoryRef2(slot) {
-  return slot !== null && typeof slot === "object" && typeof slot.factory === "string";
-}
-function isScopeRef2(slot) {
-  return slot !== null && typeof slot === "object" && slot.scope === true;
-}
+var isFactoryRef2 = isFactoryRef;
+var isScopeRef2 = isScopeRef;
+var isUnion = isUnionSlot;
 
 class Scope {
   name;
@@ -193,8 +233,8 @@ class ServiceProvider {
     }
     return this.resolveWith(token, this.frame, []);
   }
-  resolveFactory(token) {
-    return this.makeFactory({ factory: token }, this.frame);
+  resolveFactory(type, params) {
+    return this.makeFactory({ type, params }, this.frame);
   }
   lookup(token) {
     const list = this.registrations.get(token);
@@ -269,7 +309,7 @@ class ServiceProvider {
         }
         return sp.resolveWith(depToken, owningFrame, stack);
       },
-      resolveFactory: (depToken) => sp.makeFactory({ factory: depToken }, owningFrame),
+      resolveFactory: (depToken, depParams) => sp.makeFactory({ type: depToken, params: depParams }, owningFrame),
       createScope: (...args) => {
         const name = args[0] ?? "scoped";
         const childFrame = new Scope(name, owningFrame);
@@ -289,6 +329,8 @@ class ServiceProvider {
         return providerView;
       if (isFactoryRef2(slot))
         return this.makeFactory(slot, owningFrame);
+      if (isUnion(slot))
+        return this.resolveUnion(slot, owningFrame, stack);
       return this.resolveWith(slot, owningFrame, stack);
     });
     return factory(...args);
@@ -310,41 +352,56 @@ class ServiceProvider {
       if (isFactoryRef2(slot)) {
         return this.makeFactory(slot, owningFrame);
       }
+      if (isUnion(slot)) {
+        return this.resolveUnion(slot, owningFrame, stack);
+      }
       return this.resolveWith(slot, owningFrame, stack);
     });
     return new ctor(...args);
   }
   makeFactory(ref, owningFrame) {
     const sp = this;
-    const target = this.lookup(ref.factory);
+    const target = this.lookup(ref.type);
     if (target === undefined) {
-      throw new FactoryTargetError(ref.factory, "unregistered");
+      throw new FactoryTargetError(ref.type, "unregistered");
     }
     if (target.kind === "value") {
-      return () => sp.resolveWith(ref.factory, owningFrame, []);
+      return () => sp.resolveWith(ref.type, owningFrame, []);
+    }
+    const callerParams = ref.params !== undefined && ref.params.length > 0 ? ref.params : undefined;
+    if (callerParams === undefined) {
+      return () => sp.resolveWith(ref.type, owningFrame, []);
     }
     const depTarget = target.kind === "class" ? target.ctor : target.factory;
     const record = getDeps(depTarget);
     const targetSignature = record === undefined || record.signatures.length === 0 ? undefined : sp.selectTargetSignature(record.signatures);
-    const parameterized = targetSignature !== undefined && targetSignature.some((slot) => !isFactoryRef2(slot) && !isScopeRef2(slot) && !sp.isResolvable(slot));
-    if (!parameterized) {
-      return () => sp.resolveWith(ref.factory, owningFrame, []);
-    }
-    return (...callArgs) => sp.buildPartitioned(target, targetSignature, callArgs, owningFrame);
+    return (...callArgs) => sp.buildPartitioned(target, targetSignature, callerParams, callArgs, owningFrame);
   }
-  buildPartitioned(target, signature2, callerArgs, owningFrame) {
+  buildPartitioned(target, signature2, callerParams, callArgs, owningFrame) {
     const stack = [];
     const providerView = this.makeProviderView(owningFrame, stack);
-    let nextCallerArg = 0;
+    if (signature2 === undefined || signature2.length === 0) {
+      return target.kind === "class" ? new target.ctor : target.factory(providerView);
+    }
+    const remainingParamIndices = callerParams.map((_, i) => i);
     const args = signature2.map((slot) => {
       if (isScopeRef2(slot))
         return providerView;
       if (isFactoryRef2(slot))
         return this.makeFactory(slot, owningFrame);
-      if (!this.isResolvable(slot)) {
-        return callerArgs[nextCallerArg++];
+      if (isUnion(slot))
+        return this.resolveUnion(slot, owningFrame, stack);
+      const token = slot;
+      const matchIdx = remainingParamIndices.findIndex((pi) => callerParams[pi] === token);
+      if (matchIdx !== -1) {
+        const paramIdx = remainingParamIndices[matchIdx];
+        remainingParamIndices.splice(matchIdx, 1);
+        return callArgs[paramIdx];
       }
-      return this.resolveWith(slot, owningFrame, stack);
+      if (!this.isResolvable(token)) {
+        throw new NoSatisfiableSignatureError(token, token, [token]);
+      }
+      return this.resolveWith(token, owningFrame, stack);
     });
     return target.kind === "class" ? new target.ctor(...args) : target.factory(...args);
   }
@@ -356,6 +413,12 @@ class ServiceProvider {
       for (const slot of sig) {
         if (isFactoryRef2(slot) || isScopeRef2(slot))
           continue;
+        if (isUnion(slot)) {
+          if (!this.isResolvableSlot(slot)) {
+            satisfiable = false;
+          }
+          continue;
+        }
         if (!this.isResolvable(slot)) {
           satisfiable = false;
           if (typeof slot === "string")
@@ -373,6 +436,31 @@ class ServiceProvider {
   isResolvable(slot) {
     return typeof slot === "string" && this.lookup(slot) !== undefined;
   }
+  isResolvableSlot(slot) {
+    if (isFactoryRef2(slot) || isScopeRef2(slot))
+      return true;
+    if (isUnion(slot)) {
+      return slot.union.some((member) => this.isResolvableSlot(member));
+    }
+    return this.isResolvable(slot);
+  }
+  resolveUnion(slot, owningFrame, stack) {
+    for (const member of slot.union) {
+      if (this.isResolvableSlot(member)) {
+        return this.resolveSlot(member, owningFrame, stack);
+      }
+    }
+    throw new NoSatisfiableUnionError(slot.union);
+  }
+  resolveSlot(slot, owningFrame, stack) {
+    if (isScopeRef2(slot))
+      return this.makeProviderView(owningFrame, stack);
+    if (isFactoryRef2(slot))
+      return this.makeFactory(slot, owningFrame);
+    if (isUnion(slot))
+      return this.resolveUnion(slot, owningFrame, stack);
+    return this.resolveWith(slot, owningFrame, stack);
+  }
   dispose() {
     if (this.disposed)
       return;
@@ -486,13 +574,14 @@ class DiBuilder {
   }
 }
 export {
+  union,
   signature,
-  hole,
   forCtor,
   defineDeps,
   UnregisteredTokenError,
   ServiceProvider,
   Scope,
+  NoSatisfiableUnionError,
   NoSatisfiableSignatureError,
   MissingScopeError,
   MissingMetadataError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fnioc/di",
-  "version": "3.0.0",
+  "version": "4.0.1",
   "description": "The ioc runtime engine: DiBuilder, scopes, resolution, captive-dependency protection, factories, and native disposal.",
   "keywords": [
     "dependency-injection",
@@ -21,6 +21,7 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"