Express compatibility shim

The ingenium-compat package wraps (req, res, next) middleware so it can run inside a Ingenium middleware chain. The req and res shims expose enough surface for header-stamping, cookie parsing, simple body work, and short-circuit responses.

Install

npm install ingenium ingenium-compat cors helmet

Usage

import { ingenium } from 'ingenium'
import { expressCompat } from 'ingenium-compat'
import cors from 'cors'
import helmet from 'helmet'

const app = ingenium()
app.use(expressCompat(cors({ origin: 'https://app.example.com' })))
app.use(expressCompat(helmet()))

Compatibility status

Validated end-to-end in packages/ingenium-compat/test/e2e.test.ts:

Middleware	Status	Notes
`cors`	supported	full feature parity
`helmet`	supported	full feature parity
`cookie-parser`	supported	`req.cookies` populated, mirrored to `ctx.state`
`passport.initialize`	supported	`passport.authenticate` is partial (depends on session)
`morgan`	partial	logging works; `:response-time` token may be inaccurate
`express-rate-limit`	partial	works with `validate: false` and a custom `keyGenerator`
`compression`	unsupported	needs `res.write`/`res.end` ownership the shim doesn't proxy - use a reverse proxy
`body-parser`	unsupported	use native `ctx.body.json()` / `ctx.body.urlencoded()`
`express-session`	unsupported	silently no-ops - use native `sessionMiddleware`
`multer`	unsupported	owns the request stream - use native `ctx.body.multipart()`

Fail-loud on known-broken middleware

expressCompat(bodyParser.json()) throws a TypeError at registration. Silent failures of express-session, multer, body-parser, and compression now point at the native equivalent rather than misbehaving at runtime.

Opt out per call with { allowKnownBroken: true }:

app.use(expressCompat(compression(), { allowKnownBroken: true }))

You almost certainly don't want this - the native primitives exist for a reason. Use a reverse proxy for compression and the native session middleware / body parsing / multipart APIs for everything else.

Where to next?

Migration from Express - the side-by-side diff.
Body parsing - the native replacement for body-parser and multer.
Sessions - the native replacement for express-session.
Production hardening - the full prod wiring.