exegesis-express

exegesis-express is a thin Express-specific adapter for exegesis, a library that turns an OpenAPI 3.x document into a full request-handling pipeline: routing, parameter parsing, security enforcement, and optional response validation. Rather than reimplementing any of that, this package’s single middleware() export compiles your spec via exegesis.compileApi() and hands back a standard Express/connect middleware function.

Because exegesis owns request parsing, exegesis-express needs to sit ahead of any body-parser middleware in your stack, reading the raw body itself for JSON and URL-encoded payloads. Controllers are wired up declaratively through the x-exegesis-controller OpenAPI extension, so routing logic lives in the spec instead of a separate Express router, and the middleware factory supports both Promise and Node-style callback calling conventions.

What You Get

• An async middleware(openApiDoc, options) factory that compiles your OpenAPI 3.x document into an Express-compatible middleware function.
• Built-in request body parsing for application/json and application/x-www-form-urlencoded, without needing separate body-parser middleware.
• Response validation via onResponseValidationError, catching contract violations before they reach the client.
• Security scheme wiring to custom authenticator functions, plus a plugin system for cross-cutting concerns like role-based auth or CORS.
• A dual callback/Promise API so it drops into both modern async/await codebases and legacy callback-based Express apps.

Common Use Cases

• Enforcing an OpenAPI 3.x contract on an existing Express API without hand-writing validation middleware.
• Wiring OpenAPI security requirements (API keys, OAuth2, etc.) to custom authenticator functions.
• Adding response validation in staging/test environments to catch spec drift before it reaches consumers.
• Building spec-first Express services where the x-exegesis-controller extension maps OpenAPI paths directly to controller modules.

Under The Hood

Architecture The entire package is a single src/index.ts file that re-exports all types from the core exegesis package and exposes one middleware() function with two overloads — a Promise-returning form and a Node-style callback form — both of which simply forward to exegesis.compileApi(). All routing, parameter parsing, security, and validation logic lives in the upstream exegesis package; this repo’s sole responsibility is the Express-specific glue and the dual calling convention, giving it a clean, narrow boundary with almost no surface area of its own.

Tech Stack Written in TypeScript and compiled with tsc, the package’s only runtime dependency is exegesis itself; express appears solely as a dev dependency for the test suite. Tooling is conventional for a small TypeScript library: ESLint with @typescript-eslint, Prettier, Husky and lint-staged for pre-commit checks, and semantic-release for automated versioning and publishing, wired together through GitHub Actions CI.

Code Quality Two test files (integrationTest.ts, callbackTest.ts) exercise both the Promise and callback entry points against a real Express app and a sample OpenAPI document with controllers, using Mocha, Chai, chai-as-promised, and supertest-fetch, with nyc collecting coverage. TypeScript’s strict mode is enabled project-wide, and ESLint runs over both src and test. Test coverage is reasonable for the package’s small scope, though it is limited to integration-style checks rather than isolated unit tests of edge cases.

What Makes It Unique The package’s main deliberate design choice is offering both a Promise-based and a Node-style callback-based signature for the same middleware() call, letting adopters bridge older callback-oriented Express codebases without a wrapper. Beyond that dual-API ergonomics, the package introduces no novel technical ideas of its own — it is a conventional, minimal Express binding for the OpenAPI-processing logic that lives in the separate exegesis core library.