Decorator TypeScript: Method, Class, Field, dan Accessor

Decorator adalah fungsi yang kamu pasang pada class atau member class dengan @name. Fungsi ini menerima method aslinya (atau class, atau field) ditambah objek context yang mendeskripsikannya, dan bisa mengembalikan penggantinya. TypeScript mendukung decorator standar tanpa flag compiler apa pun.

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 dijalankan sekali, saat class didefinisikan, dan mengganti add dengan wrapper yang dikembalikannya. Setiap pemanggilan melewati wrapper itu. Parameter generic menjaga tipe this, argumen, dan nilai kembalian method tetap utuh, jadi add tetap menerima dua angka dan mengembalikan angka.

Bagaimana Decorator Dikompilasi

Decorator standar berasal dari proposal TC39 untuk JavaScript, dan TypeScript sudah mengimplementasikannya sejak TypeScript 5.0. Proposal itu belum menjadi bagian dari standar JavaScript, dan Node 24 tidak bisa mem-parse sintaks @, jadi ketika target-nya ES2022 (seperti di halaman-halaman ini) compiler menulis ulang setiap class yang didekorasi menjadi JavaScript biasa yang memanggil fungsi helper (__esDecorate dan __runInitializers, yang ditulis di bagian atas file). Output-nya berjalan di mana pun ES2022 berjalan.

Satu konsekuensinya: file dengan decorator tidak bisa dijalankan dengan type stripping bawaan Node (node file.ts), yang hanya membuang tipe dan membiarkan @ di tempatnya. Node berhenti dengan SyntaxError: Invalid or unexpected token. Kompilasi dulu dengan tsc atau bundler.

Jenis Decorator dan Signature-nya

Setiap decorator standar berbentuk (value, context) => replacement | void. Apa itu value, dan apa yang boleh kamu kembalikan, bergantung pada apa yang didekorasi:

Setiap objek context punya kind, name, dan addInitializer. Context sebuah member class juga punya static, private, dan objek access untuk membaca member itu dari sebuah instance. Decorator juga bisa dipakai pada member static dan #private.

Decorator Factory

Untuk mengirim opsi, tulis fungsi yang mengembalikan decorator, lalu panggil di tempat @. Inilah 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) memanggil retry lebih dulu, dan fungsi yang dikembalikannya adalah decorator yang sebenarnya. Beberapa decorator bisa ditumpuk: di @a @b method(), b diterapkan lebih dulu lalu a membungkus hasilnya.

Class Decorator dan addInitializer

Class decorator menerima class itu sendiri. Decorator ini bisa mengembalikan subclass untuk menggantikannya, atau tidak mengembalikan apa pun dan hanya mencatatnya di suatu tempat. context.addInitializer mendaftarkan kode yang dijalankan pada saat tertentu: untuk class decorator, tepat setelah class selesai didefinisikan; untuk method decorator, saat setiap instance dibuat.

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 ditulis di atas class (atau setelah export). Tanpa @bound, memanggil loose() akan melempar error, karena this akan bernilai undefined.

Field Decorator dan Accessor Decorator

Field decorator tidak bisa melihat atau mencegat penugasan berikutnya: value-nya adalah undefined, dan yang bisa dikembalikannya hanyalah fungsi yang mengubah nilai awal field. Untuk mencegat pembacaan dan penulisan, deklarasikan field dengan kata kunci accessor, yang mengubahnya menjadi pasangan getter dan setter dengan penyimpanan private, lalu dekorasi field itu:

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 adalah bagian dari proposal yang sama. Kata kunci ini menghasilkan getter dan setter sungguhan di atas field #private, itulah sebabnya p.price = -5 melewati set milik decorator.

Decorator Standar vs experimentalDecorators Legacy

Sebelum TypeScript 5.0, satu-satunya decorator yang dimiliki TypeScript adalah versi awal dari proposal itu, yang dinyalakan dengan experimentalDecorators. Flag itu masih ada, dan ia mengalihkan compiler ke model legacy, dengan signature dan semantik yang berbeda:

Decorator yang ditulis untuk satu model tidak lolos pemeriksaan tipe di model lainnya. Berikut decorator bergaya legacy di proyek tanpa flag itu:

// 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.

Perbaikannya adalah menulis ulang dalam bentuk standar (value, context), seperti contoh pertama di halaman ini, atau menyalakan model legacy untuk seluruh proyek:

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

Angular, NestJS, dan TypeORM masih mengatur experimentalDecorators di config yang dihasilkan alat mereka dan diminta dokumentasinya. NestJS dan TypeORM juga butuh emitDecoratorMetadata, karena keduanya membaca tipe saat runtime: NestJS untuk meng-inject parameter constructor, TypeORM untuk memetakan property ke kolom:

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

Kalau kamu memakai salah satu framework tersebut, tulis decorator dengan cara legacy dan ikuti dokumentasinya. Untuk kode baru tanpa framework semacam itu, pakai decorator standar.

Kapan Memakai Decorator

Decorator cocok untuk perilaku lintas bagian yang kalau tidak akan diulang di banyak method: logging, pengukuran waktu, caching, retry, pemeriksaan akses, validasi, dan mendaftarkan class ke container atau router. Decorator juga menyembunyikan alur kontrol, karena pembaca harus mencari tahu apa yang dilakukan @retry sebelum tahu apa yang dilakukan method itu. Untuk satu atau dua pemakaian, higher-order function biasa (const fetchData = retry(3, rawFetch)) lebih sederhana dan juga bisa dipakai di luar class.