Unaundaje custom decorators?

Question

Accepted Answer

NestJS hukuruhusu kuunda **custom decorators** kufunika logic inayoweza kutumika tena — mara nyingi **parameter decorators** (kutoa data kutoka kwa request) na **metadata decorators** (kuambatanisha data inayosomwa na guards/interceptors). Huweka code ikiwa DRY na yenye uwazi.

## Custom parameter decorator — toa data ya request

```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` huunda parameter decorator: function yake hupokea `ExecutionContext`, hutoa data, na hurudisha thamani ya kuingiza. Hii hubadilisha ufikiaji wa kurudiarudia wa `@Req() req` + `req.user` kwa `@CurrentUser()` safi, inayoweza kutumika tena.

## Parameter decorator yenye arguments

```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 (kwa guards/interceptors kuisoma)

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

Mchanganyiko wa `@Roles()` + `RolesGuard` — metadata decorator ambayo guard huisoma kupitia `Reflector` — ndio muundo wa kawaida wa role-based authorization.

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

## Kwa nini ni muhimu

Kuunda custom decorators ni mbinu muhimu ya NestJS ya kuweka code ikiwa DRY, yenye uwazi, na inayoweza kudumishwa. **Custom parameter decorators** (`createParamDecorator`) zinakuruhusu kufunika utoaji wa kawaida wa data ya request (kama `@CurrentUser()`) katika annotations safi, zinazoweza kutumika tena — bora zaidi kuliko kurudia `@Req() req` na kuchimba ndani ya request object katika kila handler. **Custom metadata decorators** (`SetMetadata`) ndizo msingi wa miundo ya authorization ya NestJS: njia ya kawaida ya `@Roles()` + `RolesGuard` (inayosomwa kupitia `Reflector`) kwa role-based access control inategemea kabisa kuelewa metadata decorators.

Na **kuunganisha decorators** (`applyDecorators`) kunakuruhusu kufunga decorators zinazohusiana (mfano `@Auth()` inayotumia guards na metadata pamoja) kwa utumiaji mfupi na thabiti.

Kuelewa jinsi ya kuunda hizi ndio kinachokuwezesha kujenga API za NestJS zenye uwazi, za kawaida na kutekeleza miundo ya kawaida (kuingiza current-user, RBAC) kwa njia iliyokusudiwa na framework.

Kunakuinua kutoka kwa kutumia tu built-in decorators hadi kupanua mtindo wa kutangaza wa framework kwa mahitaji ya programu yako mwenyewe — ujuzi wenye thamani, unaotumika mara kwa mara katika miradi halisi ya NestJS.