الـ Decorators في TypeScript: للتوابع والأصناف والحقول

الـ decorator دالة تربطها بصنف أو بعضو في صنف بصيغة @name. تستقبل التابع الأصلي (أو الصنف، أو الحقل) مع كائن سياق يصفه، ويمكنها إعادة بديل. تدعم TypeScript الـ decorators القياسية دون أي خيار في المترجم.

function logged<This, Args extends unknown[], Return>(
    method: (this: This, ...args: Args) => Return,
    context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,
) {
    const name = String(context.name);
    return function (this: This, ...args: Args): Return {
        console.log(`-> ${name}(${args.join(", ")})`);
        const result = method.call(this, ...args);
        console.log(`<- ${name} = ${result}`);
        return result;
    };
}

class Calculator {
    @logged
    add(a: number, b: number): number {
        return a + b;
    }
}

new Calculator().add(2, 3);
// -> add(2, 3)
// <- add = 5

يعمل @logged مرة واحدة عند تعريف الصنف، ويستبدل add بالدالة المغلّفة التي يعيدها. كل استدعاء يمر عبر هذه الدالة المغلّفة. تحافظ معاملات النوع العامة على أنواع this والوسائط والقيمة المُعادة للتابع، فيظل add يأخذ رقمين ويعيد رقمًا.

كيف تُترجم الـ Decorators

تأتي الـ decorators القياسية من مقترح TC39 للغة JavaScript، وتطبّقها TypeScript منذ الإصدار 5.0. المقترح ليس جزءًا من معيار JavaScript بعد، وNode 24 لا يحلل صيغة @، لذلك حين يكون الهدف ES2022 (كما في هذه الصفحات) يعيد المترجم كتابة كل صنف مزخرف إلى JavaScript عادية تستدعي دوال مساعدة (__esDecorate و__runInitializers، تُولَّد في أول الملف). يعمل الناتج في أي مكان تعمل فيه ES2022.

نتيجة لذلك: لا يمكن تشغيل ملف فيه decorators مع إزالة الأنواع المدمجة في Node (node file.ts)، لأنها تحذف الأنواع فقط وتترك @ في مكانه. يتوقف Node بالخطأ SyntaxError: Invalid or unexpected token. ترجمه أولًا بـ tsc أو بأداة تجميع.

أنواع الـ Decorators وتوقيعاتها

لكل decorator قياسي الشكل (value, context) => replacement | void. ما تكونه value، وما يمكنك إعادته، يعتمد على ما تزخرفه:

لكل كائن سياق الخصائص kind وname وaddInitializer. ولسياق عضو الصنف أيضًا static وprivate وكائن access لقراءة العضو من نسخة. وتعمل الـ decorators على الأعضاء الثابتة وأعضاء #private أيضًا.

مصانع الـ Decorators

لتمرير خيارات، اكتب دالة تعيد decorator واستدعها في موضع @. هذا مصنع decorators:

function retry(times: number) {
    return function <This, Args extends unknown[], Return>(
        method: (this: This, ...args: Args) => Return,
        _context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,
    ) {
        return function (this: This, ...args: Args): Return {
            for (let attempt = 1; ; attempt++) {
                try {
                    return method.call(this, ...args);
                } catch (e) {
                    if (attempt >= times) throw e;
                    console.log(`attempt ${attempt} failed, retrying`);
                }
            }
        };
    };
}

class Client {
    calls = 0;

    @retry(3)
    fetchData(): string {
        this.calls++;
        if (this.calls < 3) throw new Error("flaky");
        return `ok after ${this.calls} calls`;
    }
}

console.log(new Client().fetchData());

يستدعي @retry(3) الدالة retry أولًا، والدالة التي تعيدها هي الـ decorator الفعلي. وتتراكم الـ decorators المتعددة: في @a @b method() يُطبَّق b أولًا ثم يغلّف a النتيجة.

decorators الأصناف وaddInitializer

يستقبل decorator الصنف الصنفَ نفسه. يمكنه إعادة صنف فرعي ليحل محله، أو ألا يعيد شيئًا ويكتفي بتسجيله في مكان ما. يسجّل context.addInitializer كودًا يعمل في لحظة محددة: لـ decorator الصنف، مباشرة بعد اكتمال تعريف الصنف؛ ولـ decorator التابع، عند إنشاء كل نسخة.

const registry = new Map<string, new () => object>();

function register(id: string) {
    return function <T extends new () => object>(target: T, context: ClassDecoratorContext<T>) {
        context.addInitializer(() => {
            registry.set(id, target);
        });
    };
}

// Binds a method to its instance, so it survives being passed as a callback.
function bound<This, Args extends unknown[], Return>(
    _method: (this: This, ...args: Args) => Return,
    context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,
) {
    context.addInitializer(function (this: This) {
        const self = this as Record<string | symbol, unknown>;
        const fn = self[context.name] as (...a: unknown[]) => unknown;
        self[context.name] = fn.bind(this);
    });
}

@register("greeter")
class Greeter {
    name = "Ada";

    @bound
    greet(): string {
        return `Hello, ${this.name}`;
    }
}

const g = new Greeter();
const loose = g.greet; // detached from g
console.log(loose());  // Hello, Ada
console.log([...registry.keys()], registry.get("greeter") === Greeter); // [ 'greeter' ] true

يوضع decorator الصنف قبل تعريف الصنف (أو بعد export). دون @bound كان استدعاء loose() سيرمي خطأ، لأن this ستكون undefined.

decorators الحقول والـ Accessors

لا يستطيع decorator الحقل رؤية عمليات الإسناد اللاحقة أو اعتراضها: قيمة value هي undefined، وكل ما يمكنه إعادته دالة تحوّل القيمة الابتدائية للحقل. لاعتراض القراءة والكتابة، عرّف الحقل بالكلمة المفتاحية accessor، التي تحوّله إلى زوج getter وsetter يعتمد على تخزين خاص، وزخرفه:

function trimmed(_value: undefined, _context: ClassFieldDecoratorContext<unknown, string>) {
    return (initial: string) => initial.trim();
}

function positive<This>(
    target: ClassAccessorDecoratorTarget<This, number>,
    context: ClassAccessorDecoratorContext<This, number>,
): ClassAccessorDecoratorResult<This, number> {
    const check = (v: number) => {
        if (v <= 0) throw new RangeError(`${String(context.name)} must be positive, got ${v}`);
        return v;
    };
    return {
        init: check, // runs on the initial value
        set(v) {
            target.set.call(this, check(v));
        },
    };
}

class Product {
    @trimmed title = "  Lamp  ";
    @positive accessor price = 30;
}

const p = new Product();
console.log(`[${p.title}]`, p.price); // [Lamp] 30
p.price = 45;
console.log(p.price); // 45
try {
    p.price = -5;
} catch (e) {
    if (e instanceof Error) console.log(e.message); // price must be positive, got -5
}

accessor جزء من المقترح نفسه. يولّد getter وsetter حقيقيين مبنيين على حقل #private، ولهذا يمر p.price = -5 عبر set الخاص بالـ decorator.

القياسية مقابل experimentalDecorators القديمة

قبل TypeScript 5.0 كانت الـ decorators الوحيدة في TypeScript نسخة مبكرة من المقترح، تُفعَّل بـ experimentalDecorators. هذا الخيار لا يزال موجودًا، ويحوّل المترجم إلى النموذج القديم بتوقيعات ودلالات مختلفة:

الـ decorator المكتوب لنموذج لا يجتاز فحص الأنواع في الآخر. هذا decorator بالأسلوب القديم في مشروع دون الخيار:

// This does not compile: a legacy decorator used as a standard one.
function log(target: object, key: string, descriptor: PropertyDescriptor) {
    const original = descriptor.value;
    descriptor.value = function (this: unknown, ...args: unknown[]) {
        console.log("calling", key);
        return original.apply(this, args);
    };
}

class Service {
    @log
    run(): string {
        return "done";
    }
}

console.log(new Service().run());

index.ts(11,5): error TS1241: Unable to resolve signature of method decorator when called as an expression.
  The runtime will invoke the decorator with 2 arguments, but the decorator expects 3.

الحل إما إعادة كتابته بالصيغة القياسية (value, context)، كما في المثال الأول في هذه الصفحة، وإما تفعيل النموذج القديم للمشروع كله:

{
    "compilerOptions": {
        "experimentalDecorators": true,
        "emitDecoratorMetadata": true
    }
}

لا تزال Angular وNestJS وTypeORM تضبط experimentalDecorators في الإعدادات التي تولّدها أدواتها وتطلبها وثائقها. وتحتاج NestJS وTypeORM أيضًا إلى emitDecoratorMetadata، لأنهما تقرآن الأنواع وقت التشغيل: NestJS لحقن معاملات دالة البناء، وTypeORM لربط الخصائص بالأعمدة:

// Legacy model: needs experimentalDecorators (and emitDecoratorMetadata for DI).
@Injectable()
class UsersService {
    constructor(@Inject(DB) private db: Database) {}
}

إن كنت تستخدم أحد هذه الأطر، فاكتب الـ decorators بالطريقة القديمة واتبع وثائقه. وللكود الجديد دون إطار كهذا، استخدم الـ decorators القياسية.

متى تستخدم الـ Decorators

تناسب الـ decorators السلوك العابر الذي كان سيتكرر في توابع كثيرة: التسجيل في السجلات، وقياس الزمن، والتخزين المؤقت، وإعادة المحاولة، وفحوص الصلاحيات، والتحقق، وتسجيل الأصناف في حاوية أو موجّه. لكنها تخفي مسار التحكم أيضًا، إذ يجب على القارئ أن يبحث عما يفعله @retry قبل أن يعرف ما يفعله التابع. لاستخدام أو استخدامين، تكون دالة عليا عادية (const fetchData = retry(3, rawFetch)) أبسط وتعمل خارج الأصناف أيضًا.