@nwire/container 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Gefter / 200apps Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# @nwire/container
+
+> DI seam — the four-method `Container` interface every Nwire package composes through.
+
+## What it is
+
+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.
+
+## Install
+
+```bash
+pnpm add @nwire/container
+```
+
+## Standalone use
+
+For developers who want a tiny DI seam in any TypeScript app — no Nwire dependency on the rest of the stack. Use `InMemoryContainer` as a typed registry and `createScope()` for per-request isolation.
+
+```ts
+import { InMemoryContainer } from "@nwire/container";
+
+const root = new InMemoryContainer();
+root.register("db", () => new PrismaClient());
+
+// per-request scope inherits the parent but isolates request-scoped values
+const scope = root.createScope();
+scope.register("user", () => req.user);
+
+const db = scope.resolve<PrismaClient>("db"); // falls through to root
+const user = scope.resolve<User>("user"); // local to this scope
+```
+
+## Within nwire-app
+
+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`.
+
+```ts
+import { createApp } from "@nwire/forge";
+import { AwilixNwireContainer } from "@nwire/container-awilix";
+
+const container = new AwilixNwireContainer();
+container.register("db", () => new PrismaClient());
+
+const app = createApp("learnflow", { modules, container });
+```
+
+## API
+
+- `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.
+
+## See also
+
+- [Architecture sketch §05 — Foundation tier](../../architecture-sketch.html#packages)
+- Sibling packages: [@nwire/container-awilix](../nwire-container-awilix), [@nwire/app](../nwire-app)

package/dist/container.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `@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.
+ *
+ * See: architecture-sketch.html §05 (Foundation tier).
+ */
+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;
+    /**
+     * 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;
+    /** True when a name is registered (either locally or on a parent). */
+    has(name: string): boolean;
+}
+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;
+}
+/** A blank root container, ready to be populated by the wire. */
+export declare const rootContainer: Container;
+//# sourceMappingURL=container.d.ts.map

package/dist/container.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../src/container.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,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;CAC5B;AAED,qBAAa,iBAAkB,YAAW,SAAS;IAGrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAFpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgD;gBAE5C,MAAM,CAAC,EAAE,iBAAiB,YAAA;IAEvD,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC;IASrC,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI;IAIjE,WAAW,IAAI,SAAS;IAIxB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAI3B;AAED,iEAAiE;AACjE,eAAO,MAAM,aAAa,EAAE,SAAmC,CAAC"}

package/dist/container.js

@@ -0,0 +1,40 @@
+/**
+ * `@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.
+ *
+ * See: architecture-sketch.html §05 (Foundation tier).
+ */
+export class InMemoryContainer {
+    parent;
+    bindings = new Map();
+    constructor(parent) {
+        this.parent = parent;
+    }
+    resolve(name) {
+        if (this.bindings.has(name)) {
+            const v = this.bindings.get(name);
+            return typeof v === "function" ? v() : v;
+        }
+        if (this.parent)
+            return this.parent.resolve(name);
+        throw new Error(`Container: no binding for "${name}"`);
+    }
+    register(name, factory) {
+        this.bindings.set(name, factory);
+    }
+    createScope() {
+        return new InMemoryContainer(this);
+    }
+    has(name) {
+        if (this.bindings.has(name))
+            return true;
+        return this.parent?.has(name) ?? false;
+    }
+}
+/** A blank root container, ready to be populated by the wire. */
+export const rootContainer = new InMemoryContainer();
+//# sourceMappingURL=container.js.map

package/dist/container.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"container.js","sourceRoot":"","sources":["../src/container.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAqBH,MAAM,OAAO,iBAAiB;IAGC;IAFZ,QAAQ,GAAG,IAAI,GAAG,EAAqC,CAAC;IAEzE,YAA6B,MAA0B;QAA1B,WAAM,GAAN,MAAM,CAAoB;IAAG,CAAC;IAE3D,OAAO,CAAc,IAAY;QAC/B,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5B,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAClC,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,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,OAAkB,CAAC,CAAC;IAC9C,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;CACF;AAED,iEAAiE;AACjE,MAAM,CAAC,MAAM,aAAa,GAAc,IAAI,iBAAiB,EAAE,CAAC"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@nwire/container",
+  "version": "0.7.0",
+  "description": "Nwire — DI container contract + InMemory default. Production adapters land as @nwire/container-awilix.",
+  "keywords": [
+    "container",
+    "di",
+    "ioc",
+    "nwire"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/container.js",
+  "types": "./dist/container.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/container.js",
+      "types": "./dist/container.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.9",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc && node ../../scripts/fix-dist-extensions.mjs dist",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}