TypeScript 데코레이터: 메서드, 클래스, 필드, accessor

데코레이터는 @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는 여전히 숫자 두 개를 받고 숫자를 반환합니다.

데코레이터가 컴파일되는 방식

표준 데코레이터는 JavaScript의 TC39 제안에서 왔고, TypeScript는 TypeScript 5.0부터 이를 구현했습니다. 이 제안은 아직 JavaScript 표준에 포함되지 않았고 Node 24는 @ 문법을 파싱하지 못하므로, target이 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 객체도 있습니다. 데코레이터는 정적 멤버와 #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 키워드로 선언하세요. 그러면 private 저장소를 쓰는 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가 무엇을 하는지 찾아봐야 하기 때문입니다. 한두 번 쓸 거라면 평범한 고차 함수(const fetchData = retry(3, rawFetch))가 더 단순하고 클래스 밖에서도 동작합니다.