An ES2016 decorator is an expression which returns a function and can take a target, name and property descriptor as arguments. You apply it by prefixing the decorator with an
@character and placing this at the very top of what you are trying to decorate. Decorators can be defined for either a class, a method or a property.
Nest provides a set of useful param decorators that you can use together with the HTTP route handlers. Below is a list of the provided decorators and the plain Express (or Fastify) objects they represent
Additionally, you can create your own custom decorators. Why is this useful?
In the node.js world, it's common practice to attach properties to the request object. Then you manually extract them in each route handler, using code like the following:
In order to make your code more readable and transparent, you can create a
@User() decorator and reuse it across all of your controllers.
Then, you can simply use it wherever it fits your requirements.
When the behavior of your decorator depends on some conditions, you can use the
data parameter to pass an argument to the decorator's factory function. One use case for this is a custom decorator that extracts properties from the request object by key. Let's assume, for example, that our authentication layer validates requests and attaches a user entity to the request object. The user entity for an authenticated request might look like:
Let's define a decorator that takes a property name as key, and returns the associated value if it exists (or undefined if it doesn't exist, or if the
user object has not been created).
Here's how you could then access a particular property via the
@User() decorator in the controller:
You can use this same decorator with different keys to access different properties. If the
user object is deep or complex, this can make for easier and more readable request handler implementations.
info Hint For TypeScript users, note that
createParamDecorator<T>()is a generic. This means you can explicitly enforce type safety, for example
createParamDecorator<string>((data, ctx) => ...). Alternatively, specify a parameter type in the factory function, for example
createParamDecorator((data: string, ctx) => ...). If you omit both, the type for
Nest treats custom param decorators in the same fashion as the built-in ones (
@Query()). This means that pipes are executed for the custom annotated parameters as well (in our examples, the
user argument). Moreover, you can apply the pipe directly to the custom decorator:
info Hint Note that
validateCustomDecoratorsoption must be set to true.
ValidationPipedoes not validate arguments annotated with the custom decorators by default.
Nest provides a helper method to compose multiple decorators. For example, suppose you want to combine all decorators related to authentication into a single decorator. This could be done with the following construction:
You can then use this custom
@Auth() decorator as follows:
This has the effect of applying all four decorators with a single declaration.
warning Warning The
@ApiHideProperty()decorator from the
@nestjs/swaggerpackage is not composable and won't work properly with the