@gracefullight/saju 0.1.1 → 0.3.0

package/README.en.md

@@ -15,7 +15,13 @@
 - **Solar Time Correction** - Optional mean solar time adjustment based on longitude
 - **Tree-shakeable** - Import only what you need
 - **Fully Typed** - Complete TypeScript definitions
-- **Well Tested** - 85+ tests with 91%+ coverage
+- **Well Tested** - 180+ tests with 91%+ coverage
+- **Ten Gods Analysis** - Detailed ten gods and five elements distribution with hidden stems
+- **Strength Assessment** - 9-level strength analysis with monthly strength (得令), root strength (通根), transparency (透干), and hidden stem weights (本中餘氣)
+- **Relations Analysis** - Combinations, clashes, harms, punishments with transformation (化) status and conditions
+- **Major/Yearly Luck** - Solar term (節氣) based accurate luck start calculation, major luck and yearly luck based on gender and year pillar
+- **Yongshen Extraction** - Favorable element recommendation following 格局→抑扶→調候 priority with fortune enhancement guide
+- **Solar Terms Analysis** - Current/next solar term info with elapsed days calculation
 
 ## What is Saju (四柱)?
 
@@ -56,6 +62,39 @@ pnpm add date-fns date-fns-tz
 
 ## Quick Start
 
+```typescript
+import { DateTime } from "luxon";
+import { createLuxonAdapter } from "@gracefullight/saju/adapters/luxon";
+import { getSaju, 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" }
+);
+
+// getSaju: Calculate pillars, ten gods, strength, relations, yongshen, solar terms, major luck, yearly luck all at once
+const result = getSaju(adapter, birthDateTime, {
+  longitudeDeg: 126.9778,
+  gender: "male",  // Required: needed for major luck calculation
+  preset: STANDARD_PRESET,
+  currentYear: 2024,  // For default yearly luck range (optional)
+  yearlyLuckRange: { from: 2024, to: 2030 },  // Specify yearly luck range directly (optional)
+});
+
+console.log(result.pillars);     // { year: "己卯", month: "丙子", ... }
+console.log(result.tenGods);     // Ten gods and hidden stems analysis
+console.log(result.strength);    // Strength assessment (e.g., "weak")
+console.log(result.relations);   // Relations analysis
+console.log(result.yongShen);    // Yongshen and fortune tips
+console.log(result.solarTerms);  // Solar term info (current/next term, elapsed days)
+console.log(result.majorLuck);   // Major luck info
+console.log(result.yearlyLuck);  // Yearly luck info
+```
+
+### Calculate Four Pillars Only
+
 ```typescript
 import { DateTime } from "luxon";
 import { createLuxonAdapter } from "@gracefullight/saju/adapters/luxon";
@@ -74,18 +113,6 @@ const result = getFourPillars(adapter, birthDateTime, {
 });
 
 console.log(result);
-// {
-//   year: "己卯",    // Year Pillar (Heavenly Stem + Earthly Branch)
-//   month: "丙子",   // Month Pillar
-//   day: "庚辰",     // Day Pillar
-//   hour: "辛酉",    // Hour Pillar
-//   meta: {
-//     solarYear: 1999,
-//     sunLonDeg: 280.9,
-//     effectiveDayDate: { year: 2000, month: 1, day: 1 },
-//     adjustedHour: 18
-//   }
-// }
 ```
 
 ## Usage
@@ -126,7 +153,7 @@ import { getFourPillars, STANDARD_PRESET } from "@gracefullight/saju";
 const adapter = await createDateFnsAdapter();
 
 const dt = {
-  date: new Date(1992, 9, 12, 19, 16), // Note: month is 0-indexed
+  date: new Date(1985, 4, 15, 14, 30), // Note: month is 0-indexed
   timeZone: "Asia/Seoul",
 };
 
@@ -200,12 +227,27 @@ Traditional interpretation with Zi hour (23:00) day boundary and solar time corr
 }
 ```
 
-#### Deprecated Aliases
-- `presetA` → Use `STANDARD_PRESET`
-- `presetB` → Use `TRADITIONAL_PRESET`
-
 ### Core Functions
 
+#### `getSaju(adapter, datetime, options)`
+
+Calculate all saju analysis results (pillars, ten gods, strength, relations, yongshen, solar terms, major luck, yearly luck) at once.
+
+```typescript
+function getSaju<T>(
+  adapter: DateAdapter<T>,
+  dtLocal: T,
+  options: {
+    longitudeDeg: number;
+    gender: "male" | "female";  // Required
+    tzOffsetHours?: number;
+    preset?: typeof STANDARD_PRESET;
+    currentYear?: number;  // For default yearly luck range
+    yearlyLuckRange?: { from: number; to: number };  // Specify yearly luck range directly
+  }
+): SajuResult;
+```
+
 #### `getFourPillars(adapter, datetime, options)`
 
 Calculate all four pillars (year, month, day, hour).
@@ -228,11 +270,17 @@ function getFourPillars<T>(
   month: string;
   day: string;
   hour: string;
+  lunar: {
+    lunarYear: number;
+    lunarMonth: number;
+    lunarDay: number;
+    isLeapMonth: boolean;
+  };
   meta: {
-    solarYear: number;
+    solarYearUsed: number;
     sunLonDeg: number;
     effectiveDayDate: { year: number; month: number; day: number };
-    adjustedHour: number;
+    adjustedDtForHour: string;
   };
 }
 ```
@@ -245,7 +293,7 @@ function getFourPillars<T>(
   - `preset`: Configuration preset (use `STANDARD_PRESET` or `TRADITIONAL_PRESET`)
   - `tzOffsetHours`: Optional timezone offset in hours (default: 9 for KST)
 
-**Returns:** Object with year, month, day, hour pillars and metadata
+**Returns:** Object with year, month, day, hour pillars, lunar date, and metadata
 
 #### `yearPillar(adapter, datetime)`
 
@@ -291,6 +339,58 @@ function dayPillarFromDate(date: {
 }
 ```
 
+### Lunar Conversion Functions
+
+#### `getLunarDate(year, month, day)`
+
+Convert a solar (Gregorian) date to a lunar date.
+
+```typescript
+function getLunarDate(
+  year: number,
+  month: number,
+  day: number
+): {
+  lunarYear: number;
+  lunarMonth: number;
+  lunarDay: number;
+  isLeapMonth: boolean;
+}
+```
+
+**Example:**
+```typescript
+import { getLunarDate } from "@gracefullight/saju";
+
+const lunar = getLunarDate(2000, 1, 1);
+// { lunarYear: 1999, lunarMonth: 11, lunarDay: 25, isLeapMonth: false }
+```
+
+#### `getSolarDate(lunarYear, lunarMonth, lunarDay, isLeapMonth)`
+
+Convert a lunar date to a solar (Gregorian) date.
+
+```typescript
+function getSolarDate(
+  lunarYear: number,
+  lunarMonth: number,
+  lunarDay: number,
+  isLeapMonth?: boolean
+): {
+  year: number;
+  month: number;
+  day: number;
+}
+```
+
+**Example:**
+```typescript
+import { getSolarDate } from "@gracefullight/saju";
+
+const solar = getSolarDate(1999, 11, 25, false);
+// { year: 2000, month: 1, day: 1 }
+```
+
 #### `hourPillar(adapter, datetime, options)`
 
 Calculate only the hour pillar with optional solar time correction.
@@ -361,6 +461,109 @@ function effectiveDayDate<T>(
 }
 ```
 
+### Analysis Functions
+
+#### `analyzeTenGods(year, month, day, hour)`
+
+Analyzes ten gods and hidden stems of the four pillars.
+
+```typescript
+function analyzeTenGods(
+  year: string,
+  month: string,
+  day: string,
+  hour: string
+): FourPillarsTenGods;
+```
+
+#### `analyzeStrength(year, month, day, hour)`
+
+Assesses the strength of the day master on a 7-level scale.
+
+```typescript
+function analyzeStrength(
+  year: string,
+  month: string,
+  day: string,
+  hour: string
+): StrengthResult;
+```
+
+#### `analyzeRelations(year, month, day, hour)`
+
+Analyzes combinations, clashes, harms, and punishments between stems and branches.
+
+```typescript
+function analyzeRelations(
+  year: string,
+  month: string,
+  day: string,
+  hour: string
+): RelationsResult;
+```
+
+#### `calculateMajorLuck(adapter, datetime, gender, year, month)`
+
+Calculates major luck periods and starting age.
+
+```typescript
+function calculateMajorLuck<T>(
+  adapter: DateAdapter<T>,
+  birthDateTime: T,
+  gender: "male" | "female",
+  yearPillar: string,
+  monthPillar: string
+): MajorLuckResult;
+```
+
+#### `analyzeYongShen(year, month, day, hour)`
+
+Extracts favorable elements considering suppression and climate adjustment.
+
+```typescript
+function analyzeYongShen(
+  year: string,
+  month: string,
+  day: string,
+  hour: string
+): YongShenResult;
+```
+
+#### `analyzeSolarTerms(adapter, datetime)`
+
+Calculates current and next solar term info with elapsed days.
+
+```typescript
+function analyzeSolarTerms<T>(
+  adapter: DateAdapter<T>,
+  dtLocal: T
+): SolarTermInfo;
+```
+
+**Returns:**
+```typescript
+{
+  current: { name: "소한", hanja: "小寒", longitude: 285 },
+  currentDate: { year: 2024, month: 1, day: 6, hour: 5, minute: 30 },
+  daysSinceCurrent: 5,
+  next: { name: "대한", hanja: "大寒", longitude: 300 },
+  nextDate: { year: 2024, month: 1, day: 20, hour: 12, minute: 15 },
+  daysUntilNext: 10
+}
+```
+
+#### `getSolarTermsForYear(adapter, year, timezone)`
+
+Calculates all 24 solar terms for a specific year.
+
+```typescript
+function getSolarTermsForYear<T>(
+  adapter: DateAdapter<T>,
+  year: number,
+  timezone: string
+): Array<{ term: SolarTerm; date: {...} }>;
+```
+
 ## Advanced Usage
 
 ### Solar Time Correction
@@ -435,6 +638,85 @@ Common city longitudes for reference:
 
 ## Examples
 
+### Major and Yearly Luck Calculation
+
+```typescript
+const saju = getSaju(adapter, dt, {
+  longitudeDeg: 126.9778,
+  gender: "female",
+  yearlyLuckRange: { from: 2024, to: 2030 }
+});
+
+// Check major luck
+console.log(saju.majorLuck.pillars); // Major luck pillars list
+console.log(saju.majorLuck.startAge); // Starting age for major luck
+
+// Check yearly luck
+saju.yearlyLuck.forEach(luck => {
+  console.log(`Year ${luck.year} (${luck.pillar}): Age ${luck.age}`);
+});
+```
+
+### Solar Terms Info
+
+```typescript
+const saju = getSaju(adapter, dt, {
+  longitudeDeg: 126.9778,
+  gender: "male",
+});
+
+// Current solar term
+console.log(saju.solarTerms.current.name);  // "소한"
+console.log(saju.solarTerms.current.hanja); // "小寒"
+console.log(saju.solarTerms.daysSinceCurrent); // 5 (days since term started)
+
+// Next solar term
+console.log(saju.solarTerms.next.name);     // "대한"
+console.log(saju.solarTerms.daysUntilNext); // 10 (days until next term)
+
+// Solar term dates
+console.log(saju.solarTerms.currentDate);   // { year: 2024, month: 1, day: 6, ... }
+console.log(saju.solarTerms.nextDate);      // { year: 2024, month: 1, day: 20, ... }
+```
+
+### Ten Gods and Five Elements Analysis
+
+```typescript
+import { analyzeTenGods, countElements } from "@gracefullight/saju";
+
+const tenGods = analyzeTenGods("己卯", "丙子", "辛巳", "戊戌");
+console.log(tenGods.dayMaster); // "辛"
+
+const elements = countElements(tenGods);
+console.log(elements); // { wood: 1, fire: 1, earth: 3, metal: 1, water: 2 }
+```
+
+### Strength and Yongshen Analysis
+
+```typescript
+import { analyzeStrength, analyzeYongShen, getElementRecommendations } from "@gracefullight/saju";
+
+const strength = analyzeStrength("己卯", "丙子", "辛巳", "戊戌");
+console.log(strength.level); // "weak"
+
+const yongShen = analyzeYongShen("己卯", "丙子", "辛巳", "戊戌");
+console.log(yongShen.primary); // Favorable element (e.g., "earth")
+
+const tips = getElementRecommendations(yongShen);
+console.log(tips.colors); // Lucky colors
+```
+
+### Relations Analysis
+
+```typescript
+import { analyzeRelations } from "@gracefullight/saju";
+
+const relations = analyzeRelations("己卯", "丙子", "辛巳", "戊戌");
+relations.clashes.forEach(c => {
+  console.log(`${c.positions[0]}-${c.positions[1]} branch clash: ${c.pair[0]}-${c.pair[1]}`);
+});
+```
+
 ### Calculate for Different Timezones
 
 ```typescript
@@ -445,7 +727,7 @@ const adapter = await createLuxonAdapter();
 
 // New York birth time
 const nyTime = DateTime.fromObject(
-  { year: 1992, month: 10, day: 12, hour: 6, minute: 16 },
+  { year: 1985, month: 5, day: 15, hour: 6, minute: 30 },
   { zone: "America/New_York" }
 );
 
@@ -470,7 +752,7 @@ const month = monthPillar(adapter, dt);
 console.log(month.pillar, month.sunLonDeg);
 
 // Day pillar (no adapter needed)
-const day = dayPillarFromDate({ year: 1992, month: 10, day: 12 });
+const day = dayPillarFromDate({ year: 1985, month: 5, day: 15 });
 console.log(day.pillar);
 
 // Hour pillar with solar time
@@ -542,7 +824,15 @@ packages/saju/
 │   │   ├── luxon.ts        # Luxon adapter
 │   │   └── date-fns.ts     # date-fns adapter
 │   ├── core/               # Core calculation logic
-│   │   └── four-pillars.ts # Main algorithms
+│   │   ├── four-pillars.ts # Four pillars calculation
+│   │   ├── ten-gods.ts     # Ten gods analysis
+│   │   ├── strength.ts     # Strength assessment
+│   │   ├── relations.ts    # Relations analysis
+│   │   ├── luck.ts         # Major/yearly luck
+│   │   ├── yongshen.ts     # Yongshen extraction
+│   │   ├── solar-terms.ts  # Solar terms calculation
+│   │   └── lunar.ts        # Lunar conversion
+│   ├── types/              # Type definitions
 │   ├── __tests__/          # Test suites
 │   └── index.ts            # Public API
 ├── dist/                   # Compiled output
@@ -659,7 +949,3 @@ This library is based on traditional Chinese calendar algorithms and astronomica
 - [Documentation](https://github.com/gracefullight/saju#readme)
 - [Issue Tracker](https://github.com/gracefullight/saju/issues)
 - [Discussions](https://github.com/gracefullight/saju/discussions)
-
----
-
-Made by [gracefullight](https://github.com/gracefullight)