TypeScriptのデコレーター: メソッド・クラス・フィールド

デコレーターは、@name でクラスやクラスのメンバーに付ける関数です。元のメソッド（またはクラス、フィールド）と、それを説明するコンテキストオブジェクトを受け取り、置き換えるものを返せます。TypeScriptはコンパイラーのフラグなしで標準のデコレーターをサポートしています。

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 は相変わらず2つの数値を受け取って数値を返します。

デコレーターのコンパイル結果

標準のデコレーターはJavaScriptの TC39 の提案から来ていて、TypeScriptは TypeScript 5.0 から実装しています。この提案はまだJavaScriptの標準に入っておらず、Node 24 は @ の構文を解析できません。そのため、ターゲットが ES2022 のとき（このページのサンプルもそうです）、コンパイラーはデコレートされたクラスを、ヘルパー関数（ファイルの先頭に出力される __esDecorate と __runInitializers）を呼ぶ普通のJavaScriptに書き換えます。出力は ES2022 が動くところならどこでも動きます。

その結果として、デコレーターを含むファイルは Node の組み込みの型除去（node file.ts）では実行できません。型除去は型を取り除くだけで @ は残すからです。Node は SyntaxError: Invalid or unexpected token で止まります。先に tsc かバンドラーでコンパイルしましょう。

デコレーターの種類とシグネチャ

標準のデコレーターはすべて (value, context) => replacement | void という形です。value が何で、何を返せるかは、デコレートする対象によって変わります:

どのコンテキストオブジェクトも kind、name、addInitializer を持ちます。クラスのメンバーのコンテキストは、さらに static、private、インスタンスからメンバーを読むための access オブジェクトを持ちます。デコレーターは static メンバーや #private メンバーにも使えます。

デコレーターファクトリー

オプションを渡すには、デコレーターを返す関数を書き、@ の位置で呼び出します。これがデコレーターファクトリーです:

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 を呼び、それが返す関数が実際のデコレーターになります。デコレーターは重ねられます。@a @b method() では、b が先に適用され、その結果を a がラップします。

クラスデコレーターと addInitializer

クラスデコレーターはクラスそのものを受け取ります。サブクラスを返してクラスを置き換えることも、何も返さずにどこかに記録するだけにすることもできます。context.addInitializer は、特定のタイミングで実行するコードを登録します。クラスデコレーターならクラスが完全に定義された直後、メソッドデコレーターなら各インスタンスが作られるときです。

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

クラスデコレーターはクラスの上（または export のあと）に書きます。@bound がなければ、this が undefined になるので、loose() の呼び出しは例外を投げます。

フィールドデコレーターと accessor デコレーター

フィールドデコレーターは、あとからの代入を見ることも横取りすることもできません。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 は同じ提案の一部です。#private フィールドの上に本物の getter と setter を出力するので、p.price = -5 はデコレーターの set を通ります。

標準のデコレーターと従来の experimentalDecorators

TypeScript 5.0 より前にTypeScriptが持っていたデコレーターは、experimentalDecorators で有効にする初期版の提案だけでした。このフラグは今もあり、コンパイラーをシグネチャも意味も違う従来のモデルに切り替えます:

一方のモデル用に書いたデコレーターは、もう一方では型チェックを通りません。フラグのないプロジェクトで従来型のデコレーターを使うと次のようになります:

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

これらのフレームワークを使うなら、デコレーターは従来の方法で書き、そのドキュメントに従いましょう。そうしたフレームワークを使わない新しいコードでは、標準のデコレーターを使います。

デコレーターを使う場面

デコレーターは、そうしなければ多くのメソッドで繰り返すことになる横断的な処理に向いています。ログ、時間の計測、キャッシュ、リトライ、アクセスチェック、検証、コンテナーやルーターへのクラスの登録などです。一方で制御の流れを隠してしまうので、読む人はメソッドが何をするかを知る前に @retry が何をするかを調べなければなりません。使う場所が1つか2つなら、普通の高階関数（const fetchData = retry(3, rawFetch)）のほうがシンプルで、クラスの外でも使えます。