Jak vytvoříte vlastní dekorátory?

Question

Accepted Answer

NestJS vám umožňuje vytvářet **vlastní dekorátory** pro zapouzdření znovupoužitelné logiky — nejčastěji **parametrické dekorátory** (k extrakci dat z požadavku) a **metadatové dekorátory** (k připojení dat, která čtou guards/interceptory). Udržují kód DRY a výrazný.

## Vlastní parametrický dekorátor — extrakce dat z požadavku

```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` vytváří parametrický dekorátor: jeho funkce obdrží `ExecutionContext`, extrahuje data a vrátí hodnotu k injektáži. To nahrazuje opakující se `@Req() req` + `req.user` přístup čistým, znovupoužitelným `@CurrentUser()`.

## Parametrický dekorátor s argumenty

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

## Vlastní metadatový dekorátor (pro guards/interceptory k přečtení)

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

Kombinace `@Roles()` + `RolesGuard` — metadatový dekorátor, který guard čte přes `Reflector` — je kanonickým vzorem pro autorizaci na základě rolí.

## Skládání dekorátorů

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

## Proč je to důležité

Vytváření vlastních dekorátorů je důležitou technikou NestJS pro udržení kódu DRY, výrazného a udržovatelného. **Vlastní parametrické dekorátory** (`createParamDecorator`) vám umožňují zapouzdřit běžnou extrakci dat z požadavku (jako `@CurrentUser()`) do čistých, znovupoužitelných anotací — daleko lépe než opakování `@Req() req` a kopírování v požadavku v každém handleru. **Vlastní metadatové dekorátory** (`SetMetadata`) jsou základem autorizačních vzorů NestJS: standardní přístup `@Roles()` + `RolesGuard` (čtený přes `Reflector`) pro řízení přístupu na základě rolí zcela závisí na porozumění metadatovým dekorátorům.

A **skládání dekorátorů** (`applyDecorators`) vám umožňuje spojit související dekorátory (např. `@Auth()`, který aplikuje guards a metadata dohromady) pro stručnou, konzistentní aplikaci.

Porozumění tomu, jak je vytvořit, vám umožňuje stavět výrazná, idiomatická NestJS API a implementovat běžné vzory (current-user injection, RBAC) způsobem zamýšleným frameworkem.

Elevuje vás z pouhého používání vestavěných dekorátorů na rozšíření deklarativního stylu frameworku pro potřeby vaší vlastní aplikace — cenná, často uplatňovaná dovednost v reálných NestJS projektech.