Jak tworzyć niestandardowe dekoratory?

Question

Accepted Answer

NestJS pozwala na tworzenie **niestandardowych dekoratorów** do enkapsulacji logiki wielokrotnego użytku — najczęściej **dekoratorów parametrów** (do ekstrakcji danych z żądania) i **dekoratorów metadanych** (do dołączania danych odczytywanych przez guardy/interceptory). Utrzymują kod suchy i ekspresyjny.

## Niestandardowy dekorator parametru — ekstrakcja danych żądania

```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` buduje dekorator parametru: jego funkcja otrzymuje `ExecutionContext`, ekstraktuje dane i zwraca wartość do wstrzyknięcia. Zastępuje to powtarzające się `@Req() req` + `req.user` dostęp czystym, wielokrotnego użytku `@CurrentUser()`.

## Dekorator parametru z argumentami

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

## Niestandardowy dekorator metadanych (do odczytania przez guardy/interceptory)

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

Kombinacja `@Roles()` + `RolesGuard` — dekorator metadanych który guard odczytuje przez `Reflector` — to kanoniczny wzorzec do autoryzacji opartej na rolach.

## Komponowanie dekoratorów

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

## Dlaczego to ważne

Tworzenie niestandardowych dekoratorów jest ważną techniką NestJS do utrzymywania kodu suchego, ekspresyjnego i łatwo utrzymywanego. **Niestandardowe dekoratory parametrów** (`createParamDecorator`) pozwalają na enkapsulację typowej ekstrakcji danych żądania (jak `@CurrentUser()`) w czystych, wielokrotnego użytku adnotacjach — znacznie lepiej niż powtarzanie `@Req() req` i kopanie się w obiekcie żądania w każdym handlerze. **Niestandardowe dekoratory metadanych** (`SetMetadata`) są fundamentem wzorców autoryzacji NestJS: standardowe podejście `@Roles()` + `RolesGuard` (odczytywane przez `Reflector`) do kontroli dostępu opartej na rolach zależy całkowicie od zrozumienia dekoratorów metadanych.

I **komponowanie dekoratorów** (`applyDecorators`) pozwala na bundlowanie powiązanych dekoratorów (np. `@Auth()` który stosuje guardy i metadane razem) do zwięzłego, spójnego zastosowania.

Zrozumienie jak je tworzyć to to co pozwala na budowanie ekspresyjnych, idiomatycznych API NestJS i implementowanie typowych wzorców (wstrzyknięcie bieżącego użytkownika, RBAC) w zamierzony przez framework sposób.

Podnosi Cię od samego używania wbudowanych dekoratorów do rozszerzania deklaratywnego stylu framework'u dla potrzeb Twojej aplikacji — cenna, często stosowana umiejętność w rzeczywistych projektach NestJS.