![\"npm](\"https://img.shields.io/npm/v/korean-lunar-calendar.svg\")
\n ![\"MIT](\"https://img.shields.io/badge/license-MIT-blue.svg\"){kind=icon}
\n ![\"TypeScript](\"https://img.shields.io/badge/types-included-blue.svg\"){kind=icon}
\n ![\"Zero](\"https://img.shields.io/badge/deps-zero-success.svg\"){kind=icon}
\n ![\"Live](\"https://img.shields.io/badge/demo-live-success.svg\"){kind=icon}
\n\n Convert between the Korean lunar calendar (음력) and the\n Gregorian solar calendar (양력) — entirely offline, following the\n KARI (Korea Astronomy and Space Science Institute) standard.\n
\n\n\n \n \n \n \n \n
▶ Try the live demo — convert dates in your browser.
\n\n> The Korean and Chinese lunar calendars share the same astronomical basis but can fall on\n> different dates. This library uses the Korean (KARI) standard.\n\n## Features\n\n- **Two-way conversion** — solar → lunar and lunar → solar, in one small class.\n- **Offline** — the conversion table is bundled; no network calls, no external services.\n- **GapJa (간지) strings** — get the sexagenary year/month/day in both Korean (정유년 병오월) and Chinese (丁酉年 丙午月), plus raw cheongan/ganji indices.\n- **Leap-month aware** — handles intercalation months (윤달) and the 1582 Gregorian reform gap.\n- **Input validation** — every setter returns a `boolean`; out-of-range, non-integer, and impossible-leap-month dates are rejected.\n- **Typed & dual-format** — ships TypeScript types, ESM + CommonJS, plus a minified browser build.\n- **Zero runtime dependencies.**\n\n## Supported range\n\n| Calendar | From | To |\n| ----------------- | ------------ | ------------ |\n| Lunar (음력) | `1000-01-01` | `2050-11-18` |\n| Solar (양력) | `1000-02-13` | `2050-12-31` |\n\nDates outside this range cause the corresponding setter to return `false`.\n\n## Install\n\n```bash\nnpm install korean-lunar-calendar\n```\n\n```js\n// ES Modules\nimport KoreanLunarCalendar from \"korean-lunar-calendar\";\n\n// CommonJS\nconst KoreanLunarCalendar = require(\"korean-lunar-calendar\");\n```\n\n```html\n\n\n```\n\n## Usage\n\n### Solar → Lunar (양력 → 음력)\n\n```js\nconst calendar = new KoreanLunarCalendar();\n\n// setSolarDate(year, month, day) → boolean (false if invalid/out of range)\ncalendar.setSolarDate(2017, 6, 24);\n\ncalendar.getLunarCalendar();\n// { year: 2017, month: 5, day: 1, intercalation: true }\n\ncalendar.getKoreanGapja();\n// { year: \"정유년\", month: \"병오월\", day: \"임오일\", intercalation: \"윤월\" }\n\ncalendar.getChineseGapja();\n// { year: \"丁酉年\", month: \"丙午月\", day: \"壬午日\", intercalation: \"閏月\" }\n```\n\n### Lunar → Solar (음력 → 양력)\n\n```js\nconst calendar = new KoreanLunarCalendar();\n\n// setLunarDate(year, month, day, intercalation) → boolean\ncalendar.setLunarDate(1956, 1, 21, false);\n\ncalendar.getSolarCalendar();\n// { year: 1956, month: 3, day: 3 }\n\ncalendar.getKoreanGapja();\n// { year: \"병신년\", month: \"경인월\", day: \"기사일\", intercalation: \"\" }\n```\n\n> Always check the return value of `setSolarDate` / `setLunarDate` before reading the result —\n> the getters reflect the **last successful** set call.\n\n## API\n\n`new KoreanLunarCalendar()` creates a stateful converter. Set a date, then read it back in the\nother calendar.\n\n| Method | Returns | Description |\n| ------ | ------- | ----------- |\n| `setSolarDate(year, month, day)` | `boolean` | Set a Gregorian date. Returns `false` for out-of-range, non-integer, or nonexistent dates. |\n| `setLunarDate(year, month, day, intercalation)` | `boolean` | Set a lunar date. `intercalation` requests the leap month; returns `false` if that month has no leap month. |\n| `getSolarCalendar()` | `CalendarData` | The solar date for the last successful set. |\n| `getLunarCalendar()` | `CalendarData` | The lunar date (includes `intercalation`). |\n| `getKoreanGapja()` | `GapJaData` | Sexagenary cycle in Korean (e.g. `정유년`). |\n| `getChineseGapja()` | `GapJaData` | Sexagenary cycle in Chinese characters (e.g. `丁酉年`). |\n| `getGapja(isChinese?)` | `GapJaData` | GapJa in Korean by default, Chinese when `isChinese` is `true`. |\n| `getGapJaIndex()` | `{ cheongan, ganji }` | Raw 0-based cheongan (천간) and ganji (지지) indices for year/month/day. |\n\n### Types\n\n```ts\ninterface CalendarData {\n year: number;\n month: number;\n day: number;\n intercalation?: boolean; // present on lunar results\n}\n\ninterface GapJaData {\n year: string;\n month: string;\n day: string;\n intercalation?: string; // \"윤월\" / \"閏月\" when the lunar month is a leap month, else \"\"\n}\n```\n\n> `getSolarCalendar()` and `getLunarCalendar()` return a **copy** — mutating the returned object\n> does not affect the converter's internal state.\n\n## Validation\n\nEvery setter validates its input and returns a `boolean`, so you can branch on the result:\n\n```js\nconst calendar = new KoreanLunarCalendar();\n\n// Rejected → return false\ncalendar.setLunarDate(99, 1, 1, false); // before supported range\ncalendar.setSolarDate(2051, 1, 1); // after supported range\ncalendar.setSolarDate(2017, 6, 24.5); // non-integer day\ncalendar.setSolarDate(1582, 10, 8); // skipped by the 1582 Gregorian reform\ncalendar.setLunarDate(2017, 3, 1, true); // month 3 of 2017 has no leap month\n\n// Accepted → return true\ncalendar.setLunarDate(1000, 1, 1, false);\ncalendar.setSolarDate(2050, 12, 31);\n```\n\n## Other languages\n\nThe same library is available for other ecosystems:\n\n- **Java** — [usingsky/KoreanLunarCalendar](https://github.com/usingsky/KoreanLunarCalendar)\n- **Python** — [usingsky/korean_lunar_calendar_py](https://github.com/usingsky/korean_lunar_calendar_py)\n- **JavaScript** — [usingsky/korean_lunar_calendar_js](https://github.com/usingsky/korean_lunar_calendar_js)\n\n## Acknowledgements\n\nConversion data follows the [KARI (Korea Astronomy and Space Science Institute)](https://astro.kasi.re.kr/)\nKorean lunar–solar standard. Many thanks to KARI for publishing the reference tables.\n\n## License\n\nMIT © [Jinil Lee](https://github.com/usingsky)\n","readmeFilename":"README.md"}