Decorators ב-TypeScript: מתודה, מחלקה, שדה ו-accessor

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 מממשת אותם מאז TypeScript 5.0. ההצעה עוד לא חלק מתקן JavaScript, ו-Node 24 לא מפענח את התחביר @, ולכן כשה-target הוא ES2022 (כמו בעמודים האלה) הקומפיילר כותב מחדש כל מחלקה מעוטרת ל-JavaScript רגיל שקורא לפונקציות עזר (__esDecorate ו-__runInitializers, שנכתבות בראש הקובץ). הפלט רץ בכל מקום שבו ES2022 רץ.

השלכה אחת: קובץ עם decorators לא יכול לרוץ תחת ה-type stripping המובנה של Node (node file.ts), שרק מסיר טיפוסים ומשאיר את ה-@ במקומו. Node עוצר עם SyntaxError: Invalid or unexpected token. קמפלו אותו קודם עם tsc או עם bundler.

סוגי decorators והחתימות שלהם

לכל decorator סטנדרטי יש את הצורה (value, context) => replacement | void. מה זה value, ומה מותר להחזיר, תלוי במה שמעוטר:

לכל אובייקט הקשר יש kind, name ו-addInitializer. להקשר של איבר מחלקה יש גם static, private ואובייקט access לקריאת האיבר ממופע. decorators עובדים גם על איברים סטטיים ועל איברי #private.

Decorator Factories

כדי להעביר אפשרויות, כתבו פונקציה שמחזירה decorator וקראו לה במקום של ה-@. זה decorator factory:

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 עוטף את התוצאה.

Class Decorators ו-addInitializer

class decorator מקבל את המחלקה עצמה. הוא יכול להחזיר תת-מחלקה שתחליף אותה, או לא להחזיר כלום ורק לרשום אותה איפשהו. context.addInitializer רושם קוד שירוץ ברגע מסוים: ב-class decorator, מיד אחרי שהמחלקה מוגדרת במלואה; ב-method 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

ה-class decorator נכתב מעל המחלקה (או אחרי export). בלי @bound, קריאה ל-loose() הייתה זורקת, כי this היה undefined.

Field Decorators ו-Accessor Decorators

field 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) {}
}

אם אתם משתמשים באחד מה-frameworks האלה, כתבו decorators בדרך הישנה ועקבו אחרי התיעוד שלו. לקוד חדש בלי framework כזה, השתמשו ב-decorators הסטנדרטיים.

מתי להשתמש ב-decorators

decorators מתאימים להתנהגות רוחבית שאחרת הייתה חוזרת על עצמה בהרבה מתודות: לוגים, מדידת זמן, caching, ניסיונות חוזרים, בדיקות הרשאה, ולידציה ורישום מחלקות ב-container או ב-router. הם גם מסתירים את זרימת הבקרה, כי קורא צריך לבדוק מה @retry עושה לפני שהוא יודע מה המתודה עושה. לשימוש אחד או שניים, higher-order function רגילה (const fetchData = retry(3, rawFetch)) פשוטה יותר ועובדת גם מחוץ למחלקות.