koroman/src/koroman.d.ts

KOROMAN: Korean Romanizer with pronunciation rules based on 국립국어원 표기법

declare module 'koroman' {
  export type CasingOption =
    | 'lowercase' | 'lower' | 'l' | 'lc' | 0
    | 'uppercase' | 'upper' | 'u' | 'uc' | 1
    | 'capitalize-line' | 'cap-line' | 'cline' | 'cl' | 2
    | 'capitalize-word' | 'cap-word' | 'cword' | 'cw' | 3;

  export type NormalizedCasingOption = 'lowercase' | 'uppercase' | 'capitalize-line' | 'capitalize-word';

  export interface RomanizeOptions {
    usePronunciationRules?: boolean;
    casingOption?: CasingOption;
    /**
     * 발음상 혼동이 우려되는 음절 경계에 자동으로 붙임표(-)를 삽입한다.
     *  - 종성 ᆼ(ng) + 모음 시작 음절   (예: 중앙 → jung-ang)
     *  - 종성 ᆫ(n)  + ㄱ(g) 시작 음절  (예: 반구대 → ban-gudae)
     *  - 받침 없음   + 모음 시작 음절   (예: 해운대 → hae-undae, 세운 → se-un)
     * 기본값 false.
     */
    useHyphen?: boolean;
    /**
     * 모듈에 미리 등록된 내부 사용자 사전(setCustomDictionary 등으로 관리)을
     * 적용할지 여부. 기본 true. false면 내부 사전을 무시한다.
     * 옵션의 {@link customDictionary} 는 이 값과 무관하게 항상 적용된다.
     */
    useCustomDictionary?: boolean;
    /**
     * 일회성 사용자 사전. 매칭되는 한국어 단어는 지정된 로마자 표기로 최우선 변환된다.
     * 내부 사전이 활성화된 경우 내부 사전과 병합되며, 동일 키는 이 옵션이 우선한다.
     *  - 사전 값은 casing 옵션의 영향을 받지 않음 (사용자 지정 그대로 보존)
     *  - 음운 규칙도 적용되지 않음
     *  - 키 길이가 긴 항목부터 우선 매칭 (부분 매칭 방지)
     *
     * 예: { "김철수": "Kim Chul-soo", "서울": "Seoul" }
     */
    customDictionary?: Record<string, string>;
  }

  export function romanize(str: string, options?: RomanizeOptions): string;
  export function normalizeCasingOption(opt: CasingOption | string | number | null | undefined): NormalizedCasingOption;

  /**
   * 모듈 내부 사용자 사전을 통째로 교체한다.
   * dict가 null/undefined/빈 객체면 전체 비움과 동일.
   */
  export function setCustomDictionary(dict?: Record<string, string> | null): void;

  /**
   * 모듈 내부 사용자 사전에 항목을 추가/병합한다.
   *  - addCustomDictionary({ "김철수": "Kim Chul-soo" })
   *  - addCustomDictionary("김철수", "Kim Chul-soo")
   */
  export function addCustomDictionary(dict: Record<string, string>): void;
  export function addCustomDictionary(key: string, value: string): void;

  /** 내부 사용자 사전에서 키를 제거한다. 제거되었으면 true. */
  export function removeCustomDictionaryEntry(key: string): boolean;

  /** 내부 사용자 사전을 모두 비운다. */
  export function clearCustomDictionary(): void;

  /** 현재 내부 사용자 사전의 스냅샷(얕은 복사)을 반환한다. */
  export function getCustomDictionary(): Record<string, string>;
}