Topic

Decorators

Definition

A decorator is a function applied to a class, method, property, or parameter with an @ prefix that attaches metadata Nest reads at runtime to change how that target is treated.

In simpler words

Decorators are labels you stick on code — @Controller, @Get, @Injectable — that tell Nest what the labeled thing is for.

Nest is built almost entirely from decorator metadata: which class is a controller, which method handles which route, which parameter is public/role-gated. A Nest app commonly defines its own decorators for auth.

Open official example (opens in new tab)

After this you can

Classify a decorator as class-level, method-level, or parameter-level
Explain @Public(), @Roles(...), and @CurrentUser() and know what each attaches
Explain SetMetadata vs createParamDecorator
Predict what happens if a decorator is left off a route

Kinds of decorators Nest uses

Definition

Nest decorators attach metadata at the class level (@Controller, @Injectable, @Module), the method level (@Get, @Post, @Roles), or the parameter level (@Body, @Param, @CurrentUser), and Nest inspects that metadata when handling a request.

In simpler words

Class decorators say what the class is; method decorators say what a route does; parameter decorators say what to hand a method argument.

A class decorator like @Controller("tickets") or @Injectable() marks the whole class’s role in the DI/routing system.

A method decorator like @Get(":id") or @Roles("admin") attaches route or access metadata to one handler.

A parameter decorator like @Param("id") or @CurrentUser() tells Nest how to extract a value from the request and pass it as that argument.

All three kinds on one controller

@Controller('tickets')          // class decorator
export class TicketsController {
  @Delete(':id')                // method decorator
  @Roles('admin')               // method decorator (custom)
  remove(@Param('id') id: string) {  // parameter decorator
    return this.ticketsService.remove(id);
  }
}

Three decorator kinds, three different jobs, all metadata Nest reads before your method body runs.

Custom auth decorators

Definition

A custom decorator can be built from SetMetadata to attach arbitrary route metadata, or from createParamDecorator to compute and return a value from the current ExecutionContext.

In simpler words

@Public() and @Roles(...) just stick a metadata flag on a route; @CurrentUser() reaches into the request and hands back the logged-in user.

A common auth.decorators file defines Public = () => SetMetadata(IS_PUBLIC_KEY, true) and Roles = (...roles) => SetMetadata(ROLES_KEY, roles) — both are metadata flags that guards later read with a Reflector.

CurrentUser is built with createParamDecorator: it reads req.user (attached by the JWT strategy after a guard authenticates the request) and returns it directly as a typed User parameter.

Decorator definitions

export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);
export const Roles = (...roles: Array<'admin' | 'member'>) =>
  SetMetadata(ROLES_KEY, roles);

export const CurrentUser = createParamDecorator(
  (_data: unknown, ctx: ExecutionContext): User => {
    const request = ctx.switchToHttp().getRequest<{ user: User }>();
    return request.user;
  },
);

JwtAuthGuard/RolesGuard read IS_PUBLIC_KEY and ROLES_KEY with Reflector; CurrentUser just projects request.user.

Mistake: expecting @CurrentUser() on a public route

// Wrong — no guard ran, request.user was never set
@Public()
@Get('whoami')
me(@CurrentUser() user: User) { return user; } // undefined

// Right — protected route, guard populates request.user first
@Get('whoami')
me(@CurrentUser() user: User) { return user; }

@CurrentUser() only works after an auth guard has run and attached request.user — @Public() skips that guard.

Keep in mind

A decorator with no code reading its metadata does nothing — always check which guard/pipe/interceptor consumes it.
Prefer existing decorators (@Public, @Roles, @CurrentUser) over re-deriving auth state manually in a controller.
Order matters for stacked method decorators in some cases (e.g. guards run in registration order) — keep it consistent with existing controllers.

Test

Check your understanding

At least 10 questions — mix of concept, syntax, practical, and logic. Score ≥80% (enforced by the API) to save progress.

Checking your session…

15 questions · concept 5 · syntax 3 · practical 4 · logic 3

1. What do Nest decorators primarily do?

Concept

Execute request validation and authorization on their own at call timeTransform the decorated class into a plain JavaScript functionAttach metadata Nest reads for routing, DI, and request handlingGenerate a compiled route table that replaces the module system

2. What does @Public() do in this codebase?

Syntax

Removes JwtAuthGuard from the route so no guard runs at allSets metadata so JwtAuthGuard can allow unauthenticated accessMarks the route so Swagger hides it from the documented APIGrants every authenticated user access regardless of their role

3. What do @Roles(...) decorators do?

Practical

Check the current user role and throw 403 immediately on mismatchAttach required role metadata for RolesGuard to enforceAdd the listed roles to the user JWT when the handler respondsRegister the route only for users who already have those roles

4. Where can parameter decorators like @CurrentUser() apply?

Logic

On the controller class to inject the user into every handlerOn provider constructor parameters to inject the current userOn handler parameters to extract values from the request contextOn any parameter, including those in services and guards

5. Which decorator maps a GET route?

Concept

@Route("GET") on a controller method@Get() on the controller class to map all of its methods@Get() on a controller method@HttpGet() on a service method

6. Who actually rejects unauthorized requests?

Practical

The ValidationPipe, after it fails to validate the auth tokenAn exception filter that inspects the request before the handlerMiddleware that runs after the guards and checks the JWTGuards (e.g. JwtAuthGuard) reading metadata and the request

7. What is SetMetadata used for?

Syntax

Reading previously stored metadata back inside a guardAttaching validation rules that pipes enforce on DTOsRegistering global metadata shared across every module automaticallyStoring custom keys like roles/public for Reflector consumers

8. Which claim about @Roles execution is most accurate?

Logic

It compares request.user.role and leaves only the 403 response to the guardIt records metadata; it does not by itself compare request.user.roleIt reads the JWT to determine the user role before the guard runsIt runs after the guard to double-check the role decision

9. What does @Body() do?

Concept

Tells Nest to pass the request body into that parameter (then pipes may validate)Parses and validates the request body itself before the handler runsMerges the request body and query string into one parameterPasses the raw request stream so the handler can parse it manually

10. Why combine decorators with Reflector in guards?

Practical

Reflector attaches the metadata that decorators later read at runtimeReflector converts decorator metadata into DTO validation rulesGuards use Reflector to inject the providers the decorators requestedGuards read handler/class metadata to decide allow/deny

11. What does applying @Public() to this route actually do?

Conceptintermediate

export const Public = () => SetMetadata('isPublic', true);

@Public()
@Get('health')
health() { return { ok: true }; }

It immediately disables the global guard for that route at decoration timeIt only attaches isPublic metadata; a guard must read it via Reflector to skip authIt removes the route from Swagger so unauthenticated users cannot find itIt sets isPublic on the request object for the handler to check

12. What will user be inside this handler?

Syntaxadvanced

export const CurrentUser = createParamDecorator(
  (_data, ctx: ExecutionContext) =>
    ctx.switchToHttp().getRequest().user,
);

@Get('me')
me(@CurrentUser() user: User) { return user; }

The raw JWT string from the cookie headerThe request.user object attached earlier by the auth guard/strategyA new User entity fetched from Postgres by the decoratorundefined, because param decorators cannot read the request

13. What does @Roles by itself do here?

Practicalintermediate

@Roles('admin')
@Delete(':id')
remove() {}

Immediately returns 403 for non-admins when the route is hitFilters the response so non-admin fields are stripped outAttaches required-role metadata; a RolesGuard must enforce itRegisters the route only for requests whose JWT already lists admin

14. What is the relationship between these decorators?

Logicadvanced

@UseGuards(RolesGuard)
@Roles('admin')
@Get()
list() {}

The RolesGuard runs before @Roles sets its metadata, so it always denies@Roles stores metadata that @UseGuards(RolesGuard) reads to allow or denyThe order of the two decorators changes which HTTP method is mapped@Roles only works if RolesGuard is registered globally, not per-route

15. What does @Body() do here?

Conceptintermediate

@Post()
create(@Body() dto: CreateTicketDto) {}

Validates the body against CreateTicketDto before any pipe runsBinds the parsed request body to dto, which pipes may then validateBinds the body but skips the global ValidationPipe for this parameterReads the request body and the route params into one object

Checking your session…