The Korean and Chinese lunar calendars share the same astronomical basis but can fall on different dates. This library uses the Korean (KARI) standard.

Features

• Two-way conversion — solar → lunar and lunar → solar, in one small class.
• Offline — the conversion table is bundled; no network calls, no external services.
• GapJa (간지) strings — get the sexagenary year/month/day in both Korean (정유년 병오월) and Chinese (丁酉年 丙午月), plus raw cheongan/ganji indices.
• Leap-month aware — handles intercalation months (윤달) and the 1582 Gregorian reform gap.
• Input validation — every setter returns a boolean; out-of-range, non-integer, and impossible-leap-month dates are rejected.
• Typed & dual-format — ships TypeScript types, ESM + CommonJS, plus a minified browser build.
• Zero runtime dependencies.

Supported range

| Calendar | From | To | | ----------------- | ------------ | ------------ | | Lunar (음력) | 1000-01-01 | 2050-11-18 | | Solar (양력) | 1000-02-13 | 2050-12-31 |

Dates outside this range cause the corresponding setter to return false.

Install

npm install korean-lunar-calendar

// ES Modules
import KoreanLunarCalendar from "korean-lunar-calendar";

// CommonJS
const KoreanLunarCalendar = require("korean-lunar-calendar");

<!-- Browser (CDN) -->
<script src="https://cdn.jsdelivr.net/npm/korean-lunar-calendar/dist/korean-lunar-calendar.min.js"></script>

Usage

Solar → Lunar (양력 → 음력)

const calendar = new KoreanLunarCalendar();

// setSolarDate(year, month, day) → boolean (false if invalid/out of range)
calendar.setSolarDate(2017, 6, 24);

calendar.getLunarCalendar();
// { year: 2017, month: 5, day: 1, intercalation: true }

calendar.getKoreanGapja();
// { year: "정유년", month: "병오월", day: "임오일", intercalation: "윤월" }

calendar.getChineseGapja();
// { year: "丁酉年", month: "丙午月", day: "壬午日", intercalation: "閏月" }

Lunar → Solar (음력 → 양력)

const calendar = new KoreanLunarCalendar();

// setLunarDate(year, month, day, intercalation) → boolean
calendar.setLunarDate(1956, 1, 21, false);

calendar.getSolarCalendar();
// { year: 1956, month: 3, day: 3 }

calendar.getKoreanGapja();
// { year: "병신년", month: "경인월", day: "기사일", intercalation: "" }

Always check the return value of setSolarDate / setLunarDate before reading the result — the getters reflect the last successful set call.

API

new KoreanLunarCalendar() creates a stateful converter. Set a date, then read it back in the other calendar.

| Method | Returns | Description | | ------ | ------- | ----------- | | setSolarDate(year, month, day) | boolean | Set a Gregorian date. Returns false for out-of-range, non-integer, or nonexistent dates. | | setLunarDate(year, month, day, intercalation) | boolean | Set a lunar date. intercalation requests the leap month; returns false if that month has no leap month. | | getSolarCalendar() | CalendarData | The solar date for the last successful set. | | getLunarCalendar() | CalendarData | The lunar date (includes intercalation). | | getKoreanGapja() | GapJaData | Sexagenary cycle in Korean (e.g. 정유년). | | getChineseGapja() | GapJaData | Sexagenary cycle in Chinese characters (e.g. 丁酉年). | | getGapja(isChinese?) | GapJaData | GapJa in Korean by default, Chinese when isChinese is true. | | getGapJaIndex() | { cheongan, ganji } | Raw 0-based cheongan (천간) and ganji (지지) indices for year/month/day. |

Types

interface CalendarData {
  year: number;
  month: number;
  day: number;
  intercalation?: boolean; // present on lunar results
}

interface GapJaData {
  year: string;
  month: string;
  day: string;
  intercalation?: string; // "윤월" / "閏月" when the lunar month is a leap month, else ""
}

getSolarCalendar() and getLunarCalendar() return a copy — mutating the returned object does not affect the converter's internal state.

Validation

Every setter validates its input and returns a boolean, so you can branch on the result:

const calendar = new KoreanLunarCalendar();

// Rejected → return false
calendar.setLunarDate(99, 1, 1, false);   // before supported range
calendar.setSolarDate(2051, 1, 1);        // after supported range
calendar.setSolarDate(2017, 6, 24.5);     // non-integer day
calendar.setSolarDate(1582, 10, 8);       // skipped by the 1582 Gregorian reform
calendar.setLunarDate(2017, 3, 1, true);  // month 3 of 2017 has no leap month

// Accepted → return true
calendar.setLunarDate(1000, 1, 1, false);
calendar.setSolarDate(2050, 12, 31);

Other languages

The same library is available for other ecosystems:

• Java — usingsky/KoreanLunarCalendar
• Python — usingsky/korean_lunar_calendar_py
• JavaScript — usingsky/korean_lunar_calendar_js

Acknowledgements

Conversion data follows the KARI (Korea Astronomy and Space Science Institute) Korean lunar–solar standard. Many thanks to KARI for publishing the reference tables.

License

MIT © Jinil Lee