@gracefullight/saju 0.1.0

package/README.md

@@ -0,0 +1,665 @@
+# @gracefullight/saju
+
+> 유연한 날짜 어댑터를 지원하는 사주(四柱命理) 계산 TypeScript 라이브러리
+
+[![npm version](https://img.shields.io/npm/v/@gracefullight/saju.svg)](https://www.npmjs.com/package/@gracefullight/saju)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**한국어** | [English](./README.en.md)
+
+## 주요 기능
+
+- **정확한 사주 계산** - 천문학적 정밀도로 전통 중국 역법 알고리즘 구현
+- **유연한 날짜 어댑터 패턴** - Luxon, date-fns 또는 원하는 날짜 라이브러리 사용 가능
+- **타임존 & 위치 지원** - 타임존 및 지리적 좌표 적절히 처리
+- **태양시 보정** - 경도 기반 평균 태양시 조정 옵션
+- **트리쉐이킹 지원** - 필요한 것만 import
+- **완전한 타입 지원** - TypeScript 정의 완비
+- **충분한 테스트** - 85개 이상 테스트, 91% 이상 커버리지
+
+## 사주(四柱)란?
+
+사주(四柱), 또는 사주명리는 출생 연월일시를 기반으로 한 전통 한국/중국 운명 분석 시스템입니다. 각 기둥은 다음으로 구성됩니다:
+- **천간(天干)**: 10개 원소 (甲乙丙丁戊己庚辛壬癸)
+- **지지(地支)**: 12지지 (子丑寅卯辰巳午未申酉戌亥)
+
+이 라이브러리는 다음을 사용하여 기둥을 계산합니다:
+- **입춘(立春)** 을 이용한 연주 전환
+- **태양 황경** 을 이용한 월주 결정
+- **율리우스 적일** 을 이용한 일주 계산
+- **전통 중국 시진(時辰) 체계** 를 이용한 시주
+
+## 설치
+
+```bash
+# pnpm 사용
+pnpm add @gracefullight/saju
+
+# npm 사용
+npm install @gracefullight/saju
+
+# yarn 사용
+yarn add @gracefullight/saju
+```
+
+### 날짜 라이브러리 어댑터
+
+선호도에 따라 선택:
+
+```bash
+# 옵션 1: Luxon (현대적인 앱에 권장)
+pnpm add luxon @types/luxon
+
+# 옵션 2: date-fns (가벼운 대안)
+pnpm add date-fns date-fns-tz
+```
+
+## 빠른 시작
+
+```typescript
+import { DateTime } from "luxon";
+import { createLuxonAdapter } from "@gracefullight/saju/adapters/luxon";
+import { getFourPillars, STANDARD_PRESET } from "@gracefullight/saju";
+
+const adapter = await createLuxonAdapter();
+
+const birthDateTime = DateTime.fromObject(
+  { year: 2000, month: 1, day: 1, hour: 18, minute: 0 },
+  { zone: "Asia/Seoul" }
+);
+
+const result = getFourPillars(adapter, birthDateTime, {
+  longitudeDeg: 126.9778, // 서울 경도
+  preset: STANDARD_PRESET,
+});
+
+console.log(result);
+// {
+//   year: "己卯",    // 연주 (천간 + 지지)
+//   month: "丙子",   // 월주
+//   day: "庚辰",     // 일주
+//   hour: "辛酉",    // 시주
+//   meta: {
+//     solarYear: 1999,
+//     sunLonDeg: 280.9,
+//     effectiveDayDate: { year: 2000, month: 1, day: 1 },
+//     adjustedHour: 18
+//   }
+// }
+```
+
+## 사용법
+
+### Luxon 사용
+
+```typescript
+import { DateTime } from "luxon";
+import { createLuxonAdapter } from "@gracefullight/saju/adapters/luxon";
+import { getFourPillars, STANDARD_PRESET, TRADITIONAL_PRESET } from "@gracefullight/saju";
+
+const adapter = await createLuxonAdapter();
+
+const dt = DateTime.fromObject(
+  { year: 2000, month: 1, day: 1, hour: 18, minute: 0 },
+  { zone: "Asia/Seoul" }
+);
+
+// 표준 프리셋: 자정(00:00) 날짜 경계, 태양시 보정 없음
+const resultStandard = getFourPillars(adapter, dt, {
+  longitudeDeg: 126.9778,
+  preset: STANDARD_PRESET,
+});
+
+// 전통 프리셋: 자시(23:00) 날짜 경계, 태양시 보정 사용
+const resultTraditional = getFourPillars(adapter, dt, {
+  longitudeDeg: 126.9778,
+  preset: TRADITIONAL_PRESET,
+});
+```
+
+### date-fns 사용
+
+```typescript
+import { createDateFnsAdapter } from "@gracefullight/saju/adapters/date-fns";
+import { getFourPillars, STANDARD_PRESET } from "@gracefullight/saju";
+
+const adapter = await createDateFnsAdapter();
+
+const dt = {
+  date: new Date(1992, 9, 12, 19, 16), // 주의: 월은 0부터 시작
+  timeZone: "Asia/Seoul",
+};
+
+const result = getFourPillars(adapter, dt, {
+  longitudeDeg: 126.9778,
+  preset: STANDARD_PRESET,
+});
+```
+
+### 커스텀 날짜 어댑터
+
+`DateAdapter` 인터페이스를 구현하여 원하는 날짜 라이브러리 사용:
+
+```typescript
+import type { DateAdapter } from "@gracefullight/saju";
+
+const myAdapter: DateAdapter<MyDateType> = {
+  // 날짜 컴포넌트 getter
+  getYear: (date) => date.year,
+  getMonth: (date) => date.month,
+  getDay: (date) => date.day,
+  getHour: (date) => date.hour,
+  getMinute: (date) => date.minute,
+  getSecond: (date) => date.second,
+  getZoneName: (date) => date.zoneName,
+
+  // 날짜 연산
+  plusMinutes: (date, minutes) => date.add({ minutes }),
+  plusDays: (date, days) => date.add({ days }),
+  minusDays: (date, days) => date.subtract({ days }),
+
+  // 타임존 연산
+  toUTC: (date) => date.toUTC(),
+  setZone: (date, zoneName) => date.setZone(zoneName),
+
+  // 변환
+  toISO: (date) => date.toISO(),
+  toMillis: (date) => date.valueOf(),
+  fromMillis: (millis, zone) => MyDate.fromMillis(millis, zone),
+
+  // 유틸리티
+  createUTC: (year, month, day, hour, minute, second) =>
+    MyDate.utc(year, month, day, hour, minute, second),
+  isGreaterThanOrEqual: (date1, date2) => date1 >= date2,
+};
+```
+
+## API 레퍼런스
+
+### 설정 프리셋
+
+#### `STANDARD_PRESET`
+자정 날짜 경계와 태양시 보정 없는 현대적 해석
+
+```typescript
+{
+  dayBoundary: "midnight",           // 날짜는 00:00에 시작
+  useMeanSolarTimeForHour: false,    // 시주는 현지 시간 사용
+  useMeanSolarTimeForBoundary: false // 날짜 경계는 현지 시간 사용
+}
+```
+
+#### `TRADITIONAL_PRESET`
+자시(23:00) 날짜 경계와 태양시 보정을 사용하는 전통적 해석
+
+```typescript
+{
+  dayBoundary: "zi23",               // 날짜는 23:00(子時)에 시작
+  useMeanSolarTimeForHour: true,     // 시주는 태양시 사용
+  useMeanSolarTimeForBoundary: true  // 날짜 경계는 태양시 사용
+}
+```
+
+#### 사용 중단된 별칭
+- `presetA` → `STANDARD_PRESET` 사용 권장
+- `presetB` → `TRADITIONAL_PRESET` 사용 권장
+
+### 핵심 함수
+
+#### `getFourPillars(adapter, datetime, options)`
+
+네 기둥(연주, 월주, 일주, 시주) 모두 계산
+
+```typescript
+function getFourPillars<T>(
+  adapter: DateAdapter<T>,
+  datetime: T,
+  options: {
+    longitudeDeg: number;
+    preset?: {
+      dayBoundary: "midnight" | "zi23";
+      useMeanSolarTimeForHour: boolean;
+      useMeanSolarTimeForBoundary: boolean;
+    };
+    tzOffsetHours?: number;
+  }
+): {
+  year: string;
+  month: string;
+  day: string;
+  hour: string;
+  meta: {
+    solarYear: number;
+    sunLonDeg: number;
+    effectiveDayDate: { year: number; month: number; day: number };
+    adjustedHour: number;
+  };
+}
+```
+
+**매개변수:**
+- `adapter`: DateAdapter 인스턴스
+- `datetime`: 어댑터 형식의 날짜/시간 객체
+- `options`:
+  - `longitudeDeg`: 지리적 경도(도 단위) (예: 서울 126.9778)
+  - `preset`: 설정 프리셋 (`STANDARD_PRESET` 또는 `TRADITIONAL_PRESET` 사용)
+  - `tzOffsetHours`: 타임존 오프셋(시간 단위), 선택사항 (기본값: 9, KST)
+
+**반환값:** 연월일시 기둥과 메타데이터를 포함한 객체
+
+#### `yearPillar(adapter, datetime)`
+
+입춘(立春, 봄의 시작) 기준으로 연주만 계산
+
+```typescript
+function yearPillar<T>(
+  adapter: DateAdapter<T>,
+  datetime: T
+): {
+  idx60: number;
+  pillar: string;
+  solarYear: number;
+}
+```
+
+#### `monthPillar(adapter, datetime)`
+
+태양 황경 기준으로 월주만 계산
+
+```typescript
+function monthPillar<T>(
+  adapter: DateAdapter<T>,
+  datetime: T
+): {
+  pillar: string;
+  sunLonDeg: number;
+}
+```
+
+#### `dayPillarFromDate({ year, month, day })`
+
+율리우스 적일을 사용하여 일주만 계산
+
+```typescript
+function dayPillarFromDate(date: {
+  year: number;
+  month: number;
+  day: number;
+}): {
+  idx60: number;
+  pillar: string;
+}
+```
+
+#### `hourPillar(adapter, datetime, options)`
+
+태양시 보정 옵션과 함께 시주만 계산
+
+```typescript
+function hourPillar<T>(
+  adapter: DateAdapter<T>,
+  datetime: T,
+  options?: {
+    longitudeDeg?: number;
+    tzOffsetHours?: number;
+    useMeanSolarTimeForHour?: boolean;
+    dayBoundary?: "midnight" | "zi23";
+    useMeanSolarTimeForBoundary?: boolean;
+  }
+): {
+  pillar: string;
+  adjustedDt: T;
+  adjustedHour: number;
+}
+```
+
+### 상수
+
+```typescript
+// 10 천간(天干)
+export const STEMS: string[];
+// ["甲", "乙", "丙", "丁", "戊", "己", "庚", "辛", "壬", "癸"]
+
+// 12 지지(地支)
+export const BRANCHES: string[];
+// ["子", "丑", "寅", "卯", "辰", "巳", "午", "未", "申", "酉", "戌", "亥"]
+```
+
+### 헬퍼 함수
+
+#### `applyMeanSolarTime(adapter, dtLocal, longitudeDeg, tzOffsetHours)`
+
+경도 기반 평균 태양시 보정 적용
+
+```typescript
+function applyMeanSolarTime<T>(
+  adapter: DateAdapter<T>,
+  dtLocal: T,
+  longitudeDeg: number,
+  tzOffsetHours: number
+): T
+```
+
+#### `effectiveDayDate(adapter, dtLocal, options)`
+
+날짜 경계 규칙을 고려한 유효 날짜 계산
+
+```typescript
+function effectiveDayDate<T>(
+  adapter: DateAdapter<T>,
+  dtLocal: T,
+  options: {
+    dayBoundary?: "midnight" | "zi23";
+    longitudeDeg?: number;
+    tzOffsetHours?: number;
+    useMeanSolarTimeForBoundary?: boolean;
+  }
+): {
+  year: number;
+  month: number;
+  day: number;
+}
+```
+
+## 고급 사용법
+
+### 태양시 보정
+
+태양시 보정은 현지 시계 시간과 실제 태양시의 차이를 고려하여 경도에 따라 현지 시간을 조정합니다.
+
+```typescript
+import { applyMeanSolarTime, createLuxonAdapter } from "@gracefullight/saju";
+import { DateTime } from "luxon";
+
+const adapter = await createLuxonAdapter();
+const localTime = DateTime.local(2024, 1, 1, 12, 0, 0, { zone: "Asia/Seoul" });
+
+// 서울은 경도 126.9778°E이지만 UTC+9(표준 자오선 135°E) 사용
+// 이로 인해 약 32분 차이 발생
+const solarTime = applyMeanSolarTime(adapter, localTime, 126.9778, 9);
+console.log(solarTime.hour); // ~11.47 (11:28)
+```
+
+### 날짜 경계 모드
+
+**자정 모드** (`dayBoundary: "midnight"`):
+- 날짜가 00:00 현지 시간에 변경
+- 더 단순하고 현대 달력과 일치
+- 일반적인 사용에 적합
+
+**자시 모드** (`dayBoundary: "zi23"`):
+- 날짜가 23:00 현지 시간에 변경
+- 전통 중국 시간 체계
+- 자시(子時)가 자정을 걸침 (23:00-01:00)
+
+```typescript
+const result1 = getFourPillars(adapter, dt, {
+  longitudeDeg: 126.9778,
+  preset: { ...STANDARD_PRESET, dayBoundary: "midnight" },
+});
+
+const result2 = getFourPillars(adapter, dt, {
+  longitudeDeg: 126.9778,
+  preset: { ...STANDARD_PRESET, dayBoundary: "zi23" },
+});
+```
+
+### 커스텀 설정
+
+특정 요구사항에 맞게 설정 조합:
+
+```typescript
+const customConfig = {
+  dayBoundary: "midnight" as const,      // 현대적인 자정 경계
+  useMeanSolarTimeForHour: true,         // 하지만 시주는 태양시 사용
+  useMeanSolarTimeForBoundary: false,    // 날짜 경계는 현지 시간 사용
+};
+
+const result = getFourPillars(adapter, dt, {
+  longitudeDeg: 126.9778,
+  preset: customConfig,
+});
+```
+
+## 지리적 좌표
+
+참고용 주요 도시 경도:
+
+| 도시 | 경도 | 예시 |
+|------|------|------|
+| 서울, 대한민국 | 126.9778°E | `longitudeDeg: 126.9778` |
+| 베이징, 중국 | 116.4074°E | `longitudeDeg: 116.4074` |
+| 도쿄, 일본 | 139.6917°E | `longitudeDeg: 139.6917` |
+| 상하이, 중국 | 121.4737°E | `longitudeDeg: 121.4737` |
+| 타이베이, 대만 | 121.5654°E | `longitudeDeg: 121.5654` |
+
+## 예제
+
+### 다양한 타임존에서 계산
+
+```typescript
+import { DateTime } from "luxon";
+import { createLuxonAdapter, getFourPillars, TRADITIONAL_PRESET } from "@gracefullight/saju";
+
+const adapter = await createLuxonAdapter();
+
+// 뉴욕 출생 시간
+const nyTime = DateTime.fromObject(
+  { year: 1992, month: 10, day: 12, hour: 6, minute: 16 },
+  { zone: "America/New_York" }
+);
+
+const result = getFourPillars(adapter, nyTime, {
+  longitudeDeg: -74.0060, // 뉴욕 경도
+  tzOffsetHours: -5,      // EST 오프셋
+  preset: TRADITIONAL_PRESET,
+});
+```
+
+### 개별 기둥 계산
+
+```typescript
+import { yearPillar, monthPillar, dayPillarFromDate, hourPillar } from "@gracefullight/saju";
+
+// 연주
+const year = yearPillar(adapter, dt);
+console.log(year.pillar, year.solarYear);
+
+// 월주
+const month = monthPillar(adapter, dt);
+console.log(month.pillar, month.sunLonDeg);
+
+// 일주 (어댑터 불필요)
+const day = dayPillarFromDate({ year: 1992, month: 10, day: 12 });
+console.log(day.pillar);
+
+// 태양시를 사용한 시주
+const hour = hourPillar(adapter, dt, {
+  longitudeDeg: 126.9778,
+  useMeanSolarTimeForHour: true,
+});
+console.log(hour.pillar, hour.adjustedHour);
+```
+
+### 일괄 처리
+
+```typescript
+const birthDates = [
+  { year: 1990, month: 1, day: 15, hour: 10, minute: 30 },
+  { year: 1995, month: 5, day: 20, hour: 14, minute: 45 },
+  { year: 2000, month: 12, day: 25, hour: 18, minute: 0 },
+];
+
+const adapter = await createLuxonAdapter();
+
+const results = birthDates.map((birth) => {
+  const dt = DateTime.fromObject(birth, { zone: "Asia/Seoul" });
+  return {
+    birth,
+    pillars: getFourPillars(adapter, dt, {
+      longitudeDeg: 126.9778,
+      preset: STANDARD_PRESET,
+    }),
+  };
+});
+```
+
+## 개발
+
+### 설정
+
+```bash
+# 저장소 클론
+git clone https://github.com/gracefullight/saju.git
+cd saju
+
+# 의존성 설치
+pnpm install
+
+# 테스트 실행
+pnpm test
+
+# 커버리지와 함께 테스트 실행
+pnpm test:coverage
+
+# 빌드
+pnpm build
+
+# 린트
+pnpm lint
+
+# 포맷
+pnpm lint:fix
+```
+
+### 프로젝트 구조
+
+```
+packages/saju/
+├── src/
+│   ├── adapters/           # 날짜 라이브러리 어댑터
+│   │   ├── date-adapter.ts # 어댑터 인터페이스
+│   │   ├── luxon.ts        # Luxon 어댑터
+│   │   └── date-fns.ts     # date-fns 어댑터
+│   ├── core/               # 핵심 계산 로직
+│   │   └── four-pillars.ts # 메인 알고리즘
+│   ├── __tests__/          # 테스트 스위트
+│   └── index.ts            # 공개 API
+├── dist/                   # 컴파일된 출력
+├── coverage/               # 테스트 커버리지 리포트
+└── README.md
+```
+
+### 테스트 실행
+
+```bash
+# 모든 테스트 실행
+pnpm test
+
+# watch 모드로 테스트 실행
+pnpm test:watch
+
+# 커버리지 리포트 생성
+pnpm test:coverage
+```
+
+커버리지 결과:
+```
+File               | % Stmts | % Branch | % Funcs | % Lines
+-------------------|---------|----------|---------|----------
+All files          |   91.45 |    80.68 |   96.55 |   91.45
+ src/adapters      |   94.59 |    90.24 |     100 |   94.59
+ src/core          |   96.87 |    75.55 |     100 |   96.87
+```
+
+## 자주 묻는 질문
+
+### 단일 날짜 라이브러리 대신 날짜 어댑터를 사용하는 이유는?
+
+프로젝트마다 다른 날짜 라이브러리를 사용합니다. 어댑터 패턴을 통해:
+- 추가 의존성 없이 기존 날짜 라이브러리 사용 가능
+- 필요한 것만 포함하여 번들 크기 최소화
+- 프로젝트의 날짜 처리 방식과 일관성 유지
+
+### STANDARD_PRESET과 TRADITIONAL_PRESET의 차이는?
+
+**STANDARD_PRESET**은 현대적 관례 사용:
+- 날짜가 자정(00:00)에 시작
+- 현지 시계 시간 사용
+- 일반적인 사용에 더 간단
+
+**TRADITIONAL_PRESET**은 전통 중국 점성술 따름:
+- 날짜가 자시(23:00)에 시작
+- 경도 기반 태양시 보정 적용
+- 역사적으로 더 정확
+
+### 계산은 얼마나 정확한가요?
+
+이 라이브러리는 다음을 구현합니다:
+- 일주를 위한 율리우스 적일 알고리즘 (모든 역사적 날짜에 정확)
+- 월주를 위한 천문학적 태양 황경 계산
+- 연주를 위한 입춘(봄의 시작) 계산
+- 시주를 위한 전통 중국 시진(時辰) 체계
+
+모든 알고리즘은 알려진 역사적 날짜로 테스트되었으며 전통 중국 달력 참고자료와 일치합니다.
+
+### 역사적 날짜에도 사용할 수 있나요?
+
+네! 율리우스 적일 알고리즘은 다음에서 올바르게 작동합니다:
+- 그레고리력의 모든 날짜 (1582년 이후)
+- 율리우스력의 대부분 날짜 (적절한 달력 변환 포함)
+- 먼 미래의 날짜
+
+다만, 약 1970년 이전 날짜의 타임존 데이터는 덜 정확할 수 있습니다.
+
+### 같은 출생 시간이 다른 프리셋에서 다른 결과를 주는 이유는?
+
+프리셋은 다음에 영향을 미칩니다:
+1. **날짜 경계**: 날짜가 실제로 변경되는 시점 (자정 vs. 23:00)
+2. **태양시**: 경도 차이에 대한 조정 여부
+
+예를 들어, 23:30은 다음과 같을 수 있습니다:
+- 같은 날의 자시 (자정 경계 사용 시)
+- 다음 날의 자시 (자시23 경계 사용 시)
+
+이는 의도적이며 사주 해석의 다양한 학파를 반영합니다.
+
+## 기여하기
+
+기여를 환영합니다! Pull Request를 자유롭게 제출해주세요.
+
+1. 저장소 포크
+2. feature 브랜치 생성 (`git checkout -b feature/amazing-feature`)
+3. 변경사항 커밋 (`git commit -m 'Add some amazing feature'`)
+4. 브랜치에 푸시 (`git push origin feature/amazing-feature`)
+5. Pull Request 오픈
+
+### 가이드라인
+
+- 새 기능에 대한 테스트 작성
+- 코드 커버리지 유지 또는 개선
+- 기존 코드 스타일 따르기 (Biome으로 강제)
+- 필요에 따라 문서 업데이트
+
+## 라이선스
+
+MIT © [gracefullight](https://github.com/gracefullight)
+
+## 크레딧
+
+이 라이브러리는 사주명리(四柱命理)에 사용되는 전통 중국 역법 알고리즘과 천문 계산을 기반으로 합니다.
+
+## 관련 프로젝트
+
+- [Luxon](https://moment.github.io/luxon/) - 현대적인 날짜/시간 라이브러리
+- [date-fns](https://date-fns.org/) - 현대적인 JavaScript 날짜 유틸리티 라이브러리
+
+## 지원
+
+- [문서](https://github.com/gracefullight/saju#readme)
+- [이슈 트래커](https://github.com/gracefullight/saju/issues)
+- [토론](https://github.com/gracefullight/saju/discussions)
+
+---
+
+Made by [gracefullight](https://github.com/gracefullight)

package/dist/__tests__/date-fns-adapter.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=date-fns-adapter.test.d.ts.map

package/dist/__tests__/date-fns-adapter.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"date-fns-adapter.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/date-fns-adapter.test.ts"],"names":[],"mappings":""}