fastify 5.2.0 → 5.2.2

package/docs/Reference/Reply.md

@@ -151,7 +151,7 @@ fastify.get('/', async function (req, rep) {
 Sets a response header. If the value is omitted or undefined, it is coerced to
 `''`.
 
-> Note: the header's value must be properly encoded using
+> 🛈 Note: The header's value must be properly encoded using
 > [`encodeURI`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURI)
 > or similar modules such as
 > [`encodeurl`](https://www.npmjs.com/package/encodeurl). Invalid characters
@@ -260,11 +260,11 @@ requires heavy resources to be sent after the `data`, for example,
 `Server-Timing` and `Etag`. It can ensure the client receives the response data
 as soon as possible.
 
-*Note: The header `Transfer-Encoding: chunked` will be added once you use the
-trailer. It is a hard requirement for using trailer in Node.js.*
+> 🛈 Note: The header `Transfer-Encoding: chunked` will be added once you use
+> the trailer. It is a hard requirement for using trailer in Node.js.
 
-*Note: Any error passed to `done` callback will be ignored. If you interested
-in the error, you can turn on `debug` level logging.*
+> 🛈 Note: Any error passed to `done` callback will be ignored. If you interested
+> in the error, you can turn on `debug` level logging.*
 
 ```js
 reply.trailer('server-timing', function() {
@@ -314,7 +314,7 @@ reply.getTrailer('server-timing') // undefined
 Redirects a request to the specified URL, the status code is optional, default
 to `302` (if status code is not already set by calling `code`).
 
-> Note: the input URL must be properly encoded using
+> 🛈 Note: The input URL must be properly encoded using
 > [`encodeURI`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURI)
 > or similar modules such as
 > [`encodeurl`](https://www.npmjs.com/package/encodeurl). Invalid URLs will
@@ -362,7 +362,8 @@ Sets the content type for the response. This is a shortcut for
 reply.type('text/html')
 ```
 If the `Content-Type` has a JSON subtype, and the charset parameter is not set,
-`utf-8` will be used as the charset by default.
+`utf-8` will be used as the charset by default. For other content types, the
+charset must be set explicitly.
 
 ### .getSerializationFunction(schema | httpStatus, [contentType])
 <a id="getserializationfunction"></a>
@@ -822,8 +823,8 @@ automatically create an error structured as the following:
 You can add custom properties to the Error object, such as `headers`, that will
 be used to enhance the HTTP response.
 
-*Note: If you are passing an error to `send` and the statusCode is less than
-400, Fastify will automatically set it at 500.*
+> 🛈 Note: If you are passing an error to `send` and the statusCode is less than
+> 400, Fastify will automatically set it at 500.
 
 Tip: you can simplify errors by using the
 [`http-errors`](https://npm.im/http-errors) module or
@@ -870,7 +871,7 @@ fastify.get('/', {
 If you want to customize error handling, check out
 [`setErrorHandler`](./Server.md#seterrorhandler) API.
 
-*Note: you are responsible for logging when customizing the error handler*
+> 🛈 Note: you are responsible for logging when customizing the error handler.
 
 API:
 

package/docs/Reference/Request.md

@@ -4,75 +4,71 @@
 The first parameter of the handler function is `Request`.
 
 Request is a core Fastify object containing the following fields:
-- `query` - the parsed querystring, its format is specified by
-  [`querystringParser`](./Server.md#querystringparser)
-- `body` - the request payload, see [Content-Type
-  Parser](./ContentTypeParser.md) for details on what request payloads Fastify
-  natively parses and how to support other content types
-- `params` - the params matching the URL
-- [`headers`](#headers) - the headers getter and setter
-- `raw` - the incoming HTTP request from Node core
-- `server` - The Fastify server instance, scoped to the current [encapsulation
-  context](./Encapsulation.md)
-- `id` - the request ID
-- `log` - the logger instance of the incoming request
-- `ip` - the IP address of the incoming request
-- `ips` - an array of the IP addresses, ordered from closest to furthest, in the
+- `query` - The parsed querystring, its format is specified by
+  [`querystringParser`](./Server.md#querystringparser).
+- `body` - The request payload, see [Content-Type Parser](./ContentTypeParser.md)
+  for details on what request payloads Fastify natively parses and how to support
+  other content types.
+- `params` - The params matching the URL.
+- [`headers`](#headers) - The headers getter and setter.
+- `raw` - The incoming HTTP request from Node core.
+- `server` - The Fastify server instance, scoped to the current
+  [encapsulation context](./Encapsulation.md).
+- `id` - The request ID.
+- `log` - The logger instance of the incoming request.
+- `ip` - The IP address of the incoming request.
+- `ips` - An array of the IP addresses, ordered from closest to furthest, in the
   `X-Forwarded-For` header of the incoming request (only when the
-  [`trustProxy`](./Server.md#factory-trust-proxy) option is enabled)
-- `host` - the host of the incoming request (derived from `X-Forwarded-Host`
+  [`trustProxy`](./Server.md#factory-trust-proxy) option is enabled).
+- `host` - The host of the incoming request (derived from `X-Forwarded-Host`
   header when the [`trustProxy`](./Server.md#factory-trust-proxy) option is
-  enabled). For HTTP/2 compatibility it returns `:authority` if no host header
-  exists. The host header may return empty string when using
-  `requireHostHeader = false`, not suppied when connected with `HTTP/1.0` or
-  using schema validation that remove the extra headers.
-- `hostname` - the host of the `host` property, it may refers the incoming
-  request hostname
-- `port` - the port of the `host` property, it may refers the port thats
-  the server is listening on
-- `protocol` - the protocol of the incoming request (`https` or `http`)
-- `method` - the method of the incoming request
-- `url` - the URL of the incoming request
-- `originalUrl` - similar to `url`, this allows you to access the
-  original `url` in case of internal re-routing
-- `is404` - true if request is being handled by 404 handler, false if it is not
-- `socket` - the underlying connection of the incoming request
-- `context` - Deprecated, use `request.routeOptions.config` instead.
-A Fastify internal object. You should not use
-it directly or modify it. It is useful to access one special key:
+  enabled). For HTTP/2 compatibility, it returns `:authority` if no host header
+  exists. The host header may return an empty string if `requireHostHeader` is
+  `false`, not provided with HTTP/1.0, or removed by schema validation.
+- `hostname` - The hostname derived from the `host` property of the incoming request.
+- `port` - The port from the `host` property, which may refer to the port the
+  server is listening on.
+- `protocol` - The protocol of the incoming request (`https` or `http`).
+- `method` - The method of the incoming request.
+- `url` - The URL of the incoming request.
+- `originalUrl` - Similar to `url`, allows access to the original `url` in
+  case of internal re-routing.
+- `is404` - `true` if request is being handled by 404 handler, `false` otherwise.
+- `socket` - The underlying connection of the incoming request.
+- `context` - Deprecated, use `request.routeOptions.config` instead. A Fastify
+  internal object. Do not use or modify it directly. It is useful to access one
+  special key:
   - `context.config` - The route [`config`](./Routes.md#routes-config) object.
-- `routeOptions` - The route [`option`](./Routes.md#routes-options) object
-  - `bodyLimit` - either server limit or route limit
-  - `config` - the [`config`](./Routes.md#routes-config) object for this route
-  - `method` - the http method for the route
-  - `url` - the path of the URL to match this route
-  - `handler` - the handler for this route
-  - `attachValidation` - attach `validationError` to request
-    (if there is a schema defined)
-  - `logLevel` - log level defined for this route
-  - `schema` - the JSON schemas definition for this route
-  - `version` -  a semver compatible string that defines the version of the endpoint
-  - `exposeHeadRoute` - creates a sibling HEAD route for any GET routes
-  - `prefixTrailingSlash` - string used to determine how to handle passing /
+- `routeOptions` - The route [`option`](./Routes.md#routes-options) object.
+  - `bodyLimit` - Either server limit or route limit.
+  - `config` - The [`config`](./Routes.md#routes-config) object for this route.
+  - `method` - The HTTP method for the route.
+  - `url` - The path of the URL to match this route.
+  - `handler` - The handler for this route.
+  - `attachValidation` - Attach `validationError` to request (if there is
+    a schema defined).
+  - `logLevel` - Log level defined for this route.
+  - `schema` - The JSON schemas definition for this route.
+  - `version` - A semver compatible string that defines the version of the endpoint.
+  - `exposeHeadRoute` - Creates a sibling HEAD route for any GET routes.
+  - `prefixTrailingSlash` - String used to determine how to handle passing `/`
     as a route with a prefix.
 - [.getValidationFunction(schema | httpPart)](#getvalidationfunction) -
-  Returns a validation function for the specified schema or http part,
-  if any of either are set or cached.
+  Returns a validation function for the specified schema or HTTP part, if
+  set or cached.
 - [.compileValidationSchema(schema, [httpPart])](#compilevalidationschema) -
-  Compiles the specified schema and returns a validation function
-  using the default (or customized) `ValidationCompiler`.
-  The optional `httpPart` is forwarded to the `ValidationCompiler`
-  if provided, defaults to `null`.
+  Compiles the specified schema and returns a validation function using the
+  default (or customized) `ValidationCompiler`. The optional `httpPart` is
+  forwarded to the `ValidationCompiler` if provided, defaults to `null`.
 - [.validateInput(data, schema | httpPart, [httpPart])](#validate) -
-  Validates the specified input by using the specified
-  schema and returns the serialized payload. If the optional
-  `httpPart` is provided, the function will use the serializer
-  function given for that HTTP Status Code. Defaults to `null`.
+  Validates the input using the specified schema and returns the serialized
+  payload. If `httpPart` is provided, the function uses the serializer for
+  that HTTP Status Code. Defaults to `null`.
 
 ### Headers
 
-The `request.headers` is a getter that returns an Object with the headers of the
-incoming request. You can set custom headers like this:
+The `request.headers` is a getter that returns an object with the headers of the
+incoming request. Set custom headers as follows:
 
 ```js
 request.headers = {
@@ -81,15 +77,15 @@ request.headers = {
 }
 ```
 
-This operation will add to the request headers the new values that can be read
-calling `request.headers.bar`. Moreover, you can still access the standard
-request's headers with the `request.raw.headers` property.
+This operation adds new values to the request headers, accessible via
+`request.headers.bar`. Standard request headers remain accessible via
+`request.raw.headers`.
 
-> Note: For performance reason on `not found` route, you may see that we will
-add an extra property `Symbol('fastify.RequestAcceptVersion')` on the headers.
+For performance reasons, `Symbol('fastify.RequestAcceptVersion')` may be added
+to headers on `not found` routes.
 
-> Note: When using schema, it may mutate the `request.headers` and
-`request.raw.headers` object. So, you may found the headers becomes empty.
+> 🛈 Note: Schema validation may mutate the `request.headers` and
+> `request.raw.headers` objects, causing the headers to become empty.
 
 ```js
 fastify.post('/:params', options, function (request, reply) {
@@ -123,13 +119,12 @@ fastify.post('/:params', options, function (request, reply) {
 ### .getValidationFunction(schema | httpPart)
 <a id="getvalidationfunction"></a>
 
-By calling this function using a provided `schema` or `httpPart`,
-it will return a `validation` function that can be used to
-validate diverse inputs. It returns `undefined` if no
-serialization function was found using either of the provided inputs.
+By calling this function with a provided `schema` or `httpPart`, it returns a
+`validation` function to validate diverse inputs. It returns `undefined` if no
+serialization function is found using the provided inputs.
 
-This function has property errors. Errors encountered during the last validation
-are assigned to errors
+This function has an `errors` property. Errors encountered during the last
+validation are assigned to `errors`.
 
 ```js
 const validate = request
@@ -152,24 +147,23 @@ console.log(validate({ foo: 0.5 })) // false
 console.log(validate.errors) // validation errors
 ```
 
-See [.compileValidationSchema(schema, [httpStatus])](#compilevalidationschema)
-for more information on how to compile validation function.
+See [.compileValidationSchema(schema, [httpStatus])](#compileValidationSchema)
+for more information on compiling validation schemas.
 
 ### .compileValidationSchema(schema, [httpPart])
 <a id="compilevalidationschema"></a>
 
-This function will compile a validation schema and
-return a function that can be used to validate data.
-The function returned (a.k.a. _validation function_) is compiled
-by using the provided [`SchemaController#ValidationCompiler`](./Server.md#schema-controller).
-A `WeakMap` is used to cached this, reducing compilation calls.
+This function compiles a validation schema and returns a function to validate data.
+The returned function (a.k.a. _validation function_) is compiled using the provided
+[`SchemaController#ValidationCompiler`](./Server.md#schema-controller). A `WeakMap`
+is used to cache this, reducing compilation calls.
 
-The optional parameter `httpPart`, if provided, is forwarded directly
-the `ValidationCompiler`, so it can be used to compile the validation
-function if a custom `ValidationCompiler` is provided for the route.
+The optional parameter `httpPart`, if provided, is forwarded to the
+`ValidationCompiler`, allowing it to compile the validation function if a custom
+`ValidationCompiler` is provided for the route.
 
-This function has property errors. Errors encountered during the last validation
-are assigned to errors
+This function has an `errors` property. Errors encountered during the last
+validation are assigned to `errors`.
 
 ```js
 const validate = request
@@ -199,16 +193,13 @@ console.log(validate({ hello: 'world' })) // false
 console.log(validate.errors) // validation errors
 ```
 
-Note that you should be careful when using this function, as it will cache
-the compiled validation functions based on the schema provided. If the
-schemas provided are mutated or changed, the validation functions will not
-detect that the schema has been altered and for instance it will reuse the
-previously compiled validation function, as the cache is based on
-the reference of the schema (Object) previously provided.
+Be careful when using this function, as it caches compiled validation functions
+based on the provided schema. If schemas are mutated or changed, the validation
+functions will not detect the alterations and will reuse the previously compiled
+validation function, as the cache is based on the schema's reference.
 
-If there is a need to change the properties of a schema, always opt to create
-a totally new schema (object), otherwise the implementation will not benefit from
-the cache mechanism.
+If schema properties need to be changed, create a new schema object to benefit
+from the cache mechanism.
 
 Using the following schema as an example:
 ```js
@@ -249,12 +240,11 @@ console.log(newValidate === validate) // false
 ### .validateInput(data, [schema | httpStatus], [httpStatus])
 <a id="validate"></a>
 
-This function will validate the input based on the provided schema,
-or HTTP part passed. If both are provided, the `httpPart` parameter
-will take precedence.
+This function validates the input based on the provided schema or HTTP part. If
+both are provided, the `httpPart` parameter takes precedence.
 
-If there is not a validation function for a given `schema`, a new validation
-function will be compiled, forwarding the `httpPart` if provided.
+If no validation function exists for a given `schema`, a new validation function
+will be compiled, forwarding the `httpPart` if provided.
 
 ```js
 request
@@ -286,4 +276,4 @@ request
 ```
 
 See [.compileValidationSchema(schema, [httpStatus])](#compileValidationSchema)
-for more information on how to compile validation schemas.
+for more information on compiling validation schemas.