@fnioc/di 1.0.0

package/README.md

@@ -0,0 +1,294 @@
+# @fnioc/di
+
+The runtime engine for `ioc`. Resolves dependency graphs, manages scope lifetimes, enforces captive-dependency correctness, and drives native disposal.
+
+No decorators. No `reflect-metadata`. No runtime type introspection. Feed it string tokens and dep arrays (generated by `@fnioc/transformer` or written by hand via `@fnioc/core`'s authoring surfaces) and it handles the rest.
+
+---
+
+## `DiBuilder<Scopes>`
+
+The entry point. `Scopes` is your string union of scope names. Transient (no cache, fresh instance on every resolve) is the default — there is no `"transient"` tag; the absence of `.as()` is what makes a registration transient.
+
+```typescript
+import { DiBuilder } from "@fnioc/di";
+
+const services = new DiBuilder<"singleton" | "request">();
+```
+
+### `.add<Interface>(Concrete).as<"scope">()`
+
+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
+// With transformer (author form):
+services.add<ILogger>(ConsoleLogger).as<"singleton">();
+services.add<IUserRepo>(SqlUserRepo).as<"request">();
+services.add<IRequestId>(UuidRequestId>(); // no .as() → transient
+
+// Without transformer (lowered form, or plugin-less):
+services.add("pkg:ILogger", ConsoleLogger).as("singleton");
+services.add("pkg:IUserRepo", SqlUserRepo).as("request");
+services.add("pkg:IRequestId", UuidRequestId);
+```
+
+The type constraint on `Concrete` is `new (...args: any[]) => Interface` — plain `new`, not `abstract new`. Abstract classes are correctly rejected because the container instantiates the concrete.
+
+`.as<S>()` checks at compile time that `S` is a declared scope name. Passing an undeclared string is a type error.
+
+### `useFactory` and `useValue`
+
+Override paths that bypass the dep-metadata system entirely. Recommended for test doubles, third-party instances, and plugin-less consumers.
+
+```typescript
+// Factory: receives the scope's container, returns the instance
+container.register("pkg:IDb", {
+  useFactory: (c) => new PostgresDb(c.resolve<IConfig>("pkg:IConfig")),
+});
+
+// Value: a pre-constructed instance (always singleton-like; re-used as-is)
+container.register("pkg:ICache", {
+  useValue: new NullCache(),
+});
+```
+
+`useFactory` with `.as("singleton")` on the parent builder makes the factory run once and cache the result. `useValue` is always cached.
+
+---
+
+## Scope model
+
+Scopes form a parent-linked chain. The root scope is a real, app-lifetime object — never auto-created by the container.
+
+```typescript
+const root = services.createScope("singleton"); // app lifetime
+const req  = root.createScope("request");        // per HTTP request
+```
+
+**Resolution walks the parent chain** for two purposes:
+
+1. **Registration lookup** — walks up until the token is found. A child scope can shadow a parent registration.
+2. **Instance ownership** — the lifetime tag names which ancestor scope caches the instance. Walks up to the nearest matching ancestor and caches there.
+
+**Lifetime rules:**
+
+| Registration | Behavior |
+|---|---|
+| No `.as()` (transient) | Fresh instance on every resolve. Never cached. |
+| `.as("singleton")` | Owned and cached by the nearest `"singleton"` ancestor in the chain. |
+| `.as("request")` | Owned and cached by the nearest `"request"` ancestor in the chain. |
+| Tag with no matching ancestor | **Throws.** The missing-ancestor error is intentional — see captive-dependency protection below. |
+
+### Captive-dependency protection
+
+The critical correctness rule: deps are resolved **relative to the scope that will own the instance**, not the scope that triggered the resolve.
+
+```typescript
+const services = new DiBuilder<"singleton" | "request">();
+services.add<ICache>(RedisCache).as<"singleton">();
+services.add<IUserContext>(HttpUserContext).as<"request">();
+services.add<IUserService>(UserService).as<"singleton">();
+// UserService constructor: (cache: ICache, ctx: IUserContext)
+
+const root = services.createScope("singleton");
+const req  = root.createScope("request");
+
+req.resolve<IUserService>("pkg:IUserService");
+// Throws: UserService is singleton-owned.
+// Its deps are resolved from the singleton scope's chain.
+// That chain has no "request" ancestor → IUserContext cannot be resolved → throws.
+//
+// Without this rule, UserService would silently capture one request's
+// IUserContext and hold it across every subsequent request.
+```
+
+This mirrors `Microsoft.Extensions.DependencyInjection`'s scope-validation discipline. The throw is the feature.
+
+---
+
+## 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.
+
+```typescript
+// Two overloads: prefer the one with ILogger if available
+@signature("pkg:ILogger", "pkg:IDb")
+@signature("pkg:IDb")
+class MyService {
+  constructor(logOrDb: ILogger | IDb, db?: IDb) { ... }
+}
+```
+
+If ILogger is registered, the two-parameter signature wins. If not, the one-parameter signature is used.
+
+---
+
+## Cycle detection
+
+The engine maintains a resolution stack per `resolve()` call. If a token appears on the stack when it is about to be pushed again, it throws with the full path:
+
+```
+Circular dependency detected:
+  pkg:IUserRepo → pkg:IDb → pkg:IConnectionPool → pkg:IDb
+```
+
+---
+
+## Disposal
+
+Closing a scope disposes the instances it owns in **reverse construction order**. Only instances implementing the native TC39 disposal contract are disposed.
+
+```typescript
+// Sync disposal
+scope.dispose(): void
+
+// Async disposal
+scope.disposeAsync(): Promise<void>
+
+// Native using / await using (TypeScript 5.2+, requires "ESNext.Disposable" in lib)
+{
+  await using req = root.createScope("request");
+  // req.disposeAsync() called automatically on block exit
+}
+```
+
+`Symbol.dispose` and `Symbol.asyncDispose` only — no custom `dispose()` interface. Sync `dispose()` throws if the scope owns a `Promise`-valued disposable, directing you to `disposeAsync()`. Async teardown is never silently skipped.
+
+Instances owned by ancestor scopes are disposed when those scopes close, not when child scopes close.
+
+---
+
+## Async as values
+
+The container never awaits. Async is expressed as `Promise<T>` values through the sync channel.
+
+```typescript
+// Register an async factory
+container.register("pkg:IDb", {
+  useFactory: async (c) => {
+    const pool = c.resolve<IConnectionPool>("pkg:IConnectionPool");
+    return new PostgresDb(await pool.connect());
+  },
+});
+
+// Consume it — declare the dep as Promise<IDb>
+class UserRepo {
+  constructor(private db: Promise<IDb>) {}
+  async findUser(id: string) {
+    return (await this.db).query(`SELECT * FROM users WHERE id = $1`, [id]);
+  }
+}
+```
+
+The container caches the factory's return verbatim — the `Promise` itself. Every resolve of `"pkg:IDb"` gets the same `Promise`; the async factory runs exactly once. `Promise<T>` at the dep site is the honest contract: the container doesn't hide asynchrony.
+
+The transformer unwraps `Promise<X>` at dep-extraction: a parameter typed `Promise<IDb>` maps to the same token as `IDb` (`"pkg:IDb"`). Promise-ness lives in the factory's return, not in a separate token.
+
+---
+
+## Factory injection
+
+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
+// IDb is a registered class. This parameter receives a callable:
+constructor(makeDb: () => IDb) { ... }
+
+// Partial factory — the target ctor has holes the caller fills:
+constructor(makeRepo: (tableName: string) => IUserRepo) { ... }
+```
+
+### Named function-interface opt-out
+
+A **named** callable interface is NOT treated as a factory — it resolves as a normal service keyed on that interface's own token:
+
+```typescript
+interface IDbFactory { (): IDb }
+
+// Resolves as the "pkg:IDbFactory" token, not a factory for IDb
+constructor(dbFactory: IDbFactory) { ... }
+```
+
+Name the interface to opt out of factory interpretation whenever your function-typed service should itself be a registered dep.
+
+### 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.
+
+```typescript
+// IUserRepo concrete: constructor(log: ILogger, tableName: string, db: IDb)
+// ILogger and IDb are registered; tableName is not (a hole).
+// Injected factory type: (tableName: string) => IUserRepo
+
+class RequestHandler {
+  constructor(private makeRepo: (tableName: string) => IUserRepo) {}
+
+  handle() {
+    const repo = this.makeRepo("users");
+    // At call time: new UserRepo(resolve(ILogger), "users", resolve(IDb))
+  }
+}
+```
+
+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.
+
+### Lifetime semantics
+
+The injected factory is a closure captured at injection time, referencing the owning scope. How the target's instance is managed depends on whether the factory is parameterized:
+
+| 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. |
+
+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.
+
+### `FactoryTargetError`
+
+Thrown when the container tries to build the factory callable and cannot. Two reasons:
+
+| Reason | Meaning |
+|---|---|
+| `"unregistered"` | The factory's target token has no registration. A factory parameter needs the target registered with `services.add(...)`. |
+| `"not-a-class"` | The target is registered as a `useValue` or `useFactory` override, not a class. A factory builds its target with `new`; only class registrations qualify. Resolve it directly or change the registration. |
+
+Note: `FactoryTargetError` is thrown when the factory callable is constructed (at owning-class resolution time), not when the callable is invoked.
+
+---
+
+## API reference
+
+### `DiBuilder<Scopes>`
+
+| Member | Signature | Description |
+|---|---|---|
+| `add<I>(Concrete)` | `(ctor: new (...) => I) => RegistrationBuilder` | Register a concrete class against interface `I`. |
+| `.as<S>()`| `(tag: S) → void` | Set the lifetime tag. No call → transient. |
+| `register(token, opts)` | `(token: string, { useFactory? useValue? }) => void` | Override path. No dep metadata required. |
+| `createScope(tag)` | `(tag: Scopes) => Scope<Scopes>` | Create the root scope. |
+
+### `Scope<Scopes>`
+
+| Member | Signature | Description |
+|---|---|---|
+| `createScope(tag)` | `(tag: Scopes) => Scope<Scopes>` | Create a child scope. |
+| `resolve<T>(token)` | `(token: string) => T` | Resolve an instance. Throws on captive-dep violation, missing tag ancestor, or cycle. |
+| `dispose()` | `() => void` | Sync close. Throws if any owned instance has async-only disposal. |
+| `disposeAsync()` | `() => Promise<void>` | Async close. |
+| `[Symbol.dispose]()` | — | Native `using` support. |
+| `[Symbol.asyncDispose]()` | — | Native `await using` support. |
+
+---
+
+## TypeScript configuration
+
+Disposal support requires `"ESNext.Disposable"` in your `lib` array. `"ES2022"` alone does not include the disposal symbols.
+
+```jsonc
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "ESNext.Disposable"]
+  }
+}
+```

package/dist/builder.d.ts

@@ -0,0 +1,81 @@
+import type { Token } from "@fnioc/core";
+import { Scope } from "./scope.js";
+import type { Ctor, OverrideSpec } from "./types.js";
+/**
+ * The continuation returned by `DiBuilder.add`. Carries the just-added
+ * registration so `.as()` can attach its lifetime tag in place. An `.add()`
+ * with no trailing `.as()` leaves the registration untagged ⇒ transient.
+ *
+ * `Scopes` is threaded so `.as()` only accepts a declared scope name —
+ * compile-time captive-misconfiguration guard at the registration site.
+ */
+export interface AddBuilder<Scopes extends string> {
+    /**
+     * Attaches the lifetime tag. Must name a declared scope.
+     *
+     * Two call shapes, by design (PRD §7):
+     *   - AUTHORED   `.as<"singleton">()` — the scope name is a TYPE argument; the
+     *     `S extends Scopes` bound is the compile-time captive-misconfiguration
+     *     guard. No value argument is passed; this form is never executed (the
+     *     transformer rewrites it before it runs).
+     *   - LOWERED    `.as("singleton")` — the transformer rewrites the type
+     *     argument to a value argument. This is the form the engine executes; the
+     *     runtime reads the tag from the value arg.
+     *
+     * `scope` is therefore OPTIONAL at the type level: the authored form supplies
+     * it as a type arg only, the lowered form as a value. A bare `.as()` with no
+     * type arg leaves `S = Scopes` and is a degenerate (untagged) call — use the
+     * type arg.
+     */
+    as<S extends Scopes>(scope?: S): void;
+}
+/**
+ * The registration builder.
+ *
+ * `Scopes` is the user-supplied scope-name union (e.g.
+ * `"singleton" | "request"`). `"transient"` is NOT a member — transient is the
+ * absence of a tag, not a scope.
+ *
+ * @example
+ * ```ts
+ * const services = new DiBuilder<"singleton" | "request">();
+ * services.add("pkg:ILogger", ConsoleLogger).as("singleton"); // lowered form
+ * const root = services.createScope("singleton");
+ * const logger = root.resolve<ILogger>("pkg:ILogger");
+ * ```
+ */
+export declare class DiBuilder<Scopes extends string = string> {
+    private readonly registrations;
+    /**
+     * Type-only authoring overload — the form the transformer rewrites FROM. The
+     * concrete is typed `new (...args: any[]) => I` (plain `new`, so an abstract
+     * class is rejected). At runtime the engine only ever receives the
+     * string-token form below; this signature exists purely so type-driven
+     * authoring type-checks before the transformer lowers it.
+     */
+    add<I>(ctor: new (...args: any[]) => I): AddBuilder<Scopes>;
+    /**
+     * The runtime reality — a string token bound to a concrete constructor. This
+     * is what the transformer emits and what the engine actually executes.
+     */
+    add(token: Token, ctor: Ctor): AddBuilder<Scopes>;
+    /**
+     * The plugin-less override path. Registers a token against either a
+     * `useFactory` closure (which resolves its own deps from the scope passed to
+     * it) or a `useValue` instance. The recommended mechanism for test doubles,
+     * third-party instances, and plugin-less wiring.
+     *
+     * A `useFactory` may carry an optional `tag` so the factory's result is
+     * cached at a matching ancestor scope (singleton-style); without a tag it
+     * runs on every resolve. A `useValue` is the instance itself — always the
+     * same value, no lifetime.
+     */
+    register<T>(token: Token, spec: OverrideSpec<T>): this;
+    /**
+     * Mints the root scope. The root must be a real, app-lifetime object — its
+     * name is the lifetime tag that singletons (or whatever the app's longest
+     * lifetime is) bind to.
+     */
+    createScope(rootScopeName: Scopes): Scope<Scopes>;
+}
+//# sourceMappingURL=builder.d.ts.map

package/dist/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,KAAK,EAEV,IAAI,EACJ,YAAY,EAGb,MAAM,YAAY,CAAC;AAEpB;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU,CAAC,MAAM,SAAS,MAAM;IAC/C;;;;;;;;;;;;;;;;OAgBG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;CACvC;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,SAAS,CAAC,MAAM,SAAS,MAAM,GAAG,MAAM;IACnD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAkC;IAEhE;;;;;;OAMG;IACI,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC;IAClE;;;OAGG;IACI,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC;IAsCxD;;;;;;;;;;OAUG;IACI,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI;IAa7D;;;;OAIG;IACI,WAAW,CAAC,aAAa,EAAE,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;CAGzD"}

package/dist/builder.js

@@ -0,0 +1,85 @@
+// The registration builder. Holds the base token → registration map and hands
+// out a root Scope. `.add()` is the surface the transformer lowers to; the
+// override paths (`.register`) are the recommended plugin-less mechanism.
+import { Scope } from "./scope.js";
+/**
+ * The registration builder.
+ *
+ * `Scopes` is the user-supplied scope-name union (e.g.
+ * `"singleton" | "request"`). `"transient"` is NOT a member — transient is the
+ * absence of a tag, not a scope.
+ *
+ * @example
+ * ```ts
+ * const services = new DiBuilder<"singleton" | "request">();
+ * services.add("pkg:ILogger", ConsoleLogger).as("singleton"); // lowered form
+ * const root = services.createScope("singleton");
+ * const logger = root.resolve<ILogger>("pkg:ILogger");
+ * ```
+ */
+export class DiBuilder {
+    registrations = new Map();
+    add(tokenOrCtor, maybeCtor) {
+        // Only the string-token form reaches the engine at runtime. The type-only
+        // overload is never actually invoked post-transform; guard defensively so a
+        // hand-written type-form call fails loud rather than registering garbage.
+        if (typeof tokenOrCtor !== "string" || maybeCtor === undefined) {
+            throw new TypeError('add<I>(ctor) requires the @fnioc/transformer plugin. Without it, ' +
+                'register with an explicit token: add("my:token", MyClass).');
+        }
+        const registration = {
+            kind: "class",
+            ctor: maybeCtor,
+            tag: undefined,
+        };
+        this.registrations.set(tokenOrCtor, registration);
+        // `.as()` rebinds the registration with its tag. The map holds an immutable
+        // record, so swap in a fresh one rather than mutating the readonly field.
+        const token = tokenOrCtor;
+        const registrations = this.registrations;
+        return {
+            as(scope) {
+                // The lowered form always passes a value arg; the authored type-arg-only
+                // form never executes (the transformer rewrites it first). A no-arg call
+                // at runtime would leave the registration transient — guard so it is a
+                // no-op rather than overwriting the tag with `undefined`.
+                if (scope === undefined)
+                    return;
+                registrations.set(token, { ...registration, tag: scope });
+            },
+        };
+    }
+    /**
+     * The plugin-less override path. Registers a token against either a
+     * `useFactory` closure (which resolves its own deps from the scope passed to
+     * it) or a `useValue` instance. The recommended mechanism for test doubles,
+     * third-party instances, and plugin-less wiring.
+     *
+     * A `useFactory` may carry an optional `tag` so the factory's result is
+     * cached at a matching ancestor scope (singleton-style); without a tag it
+     * runs on every resolve. A `useValue` is the instance itself — always the
+     * same value, no lifetime.
+     */
+    register(token, spec) {
+        if ("useValue" in spec) {
+            this.registrations.set(token, { kind: "value", useValue: spec.useValue });
+        }
+        else {
+            this.registrations.set(token, {
+                kind: "factory",
+                useFactory: spec.useFactory,
+                tag: spec.tag,
+            });
+        }
+        return this;
+    }
+    /**
+     * Mints the root scope. The root must be a real, app-lifetime object — its
+     * name is the lifetime tag that singletons (or whatever the app's longest
+     * lifetime is) bind to.
+     */
+    createScope(rootScopeName) {
+        return new Scope(rootScopeName, undefined, this.registrations);
+    }
+}
+//# sourceMappingURL=builder.js.map

package/dist/builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,2EAA2E;AAC3E,0EAA0E;AAI1E,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAsCnC;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,SAAS;IACH,aAAa,GAAG,IAAI,GAAG,EAAuB,CAAC;IAezD,GAAG,CACR,WAAsD,EACtD,SAAgB;QAEhB,0EAA0E;QAC1E,4EAA4E;QAC5E,0EAA0E;QAC1E,IAAI,OAAO,WAAW,KAAK,QAAQ,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC/D,MAAM,IAAI,SAAS,CACjB,mEAAmE;gBACjE,4DAA4D,CAC/D,CAAC;QACJ,CAAC;QAED,MAAM,YAAY,GAAsB;YACtC,IAAI,EAAE,OAAO;YACb,IAAI,EAAE,SAAS;YACf,GAAG,EAAE,SAAS;SACf,CAAC;QACF,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;QAElD,4EAA4E;QAC5E,0EAA0E;QAC1E,MAAM,KAAK,GAAG,WAAW,CAAC;QAC1B,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC;QACzC,OAAO;YACL,EAAE,CAAmB,KAAS;gBAC5B,yEAAyE;gBACzE,yEAAyE;gBACzE,uEAAuE;gBACvE,0DAA0D;gBAC1D,IAAI,KAAK,KAAK,SAAS;oBAAE,OAAO;gBAChC,aAAa,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,GAAG,YAAY,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;YAC5D,CAAC;SACF,CAAC;IACJ,CAAC;IAED;;;;;;;;;;OAUG;IACI,QAAQ,CAAI,KAAY,EAAE,IAAqB;QACpD,IAAI,UAAU,IAAI,IAAI,EAAE,CAAC;YACvB,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC5E,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,EAAE;gBAC5B,IAAI,EAAE,SAAS;gBACf,UAAU,EAAE,IAAI,CAAC,UAA8C;gBAC/D,GAAG,EAAE,IAAI,CAAC,GAAG;aACd,CAAC,CAAC;QACL,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACI,WAAW,CAAC,aAAqB;QACtC,OAAO,IAAI,KAAK,CAAS,aAAa,EAAE,SAAS,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;IACzE,CAAC;CACF"}

package/dist/errors.d.ts

@@ -0,0 +1,73 @@
+import type { Token } from "@fnioc/core";
+/** Base class for every error the container raises. */
+export declare class DiError extends Error {
+    constructor(message: string);
+}
+/**
+ * A token was requested but no registration exists for it anywhere in the
+ * resolving scope's chain (nor on the builder's base map).
+ */
+export declare class UnregisteredTokenError extends DiError {
+    readonly token: Token;
+    constructor(token: Token);
+}
+/**
+ * A registration carries a lifetime tag, but no ancestor scope in the resolving
+ * chain has a matching name. This is the captive-dependency / misconfiguration
+ * detector — the engine never auto-creates a scope to satisfy the tag.
+ */
+export declare class MissingScopeError extends DiError {
+    readonly token: Token;
+    readonly tag: string;
+    readonly availableScopes: readonly string[];
+    constructor(token: Token, tag: string, availableScopes: readonly string[]);
+}
+/**
+ * A constructor with parameters has no DepRecord in the WeakMap — the
+ * transformer never saw it and it was never hand-annotated.
+ */
+export declare class MissingMetadataError extends DiError {
+    readonly token: Token;
+    readonly ctorName: string;
+    constructor(token: Token, ctorName: string);
+}
+/**
+ * A constructor has DepRecord signatures, but none of them is directly
+ * satisfiable in the owning scope (every signature names at least one token
+ * that is not registered, or contains a hole this phase cannot fill).
+ */
+export declare class NoSatisfiableSignatureError extends DiError {
+    readonly token: Token;
+    readonly ctorName: string;
+    readonly unsatisfiable: readonly Token[];
+    constructor(token: Token, ctorName: string, unsatisfiable: readonly Token[]);
+}
+/**
+ * A token reappeared on the active resolution stack — the dependency graph has
+ * a cycle. The message includes the full path that closed the loop.
+ */
+export declare class CircularDependencyError extends DiError {
+    readonly path: readonly Token[];
+    constructor(path: readonly Token[]);
+}
+/**
+ * A constructor parameter is typed as a factory of some token (a `FactoryRef`),
+ * but that token cannot be turned into a factory: either it is not registered,
+ * or it is registered as a `useValue` / `useFactory` override rather than a
+ * class. A factory injects a callable that constructs the target class on
+ * demand, so the target must be a class registration.
+ */
+export declare class FactoryTargetError extends DiError {
+    readonly factoryToken: Token;
+    readonly reason: "unregistered" | "not-a-class";
+    constructor(factoryToken: Token, reason: "unregistered" | "not-a-class");
+}
+/**
+ * Sync `dispose()` was called on a scope that owns a Promise-valued (thenable)
+ * cached instance. A pending Promise cannot be disposed synchronously — the
+ * caller must use `disposeAsync()`.
+ */
+export declare class AsyncDisposalRequiredError extends DiError {
+    constructor();
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,uDAAuD;AACvD,qBAAa,OAAQ,SAAQ,KAAK;gBACb,OAAO,EAAE,MAAM;CAInC;AAED;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,OAAO;aACd,KAAK,EAAE,KAAK;gBAAZ,KAAK,EAAE,KAAK;CAMhD;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,OAAO;aAE1B,KAAK,EAAE,KAAK;aACZ,GAAG,EAAE,MAAM;aACX,eAAe,EAAE,SAAS,MAAM,EAAE;gBAFlC,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,MAAM,EACX,eAAe,EAAE,SAAS,MAAM,EAAE;CAerD;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,OAAO;aAE7B,KAAK,EAAE,KAAK;aACZ,QAAQ,EAAE,MAAM;gBADhB,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,MAAM;CAUnC;AAED;;;;GAIG;AACH,qBAAa,2BAA4B,SAAQ,OAAO;aAEpC,KAAK,EAAE,KAAK;aACZ,QAAQ,EAAE,MAAM;aAChB,aAAa,EAAE,SAAS,KAAK,EAAE;gBAF/B,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,SAAS,KAAK,EAAE;CAelD;AAED;;;GAGG;AACH,qBAAa,uBAAwB,SAAQ,OAAO;aACf,IAAI,EAAE,SAAS,KAAK,EAAE;gBAAtB,IAAI,EAAE,SAAS,KAAK,EAAE;CAG1D;AAED;;;;;;GAMG;AACH,qBAAa,kBAAmB,SAAQ,OAAO;aAE3B,YAAY,EAAE,KAAK;aACnB,MAAM,EAAE,cAAc,GAAG,aAAa;gBADtC,YAAY,EAAE,KAAK,EACnB,MAAM,EAAE,cAAc,GAAG,aAAa;CAezD;AAED;;;;GAIG;AACH,qBAAa,0BAA2B,SAAQ,OAAO;;CAQtD"}