Decorators

Decorators

The decorators API allows customization of the core Fastify objects, such as the server instance itself and any request and reply objects used during the HTTP request lifecycle. The decorators API can be used to attach any type of property to the core objects, e.g. functions, plain objects, or native types.

This API is synchronous. Attempting to define a decoration asynchronously could result in the Fastify instance booting before the decoration completes its initialization. To avoid this issue, and register an asynchronous decoration, the register API, in combination with fastify-plugin, must be used instead. To learn more, see the Plugins documentation.

Decorating core objects with this API allows the underlying JavaScript engine to optimize the handling of server, request, and reply objects. This is accomplished by defining the shape of all such object instances before they are instantiated and used. As an example, the following is not recommended because it will change the shape of objects during their lifecycle:

// Bad example! Continue reading.

// Attach a user property to the incoming request before the request
// handler is invoked.
fastify.addHook('preHandler', function (req, reply, done) {
  req.user = 'Bob Dylan'
  done()
})

// Use the attached user property in the request handler.
fastify.get('/', function (req, reply) {
  reply.send(`Hello, ${req.user}`)
})

Since the above example mutates the request object after it has already been instantiated, the JavaScript engine must deoptimize access to the request object. By using the decoration API this deoptimization is avoided:

// Decorate request with a 'user' property
fastify.decorateRequest('user', '')

// Update our property
fastify.addHook('preHandler', (req, reply, done) => {
  req.user = 'Bob Dylan'
  done()
})
// And finally access it
fastify.get('/', (req, reply) => {
  reply.send(`Hello, ${req.user}!`)
})

Note that it is important to keep the initial shape of a decorated field as 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 thrown and error during the fastify startup. See decorateRequest.

See JavaScript engine fundamentals: Shapes and Inline Caches for more information on this topic.

Usage

decorate(name, value, [dependencies])

This method is used to customize the Fastify server instance.

For example, to attach a new method to the server instance:

fastify.decorate('utility', function () {
  // Something very useful
})

As mentioned above, non-function values can be attached to the server instance as:

fastify.decorate('conf', {
  db: 'some.db',
  port: 3000
})

To access decorated properties, use the name provided to the decoration API:

fastify.utility()

console.log(fastify.conf.db)

The decorated Fastify server is bound to this in route handlers:

fastify.decorate('db', new DbConnection())

fastify.get('/', async function (request, reply) {
  // using return
  return { hello: await this.db.query('world') }
  
  // or
  // using reply.send()
  reply.send({ hello: await this.db.query('world') })
  await reply
})

The dependencies parameter is an optional list of decorators that the decorator being defined relies upon. This list is simply a list of string names of other decorators. In the following example, the "utility" decorator depends upon "greet" and "hi" decorators:

async function greetDecorator (fastify, opts) {
  fastify.decorate('greet', () => {
    return 'greet message'
  })
}

async function hiDecorator (fastify, opts) {
  fastify.decorate('hi', () => {
    return 'hi message'
  })
}

async function utilityDecorator (fastify, opts) {
  fastify.decorate('utility', () => {
    return `${fastify.greet()} | ${fastify.hi()}`
  })
}

fastify.register(fastifyPlugin(greetDecorator, { name: 'greet' }))
fastify.register(fastifyPlugin(hiDecorator, { name: 'hi' }))
fastify.register(fastifyPlugin(utilityDecorator, { dependencies: ['greet', 'hi'] }))

fastify.get('/', function (req, reply) {
  // Response: {"hello":"greet message | hi message"}
  reply.send({ hello: fastify.utility() })
})

fastify.listen({ port: 3000 }, (err, address) => {
  if (err) throw err
})

Note: using an arrow function will break the binding of this to the FastifyInstance.

If a dependency is not satisfied, the decorate method will throw an exception. The dependency check is performed before the server instance is booted. Thus, it cannot occur during runtime.

decorateReply(name, value, [dependencies])

As the name suggests, this API is used to add new methods/properties to the core Reply object:

fastify.decorateReply('utility', function () {
  // Something very useful
})

Note: using an arrow function will break the binding of this to the Fastify Reply instance.

Note: using decorateReply will throw and error if used with a reference type:

// Don't do this
fastify.decorateReply('foo', { bar: 'fizz'})

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. Example:

const fp = require('fastify-plugin')

async function myPlugin (app) {
  app.decorateRequest('foo')
  app.addHook('onRequest', async (req, reply) => {
    req.foo = { bar: 42 }
  })
}

module.exports = fp(myPlugin)

See decorate for information about the dependencies parameter.

decorateRequest(name, value, [dependencies])

As above with decorateReply, this API is used add new methods/properties to the core Request object:

fastify.decorateRequest('utility', function () {
  // something very useful
})

Note: using an arrow function will break the binding of this to the Fastify Request instance.

Note: using decorateRequest will emit an error if used with a reference type:

// Don't do this
fastify.decorateRequest('foo', { bar: 'fizz'})

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.

Example:

const fp = require('fastify-plugin')

async function myPlugin (app) {
  app.decorateRequest('foo')
  app.addHook('onRequest', async (req, reply) => {
    req.foo = { bar: 42 }
  })
}

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:

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 for information about the dependencies parameter.

hasDecorator(name)

Used to check for the existence of a server instance decoration:

fastify.hasDecorator('utility')

hasRequestDecorator

Used to check for the existence of a Request decoration:

fastify.hasRequestDecorator('utility')

hasReplyDecorator

Used to check for the existence of a Reply decoration:

fastify.hasReplyDecorator('utility')

Decorators and Encapsulation

Defining a decorator (using decorate, decorateRequest, or decorateReply) with the same name more than once in the same encapsulated context will throw an exception.

As an example, the following will throw:

const server = require('fastify')()

server.decorateReply('view', function (template, args) {
  // Amazing view rendering engine
})

server.get('/', (req, reply) => {
  reply.view('/index.html', { hello: 'world' })
})

// Somewhere else in our codebase, we define another
// view decorator. This throws.
server.decorateReply('view', function (template, args) {
  // Another rendering engine
})

server.listen({ port: 3000 })

But this will not:

const server = require('fastify')()

server.decorateReply('view', function (template, args) {
  // Amazing view rendering engine.
})

server.register(async function (server, opts) {
  // We add a view decorator to the current encapsulated
  // plugin. This will not throw as outside of this encapsulated
  // plugin view is the old one, while inside it is the new one.
  server.decorateReply('view', function (template, args) {
    // Another rendering engine
  })

  server.get('/', (req, reply) => {
    reply.view('/index.page', { hello: 'world' })
  })
}, { prefix: '/bar' })

server.listen({ port: 3000 })

Getters and Setters

Decorators accept special "getter/setter" objects. These objects have functions named getter and setter (though the setter function is optional). This allows defining properties via decorators, for example:

fastify.decorate('foo', {
  getter () {
    return 'a getter'
  }
})

Will define the foo property on the Fastify instance:

console.log(fastify.foo) // 'a getter'