TypeScript 데코레이터 메타데이터와 reflect-metadata

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "strict": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "rootDir": "src",
    "outDir": "out"
  }
}

// src/01-emit/model.ts
function Property(label: string) {
  return function (target: object, propertyKey: string) {
    console.log(`Property('${label}') 호출: ${propertyKey}`);
  };
}
 
export class TitleModel {
  @Property('제목')
  text: string = '';
 
  @Property('글자 크기')
  fontSize: number = 12;
}

// out/01-emit/model.js (헬퍼 정의 생략)
function Property(label) {
    return function (target, propertyKey) {
        console.log(`Property('${label}') 호출: ${propertyKey}`);
    };
}
export class TitleModel {
    text = '';
    fontSize = 12;
}
__decorate([
    Property('제목'),
    __metadata("design:type", String)
], TitleModel.prototype, "text", void 0);
__decorate([
    Property('글자 크기'),
    __metadata("design:type", Number)
], TitleModel.prototype, "fontSize", void 0);

+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
 ...
 __decorate([
-    Property('제목')
+    Property('제목'),
+    __metadata("design:type", String)
 ], TitleModel.prototype, "text", void 0);

// src/02-reflect/without-reflect.ts
import { TitleModel } from '../01-emit/model.js';
 
console.log('Reflect.metadata 타입:', typeof (Reflect as { metadata?: unknown }).metadata);
 
new TitleModel();
new TitleModel();
console.log('인스턴스 2개 생성 완료');

$ node out/02-reflect/without-reflect.js
Property('제목') 호출: text
Property('글자 크기') 호출: fontSize
Reflect.metadata 타입: undefined
인스턴스 2개 생성 완료

var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
    return c > 3 && r && Object.defineProperty(target, key, r), r;
};
var __metadata = (this && this.__metadata) || function (k, v) {
    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
};

// src/02-reflect/with-reflect.ts
import 'reflect-metadata';
import { TitleModel } from '../01-emit/model.js';
 
const proto = TitleModel.prototype;
 
console.log('text:', Reflect.getMetadata('design:type', proto, 'text'));
console.log('fontSize:', Reflect.getMetadata('design:type', proto, 'fontSize'));
console.log('text의 메타데이터 키:', Reflect.getMetadataKeys(proto, 'text'));

$ node out/02-reflect/with-reflect.js
Property('제목') 호출: text
Property('글자 크기') 호출: fontSize
text: [Function: String]
fontSize: [Function: Number]
text의 메타데이터 키: [ 'design:type' ]

WeakMap (키: target 객체)
└─ TitleModel.prototype → Map (키: 속성 이름)
   ├─ 'text'     → Map { 'design:type' → String }
   └─ 'fontSize' → Map { 'design:type' → Number }

// src/02-reflect/inherit.ts
import 'reflect-metadata';
import { TitleModel } from '../01-emit/model.js';
 
class SubTitleModel extends TitleModel {}
 
const proto = SubTitleModel.prototype;
 
console.log('getMetadata:', Reflect.getMetadata('design:type', proto, 'text'));
console.log('getOwnMetadata:', Reflect.getOwnMetadata('design:type', proto, 'text'));
console.log('부모 프로토타입:', Object.getPrototypeOf(proto) === TitleModel.prototype);

$ node out/02-reflect/inherit.js
Property('제목') 호출: text
Property('글자 크기') 호출: fontSize
getMetadata: [Function: String]
getOwnMetadata: undefined
부모 프로토타입: true

// src/02-reflect/wrong-order.ts
import { TitleModel } from '../01-emit/model.js';
import 'reflect-metadata';
 
const proto = TitleModel.prototype;
 
console.log('text:', Reflect.getMetadata('design:type', proto, 'text'));
console.log('text의 메타데이터 키:', Reflect.getMetadataKeys(proto, 'text'));

$ node out/02-reflect/wrong-order.js
Property('제목') 호출: text
Property('글자 크기') 호출: fontSize
text: undefined
text의 메타데이터 키: []

// src/03-types/types.ts (출력 부분 생략)
import 'reflect-metadata';
 
function Mark(target: object, propertyKey: string) {}
 
interface Point {
  x: number;
  y: number;
}
 
class Color {
  constructor(public hex: string) {}
}
 
class Box<T> {
  constructor(public value: T) {}
}
 
enum Align {
  Left,
  Right,
}
 
type Size = 'small' | 'large';
 
class Sample<T> {
  @Mark str: string = '';
  @Mark num: number = 0;
  @Mark bool: boolean = false;
  @Mark date: Date = new Date();
  @Mark list: string[] = [];
  @Mark tuple: [number, number] = [0, 0];
  @Mark optional?: string;
  @Mark nullable: string | null = null;
  @Mark maybe: string | undefined = undefined;
  @Mark union: string | number = '';
  @Mark literal: Size = 'small';
  @Mark align: Align = Align.Left;
  @Mark point: Point = { x: 0, y: 0 };
  @Mark color: Color = new Color('#000');
  @Mark box: Box<string> = new Box('');
  @Mark map: Map<string, number> = new Map();
  @Mark record: Record<string, number> = {};
  @Mark callback: () => void = () => {};
  @Mark generic: T;
  @Mark anything: unknown = null;
  @Mark inferred = 1;
 
  constructor(generic: T) {
    this.generic = generic;
  }
}

// src/03-types/later-class.ts
function Mark(target: object, propertyKey: string) {}
 
class TitleModel {
  // 같은 파일 아래쪽에 선언한 클래스를 타입으로 쓴다
  @Mark
  color?: Color;
}
 
class Color {}
 
console.log(TitleModel, Color);

$ node out/03-types/later-class-runner.js
ReferenceError: Cannot access 'Color' before initialization

// src/09-import/color.ts
console.log('color.ts 실행');
 
export class Color {
  constructor(public hex: string) {}
}

// src/09-import/style-model.ts
import { Color } from './color.js';
 
function Mark(target: object, propertyKey: string) {}
 
export class StyleModel {
  // Color는 타입 자리에만 쓴다
  @Mark
  color?: Color;
}

$ node out/09-import/main.js
color.ts 실행
StyleModel 로드 완료: function
$ node out-nometa/09-import/main.js
StyleModel 로드 완료: function

// src/04-method/method.ts
import 'reflect-metadata';
 
class Logger {}
 
// NestJS의 @Injectable()과 달리 팩토리가 아니라 데코레이터 함수 자체라 괄호 없이 붙인다
function Injectable(target: Function) {}
function Mark(target: object, propertyKey: string, descriptor: PropertyDescriptor) {}
 
@Injectable
class TitleService {
  constructor(private logger: Logger, private prefix: string) {}
 
  @Mark
  format(text: string, size: number): string {
    return `${this.prefix}${text}:${size}`;
  }
 
  // 반환 타입을 적지 않은 메서드
  @Mark
  count(text: string) {
    return text.length;
  }
}
 
// 데코레이터가 없는 클래스
class PlainService {
  constructor(private logger: Logger) {}
}
 
const proto = TitleService.prototype;
console.log('design:type      ', Reflect.getMetadata('design:type', proto, 'format'));
console.log('design:paramtypes', Reflect.getMetadata('design:paramtypes', proto, 'format'));
console.log('design:returntype', Reflect.getMetadata('design:returntype', proto, 'format'));
console.log('생성자 paramtypes', Reflect.getMetadata('design:paramtypes', TitleService));
console.log('count의 returntype', Reflect.getMetadata('design:returntype', proto, 'count'));
console.log('PlainService 생성자 paramtypes', Reflect.getMetadata('design:paramtypes', PlainService));

$ node out/04-method/method.js
design:type       [Function: Function]
design:paramtypes [ [Function: String], [Function: Number] ]
design:returntype [Function: String]
생성자 paramtypes [ [class Logger], [Function: String] ]
count의 returntype undefined
PlainService 생성자 paramtypes undefined

// out/04-method/method.js (일부)
__decorate([
    Mark,
    __metadata("design:type", Function),
    __metadata("design:paramtypes", [String, Number]),
    __metadata("design:returntype", String)
], TitleService.prototype, "format", null);
TitleService = __decorate([
    Injectable,
    __metadata("design:paramtypes", [Logger, String])
], TitleService);

// src/05-target/static-member.ts
function Inspect(target: object, propertyKey: string) {
  const kind = typeof target === 'function' ? '클래스(생성자)' : '프로토타입';
  console.log(`${propertyKey}: target은 ${kind}`);
}
 
class TitleModel {
  @Inspect
  text: string = '';
 
  @Inspect
  static defaultText: string = '제목 없음';
}

$ node out/05-target/static-member.js
text: target은 프로토타입
defaultText: target은 클래스(생성자)

], TitleModel.prototype, "text", void 0);
], TitleModel, "defaultText", void 0);

// src/05-target/by-name.ts
interface PropertyInfo {
  key: string;
  label: string;
}
 
// 클래스 이름을 키로 속성 정보를 모아 두는 저장소
const registry = new Map<string, PropertyInfo[]>();
 
let registeredTarget: object | undefined;
 
function Property(label: string) {
  return function (target: object, propertyKey: string) {
    registeredTarget = target;
    console.log('등록 시점 target.constructor.name:', target.constructor.name);
 
    const name = target.constructor.name;
    const list = registry.get(name) ?? [];
    list.push({ key: propertyKey, label });
    registry.set(name, list);
  };
}
 
function getProperties(target: object) {
  return registry.get(target.constructor.name);
}
 
class TitleModel {
  @Property('제목')
  text: string = '';
}
 
console.log('인스턴스로 조회:', getProperties(new TitleModel()));
console.log('클래스로 조회:', getProperties(TitleModel));
console.log('TitleModel.constructor.name:', TitleModel.constructor.name);
console.log('등록 시점 target === TitleModel.prototype:', registeredTarget === TitleModel.prototype);

$ node out/05-target/by-name.js
등록 시점 target.constructor.name: TitleModel
인스턴스로 조회: [ { key: 'text', label: '제목' } ]
클래스로 조회: undefined
TitleModel.constructor.name: Function
등록 시점 target === TitleModel.prototype: true

$ node dist/mangle/by-name.min.js
등록 시점 target.constructor.name: r
인스턴스로 조회: [ { key: 'text', label: '제목' } ]
클래스로 조회: undefined
TitleModel.constructor.name: Function
등록 시점 target === TitleModel.prototype: true

// src/07-mangle/registry.ts
// 이름을 키로 쓰는 전역 저장소. 번들 두 개가 같은 저장소를 쓰는 상황을 흉내 낸다.
const globalRef = globalThis as { __propertyRegistry?: Map<string, string[]> };
const registry = (globalRef.__propertyRegistry ??= new Map<string, string[]>());
 
export function Property(target: object, propertyKey: string) {
  const name = target.constructor.name;
  const list = registry.get(name) ?? [];
  list.push(propertyKey);
  registry.set(name, list);
}
 
export function dump(label: string) {
  console.log(label, Object.fromEntries(registry));
}

// src/07-mangle/chart.ts
import { Property, dump } from './registry.js';
 
export class ChartTitle {
  @Property
  visible: boolean = true;
}
 
new ChartTitle();
dump('chart 번들 로드 후:');

$ node out/07-mangle/app-unminified.js
chart 번들 로드 후: { ChartTitle: [ 'visible' ] }
map 번들 로드 후: { ChartTitle: [ 'visible' ], MapLegend: [ 'visible' ] }
$ node out/07-mangle/app.js
chart 번들 로드 후: { r: [ 'visible' ] }
map 번들 로드 후: { r: [ 'visible', 'visible' ] }

// src/05-target/by-object.ts
interface PropertyInfo {
  key: string;
  label: string;
}
 
// 클래스(생성자 함수) 객체 자체를 키로 쓰는 저장소
const registry = new WeakMap<Function, PropertyInfo[]>();
 
// 프로토타입이 넘어오면 constructor를, 클래스가 넘어오면 그대로 쓴다
function toClass(target: object): Function {
  return typeof target === 'function' ? target : target.constructor;
}
 
function Property(label: string) {
  return function (target: object, propertyKey: string) {
    const cls = toClass(target);
    const list = registry.get(cls) ?? [];
    list.push({ key: propertyKey, label });
    registry.set(cls, list);
  };
}
 
function getProperties(target: object) {
  return registry.get(toClass(target));
}
 
class TitleModel {
  @Property('제목')
  text: string = '';
}
 
console.log('인스턴스로 조회:', getProperties(new TitleModel()));
console.log('클래스로 조회:', getProperties(TitleModel));

$ node out/05-target/by-object.js
인스턴스로 조회: [ { key: 'text', label: '제목' } ]
클래스로 조회: [ { key: 'text', label: '제목' } ]

$ node out/08-object-key/app.js
chart 번들 ChartTitle 이름: f / 속성: [ 'visible' ]
map 번들 MapLegend 이름: f / 속성: [ 'visible' ]

// src/06-bundle/title-decorated.ts
import { Property } from './property.js';
 
export class TitleModel {
  @Property('제목', 'text')
  text: string = '';
 
  @Property('글자 크기', 'number')
  fontSize: number = 12;
 
  @Property('글자 색', 'color')
  color: string = '#000000';
}

// dist/bundle/case3.min.js
const t=new WeakMap;function e(t){return"function"==typeof t?t:t.constructor}function o(o,n){return function(r,c){const f=e(r),i=t.get(f)??[];i.push({key:c,label:o,editor:n}),t.set(f,i)}}var n=function(t,e,o,n){var r,c=arguments.length,f=c<3?e:null===n?n=Object.getOwnPropertyDescriptor(e,o):n;if("object"==typeof Reflect&&"function"==typeof Reflect.decorate)f=Reflect.decorate(t,e,o,n);else for(var i=t.length-1;i>=0;i--)(r=t[i])&&(f=(c<3?r(f):c>3?r(e,o,f):r(e,o))||f);return c>3&&f&&Object.defineProperty(e,o,f),f},r=function(t,e){if("object"==typeof Reflect&&"function"==typeof Reflect.metadata)return Reflect.metadata(t,e)};class c{text="";fontSize=12;color="#000000"}n([o("제목","text"),r("design:type",String)],c.prototype,"text",void 0),n([o("글자 크기","number"),r("design:type",Number)],c.prototype,"fontSize",void 0),n([o("글자 색","color"),r("design:type",String)],c.prototype,"color",void 0);const f=new c;var i;console.log(f.text,(i=f,t.get(e(i))??[]).length);

// src/06-bundle/lib-decorated.ts
export { Property, getProperties } from './property.js';
export { TitleModel } from './title-decorated.js';
export { LegendModel } from './legend-decorated.js';

// src/06-bundle/entry-decorated.ts
// LegendModel은 가져오지 않는다
import { TitleModel, getProperties } from './lib-decorated.js';
 
const model = new TitleModel();
console.log(model.text, getProperties(model).length);

f([o("범례 위치","text"),i("design:type",String)],class{position="bottom"}.prototype,"position",void 0)

{
  "compilerOptions": {
    "importHelpers": true
  }
}

// dist/esbuild/with-reflect.js (일부)
__decorateClass([
  Property("제목")
], TitleModel.prototype, "text", 2);

$ node dist/esbuild/with-reflect.js
Property('제목') 호출: text
Property('글자 크기') 호출: fontSize
text: undefined
fontSize: undefined
text의 메타데이터 키: []

error TS5052: Option 'emitDecoratorMetadata' cannot be specified without specifying option 'experimentalDecorators'.

// standard/src/standard.ts
// Node 22에는 Symbol.metadata가 없어서 먼저 채워 둔다
(Symbol as { metadata?: symbol }).metadata ??= Symbol('Symbol.metadata');
 
function Property(label: string) {
  return function (_value: undefined, context: ClassFieldDecoratorContext) {
    const { metadata } = context;
 
    // 자기 배열이 없으면 부모 배열을 복사해 새로 만든다
    if (!Object.hasOwn(metadata, 'properties')) {
      const inherited = metadata.properties;
      metadata.properties = Array.isArray(inherited) ? [...inherited] : [];
    }
 
    const list = metadata.properties;
    if (Array.isArray(list)) {
      list.push(`${String(context.name)}:${label}`);
    }
  };
}
 
class TitleModel {
  @Property('제목')
  text: string = '';
 
  @Property('글자 크기')
  fontSize: number = 12;
}
 
class SubTitleModel extends TitleModel {
  @Property('부제')
  subtitle: string = '';
}
 
console.log('TitleModel:', TitleModel[Symbol.metadata]);
console.log('SubTitleModel:', SubTitleModel[Symbol.metadata]);

$ node standard/out/standard.js
TitleModel: [Object: null prototype] {
  properties: [ 'text:제목', 'fontSize:글자 크기' ]
}
SubTitleModel: Object <[Object: null prototype]> {
  properties: [ 'text:제목', 'fontSize:글자 크기', 'subtitle:부제' ]
}