@nwire/express 0.10.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,84 @@
+# @nwire/express
+
+> Express-backed HTTP adopter — same wires as `@nwire/koa`, different runtime.
+
+```bash
+pnpm add @nwire/express @nwire/app @nwire/endpoint @nwire/wires
+```
+
+`express@^4 || ^5` is a peer dep.
+
+## Two integration modes
+
+### 1. Drive Nwire as the HTTP server (Adapter mode)
+
+```ts
+import { createApp } from "@nwire/app";
+import { endpoint } from "@nwire/endpoint";
+import { post } from "@nwire/wires/http";
+import { expressAdapter } from "@nwire/express";
+import { z } from "zod";
+
+const app = createApp({ appName: "api" });
+app.wire(
+  post("/hello", { body: z.object({ name: z.string() }) }),
+  async (input) => ({ message: `Hello, ${input.name}!` }),
+);
+
+await endpoint("api", { port: 3000 })
+  .use(expressAdapter({ prefix: "/api" }))
+  .mount(app)
+  .run();
+```
+
+### 2. Mount Nwire wires inside an existing Express app
+
+When you already run Express (or NestJS, which uses Express under the
+hood), `nwireToExpressRouter` extracts wired routes as an Express Router
+you mount alongside legacy handlers. Migration without rewrite.
+
+```ts
+import express from "express";
+import { createApp } from "@nwire/app";
+import { nwireToExpressRouter } from "@nwire/express";
+
+const legacy = express();
+legacy.get("/legacy", legacyHandler);
+
+const nwireApp = createApp({ appName: "orders" });
+nwireApp.wire(/* ... */);
+await nwireApp.start();
+
+legacy.use("/api/nwire", nwireToExpressRouter(nwireApp));
+legacy.listen(3000);
+```
+
+The router handles its own JSON body-parsing (`bodyParser: false` opts
+out) so it works whether Express has body-parser globally or not. See
+[`examples/nest-interop`](../../examples/nest-interop) for the full
+Nwire-inside-NestJS pattern.
+
+## Adopter config
+
+```ts
+expressAdapter({
+  port: 3000,                   // 0 = ephemeral; .port() returns the bound port
+  host: "0.0.0.0",
+  prefix: "/api",
+  middleware: [helmet(), morgan("combined")],
+  logger: myLogger,
+});
+```
+
+## Bridging middleware
+
+`fromExpressMiddleware(mw)` wraps an Express middleware so it can be
+passed in `httpKoa({ middleware: [...] })` — useful when an Express-only
+middleware (e.g., a vendored auth check) needs to run inside a Koa-backed
+adopter.
+
+## Related
+
+- [`@nwire/koa`](../nwire-koa) — Koa-backed sibling adopter
+- [`@nwire/endpoint`](../core-endpoint) — the lifecycle host
+- [`examples/nest-interop`](../../examples/nest-interop) — Nwire inside NestJS

package/dist/http-express.d.ts

@@ -0,0 +1,73 @@
+/**
+ * `@nwire/express` — Express-backed HTTP adopter.
+ *
+ *   import { expressAdapter } from "@nwire/express";
+ *
+ *   await endpoint("api", { port: 3000 })
+ *     .use(expressAdapter({ prefix: "/api" }))
+ *     .mount(app)
+ *     .run();
+ *
+ * Consumes wires whose `binding.$adapter === "http"` — same contract as
+ * `httpKoa`. Pick one or the other based on which framework your team
+ * lives in; both run the same wires identically.
+ *
+ * Also exports `fromExpressMiddleware(mw)` — wraps an Express middleware
+ * function so it can be passed as `httpKoa({ middleware: [...] })`. Useful
+ * when adopting Nwire inside an existing Express monorepo where stock
+ * middleware (helmet, morgan, passport) is already in place.
+ */
+import express, { type Application, type NextFunction, type Request, type Response } from "express";
+import type { Adapter } from "@nwire/endpoint";
+import type { Container } from "@nwire/container";
+import type { Wire } from "@nwire/wires";
+import { type Logger } from "@nwire/logger";
+export interface ExpressAdapterConfig {
+    /** Bound port. 0 = ephemeral. Default 3000. */
+    readonly port?: number;
+    /** Host bind address. Default 0.0.0.0. */
+    readonly host?: string;
+    /** Route prefix mounted under (e.g. "/api"). Default "/". */
+    readonly prefix?: string;
+    /** Adopter-wide Express middleware run before every wired handler. */
+    readonly middleware?: ReadonlyArray<(req: Request, res: Response, next: NextFunction) => void>;
+    /** Logger. Defaults to ConsoleLogger. */
+    readonly logger?: Logger;
+}
+export interface ExpressAdapter extends Adapter {
+    port(): number | undefined;
+    /** Underlying Express app — present after boot. Tests can pass this to
+     * supertest(adapter.app()!) for in-process request simulation. */
+    app(): Application | undefined;
+}
+export declare function expressAdapter(config?: ExpressAdapterConfig): ExpressAdapter;
+/**
+ * Build an Express Router from a Nwire App's wires. Mount it on an
+ * existing Express server to add Nwire routes alongside legacy handlers:
+ *
+ *   const nwireApp = buildNwireApp();
+ *   await nwireApp.start();
+ *   const router = nwireToExpressRouter(nwireApp);
+ *   expressApp.use("/api/nwire", router);
+ *
+ * The router uses the same dispatch path as `expressAdapter` — same
+ * validation, error envelope, container scoping — but doesn't boot its
+ * own HTTP server.
+ */
+export declare function nwireToExpressRouter(app: {
+    interface: {
+        wires: ReadonlyArray<Wire>;
+    };
+    container: Container;
+}, options?: {
+    logger?: Logger;
+    bodyParser?: boolean;
+}): express.Router;
+/**
+ * Wrap an Express middleware so it can be passed to `httpKoa({ middleware: [...] })`.
+ * Bridges the `(req, res, next)` Express contract into Koa's async chain.
+ */
+export declare function fromExpressMiddleware(mw: (req: Request, res: Response, next: NextFunction) => void): (kctx: {
+    req: unknown;
+    res: unknown;
+}, next: () => Promise<unknown>) => Promise<void>;

package/dist/http-express.js

@@ -0,0 +1,336 @@
+/**
+ * `@nwire/express` — Express-backed HTTP adopter.
+ *
+ *   import { expressAdapter } from "@nwire/express";
+ *
+ *   await endpoint("api", { port: 3000 })
+ *     .use(expressAdapter({ prefix: "/api" }))
+ *     .mount(app)
+ *     .run();
+ *
+ * Consumes wires whose `binding.$adapter === "http"` — same contract as
+ * `httpKoa`. Pick one or the other based on which framework your team
+ * lives in; both run the same wires identically.
+ *
+ * Also exports `fromExpressMiddleware(mw)` — wraps an Express middleware
+ * function so it can be passed as `httpKoa({ middleware: [...] })`. Useful
+ * when adopting Nwire inside an existing Express monorepo where stock
+ * middleware (helmet, morgan, passport) is already in place.
+ */
+import http from "node:http";
+import express from "express";
+import { dummyContainer } from "@nwire/container";
+import { ConsoleLogger } from "@nwire/logger";
+function isHttpBinding(b) {
+    return (typeof b === "object" &&
+        b !== null &&
+        b.$adapter === "http" &&
+        typeof b.verb === "string" &&
+        typeof b.path === "string");
+}
+export function expressAdapter(config = {}) {
+    let server;
+    let appInstance;
+    const logger = config.logger ?? new ConsoleLogger();
+    return {
+        $kind: "adapter",
+        kind: "http",
+        port() {
+            if (!server)
+                return undefined;
+            const addr = server.address();
+            return typeof addr === "object" && addr !== null ? addr.port : undefined;
+        },
+        app() {
+            return appInstance;
+        },
+        async boot(ctx) {
+            const expressApp = express();
+            appInstance = expressApp;
+            expressApp.use(express.json());
+            for (const mw of config.middleware ?? []) {
+                expressApp.use(mw);
+            }
+            const prefix = config.prefix ?? "";
+            for (const wire of ctx.wires) {
+                if (!isHttpBinding(wire.binding))
+                    continue;
+                const binding = wire.binding;
+                const verb = binding.verb;
+                const path = prefix + binding.path;
+                const handler = async (req, res) => {
+                    let input = {};
+                    try {
+                        if (binding.params) {
+                            Object.assign(input, binding.params.parse(req.params));
+                        }
+                        if (binding.body) {
+                            Object.assign(input, binding.body.parse(req.body));
+                        }
+                        if (binding.query) {
+                            Object.assign(input, binding.query.parse(req.query));
+                        }
+                        if (!binding.params && !binding.body && !binding.query) {
+                            input = {
+                                ...req.params,
+                                ...req.body,
+                                ...req.query,
+                            };
+                        }
+                    }
+                    catch (err) {
+                        res.status(400).json({
+                            error: { code: "validation_failed", summary: err.message },
+                        });
+                        return;
+                    }
+                    const parentContainer = ctx.containerOf(wire) ?? dummyContainer();
+                    const reqContainer = parentContainer.createScope();
+                    const envelopePartial = {
+                        tenant: req.headers["x-tenant"] ?? undefined,
+                        userId: req.user?.id ?? undefined,
+                        correlationId: req.headers["x-correlation-id"] ?? undefined,
+                        causationId: req.headers["x-causation-id"] ?? undefined,
+                    };
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const wireApp = wire.app;
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const runtimeExecute = wireApp?.runtime?.execute;
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const hasRunMethod = typeof wire.handler?.run === "function";
+                    let result;
+                    try {
+                        if (runtimeExecute && hasRunMethod) {
+                            result = await runtimeExecute.call(wireApp.runtime, wire.handler, input, envelopePartial);
+                        }
+                        else {
+                            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                            const fn = wire.handler.run ?? wire.handler;
+                            const handlerCtx = {
+                                resolve: (name) => reqContainer.resolve(name),
+                                logger,
+                                req,
+                                res,
+                                envelope: envelopePartial,
+                            };
+                            result = await fn(input, handlerCtx);
+                        }
+                    }
+                    catch (err) {
+                        const e = err;
+                        res.status(typeof e.status === "number" ? e.status : 500).json({
+                            error: {
+                                code: e.code ?? "internal_error",
+                                summary: e.summary ?? e.message ?? "Internal error",
+                            },
+                        });
+                        return;
+                    }
+                    // Response shaping: response-instance | $status envelope | verbatim.
+                    if (result &&
+                        typeof result === "object" &&
+                        result.$kind === "response-instance") {
+                        const env = result;
+                        res.status(env.status ?? 200).json(env.body);
+                    }
+                    else if (result &&
+                        typeof result === "object" &&
+                        "$status" in result) {
+                        const env = result;
+                        res.status(env.$status ?? 200).json(env.body);
+                    }
+                    else if (result === undefined) {
+                        res.status(204).end();
+                    }
+                    else {
+                        res.status(200).json(result);
+                    }
+                };
+                switch (verb) {
+                    case "get":
+                        expressApp.get(path, handler);
+                        break;
+                    case "post":
+                        expressApp.post(path, handler);
+                        break;
+                    case "put":
+                        expressApp.put(path, handler);
+                        break;
+                    case "patch":
+                        expressApp.patch(path, handler);
+                        break;
+                    case "delete":
+                        expressApp.delete(path, handler);
+                        break;
+                }
+            }
+            // Top-level error handler — catches throws from middleware.
+            expressApp.use((err, _req, res, _next) => {
+                const e = err;
+                res.status(typeof e.status === "number" ? e.status : 500).json({
+                    error: {
+                        code: e.code ?? "internal_error",
+                        summary: e.summary ?? e.message ?? "Internal error",
+                    },
+                });
+            });
+            server = http.createServer(expressApp);
+            await new Promise((resolve, reject) => {
+                server.once("error", reject);
+                server.listen(config.port ?? 3000, config.host ?? "0.0.0.0", () => {
+                    server.off("error", reject);
+                    resolve();
+                });
+            });
+            logger.info(`[express] listening on ${config.host ?? "0.0.0.0"}:${server.address().port}`);
+            ctx.addCheck({ name: "express", check: () => undefined });
+        },
+        async shutdown() {
+            if (server) {
+                await new Promise((resolve) => server.close(() => {
+                    resolve();
+                }));
+                server = undefined;
+            }
+            appInstance = undefined;
+        },
+    };
+}
+// ─── Foreign integration: expose Nwire as Express middleware ──────
+/**
+ * Build an Express Router from a Nwire App's wires. Mount it on an
+ * existing Express server to add Nwire routes alongside legacy handlers:
+ *
+ *   const nwireApp = buildNwireApp();
+ *   await nwireApp.start();
+ *   const router = nwireToExpressRouter(nwireApp);
+ *   expressApp.use("/api/nwire", router);
+ *
+ * The router uses the same dispatch path as `expressAdapter` — same
+ * validation, error envelope, container scoping — but doesn't boot its
+ * own HTTP server.
+ */
+export function nwireToExpressRouter(app, options = {}) {
+    const router = express.Router();
+    const logger = options.logger ?? new ConsoleLogger();
+    if (options.bodyParser !== false) {
+        router.use(express.json());
+    }
+    for (const wire of app.interface.wires) {
+        if (!isHttpBinding(wire.binding))
+            continue;
+        const binding = wire.binding;
+        const handler = async (req, res) => {
+            let input = {};
+            try {
+                if (binding.params)
+                    Object.assign(input, binding.params.parse(req.params));
+                if (binding.body)
+                    Object.assign(input, binding.body.parse(req.body));
+                if (binding.query)
+                    Object.assign(input, binding.query.parse(req.query));
+                if (!binding.params && !binding.body && !binding.query) {
+                    input = {
+                        ...req.params,
+                        ...req.body,
+                        ...req.query,
+                    };
+                }
+            }
+            catch (err) {
+                res.status(400).json({
+                    error: { code: "validation_failed", summary: err.message },
+                });
+                return;
+            }
+            const reqContainer = app.container.createScope();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const wireApp = wire.app ?? app;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const runtimeExecute = wireApp?.runtime?.execute;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const hasRunMethod = typeof wire.handler?.run === "function";
+            try {
+                let result;
+                if (runtimeExecute && hasRunMethod) {
+                    result = await runtimeExecute.call(wireApp.runtime, wire.handler, input, {});
+                }
+                else {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const fn = wire.handler.run ?? wire.handler;
+                    const ctx = {
+                        resolve: (name) => reqContainer.resolve(name),
+                        logger,
+                        req,
+                        res,
+                        envelope: {},
+                    };
+                    result = await fn(input, ctx);
+                }
+                if (result &&
+                    typeof result === "object" &&
+                    result.$kind === "response-instance") {
+                    const env = result;
+                    res.status(env.status ?? 200).json(env.body);
+                }
+                else if (result &&
+                    typeof result === "object" &&
+                    "$status" in result) {
+                    const env = result;
+                    res.status(env.$status ?? 200).json(env.body);
+                }
+                else if (result === undefined) {
+                    res.status(204).end();
+                }
+                else {
+                    res.status(200).json(result);
+                }
+            }
+            catch (err) {
+                const e = err;
+                res.status(typeof e.status === "number" ? e.status : 500).json({
+                    error: {
+                        code: e.code ?? "internal_error",
+                        summary: e.summary ?? e.message ?? "Internal error",
+                    },
+                });
+            }
+        };
+        switch (binding.verb) {
+            case "get":
+                router.get(binding.path, handler);
+                break;
+            case "post":
+                router.post(binding.path, handler);
+                break;
+            case "put":
+                router.put(binding.path, handler);
+                break;
+            case "patch":
+                router.patch(binding.path, handler);
+                break;
+            case "delete":
+                router.delete(binding.path, handler);
+                break;
+        }
+    }
+    return router;
+}
+// ─── Koa <-> Express middleware bridge ─────────────────────────────
+/**
+ * Wrap an Express middleware so it can be passed to `httpKoa({ middleware: [...] })`.
+ * Bridges the `(req, res, next)` Express contract into Koa's async chain.
+ */
+export function fromExpressMiddleware(mw) {
+    return async (kctx, next) => {
+        await new Promise((resolve, reject) => {
+            try {
+                mw(kctx.req, kctx.res, (err) => err ? reject(err) : resolve());
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+        await next();
+    };
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@nwire/express",
+  "version": "0.10.0",
+  "description": "Nwire — Express-backed HTTP adopter. expressAdapter() consumes wires with binding.$adapter==='http' and mounts them on an Express server; fromExpressMiddleware() bridges Express middleware into httpKoa's middleware chain.",
+  "keywords": [
+    "adopter",
+    "express",
+    "http",
+    "interop",
+    "nwire"
+  ],
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/http-express.js",
+  "types": "./dist/http-express.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/http-express.js",
+      "types": "./dist/http-express.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "express": "^5.1.0",
+    "@nwire/container": "0.10.0",
+    "@nwire/endpoint": "0.10.0",
+    "@nwire/wires": "0.10.0",
+    "@nwire/logger": "0.10.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.19.9",
+    "@types/supertest": "^6.0.3",
+    "supertest": "^7.2.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18",
+    "zod": "^4.0.0",
+    "@nwire/app": "0.10.0"
+  },
+  "peerDependencies": {
+    "express": "^4.0.0 || ^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc && node ../../scripts/fix-dist-extensions.mjs dist",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}