express-fast-json-stringify 1.3.0 → 2.0.0

package/CHANGELOG.md

@@ -1,15 +1,30 @@
 # Changelog
 
+## [2.0.0](https://github.com/nigrosimone/express-fast-json-stringify/compare/v1.3.0...v2.0.0) (2026-09-20)
+
+### ⚠ BREAKING CHANGES
+
+- install once on app.response, the middlewares only choose the schema and the string goes through res.send
+
+### Features
+
+- add a landing page with links to fast-json and native-json endpoints ([882c2ed](https://github.com/nigrosimone/express-fast-json-stringify/commit/882c2ed6b191e059f49381be2abf0ca017474140))
+- install once on app.response, the middlewares only choose the schema and the string goes through res.send ([83ab193](https://github.com/nigrosimone/express-fast-json-stringify/commit/83ab19300aad0d19c9e77288832f35c378a517bd))
+
+### Bug Fixes
+
+- correct json settings check to avoid false negatives with falsy values ([bc13964](https://github.com/nigrosimone/express-fast-json-stringify/commit/bc139640fc7732dfb4081a8395d1260df83e6d51))
+
 ## [1.3.0](https://github.com/nigrosimone/express-fast-json-stringify/compare/v1.2.9...v1.3.0) (2026-07-26)
 
 ### Features
 
-* derive the schema from an OpenAPI or Swagger document ([5ce6622](https://github.com/nigrosimone/express-fast-json-stringify/commit/5ce6622fd216df1074e844c254bef0c7731205cd))
-* opt in override of res.json, so adoption needs no call site changes ([bcfda45](https://github.com/nigrosimone/express-fast-json-stringify/commit/bcfda4579ac8380f53c525b5cadcbc177e835b9c))
+- derive the schema from an OpenAPI or Swagger document ([5ce6622](https://github.com/nigrosimone/express-fast-json-stringify/commit/5ce6622fd216df1074e844c254bef0c7731205cd))
+- opt in override of res.json, so adoption needs no call site changes ([bcfda45](https://github.com/nigrosimone/express-fast-json-stringify/commit/bcfda4579ac8380f53c525b5cadcbc177e835b9c))
 
 ### Bug Fixes
 
-* align res.fastJson with res.json HTTP semantics; add CI and vitest ([f2c8558](https://github.com/nigrosimone/express-fast-json-stringify/commit/f2c85584c105ce24c6c7327382b6b80022aade10))
+- align res.fastJson with res.json HTTP semantics; add CI and vitest ([f2c8558](https://github.com/nigrosimone/express-fast-json-stringify/commit/f2c85584c105ce24c6c7327382b6b80022aade10))
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
@@ -17,33 +32,29 @@ All notable changes to this project will be documented in this file. See [standa
 
 ### [1.2.8](https://github.com/nigrosimone/express-fast-json-stringify/compare/v1.2.6...v1.2.8) (2024-09-29)
 
-
 ### Bug Fixes
 
-* global type ([56fa47c](https://github.com/nigrosimone/express-fast-json-stringify/commit/56fa47c6b395a1de89dd85bc67f55c8cd3f5d852))
+- global type ([56fa47c](https://github.com/nigrosimone/express-fast-json-stringify/commit/56fa47c6b395a1de89dd85bc67f55c8cd3f5d852))
 
 ### [1.2.6](https://github.com/nigrosimone/express-fast-json-stringify/compare/v1.2.4...v1.2.6) (2024-09-29)
 
-
 ### Bug Fixes
 
-* export ([b753280](https://github.com/nigrosimone/express-fast-json-stringify/commit/b753280af8af5aea830715405d404f3fad6f43d7))
+- export ([b753280](https://github.com/nigrosimone/express-fast-json-stringify/commit/b753280af8af5aea830715405d404f3fad6f43d7))
 
 ### [1.2.4](https://github.com/nigrosimone/express-fast-json-stringify/compare/v1.2.2...v1.2.4) (2024-09-29)
 
-
 ### Bug Fixes
 
-* del deps ([0e9e63a](https://github.com/nigrosimone/express-fast-json-stringify/commit/0e9e63af86e647815002079b1df5ca19ff6f7632))
+- del deps ([0e9e63a](https://github.com/nigrosimone/express-fast-json-stringify/commit/0e9e63af86e647815002079b1df5ca19ff6f7632))
 
 ### [1.2.2](https://github.com/nigrosimone/express-fast-json-stringify/compare/v1.2.0...v1.2.2) (2024-09-29)
 
 ## [1.2.0](https://github.com/nigrosimone/express-fast-json-stringify/compare/v1.1.4...v1.2.0) (2024-09-29)
 
-
 ### Features
 
-* add options ([9466dc3](https://github.com/nigrosimone/express-fast-json-stringify/commit/9466dc30c20693a7ceabf2240d5d9701c76280c0))
+- add options ([9466dc3](https://github.com/nigrosimone/express-fast-json-stringify/commit/9466dc30c20693a7ceabf2240d5d9701c76280c0))
 
 ### [1.1.4](https://github.com/nigrosimone/express-fast-json-stringify/compare/v1.1.2...v1.1.4) (2024-09-29)
 
@@ -51,14 +62,12 @@ All notable changes to this project will be documented in this file. See [standa
 
 ## 1.1.0 (2024-09-29)
 
-
 ### Features
 
-* first commit ([5e3cc3e](https://github.com/nigrosimone/express-fast-json-stringify/commit/5e3cc3e46fc0d35c07299697d1133636d21bee9b))
-* npmignore ([364b397](https://github.com/nigrosimone/express-fast-json-stringify/commit/364b397ec15c14846c427c8c395b756aec839174))
-* vscode ([f962e81](https://github.com/nigrosimone/express-fast-json-stringify/commit/f962e8145aeaa517c8b80dc642f5bca6139dff4d))
-
+- first commit ([5e3cc3e](https://github.com/nigrosimone/express-fast-json-stringify/commit/5e3cc3e46fc0d35c07299697d1133636d21bee9b))
+- npmignore ([364b397](https://github.com/nigrosimone/express-fast-json-stringify/commit/364b397ec15c14846c427c8c395b756aec839174))
+- vscode ([f962e81](https://github.com/nigrosimone/express-fast-json-stringify/commit/f962e8145aeaa517c8b80dc642f5bca6139dff4d))
 
 ### Bug Fixes
 
-* ignore publish ([ca95f45](https://github.com/nigrosimone/express-fast-json-stringify/commit/ca95f450e1ce22f957fff4cd9f7520386ee70962))
+- ignore publish ([ca95f45](https://github.com/nigrosimone/express-fast-json-stringify/commit/ca95f450e1ce22f957fff4cd9f7520386ee70962))

package/README.md

@@ -1,5 +1,7 @@
 JSON serialization is a critical task in web development, particularly for applications built with Node.js and Express.js. While the native JSON serialization in Node.js (`JSON.stringify()`) is straightforward and convenient, it can become a performance bottleneck, especially under heavy load. This documentation introduces [express-fast-json-stringify](https://www.npmjs.com/package/express-fast-json-stringify), a custom middleware package that leverages [fast-json-stringify](https://www.npmjs.com/package/fast-json-stringify) to significantly boost JSON serialization performance in Express applications.
 
+Run it now on [StackBlitz](https://stackblitz.com/github/nigrosimone/express-fast-json-stringify) — it boots the Express server, serves the same payload through `res.json()` and `res.fastJson()`, and prints both responses side by side. The [sources](./example) are in this repository.
+
 ## What is fast-json-stringify?
 
 `fast-json-stringify` is a JSON serialization library developed by the Fastify team. It analyzes JSON schema definitions and compiles them into serialization functions specialized for the exact shape of your payload, so it can skip everything the schema does not describe instead of walking the object generically like `JSON.stringify()` has to.
@@ -39,15 +41,29 @@ const schema: Schema = {
 };
 ```
 
+## Installing it on the app
+
+Call `installFastJson(app)` once, when the app is built. It adds `res.fastJson()` to the
+responses of that app, on `app.response`, so no request pays for it.
+
+```ts
+import express from 'express';
+import { installFastJson } from 'express-fast-json-stringify';
+
+const app = express();
+installFastJson(app);
+```
+
 ## Applying the Middleware
 
-Use the `fastJsonSchema` middleware in your Express routes, passing the schema object as an argument. This will set up the optimized JSON serialization for that route.
+Use the `fastJsonSchema` middleware in your Express routes, passing the schema object as an argument. It picks the serializer for that route.
 
 ```ts
 import express from 'express';
-import { fastJsonSchema, Schema } from 'express-fast-json-stringify';
+import { fastJsonSchema, installFastJson, Schema } from 'express-fast-json-stringify';
 
 const app = express();
+installFastJson(app);
 
 const exampleSchema: Schema = {
   title: 'Example Schema',
@@ -68,9 +84,10 @@ Instead of using the default `res.json()` method, use the `res.fastJson()` metho
 
 ```ts
 import express from 'express';
-import { fastJsonSchema, Schema } from 'express-fast-json-stringify';
+import { fastJsonSchema, installFastJson, Schema } from 'express-fast-json-stringify';
 
 const app = express();
+installFastJson(app);
 
 const schema: Schema = {
   title: 'Example Schema',
@@ -102,12 +119,13 @@ app.get('/', fastJsonSchema(schema), (req, res, next) => {
 ## Response semantics
 
 `res.fastJson()` is a drop-in replacement for `res.json()`: only the
-serialization changes, every HTTP detail stays the same.
+serialization changes. The string then goes through `res.send()`, the same
+call `res.json()` makes, so every HTTP detail is the one the framework gives.
 
 | Behavior             | What `res.fastJson()` does                                                                          |
 | -------------------- | --------------------------------------------------------------------------------------------------- |
-| `Content-Type`       | `application/json; charset=utf-8`, unless the route already set one with `res.type()`.              |
-| `Content-Length`     | Always set, from the byte length of the payload, so the response is never chunked.                  |
+| `Content-Type`       | `application/json; charset=utf-8`; a type the route set with `res.type()` is kept, charset added.   |
+| `Content-Length`     | Set by `res.send()`, so the response is never chunked.                                              |
 | `ETag`               | Follows the app `etag` setting, exactly like `res.send()`. Set `app.set('etag', false)` to skip it. |
 | Conditional requests | A matching `If-None-Match` answers `304` with no body.                                              |
 | `204` and `304`      | No body and no `Content-Type`/`Content-Length`/`Transfer-Encoding`.                                 |
@@ -116,11 +134,16 @@ serialization changes, every HTTP detail stays the same.
 The payload is serialized before the status code is inspected, so a body that
 does not match the schema still throws on a `204` — just like `res.json()`.
 
+A route without a schema falls back to `res.json()`. Pass
+`installFastJson(app, { strict: true })` to get an error instead.
+
 ## Taking the schema from your OpenAPI document
 
 If you already publish an OpenAPI (or Swagger) document, the response schemas
 are written there — no need to repeat them in the routes. `fastJsonOpenApi`
-takes that document and resolves the schema per route and per status code:
+takes that document and resolves the schema per route and per status code.
+It installs itself, so there is no `installFastJson(app)` to call and no
+middleware runs per request:
 
 ```ts
 import express from 'express';
@@ -130,8 +153,8 @@ import document from './openapi.json' with { type: 'json' };
 
 const app = express();
 
-// One middleware for the whole app.
-app.use(fastJsonOpenApi(document));
+// Once for the whole app.
+fastJsonOpenApi(app, document);
 
 app.get('/users/:id', (req, res, next) => {
   try {
@@ -179,14 +202,20 @@ There is no dependency on any of them: the middleware only reads `paths`,
 - **OpenAPI 3.0 and 3.1** are both supported; `nullable: true` is honoured and
   annotation keywords (`example`, `discriminator`, `xml`, ...) are ignored.
 
-Routes the document does not describe fall back to `res.json()`, so adding the
-middleware app-wide cannot break an undocumented endpoint. Pass
-`{ strict: true }` to get an error instead of a silent fallback.
+Routes the document does not describe fall back to `res.json()`, so installing
+it app-wide cannot break an undocumented endpoint. Pass `{ strict: true }` to
+get an error instead of a silent fallback.
+
+The serializer of a route is found from the route object the framework
+matched and kept beside it, so a request does not rebuild the path or look up
+a string.
 
 ```ts
-// Read a different media type, pin an operation, forward fast-json-stringify options
-app.use(fastJsonOpenApi(document, { contentType: 'application/vnd.api+json' }));
-app.get('/v2/people/:id', fastJsonOpenApi(document, { path: '/users/{id}', method: 'get' }), handler);
+// Read a different media type, forward fast-json-stringify options
+fastJsonOpenApi(app, document, { contentType: 'application/vnd.api+json', rounding: 'ceil' });
+
+// A route the document spells differently: take the schema out by hand
+app.get('/v2/people/:id', fastJsonSchema(openApiSchema(document, '/users/{id}', 'get')!), handler);
 ```
 
 Because the schema decides what gets written, a property that is not in the
@@ -200,16 +229,16 @@ that means editing every `res.json()` call site, which is a lot of churn for a
 serialization change. `overrideJson` removes that step:
 
 ```ts
-app.use(fastJsonOpenApi(document, { overrideJson: true }));
+fastJsonOpenApi(app, document, { overrideJson: true });
 
 // Unchanged route. It is now serialized from the `get /users/{id}` -> `200`
 // schema, with no edit at the call site.
 app.get('/users/:id', (req, res) => res.json(user));
 ```
 
-Only `res.json` is replaced. Express implements `res.send(object)` by calling
-`res.json(object)`, so both entry points are covered by the one hook, while
-`res.send` of a string or a Buffer is left alone.
+Only `res.json` is replaced, once, on `app.response`. Express implements
+`res.send(object)` by calling `res.json(object)`, so both entry points are
+covered by the one hook, while `res.send` of a string or a Buffer is left alone.
 
 **The override cannot break a route.** It steps aside, and the stock
 `res.json()` runs, whenever:
@@ -221,24 +250,24 @@ Only `res.json` is replaced. Express implements `res.send(object)` by calling
   missing. Pass `onError` to be told when that happens:
 
 ```ts
-app.use(
-  fastJsonOpenApi(document, {
-    overrideJson: true,
-    onError: (error, req) => logger.warn({ error, url: req.originalUrl }, 'schema mismatch'),
-  }),
-);
+fastJsonOpenApi(app, document, {
+  overrideJson: true,
+  onError: (error, req) => logger.warn({ error, url: req.originalUrl }, 'schema mismatch'),
+});
 ```
 
 `strict` does not apply here: it governs explicit `res.fastJson()` calls, while
 an overridden `res.json()` always falls back rather than throw.
 
-`fastJsonSchema` accepts `overrideJson` too, with one difference: a single
-schema describes the _successful_ payload, so only `2xx` responses take the fast
-path. An error body would otherwise be rewritten into the shape of the success
-schema.
+`installFastJson(app, { overrideJson: true })` does the same for the routes
+that carry a `fastJsonSchema`, with one difference: a single schema describes
+the _successful_ payload, so only `2xx` responses take the fast path. An error
+body would otherwise be rewritten into the shape of the success schema.
 
 ```ts
-app.get('/users/:id', fastJsonSchema(userSchema, { overrideJson: true }), (req, res) => {
+installFastJson(app, { overrideJson: true });
+
+app.get('/users/:id', fastJsonSchema(userSchema), (req, res) => {
   res.json(user); // serialized through the schema
   res.status(500).json({ error: 'boom' }); // untouched, stock res.json()
 });
@@ -263,11 +292,15 @@ How much you gain depends on the payload, and on a current V8 it is not a win ac
 
 Run `npm run example` to get the numbers for your own Node.js version and payload shape before adopting it in a hot path.
 
+### On fulmine.js
+
+[fulmine.js](https://www.npmjs.com/package/fulmine.js) is Express on uWebSockets.js, and it reads the source of every middleware and handler at startup: when none of them can read a request header, the header copy is skipped for that route. The `fastJsonSchema` middleware only writes `res.locals` and calls `next()`, so it keeps that skip, and so does a handler calling `res.json()`. A handler calling `res.fastJson()` does not, because that is not a method fulmine knows, so on fulmine prefer `overrideJson` and plain `res.json()`. Measured on an API endpoint with eleven request headers, the previous design of this package cost 5 to 9 microseconds of CPU per request there; this one is within half a microsecond of serializing by hand.
+
 ## Conclusion
 
 Integrating `express-fast-json-stringify` into your Express.js application can provide substantial performance improvements when JSON serialization is a bottleneck and your schemas let the serializer skip work. It also guarantees that responses carry exactly the properties the schema describes, which is worth having on its own.
 
-To start using `express-fast-json-stringify`, follow the steps outlined in this documentation, and enjoy the benefits of faster JSON serialization in your Express applications. For a runnable demo, see [example/](./example): `npm install && npm run example`.
+To start using `express-fast-json-stringify`, follow the steps outlined in this documentation, and enjoy the benefits of faster JSON serialization in your Express applications. For a runnable demo, open it on [StackBlitz](https://stackblitz.com/github/nigrosimone/express-fast-json-stringify) or run it locally from [example/](./example): `npm install && npm run example`.
 
 ## Support
 

package/build/main/index.d.ts

@@ -1,3 +1,3 @@
+export { type Application, installFastJson, type FastJsonOptions, type OverrideErrorHandler } from './lib/install';
 export * from './lib/middleware';
 export * from './lib/openapi';
-export type { OverrideErrorHandler } from './lib/override';

package/build/main/index.js

@@ -14,6 +14,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.installFastJson = void 0;
+var install_1 = require("./lib/install");
+Object.defineProperty(exports, "installFastJson", { enumerable: true, get: function () { return install_1.installFastJson; } });
 __exportStar(require("./lib/middleware"), exports);
 __exportStar(require("./lib/openapi"), exports);
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7Ozs7Ozs7OztBQUFBLG1EQUFpQztBQUNqQyxnREFBOEIifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7Ozs7Ozs7Ozs7QUFBQSx5Q0FBbUg7QUFBeEYsMEdBQUEsZUFBZSxPQUFBO0FBQzFDLG1EQUFpQztBQUNqQyxnREFBOEIifQ==

package/build/main/lib/install.d.ts

@@ -0,0 +1,77 @@
+import type { Express, Request, Response } from 'express';
+/** What the install needs of an application: the prototype its responses share. Fulmine has one too. */
+export type Application = Pick<Express, 'response'>;
+/** A compiled serializer, as fast-json-stringify builds it. */
+export type Serializer = (body: any) => string;
+/** Finds the serializer for a response from something other than the route, an OpenAPI document. */
+export type SerializerResolver = (res: Response) => Serializer | null;
+/** Notified when an overridden `res.json()` could not use the fast path. */
+export type OverrideErrorHandler = (error: unknown, req: Request) => void;
+export type FastJsonOptions = {
+    /**
+     * Also route `res.json()`, and `res.send(object)` which Express implements on
+     * top of it, through the serializer in force.
+     *
+     * Off by default. A route's own schema describes the successful payload, so
+     * under it only `2xx` responses take the fast path: an error body would
+     * otherwise be rewritten into the wrong shape.
+     */
+    readonly overrideJson?: boolean;
+    /**
+     * Called when an overridden `res.json()` could not use the fast path because
+     * the serializer threw. The response falls back to the stock `res.json()`
+     * either way; this is only so the mismatch is visible.
+     */
+    readonly onError?: OverrideErrorHandler;
+    /**
+     * Make `res.fastJson()` throw when no schema is known for the response,
+     * instead of quietly falling back to `res.json()`. An overridden `res.json()`
+     * always falls back.
+     */
+    readonly strict?: boolean;
+};
+/** Where `fastJsonSchema` leaves the serializer of the route, on `res.locals`. */
+export declare const kSerializer: unique symbol;
+/**
+ * Give an application `res.fastJson()`, and with `overrideJson` a `res.json()`
+ * that serializes through the schema in force. Once per app, at setup: the
+ * methods go on `app.response`, so a request pays nothing to have them.
+ *
+ * `fastJsonSchema` chooses the schema per route, `fastJsonOpenApi` per
+ * operation from a document and calls this itself.
+ *
+ * @param {Application} app The application to extend
+ * @param {FastJsonOptions} options The options to use (optional)
+ *
+ * Examples:
+ * ```ts
+ * import express from 'express';
+ * import { installFastJson, fastJsonSchema } from 'express-fast-json-stringify';
+ *
+ * const app = express();
+ * installFastJson(app);
+ *
+ * app.get('/', fastJsonSchema(schema), (req, res) => {
+ *   res.fastJson({ firstName: 'Simone', lastName: 'Nigro', age: 40 });
+ * });
+ * ```
+ */
+export declare const installFastJson: (app: Application, options?: FastJsonOptions) => void;
+/** Registers where the document based serializers come from, see fastJsonOpenApi. */
+export declare const setResolver: (app: Application, resolver: SerializerResolver) => void;
+declare global {
+    namespace Express {
+        interface Response {
+            /**
+             * Send JSON response, serialized with the schema in force for the route.
+             *
+             * Examples:
+             * ```ts
+             * res.fastJson({ user: 'Simone Nigro' });
+             * res.status(200).fastJson({ user: 'Simone Nigro' });
+             * ```
+             */
+            fastJson: (body: any) => Response;
+        }
+    }
+}

package/build/main/lib/install.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setResolver = exports.installFastJson = exports.kSerializer = void 0;
+const send_1 = require("./send");
+/** Where `fastJsonSchema` leaves the serializer of the route, on `res.locals`. */
+exports.kSerializer = Symbol('express-fast-json-stringify');
+// one state per response prototype, which is one per app
+const states = new WeakMap();
+const routeOf = (req) => { var _a, _b; return `${req.baseUrl}${(_b = (_a = req.route) === null || _a === void 0 ? void 0 : _a.path) !== null && _b !== void 0 ? _b : req.path}`; };
+// the route's own serializer first, then what the document says
+const pick = (state, res, successOnly) => {
+    const own = res.locals[exports.kSerializer];
+    if (own !== undefined && (!successOnly || (res.statusCode >= 200 && res.statusCode < 300))) {
+        return own;
+    }
+    return state.resolver === null ? null : state.resolver(res);
+};
+const fastJsonMethod = (state) => function installFastJson(body) {
+    const serialize = pick(state, this, false);
+    if (serialize === null) {
+        if (state.strict) {
+            throw new Error(`express-fast-json-stringify: no schema for ${this.req.method} ${routeOf(this.req)}`);
+        }
+        return state.stockJson.call(this, body);
+    }
+    return (0, send_1.sendSerialized)(this, serialize(body));
+};
+// The stock res.json() runs whenever the fast path does not apply: a setting that changes the
+// bytes (json replacer, spaces, escape), no schema for this response, or a body the schema refuses
+const jsonMethod = (state) => function json(body) {
+    var _a;
+    const app = this.app;
+    if (!app.get('json replacer') && !app.get('json spaces') && !app.get('json escape')) {
+        const serialize = pick(state, this, true);
+        if (serialize !== null) {
+            let out;
+            try {
+                out = serialize(body);
+            }
+            catch (error) {
+                (_a = state.onError) === null || _a === void 0 ? void 0 : _a.call(state, error, this.req);
+            }
+            if (out !== undefined) {
+                return (0, send_1.sendSerialized)(this, out);
+            }
+        }
+    }
+    return state.stockJson.call(this, body);
+};
+/**
+ * Give an application `res.fastJson()`, and with `overrideJson` a `res.json()`
+ * that serializes through the schema in force. Once per app, at setup: the
+ * methods go on `app.response`, so a request pays nothing to have them.
+ *
+ * `fastJsonSchema` chooses the schema per route, `fastJsonOpenApi` per
+ * operation from a document and calls this itself.
+ *
+ * @param {Application} app The application to extend
+ * @param {FastJsonOptions} options The options to use (optional)
+ *
+ * Examples:
+ * ```ts
+ * import express from 'express';
+ * import { installFastJson, fastJsonSchema } from 'express-fast-json-stringify';
+ *
+ * const app = express();
+ * installFastJson(app);
+ *
+ * app.get('/', fastJsonSchema(schema), (req, res) => {
+ *   res.fastJson({ firstName: 'Simone', lastName: 'Nigro', age: 40 });
+ * });
+ * ```
+ */
+const installFastJson = (app, options = {}) => {
+    const proto = app === null || app === void 0 ? void 0 : app.response;
+    if (!proto || typeof proto.json !== 'function') {
+        throw new TypeError('express-fast-json-stringify: an Express application is required');
+    }
+    let state = states.get(proto);
+    if (state === undefined) {
+        state = { stockJson: proto.json, resolver: null, overrideJson: false, onError: undefined, strict: false };
+        states.set(proto, state);
+        proto.fastJson = fastJsonMethod(state);
+    }
+    state.overrideJson = options.overrideJson === true;
+    state.onError = options.onError;
+    state.strict = options.strict === true;
+    // the stock method is put back when the override is off, so nothing runs on res.json() that
+    // was not there before, and a framework reading the prototype sees the method it knows
+    proto.json = state.overrideJson ? jsonMethod(state) : state.stockJson;
+};
+exports.installFastJson = installFastJson;
+/** Registers where the document based serializers come from, see fastJsonOpenApi. */
+const setResolver = (app, resolver) => {
+    states.get(app.response).resolver = resolver;
+};
+exports.setResolver = setResolver;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5zdGFsbC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9saWIvaW5zdGFsbC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFFQSxpQ0FBd0M7QUFzQ3hDLGtGQUFrRjtBQUNyRSxRQUFBLFdBQVcsR0FBa0IsTUFBTSxDQUFDLDZCQUE2QixDQUFDLENBQUM7QUFZaEYseURBQXlEO0FBQ3pELE1BQU0sTUFBTSxHQUFHLElBQUksT0FBTyxFQUFpQixDQUFDO0FBRTVDLE1BQU0sT0FBTyxHQUFHLENBQUMsR0FBWSxFQUFVLEVBQUUsZUFBQyxPQUFBLEdBQUcsR0FBRyxDQUFDLE9BQU8sR0FBRyxNQUFBLE1BQUEsR0FBRyxDQUFDLEtBQUssMENBQUUsSUFBSSxtQ0FBSSxHQUFHLENBQUMsSUFBSSxFQUFFLENBQUEsRUFBQSxDQUFDO0FBRXpGLGdFQUFnRTtBQUNoRSxNQUFNLElBQUksR0FBRyxDQUFDLEtBQVksRUFBRSxHQUFhLEVBQUUsV0FBb0IsRUFBcUIsRUFBRTtJQUNwRixNQUFNLEdBQUcsR0FBSSxHQUFHLENBQUMsTUFBaUIsQ0FBQyxtQkFBVyxDQUFDLENBQUM7SUFDaEQsSUFBSSxHQUFHLEtBQUssU0FBUyxJQUFJLENBQUMsQ0FBQyxXQUFXLElBQUksQ0FBQyxHQUFHLENBQUMsVUFBVSxJQUFJLEdBQUcsSUFBSSxHQUFHLENBQUMsVUFBVSxHQUFHLEdBQUcsQ0FBQyxDQUFDLEVBQUUsQ0FBQztRQUMzRixPQUFPLEdBQUcsQ0FBQztJQUNiLENBQUM7SUFDRCxPQUFPLEtBQUssQ0FBQyxRQUFRLEtBQUssSUFBSSxDQUFDLENBQUMsQ0FBQyxJQUFJLENBQUMsQ0FBQyxDQUFDLEtBQUssQ0FBQyxRQUFRLENBQUMsR0FBRyxDQUFDLENBQUM7QUFDOUQsQ0FBQyxDQUFDO0FBRUYsTUFBTSxjQUFjLEdBQUcsQ0FBQyxLQUFZLEVBQUUsRUFBRSxDQUN0QyxTQUFTLGVBQWUsQ0FBaUIsSUFBUztJQUNoRCxNQUFNLFNBQVMs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

package/build/main/lib/middleware.d.ts

@@ -1,36 +1,22 @@
 import type { NextFunction, Request, Response } from 'express';
 import { type Options, type Schema } from 'fast-json-stringify';
-import { type OverrideErrorHandler } from './override';
 export type { Schema, Options } from 'fast-json-stringify';
-export type FastJsonSchemaOptions = Omit<Options, 'mode'> & {
-    /**
-     * Also route `res.json()` — and therefore `res.send(object)`, which Express
-     * implements on top of it — through the compiled serializer.
-     *
-     * Off by default. Because a single schema describes the successful payload,
-     * only `2xx` responses take the fast path: an error body would otherwise be
-     * rewritten into the shape of the success schema.
-     */
-    readonly overrideJson?: boolean;
-    /**
-     * Called when an overridden `res.json()` could not use the fast path because
-     * the serializer threw. The response falls back to the stock `res.json()`
-     * either way; this is only so the mismatch is visible.
-     */
-    readonly onError?: OverrideErrorHandler;
-};
+export type FastJsonSchemaOptions = Omit<Options, 'mode'>;
 /**
- * Build a stringify function using a schema of the documents that should be stringified
+ * Build a middleware that gives its route a serializer compiled from the schema.
+ * The application needs `installFastJson(app)` once for `res.fastJson()` to exist.
+ *
  * @param {Schema} schema The schema used to stringify values
- * @param {Options} options The options to use (optional)
+ * @param {FastJsonSchemaOptions} options The fast-json-stringify options (optional)
  * @see https://www.npmjs.com/package/fast-json-stringify
  *
  * Examples:
  * ```ts
  * import express from 'express';
- * import { fastJsonSchema, Schema } from 'express-fast-json-stringify';
+ * import { installFastJson, fastJsonSchema, Schema } from 'express-fast-json-stringify';
  *
  * const app = express();
+ * installFastJson(app);
  *
  * const schema: Schema = {
  *   title: 'Example Schema',
@@ -62,20 +48,4 @@ export type FastJsonSchemaOptions = Omit<Options, 'mode'> & {
  * });
  * ```
  */
-export declare const fastJsonSchema: (schema: Schema, options?: FastJsonSchemaOptions) => (req: Request, res: Response, next: NextFunction) => void;
-declare global {
-    namespace Express {
-        interface Response {
-            /**
-             * Send JSON response.
-             *
-             * Examples:
-             * ```ts
-             * res.fastJson({ user: 'Simone Nigro' });
-             * res.status(200).fastJson({ user: 'Simone Nigro' });
-             * ```
-             */
-            fastJson: (body: any) => Response;
-        }
-    }
-}
+export declare const fastJsonSchema: (schema: Schema, options?: FastJsonSchemaOptions) => (_req: Request, res: Response, next: NextFunction) => void;

package/build/main/lib/middleware.js

@@ -1,35 +1,26 @@
 "use strict";
-var __rest = (this && this.__rest) || function (s, e) {
-    var t = {};
-    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
-        t[p] = s[p];
-    if (s != null && typeof Object.getOwnPropertySymbols === "function")
-        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
-            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
-                t[p[i]] = s[p[i]];
-        }
-    return t;
-};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fastJsonSchema = void 0;
 const fast_json_stringify_1 = __importDefault(require("fast-json-stringify"));
-const override_1 = require("./override");
-const send_1 = require("./send");
+const install_1 = require("./install");
 /**
- * Build a stringify function using a schema of the documents that should be stringified
+ * Build a middleware that gives its route a serializer compiled from the schema.
+ * The application needs `installFastJson(app)` once for `res.fastJson()` to exist.
+ *
  * @param {Schema} schema The schema used to stringify values
- * @param {Options} options The options to use (optional)
+ * @param {FastJsonSchemaOptions} options The fast-json-stringify options (optional)
  * @see https://www.npmjs.com/package/fast-json-stringify
  *
  * Examples:
  * ```ts
  * import express from 'express';
- * import { fastJsonSchema, Schema } from 'express-fast-json-stringify';
+ * import { installFastJson, fastJsonSchema, Schema } from 'express-fast-json-stringify';
  *
  * const app = express();
+ * installFastJson(app);
  *
  * const schema: Schema = {
  *   title: 'Example Schema',
@@ -65,27 +56,13 @@ const fastJsonSchema = (schema, options) => {
     if (!schema || (typeof schema !== 'object' && typeof schema !== 'boolean')) {
         throw new TypeError(`express-fast-json-stringify: invalid schema`);
     }
-    const _a = options !== null && options !== void 0 ? options : {}, { overrideJson = false, onError } = _a, fastJsonOptions = __rest(_a, ["overrideJson", "onError"]);
-    const fjs = (0, fast_json_stringify_1.default)(schema, fastJsonOptions);
-    return (req, res, next) => {
-        /**
-         * Send JSON response.
-         *
-         * Examples:
-         * ```ts
-         * res.fastJson({ user: 'Simone Nigro' });
-         * res.status(200).fastJson({ user: 'Simone Nigro' });
-         * ```
-         */
-        res.fastJson = (body) => (0, send_1.sendJson)(req, res, fjs(body));
-        if (overrideJson) {
-            // A single schema describes the successful payload, so applying it to an
-            // error body would rewrite it into the wrong shape. Only 2xx responses
-            // take the fast path; everything else keeps the stock res.json().
-            (0, override_1.overrideResJson)(req, res, (status) => (status >= 200 && status < 300 ? fjs : null), onError);
-        }
+    const serialize = (0, fast_json_stringify_1.default)(schema, options);
+    // One write on res.locals and a next(), nothing else on req or res: a framework that reads a
+    // middleware's source to skip work, fulmine does, must be able to see this touches no header
+    return (_req, res, next) => {
+        res.locals[install_1.kSerializer] = serialize;
         next();
     };
 };
 exports.fastJsonSchema = fastJsonSchema;
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibWlkZGxld2FyZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9saWIvbWlkZGxld2FyZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7Ozs7Ozs7Ozs7Ozs7OztBQUNBLDhFQUEwRTtBQUUxRSx5Q0FBd0U7QUFDeEUsaUNBQWtDO0FBc0JsQzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBMENHO0FBQ0ksTUFBTSxjQUFjLEdBQUcsQ0FBQyxNQUFjLEVBQUUsT0FBK0IsRUFBRSxFQUFFO0lBQ2hGLElBQUksQ0FBQyxNQUFNLElBQUksQ0FBQyxPQUFPLE1BQU0sS0FBSyxRQUFRLElBQUksT0FBTyxNQUFNLEtBQUssU0FBUyxDQUFDLEVBQUUsQ0FBQztRQUMzRSxNQUFNLElBQUksU0FBUyxDQUFDLDZDQUE2QyxDQUFDLENBQUM7SUFDckUsQ0FBQztJQUNELE1BQU0sS0FBd0QsT0FBTyxhQUFQLE9BQU8sY0FBUCxPQUFPLEdBQUksRUFBRSxFQUFyRSxFQUFFLFlBQVksR0FBRyxLQUFLLEVBQUUsT0FBTyxPQUFzQyxFQUFqQyxlQUFlLGNBQW5ELDJCQUFxRCxDQUFnQixDQUFDO0lBQzVFLE1BQU0sR0FBRyxHQUFHLElBQUEsNkJBQVEsRUFBQyxNQUFNLEVBQUUsZUFBZSxDQUFDLENBQUM7SUFDOUMsT0FBTyxDQUFDLEdBQVksRUFBRSxHQUFhLEVBQUUsSUFBa0IsRUFBRSxFQUFFO1FBQ3pEOzs7Ozs7OztXQVFHO1FBQ0gsR0FBRyxDQUFDLFFBQVEsR0FBRyxDQUFDLElBQVMsRUFBWSxFQUFFLENBQUMsSUFBQSxlQUFRLEVBQUMsR0FBRyxFQUFFLEdBQUcsRUFBRSxHQUFHLENBQUMsSUFBSSxDQUFDLENBQUMsQ0FBQztRQUV0RSxJQUFJLFlBQVksRUFBRSxDQUFDO1lBQ2pCLHlFQUF5RTtZQUN6RSx1RUFBdUU7WUFDdkUsa0VBQWtFO1lBQ2xFLElBQUEsMEJBQWUsRUFBQyxHQUFHLEVBQUUsR0FBRyxFQUFFLENBQUMsTUFBTSxFQUFFLEVBQUUsQ0FBQyxDQUFDLE1BQU0sSUFBSSxHQUFHLElBQUksTUFBTSxHQUFHLEdBQUcsQ0FBQyxDQUFDLENBQUMsR0FBRyxDQUFDLENBQUMsQ0FBQyxJQUFJLENBQUMsRUFBRSxPQUFPLENBQUMsQ0FBQztRQUMvRixDQUFDO1FBRUQsSUFBSSxFQUFFLENBQUM7SUFDVCxDQUFDLENBQUM7QUFDSixDQUFDLENBQUM7QUEzQlcsUUFBQSxjQUFjLGtCQTJCekIifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibWlkZGxld2FyZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9saWIvbWlkZGxld2FyZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7Ozs7QUFDQSw4RUFBbUY7QUFFbkYsdUNBQXlEO0FBTXpEOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7R0E2Q0c7QUFDSSxNQUFNLGNBQWMsR0FBRyxDQUFDLE1BQWMsRUFBRSxPQUErQixFQUFFLEVBQUU7SUFDaEYsSUFBSSxDQUFDLE1BQU0sSUFBSSxDQUFDLE9BQU8sTUFBTSxLQUFLLFFBQVEsSUFBSSxPQUFPLE1BQU0sS0FBSyxTQUFTLENBQUMsRUFBRSxDQUFDO1FBQzNFLE1BQU0sSUFBSSxTQUFTLENBQUMsNkNBQTZDLENBQUMsQ0FBQztJQUNyRSxDQUFDO0lBQ0QsTUFBTSxTQUFTLEdBQWUsSUFBQSw2QkFBaUIsRUFBQyxNQUFNLEVBQUUsT0FBTyxDQUFDLENBQUM7SUFDakUsNkZBQTZGO0lBQzdGLDZGQUE2RjtJQUM3RixPQUFPLENBQUMsSUFBYSxFQUFFLEdBQWEsRUFBRSxJQUFrQixFQUFRLEVBQUU7UUFDL0QsR0FBRyxDQUFDLE1BQWlELENBQUMscUJBQVcsQ0FBQyxHQUFHLFNBQVMsQ0FBQztRQUNoRixJQUFJLEVBQUUsQ0FBQztJQUNULENBQUMsQ0FBQztBQUNKLENBQUMsQ0FBQztBQVhXLFFBQUEsY0FBYyxrQkFXekIifQ==