Merge branch 'main' into addresses

Signed-off-by: Matteo Collina <hello@matteocollina.com>

.github/labeler.yml

@@ -1,13 +1,16 @@
 # PRs that only touch the docs folder
 documentation:
-- all: ["docs/**/*"]
+- changed-files:
+  - any-glob-to-any-file: docs/**
 
 "github actions":
-- all: [".github/workflows/*"]
+- changed-files:
+  - any-glob-to-any-file: ".github/workflows/*"
 
 # PRs that only touch type files
 typescript:
-- all: ["**/*[.|-]d.ts"]
+- changed-files:
+  - any-glob-to-any-file: "**/*[.|-]d.ts"
 
 plugin:
 - all: ["docs/Guides/Ecosystem.md"]

.github/workflows/labeler.yml

@@ -1,14 +1,11 @@
 name: "Pull Request Labeler"
 on: pull_request_target
 
-permissions:
-  contents: read
-  pull-requests: write
-
 jobs:
   label:
+    permissions:
+      contents: read
+      pull-requests: write
     runs-on: ubuntu-latest
     steps:
     - uses: actions/labeler@v5
-      with:
-        repo-token: "${{ secrets.GITHUB_TOKEN }}"

docs/Guides/Database.md

@@ -245,7 +245,7 @@ for Postgres, MySQL, SQL Server and SQLite. For MongoDB migrations, please check
 #### [Postgrator](https://www.npmjs.com/package/postgrator)
 
 Postgrator is Node.js SQL migration tool that uses a directory of SQL scripts to
-alter the database schema. Each file an migrations folder need to follow the
+alter the database schema. Each file in a migrations folder need to follow the
 pattern: ` [version].[action].[optional-description].sql`.
 
 **version:** must be an incrementing number (e.g. `001` or a timestamp).

docs/Reference/Decorators.md

@@ -59,8 +59,8 @@ close as possible to the value intended to be set dynamically in the future.
 Initialize a decorator as a `''` if the intended value is a string, and as
 `null` if it will be an object or a function.
 
-Remember this example works only with value types as reference types will be
-shared amongst all requests. See [decorateRequest](#decorate-request).
+Remember this example works only with value types as reference types will 
+thrown and error during the fastify startup. See [decorateRequest](#decorate-request).
 
 See [JavaScript engine fundamentals: Shapes and Inline
 Caches](https://mathiasbynens.be/notes/shapes-ics) for more information on this
@@ -83,7 +83,7 @@ fastify.decorate('utility', function () {
 })
 ```
 
-As mentioned above, non-function values can be attached:
+As mentioned above, non-function values can be attached to the server instance as:
 
 ```js
 fastify.decorate('conf', {
@@ -177,17 +177,18 @@ fastify.decorateReply('utility', function () {
 Note: using an arrow function will break the binding of `this` to the Fastify
 `Reply` instance.
 
-Note: using `decorateReply` will emit a warning if used with a reference type:
+Note: using `decorateReply` will throw and error if used with a reference type:
 
 ```js
 // Don't do this
 fastify.decorateReply('foo', { bar: 'fizz'})
 ```
-In this example, the reference of the object is shared with all the requests:
-**any mutation will impact all requests, potentially creating security
-vulnerabilities or memory leaks**. To achieve proper encapsulation across
-requests configure a new value for each incoming request in the [`'onRequest'`
-hook](./Hooks.md#onrequest). Example:
+In this example, the reference of the object would be shared with all the requests
+and **any mutation will impact all requests, potentially creating security
+vulnerabilities or memory leaks**, so Fastify blocks it.
+
+To achieve proper encapsulation across requests configure a new value for each
+incoming request in the [`'onRequest'` hook](./Hooks.md#onrequest). Example:
 
 ```js
 const fp = require('fastify-plugin')
@@ -219,18 +220,20 @@ fastify.decorateRequest('utility', function () {
 Note: using an arrow function will break the binding of `this` to the Fastify
 `Request` instance.
 
-Note: using `decorateRequest` will emit a warning if used with a reference type:
+Note: using `decorateRequest` will emit an error if used with a reference type:
 
 ```js
 // Don't do this
 fastify.decorateRequest('foo', { bar: 'fizz'})
 ```
-In this example, the reference of the object is shared with all the requests:
-**any mutation will impact all requests, potentially creating security
-vulnerabilities or memory leaks**.
+In this example, the reference of the object would be shared with all the requests
+and **any mutation will impact all requests, potentially creating security
+vulnerabilities or memory leaks**, so Fastify blocks it.
 
 To achieve proper encapsulation across requests configure a new value for each
-incoming request in the [`'onRequest'` hook](./Hooks.md#onrequest). Example:
+incoming request in the [`'onRequest'` hook](./Hooks.md#onrequest).
+
+Example:
 
 ```js
 const fp = require('fastify-plugin')
@@ -245,6 +248,29 @@ async function myPlugin (app) {
 module.exports = fp(myPlugin)
 ```
 
+The hook solution is more flexible and allows for more complex initialization
+because you can add more logic to the `onRequest` hook.
+
+Another approach is to use the getter/setter pattern, but it requires 2 decorators:
+
+```js
+fastify.decorateRequest('my_decorator_holder') // define the holder
+fastify.decorateRequest('user', {
+  getter () {
+    this.my_decorator_holder ??= {} // initialize the holder
+    return this.my_decorator_holder
+  }
+})
+
+fastify.get('/', async function (req, reply) {
+  req.user.access = 'granted'
+  // other code
+})
+```
+
+This ensures that the `user` property is always unique for each
+request.
+
 See [`decorate`](#decorate) for information about the `dependencies` parameter.
 
 #### `hasDecorator(name)`

docs/Reference/Errors.md

@@ -36,6 +36,7 @@
     - [FST_ERR_DEC_DEPENDENCY_INVALID_TYPE](#fst_err_dec_dependency_invalid_type)
     - [FST_ERR_DEC_MISSING_DEPENDENCY](#fst_err_dec_missing_dependency)
     - [FST_ERR_DEC_AFTER_START](#fst_err_dec_after_start)
+    - [FST_ERR_DEC_REFERENCE_TYPE](#fst_err_dec_reference_type)
     - [FST_ERR_HOOK_INVALID_TYPE](#fst_err_hook_invalid_type)
     - [FST_ERR_HOOK_INVALID_HANDLER](#fst_err_hook_invalid_handler)
     - [FST_ERR_HOOK_INVALID_ASYNC_HANDLER](#fst_err_hook_invalid_async_handler)
@@ -308,6 +309,7 @@ Below is a table with all the error codes that Fastify uses.
 | <a id="fst_err_dec_dependency_invalid_type">FST_ERR_DEC_DEPENDENCY_INVALID_TYPE</a> | The dependencies of decorator must be of type `Array`. | Use an array for the dependencies. | [#3090](https://github.com/fastify/fastify/pull/3090) |
 | <a id="fst_err_dec_missing_dependency">FST_ERR_DEC_MISSING_DEPENDENCY</a> | The decorator cannot be registered due to a missing dependency. | Register the missing dependency. | [#1168](https://github.com/fastify/fastify/pull/1168) |
 | <a id="fst_err_dec_after_start">FST_ERR_DEC_AFTER_START</a> | The decorator cannot be added after start. | Add the decorator before starting the server. | [#2128](https://github.com/fastify/fastify/pull/2128) |
+| <a id="fst_err_dec_reference_type">FST_ERR_DEC_REFERENCE_TYPE</a> | The decorator cannot be a reference type. | Define the decorator with a getter/setter interface or an empty decorator with a hook. | [#5462](https://github.com/fastify/fastify/pull/5462) |
 | <a id="fst_err_hook_invalid_type">FST_ERR_HOOK_INVALID_TYPE</a> | The hook name must be a string. | Use a string for the hook name. | [#1168](https://github.com/fastify/fastify/pull/1168) |
 | <a id="fst_err_hook_invalid_handler">FST_ERR_HOOK_INVALID_HANDLER</a> | The hook callback must be a function. | Use a function for the hook callback. | [#1168](https://github.com/fastify/fastify/pull/1168) |
 | <a id="fst_err_hook_invalid_async_handler">FST_ERR_HOOK_INVALID_ASYNC_HANDLER</a> | Async function has too many arguments. Async hooks should not use the `done` argument. | Remove the `done` argument from the async hook. | [#4367](https://github.com/fastify/fastify/pull/4367) |

docs/Reference/Routes.md

@@ -768,7 +768,7 @@ matching wildcard subdomains (or any other pattern):
 fastify.route({
   method: 'GET',
   url: '/',
-  constraints: { host: /.*\.fastify\.io/ }, // will match any subdomain of fastify.dev
+  constraints: { host: /.*\.fastify\.dev/ }, // will match any subdomain of fastify.dev
   handler: function (request, reply) {
     reply.send('hello world from ' + request.headers.host)
   }

docs/Reference/Type-Providers.md

@@ -37,9 +37,8 @@ $ npm i @fastify/type-provider-json-schema-to-ts
 ```
 
 ```typescript
-import { JsonSchemaToTsProvider } from '@fastify/type-provider-json-schema-to-ts'
-
 import fastify from 'fastify'
+import { JsonSchemaToTsProvider } from '@fastify/type-provider-json-schema-to-ts'
 
 const server = fastify().withTypeProvider<JsonSchemaToTsProvider>()
 
@@ -72,11 +71,10 @@ $ npm i @fastify/type-provider-typebox
 ```
 
 ```typescript
+import fastify from 'fastify'
 import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox'
 import { Type } from '@sinclair/typebox'
 
-import fastify from 'fastify'
-
 const server = fastify().withTypeProvider<TypeBoxTypeProvider>()
 
 server.get('/route', {