fastify 4.0.0-rc.5 → 4.0.2

package/docs/Reference/Reply.md

@@ -129,7 +129,11 @@ 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 [`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.
+> 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-v14.x/docs/api/http.html#http_response_setheader_name_value).
@@ -208,11 +212,16 @@ Returns a boolean indicating if the specified header has been set.
 ### .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.
+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.
 
-*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: Currently, the computation function only supports synchronous function. That means `async-await` and `promise` are not supported.*
+*Note: Currently, the computation function only supports synchronous function.
+That means `async-await` and `promise` are not supported.*
 
 ```js
 reply.trailer('server-timing', function() {
@@ -254,7 +263,11 @@ 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 [`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.
+> 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.
 
 Example (no `reply.code()` call) sets status code to `302` and redirects to
 `/home`
@@ -310,7 +323,8 @@ Sets the content type for the response. This is a shortcut for
 ```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.
+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.
 
 ### .serializer(func)
 <a id="serializer"></a>
@@ -366,22 +380,22 @@ Another example of the misuse of `Reply.raw` is explained in
 <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.
+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.
+By calling `reply.hijack()`, an application claims full responsibility for the
+low-level request and response. Moreover, hooks will not be invoked.
 
-*Modifying the `.sent` property directly is deprecated. Please use the aforementioned
-`.hijack()` method to achieve the same effect.*
+*Modifying the `.sent` property directly is deprecated. Please use the
+aforementioned `.hijack()` method to achieve the same effect.*
 
 <a name="hijack"></a>
 ### .hijack()
-Sometimes you might need to halt the execution of the normal request lifecycle and
-handle sending the response manually.
+Sometimes you might need to halt the execution of the normal request lifecycle
+and handle sending the response manually.
 
 To achieve this, Fastify provides the `reply.hijack()` method that can be called
 during the request lifecycle (At any point before `reply.send()` is called), and
@@ -561,8 +575,8 @@ fastify.setNotFoundHandler(function (request, reply) {
 <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:
+[`onSend` hooks](./Hooks.md#onsend)) must be one of the following types,
+otherwise, an error will be thrown:
 
 - `string`
 - `Buffer`

package/docs/Reference/Request.md

@@ -13,7 +13,7 @@ Request is a core Fastify object containing the following fields:
 - [`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
->>>>>>> main:docs/Reference/Request.md
+  context](./Encapsulation.md)
 - `id` - the request ID
 - `log` - the logger instance of the incoming request
 - `ip` - the IP address of the incoming request
@@ -55,8 +55,8 @@ 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.
 
-> Note: For performance reason on `not found` route, you may see that we will add
-an extra property `Symbol('fastify.RequestAcceptVersion')` on the 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.
 
 ```js
 fastify.post('/:params', options, function (request, reply) {

package/docs/Reference/Routes.md

@@ -2,8 +2,8 @@
 
 ## Routes
 
-The route methods will configure the endpoints of your application. You have
-two ways to declare a route with Fastify: the shorthand method and the full
+The route methods will configure the endpoints of your application. You have two
+ways to declare a route with Fastify: the shorthand method and the full
 declaration.
 
 - [Full declaration](#full-declaration)
@@ -13,7 +13,8 @@ declaration.
 - [Async Await](#async-await)
 - [Promise resolution](#promise-resolution)
 - [Route Prefixing](#route-prefixing)
-  - [Handling of / route inside prefixed plugins](#handling-of--route-inside-prefixed-plugins)
+  - [Handling of / route inside prefixed
+    plugins](#handling-of--route-inside-prefixed-plugins)
 - [Custom Log Level](#custom-log-level)
 - [Custom Log Serializer](#custom-log-serializer)
 - [Config](#config)
@@ -52,8 +53,9 @@ fastify.route(options)
   instance option. If you want a custom `HEAD` handler without disabling this
   option, make sure to define it before the `GET` route.
 * `attachValidation`: attach `validationError` to request, if there is a schema
-  validation error, instead of sending the error to the error handler.
-  The default [error format](https://ajv.js.org/api.html#error-objects) is the Ajv one.
+  validation error, instead of sending the error to the error handler. The
+  default [error format](https://ajv.js.org/api.html#error-objects) is the Ajv
+  one.
 * `onRequest(request, reply, done)`: a [function](./Hooks.md#onrequest) called
   as soon as a request is received, it could also be an array of functions.
 * `preParsing(request, reply, done)`: a [function](./Hooks.md#preparsing) called
@@ -114,7 +116,8 @@ fastify.route(options)
   * `slash`: Will register only `/prefix/`.
   * `no-slash`: Will register only `/prefix`.
 
-  Note: this option does not override `ignoreTrailingSlash` in [Server](./Server.md) configuration.
+  Note: this option does not override `ignoreTrailingSlash` in
+  [Server](./Server.md) configuration.
 
 * `request` is defined in [Request](./Request.md).
 
@@ -227,35 +230,66 @@ checked before parametric and wildcard.*
 
 ```js
 // parametric
-fastify.get('/example/:userId', (request, reply) => {})
-fastify.get('/example/:userId/:secretToken', (request, reply) => {})
+fastify.get('/example/:userId', function (request, reply) {
+  // curl ${app-url}/example/12345
+  // userId === '12345'
+  const { userId } = request.params;
+  // your code here
+})
+fastify.get('/example/:userId/:secretToken', function (request, reply) {
+  // curl ${app-url}/example/12345/abc.zHi
+  // userId === '12345'
+  // secretToken === 'abc.zHi'
+  const { userId, secretToken } = request.params;
+  // your code here
+})
 
 // wildcard
-fastify.get('/example/*', (request, reply) => {})
+fastify.get('/example/*', function (request, reply) {})
 ```
 
-Regular expression routes are supported as well, but be aware that you have to escape slashes. Take note that RegExp is also very expensive in terms of performance!
+Regular expression routes are supported as well, but be aware that you have to
+escape slashes. Take note that RegExp is also very expensive in terms of
+performance!
 ```js
 // parametric with regexp
-fastify.get('/example/:file(^\\d+).png', (request, reply) => {})
+fastify.get('/example/:file(^\\d+).png', function (request, reply) {
+  // curl ${app-url}/example/12345.png
+  // file === '12345'
+  const { file } = request.params;
+  // your code here
+})
 ```
 
 It is possible to define more than one parameter within the same couple of slash
 ("/"). Such as:
 ```js
-fastify.get('/example/near/:lat-:lng/radius/:r', (request, reply) => {})
+fastify.get('/example/near/:lat-:lng/radius/:r', function (request, reply) {
+  // curl ${app-url}/example/near/15°N-30°E/radius/20
+  // lat === "15°N"
+  // lng === "30°E"
+  // r ==="20"
+  const { lat, lng, r } = request.params;
+  // your code here
+})
 ```
 *Remember in this case to use the dash ("-") as parameters separator.*
 
 Finally, it is possible to have multiple parameters with RegExp:
 ```js
-fastify.get('/example/at/:hour(^\\d{2})h:minute(^\\d{2})m', (request, reply) => {})
+fastify.get('/example/at/:hour(^\\d{2})h:minute(^\\d{2})m', function (request, reply) {
+  // curl ${app-url}/example/at/08h24m
+  // hour === "08"
+  // minute === "24"
+  const { hour, minute } = request.params;
+  // your code here
+})
 ```
 In this case as parameter separator it is possible to use whatever character is
 not matched by the regular expression.
 
-Having a route with multiple parameters may negatively affect performance,
-so prefer a single parameter approach whenever possible, especially on routes that
+Having a route with multiple parameters may negatively affect performance, so
+prefer a single parameter approach whenever possible, especially on routes that
 are on the hot path of your application. If you are interested in how we handle
 the routing, check out [find-my-way](https://github.com/delvedor/find-my-way).
 
@@ -280,8 +314,8 @@ fastify.get('/', options, async function (request, reply) {
 As you can see, we are not calling `reply.send` to send back the data to the
 user. You just need to return the body and you are done!
 
-If you need it you can also send back the data to the user with `reply.send`.
-In this case do not forget to `return reply` or `await reply` in your `async`
+If you need it you can also send back the data to the user with `reply.send`. In
+this case do not forget to `return reply` or `await reply` in your `async`
 handler or you will introduce a race condition in certain situations.
 
 ```js
@@ -320,22 +354,22 @@ fastify.get('/', options, async function (request, reply) {
   first one that happens takes precedence, the second value will be discarded,
   and a *warn* log will also be emitted because you tried to send a response
   twice.
-* Calling `reply.send()` outside of the promise is possible but requires
-  special attention. For more details read
-  [promise-resolution](#promise-resolution).
+* Calling `reply.send()` outside of the promise is possible but requires special
+  attention. For more details read [promise-resolution](#promise-resolution).
 * You cannot return `undefined`. For more details read
   [promise-resolution](#promise-resolution).
 
 ### Promise resolution
 <a id="promise-resolution"></a>
 
-If your handler is an `async` function or returns a promise, you should be aware of
-the special behavior that is necessary to support the callback and promise
+If your handler is an `async` function or returns a promise, you should be aware
+of the special behavior that is necessary to support the callback and promise
 control-flow. When the handler's promise is resolved, the reply will be
 automatically sent with its value unless you explicitly await or return `reply`
 in your handler.
 
-1. If you want to use `async/await` or promises but respond with a value with `reply.send`:
+1. If you want to use `async/await` or promises but respond with a value with
+   `reply.send`:
     - **Do** `return reply` / `await reply`.
     - **Do not** forget to call `reply.send`.
 2. If you want to use `async/await` or promises:
@@ -343,9 +377,9 @@ in your handler.
     - **Do** return the value that you want to send.
 
 In this way, we can support both `callback-style` and `async-await`, with the
-minimum trade-off. Despite so much freedom we highly recommend going with
-only one style because error handling should be handled in a consistent way
-within your application.
+minimum trade-off. Despite so much freedom we highly recommend going with only
+one style because error handling should be handled in a consistent way within
+your application.
 
 **Notice**: Every async function returns a promise by itself.
 
@@ -392,14 +426,55 @@ Now your clients will have access to the following routes:
 - `/v2/user`
 
 You can do this as many times as you want, it also works for nested `register`,
-and route parameters are supported as well. Be aware that if you use
-[`fastify-plugin`](https://github.com/fastify/fastify-plugin) this option will
-not work.
+and route parameters are supported as well.
+
+In case you want to use prefix for all of your routes, you can put them inside a
+plugin:
+
+```js
+const fastify = require('fastify')()
+
+const route = {
+    method: 'POST',
+    url: '/login',
+    handler: () => {},
+    schema: {},
+}
+
+fastify.register(function(app, _, done) {
+  app.get('/users', () => {})
+  app.route(route)
+
+  done()
+}, { prefix: '/v1' }) // global route prefix
+
+await fastify.listen({ port: 0 })
+```
+
+### Route Prefixing and fastify-plugin
+<a id="fastify-plugin"></a>
+
+Be aware that if you use
+[`fastify-plugin`](https://github.com/fastify/fastify-plugin) for wrapping your
+routes, this option will not work. You can still make it work by wrapping a
+plugin in a plugin, e. g.:
+```js
+const fp = require('fastify-plugin')
+const routes = require('./lib/routes')
+
+module.exports = fp(async function (app, opts) {
+  app.register(routes, {
+    prefix: '/v1',
+  })
+}, {
+  name: 'my-routes'
+})
+```
 
 #### Handling of / route inside prefixed plugins
 
-The `/` route has different behavior depending on if the prefix ends with `/`
-or not. As an example, if we consider a prefix `/something/`, adding a `/` route
+The `/` route has different behavior depending on if the prefix ends with `/` or
+not. As an example, if we consider a prefix `/something/`, adding a `/` route
 will only match `/something/`. If we consider a prefix `/something`, adding a
 `/` route will match both `/something` and `/something/`.
 
@@ -408,8 +483,8 @@ See the `prefixTrailingSlash` route option above to change this behavior.
 ### Custom Log Level
 <a id="custom-log-level"></a>
 
-You might need different log levels in your routes; Fastify
-achieves this in a very straightforward way.
+You might need different log levels in your routes; Fastify achieves this in a
+very straightforward way.
 
 You just need to pass the option `logLevel` to the plugin option or the route
 option with the
@@ -540,7 +615,7 @@ You can provide a `version` key in the `constraints` option to a route.
 Versioned routes allow you to declare multiple handlers for the same HTTP route
 path, which will then be matched according to each request's `Accept-Version`
 header. The `Accept-Version` header value should follow the
-[semver](http://semver.org/) specification, and routes should be declared with
+[semver](https://semver.org/) specification, and routes should be declared with
 exact semver versions for matching.
 
 Fastify will require a request `Accept-Version` header to be set if the route
@@ -659,9 +734,9 @@ fastify.route({
 Fastify will check the HTTP version of every request, based on configuration
 options ([http2](./Server.md#http2), [https](./Server.md#https), and
 [serverFactory](./Server.md#serverfactory)), to determine if it matches one or
-all of the > following versions: `2.0`, `1.1`, and `1.0`. If Fastify receives
-a different HTTP version in the request it will return a
-`505 HTTP Version Not Supported` error.
+all of the > following versions: `2.0`, `1.1`, and `1.0`. If Fastify receives a
+different HTTP version in the request it will return a `505 HTTP Version Not
+Supported` error.
 
 |                          | 2.0 | 1.1 | 1.0 | skip |
 |:------------------------:|:---:|:---:|:---:|:----:|
@@ -673,4 +748,4 @@ a different HTTP version in the request it will return a
 | serverFactory            |     |     |     | ✓    |
 
  Note: The internal HTTP version check will be removed in the future when Node
- implements [this feature](https://github.com/nodejs/node/issues/43115).
+ implements [this feature](https://github.com/nodejs/node/issues/43115).