docs: add docs on new create decorator method

content/fundamentals/execution-context.md

@@ -124,64 +124,46 @@ const methodKey = ctx.getHandler().name; // "create"
 const className = ctx.getClass().name; // "CatsController"
 ```
 
-The ability to access references to both the current class and handler method provides great flexibility. Most importantly, it gives us the opportunity to access the metadata set through the `@SetMetadata()` decorator from within guards or interceptors. We cover this use case below.
+The ability to access references to both the current class and handler method provides great flexibility. Most importantly, it gives us the opportunity to access the metadata set through either decorators created via `Reflector#createDecorator` or the built-in `@SetMetadata()` decorator from within guards or interceptors. We cover this use case below.
 
 <app-banner-enterprise></app-banner-enterprise>
 
 #### Reflection and metadata
 
-Nest provides the ability to attach **custom metadata** to route handlers through the `@SetMetadata()` decorator. We can then access this metadata from within our class to make certain decisions.
+Nest provides the ability to attach **custom metadata** to route handlers through decorators created via `Reflector#createDecorator` method, and the built-in `@SetMetadata()` decorator. In this section, let's compare the two approaches and see how to access the metadata from within a guard or interceptor.
 
-```typescript
-@@filename(cats.controller)
-@Post()
-@SetMetadata('roles', ['admin'])
-async create(@Body() createCatDto: CreateCatDto) {
-  this.catsService.create(createCatDto);
-}
-@@switch
-@Post()
-@SetMetadata('roles', ['admin'])
-@Bind(Body())
-async create(createCatDto) {
-  this.catsService.create(createCatDto);
-}
-```
-
-> info **Hint** The `@SetMetadata()` decorator is imported from the `@nestjs/common` package.
-
-With the construction above, we attached the `roles` metadata (`roles` is a metadata key and `['admin']` is the associated value) to the `create()` method. While this works, it's not good practice to use `@SetMetadata()` directly in your routes. Instead, create your own decorators, as shown below:
+To create strongly-typed decorators using `Reflector#createDecorator`, we need to specify the type argument. For example, let's create a `Roles` decorator that takes an array of strings as an argument.
 
-```typescript
+```ts
 @@filename(roles.decorator)
-import { SetMetadata } from '@nestjs/common';
-
-export const Roles = (...roles: string[]) => SetMetadata('roles', roles);
-@@switch
-import { SetMetadata } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
 
-export const Roles = (...roles) => SetMetadata('roles', roles);
+export const Roles = Reflector.createDecorator<string[]>();
 ```
 
-This approach is much cleaner and more readable, and is strongly typed. Now that we have a custom `@Roles()` decorator, we can use it to decorate the `create()` method.
+The `Roles` decorator here is a function that takes a single argument of type `string[]`.
+
+Now, to use this decorator, we simply annotate the handler with it:
 
 ```typescript
 @@filename(cats.controller)
 @Post()
-@Roles('admin')
+@Roles(['admin'])
 async create(@Body() createCatDto: CreateCatDto) {
   this.catsService.create(createCatDto);
 }
 @@switch
 @Post()
-@Roles('admin')
+@Roles(['admin'])
 @Bind(Body())
 async create(createCatDto) {
   this.catsService.create(createCatDto);
 }
 ```
 
-To access the route's role(s) (custom metadata), we'll use the `Reflector` helper class, which is provided out of the box by the framework and exposed from the `@nestjs/core` package. `Reflector` can be injected into a class in the normal way:
+Here we've attached the `Roles` decorator metadata to the `create()` method, indicating that only users with the `admin` role should be allowed to access this route.
+
+To access the route's role(s) (custom metadata), we'll use the `Reflector` helper class again. `Reflector` can be injected into a class in the normal way:
 
 ```typescript
 @@filename(roles.guard)
@@ -201,23 +183,23 @@ export class CatsService {
 
 > info **Hint** The `Reflector` class is imported from the `@nestjs/core` package.
 
-Now, to read the handler metadata, use the `get()` method.
+Now, to read the handler metadata, use the `get()` method:
 
 ```typescript
-const roles = this.reflector.get<string[]>('roles', context.getHandler());
+const roles = this.reflector.get(Roles, context.getHandler());
 ```
 
-The `Reflector#get` method allows us to easily access the metadata by passing in two arguments: a metadata **key** and a **context** (decorator target) to retrieve the metadata from. In this example, the specified **key** is `'roles'` (refer back to the `roles.decorator.ts` file above and the `SetMetadata()` call made there). The context is provided by the call to `context.getHandler()`, which results in extracting the metadata for the currently processed route handler. Remember, `getHandler()` gives us a **reference** to the route handler function.
+The `Reflector#get` method allows us to easily access the metadata by passing in two arguments: a decorator reference and a **context** (decorator target) to retrieve the metadata from. In this example, the specified **decorator** is `Roles` (refer back to the `roles.decorator.ts` file above). The context is provided by the call to `context.getHandler()`, which results in extracting the metadata for the currently processed route handler. Remember, `getHandler()` gives us a **reference** to the route handler function.
 
 Alternatively, we may organize our controller by applying metadata at the controller level, applying to all routes in the controller class.
 
 ```typescript
 @@filename(cats.controller)
-@Roles('admin')
+@Roles(['admin'])
 @Controller('cats')
 export class CatsController {}
 @@switch
-@Roles('admin')
+@Roles(['admin'])
 @Controller('cats')
 export class CatsController {}
 ```
@@ -226,32 +208,30 @@ In this case, to extract controller metadata, we pass `context.getClass()` as th
 
 ```typescript
 @@filename(roles.guard)
-const roles = this.reflector.get<string[]>('roles', context.getClass());
-@@switch
-const roles = this.reflector.get('roles', context.getClass());
+const roles = this.reflector.get(Roles, context.getClass());
 ```
 
 Given the ability to provide metadata at multiple levels, you may need to extract and merge metadata from several contexts. The `Reflector` class provides two utility methods used to help with this. These methods extract **both** controller and method metadata at once, and combine them in different ways.
 
-Consider the following scenario, where you've supplied `'roles'` metadata at both levels.
+Consider the following scenario, where you've supplied `Roles` metadata at both levels.
 
 ```typescript
 @@filename(cats.controller)
-@Roles('user')
+@Roles(['user'])
 @Controller('cats')
 export class CatsController {
   @Post()
-  @Roles('admin')
+  @Roles(['admin'])
   async create(@Body() createCatDto: CreateCatDto) {
     this.catsService.create(createCatDto);
   }
 }
 @@switch
-@Roles('user')
+@Roles(['user'])
 @Controller('cats')
 export class CatsController {}
   @Post()
-  @Roles('admin')
+  @Roles(['admin'])
   @Bind(Body())
   async create(createCatDto) {
     this.catsService.create(createCatDto);
@@ -262,23 +242,100 @@ export class CatsController {}
 If your intent is to specify `'user'` as the default role, and override it selectively for certain methods, you would probably use the `getAllAndOverride()` method.
 
 ```typescript
-const roles = this.reflector.getAllAndOverride<string[]>('roles', [
-  context.getHandler(),
-  context.getClass(),
-]);
+const roles = this.reflector.getAllAndOverride(Roles, [context.getHandler(), context.getClass()]);
 ```
 
 A guard with this code, running in the context of the `create()` method, with the above metadata, would result in `roles` containing `['admin']`.
 
 To get metadata for both and merge it (this method merges both arrays and objects), use the `getAllAndMerge()` method:
 
 ```typescript
-const roles = this.reflector.getAllAndMerge<string[]>('roles', [
-  context.getHandler(),
-  context.getClass(),
-]);
+const roles = this.reflector.getAllAndMerge(Roles, [context.getHandler(), context.getClass()]);
 ```
 
 This would result in `roles` containing `['user', 'admin']`.
 
 For both of these merge methods, you pass the metadata key as the first argument, and an array of metadata target contexts (i.e., calls to the `getHandler()` and/or `getClass())` methods) as the second argument.
+
+#### Low-level approach
+
+As mentioned earlier, instead of using `Reflector#createDecorator`, you can also use the built-in `@SetMetadata()` decorator to attach metadata to a handler.
+
+```typescript
+@@filename(cats.controller)
+@Post()
+@SetMetadata('roles', ['admin'])
+async create(@Body() createCatDto: CreateCatDto) {
+  this.catsService.create(createCatDto);
+}
+@@switch
+@Post()
+@SetMetadata('roles', ['admin'])
+@Bind(Body())
+async create(createCatDto) {
+  this.catsService.create(createCatDto);
+}
+```
+
+> info **Hint** The `@SetMetadata()` decorator is imported from the `@nestjs/common` package.
+
+With the construction above, we attached the `roles` metadata (`roles` is a metadata key and `['admin']` is the associated value) to the `create()` method. While this works, it's not good practice to use `@SetMetadata()` directly in your routes. Instead, you can create your own decorators, as shown below:
+
+```typescript
+@@filename(roles.decorator)
+import { SetMetadata } from '@nestjs/common';
+
+export const Roles = (...roles: string[]) => SetMetadata('roles', roles);
+@@switch
+import { SetMetadata } from '@nestjs/common';
+
+export const Roles = (...roles) => SetMetadata('roles', roles);
+```
+
+This approach is much cleaner and more readable, and somewhat resembles the `Reflector#createDecorator` approach. The difference is that with `@SetMetadata` you have more control over the metadata key and value, and also can create decorators that take more than one argument.
+
+Now that we have a custom `@Roles()` decorator, we can use it to decorate the `create()` method.
+
+```typescript
+@@filename(cats.controller)
+@Post()
+@Roles('admin')
+async create(@Body() createCatDto: CreateCatDto) {
+  this.catsService.create(createCatDto);
+}
+@@switch
+@Post()
+@Roles('admin')
+@Bind(Body())
+async create(createCatDto) {
+  this.catsService.create(createCatDto);
+}
+```
+
+To access the route's role(s) (custom metadata), we'll use the `Reflector` helper class again:
+
+```typescript
+@@filename(roles.guard)
+@Injectable()
+export class RolesGuard {
+  constructor(private reflector: Reflector) {}
+}
+@@switch
+@Injectable()
+@Dependencies(Reflector)
+export class CatsService {
+  constructor(reflector) {
+    this.reflector = reflector;
+  }
+}
+```
+
+> info **Hint** The `Reflector` class is imported from the `@nestjs/core` package.
+
+Now, to read the handler metadata, use the `get()` method.
+
+```typescript
+const roles = this.reflector.get<string[]>('roles', context.getHandler());
+```
+
+Here instead of passing a decorator reference, we pass the metadata **key** as the first argument (which in our case is `'roles'`). Everything else remains the same as in the `Reflector#createDecorator` example.

content/guards.md

@@ -146,72 +146,57 @@ export class AppModule {}
 
 Our `RolesGuard` is working, but it's not very smart yet. We're not yet taking advantage of the most important guard feature - the [execution context](/fundamentals/execution-context). It doesn't yet know about roles, or which roles are allowed for each handler. The `CatsController`, for example, could have different permission schemes for different routes. Some might be available only for an admin user, and others could be open for everyone. How can we match roles to routes in a flexible and reusable way?
 
-This is where **custom metadata** comes into play (learn more [here](https://docs.nestjs.com/fundamentals/execution-context#reflection-and-metadata)). Nest provides the ability to attach custom **metadata** to route handlers through the `@SetMetadata()` decorator. This metadata supplies our missing `role` data, which a smart guard needs to make decisions. Let's take a look at using `@SetMetadata()`:
+This is where **custom metadata** comes into play (learn more [here](https://docs.nestjs.com/fundamentals/execution-context#reflection-and-metadata)). Nest provides the ability to attach custom **metadata** to route handlers through either decorators created via `Reflector#createDecorator` static method, or the built-in `@SetMetadata()` decorator.
 
-```typescript
-@@filename(cats.controller)
-@Post()
-@SetMetadata('roles', ['admin'])
-async create(@Body() createCatDto: CreateCatDto) {
-  this.catsService.create(createCatDto);
-}
-@@switch
-@Post()
-@SetMetadata('roles', ['admin'])
-@Bind(Body())
-async create(createCatDto) {
-  this.catsService.create(createCatDto);
-}
-```
-
-> info **Hint** The `@SetMetadata()` decorator is imported from the `@nestjs/common` package.
+For example, let's create a `@Roles()` decorator using the `Reflector#createDecorator` method that will attach the metadata to the handler. `Reflector` is provided out of the box by the framework and exposed from the `@nestjs/core` package.
 
-With the construction above, we attached the `roles` metadata (`roles` is a key, while `['admin']` is a particular value) to the `create()` method. While this works, it's not good practice to use `@SetMetadata()` directly in your routes. Instead, create your own decorators, as shown below:
-
-```typescript
+```ts
 @@filename(roles.decorator)
-import { SetMetadata } from '@nestjs/common';
-
-export const Roles = (...roles: string[]) => SetMetadata('roles', roles);
-@@switch
-import { SetMetadata } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
 
-export const Roles = (...roles) => SetMetadata('roles', roles);
+export const Roles = Reflector.createDecorator<string[]>();
 ```
 
-This approach is much cleaner and more readable, and is strongly typed. Now that we have a custom `@Roles()` decorator, we can use it to decorate the `create()` method.
+The `Roles` decorator here is a function that takes a single argument of type `string[]`.
+
+Now, to use this decorator, we simply annotate the handler with it:
 
 ```typescript
 @@filename(cats.controller)
 @Post()
-@Roles('admin')
+@Roles(['admin'])
 async create(@Body() createCatDto: CreateCatDto) {
   this.catsService.create(createCatDto);
 }
 @@switch
 @Post()
-@Roles('admin')
+@Roles(['admin'])
 @Bind(Body())
 async create(createCatDto) {
   this.catsService.create(createCatDto);
 }
 ```
 
+Here we've attached the `Roles` decorator metadata to the `create()` method, indicating that only users with the `admin` role should be allowed to access this route.
+
+Alernatively, instead of using the `Reflector#createDecorator` method, we could use the built-in `@SetMetadata()` decorator. Learn more about [here](/fundamentals/execution-context#low-level-approach).
+
 #### Putting it all together
 
-Let's now go back and tie this together with our `RolesGuard`. Currently, it simply returns `true` in all cases, allowing every request to proceed. We want to make the return value conditional based on the comparing the **roles assigned to the current user** to the actual roles required by the current route being processed. In order to access the route's role(s) (custom metadata), we'll use the `Reflector` helper class, which is provided out of the box by the framework and exposed from the `@nestjs/core` package.
+Let's now go back and tie this together with our `RolesGuard`. Currently, it simply returns `true` in all cases, allowing every request to proceed. We want to make the return value conditional based on the comparing the **roles assigned to the current user** to the actual roles required by the current route being processed. In order to access the route's role(s) (custom metadata), we'll use the `Reflector` helper class again, as follows:
 
 ```typescript
 @@filename(roles.guard)
 import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
 import { Reflector } from '@nestjs/core';
+import { Roles } from './roles.decorator';
 
 @Injectable()
 export class RolesGuard implements CanActivate {
   constructor(private reflector: Reflector) {}
 
   canActivate(context: ExecutionContext): boolean {
-    const roles = this.reflector.get<string[]>('roles', context.getHandler());
+    const roles = this.reflector.get(Roles, context.getHandler());
     if (!roles) {
       return true;
     }
@@ -223,6 +208,7 @@ export class RolesGuard implements CanActivate {
 @@switch
 import { Injectable, Dependencies } from '@nestjs/common';
 import { Reflector } from '@nestjs/core';
+import { Roles } from './roles.decorator';
 
 @Injectable()
 @Dependencies(Reflector)
@@ -232,7 +218,7 @@ export class RolesGuard {
   }
 
   canActivate(context) {
-    const roles = this.reflector.get('roles', context.getHandler());
+    const roles = this.reflector.get(Roles, context.getHandler());
     if (!roles) {
       return true;
     }