express-fast-json-stringify 1.2.9 → 2.0.0

package/CHANGELOG.md

@@ -1,53 +1,73 @@
 # 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))
+
+### 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))
+
 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.
 
 ### [1.2.9](https://github.com/nigrosimone/express-fast-json-stringify/compare/v1.2.8...v1.2.9) (2026-01-18)
 
-### [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))
-
-### [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))
-
-### [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))
-
-### [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))
-
-### [1.1.4](https://github.com/nigrosimone/express-fast-json-stringify/compare/v1.1.2...v1.1.4) (2024-09-29)
-
-### [1.1.2](https://github.com/nigrosimone/express-fast-json-stringify/compare/v1.1.0...v1.1.2) (2024-09-29)
-
-## 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))
-
-
-### Bug Fixes
-
-* ignore publish ([ca95f45](https://github.com/nigrosimone/express-fast-json-stringify/commit/ca95f450e1ce22f957fff4cd9f7520386ee70962))
+### [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))
+
+### [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))
+
+### [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))
+
+### [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))
+
+### [1.1.4](https://github.com/nigrosimone/express-fast-json-stringify/compare/v1.1.2...v1.1.4) (2024-09-29)
+
+### [1.1.2](https://github.com/nigrosimone/express-fast-json-stringify/compare/v1.1.0...v1.1.2) (2024-09-29)
+
+## 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))
+
+### Bug Fixes
+
+- ignore publish ([ca95f45](https://github.com/nigrosimone/express-fast-json-stringify/commit/ca95f450e1ce22f957fff4cd9f7520386ee70962))

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2019 Nigro Simone
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2019 Nigro Simone
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,116 +1,307 @@
-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.
-
-## What is fast-json-stringify?
-
-`fast-json-stringify` is a JSON serialization library developed by the Fastify team. It enhances JSON conversion speed by analyzing JSON schema definitions and compiling them into highly optimized serialization functions. This makes it much faster than the native `JSON.stringify()`, particularly beneficial for high-performance applications.
-
-## Introducing express-fast-json-stringify
-
-`express-fast-json-stringify` is an npm package that brings the performance benefits of `fast-json-stringify` to Express.js applications. By integrating this package, you can achieve faster JSON serialization, thus improving the overall performance of your application.
-
-## Installation
-
-First, install the `express-fast-json-stringify` package:
-
-```
-npm install express-fast-json-stringify
-```
-
-## Creating a JSON Schema
-
-Define a schema object that specifies the structure of your JSON responses. This schema will be used by `fast-json-stringify` to optimize the serialization process.
-
-```ts
-import { Schema } from 'express-fast-json-stringify';
-
-const schema: Schema = {
-  title: 'Example Schema',
-  type: 'object',
-  properties: {
-    firstName: { type: 'string' },
-    lastName: { type: 'string' },
-    age: {
-      description: 'Age in years',
-      type: 'integer',
-    },
-  },
-};
-```
-
-## 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.
-
-```ts
-import express from 'express';
-import { fastJsonSchema, Schema } from 'express-fast-json-stringify';
-
-const app = express();
-
-const exampleSchema: Schema = {
-  title: 'Example Schema',
-  type: 'object',
-  properties: {
-    firstName: { type: 'string' },
-    lastName: { type: 'string' },
-    age: { type: 'integer' },
-  },
-};
-
-app.get('/', fastJsonSchema(exampleSchema), (req, res, next) => {});
-```
-
-## Sending JSON Responses
-
-Instead of using the default `res.json()` method, use the `res.fastJson()` method provided by the middleware to send JSON responses. This leverages the speed benefits of fast-json-stringify.
-
-```ts
-import express from 'express';
-import { fastJsonSchema, Schema } from 'express-fast-json-stringify';
-
-const app = express();
-
-const schema: Schema = {
-  title: 'Example Schema',
-  type: 'object',
-  properties: {
-    firstName: { type: 'string' },
-    lastName: { type: 'string' },
-    age: {
-      description: 'Age in years',
-      type: 'integer',
-    },
-  },
-};
-
-app.get('/', fastJsonSchema(schema), (req, res, next) => {
-  try {
-    const data = {
-      firstName: 'Simone',
-      lastName: 'Nigro',
-      age: 40,
-    };
-    res.fastJson(data);
-  } catch (error) {
-    next(error);
-  }
-});
-```
-
-## Performance Benefits
-
-Using `express-fast-json-stringify` offers several performance benefits:
-
-1. **Increased Speed**: `fast-json-stringify` can serialize JSON data much faster than JSON.stringify(), especially for complex JSON objects.
-2. **Reduced CPU Usage**: Faster serialization means less CPU time spent on processing, allowing your server to handle more concurrent requests.
-3. **Consistency and Validation**: By defining JSON schemas, you ensure that the serialized data adheres to a predefined structure, improving data consistency and reducing the likelihood of errors.
-
-## Conclusion
-
-Integrating `express-fast-json-stringify` into your Express.js application can provide substantial performance improvements, especially in scenarios where JSON serialization is a bottleneck. By leveraging the power of `fast-json-stringify`, you can achieve faster response times and handle higher loads, making your application more efficient and scalable.
-
-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 live demo, you can check out the [StackBlitz demo](https://stackblitz.com/edit/express-fast-json-stringify).
-
-## Support
-
-This is an open-source project. Star this [repository](https://github.com/nigrosimone/express-fast-json-stringify), if you like it, or even [donate](https://www.paypal.com/paypalme/snwp). Thank you so much!
+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.
+
+## Introducing express-fast-json-stringify
+
+`express-fast-json-stringify` is an npm package that brings the performance benefits of `fast-json-stringify` to Express.js applications. By integrating this package, you can achieve faster JSON serialization, thus improving the overall performance of your application.
+
+## Installation
+
+First, install the `express-fast-json-stringify` package:
+
+```
+npm install express-fast-json-stringify
+```
+
+It requires Express 4.16 or newer (Express 5 included) and Node.js 20 or newer.
+
+## Creating a JSON Schema
+
+Define a schema object that specifies the structure of your JSON responses. This schema will be used by `fast-json-stringify` to optimize the serialization process.
+
+```ts
+import { Schema } from 'express-fast-json-stringify';
+
+const schema: Schema = {
+  title: 'Example Schema',
+  type: 'object',
+  properties: {
+    firstName: { type: 'string' },
+    lastName: { type: 'string' },
+    age: {
+      description: 'Age in years',
+      type: 'integer',
+    },
+  },
+};
+```
+
+## 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. It picks the serializer for that route.
+
+```ts
+import express from 'express';
+import { fastJsonSchema, installFastJson, Schema } from 'express-fast-json-stringify';
+
+const app = express();
+installFastJson(app);
+
+const exampleSchema: Schema = {
+  title: 'Example Schema',
+  type: 'object',
+  properties: {
+    firstName: { type: 'string' },
+    lastName: { type: 'string' },
+    age: { type: 'integer' },
+  },
+};
+
+app.get('/', fastJsonSchema(exampleSchema), (req, res, next) => {});
+```
+
+## Sending JSON Responses
+
+Instead of using the default `res.json()` method, use the `res.fastJson()` method provided by the middleware to send JSON responses. This leverages the speed benefits of fast-json-stringify.
+
+```ts
+import express from 'express';
+import { fastJsonSchema, installFastJson, Schema } from 'express-fast-json-stringify';
+
+const app = express();
+installFastJson(app);
+
+const schema: Schema = {
+  title: 'Example Schema',
+  type: 'object',
+  properties: {
+    firstName: { type: 'string' },
+    lastName: { type: 'string' },
+    age: {
+      description: 'Age in years',
+      type: 'integer',
+    },
+  },
+};
+
+app.get('/', fastJsonSchema(schema), (req, res, next) => {
+  try {
+    const data = {
+      firstName: 'Simone',
+      lastName: 'Nigro',
+      age: 40,
+    };
+    res.fastJson(data);
+  } catch (error) {
+    next(error);
+  }
+});
+```
+
+## Response semantics
+
+`res.fastJson()` is a drop-in replacement for `res.json()`: only the
+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`; 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`.                                 |
+| `HEAD`               | Headers only, `Content-Length` included.                                                            |
+
+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.
+It installs itself, so there is no `installFastJson(app)` to call and no
+middleware runs per request:
+
+```ts
+import express from 'express';
+import { fastJsonOpenApi } from 'express-fast-json-stringify';
+
+import document from './openapi.json' with { type: 'json' };
+
+const app = express();
+
+// Once for the whole app.
+fastJsonOpenApi(app, document);
+
+app.get('/users/:id', (req, res, next) => {
+  try {
+    // Serialized with the schema of `get /users/{id}` -> `200`.
+    res.fastJson(user);
+  } catch (error) {
+    next(error);
+  }
+});
+
+app.post('/users', (req, res, next) => {
+  try {
+    // ...and this one with the schema of `post /users` -> `201`.
+    res.status(201).fastJson(user);
+  } catch (error) {
+    next(error);
+  }
+});
+```
+
+The document is a plain object, so this works with whatever produces yours:
+
+| Tool                        | How to pass it                                                         |
+| --------------------------- | ---------------------------------------------------------------------- |
+| `swagger-jsdoc`             | `fastJsonOpenApi(swaggerJsdoc(options))`                               |
+| `swagger-ui-express`        | the same object you hand to `swaggerUi.setup(document)`                |
+| `express-openapi-validator` | the same document you pass as `apiSpec` (or the parsed YAML/JSON file) |
+| `tsoa`                      | the generated `swagger.json`                                           |
+| hand written                | `import document from './openapi.json' with { type: 'json' }`          |
+
+There is no dependency on any of them: the middleware only reads `paths`,
+`components.schemas` (OpenAPI 3.x) and `definitions` (Swagger 2.0).
+
+### What it resolves
+
+- **The operation** comes from the matched Express route, so `/users/:id`
+  under a router mounted at `/api` looks up `/api/users/{id}`. Parameter
+  modifiers (`:id?`, `:id(\d+)`) are ignored, as OpenAPI has no equivalent.
+  A `HEAD` request falls back to the `get` operation, the way Express does.
+- **The response** is matched most specific first: the exact status code, then
+  the wildcard range (`2XX`), then `default`. `res.status(404).fastJson(...)`
+  therefore serializes with the `404` schema.
+- **`$ref`** is resolved against the document, including recursive references,
+  so `#/components/schemas/User` and `#/definitions/User` both just work.
+- **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 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, 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
+document can never reach a client — `npm run example:openapi` shows a
+`passwordHash` being dropped from an otherwise ordinary response object.
+
+### Adopting it without touching your routes
+
+Everything above needs you to call `res.fastJson()`. In an existing codebase
+that means editing every `res.json()` call site, which is a lot of churn for a
+serialization change. `overrideJson` removes that step:
+
+```ts
+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, 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:
+
+- the document describes no schema for that route and status code;
+- the app sets `json replacer`, `json spaces` or `json escape` — those change
+  the bytes `res.json()` writes and a compiled serializer cannot reproduce them;
+- the serializer rejects the body, for instance because a required property is
+  missing. Pass `onError` to be told when that happens:
+
+```ts
+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.
+
+`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
+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()
+});
+```
+
+## Performance Benefits
+
+Using `express-fast-json-stringify` offers several benefits:
+
+1. **Increased Speed**: a compiled serializer only writes the properties the schema describes, so the more your objects carry that the response does not need, the more time it saves.
+2. **Reduced CPU Usage**: faster serialization means less CPU time spent on processing, allowing your server to handle more concurrent requests.
+3. **Consistency and Validation**: by defining JSON schemas, you ensure that the serialized data adheres to a predefined structure, improving data consistency and reducing the likelihood of errors — and properties missing from the schema never leak into a response.
+
+How much you gain depends on the payload, and on a current V8 it is not a win across the board. Measured on Node.js 26 by `npm run example`:
+
+| Case                                       | `fast-json-stringify` vs `JSON.stringify`   |
+| ------------------------------------------ | ------------------------------------------- |
+| objects carrying fields outside the schema | much faster (≈9x when 17 of 20 are dropped) |
+| a single small object                      | comparable                                  |
+| every field serialized                     | comparable                                  |
+| long strings                               | slower                                      |
+
+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, 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
+
+This is an open-source project. Star this [repository](https://github.com/nigrosimone/express-fast-json-stringify), if you like it, or even [donate](https://www.paypal.com/paypalme/snwp). Thank you so much!

package/build/main/index.d.ts

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

package/build/main/index.js

@@ -14,5 +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);
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7Ozs7Ozs7OztBQUFBLG1EQUFpQyJ9
+__exportStar(require("./lib/openapi"), exports);
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7Ozs7Ozs7Ozs7QUFBQSx5Q0FBbUg7QUFBeEYsMEdBQUEsZUFBZSxPQUFBO0FBQzFDLG1EQUFpQztBQUNqQyxnREFBOEIifQ==