Token과 Provider — DI의 주소 체계와 등록 단위

// packages/core/src/types.ts
export type Token<T = unknown> = string | symbol | Constructor<T>;

// 문자열 토큰 — 환경변수나 설정값에 적합
const DB_URL = 'DATABASE_URL';

// 심볼 토큰 — 충돌 없는 전역 식별자
const LOGGER = Symbol('LOGGER');

// 클래스 토큰 — 클래스 자체가 토큰
class UsersService {}

// packages/core/src/types.ts
export type Constructor<T = unknown> = new (...args: any[]) => T;

import { forwardRef } from '@fluojs/di';
import { Inject } from '@fluojs/core';

// ServiceB 참조를 즉시 평가하지 않고 함수로 미룬다.
// 덕분에 파일 안의 선언 순서나 순환 참조 때문에 decorator 평가가 깨지지 않는다.
@Inject(forwardRef(() => ServiceB))
class ServiceA {
  constructor(private readonly b: ServiceB) {}
}

class ServiceB {
  status() { return 'ready'; }
}

// packages/di/src/types.ts
export type ForwardRefFn<T = unknown> = { __forwardRef__: true; forwardRef: () => Token<T> };

export function forwardRef<T = unknown>(fn: () => Token<T>): ForwardRefFn<T> {
  return { __forwardRef__: true, forwardRef: fn };
}

import { optional } from '@fluojs/di';
import { Inject } from '@fluojs/core';

// MetricsService가 등록돼 있으면 주입하고, 없으면 undefined로 둔다.
// 로깅/메트릭처럼 없어도 핵심 기능이 동작해야 하는 의존성에 적합하다.
@Inject(optional(MetricsService))
class UsersService {
  constructor(private readonly metrics?: MetricsService) {}
}

// packages/di/src/types.ts
export type OptionalToken<T = unknown> = { __optional__: true; token: Token<T> };

export function optional<T = unknown>(token: Token<T>): OptionalToken<T> {
  return { __optional__: true, token };
}

container.register(UsersService);
// 토큰: UsersService, 구현: UsersService 인스턴스

container.register({
  // ILogger 토큰으로 요청해도 실제 구현체는 PinoLogger를 만든다.
  provide: ILogger,
  useClass: PinoLogger,
  // 로거는 앱 전체에서 하나만 공유해도 되는 상태 없는 서비스다.
  scope: 'singleton',
});

container.register({
  provide: 'DB_CONNECTION',
  // factory provider는 비동기 생성이나 외부 리소스 연결에 적합하다.
  useFactory: async (config: AppConfig) => {
    return await createConnection(config.dbUrl);
  },
  // factory 인자는 inject 배열 순서대로 resolve된다.
  inject: [AppConfig],
  scope: 'singleton',
});

container.register({
  provide: 'CONFIG',
  // 이미 만들어진 값은 생성 과정 없이 그대로 캐시에 들어간다.
  useValue: { port: 3000, host: 'localhost' },
});

container.register(PinoLogger);
container.register({
  provide: ILogger, // ILogger로 resolve해도 PinoLogger 인스턴스가 반환된다
  useExisting: PinoLogger,
});

container.register(
  { provide: 'MIDDLEWARE', useClass: LoggingMiddleware, multi: true },
  { provide: 'MIDDLEWARE', useClass: AuthMiddleware, multi: true },
  { provide: 'MIDDLEWARE', useClass: CorsMiddleware, multi: true },
);

const middlewares = await container.resolve('MIDDLEWARE');
// → [LoggingMiddleware 인스턴스, AuthMiddleware 인스턴스, CorsMiddleware 인스턴스]

private readonly registrations = new Map<Token, NormalizedProvider>();
private readonly multiRegistrations = new Map<Token, NormalizedProvider[]>();

// packages/di/src/types.ts
export interface NormalizedProvider<T = unknown> {
  inject: Array<Token | ForwardRefFn | OptionalToken>;
  provide: Token<T>;
  scope: Scope;
  type: 'class' | 'factory' | 'value' | 'existing';
  useClass?: ClassType<T>;
  useFactory?: (...deps: unknown[]) => MaybePromise<T>;
  useValue?: T;
  useExisting?: Token;
  multi?: boolean;
}

// ClassType → inject와 scope를 메타데이터에서 읽어온다
if (isClassConstructor(provider)) {
  const metadata = getClassDiMetadata(provider);

  return {
    inject: (metadata?.inject ?? []).map(normalizeInjectToken),
    provide: provider,
    scope: metadata?.scope ?? Scope.DEFAULT,
    type: 'class',
    useClass: provider,
  };
}

// ClassProvider → inject 우선순위: provider.inject > useClass 메타데이터 > []
if (isClassProvider(provider)) {
  assertObjectProvider(provider);

  if (typeof provider.useClass !== 'function') {
    throw new InvalidProviderError('Class provider useClass must be a constructor.', { token: provider.provide });
  }

  const metadata = getClassDiMetadata(provider.useClass);

  return {
    inject: (provider.inject ?? metadata?.inject ?? []).map(normalizeInjectToken),
    multi: provider.multi,
    provide: provider.provide,
    scope: provider.scope ?? metadata?.scope ?? Scope.DEFAULT,
    type: 'class',
    useClass: provider.useClass,
  };
}