TypeScript Decorator: Metot, Sınıf, Alan ve Accessor

Decorator, bir sınıfa ya da bir sınıf üyesine @name ile eklediğiniz bir fonksiyondur. Orijinal metodu (ya da sınıfı, ya da alanı) ve onu tarif eden bir context nesnesini alır ve yerine geçecek bir değer döndürebilir. TypeScript standart decorator'ları hiçbir derleyici bayrağı olmadan destekler.

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, sınıf tanımlandığında bir kez çalışır ve add metodunu döndürdüğü sarmalayıcıyla değiştirir. Her çağrı bu sarmalayıcıdan geçer. Generic parametreler metodun this, argüman ve dönüş tiplerini korur; bu yüzden add hâlâ iki sayı alır ve bir sayı döndürür.

Decorator'lar Nasıl Derlenir

Standart decorator'lar JavaScript için bir TC39 önerisinden gelir ve TypeScript onları TypeScript 5.0'dan beri implement eder. Öneri henüz JavaScript standardının parçası değildir ve Node 24 @ sözdizimini ayrıştırmaz; bu yüzden hedef ES2022 olduğunda (bu sayfalarda olduğu gibi) derleyici dekore edilmiş her sınıfı yardımcı fonksiyonları (__esDecorate ve __runInitializers, dosyanın en üstüne yazılır) çağıran düz JavaScript'e dönüştürür. Çıktı, ES2022'nin çalıştığı her yerde çalışır.

Bunun bir sonucu var: decorator içeren bir dosya, yalnızca tipleri kaldırıp @ işaretini yerinde bırakan Node'un yerleşik tip ayıklamasıyla (node file.ts) çalışamaz. Node SyntaxError: Invalid or unexpected token ile durur. Önce tsc ya da bir bundler ile derleyin.

Decorator Türleri ve İmzaları

Her standart decorator (value, context) => replacement | void biçimindedir. value değerinin ne olduğu ve ne döndürebileceğiniz, neyin dekore edildiğine bağlıdır:

Her context nesnesinde kind, name ve addInitializer vardır. Bir sınıf üyesinin context'inde ayrıca static, private ve üyeyi bir örnekten okumak için bir access nesnesi bulunur. Decorator'lar statik ve #private üyelerde de çalışır.

Decorator Factory'leri

Seçenek geçirmek için bir decorator döndüren bir fonksiyon yazın ve onu @ konumunda çağırın. Buna decorator factory denir:

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) önce retry fonksiyonunu çağırır; asıl decorator onun döndürdüğü fonksiyondur. Birden fazla decorator üst üste binebilir: @a @b method() içinde önce b uygulanır, sonucu da a sarar.

Sınıf Decorator'ları ve addInitializer

Bir sınıf decorator'ı sınıfın kendisini alır. Onun yerine geçecek bir alt sınıf döndürebilir ya da hiçbir şey döndürmeyip sınıfı bir yere kaydedebilir. context.addInitializer, belirli bir anda çalışacak kodu kaydeder: bir sınıf decorator'ı için sınıf tamamen tanımlandıktan hemen sonra, bir metot decorator'ı için her örnek oluşturulduğunda.

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

Sınıf decorator'ı sınıfın üstüne (ya da export sonrasına) yazılır. @bound olmasaydı loose() çağrısı hata fırlatırdı, çünkü this değeri undefined olurdu.

Alan ve Accessor Decorator'ları

Bir alan decorator'ı sonraki atamaları göremez ve araya giremez: value değeri undefined'dır ve döndürebileceği tek şey alanın başlangıç değerini dönüştüren bir fonksiyondur. Okumalara ve yazmalara araya girmek için alanı accessor anahtar kelimesiyle bildirin; bu, onu private bir depolamayla desteklenen bir getter ve setter çiftine dönüştürür. Sonra onu dekore edin:

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 aynı önerinin parçasıdır. Bir #private alan üzerinde gerçek bir getter ve setter üretir; p.price = -5 atamasının decorator'ın set fonksiyonundan geçmesinin nedeni budur.

Standart Model ve Eski experimentalDecorators

TypeScript 5.0'dan önce TypeScript'in sahip olduğu tek decorator'lar, experimentalDecorators ile açılan önerinin erken bir sürümüydü. Bu bayrak hâlâ vardır ve derleyiciyi farklı imzalara ve semantiğe sahip eski modele geçirir:

Bir model için yazılmış bir decorator diğerinde tip kontrolünden geçmez. İşte bayrağı olmayan bir projede eski tarzda yazılmış bir 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.

Çözüm ya onu bu sayfadaki ilk örnekteki gibi standart (value, context) biçiminde yeniden yazmak ya da tüm proje için eski modeli açmaktır:

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

Angular, NestJS ve TypeORM, araçlarının ürettiği yapılandırmalarda hâlâ experimentalDecorators ayarlar ve dokümantasyonları da bunu ister. NestJS ve TypeORM ayrıca emitDecoratorMetadata seçeneğine ihtiyaç duyar, çünkü tipleri çalışma zamanında okurlar: NestJS constructor parametrelerini enjekte etmek için, TypeORM ise özellikleri sütunlara eşlemek için:

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

Bu framework'lerden birini kullanıyorsanız decorator'ları eski yöntemle yazın ve onun dokümantasyonunu izleyin. Böyle bir framework olmayan yeni kodlarda standart decorator'ları kullanın.

Decorator'lar Ne Zaman Kullanılmalı

Decorator'lar, aksi halde birçok metotta tekrarlanacak kesişen davranışlara uyar: loglama, süre ölçme, önbellekleme, yeniden denemeler, erişim kontrolleri, doğrulama ve sınıfları bir container'a ya da router'a kaydetme. Aynı zamanda kontrol akışını da gizlerler, çünkü okuyanın metodun ne yaptığını bilmeden önce @retry ifadesinin ne yaptığına bakması gerekir. Bir iki kullanım için düz bir higher-order fonksiyon (const fetchData = retry(3, rawFetch)) daha basittir ve sınıfların dışında da çalışır.