express-fastify-runtime 0.1.0 → 0.1.1

package/README.md

@@ -1,5 +1,10 @@
 # express-fastify-runtime
 
+[![npm version](https://img.shields.io/npm/v/express-fastify-runtime.svg)](https://www.npmjs.com/package/express-fastify-runtime)
+[![license](https://img.shields.io/npm/l/express-fastify-runtime.svg)](./LICENSE)
+
+<!-- [![npm downloads](https://img.shields.io/npm/dm/express-fastify-runtime.svg)](https://www.npmjs.com/package/express-fastify-runtime) -->
+
 > Your Express app. Fastify's speed. One line. No rewrite.
 
 ```ts
@@ -9,7 +14,7 @@ import express from "express";
 const app = express();
 app.get("/", (req, res) => res.json({ hello: "world" }));
 
-fast(app).listen({ port: 3000 });   // 👈 that's the whole trick
+fast(app).listen({ port: 3000 }); // 👈 that's the whole trick
 ```
 
 ---
@@ -17,18 +22,18 @@ fast(app).listen({ port: 3000 });   // 👈 that's the whole trick
 ## A short, slightly emotional story
 
 I love Express. I love it the way you love a comfortable pair of shoes — `req`, `res`,
-`next`, a thousand middlewares on npm, and muscle memory built over years. Express is *home*.
+`next`, a thousand middlewares on npm, and muscle memory built over years. Express is _home_.
 
 Then one day someone showed me a Fastify benchmark and my coffee went cold. "Two-ish times the
 throughput," they said, smiling like they'd discovered fire. And I thought: do I really have to
 abandon my comfortable shoes and rewrite everything in a new framework just to go faster?
 
 So I went looking for a shortcut. I found tools that "run Express on Fastify" — and many of them
-do *exactly* one thing: they hand your Express app to Fastify and let Fastify… call Express for
+do _exactly_ one thing: they hand your Express app to Fastify and let Fastify… call Express for
 every request. Your app technically runs "on Fastify." It is not one bit faster. It's a very
 polite handshake between two frameworks where nothing actually changes. Cool sticker, no engine.
 
-**`express-fastify-runtime` is the engine.** It doesn't just *expose* your Express app to
+**`express-fastify-runtime` is the engine.** It doesn't just _expose_ your Express app to
 Fastify — it **compiles** your safe routes and middleware onto Fastify's real request pipeline,
 and only falls back to actual Express for the things that genuinely need it (multipart uploads,
 `res.render`, streaming bodies, anything unusual). You keep writing Express. It actually gets
@@ -55,8 +60,16 @@ You don't rewrite a thing. You wrap one line. Your shoes stay on.
 
 ## Install
 
+[**express-fastify-runtime** on npm](https://www.npmjs.com/package/express-fastify-runtime)
+
 ```bash
 npm install express-fastify-runtime
+# or
+pnpm add express-fastify-runtime
+# or
+yarn add express-fastify-runtime
+# or
+bun add express-fastify-runtime
 ```
 
 `express` is a **peer dependency** — bring your own (`^4.18` or `^5`). `fast()` uses whatever
@@ -74,26 +87,27 @@ Express you already have.
 You wrote a normal Express app. Wrap it. Done.
 
 ```ts
-import "express-fastify-runtime";        // load first (the one rule)
+import "express-fastify-runtime"; // load first (the one rule)
 import express from "express";
 import morgan from "morgan";
 import helmet from "helmet";
 import { fast } from "express-fastify-runtime";
 
 const app = express();
-app.use(morgan("tiny"));                 // logs, correctly, per request
-app.use(helmet());                       // security headers, intact
-app.use(express.json());                 // parsed by Fastify's fast parser under the hood
+app.use(morgan("tiny")); // logs, correctly, per request
+app.use(helmet()); // security headers, intact
+app.use(express.json()); // parsed by Fastify's fast parser under the hood
 
 app.get("/users/:id", (req, res) => {
   res.json({ id: req.params.id });
 });
 
-app.use((err, req, res, next) => {       // your error middleware still works
+app.use((err, req, res, next) => {
+  // your error middleware still works
   res.status(500).json({ error: err.message });
 });
 
-const fastApp = fast(app);               // returns a Fastify instance
+const fastApp = fast(app); // returns a Fastify instance
 fastApp.listen({ port: 3000 });
 ```
 
@@ -115,9 +129,9 @@ import { fast } from "express-fastify-runtime";
 const app = express();
 app.get("/", (req, res) => res.json({ ok: true }));
 
-const fastApp = fast(app, { fastify: { logger: true } });   // pass Fastify options through
-await fastApp.register(rateLimit, { max: 100 });            // real Fastify plugins
-await fastApp.ready();                                       // let plugins load before listen
+const fastApp = fast(app, { fastify: { logger: true } }); // pass Fastify options through
+await fastApp.register(rateLimit, { max: 100 }); // real Fastify plugins
+await fastApp.ready(); // let plugins load before listen
 await fastApp.listen({ port: 3000 });
 ```
 
@@ -128,7 +142,7 @@ Fastify's full lifecycle (so 404s and internals work):
 
 ```ts
 const fastApp = fast(app);
-const server = fastApp.server;            // http.Server
+const server = fastApp.server; // http.Server
 server.listen(3000, () => console.log("up on 3000"));
 ```
 
@@ -141,8 +155,10 @@ Node app — attach your socket server to `fastApp.server`:
 import { Server as IOServer } from "socket.io";
 
 const fastApp = fast(app);
-const io = new IOServer(fastApp.server);  // share the same HTTP server
-io.on("connection", (socket) => socket.emit("hello", "from express-fastify-runtime"));
+const io = new IOServer(fastApp.server); // share the same HTTP server
+io.on("connection", (socket) =>
+  socket.emit("hello", "from express-fastify-runtime"),
+);
 
 fastApp.server.listen(3000);
 ```
@@ -170,7 +186,10 @@ Wrap the handler/middleware. Works with plain functions and arrow functions:
 ```ts
 import { expressLane } from "express-fastify-runtime";
 
-app.get("/page", expressLane((req, res) => res.render("index", { title: "Hi" })));
+app.get(
+  "/page",
+  expressLane((req, res) => res.render("index", { title: "Hi" })),
+);
 ```
 
 ### `@ExpressLane` — decorator form (class-method controllers)
@@ -226,13 +245,13 @@ Numbers are req/s, **median of repeated runs with warmup** (single-shot HTTP ben
 20–30%, so don't trust one sample — including ours; reproduce with `npm run benchmark:table`).
 10 connections, Node on an Apple-silicon laptop. Higher is better.
 
-| Scenario | Express | Fastify | **fast()** | fast/Express | fast/Fastify |
-|---|--:|--:|--:|--:|--:|
-| Plain JSON route (5 middleware) | 39,976 | 68,112 | **50,552** | **1.26×** | 0.74× |
-| JSON DB read | 41,848 | 68,624 | **50,584** | **1.21×** | 0.74× |
-| Middleware stack (helmet+morgan+json+custom) | 29,424 | 32,736 | **40,184** | **1.37×** | **1.23×** |
-| POST 1KB JSON | 33,018 | 46,752 | **46,696** | **1.41×** | **1.00×** |
-| Auth (JWT verify) | 17,636 | 33,976 | **19,360** | **1.10×** | 0.57× |
+| Scenario                                     | Express | Fastify | **fast()** | fast/Express | fast/Fastify |
+| -------------------------------------------- | ------: | ------: | ---------: | -----------: | -----------: |
+| Plain JSON route (5 middleware)              |  39,976 |  68,112 | **50,552** |    **1.26×** |        0.74× |
+| JSON DB read                                 |  41,848 |  68,624 | **50,584** |    **1.21×** |        0.74× |
+| Middleware stack (helmet+morgan+json+custom) |  29,424 |  32,736 | **40,184** |    **1.37×** |    **1.23×** |
+| POST 1KB JSON                                |  33,018 |  46,752 | **46,696** |    **1.41×** |    **1.00×** |
+| Auth (JWT verify)                            |  17,636 |  33,976 | **19,360** |    **1.10×** |        0.57× |
 
 **Reading the table:**
 
@@ -240,7 +259,7 @@ Numbers are req/s, **median of repeated runs with warmup** (single-shot HTTP ben
 - It **matches or beats Fastify** on middleware-heavy and small-payload workloads.
 - On a tight pure-JSON hot path it trails raw Fastify a little — that's the unavoidable cost of
   presenting a real Express `req`/`res`, and it's still well ahead of Express.
-- **Auth (JWT):** the gap there isn't the adapter — it's the *library*. Fastify's benchmark uses
+- **Auth (JWT):** the gap there isn't the adapter — it's the _library_. Fastify's benchmark uses
   `@fastify/jwt` (built on `fast-jwt`), which is simply faster than `jsonwebtoken`. Want that
   speed in your Express app? Use `fast-jwt` directly in your auth middleware — it's
   framework-agnostic.

package/changelog/log-2026-06-25.md

@@ -1,5 +1,24 @@
 # 2026-06-25
 
+## Fix: writes (POST/PUT with a JSON body) 500'd on the Express-lane fallback (Express 4)
+
+Reported by a consumer (Express 4): reads worked, but every request with a JSON body returned
+`500 Cannot assign to read only property 'body' of object '#<IncomingMessage>'`.
+
+- **Cause.** On the Express-lane fallback, Fastify has already parsed and consumed the body stream.
+  We attached the parsed body to the raw request as a **read-only** property to stop Express's
+  `express.json()` from overwriting it with an empty object. But body-parser **assigns**
+  `req.body = ...` unconditionally — and assigning to a read-only property *throws* on Express 4's
+  strict body-parser (Express 5 silently drops it, masking the bug). Any route on the Express lane
+  with a JSON body 500'd.
+- **Fix** (`src/express/mount.ts`): attach the body as **writable** and set body-parser's
+  `req._body = true` flag, so `express.json()`/`urlencoded()`/etc. **skip** entirely (early-return)
+  instead of re-reading the consumed stream — no re-parse, no overwrite, no throw. Only set when
+  Fastify actually parsed a body, so urlencoded/raw requests Fastify doesn't parse still flow to the
+  real Express parsers untouched.
+- **Test**: `test/compat/express4.test.js` now forces a POST with a JSON body onto the Express lane
+  and asserts `200` + correct `req.body` (the regression only manifests under Express 4).
+
 ## Publish prep
 
 - **Fastify upgraded to 5.8.5** (latest; includes the recent security/CVE fixes). Dependency floor

package/dist/express/mount.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mount.d.ts","sourceRoot":"","sources":["../../src/express/mount.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,WAAW,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAgC,MAAM,SAAS,CAAC;AAC7E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAU3C,8EAA8E;AAC9E,MAAM,MAAM,uBAAuB,GAAG,eAAe,GAAG;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAE3E,mDAAmD;AACnD,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,eAAe,EACxB,UAAU,EAAE,WAAW,EACvB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,IAAI,CAyDN"}
+{"version":3,"file":"mount.d.ts","sourceRoot":"","sources":["../../src/express/mount.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,WAAW,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAgC,MAAM,SAAS,CAAC;AAC7E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAU3C,8EAA8E;AAC9E,MAAM,MAAM,uBAAuB,GAAG,eAAe,GAAG;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAE3E,mDAAmD;AACnD,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,eAAe,EACxB,UAAU,EAAE,WAAW,EACvB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,IAAI,CAwDN"}

package/dist/express/mount.js

@@ -34,18 +34,17 @@ function mountExpress(fastify, expressApp, options) {
         (0, maxListeners_1.applyMaxListeners)(request.raw, reply.raw);
         const raw = request.raw;
         const res = reply.raw;
-        // Fastify has already consumed the body stream; attach parsed body so Express sees req.body.
-        // Define body as non-writable so express.json() cannot overwrite with empty when it reads
-        // the already-consumed stream. No Proxy — avoids per-property access overhead on Express lane.
+        // Fastify already parsed and consumed the body stream. Attach the parsed body AND set
+        // body-parser's `_body` flag so Express's express.json()/urlencoded()/etc. SKIP (they early-
+        // return when req._body is set) instead of re-reading the now-empty stream. The body must stay
+        // WRITABLE: body parsers assign `req.body = ...` unconditionally, and a read-only property
+        // throws "Cannot assign to read only property 'body'" on Express 4 (and silently drops the
+        // assignment on Express 5). The `_body` flag is what prevents the overwrite, not read-only.
         const bodyFromFastify = await Promise.resolve(request.body);
         const req = raw;
         if (bodyFromFastify !== undefined) {
-            Object.defineProperty(raw, 'body', {
-                value: bodyFromFastify,
-                writable: false,
-                configurable: true,
-                enumerable: true,
-            });
+            req.body = bodyFromFastify;
+            req._body = true;
         }
         await new Promise((resolve, reject) => {
             let settled = false;

package/dist/express/mount.js.map

@@ -1 +1 @@
-{"version":3,"file":"mount.js","sourceRoot":"","sources":["../../src/express/mount.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;AA8BH,oCA6DC;AAtFD,wDAA0D;AAkB1D;;;;;;GAMG;AACH,SAAgB,YAAY,CAC1B,OAAwB,EACxB,UAAuB,EACvB,OAA6B;IAE7B,MAAM,WAAW,GAAG,OAAO,EAAE,WAAW,KAAK,IAAI,CAAC;IAElD,OAAO,CAAC,kBAAkB,CAAC,KAAK,EAAE,OAAuB,EAAE,KAAmB,EAAE,EAAE;QAChF,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,KAAK,CAAC;YACvC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC;YAC/B,OAAO,CAAC,GAAG,CAAC,2CAA2C,MAAM,IAAI,GAAG,EAAE,CAAC,CAAC;QAC1E,CAAC;QAED,IAAA,gCAAiB,EAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;QAE1C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;QACxB,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC;QAEtB,6FAA6F;QAC7F,0FAA0F;QAC1F,+FAA+F;QAC/F,MAAM,eAAe,GAAG,MAAM,OAAO,CAAC,OAAO,CAAE,OAA8B,CAAC,IAAI,CAAC,CAAC;QACpF,MAAM,GAAG,GAAG,GAA8B,CAAC;QAC3C,IAAI,eAAe,KAAK,SAAS,EAAE,CAAC;YAClC,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE;gBACjC,KAAK,EAAE,eAAe;gBACtB,QAAQ,EAAE,KAAK;gBACf,YAAY,EAAE,IAAI;gBAClB,UAAU,EAAE,IAAI;aACjB,CAAC,CAAC;QACL,CAAC;QAED,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC1C,IAAI,OAAO,GAAG,KAAK,CAAC;YACpB,MAAM,MAAM,GAAG,GAAG,EAAE;gBAClB,IAAI,OAAO;oBAAE,OAAO;gBACpB,OAAO,GAAG,IAAI,CAAC;gBACf,OAAO,EAAE,CAAC;YACZ,CAAC,CAAC;YAEF,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAC3B,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAE1B,MAAM,IAAI,GAAG,CAAC,GAAW,EAAE,EAAE;gBAC3B,IAAI,OAAO;oBAAE,OAAO;gBACpB,OAAO,GAAG,IAAI,CAAC;gBACf,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;oBACvB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;oBACtC,OAAO;gBACT,CAAC;gBACD,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;oBAChB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;oBAC7C,OAAO;gBACT,CAAC;gBACD,OAAO,EAAE,CAAC;YACZ,CAAC,CAAC;YAED,UAAgD,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;QACpE,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"mount.js","sourceRoot":"","sources":["../../src/express/mount.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;AA8BH,oCA4DC;AArFD,wDAA0D;AAkB1D;;;;;;GAMG;AACH,SAAgB,YAAY,CAC1B,OAAwB,EACxB,UAAuB,EACvB,OAA6B;IAE7B,MAAM,WAAW,GAAG,OAAO,EAAE,WAAW,KAAK,IAAI,CAAC;IAElD,OAAO,CAAC,kBAAkB,CAAC,KAAK,EAAE,OAAuB,EAAE,KAAmB,EAAE,EAAE;QAChF,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,KAAK,CAAC;YACvC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC;YAC/B,OAAO,CAAC,GAAG,CAAC,2CAA2C,MAAM,IAAI,GAAG,EAAE,CAAC,CAAC;QAC1E,CAAC;QAED,IAAA,gCAAiB,EAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;QAE1C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;QACxB,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC;QAEtB,sFAAsF;QACtF,6FAA6F;QAC7F,+FAA+F;QAC/F,2FAA2F;QAC3F,2FAA2F;QAC3F,4FAA4F;QAC5F,MAAM,eAAe,GAAG,MAAM,OAAO,CAAC,OAAO,CAAE,OAA8B,CAAC,IAAI,CAAC,CAAC;QACpF,MAAM,GAAG,GAAG,GAAoD,CAAC;QACjE,IAAI,eAAe,KAAK,SAAS,EAAE,CAAC;YAClC,GAAG,CAAC,IAAI,GAAG,eAAe,CAAC;YAC3B,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC;QACnB,CAAC;QAED,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC1C,IAAI,OAAO,GAAG,KAAK,CAAC;YACpB,MAAM,MAAM,GAAG,GAAG,EAAE;gBAClB,IAAI,OAAO;oBAAE,OAAO;gBACpB,OAAO,GAAG,IAAI,CAAC;gBACf,OAAO,EAAE,CAAC;YACZ,CAAC,CAAC;YAEF,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAC3B,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAE1B,MAAM,IAAI,GAAG,CAAC,GAAW,EAAE,EAAE;gBAC3B,IAAI,OAAO;oBAAE,OAAO;gBACpB,OAAO,GAAG,IAAI,CAAC;gBACf,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;oBACvB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;oBACtC,OAAO;gBACT,CAAC;gBACD,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;oBAChB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;oBAC7C,OAAO;gBACT,CAAC;gBACD,OAAO,EAAE,CAAC;YACZ,CAAC,CAAC;YAED,UAAgD,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;QACpE,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "express-fastify-runtime",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Run Express apps on Fastify safely, faster, without code changes",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",