fastify 5.2.0 → 5.2.2

package/docs/Reference/Logging.md

@@ -2,17 +2,18 @@
 
 ## Logging
 
-### Enable logging
-Logging is disabled by default, and you can enable it by passing `{ logger: true
-}` or `{ logger: { level: 'info' } }` when you create a Fastify instance. Note
-that if the logger is disabled, it is impossible to enable it at runtime. We use
-[abstract-logging](https://www.npmjs.com/package/abstract-logging) for this
-purpose.
+### Enable Logging
+Logging is disabled by default. Enable it by passing `{ logger: true }` or
+`{ logger: { level: 'info' } }` when creating a Fastify instance. Note that if
+the logger is disabled, it cannot be enabled at runtime.
+[abstract-logging](https://www.npmjs.com/package/abstract-logging) is used for
+this purpose.
 
 As Fastify is focused on performance, it uses
 [pino](https://github.com/pinojs/pino) as its logger, with the default log
-level, when enabled, set to `'info'`.
+level set to `'info'` when enabled.
 
+#### Basic logging setup
 Enabling the production JSON logger:
 
 ```js
@@ -21,8 +22,9 @@ const fastify = require('fastify')({
 })
 ```
 
-Enabling the logger with appropriate configuration for both local development
-and production and test environment requires a bit more configuration:
+#### Environment-Specific Configuration
+Enabling the logger with appropriate configuration for local development,
+production, and test environments requires more configuration:
 
 ```js
 const envToLogger = {
@@ -42,11 +44,11 @@ const fastify = require('fastify')({
   logger: envToLogger[environment] ?? true // defaults to true if no entry matches in the map
 })
 ```
-⚠️ `pino-pretty` needs to be installed as a dev dependency, it is not included
+⚠️ `pino-pretty` needs to be installed as a dev dependency. It is not included
 by default for performance reasons.
 
 ### Usage
-You can use the logger like this in your route handlers:
+The logger can be used in route handlers as follows:
 
 ```js
 fastify.get('/', options, function (request, reply) {
@@ -55,16 +57,16 @@ fastify.get('/', options, function (request, reply) {
 })
 ```
 
-You can trigger new logs outside route handlers by using the Pino instance from
-the Fastify instance:
+Trigger new logs outside route handlers using the Pino instance from the Fastify
+instance:
 ```js
 fastify.log.info('Something important happened!');
 ```
 
-If you want to pass some options to the logger, just pass them to Fastify.
-You can find all available options in the
-[Pino documentation](https://github.com/pinojs/pino/blob/master/docs/api.md#options).
-If you want to specify a file destination, use:
+#### Passing Logger Options
+To pass options to the logger, provide them to Fastify. See the
+[Pino documentation](https://github.com/pinojs/pino/blob/master/docs/api.md#options)
+for available options. To specify a file destination, use:
 
 ```js
 const fastify = require('fastify')({
@@ -80,8 +82,8 @@ fastify.get('/', options, function (request, reply) {
 })
 ```
 
-If you want to pass a custom stream to the Pino instance, just add a stream
-field to the logger object.
+To pass a custom stream to the Pino instance, add a `stream` field to the logger
+object:
 
 ```js
 const split = require('split2')
@@ -95,19 +97,21 @@ const fastify = require('fastify')({
 })
 ```
 
-<a id="logging-request-id"></a>
+### Advanced Logger Configuration
 
+<a id="logging-request-id"></a>
+#### Request ID Tracking
 By default, Fastify adds an ID to every request for easier tracking. If the
-requestIdHeader-option is set and the corresponding header is present than
-its value is used, otherwise a new incremental ID is generated. See Fastify
-Factory [`requestIdHeader`](./Server.md#factory-request-id-header) and Fastify
-Factory [`genReqId`](./Server.md#genreqid) for customization options.
+`requestIdHeader` option is set and the corresponding header is present, its
+value is used; otherwise, a new incremental ID is generated. See Fastify Factory
+[`requestIdHeader`](./Server.md#factory-request-id-header) and Fastify Factory
+[`genReqId`](./Server.md#genreqid) for customization options.
 
-The default logger is configured with a set of standard serializers that
-serialize objects with `req`, `res`, and `err` properties. The object received
-by `req` is the Fastify [`Request`](./Request.md) object, while the object
-received by `res` is the Fastify [`Reply`](./Reply.md) object. This behavior
-can be customized by specifying custom serializers.
+#### Serializers
+The default logger uses standard serializers for objects with `req`, `res`, and
+`err` properties. The `req` object is the Fastify [`Request`](./Request.md)
+object, and the `res` object is the Fastify [`Reply`](./Reply.md) object. This
+behavior can be customized with custom serializers.
 
 ```js
 const fastify = require('fastify')({
@@ -121,7 +125,7 @@ const fastify = require('fastify')({
 })
 ```
 For example, the response payload and headers could be logged using the approach
-below (even if it is *not recommended*):
+below (not recommended):
 
 ```js
 const fastify = require('fastify')({
@@ -142,10 +146,9 @@ const fastify = require('fastify')({
           url: request.url,
           path: request.routeOptions.url,
           parameters: request.params,
-          // Including the headers in the log could be in violation
-          // of privacy laws, e.g. GDPR. You should use the "redact" option to
-          // remove sensitive fields. It could also leak authentication data in
-          // the logs.
+          // Including headers in the log could violate privacy laws,
+          // e.g., GDPR. Use the "redact" option to remove sensitive
+          // fields. It could also leak authentication data in the logs.
           headers: request.headers
         };
       }
@@ -154,11 +157,11 @@ const fastify = require('fastify')({
 });
 ```
 
-**Note**: In certain cases, the [`Reply`](./Reply.md) object passed to the `res`
-serializer cannot be fully constructed. When writing a custom `res` serializer,
-it is necessary to check for the existence of any properties on `reply` aside
-from `statusCode`, which is always present. For example, the existence of
-`getHeaders` must be verified before it can be called:
+> 🛈 Note: In some cases, the [`Reply`](./Reply.md) object passed to the `res`
+> serializer cannot be fully constructed. When writing a custom `res`
+> serializer, check for the existence of any properties on `reply` aside from
+> `statusCode`, which is always present. For example, verify the existence of
+> `getHeaders` before calling it:
 
 ```js
 const fastify = require('fastify')({
@@ -170,7 +173,7 @@ const fastify = require('fastify')({
       res (reply) {
         // The default
         return {
-          statusCode: reply.statusCode
+          statusCode: reply.statusCode,
           headers: typeof reply.getHeaders === 'function'
             ? reply.getHeaders()
             : {}
@@ -181,11 +184,11 @@ const fastify = require('fastify')({
 });
 ```
 
-**Note**: The body cannot be serialized inside a `req` method because the
-request is serialized when we create the child logger. At that time, the body is
-not yet parsed.
+> 🛈 Note: The body cannot be serialized inside a `req` method because the
+request is serialized when the child logger is created. At that time, the body
+is not yet parsed.
 
-See an approach to log `req.body`
+See the following approach to log `req.body`:
 
 ```js
 app.addHook('preHandler', function (req, reply, done) {
@@ -196,18 +199,18 @@ app.addHook('preHandler', function (req, reply, done) {
 })
 ```
 
-**Note**: Care should be taken to ensure serializers never throw, as an error
-thrown from a serializer has the potential to cause the Node process to exit.
-See the [Pino documentation](https://getpino.io/#/docs/api?id=opt-serializers)
-on serializers for more information.
+> 🛈 Note: Ensure serializers never throw errors, as this can cause the Node
+> process to exit. See the
+> [Pino documentation](https://getpino.io/#/docs/api?id=opt-serializers) for more
+> information.
 
 *Any logger other than Pino will ignore this option.*
 
-You can also supply your own logger instance. Instead of passing configuration
-options, pass the instance as `loggerInstance`. The logger you supply must
-conform to the Pino interface; that is, it must have the following methods:
-`info`, `error`, `debug`, `fatal`, `warn`, `trace`, `silent`, `child` and a
-string property `level`.
+### Using Custom Loggers
+A custom logger instance can be supplied by passing it as `loggerInstance`. The
+logger must conform to the Pino interface, with methods: `info`, `error`,
+`debug`, `fatal`, `warn`, `trace`, `silent`, `child`, and a string property
+`level`.
 
 Example:
 
@@ -226,11 +229,11 @@ fastify.get('/', function (request, reply) {
 *The logger instance for the current request is available in every part of the
 [lifecycle](./Lifecycle.md).*
 
-## Log Redaction
+### Log Redaction
 
 [Pino](https://getpino.io) supports low-overhead log redaction for obscuring
-values of specific properties in recorded logs. As an example, we might want to
-log all the HTTP headers minus the `Authorization` header for security concerns:
+values of specific properties in recorded logs. For example, log all HTTP
+headers except the `Authorization` header for security:
 
 ```js
 const fastify = Fastify({

package/docs/Reference/Middleware.md

@@ -22,36 +22,36 @@ fastify.use(require('ienoopen')())
 fastify.use(require('x-xss-protection')())
 ```
 
-You can also use [`@fastify/middie`](https://github.com/fastify/middie), which provides
-support for simple Express-style middleware but with improved performance:
+[`@fastify/middie`](https://github.com/fastify/middie) can also be used,
+which provides support for simple Express-style middleware with improved
+performance:
 
 ```js
 await fastify.register(require('@fastify/middie'))
 fastify.use(require('cors')())
 ```
 
-Remember that middleware can be encapsulated; this means that you can decide
-where your middleware should run by using `register` as explained in the
-[plugins guide](../Guides/Plugins-Guide.md).
+Middleware can be encapsulated, allowing control over where it runs using
+`register` as explained in the [plugins guide](../Guides/Plugins-Guide.md).
 
-Fastify middleware does not expose the `send` method or other methods specific to
-the Fastify [Reply](./Reply.md#reply) instance. This is because Fastify wraps
+Fastify middleware does not expose the `send` method or other methods specific
+to the Fastify [Reply](./Reply.md#reply) instance. This is because Fastify wraps
 the incoming `req` and `res` Node instances using the
 [Request](./Request.md#request) and [Reply](./Reply.md#reply) objects
-internally, but this is done after the middleware phase. If you need to create
-middleware, you have to use the Node `req` and `res` instances. Otherwise, you
-can use the `preHandler` hook that already has the
-[Request](./Request.md#request) and [Reply](./Reply.md#reply) Fastify instances.
-For more information, see [Hooks](./Hooks.md#hooks).
+internally, but this is done after the middleware phase. To create middleware,
+use the Node `req` and `res` instances. Alternatively, use the `preHandler` hook
+that already has the Fastify [Request](./Request.md#request) and
+[Reply](./Reply.md#reply) instances. For more information, see
+[Hooks](./Hooks.md#hooks).
 
 #### Restrict middleware execution to certain paths
 <a id="restrict-usage"></a>
 
-If you need to only run middleware under certain paths, just pass the path as
-the first parameter to `use` and you are done!
+To run middleware under certain paths, pass the path as the first parameter to
+`use`.
 
-*Note that this does not support routes with parameters, (e.g.
-`/user/:id/comments`) and wildcards are not supported in multiple paths.*
+> 🛈 Note: This does not support routes with parameters
+> (e.g. `/user/:id/comments`) and wildcards are not supported in multiple paths.
 
 ```js
 const path = require('node:path')
@@ -69,10 +69,10 @@ fastify.use(['/css', '/js'], serveStatic(path.join(__dirname, '/assets')))
 
 ### Alternatives
 
-Fastify offers some alternatives to the most commonly used middleware, such as
-[`@fastify/helmet`](https://github.com/fastify/fastify-helmet) in case of
+Fastify offers alternatives to commonly used middleware, such as
+[`@fastify/helmet`](https://github.com/fastify/fastify-helmet) for
 [`helmet`](https://github.com/helmetjs/helmet),
 [`@fastify/cors`](https://github.com/fastify/fastify-cors) for
 [`cors`](https://github.com/expressjs/cors), and
 [`@fastify/static`](https://github.com/fastify/fastify-static) for
-[`serve-static`](https://github.com/expressjs/serve-static).
+[`serve-static`](https://github.com/expressjs/serve-static).

package/docs/Reference/Plugins.md

@@ -1,21 +1,18 @@
 <h1 align="center">Fastify</h1>
 
 ## Plugins
-Fastify allows the user to extend its functionalities with plugins. A plugin can
-be a set of routes, a server [decorator](./Decorators.md), or whatever. The API
-that you will need to use one or more plugins, is `register`.
-
-By default, `register` creates a *new scope*, this means that if you make some
-changes to the Fastify instance (via `decorate`), this change will not be
-reflected by the current context ancestors, but only by its descendants. This
-feature allows us to achieve plugin *encapsulation* and *inheritance*, in this
-way we create a *directed acyclic graph* (DAG) and we will not have issues
-caused by cross dependencies.
-
-You may have already seen in the [Getting
-Started](../Guides/Getting-Started.md#your-first-plugin) guide how easy it is
-to use this API:
-```
+Fastify can be extended with plugins, which can be a set of routes, a server
+[decorator](./Decorators.md), or other functionality. Use the `register` API to
+add one or more plugins.
+
+By default, `register` creates a *new scope*, meaning changes to the Fastify
+instance (via `decorate`) will not affect the current context ancestors, only
+its descendants. This feature enables plugin *encapsulation* and *inheritance*,
+creating a *directed acyclic graph* (DAG) and avoiding cross-dependency issues.
+
+The [Getting Started](../Guides/Getting-Started.md#your-first-plugin) guide
+includes an example of using this API:
+```js
 fastify.register(plugin, [options])
 ```
 
@@ -33,10 +30,9 @@ Fastify specific options is:
 + [`logSerializers`](./Routes.md#custom-log-serializer)
 + [`prefix`](#route-prefixing-option)
 
-**Note: Those options will be ignored when used with fastify-plugin**
+These options will be ignored when used with fastify-plugin.
 
-It is possible that Fastify will directly support other options in the future.
-Thus, to avoid collisions, a plugin should consider namespacing its options. For
+To avoid collisions, a plugin should consider namespacing its options. For
 example, a plugin `foo` might be registered like so:
 
 ```js
@@ -49,8 +45,7 @@ fastify.register(require('fastify-foo'), {
 })
 ```
 
-If collisions are not a concern, the plugin may simply accept the options object
-as-is:
+If collisions are not a concern, the plugin may accept the options object as-is:
 
 ```js
 fastify.register(require('fastify-foo'), {
@@ -60,9 +55,8 @@ fastify.register(require('fastify-foo'), {
 })
 ```
 
-The `options` parameter can also be a `Function` that will be evaluated at the
-time the plugin is registered while giving access to the Fastify instance via
-the first positional argument:
+The `options` parameter can also be a `Function` evaluated at plugin registration,
+providing access to the Fastify instance via the first argument:
 
 ```js
 const fp = require('fastify-plugin')
@@ -77,40 +71,38 @@ fastify.register(fp((fastify, opts, done) => {
 fastify.register(require('fastify-foo'), parent => parent.foo_bar)
 ```
 
-The Fastify instance passed on to the function is the latest state of the
-**external Fastify instance** the plugin was declared on, allowing access to
-variables injected via [`decorate`](./Decorators.md) by preceding plugins
-according to the **order of registration**. This is useful in case a plugin
-depends on changes made to the Fastify instance by a preceding plugin i.e.
-utilizing an existing database connection to wrap around it.
+The Fastify instance passed to the function is the latest state of the **external
+Fastify instance** the plugin was declared on, allowing access to variables
+injected via [`decorate`](./Decorators.md) by preceding plugins according to the
+**order of registration**. This is useful if a plugin depends on changes made to
+the Fastify instance by a preceding plugin, such as utilizing an existing database
+connection.
 
-Keep in mind that the Fastify instance passed on to the function is the same as
-the one that will be passed into the plugin, a copy of the external Fastify
-instance rather than a reference. Any usage of the instance will behave the same
-as it would if called within the plugins function i.e. if `decorate` is called,
-the decorated variables will be available within the plugins function unless it
-was wrapped with [`fastify-plugin`](https://github.com/fastify/fastify-plugin).
+Keep in mind that the Fastify instance passed to the function is the same as the
+one passed into the plugin, a copy of the external Fastify instance rather than a
+reference. Any usage of the instance will behave the same as it would if called
+within the plugin's function. For example, if `decorate` is called, the decorated
+variables will be available within the plugin's function unless it was wrapped
+with [`fastify-plugin`](https://github.com/fastify/fastify-plugin).
 
 #### Route Prefixing option
 <a id="route-prefixing-option"></a>
 
-If you pass an option with the key `prefix` with a `string` value, Fastify will
-use it to prefix all the routes inside the register, for more info check
+If an option with the key `prefix` and a `string` value is passed, Fastify will
+use it to prefix all the routes inside the register. For more info, check
 [here](./Routes.md#route-prefixing).
 
-Be aware that if you wrap your routes with
+Be aware that if routes are wrapped with
 [`fastify-plugin`](https://github.com/fastify/fastify-plugin), this option will
-not work (there is a [workaround](./Routes.md#fastify-plugin) available).
+not work (see the [workaround](./Routes.md#fastify-plugin)).
 
 #### Error handling
 <a id="error-handling"></a>
 
-The error handling is done by
-[avvio](https://github.com/mcollina/avvio#error-handling).
+Error handling is done by [avvio](https://github.com/mcollina/avvio#error-handling).
 
-As a general rule, it is highly recommended that you handle your errors in the
-next `after` or `ready` block, otherwise you will get them inside the `listen`
-callback.
+As a general rule, handle errors in the next `after` or `ready` block, otherwise
+they will be caught inside the `listen` callback.
 
 ```js
 fastify.register(require('my-plugin'))
@@ -145,16 +137,15 @@ await fastify.ready()
 
 await fastify.listen({ port: 3000 })
 ```
-*Note: Using `await` when registering a plugin loads the plugin
-and the underlying dependency tree, "finalizing" the encapsulation process.
-Any mutations to the plugin after it and its dependencies have been
-loaded will not be reflected in the parent instance.*
+Using `await` when registering a plugin loads the plugin and its dependencies,
+"finalizing" the encapsulation process. Any mutations to the plugin after it and
+its dependencies have been loaded will not be reflected in the parent instance.
 
 #### ESM support
 <a id="esm-support"></a>
 
-ESM is supported as well from [Node.js
-`v13.3.0`](https://nodejs.org/api/esm.html) and above!
+ESM is supported from [Node.js `v13.3.0`](https://nodejs.org/api/esm.html)
+and above.
 
 ```js
 // main.mjs
@@ -179,9 +170,8 @@ export default plugin
 ### Create a plugin
 <a id="create-plugin"></a>
 
-Creating a plugin is very easy, you just need to create a function that takes
-three parameters, the `fastify` instance, an `options` object, and the `done`
-callback.
+Creating a plugin is easy. Create a function that takes three parameters: the
+`fastify` instance, an `options` object, and the `done` callback.
 
 Example:
 ```js
@@ -193,7 +183,7 @@ module.exports = function (fastify, opts, done) {
   done()
 }
 ```
-You can also use `register` inside another `register`:
+`register` can also be used inside another `register`:
 ```js
 module.exports = function (fastify, opts, done) {
   fastify.decorate('utility', function () {})
@@ -205,28 +195,23 @@ module.exports = function (fastify, opts, done) {
   done()
 }
 ```
-Sometimes, you will need to know when the server is about to close, for example,
-because you must close a connection to a database. To know when this is going to
-happen, you can use the [`'onClose'`](./Hooks.md#on-close) hook.
 
-Do not forget that `register` will always create a new Fastify scope, if you do
-not need that, read the following section.
+Remember, `register` always creates a new Fastify scope. If this is not needed,
+read the following section.
 
 ### Handle the scope
 <a id="handle-scope"></a>
 
-If you are using `register` only for extending the functionality of the server
-with  [`decorate`](./Decorators.md), it is your responsibility to tell Fastify
-not to create a new scope. Otherwise, your changes will not be accessible by the
-user in the upper scope.
+If `register` is used only to extend server functionality with
+[`decorate`](./Decorators.md), tell Fastify not to create a new scope. Otherwise,
+changes will not be accessible in the upper scope.
 
-You have two ways to tell Fastify to avoid the creation of a new context:
+There are two ways to avoid creating a new context:
 - Use the [`fastify-plugin`](https://github.com/fastify/fastify-plugin) module
 - Use the `'skip-override'` hidden property
 
-We recommend using the `fastify-plugin` module, because it solves this problem
-for you, and you can pass a version range of Fastify as a parameter that your
-plugin will support.
+Using the `fastify-plugin` module is recommended, as it solves this problem and
+allows passing a version range of Fastify that the plugin will support:
 ```js
 const fp = require('fastify-plugin')
 
@@ -238,10 +223,9 @@ module.exports = fp(function (fastify, opts, done) {
 Check the [`fastify-plugin`](https://github.com/fastify/fastify-plugin)
 documentation to learn more about how to use this module.
 
-If you do not use the `fastify-plugin` module, you can use the `'skip-override'`
-hidden property, but we do not recommend it. If in the future the Fastify API
-changes it will be your responsibility to update the module, while if you use
-`fastify-plugin`, you can be sure about backward compatibility.
+If not using `fastify-plugin`, the `'skip-override'` hidden property can be used,
+but it is not recommended. Future Fastify API changes will be your responsibility
+to update, whilst `fastify-plugin` ensures backward compatibility.
 ```js
 function yourPlugin (fastify, opts, done) {
   fastify.decorate('utility', function () {})

package/docs/Reference/Principles.md

@@ -16,48 +16,41 @@ the following technical principles:
 
 ## "Zero" Overhead in Production
 
-Fastify aims to implement its features by adding as minimal overhead to your
-application as possible.
-This is usually delivered by implementing fast algorithms and data structures,
-as well as JavaScript-specific features.
+Fastify aims to implement features with minimal overhead. This is achieved by
+using fast algorithms, data structures, and JavaScript-specific features.
 
-Given that JavaScript does not offer zero-overhead data structures, this principle
-is at odds with providing a great developer experience and providing more features,
-as usually those cost some overhead.
+Since JavaScript does not offer zero-overhead data structures, this principle
+can conflict with providing a great developer experience and additional features,
+as these usually incur some overhead.
 
 ## "Good" Developer Experience
 
-Fastify aims to provide the best developer experience at the performance point
-it is operating.
-It provides a great out-of-the-box experience that is flexible enough to be
-adapted to a variety of situations.
+Fastify aims to provide the best developer experience at its performance point.
+It offers a great out-of-the-box experience that is flexible enough to adapt to
+various situations.
 
-As an example, this means that binary addons are forbidden because most JavaScript
-developers would not
-have access to a compiler.
+For example, binary addons are forbidden because most JavaScript developers do
+not have access to a compiler.
 
 ## Works great for small and big projects alike
 
-We recognize that most applications start small and become more complex over time.
-Fastify aims to grow with
-the complexity of your application, providing advanced features to structure
-your codebase.
+Most applications start small and become more complex over time. Fastify aims to
+grow with this complexity, providing advanced features to structure codebases.
 
 ## Easy to migrate to microservices (or even serverless) and back
 
-How you deploy your routes should not matter. The framework should "just work".
+Route deployment should not matter. The framework should "just work".
 
 ## Security and Data Validation
 
-Your web framework is the first point of contact with untrusted data, and it
-needs to act as the first line of defense for your system.
+A web framework is the first point of contact with untrusted data and must act
+as the first line of defense for the system.
 
 ## If something could be a plugin, it likely should
 
-We recognize that there are an infinite amount of use cases for an HTTP framework
-for Node.js. Catering to them in a single module would make the codebase unmaintainable.
-Therefore we provide hooks and options to allow you to customize the framework
-as you please.
+Recognizing the infinite use cases for an HTTP framework, catering to all in a
+single module would make the codebase unmaintainable. Therefore, hooks and
+options are provided to customize the framework as needed.
 
 ## Easily testable
 
@@ -65,14 +58,16 @@ Testing Fastify applications should be a first-class concern.
 
 ## Do not monkeypatch core
 
-Monkeypatch Node.js APIs or installing globals that alter the behavior of the
-runtime makes building modular applications harder, and limit the use cases of Fastify.
-Other frameworks do this and we do not.
+Monkeypatching Node.js APIs or installing globals that alter the runtime makes
+building modular applications harder and limits Fastify's use cases. Other
+frameworks do this; Fastify does not.
 
 ## Semantic Versioning and Long Term Support
 
-We provide a clear Long Term Support strategy so developers can know when to upgrade.
+A clear [Long Term Support strategy is provided](./LTS.md) to inform developers when
+to upgrade.
 
 ## Specification adherence
 
-In doubt, we chose the strict behavior as defined by the relevant Specifications.
+In doubt, we chose the strict behavior as defined by the relevant
+Specifications.