Kif toħloq decorators custom?

Question

Accepted Answer

NestJS jilok toħloq **decorators custom** biex tinkapsola loġika riusabbli — l-aktar komuni **parameter decorators** (biex testrattĎ data mir-rikiresta) u **metadata decorators** (biex twaħħal data miqdija minn guards/interceptors). Iḥallu l-kodiċi DRY u espressiv.

## Custom parameter decorator — estrattĎ data mir-rikiresta

```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` jibni parameter decorator: il-funzjoni tiegħu tirċievi l-`ExecutionContext`, testrattĎ data, u tirritorna l-valur biex tinjetta. Dan jibdel ir-ripetizzjoni `@Req() req` + `req.user` bi decorator nadif u riusabbli `@CurrentUser()`.

## Parameter decorator b'argumenti

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

## Custom metadata decorator (għal guards/interceptors biex jaqraw)

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

L-kombinazzjoni `@Roles()` + `RolesGuard` — metadata decorator li guard jaqra permezz ta' `Reflector` — hija l-patruni kanonika għall-awtorizzazzjoni bbazata fuq ir-rwoli.

## Kompożizzjoni ta' decorators

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

## Għaliex hija importanti

Il-ħolqien ta' decorators custom hija teknika importanti ta' NestJS biex iḥallu l-kodiċi DRY, espressiv, u manutenibbli. **Custom parameter decorators** (`createParamDecorator`) jilok tinkapsola estrazzjoni komuni ta' data mir-rikiresta (bħal `@CurrentUser()`) f'annotazzjonijiet nadfa u riusabbli — ħafna aħjar milli tirrepeti `@Req() req` u tnuggar fl-oġġett ir-rikiresta f'kull handler. **Custom metadata decorators** (`SetMetadata`) huma l-fondazzjoni tal-patruni ta' awtorizzazzjoni ta' NestJS: l-approċċ standard `@Roles()` + `RolesGuard` (maqrija permezz ta' `Reflector`) għall-kontroll ta' aċċess ibbażat fuq ir-rwoli jiddependi kompletament fuq il-fehim tal-metadata decorators.

U **kompożizzjoni ta' decorators** (`applyDecorators`) jilok tgħaqqad decorators relatati (eż. `@Auth()` li tapplika guards u metadata flimkien) għal applikazzjoni konsiza u konsistenti.
",