@kizunajs/express 2.0.0-beta.0

package/LICENSE.MD

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Sondre Ørland
+
+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,42 @@
+# @kizunajs/express
+
+`@kizunajs/express` connects a Kizuna API to an Express 5 application. It handles routing, request validation, body parsing, and error formatting, all driven by what you declared.
+
+**Requires Express >= 5.**
+
+## Installation
+
+```sh
+pnpm add @kizunajs/express express
+```
+
+## Usage
+
+```ts
+// kizuna.config.ts
+import { defineConfig } from 'kizunajs';
+import { expressAdapter } from '@kizunajs/express';
+import { routes } from './src/routes';
+
+export default defineConfig({
+    adapter: expressAdapter(),
+    routes,
+});
+```
+
+```ts
+// src/index.ts
+import express from 'express';
+import kizuna from '../kizuna.config';
+
+const app = express();
+app.use(express.json());
+
+kizuna.api.mount(app);
+
+app.listen(3000);
+```
+
+## Documentation
+
+[Express adapter](https://kizunajs.com/docs/adapters/express)

package/dist/index.cjs

@@ -0,0 +1,156 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let express = require("express");
+let node_stream = require("node:stream");
+let kizunajs_adapter = require("kizunajs/adapter");
+//#region src/server.ts
+const writeStream = (open, res, validate) => {
+	const controller = new AbortController();
+	res.on("close", () => {
+		if (!res.writableFinished) controller.abort();
+	});
+	res.flushHeaders();
+	const stream = open({
+		signal: controller.signal,
+		validate
+	});
+	(0, node_stream.pipeline)(node_stream.Readable.fromWeb(stream), res, () => void 0);
+};
+/**
+* Write a web `Response` to a node response. Plugins answer in web terms to stay
+* adapter-agnostic, so the translation belongs here.
+*/
+const writeWebResponse = async (response, res) => {
+	if (!(response instanceof globalThis.Response)) return;
+	res.status(response.status);
+	response.headers.forEach((value, name) => res.setHeader(name, value));
+	if (!response.body) {
+		res.end();
+		return;
+	}
+	node_stream.Readable.fromWeb(response.body).pipe(res);
+};
+const adapter = (0, kizunajs_adapter.createAdapter)({
+	buildHandlerContext: (adapterRequest, { res }) => ({
+		req: adapterRequest.request,
+		res
+	}),
+	respond: (result, { res, next, formatError, responseValidation }) => {
+		if (result.kind === "handler-error") {
+			next(result.error);
+			return;
+		}
+		if (result.kind === "raw-response") {
+			writeWebResponse(result.response, res);
+			return;
+		}
+		if (res.headersSent) return;
+		if (result.kind === "not-found" || result.kind === "method-not-allowed") {
+			next();
+			return;
+		}
+		const rendered = (0, kizunajs_adapter.renderJsonResult)(result, formatError, res.req);
+		for (const [key, value] of Object.entries(rendered.headers)) res.setHeader(key, value);
+		if (rendered.stream) {
+			res.status(rendered.status);
+			if (res.req.method === "HEAD") {
+				res.end();
+				return;
+			}
+			writeStream(rendered.stream, res, responseValidation);
+			return;
+		}
+		if (rendered.body === void 0) res.status(rendered.status).end();
+		else if (rendered.raw) {
+			const body = rendered.body;
+			res.status(rendered.status).send(typeof body === "string" || Buffer.isBuffer(body) ? body : Buffer.from(body));
+		} else res.status(rendered.status).json(rendered.body);
+	}
+});
+/**
+* Mount a Kizuna API onto an Express app.
+*
+* @example
+* api.mount(app);
+*/
+function mountExpress(api, app, options) {
+	const guards = api[kizunajs_adapter.GUARDS_META];
+	const schemes = api[kizunajs_adapter.SCHEMES_META];
+	const requestContext = api[kizunajs_adapter.REQUEST_CONTEXT_META];
+	const pluginExports = (0, kizunajs_adapter.pluginExportsOf)(api);
+	const jobsMeta = api[kizunajs_adapter.JOBS_META];
+	const jobRunner = (0, kizunajs_adapter.jobRunnerFrom)(jobsMeta);
+	const expressRouter = (0, express.Router)();
+	const mountRoute = (routeKey, route, routes, router) => {
+		expressRouter[route.method.toLowerCase()](route.path, (req, _res, next) => {
+			req.kizunaRoute = route;
+			next();
+		}, async (req, res, next) => {
+			const adapterRequest = {
+				request: req,
+				method: req.method,
+				resolution: {
+					kind: "pre-resolved",
+					routeKey,
+					route,
+					params: req.params
+				},
+				query: req.query,
+				headers: req.headers,
+				readBody: () => req.body
+			};
+			await adapter.handle({
+				routes,
+				router,
+				request: adapterRequest,
+				responseContext: {
+					res,
+					next,
+					formatError: options?.formatError,
+					responseValidation: options?.responseValidation
+				},
+				guards,
+				schemes,
+				requestContext,
+				pluginExports,
+				jobs: jobRunner,
+				responseValidation: options?.responseValidation
+			});
+		});
+	};
+	const mountLane = (routes, router) => {
+		const declaredRoutes = [...adapter.eachRoute(routes, router)].sort((left, right) => Number(right.route.method === "HEAD") - Number(left.route.method === "HEAD"));
+		for (const { routeKey, route } of declaredRoutes) mountRoute(routeKey, route, routes, router);
+	};
+	mountLane(api.routes, api[kizunajs_adapter.ROUTER_META]);
+	mountLane((0, kizunajs_adapter.pluginRoutesOf)(api), (0, kizunajs_adapter.pluginRouterOf)(api));
+	if (jobsMeta) {
+		const routes = (0, kizunajs_adapter.jobRoutes)(jobsMeta);
+		const router = (0, kizunajs_adapter.jobRouter)(jobsMeta);
+		for (const [routeKey, route] of Object.entries(routes)) mountRoute(routeKey, route, routes, router);
+	}
+	app.use(expressRouter);
+	return expressRouter;
+}
+/**
+* Serve an API on Express. What it takes is what every route is served with.
+*
+* @example
+* // kizuna.config.ts
+* export default defineConfig({
+*     adapter: expressAdapter(),
+*     routes,
+* });
+*
+* // src/index.ts
+* kizuna.api.mount(app);
+*/
+const expressAdapter = (defaults) => ({
+	name: "express",
+	mount: (api, app, options) => mountExpress(api, app, {
+		...defaults,
+		...options
+	})
+});
+//#endregion
+exports.expressAdapter = expressAdapter;
+exports.mountExpress = mountExpress;

package/dist/index.d.cts

@@ -0,0 +1,68 @@
+import { Request, Response, Router } from "express";
+import { Adapter, ApiWithRouter, ErrorFormatter, GUARDS_META, JOBS_META, REQUEST_CONTEXT_META, RouteDefinition, Routes, SCHEMES_META } from "kizunajs/adapter";
+
+//#region src/server.d.ts
+type ExpressApi<R extends Routes = Routes> = ApiWithRouter<R> & {
+  readonly [GUARDS_META]?: unknown;
+  readonly [SCHEMES_META]?: unknown;
+  readonly [REQUEST_CONTEXT_META]?: unknown;
+  readonly [JOBS_META]?: unknown;
+  /**
+   * Register every route on an Express app or router.
+   */
+  mount: (app: AppLike, options?: ExpressOptions) => Router;
+};
+/**
+ * The Express request and response passed to each handler.
+ */
+interface ExpressHandlerContext {
+  req: Request;
+  res: Response;
+}
+declare global {
+  namespace Express {
+    interface Request {
+      kizunaRoute?: RouteDefinition;
+    }
+  }
+}
+interface ExpressOptions {
+  /**
+   * Validate handler return values against the route's response schemas.
+   * Mismatches surface as 500 errors. Enable in development.
+   *
+   * @default false
+   */
+  responseValidation?: boolean;
+  /**
+   * Reshape error (status >= 400) response bytes before they are sent. See
+   * {@link ErrorFormatter}.
+   */
+  formatError?: ErrorFormatter<Request>;
+}
+interface AppLike {
+  use: (router: Router) => unknown;
+}
+/**
+ * Mount a Kizuna API onto an Express app.
+ *
+ * @example
+ * api.mount(app);
+ */
+declare function mountExpress(api: ExpressApi, app: AppLike, options?: ExpressOptions): Router;
+/**
+ * Serve an API on Express. What it takes is what every route is served with.
+ *
+ * @example
+ * // kizuna.config.ts
+ * export default defineConfig({
+ *     adapter: expressAdapter(),
+ *     routes,
+ * });
+ *
+ * // src/index.ts
+ * kizuna.api.mount(app);
+ */
+declare const expressAdapter: (defaults?: ExpressOptions) => Adapter<ExpressHandlerContext, [app: AppLike, options?: ExpressOptions], Router>;
+//#endregion
+export { AppLike, ExpressApi, ExpressHandlerContext, ExpressOptions, expressAdapter, mountExpress };

package/dist/index.d.mts

@@ -0,0 +1,68 @@
+import { Request, Response, Router } from "express";
+import { Adapter, ApiWithRouter, ErrorFormatter, GUARDS_META, JOBS_META, REQUEST_CONTEXT_META, RouteDefinition, Routes, SCHEMES_META } from "kizunajs/adapter";
+
+//#region src/server.d.ts
+type ExpressApi<R extends Routes = Routes> = ApiWithRouter<R> & {
+  readonly [GUARDS_META]?: unknown;
+  readonly [SCHEMES_META]?: unknown;
+  readonly [REQUEST_CONTEXT_META]?: unknown;
+  readonly [JOBS_META]?: unknown;
+  /**
+   * Register every route on an Express app or router.
+   */
+  mount: (app: AppLike, options?: ExpressOptions) => Router;
+};
+/**
+ * The Express request and response passed to each handler.
+ */
+interface ExpressHandlerContext {
+  req: Request;
+  res: Response;
+}
+declare global {
+  namespace Express {
+    interface Request {
+      kizunaRoute?: RouteDefinition;
+    }
+  }
+}
+interface ExpressOptions {
+  /**
+   * Validate handler return values against the route's response schemas.
+   * Mismatches surface as 500 errors. Enable in development.
+   *
+   * @default false
+   */
+  responseValidation?: boolean;
+  /**
+   * Reshape error (status >= 400) response bytes before they are sent. See
+   * {@link ErrorFormatter}.
+   */
+  formatError?: ErrorFormatter<Request>;
+}
+interface AppLike {
+  use: (router: Router) => unknown;
+}
+/**
+ * Mount a Kizuna API onto an Express app.
+ *
+ * @example
+ * api.mount(app);
+ */
+declare function mountExpress(api: ExpressApi, app: AppLike, options?: ExpressOptions): Router;
+/**
+ * Serve an API on Express. What it takes is what every route is served with.
+ *
+ * @example
+ * // kizuna.config.ts
+ * export default defineConfig({
+ *     adapter: expressAdapter(),
+ *     routes,
+ * });
+ *
+ * // src/index.ts
+ * kizuna.api.mount(app);
+ */
+declare const expressAdapter: (defaults?: ExpressOptions) => Adapter<ExpressHandlerContext, [app: AppLike, options?: ExpressOptions], Router>;
+//#endregion
+export { AppLike, ExpressApi, ExpressHandlerContext, ExpressOptions, expressAdapter, mountExpress };

package/dist/index.mjs

@@ -0,0 +1,154 @@
+import { Router } from "express";
+import { Readable, pipeline } from "node:stream";
+import { GUARDS_META, JOBS_META, REQUEST_CONTEXT_META, ROUTER_META, SCHEMES_META, createAdapter, jobRouter, jobRoutes, jobRunnerFrom, pluginExportsOf, pluginRouterOf, pluginRoutesOf, renderJsonResult } from "kizunajs/adapter";
+//#region src/server.ts
+const writeStream = (open, res, validate) => {
+	const controller = new AbortController();
+	res.on("close", () => {
+		if (!res.writableFinished) controller.abort();
+	});
+	res.flushHeaders();
+	const stream = open({
+		signal: controller.signal,
+		validate
+	});
+	pipeline(Readable.fromWeb(stream), res, () => void 0);
+};
+/**
+* Write a web `Response` to a node response. Plugins answer in web terms to stay
+* adapter-agnostic, so the translation belongs here.
+*/
+const writeWebResponse = async (response, res) => {
+	if (!(response instanceof globalThis.Response)) return;
+	res.status(response.status);
+	response.headers.forEach((value, name) => res.setHeader(name, value));
+	if (!response.body) {
+		res.end();
+		return;
+	}
+	Readable.fromWeb(response.body).pipe(res);
+};
+const adapter = createAdapter({
+	buildHandlerContext: (adapterRequest, { res }) => ({
+		req: adapterRequest.request,
+		res
+	}),
+	respond: (result, { res, next, formatError, responseValidation }) => {
+		if (result.kind === "handler-error") {
+			next(result.error);
+			return;
+		}
+		if (result.kind === "raw-response") {
+			writeWebResponse(result.response, res);
+			return;
+		}
+		if (res.headersSent) return;
+		if (result.kind === "not-found" || result.kind === "method-not-allowed") {
+			next();
+			return;
+		}
+		const rendered = renderJsonResult(result, formatError, res.req);
+		for (const [key, value] of Object.entries(rendered.headers)) res.setHeader(key, value);
+		if (rendered.stream) {
+			res.status(rendered.status);
+			if (res.req.method === "HEAD") {
+				res.end();
+				return;
+			}
+			writeStream(rendered.stream, res, responseValidation);
+			return;
+		}
+		if (rendered.body === void 0) res.status(rendered.status).end();
+		else if (rendered.raw) {
+			const body = rendered.body;
+			res.status(rendered.status).send(typeof body === "string" || Buffer.isBuffer(body) ? body : Buffer.from(body));
+		} else res.status(rendered.status).json(rendered.body);
+	}
+});
+/**
+* Mount a Kizuna API onto an Express app.
+*
+* @example
+* api.mount(app);
+*/
+function mountExpress(api, app, options) {
+	const guards = api[GUARDS_META];
+	const schemes = api[SCHEMES_META];
+	const requestContext = api[REQUEST_CONTEXT_META];
+	const pluginExports = pluginExportsOf(api);
+	const jobsMeta = api[JOBS_META];
+	const jobRunner = jobRunnerFrom(jobsMeta);
+	const expressRouter = Router();
+	const mountRoute = (routeKey, route, routes, router) => {
+		expressRouter[route.method.toLowerCase()](route.path, (req, _res, next) => {
+			req.kizunaRoute = route;
+			next();
+		}, async (req, res, next) => {
+			const adapterRequest = {
+				request: req,
+				method: req.method,
+				resolution: {
+					kind: "pre-resolved",
+					routeKey,
+					route,
+					params: req.params
+				},
+				query: req.query,
+				headers: req.headers,
+				readBody: () => req.body
+			};
+			await adapter.handle({
+				routes,
+				router,
+				request: adapterRequest,
+				responseContext: {
+					res,
+					next,
+					formatError: options?.formatError,
+					responseValidation: options?.responseValidation
+				},
+				guards,
+				schemes,
+				requestContext,
+				pluginExports,
+				jobs: jobRunner,
+				responseValidation: options?.responseValidation
+			});
+		});
+	};
+	const mountLane = (routes, router) => {
+		const declaredRoutes = [...adapter.eachRoute(routes, router)].sort((left, right) => Number(right.route.method === "HEAD") - Number(left.route.method === "HEAD"));
+		for (const { routeKey, route } of declaredRoutes) mountRoute(routeKey, route, routes, router);
+	};
+	mountLane(api.routes, api[ROUTER_META]);
+	mountLane(pluginRoutesOf(api), pluginRouterOf(api));
+	if (jobsMeta) {
+		const routes = jobRoutes(jobsMeta);
+		const router = jobRouter(jobsMeta);
+		for (const [routeKey, route] of Object.entries(routes)) mountRoute(routeKey, route, routes, router);
+	}
+	app.use(expressRouter);
+	return expressRouter;
+}
+/**
+* Serve an API on Express. What it takes is what every route is served with.
+*
+* @example
+* // kizuna.config.ts
+* export default defineConfig({
+*     adapter: expressAdapter(),
+*     routes,
+* });
+*
+* // src/index.ts
+* kizuna.api.mount(app);
+*/
+const expressAdapter = (defaults) => ({
+	name: "express",
+	mount: (api, app, options) => mountExpress(api, app, {
+		...defaults,
+		...options
+	})
+});
+//#endregion
+export { expressAdapter, mountExpress };

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@kizunajs/express",
+  "version": "2.0.0-beta.0",
+  "description": "Express adapter for Kizuna.js",
+  "keywords": [
+    "kizunajs",
+    "typescript",
+    "zod",
+    "openapi",
+    "spec-driven",
+    "type-safe",
+    "rest",
+    "api",
+    "express",
+    "adapter",
+    "server"
+  ],
+  "license": "MIT",
+  "homepage": "https://kizunajs.com/docs/adapters/express",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kizunajs/kizuna.git",
+    "directory": "packages/express"
+  },
+  "bugs": "https://github.com/kizunajs/kizuna/issues",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "kizuna": {
+    "entries": {
+      ".": "server"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "express": "^5.0.0",
+    "zod": "^4.0.0",
+    "kizunajs": "2.0.0-beta.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "express": "^5.0.0",
+    "tsdown": "^0.21.0",
+    "typescript": "^6.0.3",
+    "zod": "^4.0.0",
+    "kizunajs": "2.0.0-beta.0"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm,cjs --dts --clean --external kizunajs --external express --external zod",
+    "typecheck": "tsc --noEmit"
+  }
+}