chinese-lunar-date

고정밀 음력 라이브러리 — 간지 · 띠 · 절기 · 명절 · 포맷 · 다국어

천문 알고리즘 기반 음력 계산. 중국·일본·한국·베트남 4종 음력 변형 및 간체중국어·번체중국어(대만/홍콩)·日本語·한국어·Tiếng Việt 6개 언어 지원.

Copyright (c) 2025 北京锋通科技有限公司 (郭玉峰, 吴琼). MIT License.

import { ChineseDate } from 'chinese-lunar-date'

const date = ChineseDate.fromGregorian(2024, 6, 21)

date.yearGanZhi    // "甲辰"
date.zodiac        // "용"
date.zodiacEmoji   // "🐉"
date.formatFull()  // "갑진용년 5월초육"

본 프로젝트의 독창성

• 자체 개발 경량 천문 모듈 — VSOP87 행성 이론 절단 데이터(1e-7 임계값, 220/2564항만 유지) 기반. 무거운 astronomia 라이브러리 대체. IIFE 크기를 ~350 KB에서 ~47 KB(gzip ~16 KB)로 축소하면서 정밀도 무손실
• 4종 역법 통일 아키텍처 — 중/일/한/베 4종 음력 변형을 CalendarConfig로 설정 구동. 서로 다른 기원과 시간대 이력에 동일 알고리즘 적용
• 불변 값 객체 + 순수 함수 듀얼 모드 — 고수준 API(ChineseDate 등)는 불변 값 객체, 저수준 알고리즘은 모두 순수 함수. 두 모드를 독립적으로 사용 가능
• 번체중국어 지역 차별화 — zh-TW와 zh-HK는 글자뿐만 아니라 명절명도 구분(예: 「春節/農曆新年」). 단순 번간 변환이 아님

왜 chinese-lunar-date를 선택하는가?

특징

• 천문급 정밀도 — VSOP87 행성 이론 기반 자체 개발 경량 천문 모듈
• 불변 값 객체 — 인스턴스 생성 후 변경 불가. with() / addDays()는 새 인스턴스 반환
• 간지 — 연주·월주·일주, 육십갑자 번호와 문자열 상호 변환
• 띠 — 12띠 다국어 명칭 + Emoji
• 24절기 — 일 단위 정밀도로 절기 계산, 중기와 절기 구분
• 전통 명절 — 13종 내장 명절, 지역별 자동 필터
• 다국어 / 다지역 — zh-CN / zh-TW / zh-HK / ja-JP / ko-KR / vi-VN
• 포맷 — 5종 내장 + 커스텀 패턴 문자열
• 다역법 — 중 / 일 / 한 / 베 4종 역법 설정(다른 기원, 다른 시간대 이력)
• TypeScript 우선 — 완전 타입 정의, ESM / CJS / IIFE 출력
• 경량 — IIFE 압축 후 단 ~47 KB(gzip ~16 KB)

설치

npm install chinese-lunar-date

빠른 시작

날짜 생성

import { ChineseDate } from 'chinese-lunar-date'

const date = ChineseDate.fromGregorian(2024, 6, 21)
const date2 = ChineseDate.fromDate(new Date(2024, 5, 21))
const today = ChineseDate.today()
const date3 = ChineseDate.fromValue({ cycle: 78, year: 34, month: 5, leap: false, day: 6 })

속성 읽기

const date = ChineseDate.fromGregorian(2024, 6, 21)

date.cycle           // 78
date.year            // 34
date.month           // 5
date.leap            // false
date.day             // 6
date.gregorianYear   // 2024

date.yearGanZhi      // "甲辰"
date.monthGanZhi     // "庚午"
date.dayGanZhi       // "甲寅"

date.zodiac          // "용"
date.zodiacEmoji     // "🐉"
date.zodiacIndex     // 4

포맷

const date = ChineseDate.fromGregorian(2024, 6, 21)

date.formatFull('ko-KR')   // "갑진용년 5월초육"
date.formatGanZhi()        // "甲辰年 庚午月 甲寅日"
date.formatCompact()       // "78/34/5/0/6"
date.format('{Ygz}{Z}년 {Mname}{Dname}', 'ko-KR')  // "갑진용년 5월초육"

날짜 연산

const date = ChineseDate.fromGregorian(2024, 6, 21)

const tomorrow = date.addDays(1)
const yesterday = date.addDays(-1)
const firstDay = date.with({ day: 1 })
tomorrow.isAfter(date)     // true

변환

const date = ChineseDate.fromGregorian(2024, 6, 21)

date.toGregorian()  // { year: 2024, month: 6, day: 21 }
date.toDate()       // Date object
date.toJSON()       // { cycle: 78, year: 34, month: 5, leap: false, day: 6 }

다역법

import { ChineseDate, JapaneseDate, KoreanDate, VietnameseDate } from 'chinese-lunar-date'

const cn = ChineseDate.fromGregorian(2024, 6, 21)    // UTC+8
const jp = JapaneseDate.fromGregorian(2024, 6, 21)   // UTC+9
const kr = KoreanDate.fromGregorian(2024, 6, 21)     // UTC+8:30/9, 단군기원
const vn = VietnameseDate.fromGregorian(2024, 6, 21) // UTC+7/8

참고: 시간대 차이로 인해 같은 양력 날짜가 다른 역법에서 다른 음력 날짜에 해당할 수 있습니다.

24절기

import { ChineseDate, solarTermName } from 'chinese-lunar-date'

ChineseDate.solarTerm(5, 2024)   // 청명
solarTermName(3, 'ko-KR')       // "경칩"

const date = ChineseDate.fromGregorian(2024, 4, 4)
date.getSolarTermName('ko-KR')  // "청명"

전통 명절

import { ChineseDate } from 'chinese-lunar-date'

ChineseDate.festivalDate('spring', 2024)      // 춘절
ChineseDate.festivalsInYear(2024, 'ko-KR')

다국어 / 다지역

import { getLocale, availableLocales } from 'chinese-lunar-date'

const loc = getLocale('ko-KR')
loc.zodiac        // ["쥐", "소", "호랑이", "토끼", "용", "뱀", "말", "양", "원숭이", "닭", "개", "돼지"]
loc.solarTerms    // ["입춘", "우수", "경칩", ...]

포맷 Token

전체 Token 목록은사용 안내서를 참조하세요.

브라우저 사용 (IIFE)

<script src="dist/chinese-lunar-date.iife.js"></script>
<script>
  const date = ChineseDate.ChineseDate.fromGregorian(2024, 6, 21)
  console.log(date.formatFull('ko-KR'))  // "갑진용년 5월초육"
</script>

빌드

npm install chinese-lunar-date
npm run build        # ESM + CJS + IIFE 컴파일
npm run build:types  # .d.ts 타입 선언 생성
npm run test         # 테스트 실행

피드백 및 협력

사용 중 문제가 발생하거나 기능 제안, 비즈니스 협력 등이 필요하신 경우 이메일로 연락해 주세요：

📧 gyfinjava@163.com

License

MIT License

Copyright (c) 2025 北京锋通科技有限公司 (郭玉峰, 吴琼)