Cum creezi decoratori personalizați?

Question

Accepted Answer

NestJS te lasă să creezi **decoratori personalizați** pentru a încapsula logica reutilizabilă — cel mai frecvent **decoratori de parametri** (pentru a extrage date din cerere) și **decoratori de metadate** (pentru a atașa date citite de garduri/interceptori). Ei țin codul DRY și expresiv.

## Decorator de parametru personalizat — extrage date din cerere

```ts
import { createParamDecorator, ExecutionContext } from "@nestjs/common";

// extract the authenticated user (attached to the request by an auth guard)
export const CurrentUser = createParamDecorator(
  (data: unknown, ctx: ExecutionContext) => {
    const request = ctx.switchToHttp().getRequest();
    return request.user;        // return whatever you want injected
  },
);

// usage — clean and readable
@Get("profile")
getProfile(@CurrentUser() user: User) {     // instead of @Req() req and req.user
  return user;
}
```

`createParamDecorator` construiește un decorator de parametru: funcția sa primește `ExecutionContext`, extrage date și returnează valoarea care trebuie injectată. Aceasta înlocuiește accesul repetitiv `@Req() req` + `req.user` cu un `@CurrentUser()` curat și reutilizabil.

## Decorator de parametru cu argumente

```ts
// extract a specific property: @CurrentUser("email")
export const CurrentUser = createParamDecorator(
  (data: string, ctx: ExecutionContext) => {
    const user = ctx.switchToHttp().getRequest().user;
    return data ? user?.[data] : user;   // `data` is the argument passed to the decorator
  },
);
// @CurrentUser("email") email: string  → injects just user.email
```

## Decorator de metadate personalizat (pentru garduri/interceptori care să-l citească)

```ts
import { SetMetadata } from "@nestjs/common";

// a @Roles() decorator that ATTACHES metadata to a route
export const Roles = (...roles: string[]) => SetMetadata("roles", roles);

// usage
@Roles("admin", "editor")
@Get("users")
listUsers() {}
```

```ts
// a guard reads the metadata via Reflector
@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}
  canActivate(ctx: ExecutionContext): boolean {
    const roles = this.reflector.get<string[]>("roles", ctx.getHandler());   // read it
    const { user } = ctx.switchToHttp().getRequest();
    return !roles || roles.some(r => user.roles?.includes(r));
  }
}
```

Combinația `@Roles()` + `RolesGuard` — un decorator de metadate pe care o gardă îl citește prin `Reflector` — este modelul canonic pentru autorizare pe bază de roluri.

## Compunerea decoratorilor

```ts
import { applyDecorators } from "@nestjs/common";
// bundle multiple decorators into one reusable decorator
export function Auth(...roles: string[]) {
  return applyDecorators(SetMetadata("roles", roles), UseGuards(AuthGuard, RolesGuard));
}
// usage: @Auth("admin")  — applies metadata + guards in one decorator
```

## De ce contează

Crearea decoratorilor personalizați este o tehnică importantă în NestJS pentru a păstra codul DRY, expresiv și ușor de întreținut. **Decoratorii de parametri personalizați** (`createParamDecorator`) te lasă să încapsulezi extragerea comună de date din cerere (cum ar fi `@CurrentUser()`) în adnotări curate și reutilizabile — mult mai bine decât a repeta `@Req() req` și a săpa în obiectul cererii în fiecare handler. **Decoratorii de metadate personalizați** (`SetMetadata`) sunt fundamentul modelelor de autorizare ale NestJS: abordarea standard `@Roles()` + `RolesGuard` (citită prin `Reflector`) pentru controlul accesului pe bază de roluri depinde în totalitate de înțelegerea decoratorilor de metadate.

Și **compunerea decoratorilor** (`applyDecorators`) te lasă să consolidezi decoratori înrudiți (de ex. un `@Auth()` care aplică garduri și metadate împreună) pentru o aplicare concisă și consistentă.

Înțelegerea modului în care să creezi acestea este ceea ce te lasă să construiești API-uri NestJS expresive și idiomatice și să implementezi modele comune (injectare utilizatorului curent, RBAC) în modul intenționat de framework.

Te ridică de la simpla utilizare a decoratorilor încorporați la extinderea stilului declarativ al framework-ului pentru nevoile aplicației tale — o abilitate valoroasă și frecvent aplicată în proiectele reale cu NestJS.