ما هي الـ decorators وكيف يتم استخدامها؟

Question

Accepted Answer

**decorator** هي إعلان خاص (`@name`) يضيف سلوكًا أو بيانات وصفية إلى class أو method أو property أو parameter. إنها دالة يستدعيها runtime مع الهدف المزخرف، مما يتيح لك التفاف أو إضافة تعليقات توضيحية بطريقة إعلانية.

```ts
// A simple method decorator that logs calls
function log(target: any, key: string, desc: PropertyDescriptor) {
  const original = desc.value;
  desc.value = function (...args: any[]) {     // wrap the original method
    console.log(`calling ${key} with`, args);
    return original.apply(this, args);
  };
}

class Service {
  @log
  fetch(id: number) { return { id }; }
}
new Service().fetch(1); // logs "calling fetch with [1]" then runs
```

تلقى الـ decorator وصف الـ method واستبدله بـ wrapper — سلوك cross-cutting (logging، caching، timing) دون لمس جسم الـ method.

## أين تراها في الأغلب: frameworks

```ts
@Controller("users")          // NestJS — declares a route controller
export class UsersController {
  @Get(":id")                 // maps GET /users/:id
  findOne(@Param("id") id: string) { return id; } // param decorator injects the route param
}

@Entity()                     // TypeORM — maps a class to a DB table
class User { @Column() name: string; }
```

NestJS و Angular و TypeORM و class-validator مبنية حول الـ decorators للـ DI و routing و ORM mapping و validation.

## نوعان (مهم)

```json
{ "experimentalDecorators": true, "emitDecoratorMetadata": true }
```

الـ **decorators الموروثة (التجريبية)** أعلاه هي ما تعتمد عليه Nest/Angular/TypeORM اليوم. هناك أيضًا الـ **TC39 Stage-3 decorators** الأحدث (TS 5+) بتوقيع مختلف، وهي المعيار المستقبلي — لكن معظم الأطر الموجودة لا تزال تستخدم النموذج الموروث.

## لماذا هذا مهم

تتيح الـ decorators للـ meta-programming نظيفة وإعلانية — الأساس الذي تعتمد عليه server frameworks و ORMs.

معرفة كل من الآلية (دالة تلف الهدف) والانقسام بين الموروثة والمعيار ضروري للعمل في نظام NestJS/Angular.