¿Cómo crear decoradores personalizados?

Question

Accepted Answer

NestJS te permite crear **decoradores personalizados** para encapsular lógica reutilizable — más comúnmente **decoradores de parámetros** (para extraer datos de la solicitud) y **decoradores de metadatos** (para adjuntar datos leídos por guards/interceptores). Mantienen el código DRY y expresivo.

## Decorador de parámetro personalizado — extraer datos de la solicitud

```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` construye un decorador de parámetro: su función recibe el `ExecutionContext`, extrae datos y devuelve el valor a inyectar. Esto reemplaza el acceso repetitivo a `@Req() req` + `req.user` con un `@CurrentUser()` limpio y reutilizable.

## Decorador de parámetro con argumentos

```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
```

## Decorador de metadatos personalizado (para que guards/interceptores lo lean)

```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));
  }
}
```

La combinación `@Roles()` + `RolesGuard` — un decorador de metadatos que un guard lee a través de `Reflector` — es el patrón canónico para autorización basada en roles.

## Composición de decoradores

```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
```

## Por qué es importante

Crear decoradores personalizados es una técnica importante en NestJS para mantener el código DRY, expresivo y mantenible. Los **decoradores de parámetro personalizados** (`createParamDecorator`) te permiten encapsular la extracción común de datos de solicitud (como `@CurrentUser()`) en anotaciones limpias y reutilizables — mucho mejor que repetir `@Req() req` e indagar en el objeto de solicitud en cada manejador. Los **decoradores de metadatos personalizados** (`SetMetadata`) son la base de los patrones de autorización de NestJS: el enfoque estándar `@Roles()` + `RolesGuard` (leído a través de `Reflector`) para control de acceso basado en roles depende completamente de entender decoradores de metadatos.

Y la **composición de decoradores** (`applyDecorators`) te permite agrupar decoradores relacionados (por ejemplo, un `@Auth()` que aplica guards y metadatos juntos) para una aplicación concisa y consistente.

Entender cómo crear estos es lo que te permite construir APIs NestJS expresivas e idiomáticas e implementar patrones comunes (inyección de usuario actual, RBAC) de la manera que el framework intenta — una habilidad valiosa y frecuentemente aplicada en proyectos NestJS reales.

Te eleva de simplemente usar decoradores integrados a extender el estilo declarativo del framework para las necesidades de tu propia aplicación — una habilidad valiosa y frecuentemente aplicada en proyectos NestJS reales.