fastify 5.2.1 → 5.2.2

package/docs/Reference/Errors.md

@@ -102,8 +102,8 @@
 <a id="error-handling"></a>
 
 #### Uncaught Errors
-In Node.js, uncaught errors are likely to cause memory leaks, file descriptor
-leaks, and other major production issues.
+In Node.js, uncaught errors can cause memory leaks, file descriptor leaks, and
+other major production issues.
 [Domains](https://nodejs.org/en/docs/guides/domain-postmortem/) were a failed
 attempt to fix this.
 
@@ -112,29 +112,28 @@ way to deal with them is to
 [crash](https://nodejs.org/api/process.html#process_warning_using_uncaughtexception_correctly).
 
 #### Catching Errors In Promises
-If you are using promises, you should attach a `.catch()` handler synchronously.
+When using promises, attach a `.catch()` handler synchronously.
 
 ### Errors In Fastify
-Fastify follows an all-or-nothing approach and aims to be lean and optimal as
-much as possible. The developer is responsible for making sure that the errors
-are handled properly.
+Fastify follows an all-or-nothing approach and aims to be lean and optimal. The
+developer is responsible for ensuring errors are handled properly.
 
 #### Errors In Input Data
-Most errors are a result of unexpected input data, so we recommend [validating
-your input data against a JSON schema](./Validation-and-Serialization.md).
+Most errors result from unexpected input data, so it is recommended to
+[validate input data against a JSON schema](./Validation-and-Serialization.md).
 
 #### Catching Uncaught Errors In Fastify
-Fastify tries to catch as many uncaught errors as it can without hindering
+Fastify tries to catch as many uncaught errors as possible without hindering
 performance. This includes:
 
 1. synchronous routes, e.g. `app.get('/', () => { throw new Error('kaboom') })`
 2. `async` routes, e.g. `app.get('/', async () => { throw new Error('kaboom')
    })`
 
-The error in both cases will be caught safely and routed to Fastify's default
-error handler for a generic `500 Internal Server Error` response.
+In both cases, the error will be caught safely and routed to Fastify's default
+error handler, resulting in a generic `500 Internal Server Error` response.
 
-To customize this behavior you should use
+To customize this behavior, use
 [`setErrorHandler`](./Server.md#seterrorhandler).
 
 ### Errors In Fastify Lifecycle Hooks And A Custom Error Handler
@@ -144,52 +143,50 @@ From the [Hooks documentation](./Hooks.md#manage-errors-from-a-hook):
 > `done()` and Fastify will automatically close the request and send the
 > appropriate error code to the user.
 
-When a custom error handler has been defined through
-[`setErrorHandler`](./Server.md#seterrorhandler), the custom error handler will
-receive the error passed to the `done()` callback (or through other supported
-automatic error handling mechanisms). If `setErrorHandler` has been used
-multiple times to define multiple handlers, the error will be routed to the most
-precedent handler defined within the error [encapsulation
-context](./Encapsulation.md). Error handlers are fully encapsulated, so a
-`setErrorHandler` call within a plugin will limit the error handler to that
-plugin's context.
+When a custom error handler is defined through
+[`setErrorHandler`](./Server.md#seterrorhandler), it will receive the error
+passed to the `done()` callback or through other supported automatic error
+handling mechanisms. If `setErrorHandler` is used multiple times, the error will
+be routed to the most precedent handler within the error
+[encapsulation context](./Encapsulation.md). Error handlers are fully
+encapsulated, so a `setErrorHandler` call within a plugin will limit the error
+handler to that plugin's context.
 
 The root error handler is Fastify's generic error handler. This error handler
 will use the headers and status code in the `Error` object, if they exist. The
 headers and status code will not be automatically set if a custom error handler
 is provided.
 
-Some things to consider in your custom error handler:
+The following should be considered when using a custom error handler:
 
-- you can `reply.send(data)`, which will behave as it would in [regular route
-  handlers](./Reply.md#senddata)
+- `reply.send(data)` behaves as in [regular route handlers](./Reply.md#senddata)
   - objects are serialized, triggering the `preSerialization` lifecycle hook if
-    you have one defined
-  - strings, buffers, and streams are sent to the client, with appropriate
-    headers (no serialization)
-
-- You can throw a new error in your custom error handler - errors (new error or
-	the received error parameter re-thrown) - will call the parent `errorHandler`.
-  - `onError` hook will be triggered once only for the first error being thrown.
-  - an error will not be triggered twice from a lifecycle hook - Fastify
-    internally monitors the error invocation to avoid infinite loops for errors
-    thrown in the reply phases of the lifecycle. (those after the route handler)
-
-When utilizing Fastify's custom error handling through [`setErrorHandler`](./Server.md#seterrorhandler),
-you should be aware of how errors are propagated between custom and default
-error handlers.
-
-If a plugin's error handler re-throws an error, and the error is not an
-instance of [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)
-(as seen in the `/bad` route in the following example), it will not propagate
-to the parent context error handler. Instead, it will be caught by the default
-error handler.
-
-To ensure consistent error handling, it is recommended to throw instances of
-`Error`. For instance, in the following example, replacing `throw 'foo'` with
-`throw new Error('foo')` in the `/bad` route ensures that errors propagate through
-the custom error handling chain as intended. This practice helps avoid potential
-pitfalls when working with custom error handling in Fastify.
+    defined
+  - strings, buffers, and streams are sent to the client with appropriate headers
+    (no serialization)
+
+- Throwing a new error in a custom error handler will call the parent
+  `errorHandler`.
+  - The `onError` hook will be triggered once for the first error thrown
+  - An error will not be triggered twice from a lifecycle hook. Fastify
+    internally monitors error invocation to avoid infinite loops for errors
+    thrown in the reply phases of the lifecycle (those after the route handler)
+
+When using Fastify's custom error handling through
+[`setErrorHandler`](./Server.md#seterrorhandler), be aware of how errors are
+propagated between custom and default error handlers.
+
+If a plugin's error handler re-throws an error that is not an instance of
+[Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error),
+it will not propagate to the parent context error handler. Instead, it will be
+caught by the default error handler. This can be seen in the `/bad` route of the
+example below.
+
+To ensure consistent error handling, throw instances of `Error`. For example,
+replace `throw 'foo'` with `throw new Error('foo')` in the `/bad` route to
+ensure errors propagate through the custom error handling chain as intended.
+This practice helps avoid potential pitfalls when working with custom error
+handling in Fastify.
 
 For example:
 ```js
@@ -242,7 +239,7 @@ You can access `errorCodes` for mapping:
 // ESM
 import { errorCodes } from 'fastify'
 
-// CommonJs
+// CommonJS
 const errorCodes = require('fastify').errorCodes
 ```
 
@@ -267,7 +264,7 @@ fastify.setErrorHandler(function (error, request, reply) {
     // Send error response
     reply.status(500).send({ ok: false })
   } else {
-    // fastify will use parent error handler to handle this
+    // Fastify will use parent error handler to handle this
     reply.send(error)
   }
 })
@@ -282,7 +279,7 @@ fastify.listen({ port: 3000 }, function (err, address) {
 })
 ```
 
-Below is a table with all the error codes that Fastify uses.
+Below is a table with all the error codes used by Fastify.
 
 | Code | Description | How to solve | Discussion |
 |------|-------------|--------------|------------|

package/docs/Reference/HTTP2.md

@@ -2,11 +2,11 @@
 
 ## HTTP2
 
-_Fastify_ supports HTTP2 over either HTTPS (h2) or plaintext (h2c).
+_Fastify_ supports HTTP2 over HTTPS (h2) or plaintext (h2c).
 
 Currently, none of the HTTP2-specific APIs are available through _Fastify_, but
-Node's `req` and `res` can be accessed through our `Request` and `Reply`
-interface. PRs are welcome.
+Node's `req` and `res` can be accessed through the `Request` and `Reply`
+interfaces. PRs are welcome.
 
 ### Secure (HTTPS)
 
@@ -61,7 +61,7 @@ fastify.get('/', function (request, reply) {
 fastify.listen({ port: 3000 })
 ```
 
-You can test your new server with:
+Test the new server with:
 
 ```
 $ npx h2url https://localhost:3000
@@ -69,8 +69,8 @@ $ npx h2url https://localhost:3000
 
 ### Plain or insecure
 
-If you are building microservices, you can connect to HTTP2 in plain text,
-however, this is not supported by browsers.
+For microservices, HTTP2 can connect in plain text, but this is not
+supported by browsers.
 
 ```js
 'use strict'
@@ -86,7 +86,7 @@ fastify.get('/', function (request, reply) {
 fastify.listen({ port: 3000 })
 ```
 
-You can test your new server with:
+Test the new server with:
 
 ```
 $ npx h2url http://localhost:3000

package/docs/Reference/Hooks.md

@@ -34,9 +34,9 @@ are Request/Reply hooks and application hooks:
 - [Using Hooks to Inject Custom Properties](#using-hooks-to-inject-custom-properties)
 - [Diagnostics Channel Hooks](#diagnostics-channel-hooks)
 
-**Notice:** the `done` callback is not available when using `async`/`await` or
-returning a `Promise`. If you do invoke a `done` callback in this situation
-unexpected behavior may occur, e.g. duplicate invocation of handlers.
+> 🛈 Note: The `done` callback is not available when using `async`/`await` or
+> returning a `Promise`. If you do invoke a `done` callback in this situation
+> unexpected behavior may occur, e.g. duplicate invocation of handlers.
 
 ## Request/Reply Hooks
 
@@ -68,9 +68,9 @@ fastify.addHook('onRequest', async (request, reply) => {
 })
 ```
 
-**Notice:** in the [onRequest](#onrequest) hook, `request.body` will always be
-`undefined`, because the body parsing happens before the
-[preValidation](#prevalidation) hook.
+> 🛈 Note: In the [onRequest](#onrequest) hook, `request.body` will always be
+> `undefined`, because the body parsing happens before the
+> [preValidation](#prevalidation) hook.
 
 ### preParsing
 
@@ -98,17 +98,17 @@ fastify.addHook('preParsing', async (request, reply, payload) => {
 })
 ```
 
-**Notice:** in the [preParsing](#preparsing) hook, `request.body` will always be
-`undefined`, because the body parsing happens before the
-[preValidation](#prevalidation) hook.
+> 🛈 Note: In the [preParsing](#preparsing) hook, `request.body` will always be
+> `undefined`, because the body parsing happens before the
+> [preValidation](#prevalidation) hook.
 
-**Notice:** you should also add a `receivedEncodedLength` property to the
-returned stream. This property is used to correctly match the request payload
-with the `Content-Length` header value. Ideally, this property should be updated
-on each received chunk.
+> 🛈 Note: You should also add a `receivedEncodedLength` property to the
+> returned stream. This property is used to correctly match the request payload
+> with the `Content-Length` header value. Ideally, this property should be updated
+> on each received chunk.
 
-**Notice:** The size of the returned stream is checked to not exceed the limit
-set in [`bodyLimit`](./Server.md#bodylimit) option.
+> 🛈 Note: The size of the returned stream is checked to not exceed the limit
+> set in [`bodyLimit`](./Server.md#bodylimit) option.
 
 ### preValidation
 
@@ -166,8 +166,8 @@ fastify.addHook('preSerialization', async (request, reply, payload) => {
 })
 ```
 
-Note: the hook is NOT called if the payload is a `string`, a `Buffer`, a
-`stream`, or `null`.
+> 🛈 Note: The hook is NOT called if the payload is a `string`, a `Buffer`, a
+> `stream`, or `null`.
 
 ### onError
 ```js
@@ -196,8 +196,8 @@ user
 *(Note that the default error handler always sends the error back to the
 user)*.
 
-**Notice:** unlike the other hooks, passing an error to the `done` function is not
-supported.
+> 🛈 Note: Unlike the other hooks, passing an error to the `done` function is not
+> supported.
 
 ### onSend
 If you are using the `onSend` hook, you can change the payload. For example:
@@ -233,8 +233,8 @@ fastify.addHook('onSend', (request, reply, payload, done) => {
 > to `0`, whereas the `Content-Length` header will not be set if the payload is
 > `null`.
 
-Note: If you change the payload, you may only change it to a `string`, a
-`Buffer`, a `stream`, a `ReadableStream`, a `Response`, or `null`.
+> 🛈 Note: If you change the payload, you may only change it to a `string`, a
+> `Buffer`, a `stream`, a `ReadableStream`, a `Response`, or `null`.
 
 
 ### onResponse
@@ -256,8 +256,8 @@ The `onResponse` hook is executed when a response has been sent, so you will not
 be able to send more data to the client. It can however be useful for sending
 data to external services, for example, to gather statistics.
 
-**Note:** setting `disableRequestLogging` to `true` will disable any error log
-inside the `onResponse` hook. In this case use `try - catch` to log errors.
+> 🛈 Note: Setting `disableRequestLogging` to `true` will disable any error log
+> inside the `onResponse` hook. In this case use `try - catch` to log errors.
 
 ### onTimeout
 
@@ -298,7 +298,8 @@ The `onRequestAbort` hook is executed when a client closes the connection before
 the entire request has been processed. Therefore, you will not be able to send
 data to the client.
 
-**Notice:** client abort detection is not completely reliable. See: [`Detecting-When-Clients-Abort.md`](../Guides/Detecting-When-Clients-Abort.md)
+> 🛈 Note: Client abort detection is not completely reliable.
+> See: [`Detecting-When-Clients-Abort.md`](../Guides/Detecting-When-Clients-Abort.md)
 
 ### Manage Errors from a hook
 If you get an error during the execution of your hook, just pass it to `done()`
@@ -451,8 +452,8 @@ fastify.addHook('onListen', async function () {
 })
 ```
 
-> **Note**
-> This hook will not run when the server is started using `fastify.inject()` or `fastify.ready()`
+> 🛈 Note: This hook will not run when the server is started using
+> fastify.inject()` or `fastify.ready()`.
 
 ### onClose
 <a id="on-close"></a>
@@ -575,8 +576,8 @@ This hook can be useful if you are developing a plugin that needs to know when a
 plugin context is formed, and you want to operate in that specific context, thus
 this hook is encapsulated.
 
-**Note:** This hook will not be called if a plugin is wrapped inside
-[`fastify-plugin`](https://github.com/fastify/fastify-plugin).
+> 🛈 Note: This hook will not be called if a plugin is wrapped inside
+> [`fastify-plugin`](https://github.com/fastify/fastify-plugin).
 ```js
 fastify.decorate('data', [])
 
@@ -773,7 +774,7 @@ fastify.route({
 })
 ```
 
-**Note**: both options also accept an array of functions.
+> 🛈 Note: Both options also accept an array of functions.
 
 ## Using Hooks to Inject Custom Properties
 <a id="using-hooks-to-inject-custom-properties"></a>
@@ -860,7 +861,7 @@ channel.subscribe(function ({ fastify }) {
 })
 ```
 
-> **Note:** The TracingChannel class API is currently experimental and may undergo
+> 🛈 Note: The TracingChannel class API is currently experimental and may undergo
 > breaking changes even in semver-patch releases of Node.js.
 
 Five other events are published on a per-request basis following the

package/docs/Reference/LTS.md

@@ -1,8 +1,7 @@
 <h1 align="center">Fastify</h1>
 
 ## Long Term Support
-
-`<a id="lts"></a>`
+<a id="lts"></a>
 
 Fastify's Long Term Support (LTS) is provided according to the schedule laid out
 in this document:
@@ -25,13 +24,11 @@ in this document:
    and verified against alternative runtimes that are compatible with Node.js.
    The maintenance teams of these alternative runtimes are responsible for ensuring
    and guaranteeing these tests work properly.
-      1. [N|Solid](https://docs.nodesource.com/nsolid), maintained by NodeSource,
-      commits to testing and verifying each Fastify major release against the N|Solid
-      LTS versions that are current at the time of the Fastify release.
-      NodeSource guarantees that Fastify will be compatible and function correctly
-      with N|Solid, aligning with the support and compatibility scope of the N|Solid
-      LTS versions available at the time of the Fastify release.
-      This ensures users of N|Solid can confidently use Fastify.
+   1. [N|Solid](https://docs.nodesource.com/docs/product_suite) tests and
+      verifies each Fastify major release against current N|Solid LTS versions.
+      NodeSource ensures Fastify compatibility with N|Solid, aligning with the
+      support scope of N|Solid LTS versions at the time of the Fastify release.
+      This guarantees N|Solid users can confidently use Fastify.
 
 A "month" is defined as 30 consecutive days.
 
@@ -41,12 +38,12 @@ A "month" is defined as 30 consecutive days.
 > occasions where we need to release breaking changes as a _minor_ version
 > release. Such changes will _always_ be noted in the [release
 > notes](https://github.com/fastify/fastify/releases).
->
+> 
 > To avoid automatically receiving breaking security updates it is possible to
 > use the tilde (`~`) range qualifier. For example, to get patches for the 3.15
 > release, and avoid automatically updating to the 3.16 release, specify the
 > dependency as `"fastify": "~3.15.x"`. This will leave your application
-> vulnerable, so please use with caution.
+> vulnerable, so please use it with caution.
 
 ### Security Support Beyond LTS
 
@@ -55,8 +52,7 @@ OpenJS Ecosystem Sustainability Program for versions of Fastify that are EOL.
 For more information, see their [Never Ending Support][hd-link] service.
 
 ### Schedule
-
-`<a id="lts-schedule"></a>`
+<a id="lts-schedule"></a>
 
 | Version | Release Date | End Of LTS Date | Node.js            | Nsolid(Node)   |
 | :------ | :----------- | :-------------- | :----------------- | :------------- |
@@ -67,8 +63,7 @@ For more information, see their [Never Ending Support][hd-link] service.
 | 5.0.0   | 2024-09-17   | TBD             | 20, 22             | v5(20)         |
 
 ### CI tested operating systems
-
-`<a id="supported-os"></a>`
+<a id="supported-os"></a>
 
 Fastify uses GitHub Actions for CI testing, please refer to [GitHub&#39;s
 documentation regarding workflow

package/docs/Reference/Lifecycle.md

@@ -3,12 +3,11 @@
 ## Lifecycle
 <a id="lifecycle"></a>
 
-Following the schema of the internal lifecycle of Fastify.
+This schema shows the internal lifecycle of Fastify.
 
-On the right branch of every section there is the next phase of the lifecycle,
-on the left branch there is the corresponding error code that will be generated
-if the parent throws an error *(note that all the errors are automatically
-handled by Fastify)*.
+The right branch of each section shows the next phase of the lifecycle. The left
+branch shows the corresponding error code generated if the parent throws an
+error. All errors are automatically handled by Fastify.
 
 ```
 Incoming Request
@@ -42,26 +41,23 @@ Incoming Request
                                                                             └─▶ onResponse Hook
 ```
 
-At any point before or during the `User Handler`, `reply.hijack()` can be called
-to prevent Fastify from:
-- Running all the following hooks and user handler
-- Sending the response automatically
+Before or during the `User Handler`, `reply.hijack()` can be called to:
+- Prevent Fastify from running subsequent hooks and the user handler
+- Prevent Fastify from sending the response automatically
 
-NB (*): If `reply.raw` is used to send a response back to the user, `onResponse`
-hooks will still be executed
+If `reply.raw` is used to send a response, `onResponse` hooks will still
+be executed.
 
 ## Reply Lifecycle
 <a id="reply-lifecycle"></a>
 
-Whenever the user handles the request, the result may be:
+When the user handles the request, the result may be:
 
-- in async handler: it returns a payload
-- in async handler: it throws an `Error`
-- in sync handler: it sends a payload
-- in sync handler: it sends an `Error` instance
+- In an async handler: it returns a payload or throws an `Error`
+- In a sync handler: it sends a payload or an `Error` instance
 
-If the reply was hijacked, we skip all the below steps. Otherwise, when it is
-being submitted, the data flow performed is the following:
+If the reply was hijacked, all subsequent steps are skipped. Otherwise, when
+submitted, the data flow is as follows:
 
 ```
                         ★ schema validation Error
@@ -81,9 +77,8 @@ being submitted, the data flow performed is the following:
                                                                                 └─▶ reply sent
 ```
 
-Note: `reply sent` means that the JSON payload will be serialized by:
-
-- the [reply serialized](./Server.md#setreplyserializer) if set
-- or by the [serializer compiler](./Server.md#setserializercompiler) when a JSON
-  schema has been set for the returning HTTP status code
-- or by the default `JSON.stringify` function
+`reply sent` means the JSON payload will be serialized by one of the following:
+- The [reply serializer](./Server.md#setreplyserializer) if set
+- The [serializer compiler](./Server.md#setserializercompiler) if a JSON schema
+  is set for the HTTP status code
+- The default `JSON.stringify` function