fastify 6.0.0-alpha.4 → 6.0.0-alpha.6

package/docs/Reference/Reply.md

@@ -1,45 +1,52 @@
 <h1 align="center">Fastify</h1>
 
 ## Reply
-- [Reply](#reply)
-  - [Introduction](#introduction)
-  - [.code(statusCode)](#codestatuscode)
-  - [.elapsedTime](#elapsedtime)
-  - [.statusCode](#statuscode)
-  - [.mediaType](#mediatype)
-  - [.server](#server)
-  - [.header(key, value)](#headerkey-value)
-  - [.headers(object)](#headersobject)
-  - [.getHeader(key)](#getheaderkey)
-  - [.getHeaders()](#getheaders)
-  - [.removeHeader(key)](#removeheaderkey)
-  - [.hasHeader(key)](#hasheaderkey)
-  - [.writeEarlyHints(hints, callback)](#writeearlyhintshints-callback)
-  - [.trailer(key, function)](#trailerkey-function)
-  - [.hasTrailer(key)](#hastrailerkey)
-  - [.removeTrailer(key)](#removetrailerkey)
-  - [.redirect(dest, [code ,])](#redirectdest--code)
-  - [.callNotFound()](#callnotfound)
-  - [.type(contentType)](#typecontenttype)
-  - [.getSerializationFunction(schema | httpStatus, [contentType])](#getserializationfunctionschema--httpstatus)
-  - [.compileSerializationSchema(schema, [httpStatus], [contentType])](#compileserializationschemaschema-httpstatus)
-  - [.serializeInput(data, [schema | httpStatus], [httpStatus], [contentType])](#serializeinputdata-schema--httpstatus-httpstatus)
-  - [.serializer(func)](#serializerfunc)
-  - [.raw](#raw)
-  - [.sent](#sent)
-  - [.hijack()](#hijack)
-  - [.send(data)](#senddata)
-    - [Objects](#objects)
-    - [Strings](#strings)
-    - [Streams](#streams)
-    - [Buffers](#buffers)
-    - [TypedArrays](#typedarrays)
-    - [ReadableStream](#readablestream)
-    - [Response](#response)
-    - [Errors](#errors)
-    - [Type of the final payload](#type-of-the-final-payload)
-    - [Async-Await and Promises](#async-await-and-promises)
-  - [.then(fulfilled, rejected)](#thenfulfilled-rejected)
+- [Introduction](#introduction)
+- [Reply](#reply-object)
+  - [Properties](#properties)
+    - [.statusCode](#statuscode)
+    - [.sent](#sent)
+    - [.request](#request)
+    - [.log](#log)
+    - [.raw](#raw)
+    - [.server](#server)
+    - [.routeOptions](#routeoptions)
+    - [.mediaType](#mediatype)
+    - [.elapsedTime](#elapsedtime)
+  - [Methods](#methods)
+    - [.send(data)](#senddata)
+      - [Objects](#objects)
+      - [Strings](#strings)
+      - [Buffers](#buffers)
+      - [TypedArrays](#typedarrays)
+      - [Streams](#streams)
+      - [ReadableStream](#readablestream)
+      - [Response](#response)
+      - [Errors](#errors)
+      - [Async-Await and Promises](#async-await-and-promises)
+      - [Type of the final payload](#type-of-the-final-payload)
+    - [.code(statusCode)](#codestatuscode)
+    - [.header(key, value)](#headerkey-value)
+    - [.headers(object)](#headersobject)
+    - [.type(contentType)](#typecontenttype)
+    - [.redirect(dest, [code])](#redirectdest-code)
+    - [.getHeader(key)](#getheaderkey)
+    - [.getHeaders()](#getheaders)
+    - [.hasHeader(key)](#hasheaderkey)
+    - [.removeHeader(key)](#removeheaderkey)
+    - [.callNotFound()](#callnotfound)
+    - [.hijack()](#hijack)
+    - [.serializer(func)](#serializerfunc)
+    - [.serialize(payload)](#serializepayload)
+    - [.trailer(key, function)](#trailerkey-function)
+    - [.hasTrailer(key)](#hastrailerkey)
+    - [.removeTrailer(key)](#removetrailerkey)
+    - [.writeEarlyHints(hints, callback)](#writeearlyhintshints-callback)
+    - [.then(fulfilled, rejected)](#thenfulfilled-rejected)
+    - [.getDecorator(name)](#getdecoratorname)
+    - [.getSerializationFunction(schema | httpStatus, [contentType])](#getserializationfunctionschema--httpstatus-contenttype)
+    - [.compileSerializationSchema(schema, [httpStatus], [contentType])](#compileserializationschemaschema-httpstatus-contenttype)
+    - [.serializeInput(data, [schema | httpStatus], [httpStatus], [contentType])](#serializeinputdata-schema--httpstatus-httpstatus-contenttype)
 
 ### Introduction
 <a id="introduction"></a>
@@ -66,7 +73,7 @@ since the request was received by Fastify.
 - `.hasTrailer(key)` - Determine if a trailer has been set.
 - `.removeTrailer(key)` - Remove the value of a previously set trailer.
 - `.type(value)` - Sets the header `Content-Type`.
-- `.redirect(dest, [code,])` - Redirect to the specified URL, the status code is
+- `.redirect(dest, [code])` - Redirect to the specified URL, the status code is
   optional (defaults to `302`).
 - `.callNotFound()` - Invokes the custom not found handler.
 - `.serialize(payload)` - Serializes the specified payload using the default
@@ -95,6 +102,7 @@ since the request was received by Fastify.
   from Node core.
 - `.log` - The logger instance of the incoming request.
 - `.request` - The incoming request.
+- `.getDecorator(name)` - Returns the value of a reply decorator.
 
 ```js
 fastify.get('/', options, function (request, reply) {
@@ -106,22 +114,13 @@ fastify.get('/', options, function (request, reply) {
 })
 ```
 
-### .code(statusCode)
-<a id="code"></a>
-
-If not set via `reply.code`, the resulting `statusCode` will be `200`.
-
-### .elapsedTime
-<a id="elapsedTime"></a>
-
-Invokes the custom response time getter to calculate the amount of time passed
-since the request was received by Fastify.
+### Reply
+<a id="reply-object"></a>
 
-```js
-const milliseconds = reply.elapsedTime
-```
+#### Properties
+<a id="properties"></a>
 
-### .statusCode
+##### .statusCode
 <a id="statusCode"></a>
 
 This property reads and sets the HTTP status code. It is an alias for
@@ -131,20 +130,69 @@ if (reply.statusCode >= 299) {
   reply.statusCode = 500
 }
 ```
-### .mediaType
-<a id="mediatype"></a>
 
-Returns the media type extracted from `Content-Type` header. When `Content-Type`
-header is missing, it will return `undefined`.
+##### .sent
+<a id="sent"></a>
+
+As the name suggests, `.sent` is a property to indicate if a response has been
+sent via `reply.send()`. It will also be `true` in case `reply.hijack()` was
+used.
+
+In case a route handler is defined as an async function or it returns a promise,
+it is possible to call `reply.hijack()` to indicate that the automatic
+invocation of `reply.send()` once the handler promise resolve should be skipped.
+By calling `reply.hijack()`, an application claims full responsibility for the
+low-level request and response. Moreover, hooks will not be invoked.
+
+##### .request
+<a id="request"></a>
+
+The [`Request`](./Request.md) object of the incoming request this reply belongs
+to.
 
 ```js
-if (reply.mediaType === 'image/gif') {
-  const versionBuffer = new Uint8Array(reply.payload, 3, 3)
-  reply.header('x-gif-version', new TextDecoder().decode(versionBuffer))
-}
+fastify.addHook('onSend', async function (request, reply, payload) {
+  reply.header('x-request-url', reply.request.url)
+})
 ```
 
-### .server
+##### .log
+<a id="log"></a>
+
+The logger instance of the incoming request. It is the same instance as
+`request.log`, so every log line includes the request id. See
+[Logging](./Logging.md) for more information.
+
+```js
+fastify.get('/', function (request, reply) {
+  reply.log.info('sending the response')
+  reply.send({ hello: 'world' })
+})
+```
+
+##### .raw
+<a id="raw"></a>
+
+This is the
+[`http.ServerResponse`](https://nodejs.org/dist/latest-v20.x/docs/api/http.html#http_class_http_serverresponse)
+from Node core. Whilst you are using the Fastify `Reply` object, the use of
+`Reply.raw` functions is at your own risk as you are skipping all the Fastify
+logic of handling the HTTP response. e.g.:
+
+```js
+app.get('/cookie-2', (req, reply) => {
+  reply.setCookie('session', 'value', { secure: false }) // this will not be used
+
+  // in this case we are using only the nodejs http server response object
+  reply.raw.writeHead(200, { 'Content-Type': 'text/plain' })
+  reply.raw.write('ok')
+  reply.raw.end()
+})
+```
+Another example of the misuse of `Reply.raw` is explained in
+[Reply](#getheaders).
+
+##### .server
 <a id="server"></a>
 
 The Fastify server instance, scoped to the current [encapsulation
@@ -160,486 +208,548 @@ fastify.get('/', async function (req, rep) {
 })
 ```
 
-### .header(key, value)
-<a id="header"></a>
-
-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
-> [`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
-> will result in a 500 `TypeError` response.
-
-For more information, see
-[`http.ServerResponse#setHeader`](https://nodejs.org/dist/latest-v20.x/docs/api/http.html#http_response_setheader_name_value).
-
-- ### set-cookie
-  <a id="set-cookie"></a>
-
-    - When sending different values as a cookie with `set-cookie` as the key,
-      every value will be sent as a cookie instead of replacing the previous
-      value.
-
-    ```js
-    reply.header('set-cookie', 'foo');
-    reply.header('set-cookie', 'bar');
-    ```
-  - The browser will only consider the latest reference of a key for the
-    `set-cookie` header. This is done to avoid parsing the `set-cookie` header
-    when added to a reply and speeds up the serialization of the reply.
-
-  - To reset the `set-cookie` header, you need to make an explicit call to
-    `reply.removeHeader('set-cookie')`, read more about `.removeHeader(key)`
-    [here](#removeheaderkey).
-
+##### .routeOptions
+<a id="routeoptions"></a>
 
+A read-only reference to the route options of the incoming request. It is the
+same object as [`request.routeOptions`](./Request.md).
 
-### .headers(object)
-<a id="headers"></a>
-
-Sets all the keys of the object as response headers.
-[`.header`](#headerkey-value) will be called under the hood.
 ```js
-reply.headers({
-  'x-foo': 'foo',
-  'x-bar': 'bar'
+fastify.get('/', { config: { foo: 'bar' } }, function (request, reply) {
+  reply.send(reply.routeOptions.config.foo) // bar
 })
 ```
 
-### .getHeader(key)
-<a id="getHeader"></a>
+##### .mediaType
+<a id="mediatype"></a>
+
+Returns the media type extracted from `Content-Type` header. When `Content-Type`
+header is missing, it will return `undefined`.
 
-Retrieves the value of a previously set header.
 ```js
-reply.header('x-foo', 'foo') // setHeader: key, value
-reply.getHeader('x-foo') // 'foo'
+if (reply.mediaType === 'image/gif') {
+  const versionBuffer = new Uint8Array(reply.payload, 3, 3)
+  reply.header('x-gif-version', new TextDecoder().decode(versionBuffer))
+}
 ```
 
-### .getHeaders()
-<a id="getHeaders"></a>
+##### .elapsedTime
+<a id="elapsedTime"></a>
 
-Gets a shallow copy of all current response headers, including those set via the
-raw `http.ServerResponse`. Note that headers set via Fastify take precedence
-over those set via `http.ServerResponse`.
+Invokes the custom response time getter to calculate the amount of time passed
+since the request was received by Fastify.
 
 ```js
-reply.header('x-foo', 'foo')
-reply.header('x-bar', 'bar')
-reply.raw.setHeader('x-foo', 'foo2')
-reply.getHeaders() // { 'x-foo': 'foo', 'x-bar': 'bar' }
+const milliseconds = reply.elapsedTime
 ```
 
-### .removeHeader(key)
-<a id="removeHeader"></a>
+#### Methods
+<a id="methods"></a>
 
-Remove the value of a previously set header.
-```js
-reply.header('x-foo', 'foo')
-reply.removeHeader('x-foo')
-reply.getHeader('x-foo') // undefined
-```
+##### .send(data)
+<a id="send"></a>
 
-### .hasHeader(key)
-<a id="hasHeader"></a>
+As the name suggests, `.send()` is the function that sends the payload to the
+end user.
 
-Returns a boolean indicating if the specified header has been set.
+###### Objects
+<a id="send-object"></a>
 
-### .writeEarlyHints(hints, callback)
-<a id="writeEarlyHints"></a>
+As noted above, if you are sending JSON objects, `send` will serialize the
+object with
+[fast-json-stringify](https://www.npmjs.com/package/fast-json-stringify) if you
+set an output schema, otherwise, `JSON.stringify()` will be used.
+```js
+fastify.get('/json', options, function (request, reply) {
+  reply.send({ hello: 'world' })
+})
+```
 
-Sends early hints to the client. Early hints allow the client to
-start processing resources before the final response is sent.
-This can improve performance by allowing the client to preload
-or preconnect to resources while the server is still generating the response.
+###### Strings
+<a id="send-string"></a>
 
-The hints parameter is an object containing the early hint key-value pairs.
+If you pass a string to `send` without a `Content-Type`, it will be sent as
+`text/plain; charset=utf-8`. If you set the `Content-Type` header and pass a
+string to `send`, it will be serialized with the custom serializer if one is
+set, otherwise, it will be sent unmodified.
 
-Example:
+> ℹ️ Note:
+> Even when the `Content-Type` header is set to `application/json`,
+> strings are sent unmodified by default. To serialize a string as JSON, you
+> must set a custom serializer:
 
 ```js
-reply.writeEarlyHints({
-  Link: '</styles.css>; rel=preload; as=style'
-});
+fastify.get('/json-string', async function (request, reply) {
+  reply
+    .type('application/json; charset=utf-8')
+    .serializer(JSON.stringify)
+    .send('Hello') // Returns "Hello" (JSON-encoded string)
+})
+```
+```js
+fastify.get('/json', options, function (request, reply) {
+  reply.send('plain string')
+})
 ```
 
-The optional callback parameter is a function that will be called
-once the hint is sent or if an error occurs.
-
-### .trailer(key, function)
-<a id="trailer"></a>
-
-Sets a response trailer. Trailer is usually used when you need a header that
-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.
+###### Buffers
+<a id="send-buffers"></a>
 
-> ℹ️ Note:
-> For HTTP/1 responses, the header `Transfer-Encoding: chunked` will be added
-> once you use a trailer. HTTP/2 does not use chunked transfer encoding and
-> sends trailers using its native trailing headers support.
+If you are sending a buffer and you have not set a `'Content-Type'` header,
+*send* will set it to `'application/octet-stream'`.
 
-> ℹ️ Note:
-> Any error passed to `done` callback will be ignored. If you are interested
-> in the error, you can turn on `debug` level logging.
+As noted above, Buffers are considered to be pre-serialized, so they will be
+sent unmodified without response validation.
 
 ```js
-reply.trailer('server-timing', async function () {
-  return 'db;dur=53, app;dur=47.2'
-})
+const fs = require('node:fs')
 
-const { createHash } = require('node:crypto')
-// trailer function also receive two argument
-// @param {object} reply fastify reply
-// @param {string|Buffer|null} payload payload that already sent, note that it will be null when stream is sent
-// @param {function} done callback to set trailer value
-reply.trailer('content-md5', function(reply, payload, done) {
-  const hash = createHash('md5')
-  hash.update(payload)
-  done(null, hash.digest('hex'))
+fastify.get('/streams', function (request, reply) {
+  fs.readFile('some-file', (err, fileBuffer) => {
+    reply.send(err || fileBuffer)
+  })
 })
+```
 
-// when you prefer async-await
-reply.trailer('content-md5', async function(reply, payload) {
-  const hash = createHash('md5')
-  hash.update(payload)
-  return hash.digest('hex')
+When using async-await you will need to return or await the reply object:
+```js
+const fs = require('node:fs')
+
+fastify.get('/streams', async function (request, reply) {
+  fs.readFile('some-file', (err, fileBuffer) => {
+    reply.send(err || fileBuffer)
+  })
+  return reply
 })
 ```
 
-### .hasTrailer(key)
-<a id="hasTrailer"></a>
+###### TypedArrays
+<a id="send-typedarrays"></a>
 
-Returns a boolean indicating if the specified trailer has been set.
+`send` manages TypedArray like a Buffer, and sets the `'Content-Type'`
+header to `'application/octet-stream'` if not already set.
 
-### .removeTrailer(key)
-<a id="removeTrailer"></a>
+As noted above, TypedArray/Buffers are considered to be pre-serialized, so they
+will be sent unmodified without response validation.
 
-Remove the value of a previously set trailer.
 ```js
-reply.trailer('server-timing', async function () {
-  return 'db;dur=53, app;dur=47.2'
+const fs = require('node:fs')
+
+fastify.get('/streams', function (request, reply) {
+  const typedArray = new Uint16Array(10)
+  reply.send(typedArray)
 })
-reply.removeTrailer('server-timing')
-reply.hasTrailer('server-timing') // false
 ```
 
+###### Streams
+<a id="send-streams"></a>
 
-### .redirect(dest, [code ,])
-<a id="redirect"></a>
+If you are sending a stream and you have not set a `'Content-Type'` header,
+*send* will set it to `'application/octet-stream'`.
 
-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`).
+As noted above, streams are considered to be pre-serialized, so they will be
+sent unmodified without response validation.
 
-> ℹ️ 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
-> result in a 500 `TypeError` response.
+When sending streams over HTTP/2, Fastify does not change the chunks emitted by
+the stream. If a stream can emit very large chunks, split them in your
+application code, for example by using `fs.createReadStream()` or a transform
+stream that emits smaller chunks.
 
-Example (no `reply.code()` call) sets status code to `302` and redirects to
-`/home`
-```js
-reply.redirect('/home')
-```
+See special note about error handling for streams in
+[`setErrorHandler`](./Server.md#seterrorhandler).
 
-Example (no `reply.code()` call) sets status code to `303` and redirects to
-`/home`
 ```js
-reply.redirect('/home', 303)
-```
+const fs = require('node:fs')
 
-Example (`reply.code()` call) sets status code to `303` and redirects to `/home`
-```js
-reply.code(303).redirect('/home')
+fastify.get('/streams', function (request, reply) {
+  const stream = fs.createReadStream('some-file', 'utf8')
+  reply.header('Content-Type', 'application/octet-stream')
+  reply.send(stream)
+})
 ```
-
-Example (`reply.code()` call) sets status code to `302` and redirects to `/home`
+When using async-await you will need to return or await the reply object:
 ```js
-reply.code(303).redirect('/home', 302)
-```
-
-### .callNotFound()
-<a id="call-not-found"></a>
-
-Invokes the custom not found handler. Note that it will only call `preHandler`
-hook specified in [`setNotFoundHandler`](./Server.md#set-not-found-handler).
+const fs = require('node:fs')
 
-```js
-reply.callNotFound()
+fastify.get('/streams', async function (request, reply) {
+  const stream = fs.createReadStream('some-file', 'utf8')
+  reply.header('Content-Type', 'application/octet-stream')
+  return reply.send(stream)
+})
 ```
 
-### .type(contentType)
-<a id="type"></a>
+###### ReadableStream
+<a id="send-readablestream"></a>
 
-Sets the content type for the response. This is a shortcut for
-`reply.header('Content-Type', 'the/type')`.
+`ReadableStream` will be treated as a node stream mentioned above,
+the content is considered to be pre-serialized, so they will be
+sent unmodified without response validation.
 
 ```js
-reply.type('text/html')
+const fs = require('node:fs')
+const { ReadableStream } = require('node:stream/web')
+
+fastify.get('/streams', function (request, reply) {
+  const stream = fs.createReadStream('some-file')
+  reply.header('Content-Type', 'application/octet-stream')
+  reply.send(ReadableStream.from(stream))
+})
 ```
-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. For other content types, the
-charset must be set explicitly.
 
-### .getSerializationFunction(schema | httpStatus, [contentType])
-<a id="getserializationfunction"></a>
+###### Response
+<a id="send-response"></a>
 
-By calling this function using a provided `schema` or `httpStatus`,
-and the optional `contentType`, it will return a `serialization` function
-that can be used to serialize diverse inputs. It returns `undefined` if no
-serialization function was found using either of the provided inputs.
+`Response` allows to manage the reply payload, status code and
+headers in one place. The payload provided inside `Response` is
+considered to be pre-serialized, so they will be sent unmodified
+without response validation.
 
-This heavily depends of the `schema#responses` attached to the route, or
-the serialization functions compiled by using `compileSerializationSchema`.
+Please be aware when using `Response`, the status code and headers
+will not directly reflect to `reply.statusCode` and `reply.getHeaders()`.
+Such behavior is based on `Response` only allow `readonly` status
+code and headers. The data is not allow to be bi-direction editing,
+and may confuse when checking the `payload` in `onSend` hooks.
 
 ```js
-const serialize = reply
-                  .getSerializationFunction({
-                    type: 'object',
-                    properties: {
-                      foo: {
-                        type: 'string'
-                      }
-                    }
-                  })
-serialize({ foo: 'bar' }) // '{"foo":"bar"}'
-
-// or
-
-const serialize = reply
-                  .getSerializationFunction(200)
-serialize({ foo: 'bar' }) // '{"foo":"bar"}'
-
-// or
+const fs = require('node:fs')
+const { ReadableStream } = require('node:stream/web')
 
-const serialize = reply
-                  .getSerializationFunction(200, 'application/json')
-serialize({ foo: 'bar' }) // '{"foo":"bar"}'
+fastify.get('/streams', function (request, reply) {
+  const stream = fs.createReadStream('some-file')
+  const readableStream = ReadableStream.from(stream)
+  const response = new Response(readableStream, {
+    status: 200,
+    headers: { 'content-type': 'application/octet-stream' }
+  })
+  reply.send(response)
+})
 ```
 
-See [.compileSerializationSchema(schema, [httpStatus], [contentType])](#compileserializationschema)
-for more information on how to compile serialization schemas.
-
-### .compileSerializationSchema(schema, [httpStatus], [contentType])
-<a id="compileserializationschema"></a>
-
-This function will compile a serialization schema and
-return a function that can be used to serialize data.
-The function returned (a.k.a. _serialization function_) returned is compiled
-by using the provided `SerializerCompiler`. Also this is cached by using
-a `WeakMap` for reducing compilation calls.
 
-The optional parameters `httpStatus` and `contentType`, if provided,
-are forwarded directly to the `SerializerCompiler`, so it can be used
-to compile the serialization function if a custom `SerializerCompiler` is used.
+###### Errors
+<a id="errors"></a>
 
-This heavily depends of the `schema#responses` attached to the route, or
-the serialization functions compiled by using `compileSerializationSchema`.
+If you pass to *send* an object that is an instance of *Error*, Fastify will
+automatically create an error structured as the following:
 
 ```js
-const serialize = reply
-                  .compileSerializationSchema({
-                    type: 'object',
-                    properties: {
-                      foo: {
-                        type: 'string'
-                      }
-                    }
-                  })
-serialize({ foo: 'bar' }) // '{"foo":"bar"}'
+{
+  error: String        // the HTTP error message
+  code: String         // the Fastify error code
+  message: String      // the user error message
+  statusCode: Number   // the HTTP status code
+}
+```
 
-// or
+You can add custom properties to the Error object, such as `headers`, that will
+be used to enhance the HTTP response.
 
-const serialize = reply
-                  .compileSerializationSchema({
-                    type: 'object',
-                    properties: {
-                      foo: {
-                        type: 'string'
-                      }
-                    }
-                  }, 200)
-serialize({ foo: 'bar' }) // '{"foo":"bar"}'
+> ℹ️ Note:
+> If you are passing an error to `send` and the statusCode is less than
+> 400, Fastify will automatically set it at 500.
 
-// or
+Tip: you can simplify errors by using the
+[`http-errors`](https://www.npmjs.com/package/http-errors) module or
+[`@fastify/sensible`](https://github.com/fastify/fastify-sensible) plugin to
+generate errors:
 
-const serialize = reply
-                  .compileSerializationSchema({
-                        '3xx': {
-                          content: {
-                            'application/json': {
-                              schema: {
-                                name: { type: 'string' },
-                                phone: { type: 'number' }
-                              }
-                            }
-                          }
-                        }
-                  }, '3xx', 'application/json')
-serialize({ name: 'Jone', phone: 201090909090 }) // '{"name":"Jone", "phone":201090909090}'
+```js
+fastify.get('/', function (request, reply) {
+  reply.send(httpErrors.Gone())
+})
 ```
 
-Note that you should be careful when using this function, as it will cache
-the compiled serialization functions based on the schema provided. If the
-schemas provided is mutated or changed, the serialization functions will not
-detect that the schema has been altered and for instance it will reuse the
-previously compiled serialization function based on the reference of the schema
-previously provided.
+To customize the JSON error output you can do it by:
 
-If there's a need to change the properties of a schema, always opt to create
-a totally new object, otherwise the implementation won't benefit from the cache
-mechanism.
+- setting a response JSON schema for the status code you need
+- add the additional properties to the `Error` instance
+
+Notice that if the returned status code is not in the response schema list, the
+default behavior will be applied.
 
-:Using the following schema as example:
 ```js
-const schema1 = {
-  type: 'object',
-  properties: {
-    foo: {
-      type: 'string'
+fastify.get('/', {
+  schema: {
+    response: {
+      501: {
+        type: 'object',
+        properties: {
+          statusCode: { type: 'number' },
+          code: { type: 'string' },
+          error: { type: 'string' },
+          message: { type: 'string' },
+          time: { type: 'string' }
+        }
+      }
     }
   }
-}
+}, function (request, reply) {
+  const error = new Error('This endpoint has not been implemented')
+  error.time = 'it will be implemented in two weeks'
+  reply.code(501).send(error)
+})
 ```
 
-*Not*
-```js
-const serialize = reply.compileSerializationSchema(schema1)
+If you want to customize error handling, check out
+[`setErrorHandler`](./Server.md#seterrorhandler) API.
 
-// Later on...
-schema1.properties.foo.type = 'integer'
-const newSerialize = reply.compileSerializationSchema(schema1)
+> ℹ️ Note:
+> You are responsible for logging when customizing the error handler.
 
-console.log(newSerialize === serialize) // true
-```
+API:
 
-*Instead*
 ```js
-const serialize = reply.compileSerializationSchema(schema1)
+fastify.setErrorHandler(function (error, request, reply) {
+  request.log.warn(error)
+  const statusCode = error.statusCode >= 400 ? error.statusCode : 500
+  reply
+    .code(statusCode)
+    .type('text/plain')
+    .send(statusCode >= 500 ? 'Internal server error' : error.message)
+})
+```
 
-// Later on...
-const newSchema = Object.assign({}, schema1)
-newSchema.properties.foo.type = 'integer'
+Beware that calling `reply.send(error)` in your custom error handler will send
+the error to the default error handler.
+Check out the [Reply Lifecycle](./Lifecycle.md#reply-lifecycle)
+for more information.
 
-const newSerialize = reply.compileSerializationSchema(newSchema)
+The not found errors generated by the router will use the
+[`setNotFoundHandler`](./Server.md#setnotfoundhandler)
 
-console.log(newSerialize === serialize) // false
+API:
+
+```js
+fastify.setNotFoundHandler(function (request, reply) {
+  reply
+    .code(404)
+    .type('text/plain')
+    .send('a custom not found')
+})
 ```
 
-### .serializeInput(data, [schema | httpStatus], [httpStatus], [contentType])
-<a id="serializeinput"></a>
+###### Async-Await and Promises
+<a id="async-await-promise"></a>
 
-This function will serialize the input data based on the provided schema
-or HTTP status code. If both are provided the `httpStatus` will take precedence.
+Fastify natively handles promises and supports async-await.
 
-If there is not a serialization function for a given `schema` a new serialization
-function will be compiled, forwarding the `httpStatus` and `contentType` if provided.
+*Note that in the following examples we are not using reply.send.*
+```js
+const { promisify } = require('node:util')
+const delay = promisify(setTimeout)
+
+fastify.get('/promises', options, function (request, reply) {
+ return delay(200).then(() => { return { hello: 'world' }})
+})
+
+fastify.get('/async-await', options, async function (request, reply) {
+  await delay(200)
+  return { hello: 'world' }
+})
+```
+
+Rejected promises default to a `500` HTTP status code. Reject the promise, or
+`throw` in an `async function`, with an object that has `statusCode` (or
+`status`) and `message` properties to modify the reply.
 
 ```js
-reply
-  .serializeInput({ foo: 'bar'}, {
-    type: 'object',
-    properties: {
-      foo: {
-        type: 'string'
-      }
-    }
-  }) // '{"foo":"bar"}'
+fastify.get('/teapot', async function (request, reply) {
+  const err = new Error()
+  err.statusCode = 418
+  err.message = 'short and stout'
+  throw err
+})
 
-// or
+fastify.get('/botnet', async function (request, reply) {
+  throw { statusCode: 418, message: 'short and stout' }
+  // will return to the client the same json
+})
+```
 
-reply
-  .serializeInput({ foo: 'bar'}, {
-    type: 'object',
-    properties: {
-      foo: {
-        type: 'string'
-      }
-    }
-  }, 200) // '{"foo":"bar"}'
+If you want to know more please review
+[Routes#async-await](./Routes.md#async-await).
 
-// or
+###### Type of the final payload
+<a id="payload-type"></a>
 
-reply
-  .serializeInput({ foo: 'bar'}, 200) // '{"foo":"bar"}'
+The type of the sent payload (after serialization and going through any
+[`onSend` hooks](./Hooks.md#onsend)) must be one of the following types,
+otherwise, an error will be thrown:
 
-// or
+- `string`
+- `Buffer`
+- `stream`
+- `undefined`
+- `null`
 
-reply
-  .serializeInput({ name: 'Jone', age: 18 }, '200', 'application/vnd.v1+json') // '{"name": "Jone", "age": 18}'
+##### .code(statusCode)
+<a id="code"></a>
+
+If not set via `reply.code`, the resulting `statusCode` will be `200`.
+
+`.status(statusCode)` is an alias of `.code(statusCode)`.
+
+##### .header(key, value)
+<a id="header"></a>
+
+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
+> [`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
+> will result in a 500 `TypeError` response.
+
+For more information, see
+[`http.ServerResponse#setHeader`](https://nodejs.org/dist/latest-v20.x/docs/api/http.html#http_response_setheader_name_value).
+
+- ###### set-cookie
+  <a id="set-cookie"></a>
+
+    - When sending different values as a cookie with `set-cookie` as the key,
+      every value will be sent as a cookie instead of replacing the previous
+      value.
+
+    ```js
+    reply.header('set-cookie', 'foo');
+    reply.header('set-cookie', 'bar');
+    ```
+  - The browser will only consider the latest reference of a key for the
+    `set-cookie` header. This is done to avoid parsing the `set-cookie` header
+    when added to a reply and speeds up the serialization of the reply.
+
+  - To reset the `set-cookie` header, you need to make an explicit call to
+    `reply.removeHeader('set-cookie')`, read more about `.removeHeader(key)`
+    [here](#removeheaderkey).
+
+##### .headers(object)
+<a id="headers"></a>
+
+Sets all the keys of the object as response headers.
+[`.header`](#headerkey-value) will be called under the hood.
+```js
+reply.headers({
+  'x-foo': 'foo',
+  'x-bar': 'bar'
+})
 ```
 
-See [.compileSerializationSchema(schema, [httpStatus], [contentType])](#compileserializationschema)
-for more information on how to compile serialization schemas.
+##### .type(contentType)
+<a id="type"></a>
 
-### .serializer(func)
-<a id="serializer"></a>
+Sets the content type for the response. This is a shortcut for
+`reply.header('Content-Type', 'the/type')`.
 
-By default, `.send()` will JSON-serialize any value that is not one of `Buffer`,
-`stream`, `string`, `undefined`, or `Error`. If you need to replace the default
-serializer with a custom serializer for a particular request, you can do so with
-the `.serializer()` utility. Be aware that if you are using a custom serializer,
-you must set a custom `'Content-Type'` header.
+```js
+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. For other content types, the
+charset must be set explicitly.
+
+##### .redirect(dest, [code])
+<a id="redirect"></a>
+
+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
+> [`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
+> result in a 500 `TypeError` response.
 
+> ⚠️ Security:
+> Encoding alone does **not** prevent open redirects. Neither `encodeURI`
+> nor `encodeurl` escapes `/`, so a caller-supplied target such as
+> `//evil.com` or `/\evil.com` survives encoding and is resolved by the
+> browser as a new host (a protocol-relative, authority-opening
+> reference). When `dest` can be influenced by request input
+> (`req.query`, `req.body`, `req.params`, cookies, or headers), validate
+> that the resolved target is same-origin or on an explicit allowlist
+> instead of relying on encoding:
+>
+> ```js
+> const target = new URL(dest, 'https://your-site.example')
+> if (target.origin !== 'https://your-site.example') {
+>   return reply.code(400).send()
+> }
+> ```
+
+Example (no `reply.code()` call) sets status code to `302` and redirects to
+`/home`
 ```js
-reply
-  .header('Content-Type', 'application/x-protobuf')
-  .serializer(protoBuf.serialize)
+reply.redirect('/home')
 ```
 
-Note that you don't need to use this utility inside a `handler` because Buffers,
-streams, and strings (unless a serializer is set) are considered to already be
-serialized.
+Example (no `reply.code()` call) sets status code to `303` and redirects to
+`/home`
+```js
+reply.redirect('/home', 303)
+```
 
+Example (`reply.code()` call) sets status code to `303` and redirects to `/home`
 ```js
-reply
-  .header('Content-Type', 'application/x-protobuf')
-  .send(protoBuf.serialize(data))
+reply.code(303).redirect('/home')
 ```
 
-See [`.send()`](#send) for more information on sending different types of
-values.
+Example (`reply.code()` call) sets status code to `302` and redirects to `/home`
+```js
+reply.code(303).redirect('/home', 302)
+```
 
-### .raw
-<a id="raw"></a>
+##### .getHeader(key)
+<a id="getHeader"></a>
 
-This is the
-[`http.ServerResponse`](https://nodejs.org/dist/latest-v20.x/docs/api/http.html#http_class_http_serverresponse)
-from Node core. Whilst you are using the Fastify `Reply` object, the use of
-`Reply.raw` functions is at your own risk as you are skipping all the Fastify
-logic of handling the HTTP response. e.g.:
+Retrieves the value of a previously set header.
+```js
+reply.header('x-foo', 'foo') // setHeader: key, value
+reply.getHeader('x-foo') // 'foo'
+```
+
+##### .getHeaders()
+<a id="getHeaders"></a>
+
+Gets a shallow copy of all current response headers, including those set via the
+raw `http.ServerResponse`. Note that headers set via Fastify take precedence
+over those set via `http.ServerResponse`.
 
 ```js
-app.get('/cookie-2', (req, reply) => {
-  reply.setCookie('session', 'value', { secure: false }) // this will not be used
+reply.header('x-foo', 'foo')
+reply.header('x-bar', 'bar')
+reply.raw.setHeader('x-foo', 'foo2')
+reply.getHeaders() // { 'x-foo': 'foo', 'x-bar': 'bar' }
+```
 
-  // in this case we are using only the nodejs http server response object
-  reply.raw.writeHead(200, { 'Content-Type': 'text/plain' })
-  reply.raw.write('ok')
-  reply.raw.end()
-})
+##### .hasHeader(key)
+<a id="hasHeader"></a>
+
+Returns a boolean indicating if the specified header has been set.
+
+##### .removeHeader(key)
+<a id="removeHeader"></a>
+
+Remove the value of a previously set header.
+```js
+reply.header('x-foo', 'foo')
+reply.removeHeader('x-foo')
+reply.getHeader('x-foo') // undefined
 ```
-Another example of the misuse of `Reply.raw` is explained in
-[Reply](#getheaders).
 
-### .sent
-<a id="sent"></a>
+##### .callNotFound()
+<a id="call-not-found"></a>
 
-As the name suggests, `.sent` is a property to indicate if a response has been
-sent via `reply.send()`. It will also be `true` in case `reply.hijack()` was
-used.
+Invokes the custom not found handler. Note that it will only call `preHandler`
+hook specified in [`setNotFoundHandler`](./Server.md#set-not-found-handler).
 
-In case a route handler is defined as an async function or it returns a promise,
-it is possible to call `reply.hijack()` to indicate that the automatic
-invocation of `reply.send()` once the handler promise resolve should be skipped.
-By calling `reply.hijack()`, an application claims full responsibility for the
-low-level request and response. Moreover, hooks will not be invoked.
+```js
+reply.callNotFound()
+```
 
-### .hijack()
+##### .hijack()
 <a name="hijack"></a>
 
 Sometimes you might need to halt the execution of the normal request lifecycle
@@ -662,357 +772,353 @@ app.get('/', (req, reply) => {
 If `reply.raw` is used to send a response back to the user, the `onResponse`
 hooks will still be executed.
 
-### .send(data)
-<a id="send"></a>
-
-As the name suggests, `.send()` is the function that sends the payload to the
-end user.
+##### .serializer(func)
+<a id="serializer"></a>
 
-#### Objects
-<a id="send-object"></a>
+By default, `.send()` will JSON-serialize any value that is not one of `Buffer`,
+`stream`, `string`, `undefined`, or `Error`. If you need to replace the default
+serializer with a custom serializer for a particular request, you can do so with
+the `.serializer()` utility. Be aware that if you are using a custom serializer,
+you must set a custom `'Content-Type'` header.
 
-As noted above, if you are sending JSON objects, `send` will serialize the
-object with
-[fast-json-stringify](https://www.npmjs.com/package/fast-json-stringify) if you
-set an output schema, otherwise, `JSON.stringify()` will be used.
 ```js
-fastify.get('/json', options, function (request, reply) {
-  reply.send({ hello: 'world' })
-})
+reply
+  .header('Content-Type', 'application/x-protobuf')
+  .serializer(protoBuf.serialize)
 ```
 
-#### Strings
-<a id="send-string"></a>
-
-If you pass a string to `send` without a `Content-Type`, it will be sent as
-`text/plain; charset=utf-8`. If you set the `Content-Type` header and pass a
-string to `send`, it will be serialized with the custom serializer if one is
-set, otherwise, it will be sent unmodified.
-
-> ℹ️ Note:
-> Even when the `Content-Type` header is set to `application/json`,
-> strings are sent unmodified by default. To serialize a string as JSON, you
-> must set a custom serializer:
+Note that you don't need to use this utility inside a `handler` because Buffers,
+streams, and strings (unless a serializer is set) are considered to already be
+serialized.
 
 ```js
-fastify.get('/json-string', async function (request, reply) {
-  reply
-    .type('application/json; charset=utf-8')
-    .serializer(JSON.stringify)
-    .send('Hello') // Returns "Hello" (JSON-encoded string)
-})
+reply
+  .header('Content-Type', 'application/x-protobuf')
+  .send(protoBuf.serialize(data))
 ```
+
+See [`.send()`](#send) for more information on sending different types of
+values.
+
+##### .serialize(payload)
+<a id="serialize"></a>
+
+Serializes the specified payload using the custom serializer set via
+[`.serializer()`](#serializerfunc), if any. Otherwise, it uses the default
+serializer of the route, which takes into account the response schema for the
+current status code. It returns the serialized payload.
+
 ```js
-fastify.get('/json', options, function (request, reply) {
-  reply.send('plain string')
+fastify.get('/', function (request, reply) {
+  const payload = reply.serialize({ hello: 'world' })
+  reply.type('application/json').send(payload)
 })
 ```
 
-#### Streams
-<a id="send-streams"></a>
-
-If you are sending a stream and you have not set a `'Content-Type'` header,
-*send* will set it to `'application/octet-stream'`.
+##### .trailer(key, function)
+<a id="trailer"></a>
 
-As noted above, streams are considered to be pre-serialized, so they will be
-sent unmodified without response validation.
+Sets a response trailer. Trailer is usually used when you need a header that
+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.
 
-When sending streams over HTTP/2, Fastify does not change the chunks emitted by
-the stream. If a stream can emit very large chunks, split them in your
-application code, for example by using `fs.createReadStream()` or a transform
-stream that emits smaller chunks.
+> ℹ️ Note:
+> For HTTP/1 responses, the header `Transfer-Encoding: chunked` will be added
+> once you use a trailer. HTTP/2 does not use chunked transfer encoding and
+> sends trailers using its native trailing headers support.
 
-See special note about error handling for streams in
-[`setErrorHandler`](./Server.md#seterrorhandler).
+> ℹ️ Note:
+> Any error passed to `done` callback will be ignored. If you are interested
+> in the error, you can turn on `debug` level logging.
 
 ```js
-const fs = require('node:fs')
+reply.trailer('server-timing', async function () {
+  return 'db;dur=53, app;dur=47.2'
+})
 
-fastify.get('/streams', function (request, reply) {
-  const stream = fs.createReadStream('some-file', 'utf8')
-  reply.header('Content-Type', 'application/octet-stream')
-  reply.send(stream)
+const { createHash } = require('node:crypto')
+// trailer function also receive two argument
+// @param {object} reply fastify reply
+// @param {string|Buffer|null} payload payload that already sent, note that it will be null when stream is sent
+// @param {function} done callback to set trailer value
+reply.trailer('content-md5', function(reply, payload, done) {
+  const hash = createHash('md5')
+  hash.update(payload)
+  done(null, hash.digest('hex'))
 })
-```
-When using async-await you will need to return or await the reply object:
-```js
-const fs = require('node:fs')
 
-fastify.get('/streams', async function (request, reply) {
-  const stream = fs.createReadStream('some-file', 'utf8')
-  reply.header('Content-Type', 'application/octet-stream')
-  return reply.send(stream)
+// when you prefer async-await
+reply.trailer('content-md5', async function(reply, payload) {
+  const hash = createHash('md5')
+  hash.update(payload)
+  return hash.digest('hex')
 })
 ```
 
-#### Buffers
-<a id="send-buffers"></a>
+##### .hasTrailer(key)
+<a id="hasTrailer"></a>
 
-If you are sending a buffer and you have not set a `'Content-Type'` header,
-*send* will set it to `'application/octet-stream'`.
+Returns a boolean indicating if the specified trailer has been set.
 
-As noted above, Buffers are considered to be pre-serialized, so they will be
-sent unmodified without response validation.
+##### .removeTrailer(key)
+<a id="removeTrailer"></a>
 
+Remove the value of a previously set trailer.
 ```js
-const fs = require('node:fs')
-
-fastify.get('/streams', function (request, reply) {
-  fs.readFile('some-file', (err, fileBuffer) => {
-    reply.send(err || fileBuffer)
-  })
+reply.trailer('server-timing', async function () {
+  return 'db;dur=53, app;dur=47.2'
 })
+reply.removeTrailer('server-timing')
+reply.hasTrailer('server-timing') // false
 ```
 
-When using async-await you will need to return or await the reply object:
-```js
-const fs = require('node:fs')
-
-fastify.get('/streams', async function (request, reply) {
-  fs.readFile('some-file', (err, fileBuffer) => {
-    reply.send(err || fileBuffer)
-  })
-  return reply
-})
-```
+##### .writeEarlyHints(hints, callback)
+<a id="writeEarlyHints"></a>
 
-#### TypedArrays
-<a id="send-typedarrays"></a>
+Sends early hints to the client. Early hints allow the client to
+start processing resources before the final response is sent.
+This can improve performance by allowing the client to preload
+or preconnect to resources while the server is still generating the response.
 
-`send` manages TypedArray like a Buffer, and sets the `'Content-Type'`
-header to `'application/octet-stream'` if not already set.
+The hints parameter is an object containing the early hint key-value pairs.
 
-As noted above, TypedArray/Buffers are considered to be pre-serialized, so they
-will be sent unmodified without response validation.
+Example:
 
 ```js
-const fs = require('node:fs')
-
-fastify.get('/streams', function (request, reply) {
-  const typedArray = new Uint16Array(10)
-  reply.send(typedArray)
-})
+reply.writeEarlyHints({
+  Link: '</styles.css>; rel=preload; as=style'
+});
 ```
 
-#### ReadableStream
-<a id="send-readablestream"></a>
+The optional callback parameter is a function that will be called
+once the hint is sent or if an error occurs.
 
-`ReadableStream` will be treated as a node stream mentioned above,
-the content is considered to be pre-serialized, so they will be
-sent unmodified without response validation.
+##### .then(fulfilled, rejected)
+<a id="then"></a>
 
-```js
-const fs = require('node:fs')
-const { ReadableStream } = require('node:stream/web')
+As the name suggests, a `Reply` object can be awaited upon, i.e. `await reply`
+will wait until the reply is sent. The `await` syntax calls the `reply.then()`.
 
-fastify.get('/streams', function (request, reply) {
-  const stream = fs.createReadStream('some-file')
-  reply.header('Content-Type', 'application/octet-stream')
-  reply.send(ReadableStream.from(stream))
-})
-```
+`reply.then(fulfilled, rejected)` accepts two parameters:
 
-#### Response
-<a id="send-response"></a>
+- `fulfilled` will be called when a response has been fully sent,
+- `rejected` will be called if the underlying stream had an error, e.g. the
+  socket has been destroyed.
 
-`Response` allows to manage the reply payload, status code and
-headers in one place. The payload provided inside `Response` is
-considered to be pre-serialized, so they will be sent unmodified
-without response validation.
+For more details, see:
 
-Please be aware when using `Response`, the status code and headers
-will not directly reflect to `reply.statusCode` and `reply.getHeaders()`.
-Such behavior is based on `Response` only allow `readonly` status
-code and headers. The data is not allow to be bi-direction editing,
-and may confuse when checking the `payload` in `onSend` hooks.
+- https://github.com/fastify/fastify/issues/1864 for the discussion about this
+  feature
+- https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then
+  for the signature
+
+##### .getDecorator(name)
+
+Returns the value of a reply decorator declared with
+[`decorateReply`](./Decorators.md#decoratereplyname-value-dependencies). If the
+decorator is a function, it is returned bound to the reply. It throws an
+`FST_ERR_DEC_UNDECLARED` error if the decorator has not been declared. See
+[`getDecorator`](./Decorators.md#getdecoratorname) for more details.
 
 ```js
-const fs = require('node:fs')
-const { ReadableStream } = require('node:stream/web')
+fastify.decorateReply('helper', function () {
+  return this.statusCode
+})
 
-fastify.get('/streams', function (request, reply) {
-  const stream = fs.createReadStream('some-file')
-  const readableStream = ReadableStream.from(stream)
-  const response = new Response(readableStream, {
-    status: 200,
-    headers: { 'content-type': 'application/octet-stream' }
-  })
-  reply.send(response)
+fastify.get('/', function (request, reply) {
+  const helper = reply.getDecorator('helper')
+  reply.code(201).send({ statusCode: helper() }) // { statusCode: 201 }
 })
 ```
 
+##### .getSerializationFunction(schema | httpStatus, [contentType])
+<a id="getserializationfunction"></a>
 
-#### Errors
-<a id="errors"></a>
+By calling this function using a provided `schema` or `httpStatus`,
+and the optional `contentType`, it will return a `serialization` function
+that can be used to serialize diverse inputs. It returns `undefined` if no
+serialization function was found using either of the provided inputs.
 
-If you pass to *send* an object that is an instance of *Error*, Fastify will
-automatically create an error structured as the following:
+This heavily depends of the `schema#responses` attached to the route, or
+the serialization functions compiled by using `compileSerializationSchema`.
 
 ```js
-{
-  error: String        // the HTTP error message
-  code: String         // the Fastify error code
-  message: String      // the user error message
-  statusCode: Number   // the HTTP status code
-}
-```
+const serialize = reply
+                  .getSerializationFunction({
+                    type: 'object',
+                    properties: {
+                      foo: {
+                        type: 'string'
+                      }
+                    }
+                  })
+serialize({ foo: 'bar' }) // '{"foo":"bar"}'
 
-You can add custom properties to the Error object, such as `headers`, that will
-be used to enhance the HTTP response.
+// or
 
-> ℹ️ Note:
-> If you are passing an error to `send` and the statusCode is less than
-> 400, Fastify will automatically set it at 500.
+const serialize = reply
+                  .getSerializationFunction(200)
+serialize({ foo: 'bar' }) // '{"foo":"bar"}'
 
-Tip: you can simplify errors by using the
-[`http-errors`](https://www.npmjs.com/package/http-errors) module or
-[`@fastify/sensible`](https://github.com/fastify/fastify-sensible) plugin to
-generate errors:
+// or
 
-```js
-fastify.get('/', function (request, reply) {
-  reply.send(httpErrors.Gone())
-})
+const serialize = reply
+                  .getSerializationFunction(200, 'application/json')
+serialize({ foo: 'bar' }) // '{"foo":"bar"}'
 ```
 
-To customize the JSON error output you can do it by:
+See [.compileSerializationSchema(schema, [httpStatus], [contentType])](#compileserializationschema)
+for more information on how to compile serialization schemas.
 
-- setting a response JSON schema for the status code you need
-- add the additional properties to the `Error` instance
+##### .compileSerializationSchema(schema, [httpStatus], [contentType])
+<a id="compileserializationschema"></a>
 
-Notice that if the returned status code is not in the response schema list, the
-default behavior will be applied.
+This function will compile a serialization schema and
+return a function that can be used to serialize data.
+The function returned (a.k.a. _serialization function_) returned is compiled
+by using the provided `SerializerCompiler`. Also this is cached by using
+a `WeakMap` for reducing compilation calls.
+
+The optional parameters `httpStatus` and `contentType`, if provided,
+are forwarded directly to the `SerializerCompiler`, so it can be used
+to compile the serialization function if a custom `SerializerCompiler` is used.
+
+This heavily depends of the `schema#responses` attached to the route, or
+the serialization functions compiled by using `compileSerializationSchema`.
 
 ```js
-fastify.get('/', {
-  schema: {
-    response: {
-      501: {
-        type: 'object',
-        properties: {
-          statusCode: { type: 'number' },
-          code: { type: 'string' },
-          error: { type: 'string' },
-          message: { type: 'string' },
-          time: { type: 'string' }
-        }
-      }
-    }
-  }
-}, function (request, reply) {
-  const error = new Error('This endpoint has not been implemented')
-  error.time = 'it will be implemented in two weeks'
-  reply.code(501).send(error)
-})
-```
+const serialize = reply
+                  .compileSerializationSchema({
+                    type: 'object',
+                    properties: {
+                      foo: {
+                        type: 'string'
+                      }
+                    }
+                  })
+serialize({ foo: 'bar' }) // '{"foo":"bar"}'
 
-If you want to customize error handling, check out
-[`setErrorHandler`](./Server.md#seterrorhandler) API.
+// or
 
-> ℹ️ Note:
-> You are responsible for logging when customizing the error handler.
+const serialize = reply
+                  .compileSerializationSchema({
+                    type: 'object',
+                    properties: {
+                      foo: {
+                        type: 'string'
+                      }
+                    }
+                  }, 200)
+serialize({ foo: 'bar' }) // '{"foo":"bar"}'
 
-API:
+// or
 
-```js
-fastify.setErrorHandler(function (error, request, reply) {
-  request.log.warn(error)
-  const statusCode = error.statusCode >= 400 ? error.statusCode : 500
-  reply
-    .code(statusCode)
-    .type('text/plain')
-    .send(statusCode >= 500 ? 'Internal server error' : error.message)
-})
+const serialize = reply
+                  .compileSerializationSchema({
+                        '3xx': {
+                          content: {
+                            'application/json': {
+                              schema: {
+                                name: { type: 'string' },
+                                phone: { type: 'number' }
+                              }
+                            }
+                          }
+                        }
+                  }, '3xx', 'application/json')
+serialize({ name: 'Jone', phone: 201090909090 }) // '{"name":"Jone", "phone":201090909090}'
 ```
 
-Beware that calling `reply.send(error)` in your custom error handler will send
-the error to the default error handler.
-Check out the [Reply Lifecycle](./Lifecycle.md#reply-lifecycle)
-for more information.
-
-The not found errors generated by the router will use the
-[`setNotFoundHandler`](./Server.md#setnotfoundhandler)
+Note that you should be careful when using this function, as it will cache
+the compiled serialization functions based on the schema provided. If the
+schemas provided is mutated or changed, the serialization functions will not
+detect that the schema has been altered and for instance it will reuse the
+previously compiled serialization function based on the reference of the schema
+previously provided.
 
-API:
+If there's a need to change the properties of a schema, always opt to create
+a totally new object, otherwise the implementation won't benefit from the cache
+mechanism.
 
+:Using the following schema as example:
 ```js
-fastify.setNotFoundHandler(function (request, reply) {
-  reply
-    .code(404)
-    .type('text/plain')
-    .send('a custom not found')
-})
+const schema1 = {
+  type: 'object',
+  properties: {
+    foo: {
+      type: 'string'
+    }
+  }
+}
 ```
 
-#### Type of the final payload
-<a id="payload-type"></a>
-
-The type of the sent payload (after serialization and going through any
-[`onSend` hooks](./Hooks.md#onsend)) must be one of the following types,
-otherwise, an error will be thrown:
-
-- `string`
-- `Buffer`
-- `stream`
-- `undefined`
-- `null`
+*Not*
+```js
+const serialize = reply.compileSerializationSchema(schema1)
 
-#### Async-Await and Promises
-<a id="async-await-promise"></a>
+// Later on...
+schema1.properties.foo.type = 'integer'
+const newSerialize = reply.compileSerializationSchema(schema1)
 
-Fastify natively handles promises and supports async-await.
+console.log(newSerialize === serialize) // true
+```
 
-*Note that in the following examples we are not using reply.send.*
+*Instead*
 ```js
-const { promisify } = require('node:util')
-const delay = promisify(setTimeout)
+const serialize = reply.compileSerializationSchema(schema1)
 
-fastify.get('/promises', options, function (request, reply) {
- return delay(200).then(() => { return { hello: 'world' }})
-})
+// Later on...
+const newSchema = Object.assign({}, schema1)
+newSchema.properties.foo.type = 'integer'
 
-fastify.get('/async-await', options, async function (request, reply) {
-  await delay(200)
-  return { hello: 'world' }
-})
+const newSerialize = reply.compileSerializationSchema(newSchema)
+
+console.log(newSerialize === serialize) // false
 ```
 
-Rejected promises default to a `500` HTTP status code. Reject the promise, or
-`throw` in an `async function`, with an object that has `statusCode` (or
-`status`) and `message` properties to modify the reply.
+##### .serializeInput(data, [schema | httpStatus], [httpStatus], [contentType])
+<a id="serializeinput"></a>
 
-```js
-fastify.get('/teapot', async function (request, reply) {
-  const err = new Error()
-  err.statusCode = 418
-  err.message = 'short and stout'
-  throw err
-})
+This function will serialize the input data based on the provided schema
+or HTTP status code. If both are provided the `httpStatus` will take precedence.
 
-fastify.get('/botnet', async function (request, reply) {
-  throw { statusCode: 418, message: 'short and stout' }
-  // will return to the client the same json
-})
-```
+If there is not a serialization function for a given `schema` a new serialization
+function will be compiled, forwarding the `httpStatus` and `contentType` if provided.
 
-If you want to know more please review
-[Routes#async-await](./Routes.md#async-await).
+```js
+reply
+  .serializeInput({ foo: 'bar'}, {
+    type: 'object',
+    properties: {
+      foo: {
+        type: 'string'
+      }
+    }
+  }) // '{"foo":"bar"}'
 
-### .then(fulfilled, rejected)
-<a id="then"></a>
+// or
 
-As the name suggests, a `Reply` object can be awaited upon, i.e. `await reply`
-will wait until the reply is sent. The `await` syntax calls the `reply.then()`.
+reply
+  .serializeInput({ foo: 'bar'}, {
+    type: 'object',
+    properties: {
+      foo: {
+        type: 'string'
+      }
+    }
+  }, 200) // '{"foo":"bar"}'
 
-`reply.then(fulfilled, rejected)` accepts two parameters:
+// or
 
-- `fulfilled` will be called when a response has been fully sent,
-- `rejected` will be called if the underlying stream had an error, e.g. the
-  socket has been destroyed.
+reply
+  .serializeInput({ foo: 'bar'}, 200) // '{"foo":"bar"}'
 
-For more details, see:
+// or
 
-- https://github.com/fastify/fastify/issues/1864 for the discussion about this
-  feature
-- https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then
-  for the signature
+reply
+  .serializeInput({ name: 'Jone', age: 18 }, '200', 'application/vnd.v1+json') // '{"name": "Jone", "age": 18}'
+```
+
+See [.compileSerializationSchema(schema, [httpStatus], [contentType])](#compileserializationschema)
+for more information on how to compile serialization schemas.