@ibabkin/openapi-express-server 1.1.0

package/README.md

@@ -0,0 +1,58 @@
+# @ibabkin/openapi-express-server
+
+Express.js building blocks for wiring routes from an OpenAPI spec to controllers resolved from a
+[`ts-ioc-container`](https://github.com/IgorBabkin/ts-ioc-container) scope. Pairs with
+`@ibabkin/openapi-to-server` (controller interfaces) and `@ibabkin/openapi-to-zod`
+(Zod payload validators).
+
+## Exports
+
+- `extractRoutes(spec)` — flattens an `OpenAPIV3.Document` into `RouteMetadata[]` (path, method, operationId, controller/method names derived from the first tag and `operationId`)
+- `convertOpenAPIPathToExpress(path)` — `/users/{id}` → `/users/:id`
+- `buildPayload(req)` — picks `params`, `query`, `body`, `headers` off an Express request
+- `containerMiddleware(appContainer)` — creates a request-scoped child container, attaches it to `req.container`, and disposes it when the response finishes
+- `getContainerOrFail(req)` — reads `req.container` or throws
+
+## Usage
+
+Register controllers in an application container keyed by their OpenAPI tag, then register one Express route per
+operation. A reference `RouteBuilder` that does exactly this lives in [`__tests__/RouteBuilder.ts`](./__tests__/RouteBuilder.ts):
+
+```typescript
+import 'reflect-metadata';
+import express from 'express';
+import { Container, Registration } from 'ts-ioc-container';
+import { containerMiddleware } from '@ibabkin/openapi-express-server';
+import { PAYLOADS } from './generated-validators';
+import { RouteBuilder } from './RouteBuilder';
+
+const container = new Container({ tags: ['application'] });
+container.addRegistration(Registration.fromClass(UsersController).bindToKey('Users'));
+
+const app = express();
+app.use(express.json());
+app.use(containerMiddleware(container));
+
+container.resolve(RouteBuilder, { args: [spec, PAYLOADS] }).applyTo(app);
+
+app.use((error, req, res, next) => {
+  res.status(error instanceof ZodError ? 400 : 500).json({ error: error.message });
+});
+```
+
+Each request resolves the controller from the request scope, validates `req` with the Zod schema for the
+`operationId`, calls `controller[methodName](payload)`, and writes `{ status, headers, body }` to the response.
+
+## Development
+
+```bash
+pnpm build
+pnpm test
+```
+
+`__tests__/integration/generated.spec.ts` generates types and validators from `__tests__/integration/api.yaml` at
+test time and runs an end-to-end server against them.
+
+## License
+
+ISC

package/esm/containerMiddleware.d.ts

@@ -0,0 +1,5 @@
+import { RequestHandler, Request } from 'express-serve-static-core';
+import { IContainer } from 'ts-ioc-container';
+export declare function containerMiddleware(appContainer: IContainer): RequestHandler;
+export declare function getContainerOrFail(req: Request): IContainer;
+//# sourceMappingURL=containerMiddleware.d.ts.map

package/esm/containerMiddleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"containerMiddleware.d.ts","sourceRoot":"","sources":["../lib/containerMiddleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,UAAU,GAAG,cAAc,CAsB5E;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,cAK9C"}

package/esm/containerMiddleware.js

@@ -0,0 +1,26 @@
+export function containerMiddleware(appContainer) {
+    return (req, res, next) => {
+        // Create request-scoped container
+        const requestScope = appContainer.createScope({ tags: ['request'] });
+        // Attach to request
+        req.container = requestScope;
+        // Cleanup on response finish
+        res.on('finish', () => {
+            requestScope.dispose();
+        });
+        // Cleanup on error
+        res.on('close', () => {
+            if (!res.writableEnded) {
+                requestScope.dispose();
+            }
+        });
+        next();
+    };
+}
+export function getContainerOrFail(req) {
+    if (!req.container) {
+        throw new Error(`Container is not provided`);
+    }
+    return req.container;
+}
+//# sourceMappingURL=containerMiddleware.js.map

package/esm/containerMiddleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"containerMiddleware.js","sourceRoot":"","sources":["../lib/containerMiddleware.ts"],"names":[],"mappings":"AAGA,MAAM,UAAU,mBAAmB,CAAC,YAAwB;IAC1D,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QACxB,kCAAkC;QAClC,MAAM,YAAY,GAAG,YAAY,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QAErE,oBAAoB;QACpB,GAAG,CAAC,SAAS,GAAG,YAAY,CAAC;QAE7B,6BAA6B;QAC7B,GAAG,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;YACpB,YAAY,CAAC,OAAO,EAAE,CAAC;QACzB,CAAC,CAAC,CAAC;QAEH,mBAAmB;QACnB,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACnB,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC;gBACvB,YAAY,CAAC,OAAO,EAAE,CAAC;YACzB,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,GAAY;IAC7C,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,GAAG,CAAC,SAAS,CAAC;AACvB,CAAC"}

package/esm/index.d.ts

@@ -0,0 +1,5 @@
+export { OpenAPIServerConfig, RouteMetadata, ErrorHandler, ControllerInstance } from './types.js';
+export { buildPayload, Payload } from './payloadBuilder.js';
+export { extractRoutes, convertOpenAPIPathToExpress } from './routeExtractor.js';
+export { containerMiddleware, getContainerOrFail } from './containerMiddleware.js';
+//# sourceMappingURL=index.d.ts.map

package/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAClG,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC"}

package/esm/index.js

@@ -0,0 +1,4 @@
+export { buildPayload } from './payloadBuilder.js';
+export { extractRoutes, convertOpenAPIPathToExpress } from './routeExtractor.js';
+export { containerMiddleware, getContainerOrFail } from './containerMiddleware.js';
+//# sourceMappingURL=index.js.map

package/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAW,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC"}

package/esm/payloadBuilder.d.ts

@@ -0,0 +1,9 @@
+import { Request } from 'express';
+export interface Payload {
+    params?: Record<string, any>;
+    query?: Record<string, any>;
+    body?: any;
+    headers?: Record<string, any>;
+}
+export declare function buildPayload(req: Request): Payload;
+//# sourceMappingURL=payloadBuilder.d.ts.map

package/esm/payloadBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payloadBuilder.d.ts","sourceRoot":"","sources":["../lib/payloadBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAElC,MAAM,WAAW,OAAO;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,IAAI,CAAC,EAAE,GAAG,CAAC;IACX,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC/B;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAoBlD"}

package/esm/payloadBuilder.js

@@ -0,0 +1,17 @@
+export function buildPayload(req) {
+    const payload = {};
+    if (req.params && Object.keys(req.params).length > 0) {
+        payload.params = req.params;
+    }
+    if (req.query && Object.keys(req.query).length > 0) {
+        payload.query = req.query;
+    }
+    if (req.body !== undefined && req.body !== null) {
+        payload.body = req.body;
+    }
+    if (req.headers && Object.keys(req.headers).length > 0) {
+        payload.headers = req.headers;
+    }
+    return payload;
+}
+//# sourceMappingURL=payloadBuilder.js.map

package/esm/payloadBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payloadBuilder.js","sourceRoot":"","sources":["../lib/payloadBuilder.ts"],"names":[],"mappings":"AASA,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,MAAM,OAAO,GAAY,EAAE,CAAC;IAE5B,IAAI,GAAG,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrD,OAAO,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;IAC9B,CAAC;IAED,IAAI,GAAG,CAAC,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnD,OAAO,CAAC,KAAK,GAAG,GAAG,CAAC,KAA4B,CAAC;IACnD,CAAC;IAED,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IAC1B,CAAC;IAED,IAAI,GAAG,CAAC,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvD,OAAO,CAAC,OAAO,GAAG,GAAG,CAAC,OAA8B,CAAC;IACvD,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/esm/routeExtractor.d.ts

@@ -0,0 +1,5 @@
+import { OpenAPIV3 } from 'openapi-types';
+import { RouteMetadata } from './types.js';
+export declare function extractRoutes(spec: OpenAPIV3.Document): RouteMetadata[];
+export declare function convertOpenAPIPathToExpress(openApiPath: string): string;
+//# sourceMappingURL=routeExtractor.d.ts.map

package/esm/routeExtractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routeExtractor.d.ts","sourceRoot":"","sources":["../lib/routeExtractor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,CAAC,QAAQ,GAAG,aAAa,EAAE,CA0CvE;AAMD,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEvE"}

package/esm/routeExtractor.js

@@ -0,0 +1,41 @@
+export function extractRoutes(spec) {
+    const routes = [];
+    if (!spec.paths) {
+        return routes;
+    }
+    for (const [path, pathItem] of Object.entries(spec.paths)) {
+        if (!pathItem)
+            continue;
+        const methods = ['get', 'post', 'put', 'patch', 'delete', 'options', 'head'];
+        for (const method of methods) {
+            const operation = pathItem[method];
+            if (!operation || !operation.operationId) {
+                continue;
+            }
+            const tags = operation.tags || [];
+            const firstTag = tags[0];
+            if (!firstTag) {
+                console.warn(`Operation ${operation.operationId} has no tags, skipping`);
+                continue;
+            }
+            const controllerName = capitalizeFirst(firstTag);
+            const methodName = operation.operationId;
+            routes.push({
+                path,
+                method: method.toUpperCase(),
+                operationId: operation.operationId,
+                tags,
+                controllerName,
+                methodName,
+            });
+        }
+    }
+    return routes;
+}
+function capitalizeFirst(str) {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+}
+export function convertOpenAPIPathToExpress(openApiPath) {
+    return openApiPath.replace(/{([^}]+)}/g, ':$1');
+}
+//# sourceMappingURL=routeExtractor.js.map

package/esm/routeExtractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routeExtractor.js","sourceRoot":"","sources":["../lib/routeExtractor.ts"],"names":[],"mappings":"AAGA,MAAM,UAAU,aAAa,CAAC,IAAwB;IACpD,MAAM,MAAM,GAAoB,EAAE,CAAC;IAEnC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;QAChB,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1D,IAAI,CAAC,QAAQ;YAAE,SAAS;QAExB,MAAM,OAAO,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,CAAU,CAAC;QAEtF,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAA0C,CAAC;YAE5E,IAAI,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC;gBACzC,SAAS;YACX,CAAC;YAED,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,IAAI,EAAE,CAAC;YAClC,MAAM,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;YAEzB,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,OAAO,CAAC,IAAI,CAAC,aAAa,SAAS,CAAC,WAAW,wBAAwB,CAAC,CAAC;gBACzE,SAAS;YACX,CAAC;YAED,MAAM,cAAc,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;YACjD,MAAM,UAAU,GAAG,SAAS,CAAC,WAAW,CAAC;YAEzC,MAAM,CAAC,IAAI,CAAC;gBACV,IAAI;gBACJ,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE;gBAC5B,WAAW,EAAE,SAAS,CAAC,WAAW;gBAClC,IAAI;gBACJ,cAAc;gBACd,UAAU;aACX,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,eAAe,CAAC,GAAW;IAClC,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,WAAmB;IAC7D,OAAO,WAAW,CAAC,OAAO,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;AAClD,CAAC"}

package/esm/types.d.ts

@@ -0,0 +1,29 @@
+import { Request, Response, NextFunction } from 'express';
+import { OpenAPIV3 } from 'openapi-types';
+import { IContainer } from 'ts-ioc-container';
+export interface OpenAPIServerConfig {
+    spec: OpenAPIV3.Document;
+    controllers: Record<string, any>;
+    basePath?: string;
+    errorHandler?: ErrorHandler;
+}
+export interface RouteMetadata {
+    path: string;
+    method: string;
+    operationId: string;
+    tags: string[];
+    controllerName: string;
+    methodName: string;
+}
+export type ErrorHandler = (error: Error, req: Request, res: Response, next: NextFunction) => void;
+export interface ControllerInstance {
+    [methodName: string]: (payload: any) => Promise<any>;
+}
+declare global {
+    namespace Express {
+        interface Request {
+            container: IContainer;
+        }
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/esm/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../lib/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC,QAAQ,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,KAAK,IAAI,CAAC;AAEnG,MAAM,WAAW,kBAAkB;IACjC,CAAC,UAAU,EAAE,MAAM,GAAG,CAAC,OAAO,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;CACtD;AAED,OAAO,CAAC,MAAM,CAAC;IAEb,UAAU,OAAO,CAAC;QAChB,UAAU,OAAO;YACf,SAAS,EAAE,UAAU,CAAC;SACvB;KACF;CACF"}

package/esm/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/esm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../lib/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@ibabkin/openapi-express-server",
+  "version": "1.1.0",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "description": "Express.js server implementation for OpenAPI-generated interfaces",
+  "keywords": [
+    "openapi",
+    "swagger",
+    "express",
+    "server",
+    "typescript"
+  ],
+  "author": "ibabkin <igba14@gmail.com>",
+  "homepage": "https://github.com/IgorBabkin/openapi-to-server/tree/master/packages/openapi-express-server",
+  "license": "ISC",
+  "type": "module",
+  "main": "esm/index.js",
+  "types": "esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./esm/index.js",
+      "types": "./esm/index.d.ts"
+    }
+  },
+  "module": "esm/index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IgorBabkin/openapi-to-server.git"
+  },
+  "directories": {
+    "lib": "lib",
+    "test": "__tests__"
+  },
+  "files": [
+    "esm/**/*"
+  ],
+  "scripts": {
+    "build": "pnpm run clean && pnpm run build:ts",
+    "test": "jest",
+    "test:generate:code": "tsx ./__tests__/generate.ts && prettier --write __tests__/controller-interfaces.ts __tests__/validators.ts",
+    "test:watch": "jest --coverage --watch",
+    "clean": "rimraf esm *.tsbuildinfo",
+    "watch": "nodemon --watch lib --exec 'pnpm run compile'",
+    "build:ts": "tsc -p tsconfig.prod.json"
+  },
+  "dependencies": {
+    "@ibabkin/openapi-to-server": "workspace:*",
+    "@ibabkin/openapi-to-zod": "workspace:*",
+    "express": "^4.18.2",
+    "js-yaml": "^4.1.0",
+    "reflect-metadata": "^0.2.2",
+    "ts-ioc-container": "^46.8.0",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@jest/test-sequencer": "29.7.0",
+    "@types/express": "^4.17.21",
+    "@types/jest": "29.5.14",
+    "@types/js-yaml": "^4.0.5",
+    "@types/node": "^20.10.0",
+    "@types/supertest": "^6.0.2",
+    "jest": "29.7.0",
+    "openapi-types": "^12.1.0",
+    "rimraf": "3.0.2",
+    "supertest": "^6.3.3",
+    "ts-jest": "29.2.5",
+    "tsx": "^4.21.0",
+    "typescript": "5.7.3"
+  }
+}