saju-logic (사주 로직 라이브러리)

1. 개요

이 프로젝트는 두 가지 구체적인 목표를 해결하기 위해 시작되었습니다.

1. 차샘 만세력의 '본원차력' 구현: '차샘 만세력'의 핵심 개념인 '본원차력'(균시차를 적용한 진태양시)을 정확하게 계산하고 표시해주는 로직이 필요했습니다.
2. 역사적 인물 사주 분석: 기존 만세력 라이브러리들은 대부분 1900년 이후의 데이터에 최적화되어 있어, 역사적 인물(예: 1600년대)의 사주를 정확하게 분석하는 데 한계가 있었습니다.

이러한 문제들을 해결하기 위해, 기존 라이브러리를 직접 수정하고 핵심 로직을 TypeScript로 재구현하여, 더 정확하고 유연하며 확장 가능한 사주 로직 라이브러리를 만드는 것을 목표로 합니다.

2. 주요 목표

• 정확한 절기 계산: 천문학적 계산에 기반하여 24절기가 시작되는 시점을 정밀하게 계산합니다.
• 유연한 시간 보정: 표준시뿐만 아니라, 경도에 따른 진태양시(균시차)를 적용할 수 있는 유연한 시간 보정 옵션을 제공하여 '본원차력'과 같은 고급 분석을 지원합니다.
• 신뢰도 높은 음력 변환: 타입 안정성이 확보된 lunar-typescript를 사용하여 양력-음력 변환 기능의 신뢰도를 높입니다.
• 광범위한 연도 지원 (장기 목표): 현대 라이브러리의 일반적인 한계(1900~2100년)를 넘어, 역사적 인물의 사주까지 분석할 수 있는 고정밀 계산 기능을 장기적인 목표로 연구하고 개발합니다.

3. 참조 및 개발 철학

이 라이브러리는 @gracefullight/saju (v1.1.3)의 뛰어난 구조와 로직을 벤치마킹하여 개발되었습니다. 오픈소스로 지식을 공유해주신 원작자에게 깊은 감사를 표합니다.

saju-logic은 참조 소스의 구조와 로직 흐름을 충실히 복제하는 것을 기본 원칙으로 삼되, 다음과 같은 합리적인 개선을 추구합니다.

• 타입 안정성 강화: lunar.ts 모듈의 경우, 참조 소스가 사용한 lunar-javascript 대신 타입 정보가 내장된 lunar-typescript를 사용하여 개발 경험과 안정성을 높였습니다. 이는 모듈의 외부 인터페이스를 유지하면서 내부 구현만 개선한 사례입니다.

4. 설치

npm을 사용하여 패키지를 설치합니다.

npm install saju-logic

5. 사용법

라이브러리 사용법 예시는 개발이 진행됨에 따라 업데이트될 예정입니다.

import { getFourPillars } from 'saju-logic';

// 사용 예시 (향후 변경될 수 있음)
// const pillars = getFourPillars(new Date(), { longitude: 127.0 });
// console.log(pillars);

6. 개발 환경

• 언어: TypeScript
• 런타임: Node.js
• 테스트 프레임워크: Vitest
• 패키지 매니저: npm

7. 주요 스크립트

• 빌드: TypeScript 소스 코드를 dist 디렉터리에 JavaScript 파일로 컴파일합니다.

  npm run build

• 테스트: vitest를 사용하여 프로젝트의 모든 테스트를 실행합니다.

  npm test

8. 라이선스

이 프로젝트는 ISC 라이선스를 따릅니다.