kor-lunar 1.5.4 → 1.6.0

package/README.md

@@ -13,12 +13,13 @@
 
 ## 특징
 
-- **음력 ↔ 양력 변환** - `toLunar`, `toSolar`
-- **윤달 처리** - `isLeapMonth` 옵션
-- **음력 간지 출력** - 세차(`secha`), 월건(`wolgeon`), 일진(`iljin`)
+- **음력 ↔ 양력 변환** — `toLunar`, `toSolar`
+- **LunarCalendar 클래스** — 음력 날짜 연산 객체 (생성, 연산, 비교)
+- **윤달 처리** — `isLeapMonth` 옵션
+- **음력 간지 출력** — 세차(`secha`), 월건(`wolgeon`), 일진(`iljin`)
   - 윤달인 경우 `wolgeon`은 빈 문자열로 반환됩니다
-- **TypeScript 지원** - 타입 정의 기본 제공
-- **Zero Dependencies** - 외부 의존성 없음
+- **TypeScript 지원** — 타입 정의 기본 제공
+- **Zero Dependencies** — 외부 의존성 없음
 - **CJS / ESM / UMD** — 다양한 환경에서 사용 가능
 
 - [예제 사이트](https://kahyou22.github.io/kor-lunar-js/)
@@ -39,7 +40,7 @@ npm install kor-lunar
 ### 브라우저 CDN
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/kor-lunar@1.5/dist/kor-lunar.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/kor-lunar@1.6/dist/kor-lunar.min.js"></script>
 ```
 
 CDN 사용 시 전역 변수 `korLunar`로 접근할 수 있습니다.
@@ -57,18 +58,21 @@ const korLunar = require("kor-lunar");
 Named export도 지원합니다:
 
 ```js
-import { toLunar, toSolar } from "kor-lunar";
+import { toLunar, toSolar, LunarCalendar } from "kor-lunar";
 ```
 
+---
+
 ## 예제
 
 [예제 사이트](https://kahyou22.github.io/kor-lunar-js/)
 
+### 양력 → 음력 (`toLunar`)
+
 ```js
-import korLunar from "kor-lunar";
+import { toLunar } from "kor-lunar";
 
-// 양력 → 음력
-console.log(korLunar.toLunar(2025, 6, 25));
+console.log(toLunar(2025, 6, 25));
 // {
 //   year: 2025,
 //   month: 6,
@@ -80,9 +84,12 @@ console.log(korLunar.toLunar(2025, 6, 25));
 //   julianDay: 2460852,
 //   dayOfWeek: 3
 // }
+```
 
-// 양력 → 음력 (윤달)
-console.log(korLunar.toLunar(2025, 7, 25));
+### 양력 → 음력 (윤달)
+
+```js
+console.log(toLunar(2025, 7, 25));
 // {
 //   year: 2025,
 //   month: 6,
@@ -94,12 +101,17 @@ console.log(korLunar.toLunar(2025, 7, 25));
 //   julianDay: 2460882,
 //   dayOfWeek: 5
 // }
+```
 
-// 음력 → 양력
-console.log(korLunar.toSolar(2025, 6, 1, false));
+### 음력 → 양력 (`toSolar`)
+
+```js
+import { toSolar } from "kor-lunar";
+
+console.log(toSolar(2025, 6, 1, false));
 // { year: 2025, month: 6, day: 25 }
 
-console.log(korLunar.toSolar(2025, 6, 1, true));
+console.log(toSolar(2025, 6, 1, true));
 // { year: 2025, month: 7, day: 25 }
 ```
 
@@ -107,6 +119,78 @@ console.log(korLunar.toSolar(2025, 6, 1, true));
 > 이를 통해 단순 음력 변환 뿐만 아니라, 더 다양한 기능을 구현할 수 있습니다.  
 > [예제 사이트: 음력 달력](https://kahyou22.github.io/kor-lunar-js/#lunarCalendar)
 
+---
+
+## LunarCalendar
+
+음력 날짜를 다루기 위한 **불변(immutable) 클래스**입니다.  
+날짜 연산, 비교, 변환 등을 지원하며, 모든 변경 메서드는 원본을 수정하지 않고 새 객체를 반환합니다.
+
+### 예제
+
+```js
+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
+```
+
+#### addMonths 동작 방식
+
+- 윤달도 하나의 독립적인 월로 취급합니다
+- 대상 월의 일수가 현재 일보다 적으면 마지막 날로 클램핑됩니다
+
+```js
+// 2025년에는 윤6월이 있음
+const june = LunarCalendar.of(2025, 6, 1); // 6월 평달
+const leapJune = june.addMonths(1); // 6월 윤달
+const july = june.addMonths(2); // 7월 평달
+
+// day 클램핑: 1월 30일 + 1개월 -> 2월의 마지막 날
+const jan30 = LunarCalendar.of(2025, 1, 30);
+const feb = jan30.addMonths(1);
+feb.day; // 29 (2025년 음력 2월이 29일까지인 경우)
+```
+
+#### addYears 동작 방식
+
+- 같은 월/일을 유지하려 시도합니다
+- 윤달인데 대상 연도에 해당 윤달이 없으면 평달로 폴백합니다
+- 대상 월의 일수가 현재 일보다 적으면 마지막 날로 클램핑됩니다
+
+```js
+// 윤달 → 대상 연도에 해당 윤달이 없으면 평달로
+const leapJune = LunarCalendar.of(2025, 6, 1, true);
+const nextYear = leapJune.addYears(1);
+nextYear.isLeapMonth; // false (2026년에 윤6월이 없으므로 평달)
+```
+
 ## 라이선스
 
 [MIT](LICENSE)