fastify 5.2.2 → 5.3.0

package/SPONSORS.md

@@ -16,7 +16,6 @@ _Be the first!_
 - [Mercedes-Benz Group](https://github.com/mercedes-benz)
 - [Val Town, Inc.](https://opencollective.com/valtown)
 - [Handsontable - JavaScript Data Grid](https://handsontable.com/docs/react-data-grid/?utm_source=Fastify_GH&utm_medium=sponsorship&utm_campaign=library_sponsorship_2024)
-- [Jspreadsheet](https://jspreadsheet.com/)
 - [Lokalise - A Localization and Translation Software Tool](https://lokalise.com/?utm_source=Fastify_GH&utm_medium=sponsorship)
 
 ## Tier 2

package/docs/Guides/Ecosystem.md

@@ -460,6 +460,8 @@ middlewares into Fastify plugins
   Lightweight cache plugin
 - [`fastify-list-routes`](https://github.com/chuongtrh/fastify-list-routes)
   A simple plugin for Fastify to list all available routes.
+- [`fastify-lm`](https://github.com/galiprandi/fastify-lm#readme)
+  Use OpenAI, Claude, Google, Deepseek, and others LMs with one Fastify plugin.
 - [`fastify-loader`](https://github.com/TheNoim/fastify-loader) Load routes from
   a directory and inject the Fastify instance in each file.
 - [`fastify-log-controller`](https://github.com/Eomm/fastify-log-controller/)

package/docs/Reference/Decorators.md

@@ -365,3 +365,202 @@ Will define the `foo` property on the Fastify instance:
 ```js
 console.log(fastify.foo) // 'a getter'
 ```
+
+### `getDecorator<T>` API
+
+Fastify's `getDecorator<T>` API retrieves an existing decorator from the
+Fastify instance, `Request`, or `Reply`. If the decorator is not defined, an
+`FST_ERR_DEC_UNDECLARED` error is thrown.
+
+#### Use cases
+
+**Early Plugin Dependency Validation**
+
+`getDecorator<T>` on Fastify instance verifies that required decorators are
+available at registration time. 
+
+For example:
+
+```js
+fastify.register(async function (fastify) {
+  const usersRepository = fastify.getDecorator('usersRepository')
+
+  fastify.get('/users', async function (request, reply) {
+    // We are sure `usersRepository` exists at runtime
+    return usersRepository.findAll()
+  })
+})
+```
+
+**Handling Missing Decorators**
+
+Directly accessing a decorator may lead to unexpected behavior if it is not declared:
+
+```ts
+const user = request.user;
+if (user && user.isAdmin) {
+  // Execute admin tasks.
+}
+```
+
+If `request.user` doesn't exist, then `user` will be set to `undefined`. 
+This makes it unclear whether the user is unauthenticated or the decorator is missing.
+
+Using `getDecorator` enforces runtime safety:
+
+```ts
+// If the decorator is missing, an explicit `FST_ERR_DEC_UNDECLARED` 
+// error is thrown immediately.
+const user = request.getDecorator('user');
+if (user && user.isAdmin) {
+  // Execute admin tasks.
+}
+```
+
+**Alternative to Module Augmentation**
+
+Decorators are typically typed via module augmentation:
+
+```ts
+declare module 'fastify' {
+  interface FastifyInstance {
+    usersRepository: IUsersRepository
+  }
+  interface FastifyRequest {
+    session: ISession
+  }
+  interface FastifyReply {
+    sendSuccess: SendSuccessFn
+  }
+}
+```
+
+This approach modifies the Fastify instance globally, which may lead to
+conflicts and inconsistent behavior in multi-server setups or with plugin
+encapsulation.
+
+Using `getDecorator<T>` allows to limit types scope:
+
+```ts
+serverOne.register(async function (fastify) {
+  const usersRepository = fastify.getDecorator<PostgreUsersRepository>(
+    'usersRepository'
+  )
+
+  fastify.decorateRequest('session', null)
+  fastify.addHook('onRequest', async (req, reply) => {
+    // Yes, the request object has a setDecorator method. 
+    // More information will be provided soon.
+    req.setDecorator('session', { user: 'Jean' })
+  })
+
+  fastify.get('/me', (request, reply) => {
+    const session = request.getDecorator<ISession>('session')
+    reply.send(session)
+  })
+})
+
+serverTwo.register(async function (fastify) {
+  const usersRepository = fastify.getDecorator<SqlLiteUsersRepository>(
+    'usersRepository'
+  )
+
+  fastify.decorateReply('sendSuccess', function (data) {
+    return this.send({ success: true })
+  })
+
+  fastify.get('/success', async (request, reply) => {
+    const sendSuccess = reply.getDecorator<SendSuccessFn>('sendSuccess')
+    await sendSuccess()
+  })
+})
+```
+
+#### Bound functions inference
+
+To save time, it's common to infer function types instead of 
+writing them manually:
+
+```ts
+function sendSuccess (this: FastifyReply) {
+  return this.send({ success: true })
+}
+
+export type SendSuccess = typeof sendSuccess
+```
+
+However, `getDecorator` returns functions with the `this` 
+context already **bound**, meaning the `this` parameter disappears 
+from the function signature.
+
+To correctly type it, you should use `OmitThisParameter` utility:
+
+```ts
+function sendSuccess (this: FastifyReply) {
+  return this.send({ success: true })
+}
+
+type BoundSendSuccess = OmitThisParameter<typeof sendSuccess>
+
+fastify.decorateReply('sendSuccess', sendSuccess)
+fastify.get('/success', async (request, reply) => {
+  const sendSuccess = reply.getDecorator<BoundSendSuccess>('sendSuccess')
+  await sendSuccess()
+})
+```
+
+### `Request.setDecorator<T>` Method
+
+The `setDecorator<T>` method provides a safe and convenient way to 
+update the value of a `Request` decorator.  
+If the decorator does not exist, a `FST_ERR_DEC_UNDECLARED` error 
+is thrown.
+
+#### Use Cases
+
+**Runtime Safety**
+
+A typical way to set a `Request` decorator looks like this:
+
+```ts
+fastify.decorateRequest('user', '')
+fastify.addHook('preHandler', async (req, reply) => {
+  req.user = 'Bob Dylan'
+})
+```
+
+However, there is no guarantee that the decorator actually exists 
+unless you manually check beforehand.  
+Additionally, typos are common, e.g. `account`, `acount`, or `accout`.
+
+By using `setDecorator`, you are always sure that the decorator exists:
+
+```ts
+fastify.decorateRequest('user', '')
+fastify.addHook('preHandler', async (req, reply) => {
+  // Throws FST_ERR_DEC_UNDECLARED if the decorator does not exist
+  req.setDecorator('user-with-typo', 'Bob Dylan')
+})
+```
+
+---
+
+**Type Safety**
+
+If the `FastifyRequest` interface does not declare the decorator, you 
+would typically need to use type assertions:
+
+```ts
+fastify.addHook('preHandler', async (req, reply) => {
+  (req as typeof req & { user: string }).user = 'Bob Dylan'
+})
+```
+
+The `setDecorator<T>` method eliminates the need for explicit type 
+assertions while allowing type safety:
+
+```ts
+fastify.addHook('preHandler', async (req, reply) => {
+  req.setDecorator<string>('user', 'Bob Dylan')
+})
+```

package/docs/Reference/Errors.md

@@ -36,6 +36,7 @@
     - [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_DEC_UNDECLARED](#fst_err_dec_undeclared)
     - [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)
@@ -306,6 +307,7 @@ Below is a table with all the error codes used by Fastify.
 | <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_dec_undeclared">FST_ERR_DEC_UNDECLARED</a> | An attempt was made to access a decorator that has not been declared. | Declare the decorator before using it. | [#](https://github.com/fastify/fastify/pull/)
 | <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) |

package/fastify.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const VERSION = '5.2.2'
+const VERSION = '5.3.0'
 
 const Avvio = require('avvio')
 const http = require('node:http')
@@ -343,6 +343,7 @@ function fastify (options) {
     decorateRequest: decorator.decorateRequest,
     hasRequestDecorator: decorator.existRequest,
     hasReplyDecorator: decorator.existReply,
+    getDecorator: decorator.getInstanceDecorator,
     addHttpMethod,
     // fake http injection
     inject,
@@ -639,7 +640,7 @@ function fastify (options) {
       resolveReady(fastify)
       fastify[kState].booting = false
       fastify[kState].ready = true
-      fastify[kState].promise = null
+      fastify[kState].readyPromise = null
     }
   }
 

package/lib/decorate.js

@@ -4,7 +4,7 @@ const {
   kReply,
   kRequest,
   kState,
-  kHasBeenDecorated
+  kHasBeenDecorated,
 } = require('./symbols.js')
 
 const {
@@ -12,7 +12,8 @@ const {
   FST_ERR_DEC_MISSING_DEPENDENCY,
   FST_ERR_DEC_AFTER_START,
   FST_ERR_DEC_REFERENCE_TYPE,
-  FST_ERR_DEC_DEPENDENCY_INVALID_TYPE
+  FST_ERR_DEC_DEPENDENCY_INVALID_TYPE,
+  FST_ERR_DEC_UNDECLARED,
 } = require('./errors')
 
 function decorate (instance, name, fn, dependencies) {
@@ -32,6 +33,18 @@ function decorate (instance, name, fn, dependencies) {
   }
 }
 
+function getInstanceDecorator (name) {
+  if (!checkExistence(this, name)) {
+    throw new FST_ERR_DEC_UNDECLARED(name, 'instance')
+  }
+
+  if (typeof this[name] === 'function') {
+    return this[name].bind(this)
+  }
+
+  return this[name]
+}
+
 function decorateConstructor (konstructor, name, fn, dependencies) {
   const instance = konstructor.prototype
   if (Object.hasOwn(instance, name) || hasKey(konstructor, name)) {
@@ -133,5 +146,7 @@ module.exports = {
   existReply: checkReplyExistence,
   dependencies: checkDependencies,
   decorateReply,
-  decorateRequest
+  decorateRequest,
+  getInstanceDecorator,
+  hasKey
 }

package/lib/errors.js

@@ -149,6 +149,10 @@ const codes = {
     'FST_ERR_DEC_REFERENCE_TYPE',
     "The decorator '%s' of type '%s' is a reference type. Use the { getter, setter } interface instead."
   ),
+  FST_ERR_DEC_UNDECLARED: createError(
+    'FST_ERR_DEC_UNDECLARED',
+    "No decorator '%s' has been declared on %s."
+  ),
 
   /**
    * hooks

package/lib/reply.js

@@ -22,7 +22,7 @@ const {
   kReplyCacheSerializeFns,
   kSchemaController,
   kOptions,
-  kRouteContext
+  kRouteContext,
 } = require('./symbols.js')
 const {
   onSendHookRunner,
@@ -52,8 +52,10 @@ const {
   FST_ERR_BAD_TRAILER_NAME,
   FST_ERR_BAD_TRAILER_VALUE,
   FST_ERR_MISSING_SERIALIZATION_FN,
-  FST_ERR_MISSING_CONTENTTYPE_SERIALIZATION_FN
+  FST_ERR_MISSING_CONTENTTYPE_SERIALIZATION_FN,
+  FST_ERR_DEC_UNDECLARED,
 } = require('./errors')
+const decorators = require('./decorate')
 
 const toString = Object.prototype.toString
 
@@ -475,6 +477,19 @@ Reply.prototype.then = function (fulfilled, rejected) {
   })
 }
 
+Reply.prototype.getDecorator = function (name) {
+  if (!decorators.hasKey(this, name) && !decorators.exist(this, name)) {
+    throw new FST_ERR_DEC_UNDECLARED(name, 'reply')
+  }
+
+  const decorator = this[name]
+  if (typeof decorator === 'function') {
+    return decorator.bind(this)
+  }
+
+  return decorator
+}
+
 function preSerializationHook (reply, payload) {
   if (reply[kRouteContext].preSerialization !== null) {
     preSerializationHookRunner(

package/lib/request.js

@@ -11,9 +11,10 @@ const {
   kOptions,
   kRequestCacheValidateFns,
   kRouteContext,
-  kRequestOriginalUrl
+  kRequestOriginalUrl,
 } = require('./symbols')
-const { FST_ERR_REQ_INVALID_VALIDATION_INVOCATION } = require('./errors')
+const { FST_ERR_REQ_INVALID_VALIDATION_INVOCATION, FST_ERR_DEC_UNDECLARED } = require('./errors')
+const decorators = require('./decorate')
 
 const HTTP_PART_SYMBOL_MAP = {
   body: kSchemaBody,
@@ -141,6 +142,12 @@ function buildRequestWithTrustProxy (R, trustProxy) {
   return _Request
 }
 
+function assertsRequestDecoration (request, name) {
+  if (!decorators.hasKey(request, name) && !decorators.exist(request, name)) {
+    throw new FST_ERR_DEC_UNDECLARED(name, 'request')
+  }
+}
+
 Object.defineProperties(Request.prototype, {
   server: {
     get () {
@@ -343,6 +350,25 @@ Object.defineProperties(Request.prototype, {
 
       return validate(input)
     }
+  },
+  getDecorator: {
+    value: function (name) {
+      assertsRequestDecoration(this, name)
+
+      const decorator = this[name]
+      if (typeof decorator === 'function') {
+        return decorator.bind(this)
+      }
+
+      return decorator
+    }
+  },
+  setDecorator: {
+    value: function (name, value) {
+      assertsRequestDecoration(this, name)
+
+      this[name] = value
+    }
   }
 })
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fastify",
-  "version": "5.2.2",
+  "version": "5.3.0",
   "description": "Fast and low overhead web framework, for Node.js",
   "main": "fastify.js",
   "type": "commonjs",
@@ -209,9 +209,9 @@
     "find-my-way": "^9.0.0",
     "light-my-request": "^6.0.0",
     "pino": "^9.0.0",
-    "process-warning": "^4.0.0",
+    "process-warning": "^5.0.0",
     "rfdc": "^1.3.1",
-    "secure-json-parse": "^3.0.1",
+    "secure-json-parse": "^4.0.0",
     "semver": "^7.6.0",
     "toad-cache": "^3.7.0"
   },

package/test/build/error-serializer.test.js

@@ -32,6 +32,5 @@ test('ensure the current error serializer is latest', { skip: !isPrepublish }, a
   const current = await fs.promises.readFile(path.resolve('lib/error-serializer.js'))
 
   // line break should not be a problem depends on system
-  // t.assert.strictEqual(unifyLineBreak(current), unifyLineBreak(code))
-  t.assert.ok(current)
+  t.assert.strictEqual(unifyLineBreak(current), unifyLineBreak(code))
 })

package/test/custom-parser.4.test.js

@@ -1,19 +1,18 @@
 'use strict'
 
-const t = require('tap')
-const test = t.test
+const { test } = require('node:test')
 const sget = require('simple-get').concat
 const Fastify = require('../fastify')
 const jsonParser = require('fast-json-body')
 const { getServerUrl } = require('./helper')
+const { waitForCb } = require('./toolkit')
 
 process.removeAllListeners('warning')
 
-test('should prefer string content types over RegExp ones', t => {
+test('should prefer string content types over RegExp ones', (t, testDone) => {
   t.plan(7)
   const fastify = Fastify()
-  t.teardown(fastify.close.bind(fastify))
-
+  t.after(() => { fastify.close() })
   fastify.post('/', (req, reply) => {
     reply.send(req.body)
   })
@@ -33,7 +32,8 @@ test('should prefer string content types over RegExp ones', t => {
   })
 
   fastify.listen({ port: 0 }, err => {
-    t.error(err)
+    t.assert.ifError(err)
+    const completion = waitForCb({ steps: 2 })
 
     sget({
       method: 'POST',
@@ -43,9 +43,10 @@ test('should prefer string content types over RegExp ones', t => {
         'Content-Type': 'application/json'
       }
     }, (err, response, body) => {
-      t.error(err)
-      t.equal(response.statusCode, 200)
-      t.same(body.toString(), JSON.stringify({ k1: 'myValue', k2: 'myValue' }))
+      t.assert.ifError(err)
+      t.assert.strictEqual(response.statusCode, 200)
+      t.assert.equal(body.toString(), JSON.stringify({ k1: 'myValue', k2: 'myValue' }))
+      completion.stepIn()
     })
 
     sget({
@@ -56,18 +57,21 @@ test('should prefer string content types over RegExp ones', t => {
         'Content-Type': 'application/javascript'
       }
     }, (err, response, body) => {
-      t.error(err)
-      t.equal(response.statusCode, 200)
-      t.same(body.toString(), 'javascript')
+      t.assert.ifError(err)
+      t.assert.strictEqual(response.statusCode, 200)
+      t.assert.equal(body.toString(), 'javascript')
+      completion.stepIn()
     })
+
+    completion.patience.then(testDone)
   })
 })
 
-test('removeContentTypeParser should support arrays of content types to remove', t => {
+test('removeContentTypeParser should support arrays of content types to remove', (t, testDone) => {
   t.plan(8)
 
   const fastify = Fastify()
-  t.teardown(fastify.close.bind(fastify))
+  t.after(() => fastify.close())
 
   fastify.addContentTypeParser('application/xml', function (req, payload, done) {
     payload.on('data', () => {})
@@ -90,7 +94,8 @@ test('removeContentTypeParser should support arrays of content types to remove',
   })
 
   fastify.listen({ port: 0 }, err => {
-    t.error(err)
+    t.assert.ifError(err)
+    const completion = waitForCb({ steps: 3 })
 
     sget({
       method: 'POST',
@@ -100,9 +105,10 @@ test('removeContentTypeParser should support arrays of content types to remove',
         'Content-Type': 'application/xml'
       }
     }, (err, response, body) => {
-      t.error(err)
-      t.equal(response.statusCode, 200)
-      t.same(body.toString(), 'xml')
+      t.assert.ifError(err)
+      t.assert.strictEqual(response.statusCode, 200)
+      t.assert.equal(body.toString(), 'xml')
+      completion.stepIn()
     })
 
     sget({
@@ -113,8 +119,9 @@ test('removeContentTypeParser should support arrays of content types to remove',
         'Content-Type': 'image/png'
       }
     }, (err, response, body) => {
-      t.error(err)
-      t.equal(response.statusCode, 415)
+      t.assert.ifError(err)
+      t.assert.strictEqual(response.statusCode, 415)
+      completion.stepIn()
     })
 
     sget({
@@ -125,16 +132,19 @@ test('removeContentTypeParser should support arrays of content types to remove',
         'Content-Type': 'application/json'
       }
     }, (err, response, body) => {
-      t.error(err)
-      t.equal(response.statusCode, 415)
+      t.assert.ifError(err)
+      t.assert.strictEqual(response.statusCode, 415)
+      completion.stepIn()
     })
+    completion.patience.then(testDone)
   })
 })
 
-test('removeContentTypeParser should support encapsulation', t => {
+test('removeContentTypeParser should support encapsulation', (t, testDone) => {
   t.plan(6)
 
   const fastify = Fastify()
+  t.after(() => fastify.close())
 
   fastify.addContentTypeParser('application/xml', function (req, payload, done) {
     payload.on('data', () => {})
@@ -158,7 +168,8 @@ test('removeContentTypeParser should support encapsulation', t => {
   })
 
   fastify.listen({ port: 0 }, err => {
-    t.error(err)
+    t.assert.ifError(err)
+    const completion = waitForCb({ steps: 2 })
 
     sget({
       method: 'POST',
@@ -168,8 +179,9 @@ test('removeContentTypeParser should support encapsulation', t => {
         'Content-Type': 'application/xml'
       }
     }, (err, response, body) => {
-      t.error(err)
-      t.equal(response.statusCode, 415)
+      t.assert.ifError(err)
+      t.assert.strictEqual(response.statusCode, 415)
+      completion.stepIn()
     })
 
     sget({
@@ -180,18 +192,20 @@ test('removeContentTypeParser should support encapsulation', t => {
         'Content-Type': 'application/xml'
       }
     }, (err, response, body) => {
-      t.error(err)
-      t.equal(response.statusCode, 200)
-      t.same(body.toString(), 'xml')
-      fastify.close()
+      t.assert.ifError(err)
+      t.assert.strictEqual(response.statusCode, 200)
+      t.assert.equal(body.toString(), 'xml')
+      completion.stepIn()
     })
+    completion.patience.then(testDone)
   })
 })
 
-test('removeAllContentTypeParsers should support encapsulation', t => {
+test('removeAllContentTypeParsers should support encapsulation', (t, testDone) => {
   t.plan(6)
 
   const fastify = Fastify()
+  t.after(() => fastify.close())
 
   fastify.post('/', (req, reply) => {
     reply.send(req.body)
@@ -208,7 +222,8 @@ test('removeAllContentTypeParsers should support encapsulation', t => {
   })
 
   fastify.listen({ port: 0 }, err => {
-    t.error(err)
+    t.assert.ifError(err)
+    const completion = waitForCb({ steps: 2 })
 
     sget({
       method: 'POST',
@@ -218,8 +233,9 @@ test('removeAllContentTypeParsers should support encapsulation', t => {
         'Content-Type': 'application/json'
       }
     }, (err, response, body) => {
-      t.error(err)
-      t.equal(response.statusCode, 415)
+      t.assert.ifError(err)
+      t.assert.strictEqual(response.statusCode, 415)
+      completion.stepIn()
     })
 
     sget({
@@ -230,10 +246,11 @@ test('removeAllContentTypeParsers should support encapsulation', t => {
         'Content-Type': 'application/json'
       }
     }, (err, response, body) => {
-      t.error(err)
-      t.equal(response.statusCode, 200)
-      t.same(JSON.parse(body.toString()).test, 1)
-      fastify.close()
+      t.assert.ifError(err)
+      t.assert.strictEqual(response.statusCode, 200)
+      t.assert.equal(JSON.parse(body.toString()).test, 1)
+      completion.stepIn()
     })
+    completion.patience.then(testDone)
   })
 })