@nwire/container 0.8.0 → 0.9.1

package/README.md

@@ -1,33 +1,109 @@
 # @nwire/container
 
-> DI seam — the four-method `Container` interface every Nwire package composes through.
+Typed DI container, generic over the app's `Cradle` shape. Awilix-backed under the hood — you get scope hierarchy, lazy proxy cradle, lifetimes (singleton/transient/scoped), disposers, and factory-with-deps for free.
 
-## What it is
+```bash
+pnpm add @nwire/container
+```
 
-A small `Container` interface (`resolve` / `has` / `register` / `createScope`) plus an in-memory default. Every other Nwire package depends only on this, so you can bring your own DI (plain object, Awilix, tsyringe) without rewriting the framework.
+## Why
 
-## Install
+Apps grow into needing:
 
-```bash
-pnpm add @nwire/container
+- **Typed bindings.** `container.cradle.logger` should be `Logger`, not `unknown`.
+- **Per-request scopes.** Each HTTP request gets its own scope so `user`, `tenant`, `requestId` don't leak across requests.
+- **Lifetimes.** `singleton` for connections; `scoped` for per-request transactions; `transient` for fresh-each-time values.
+- **Disposers.** Graceful shutdown calls `db.close()`, `redis.quit()` automatically when a scope ends.
+- **Source location.** Studio shows "this binding was registered at `src/wires/api.ts:42`".
+
+Awilix has done this for over a decade. We wrap it with a typed `Container<TCradle>` interface so app code stays decoupled from awilix-specific imports, and you opt into the full Awilix surface via `.raw` when you need it.
+
+## Surface
+
+```ts
+interface Container<TCradle extends object = object> {
+  resolve<T, K extends string>(name: K): K extends keyof TCradle ? TCradle[K] : T;
+  register<T, K extends string>(
+    name: K,
+    factory: K extends keyof TCradle ? TCradle[K] | (() => TCradle[K]) : T | (() => T),
+  ): void;
+  readonly cradle: TCradle;
+  createScope(): Container<TCradle>;
+  has(name: keyof TCradle | (string & {})): boolean;
+  list?(): ReadonlyArray<BindingEntry>;
+  readonly raw: AwilixContainer<TCradle>;
+}
+
+function createContainer<TCradle extends object = object>(): Container<TCradle>;
+```
+
+## Consumer example
+
+```ts
+import { createContainer } from "@nwire/container";
+
+// Each plugin exports its cradle contribution as a type.
+import type { AuthCradle } from "@nwire/auth"; // { "auth.user": User; … }
+import type { DbCradle } from "@nwire/data-drizzle"; // { "db.pg": PgClient }
+
+// App composes the cradle (plus its own bindings).
+type AppCradle = AuthCradle &
+  DbCradle & {
+    config: AppConfig;
+    logger: Logger;
+  };
+
+const root = createContainer<AppCradle>();
+root.register("config", { port: 3000, dbUrl: process.env.DATABASE_URL! });
+root.register("logger", () => ({ log: (s) => process.stdout.write(s + "\n") }));
+root.register("db.pg", () => new PgClient(root.cradle.config.dbUrl)); // ← typed
+
+root.cradle.logger.log(`Listening on :${root.cradle.config.port}`); // ← typed, autocomplete
+
+// Per-request scope — child inherits, owns request-scoped values
+server.on("request", async (req, res) => {
+  const scope = root.createScope();
+  scope.register("requestId", crypto.randomUUID());
+  scope.register("user", await loadUser(req));
+  // hand `scope` to your handler / framework
+});
 ```
 
-## Within nwire-app
+## Lazy by default
 
-For developers using this package as part of the Nwire stack. Plugins register on the container during `boot`; handlers resolve via `ctx.resolve("key")`. Swap the implementation by passing a different `Container` to `createApp`.
+`container.cradle` is an Awilix proxy. Untouched bindings never instantiate; touched ones are cached (singleton) or fresh-each-time (transient) per the registration.
 
 ```ts
-import { createApp } from "@nwire/forge";
-import { AwilixNwireContainer } from "@nwire/container-awilix";
+const factory = vi.fn(() => new ExpensiveDb());
+root.register("db", factory);
 
-const container = new AwilixNwireContainer();
-container.register("db", () => new PrismaClient());
+// factory not called yet
+void root.cradle.db; // ← now called once
+void root.cradle.db; // ← cached, not called again
+```
 
-const app = createApp("learnflow", { modules, container });
+## Full Awilix when you need it
+
+`container.raw` is the underlying `AwilixContainer`. Use it for disposers, asClass, scoped lifetimes, async resolution, or `loadModules` — anything beyond the simple register/cradle/resolve surface:
+
+```ts
+import { asFunction, asValue, Lifetime } from "awilix";
+
+root.raw.register({
+  pgPool: asFunction(({ config }) => new PgPool(config.dbUrl))
+    .singleton()
+    .disposer((p) => p.end()), // graceful shutdown
+  pgTx: asFunction(({ pgPool }) => pgPool.transaction())
+    .setLifetime(Lifetime.SCOPED) // one transaction per request scope
+    .disposer((tx) => tx.rollback()), // auto-rollback if scope ends without commit
+});
 ```
 
-## API
+## Used by
+
+Every Nwire transport (HTTP, queue, cron, MCP) creates its scope chain through this surface. Plugins register into it. Handlers read from a wire-composed ctx that pulls from the cradle.
+
+## Notes
 
-- `Container` — interface every adapter implements.
-- `InMemoryContainer` — `Map`-backed default; good for tests and small wires.
-- `rootContainer` — a pre-built blank `InMemoryContainer` framework layers compose with.
+- Awilix uses PROXY injection mode by default — destructure parameters resolve from the cradle by name.
+- `keyof TCradle` keys can include any string, including dotted names (`"auth.user"`, `"db.pg"`). Namespacing is the convention to avoid plugin name clashes.

package/dist/__tests__/cradle.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `Container<TCradle>` — Awilix-backed generic. App declares its cradle
+ * shape; plugins export type fragments the app intersects in. No global
+ * augmentation, no cross-app pollution.
+ *
+ *   - declared keys resolve via both `.cradle.X` and `.resolve("X")`
+ *   - wrong-shape factory for a declared key is a real type error
+ *   - unknown names fall back to `<T>` generic
+ *   - `.cradle` is a typed Awilix proxy: lazy resolution
+ *   - child scopes inherit cradle typing
+ *   - `.raw` exposes the underlying AwilixContainer for advanced cases
+ */
+export {};
+//# sourceMappingURL=cradle.test.d.ts.map

package/dist/__tests__/cradle.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cradle.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/cradle.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/__tests__/cradle.test.js

@@ -0,0 +1,83 @@
+/**
+ * `Container<TCradle>` — Awilix-backed generic. App declares its cradle
+ * shape; plugins export type fragments the app intersects in. No global
+ * augmentation, no cross-app pollution.
+ *
+ *   - declared keys resolve via both `.cradle.X` and `.resolve("X")`
+ *   - wrong-shape factory for a declared key is a real type error
+ *   - unknown names fall back to `<T>` generic
+ *   - `.cradle` is a typed Awilix proxy: lazy resolution
+ *   - child scopes inherit cradle typing
+ *   - `.raw` exposes the underlying AwilixContainer for advanced cases
+ */
+import { describe, expect, it, expectTypeOf, vi } from "vitest";
+import { asFunction, asValue, Lifetime } from "awilix";
+import { createContainer } from "../container.js";
+describe("createContainer<TCradle> — typed binding surface", () => {
+    it("resolves a declared key to its declared type via .cradle and .resolve", () => {
+        const c = createContainer();
+        c.register("config", { port: 3000, host: "0.0.0.0" });
+        c.register("logger", () => ({ log: () => { } }));
+        expectTypeOf(c.cradle.config).toEqualTypeOf();
+        expectTypeOf(c.cradle.logger).toEqualTypeOf();
+        expectTypeOf(c.resolve("config")).toEqualTypeOf();
+        expect(c.cradle.config.port).toBe(3000);
+        expect(c.resolve("logger")).toBe(c.cradle.logger); // factory.singleton() caches
+        c.cradle.logger.log("ok");
+    });
+    it("rejects a wrong-shaped registration at the type level", () => {
+        const c = createContainer();
+        // @ts-expect-error config must satisfy AppConfig, not a string
+        c.register("config", "not-config");
+        expect(c.has("config")).toBe(true);
+    });
+    it("falls back to the <T> generic for unknown names (escape hatch)", () => {
+        const c = createContainer();
+        c.register("widget", { id: "w-1" });
+        const widget = c.resolve("widget");
+        expectTypeOf(widget).toEqualTypeOf();
+        expect(widget.id).toBe("w-1");
+    });
+    it("cradle is lazy — factories run only on first access", () => {
+        const factory = vi.fn(() => ({ log: () => { } }));
+        const c = createContainer();
+        c.register("logger", factory);
+        expect(factory).not.toHaveBeenCalled(); // ← never touched, never called
+        void c.cradle.logger;
+        expect(factory).toHaveBeenCalledTimes(1);
+        void c.cradle.logger;
+        expect(factory).toHaveBeenCalledTimes(1); // ← singleton: cached
+    });
+    it("child scope inherits TCradle typing from the parent", () => {
+        const parent = createContainer();
+        parent.register("config", { port: 8080, host: "localhost" });
+        const child = parent.createScope();
+        expectTypeOf(child.cradle.config).toEqualTypeOf();
+        expect(child.cradle.config.host).toBe("localhost");
+    });
+    it("child scope overrides parent for the scope only", () => {
+        const parent = createContainer();
+        parent.register("config", { port: 80, host: "prod" });
+        const child = parent.createScope();
+        child.register("config", { port: 99, host: "test" });
+        expect(child.cradle.config.host).toBe("test");
+        expect(parent.cradle.config.host).toBe("prod");
+    });
+    it(".raw exposes the underlying AwilixContainer for advanced cases", () => {
+        const c = createContainer();
+        // Use Awilix's full surface directly — lifetimes, disposers, factory-with-deps.
+        c.raw.register({
+            logger: asValue({ log: () => { } }),
+            config: asFunction(() => ({ port: 1, host: "x" })).setLifetime(Lifetime.SINGLETON),
+        });
+        expect(c.cradle.logger).toBeDefined();
+        expect(c.cradle.config.port).toBe(1);
+    });
+    it("untyped container works with default <TCradle = object>", () => {
+        const c = createContainer();
+        c.register("anything", 42);
+        expect(c.resolve("anything")).toBe(42);
+        expect(c.has("anything")).toBe(true);
+    });
+});
+//# sourceMappingURL=cradle.test.js.map

package/dist/__tests__/cradle.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cradle.test.js","sourceRoot":"","sources":["../../src/__tests__/cradle.test.ts"],"names":[],"mappings":"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"}

package/dist/container.d.ts

@@ -1,13 +1,24 @@
 /**
  * `@nwire/container` — DI seam.
  *
- * Defines the four-method `Container` interface every Nwire layer composes
- * through (`resolve` / `has` / `register` / `createScope`) and ships an
- * in-memory default. Bring your own DI (plain object, Awilix, tsyringe)
- * under any Nwire package without rewriting the framework.
+ * Generic over a `TCradle` shape (Awilix-style). Apps declare their cradle
+ * type at the boot site; plugins export type fragments the app intersects
+ * in. Nothing is globally augmented.
  *
- * See: architecture-sketch.html §05 (Foundation tier).
+ *   type AppCradle = AuthCradle & DbCradle & { config: AppConfig };
+ *   const c = createContainer<AppCradle>();
+ *   c.register("auth.user", user);     // typed
+ *   c.cradle["auth.user"]              // → User, autocomplete + lazy
+ *   c.resolve("auth.user")             // → User, escape hatch
+ *
+ * Implementation is Awilix-backed: scope hierarchy, lazy proxy cradle,
+ * lifetimes (singleton/transient/scoped), disposers, factory-with-deps.
+ * Source-location capture wraps `register()` so Studio's `.nwire/di.json`
+ * surfaces "where was this binding made?".
+ *
+ * Apps consume `createContainer<TCradle>()` as the canonical factory.
  */
+import { type AwilixContainer } from "awilix";
 import { type SourceLocation } from "@nwire/messages";
 /**
  * One row per active registration, surfaced by `container.list()`. Studio
@@ -16,49 +27,75 @@ import { type SourceLocation } from "@nwire/messages";
  *
  * `kind` reflects how the value was stored: a function factory under
  * `register()` is `"transient"` (re-evaluated on every resolve); a plain
- * value is `"singleton"`.
+ * value is `"singleton"`. Awilix's full lifetime spectrum
+ * (singleton/transient/scoped) is available via `.raw.register({…})`.
  */
 export interface BindingEntry {
     readonly name: string;
     readonly kind: "singleton" | "transient";
     readonly source?: SourceLocation;
 }
-export interface Container {
-    /** Look up a registered value by name. Throws when unregistered. */
-    resolve<T = unknown>(name: string): T;
-    /** Register a value or factory under a name. Last-write wins. */
-    register<T = unknown>(name: string, factory: T | (() => T)): void;
+export interface Container<TCradle extends object = object> {
+    /**
+     * Imperative lookup by name. Throws when unregistered.
+     *
+     * Names declared on `TCradle` resolve to their declared type. Unknown
+     * names default to `unknown` — pass an explicit `<T>` to override.
+     */
+    resolve<T = unknown, K extends string = string>(name: K): K extends keyof TCradle ? TCradle[K] : T;
+    /**
+     * Register a value or factory under a name. Last-write wins.
+     *
+     * - Plain value  → Awilix `asValue(v)` (singleton-equivalent).
+     * - Function `() => T` → Awilix `asFunction(fn).singleton()` (cached after first resolve).
+     *
+     * Apps that need Awilix's full lifetime / disposer / factory-with-deps
+     * surface use `container.raw.register({…})` directly — the underlying
+     * `AwilixContainer` is exposed via `.raw`.
+     */
+    register<T = unknown, K extends string = string>(name: K, factory: K extends keyof TCradle ? TCradle[K] | (() => TCradle[K]) : T | (() => T)): void;
+    /**
+     * Typed lazy proxy. `container.cradle["auth.user"]` resolves through the
+     * same machinery `container.resolve("auth.user")` uses — bindings are
+     * resolved only on access, so untouched ones never instantiate.
+     * Awilix's PROXY-mode cradle, surfaced under our typed interface.
+     */
+    readonly cradle: TCradle;
     /**
      * Create a child scope that inherits parent registrations but lets the
      * caller override or register locally. Used for per-request scopes —
      * each HTTP request gets a scoped container so per-request values
      * (envelope, user, tenant) don't leak across requests.
      */
-    createScope(): Container;
+    createScope(): Container<TCradle>;
     /** True when a name is registered (either locally or on a parent). */
-    has(name: string): boolean;
+    has(name: keyof TCradle | (string & {})): boolean;
     /**
-     * Snapshot every binding visible to this container (own bindings union
-     * parent bindings; child overrides win on name collisions). Purely
+     * Snapshot every binding visible to this container. Purely
      * introspective — never throws, never resolves factories. Studio + CLI
-     * `nwire cache` use this to surface the DI surface; runtime code should
-     * stick to `resolve` / `has`.
+     * `nwire cache` use this to surface the DI surface.
      *
-     * Optional so external `Container` adapters (Awilix, tsyringe, plain
-     * objects) stay valid without re-implementing introspection.
+     * Optional so external `Container` adapters stay valid without
+     * re-implementing introspection.
      */
     list?(): ReadonlyArray<BindingEntry>;
+    /**
+     * Escape hatch — the underlying Awilix container. Use when you need
+     * Awilix-specific surface (`asClass`, scoped lifetimes, disposers,
+     * `loadModules`, …). Apps that stay on `register` + `cradle` + `resolve`
+     * never touch this.
+     */
+    readonly raw: AwilixContainer<TCradle>;
 }
-export declare class InMemoryContainer implements Container {
-    private readonly parent?;
-    private readonly bindings;
-    constructor(parent?: InMemoryContainer | undefined);
-    resolve<T = unknown>(name: string): T;
-    register<T = unknown>(name: string, factory: T | (() => T)): void;
-    createScope(): Container;
-    has(name: string): boolean;
-    list(): ReadonlyArray<BindingEntry>;
-}
-/** A blank root container, ready to be populated by the wire. */
-export declare const rootContainer: Container;
+/**
+ * Build a container — generic over `TCradle`. The returned value
+ * satisfies the `Container<TCradle>` interface and is backed by Awilix
+ * (PROXY-mode cradle, scope hierarchy, lifetimes, disposers).
+ *
+ *   type AppCradle = { logger: Logger; pg: PgClient };
+ *   const root = createContainer<AppCradle>();
+ *   root.register("logger", asValue(logger));
+ *   root.cradle.logger.log("…");
+ */
+export declare function createContainer<TCradle extends object = object>(): Container<TCradle>;
 //# sourceMappingURL=container.d.ts.map

package/dist/container.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../src/container.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAyB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE7E;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,WAAW,CAAC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC;CAClC;AAED,MAAM,WAAW,SAAS;IACxB,oEAAoE;IACpE,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC;IAEtC,iEAAiE;IACjE,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC;IAElE;;;;;OAKG;IACH,WAAW,IAAI,SAAS,CAAC;IAEzB,sEAAsE;IACtE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAE3B;;;;;;;;;OASG;IACH,IAAI,CAAC,IAAI,aAAa,CAAC,YAAY,CAAC,CAAC;CACtC;AAOD,qBAAa,iBAAkB,YAAW,SAAS;IAGrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAFpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;gBAEhC,MAAM,CAAC,EAAE,iBAAiB,YAAA;IAEvD,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC;IAUrC,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI;IAUjE,WAAW,IAAI,SAAS;IAIxB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAK1B,IAAI,IAAI,aAAa,CAAC,YAAY,CAAC;CAepC;AAED,iEAAiE;AACjE,eAAO,MAAM,aAAa,EAAE,SAAmC,CAAC"}
+{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../src/container.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAKL,KAAK,eAAe,EACrB,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAyB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE7E;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,WAAW,CAAC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC;CAClC;AAED,MAAM,WAAW,SAAS,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM;IACxD;;;;;OAKG;IACH,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,EAC5C,IAAI,EAAE,CAAC,GACN,CAAC,SAAS,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAE5C;;;;;;;;;OASG;IACH,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,EAC7C,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,CAAC,SAAS,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,GACjF,IAAI,CAAC;IAER;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAEzB;;;;;OAKG;IACH,WAAW,IAAI,SAAS,CAAC,OAAO,CAAC,CAAC;IAElC,sEAAsE;IACtE,GAAG,CAAC,IAAI,EAAE,MAAM,OAAO,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC;IAElD;;;;;;;OAOG;IACH,IAAI,CAAC,IAAI,aAAa,CAAC,YAAY,CAAC,CAAC;IAErC;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC;CACxC;AA8ED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,KAAK,SAAS,CAAC,OAAO,CAAC,CAErF"}

package/dist/container.js

@@ -1,29 +1,44 @@
 /**
  * `@nwire/container` — DI seam.
  *
- * Defines the four-method `Container` interface every Nwire layer composes
- * through (`resolve` / `has` / `register` / `createScope`) and ships an
- * in-memory default. Bring your own DI (plain object, Awilix, tsyringe)
- * under any Nwire package without rewriting the framework.
+ * Generic over a `TCradle` shape (Awilix-style). Apps declare their cradle
+ * type at the boot site; plugins export type fragments the app intersects
+ * in. Nothing is globally augmented.
  *
- * See: architecture-sketch.html §05 (Foundation tier).
+ *   type AppCradle = AuthCradle & DbCradle & { config: AppConfig };
+ *   const c = createContainer<AppCradle>();
+ *   c.register("auth.user", user);     // typed
+ *   c.cradle["auth.user"]              // → User, autocomplete + lazy
+ *   c.resolve("auth.user")             // → User, escape hatch
+ *
+ * Implementation is Awilix-backed: scope hierarchy, lazy proxy cradle,
+ * lifetimes (singleton/transient/scoped), disposers, factory-with-deps.
+ * Source-location capture wraps `register()` so Studio's `.nwire/di.json`
+ * surfaces "where was this binding made?".
+ *
+ * Apps consume `createContainer<TCradle>()` as the canonical factory.
  */
+import { createContainer as createAwilixContainer, asValue, asFunction, InjectionMode, } from "awilix";
 import { captureSourceLocation } from "@nwire/messages";
-export class InMemoryContainer {
-    parent;
-    bindings = new Map();
-    constructor(parent) {
-        this.parent = parent;
+/** Per-binding source-location capture, keyed by the underlying Awilix container. */
+const sourceByContainer = new WeakMap();
+class NwireContainer {
+    raw;
+    constructor(awilix) {
+        this.raw =
+            awilix ??
+                createAwilixContainer({
+                    injectionMode: InjectionMode.PROXY,
+                });
+        if (!sourceByContainer.has(this.raw)) {
+            sourceByContainer.set(this.raw, new Map());
+        }
+    }
+    get cradle() {
+        return this.raw.cradle;
     }
     resolve(name) {
-        const own = this.bindings.get(name);
-        if (own !== undefined) {
-            const v = own.value;
-            return typeof v === "function" ? v() : v;
-        }
-        if (this.parent)
-            return this.parent.resolve(name);
-        throw new Error(`Container: no binding for "${name}"`);
+        return this.raw.resolve(name);
     }
     register(name, factory) {
         // Skip two frames: this `register` itself plus the synthetic `Error`
@@ -32,32 +47,51 @@ export class InMemoryContainer {
         // frames (forge's app capability registration, plugin .provide(), etc.)
         // until it lands on user code.
         const source = captureSourceLocation(2);
-        this.bindings.set(name, { value: factory, source });
+        const sources = sourceByContainer.get(this.raw);
+        if (source && sources)
+            sources.set(name, source);
+        if (typeof factory === "function") {
+            this.raw.register({
+                [name]: asFunction(factory).singleton(),
+            });
+        }
+        else {
+            this.raw.register({
+                [name]: asValue(factory),
+            });
+        }
     }
     createScope() {
-        return new InMemoryContainer(this);
+        return new NwireContainer(this.raw.createScope());
     }
     has(name) {
-        if (this.bindings.has(name))
-            return true;
-        return this.parent?.has(name) ?? false;
+        return this.raw.hasRegistration(name);
     }
     list() {
-        // Walk parent chain first so child-overrides win when we re-insert.
-        const merged = new Map();
-        for (const entry of this.parent?.list?.() ?? []) {
-            merged.set(entry.name, entry);
-        }
-        for (const [name, binding] of this.bindings) {
-            merged.set(name, {
-                name,
-                kind: typeof binding.value === "function" ? "transient" : "singleton",
-                source: binding.source,
-            });
-        }
-        return Array.from(merged.values());
+        const sources = sourceByContainer.get(this.raw) ?? new Map();
+        const registrations = this.raw.registrations;
+        return Object.keys(registrations).map((name) => {
+            // Awilix exposes `lifetime` on each registration; classify by it.
+            // `SINGLETON` (which we use for asFunction(...).singleton()) and
+            // `TRANSIENT` are the two we surface; SCOPED collapses into "transient"
+            // for the Studio view.
+            const reg = registrations[name].lifetime;
+            const kind = reg === "TRANSIENT" ? "transient" : "singleton";
+            return { name, kind, source: sources.get(name) };
+        });
     }
 }
-/** A blank root container, ready to be populated by the wire. */
-export const rootContainer = new InMemoryContainer();
+/**
+ * Build a container — generic over `TCradle`. The returned value
+ * satisfies the `Container<TCradle>` interface and is backed by Awilix
+ * (PROXY-mode cradle, scope hierarchy, lifetimes, disposers).
+ *
+ *   type AppCradle = { logger: Logger; pg: PgClient };
+ *   const root = createContainer<AppCradle>();
+ *   root.register("logger", asValue(logger));
+ *   root.cradle.logger.log("…");
+ */
+export function createContainer() {
+    return new NwireContainer();
+}
 //# sourceMappingURL=container.js.map

package/dist/container.js.map

@@ -1 +1 @@
-{"version":3,"file":"container.js","sourceRoot":"","sources":["../src/container.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,qBAAqB,EAAuB,MAAM,iBAAiB,CAAC;AAqD7E,MAAM,OAAO,iBAAiB;IAGC;IAFZ,QAAQ,GAAG,IAAI,GAAG,EAAyB,CAAC;IAE7D,YAA6B,MAA0B;QAA1B,WAAM,GAAN,MAAM,CAAoB;IAAG,CAAC;IAE3D,OAAO,CAAc,IAAY;QAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,MAAM,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC;YACpB,OAAO,OAAO,CAAC,KAAK,UAAU,CAAC,CAAC,CAAE,CAAa,EAAE,CAAC,CAAC,CAAE,CAAO,CAAC;QAC/D,CAAC;QACD,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAI,IAAI,CAAC,CAAC;QACrD,MAAM,IAAI,KAAK,CAAC,8BAA8B,IAAI,GAAG,CAAC,CAAC;IACzD,CAAC;IAED,QAAQ,CAAc,IAAY,EAAE,OAAsB;QACxD,qEAAqE;QACrE,uEAAuE;QACvE,sEAAsE;QACtE,wEAAwE;QACxE,+BAA+B;QAC/B,MAAM,MAAM,GAAG,qBAAqB,CAAC,CAAC,CAAC,CAAC;QACxC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,OAAkB,EAAE,MAAM,EAAE,CAAC,CAAC;IACjE,CAAC;IAED,WAAW;QACT,OAAO,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;IAED,GAAG,CAAC,IAAY;QACd,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QACzC,OAAO,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC;IACzC,CAAC;IAED,IAAI;QACF,oEAAoE;QACpE,MAAM,MAAM,GAAG,IAAI,GAAG,EAAwB,CAAC;QAC/C,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC;YAChD,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAChC,CAAC;QACD,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC5C,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE;gBACf,IAAI;gBACJ,IAAI,EAAI,OAAO,OAAO,CAAC,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,WAAW;gBACvE,MAAM,EAAE,OAAO,CAAC,MAAM;aACvB,CAAC,CAAC;QACL,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IACrC,CAAC;CACF;AAED,iEAAiE;AACjE,MAAM,CAAC,MAAM,aAAa,GAAc,IAAI,iBAAiB,EAAE,CAAC"}
+{"version":3,"file":"container.js","sourceRoot":"","sources":["../src/container.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nwire/container",
-  "version": "0.8.0",
-  "description": "Nwire — DI container contract + InMemory default. Production adapters land as @nwire/container-awilix.",
+  "version": "0.9.1",
+  "description": "Nwire — DI container contract + Awilix-backed default. Generic over TCradle; ships scope hierarchy, lazy cradle proxy, lifetimes, disposers via Awilix.",
   "keywords": [
     "container",
     "di",
@@ -27,7 +27,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@nwire/messages": "0.8.0"
+    "awilix": "^12.0.4",
+    "@nwire/messages": "0.9.1"
   },
   "devDependencies": {
     "@types/node": "^22.19.9",