kor-lunar

한국천문연구원(KASI)의 음력·양력 변환 데이터를 기반으로 한 자바스크립트 라이브러리입니다.
네트워크 요청 없이 오프라인에서도 동작하고, 별도의 외부 의존성이 없습니다.

⚠️ 주의: 데이터는 2025년 5월 20일 기준으로 갱신되었습니다.
이후의 중요한 변경 사항이 반영되지 않을 수 있으므로,
중요한 작업에는 아래 한국천문연구원 공식 API를 사용하시기 바랍니다.

특징

• 음력 ↔ 양력 변환 — toLunar, toSolar
• LunarCalendar 클래스 — 음력 날짜 연산 객체 (생성, 연산, 비교)
• 윤달 처리 — isLeapMonth 옵션
• 음력 간지 출력 — 세차(secha), 월건(wolgeon), 일진(iljin)
• TypeScript 지원 — 타입 정의 기본 제공
• Zero Dependencies — 외부 의존성 없음
• CJS / ESM / UMD — 다양한 환경에서 사용 가능

예제 사이트

지원 날짜 범위

| 함수 | 범위 | | ----------------------- | ---------------------------------- | | toLunar (양력 → 음력) | 1890년 1월 21일 ~ 2050년 12월 31일 | | toSolar (음력 → 양력) | 1890년 1월 1일 ~ 2050년 11월 18일 |

범위를 벗어난 날짜가 입력될 경우 RangeError가 발생합니다.

설치

npm install kor-lunar

브라우저 CDN

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/kor-lunar.min.js"></script>

CDN 사용 시 전역 변수 korLunar로 접근할 수 있습니다.
예기치 않은 변경을 방지하기 위해 메이저 버전을 고정하는 것을 권장합니다.

사용법

모듈 불러오기

import korLunar from "kor-lunar";
// 또는
const korLunar = require("kor-lunar");

Named export도 지원합니다:

import { toLunar, toSolar, LunarCalendar } from "kor-lunar";

양력 → 음력 (toLunar)

import { toLunar } from "kor-lunar";

console.log(toLunar(2025, 6, 25));
// {
//   year: 2025,
//   month: 6,
//   day: 1,
//   isLeapMonth: false,
//   secha: '을사',
//   wolgeon: '계미',
//   iljin: '을축',
//   julianDay: 2460852,
//   dayOfWeek: 3
// }

// 윤달인 경우
console.log(toLunar(2025, 7, 25));
// { ..., month: 6, isLeapMonth: true, wolgeon: '' }
// 윤달인 경우 wolgeon은 빈 문자열로 반환됩니다

음력 → 양력 (toSolar)

import { toSolar } from "kor-lunar";

console.log(toSolar(2025, 6, 1, false));
// { year: 2025, month: 6, day: 25 }

console.log(toSolar(2025, 6, 1, true));
// { year: 2025, month: 7, day: 25 }

LunarCalendar

음력 날짜를 다루기 위한 불변(immutable) 클래스입니다.
날짜 연산, 비교, 변환 등을 지원하며,
모든 변경 메서드는 원본을 수정하지 않고 새 객체를 반환합니다.

import { LunarCalendar } from "kor-lunar";

// 음력 날짜로 생성 (2025년 8월 15일, 추석)
const chuseok = LunarCalendar.of(2025, 8, 15);

// 속성 접근
chuseok.year; // 2025
chuseok.month; // 8
chuseok.day; // 15
chuseok.isLeapMonth; // false
chuseok.dayOfWeek; // 0 (일요일)
chuseok.secha; // '을사'
chuseok.wolgeon; // '을유'
chuseok.iljin; // '무신'

// 양력 변환
chuseok.toSolar(); // { year: 2025, month: 10, day: 6 }

// 문자열 표현
chuseok.toString(); // '2025-08-15' (윤달인 경우 2025-윤06-01)

// 날짜 연산 (원본은 변경되지 않음)
const nextDay = chuseok.addDays(1);
const nextMonth = chuseok.addMonths(1);
const nextYear = chuseok.addYears(1);

// 비교
chuseok.isBefore(nextDay); // true
chuseok.equals(chuseok); // true
nextDay.diffDays(chuseok); // 1

korLunar.LunarTable과 korLunar.SolarTable을 통해 내부 유틸 함수에 직접 접근할 수도 있습니다.
이를 통해 더 다양한 기능을 구현할 수 있습니다 — 예제: 음력 달력

기여

버그 제보, 기능 제안, PR 등 모두 환영합니다.

• 🔍 버그 제보 → Issues
• 💡 기능 제안 → Issues 또는 Discussions
• 💬 질문 · 의견 → Discussions

자유롭게 남겨주세요.

라이선스

MIT

출처 및 참고 자료

• 한국천문연구원: https://www.kasi.re.kr
• 공공데이터포털: https://www.data.go.kr/data/15012679/openapi.do