kor-lunar/dist/kor-lunar.d.ts

한국 음력 변환 유틸 / Korean lunar calendar converter

declare const BASE_YEAR$1 = 1890;
declare const BASE_MONTH$1 = 1;
declare const BASE_DAY$1 = 1;
declare const BASE_VALUE$1: number;
declare const MAX_YEAR$1 = 2050;
declare const MAX_MONTH$1 = 11;
declare const MAX_DAY$1 = 18;
declare const MAX_VALUE$1: number;
/**
 * 해당 월 (평달)의 일 수를 반환합니다.
 * @param year 1890년 ~ 2050년
 * @param month 1월 ~ 12월
 * @returns 월의 일 수 (29 또는 30)
 */
declare const getMonthDays$1: (year: number, month: number) => number;
/**
 * 해당 연도의 윤달을 반환합니다.
 * @param year 1890년 ~ 2050년
 * @returns 윤달 월 (1월 ~ 12월), 없으면 0
 */
declare const getLeapMonth: (year: number) => number;
/**
 * 해당 연도에 윤달이 있는지를 반환합니다.
 * @param year 1890년 ~ 2050년
 * @return 윤달이 있으면 true
 */
declare const hasLeapMonth: (year: number) => boolean;
/**
 * 해당 월이 윤달인지를 반환합니다.
 * @param year 1890년 ~ 2050년
 * @param month 1월 ~ 12월
 * @returns 윤달이면 true
 */
declare const isLeapMonth: (year: number, month: number) => boolean;
/**
 * 해당 월 (윤달)의 일 수를 반환합니다.
 * @param year 1890년 ~ 2050년
 * @param month 1월 ~ 12월
 * @returns 윤달의 일 수 (29 또는 30), 윤달이 아니면 0
 */
declare const getLeapMonthDays: (year: number, month: number) => number;
/**
 * 해당 연도의 총 일 수를 반환합니다.
 * @param year 1890년 ~ 2050년
 * @return 해당 연도의 총 일 수
 */
declare const getYearDays$1: (year: number) => number;
/**
 * 1890년부터 해당 연도 전까지의 누적 일 수를 반환합니다.
 * @param year 1890년 ~ 2050년
 * @return 해당 연도 전까지의 누적 일 수
 */
declare const getTotalDaysBeforeYear$1: (year: number) => number;
/**
 * 해당 연도 내에서 해당 월 (및 윤달 포함) 전까지의 누적 일 수를 반환합니다.
 * @param year 1890년 ~ 2050년
 * @param month 1월 ~ 12월
 * @param isLeapMonth 대상이 윤달이면 true
 * @returns 해당 연도 내, 해당 월 전까지의 누적 일 수
 */
declare const getTotalDaysBeforeMonth$1: (year: number, month: number, isLeapMonth: boolean) => number;
/**
 * 1890년부터 해당 연도, 월, 일 (및 윤달 포함) 까지의 누적 일 수를 반환합니다.
 * @param year 1890년 ~ 2050년
 * @param month 1월 ~ 12월
 * @param day 일자
 * @param isLeapMonth 대상이 윤달이면 true
 * @returns 총 누적 일 수
 */
declare const getTotalDays$1: (year: number, month: number, day: number, isLeapMonth: boolean) => number;
/**
 * 해당 연도의 총 월 수를 반환합니다. (윤달 포함)
 * @param year 1890년 ~ 2050년
 * @returns 윤달이 있으면 13, 없으면 12
 */
declare const getMonthCount: (year: number) => number;
/**
 * 1890년부터 해당 연도 전까지의 누적 월 수를 반환합니다. (윤달 포함)
 * @param year 1890년 ~ 2050년
 * @returns 해당 연도 전까지의 누적 월 수
 */
declare const getTotalMonthsBeforeYear: (year: number) => number;
/**
 * 1890년부터 해당 연도, 월 (및 윤달 포함) 까지의 누적 월 수를 반환합니다.
 * @param year 1890년 ~ 2050년
 * @param month 1월 ~ 12월
 * @param isLeapMonth 대상이 윤달이면 true
 * @returns 총 누적 월 수
 */
declare const getTotalMonths: (year: number, month: number, isLeapMonth: boolean) => number;
/**
 * 누적 월 수에서 (year, month, isLeapMonth)를 복원합니다.
 * @param totalMonths 총 누적 월 수
 * @returns year, month, isLeapMonth
 */
declare const fromTotalMonths: (totalMonths: number) => {
    year: number;
    month: number;
    isLeapMonth: boolean;
};
/** 지원하는 최소 julianDay */
declare const BASE_JULIAN_DAY = 2411389;
/** 지원하는 최대 julianDay */
declare const MAX_JULIAN_DAY: number;
declare const getSecha: (year: number) => string;
declare const getWolgeon: (year: number, month: number) => string;
declare const getIljinByJulianDay: (julianDay: number) => string;
declare const getIljin: (year: number, month: number, day: number, isLeapMonth: boolean) => string;
/**
 * 날짜가 지원하는 범위 내에 있는지를 반환합니다.
 * 날짜의 유효성 (존재 여부)은 검사하지 않습니다.
 * @returns 날짜가 범위 내에 있으면 true
 */
declare const isDateInRange$1: (year: number, month: number, day: number) => boolean;
/**
 * 실제로 존재하는 유효한 날짜인지를 반환합니다.
 * @returns 유효한 날짜이면 true
 */
declare const isValidDate$1: (year: number, month: number, day: number, isLeapMonth: boolean) => boolean;
/**
 * 해당 월의 0-based 연속적인 월 인덱스를 반환합니다.
 * @param year 1890년 ~ 2050년
 * @param month 1월 ~ 12월
 * @param isLeapMonth 대상이 윤달이면 true
 * @returns 윤달이 있는 해는 0 ~ 12 (13개월), 없는 해는 0 ~ 11 (12개월)
 */
declare const getMonthIndex: (year: number, month: number, isLeapMonth: boolean) => number;
/**
 * 0-based 연속적인 월 인덱스에 해당하는 월과 윤달 여부를 반환합니다.
 * @param year 1890년 ~ 2050년
 * @param monthIndex 윤달이 있는 해는 0 ~ 12 (13개월), 없는 해는 0 ~ 11 (12개월)
 * @returns month (1~12)와 isLeapMonth 여부
 */
declare const getMonthFromIndex: (year: number, monthIndex: number) => {
    month: number;
    isLeapMonth: boolean;
};

declare const LunarTable_BASE_JULIAN_DAY: typeof BASE_JULIAN_DAY;
declare const LunarTable_MAX_JULIAN_DAY: typeof MAX_JULIAN_DAY;
declare const LunarTable_fromTotalMonths: typeof fromTotalMonths;
declare const LunarTable_getIljin: typeof getIljin;
declare const LunarTable_getIljinByJulianDay: typeof getIljinByJulianDay;
declare const LunarTable_getLeapMonth: typeof getLeapMonth;
declare const LunarTable_getLeapMonthDays: typeof getLeapMonthDays;
declare const LunarTable_getMonthCount: typeof getMonthCount;
declare const LunarTable_getMonthFromIndex: typeof getMonthFromIndex;
declare const LunarTable_getMonthIndex: typeof getMonthIndex;
declare const LunarTable_getSecha: typeof getSecha;
declare const LunarTable_getTotalMonths: typeof getTotalMonths;
declare const LunarTable_getTotalMonthsBeforeYear: typeof getTotalMonthsBeforeYear;
declare const LunarTable_getWolgeon: typeof getWolgeon;
declare const LunarTable_hasLeapMonth: typeof hasLeapMonth;
declare const LunarTable_isLeapMonth: typeof isLeapMonth;
declare namespace LunarTable {
  export {
    BASE_DAY$1 as BASE_DAY,
    LunarTable_BASE_JULIAN_DAY as BASE_JULIAN_DAY,
    BASE_MONTH$1 as BASE_MONTH,
    BASE_VALUE$1 as BASE_VALUE,
    BASE_YEAR$1 as BASE_YEAR,
    MAX_DAY$1 as MAX_DAY,
    LunarTable_MAX_JULIAN_DAY as MAX_JULIAN_DAY,
    MAX_MONTH$1 as MAX_MONTH,
    MAX_VALUE$1 as MAX_VALUE,
    MAX_YEAR$1 as MAX_YEAR,
    LunarTable_fromTotalMonths as fromTotalMonths,
    LunarTable_getIljin as getIljin,
    LunarTable_getIljinByJulianDay as getIljinByJulianDay,
    LunarTable_getLeapMonth as getLeapMonth,
    LunarTable_getLeapMonthDays as getLeapMonthDays,
    LunarTable_getMonthCount as getMonthCount,
    getMonthDays$1 as getMonthDays,
    LunarTable_getMonthFromIndex as getMonthFromIndex,
    LunarTable_getMonthIndex as getMonthIndex,
    LunarTable_getSecha as getSecha,
    getTotalDays$1 as getTotalDays,
    getTotalDaysBeforeMonth$1 as getTotalDaysBeforeMonth,
    getTotalDaysBeforeYear$1 as getTotalDaysBeforeYear,
    LunarTable_getTotalMonths as getTotalMonths,
    LunarTable_getTotalMonthsBeforeYear as getTotalMonthsBeforeYear,
    LunarTable_getWolgeon as getWolgeon,
    getYearDays$1 as getYearDays,
    LunarTable_hasLeapMonth as hasLeapMonth,
    isDateInRange$1 as isDateInRange,
    LunarTable_isLeapMonth as isLeapMonth,
    isValidDate$1 as isValidDate,
  };
}

declare const BASE_YEAR = 1890;
declare const BASE_MONTH = 1;
declare const BASE_DAY = 21;
declare const BASE_VALUE: number;
declare const MAX_YEAR = 2050;
declare const MAX_MONTH = 12;
declare const MAX_DAY = 31;
declare const MAX_VALUE: number;
declare const isLeapYear: (year: number) => boolean;
declare const getMonthDays: (year: number, month: number) => number;
declare const getYearDays: (year: number) => number;
declare const getTotalDaysBeforeYear: (year: number) => number;
declare const getTotalDaysBeforeMonth: (year: number, month: number) => number;
declare const getTotalDays: (year: number, month: number, day: number) => number;
/**
 * 날짜가 지원하는 범위 내에 있는지를 반환합니다.
 * 날짜의 유효성 (존재 여부)은 검사하지 않습니다.
 * @returns 날짜가 범위 내에 있으면 true
 */
declare const isDateInRange: (year: number, month: number, day: number) => boolean;
/**
 * 실제로 존재하는 유효한 날짜인지를 반환합니다.
 * @returns 유효한 날짜이면 true
 */
declare const isValidDate: (year: number, month: number, day: number) => boolean;

declare const SolarTable_BASE_DAY: typeof BASE_DAY;
declare const SolarTable_BASE_MONTH: typeof BASE_MONTH;
declare const SolarTable_BASE_VALUE: typeof BASE_VALUE;
declare const SolarTable_BASE_YEAR: typeof BASE_YEAR;
declare const SolarTable_MAX_DAY: typeof MAX_DAY;
declare const SolarTable_MAX_MONTH: typeof MAX_MONTH;
declare const SolarTable_MAX_VALUE: typeof MAX_VALUE;
declare const SolarTable_MAX_YEAR: typeof MAX_YEAR;
declare const SolarTable_getMonthDays: typeof getMonthDays;
declare const SolarTable_getTotalDays: typeof getTotalDays;
declare const SolarTable_getTotalDaysBeforeMonth: typeof getTotalDaysBeforeMonth;
declare const SolarTable_getTotalDaysBeforeYear: typeof getTotalDaysBeforeYear;
declare const SolarTable_getYearDays: typeof getYearDays;
declare const SolarTable_isDateInRange: typeof isDateInRange;
declare const SolarTable_isLeapYear: typeof isLeapYear;
declare const SolarTable_isValidDate: typeof isValidDate;
declare namespace SolarTable {
  export {
    SolarTable_BASE_DAY as BASE_DAY,
    SolarTable_BASE_MONTH as BASE_MONTH,
    SolarTable_BASE_VALUE as BASE_VALUE,
    SolarTable_BASE_YEAR as BASE_YEAR,
    SolarTable_MAX_DAY as MAX_DAY,
    SolarTable_MAX_MONTH as MAX_MONTH,
    SolarTable_MAX_VALUE as MAX_VALUE,
    SolarTable_MAX_YEAR as MAX_YEAR,
    SolarTable_getMonthDays as getMonthDays,
    SolarTable_getTotalDays as getTotalDays,
    SolarTable_getTotalDaysBeforeMonth as getTotalDaysBeforeMonth,
    SolarTable_getTotalDaysBeforeYear as getTotalDaysBeforeYear,
    SolarTable_getYearDays as getYearDays,
    SolarTable_isDateInRange as isDateInRange,
    SolarTable_isLeapYear as isLeapYear,
    SolarTable_isValidDate as isValidDate,
  };
}

interface LunarDate {
    year: number;
    month: number;
    day: number;
    isLeapMonth: boolean;
    secha: string;
    wolgeon: string;
    iljin: string;
    julianDay: number;
    dayOfWeek: number;
}
interface SolarDate {
    year: number;
    month: number;
    day: number;
}
/**
 * 양력을 음력으로 변환합니다.
 * 양력 지원 날짜 범위: 1890년 1월 21일 ~ 2050년 12월 31일
 * 날짜의 유효성(존재 여부)은 검사하지 않습니다.
 * @param solYear 양력 연도
 * @param solMonth 양력 월
 * @param solDay 양력 일
 * @returns 음력 날짜
 */
declare const toLunar: (solYear: number, solMonth: number, solDay: number) => LunarDate;
/**
 * 음력을 양력으로 변환합니다.
 * 음력 지원 날짜 범위: 1890년 1월 1일 ~ 2050년 11월 18일
 * 날짜의 유효성(존재 여부)은 검사하지 않습니다.
 * @param lunYear 음력 연도
 * @param lunMonth 음력 월
 * @param lunDay 음력 일
 * @param isLeapMonth 음력 윤달 여부, 윤달이면 true
 * @returns 양력 날짜
 */
declare const toSolar: (lunYear: number, lunMonth: number, lunDay: number, isLeapMonth: boolean) => SolarDate;
/**
 * julianDay(율리우스 일)를 음력으로 변환합니다.
 * julianDay 지원 범위: 2411389 ~ 2470379
 * @param julianDay 율리우스 일
 * @returns 음력 날짜
 */
declare const fromJulianDay: (julianDay: number) => LunarDate;

/** @deprecated `LunarData`는 `LunarTable`로 이름이 변경되었습니다. */
declare const LunarData: typeof LunarTable;
/** @deprecated `SolarData`는 `SolarTable`로 이름이 변경되었습니다. */
declare const SolarData: typeof SolarTable;

/**
 * 음력 날짜를 다루는 불변(immutable) 캘린더 클래스입니다.
 *
 * @experimental 이 클래스는 실험적입니다.
 * 설계에 고민 중인 게 많아서
 * 향후 마이너 버전에서 API(메서드, 반환값, 클래스 이름)가
 * 변경되거나 제거될 수 있습니다.
 */
declare class LunarCalendar {
    private readonly _julianDay;
    private _cache?;
    private constructor();
    /**
     * 음력 날짜로 생성합니다.
     * @param year 음력 연도 (1890 ~ 2050)
     * @param month 음력 월 (1 ~ 12)
     * @param day 음력 일
     * @param isLeapMonth 윤달 여부 (기본값: false)
     * @returns 음력 날짜 객체
     */
    static of(year: number, month: number, day: number, isLeapMonth?: boolean): LunarCalendar;
    /**
     * LunarDate 객체에서 생성합니다.
     * @param lunarDate 음력 날짜 객체
     * @returns 음력 날짜 객체
     */
    static from(lunarDate: LunarDate): LunarCalendar;
    /**
     * 양력 날짜로 생성합니다.
     * @param year 양력 연도
     * @param month 양력 월
     * @param day 양력 일
     * @returns 음력 날짜 객체
     */
    static fromSolar(year: number, month: number, day: number): LunarCalendar;
    /**
     * julianDay(율리우스 일)로 생성합니다.
     * @param julianDay 율리우스 일
     * @returns 음력 날짜 객체
     */
    static fromJulianDay(julianDay: number): LunarCalendar;
    /**
     * 오늘의 음력 날짜를 반환합니다.
     * @returns 오늘의 음력 날짜 객체
     */
    static today(): LunarCalendar;
    private _resolve;
    /** 음력 연도 */
    get year(): number;
    /** 음력 월 (1 ~ 12) */
    get month(): number;
    /** 음력 일 */
    get day(): number;
    /** 윤달 여부 */
    get isLeapMonth(): boolean;
    /** 율리우스 일 */
    get julianDay(): number;
    /** 요일 (0: 일요일 ~ 6: 토요일) */
    get dayOfWeek(): number;
    /** 세차 (예: "을사") */
    get secha(): string;
    /** 월건 (윤달이면 빈 문자열) */
    get wolgeon(): string;
    /** 일진 */
    get iljin(): string;
    /**
     * 일 수를 더한 새 음력 날짜를 반환합니다.
     * @param days 더할 일 수 (음수면 빼기)
     * @returns 새 음력 날짜 객체
     */
    addDays(days: number): LunarCalendar;
    /**
     * 월 수를 더한 새 음력 날짜를 반환합니다.
     * 윤달도 하나의 독립적인 월로 취급합니다.
     * 대상 월의 일수가 현재 일보다 적으면 마지막 날로 클램핑됩니다.
     * @param months 더할 월 수 (음수이면 빼기)
     * @returns 새 음력 날짜 객체
     */
    addMonths(months: number): LunarCalendar;
    /**
     * 연 수를 더한 새 음력 날짜를 반환합니다.
     * 같은 월/일을 유지하려 시도하며, 윤달이 대상 연도에 없으면 평달로 폴백합니다.
     * 대상 월의 일수가 현재 일보다 적으면 마지막 날로 클램핑됩니다.
     * @param years 더할 연 수 (음수이면 빼기)
     * @returns 새 음력 날짜 객체
     */
    addYears(years: number): LunarCalendar;
    /**
     * 양력 날짜로 변환합니다.
     * @returns 양력 날짜
     */
    toSolar(): SolarDate;
    /**
     * LunarDate 인터페이스로 변환합니다.
     * @returns 음력 날짜
     */
    toLunarDate(): LunarDate;
    /**
     * 두 음력 날짜가 같은 날인지 비교합니다.
     * @returns 같은 날이면 true
     */
    equals(other: LunarCalendar): boolean;
    /**
     * 이 날짜가 other보다 이전인지 비교합니다.
     * @returns 이전이면 true
     */
    isBefore(other: LunarCalendar): boolean;
    /**
     * 이 날짜가 other보다 이후인지 비교합니다.
     * @returns 이후이면 true
     */
    isAfter(other: LunarCalendar): boolean;
    /**
     * 두 날짜 사이의 일수 차이를 반환합니다.
     * this가 other보다 이후이면 양수, 이전이면 음수를 반환합니다.
     * @returns 일수 차이
     */
    diffDays(other: LunarCalendar): number;
    /**
     * @experimental 출력 형식이 변경될 수 있습니다.
     * 음력 날짜의 문자열 표현을 반환합니다.
     * 평달인 경우: "2025-08-15"
     * 윤달인 경우: "2025-윤06-01"
     * @returns 음력 날짜의 문자열 표현
     */
    toString(): string;
    /**
     * @experimental 출력 형식이 변경될 수 있습니다.
     * 한국 전통 방식으로 음력 날짜를 읽기 쉽게 문자열로 반환합니다.
     * 예: "을사년 정월 보름", "갑진년 윤삼월 초하루"
     * @returns 한국 전통 방식의 음력 날짜 문자열 표현
     */
    toTraditionalString(): string;
}

declare const korLunar: {
    toLunar: (solYear: number, solMonth: number, solDay: number) => LunarDate;
    toSolar: (lunYear: number, lunMonth: number, lunDay: number, isLeapMonth: boolean) => SolarDate;
    fromJulianDay: (julianDay: number) => LunarDate;
    LunarTable: typeof LunarTable;
    SolarTable: typeof SolarTable;
    LunarData: typeof LunarTable;
    SolarData: typeof SolarTable;
    LunarCalendar: typeof LunarCalendar;
};

export { LunarCalendar, LunarData, LunarTable, SolarData, SolarTable, korLunar as default, fromJulianDay, toLunar, toSolar };
export type { LunarDate, SolarDate };