@gracefullight/saju 0.1.0

package/dist/adapters/date-adapter.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Date adapter interface for abstracting date/time operations.
+ * This allows the library to work with any date library (Luxon, date-fns, Day.js, etc.)
+ */
+export interface DateAdapter<T = unknown> {
+    /**
+     * Get the year component
+     */
+    getYear(date: T): number;
+    /**
+     * Get the month component (1-12)
+     */
+    getMonth(date: T): number;
+    /**
+     * Get the day component
+     */
+    getDay(date: T): number;
+    /**
+     * Get the hour component (0-23)
+     */
+    getHour(date: T): number;
+    /**
+     * Get the minute component (0-59)
+     */
+    getMinute(date: T): number;
+    /**
+     * Get the second component (0-59)
+     */
+    getSecond(date: T): number;
+    /**
+     * Get the timezone name (e.g., "Asia/Seoul", "America/New_York")
+     */
+    getZoneName(date: T): string;
+    /**
+     * Add minutes to a date
+     */
+    plusMinutes(date: T, minutes: number): T;
+    /**
+     * Add days to a date
+     */
+    plusDays(date: T, days: number): T;
+    /**
+     * Subtract days from a date
+     */
+    minusDays(date: T, days: number): T;
+    /**
+     * Convert to UTC
+     */
+    toUTC(date: T): T;
+    /**
+     * Convert to ISO string
+     */
+    toISO(date: T): string;
+    /**
+     * Convert to milliseconds since epoch
+     */
+    toMillis(date: T): number;
+    /**
+     * Create a date from milliseconds since epoch
+     */
+    fromMillis(millis: number, zone: string): T;
+    /**
+     * Create a UTC date
+     */
+    createUTC(year: number, month: number, day: number, hour: number, minute: number, second: number): T;
+    /**
+     * Set the timezone of a date without changing the underlying instant
+     */
+    setZone(date: T, zoneName: string): T;
+    /**
+     * Compare two dates (returns true if date1 >= date2)
+     */
+    isGreaterThanOrEqual(date1: T, date2: T): boolean;
+}
+//# sourceMappingURL=date-adapter.d.ts.map

package/dist/adapters/date-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"date-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/date-adapter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO;IACtC;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC;IAE1B;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC;IAExB;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC;IAEzB;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC;IAE3B;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC;IAE3B;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC;IAE7B;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,CAAC,CAAC;IAEzC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC;IAEnC;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC;IAEpC;;OAEG;IACH,KAAK,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC;IAElB;;OAEG;IACH,KAAK,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC;IAE1B;;OAEG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC;IAE5C;;OAEG;IACH,SAAS,CACP,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,CAAC,CAAC;IAEL;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,CAAC;IAEtC;;OAEG;IACH,oBAAoB,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC;CACnD"}

package/dist/adapters/date-adapter.js

@@ -0,0 +1 @@
+export {};

package/dist/adapters/date-fns.d.ts

@@ -0,0 +1,8 @@
+import type { DateAdapter } from "@/adapters/date-adapter";
+interface DateFnsDate {
+    date: Date;
+    timeZone: string;
+}
+export declare function createDateFnsAdapter(): Promise<DateAdapter<DateFnsDate>>;
+export {};
+//# sourceMappingURL=date-fns.d.ts.map

package/dist/adapters/date-fns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"date-fns.d.ts","sourceRoot":"","sources":["../../src/adapters/date-fns.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,UAAU,WAAW;IACnB,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,CA4E9E"}

package/dist/adapters/date-fns.js

@@ -0,0 +1,73 @@
+export async function createDateFnsAdapter() {
+    let addMinutes;
+    let addDays;
+    let subDays;
+    let getYear;
+    let getMonth;
+    let getDate;
+    let getHours;
+    let getMinutes;
+    let getSeconds;
+    let formatISO;
+    let fromZonedTime;
+    let toZonedTime;
+    try {
+        const dateFns = await import("date-fns");
+        const dateFnsTz = await import("date-fns-tz");
+        addMinutes = dateFns.addMinutes;
+        addDays = dateFns.addDays;
+        subDays = dateFns.subDays;
+        getYear = dateFns.getYear;
+        getMonth = dateFns.getMonth;
+        getDate = dateFns.getDate;
+        getHours = dateFns.getHours;
+        getMinutes = dateFns.getMinutes;
+        getSeconds = dateFns.getSeconds;
+        formatISO = dateFns.formatISO;
+        fromZonedTime = dateFnsTz.fromZonedTime;
+        toZonedTime = dateFnsTz.toZonedTime;
+    }
+    catch {
+        throw new Error("date-fns or date-fns-tz is not installed. Install with: npm install date-fns date-fns-tz");
+    }
+    return {
+        getYear: (dateFns) => getYear(dateFns.date),
+        getMonth: (dateFns) => getMonth(dateFns.date) + 1,
+        getDay: (dateFns) => getDate(dateFns.date),
+        getHour: (dateFns) => getHours(dateFns.date),
+        getMinute: (dateFns) => getMinutes(dateFns.date),
+        getSecond: (dateFns) => getSeconds(dateFns.date),
+        getZoneName: (dateFns) => dateFns.timeZone,
+        plusMinutes: (dateFns, minutes) => ({
+            date: addMinutes(dateFns.date, minutes),
+            timeZone: dateFns.timeZone,
+        }),
+        plusDays: (dateFns, days) => ({
+            date: addDays(dateFns.date, days),
+            timeZone: dateFns.timeZone,
+        }),
+        minusDays: (dateFns, days) => ({
+            date: subDays(dateFns.date, days),
+            timeZone: dateFns.timeZone,
+        }),
+        toUTC: (dateFns) => ({
+            date: fromZonedTime(dateFns.date, dateFns.timeZone),
+            timeZone: "UTC",
+        }),
+        toISO: (dateFns) => formatISO(dateFns.date),
+        toMillis: (dateFns) => dateFns.date.getTime(),
+        fromMillis: (millis, zone) => ({
+            date: new Date(millis),
+            timeZone: zone,
+        }),
+        createUTC: (year, month, day, hour, minute, second) => ({
+            date: new Date(Date.UTC(year, month - 1, day, hour, minute, second)),
+            timeZone: "UTC",
+        }),
+        setZone: (dateFns, zoneName) => ({
+            date: toZonedTime(dateFns.date, zoneName),
+            timeZone: zoneName,
+        }),
+        isGreaterThanOrEqual: (date1, date2) => date1.date >= date2.date,
+    };
+}

package/dist/adapters/luxon.d.ts

@@ -0,0 +1,3 @@
+import type { DateAdapter } from "@/adapters/date-adapter";
+export declare function createLuxonAdapter(): Promise<DateAdapter<import("luxon").DateTime>>;
+//# sourceMappingURL=luxon.d.ts.map

package/dist/adapters/luxon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"luxon.d.ts","sourceRoot":"","sources":["../../src/adapters/luxon.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,WAAW,CAAC,OAAO,OAAO,EAAE,QAAQ,CAAC,CAAC,CAsCzF"}

package/dist/adapters/luxon.js

@@ -0,0 +1,39 @@
+export async function createLuxonAdapter() {
+    let DateTime;
+    try {
+        const luxon = await import("luxon");
+        DateTime = luxon.DateTime;
+    }
+    catch {
+        throw new Error("Luxon is not installed. Install it with: npm install luxon @types/luxon");
+    }
+    return {
+        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) => {
+            const zoneName = date.zoneName;
+            if (zoneName === null)
+                throw new Error("DateTime has no timezone");
+            return zoneName;
+        },
+        plusMinutes: (date, minutes) => date.plus({ minutes }),
+        plusDays: (date, days) => date.plus({ days }),
+        minusDays: (date, days) => date.minus({ days }),
+        toUTC: (date) => date.toUTC(),
+        toISO: (date) => {
+            const iso = date.toISO();
+            if (iso === null)
+                throw new Error("Failed to convert DateTime to ISO string");
+            return iso;
+        },
+        toMillis: (date) => date.toMillis(),
+        fromMillis: (millis, zone) => DateTime.fromMillis(millis, { zone }),
+        createUTC: (year, month, day, hour, minute, second) => DateTime.utc(year, month, day, hour, minute, second),
+        setZone: (date, zoneName) => date.setZone(zoneName),
+        isGreaterThanOrEqual: (date1, date2) => date1 >= date2,
+    };
+}

package/dist/core/four-pillars.d.ts

@@ -0,0 +1,88 @@
+import type { DateAdapter } from "@/adapters/date-adapter";
+export declare const STEMS: string[];
+export declare const BRANCHES: string[];
+export declare const STANDARD_PRESET: {
+    dayBoundary: "midnight";
+    useMeanSolarTimeForHour: boolean;
+    useMeanSolarTimeForBoundary: boolean;
+};
+export declare const TRADITIONAL_PRESET: {
+    dayBoundary: "zi23";
+    useMeanSolarTimeForHour: boolean;
+    useMeanSolarTimeForBoundary: boolean;
+};
+export declare const presetA: {
+    dayBoundary: "midnight";
+    useMeanSolarTimeForHour: boolean;
+    useMeanSolarTimeForBoundary: boolean;
+};
+export declare const presetB: {
+    dayBoundary: "zi23";
+    useMeanSolarTimeForHour: boolean;
+    useMeanSolarTimeForBoundary: boolean;
+};
+export declare function dayPillarFromDate({ year, month, day, }: {
+    year: number;
+    month: number;
+    day: number;
+}): {
+    idx60: number;
+    pillar: string;
+};
+export declare function applyMeanSolarTime<T>(adapter: DateAdapter<T>, dtLocal: T, longitudeDeg: number, tzOffsetHours?: number): T;
+export declare function yearPillar<T>(adapter: DateAdapter<T>, dtLocal: T): {
+    idx60: number;
+    pillar: string;
+    solarYear: number;
+};
+export declare function monthPillar<T>(adapter: DateAdapter<T>, dtLocal: T): {
+    pillar: string;
+    sunLonDeg: number;
+};
+export declare function effectiveDayDate<T>(adapter: DateAdapter<T>, dtLocal: T, { dayBoundary, longitudeDeg, tzOffsetHours, useMeanSolarTimeForBoundary, }?: {
+    dayBoundary?: "midnight" | "zi23";
+    longitudeDeg?: number;
+    tzOffsetHours?: number;
+    useMeanSolarTimeForBoundary?: boolean;
+}): {
+    year: number;
+    month: number;
+    day: number;
+};
+export declare function hourPillar<T>(adapter: DateAdapter<T>, dtLocal: T, { longitudeDeg, tzOffsetHours, useMeanSolarTimeForHour, dayBoundary, useMeanSolarTimeForBoundary, }?: {
+    longitudeDeg?: number;
+    tzOffsetHours?: number;
+    useMeanSolarTimeForHour?: boolean;
+    dayBoundary?: "midnight" | "zi23";
+    useMeanSolarTimeForBoundary?: boolean;
+}): {
+    pillar: string;
+    adjustedDt: T;
+    effectiveDate: {
+        year: number;
+        month: number;
+        day: number;
+    };
+};
+export declare function getFourPillars<T>(adapter: DateAdapter<T>, dtLocal: T, { longitudeDeg, tzOffsetHours, preset, }: {
+    longitudeDeg: number;
+    tzOffsetHours?: number;
+    preset?: typeof presetA | typeof presetB;
+}): {
+    year: string;
+    month: string;
+    day: string;
+    hour: string;
+    meta: {
+        solarYearUsed: number;
+        sunLonDeg: number;
+        effectiveDayDate: {
+            year: number;
+            month: number;
+            day: number;
+        };
+        adjustedDtForHour: string;
+        preset: typeof preset;
+    };
+};
+//# sourceMappingURL=four-pillars.d.ts.map

package/dist/core/four-pillars.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"four-pillars.d.ts","sourceRoot":"","sources":["../../src/core/four-pillars.ts"],"names":[],"mappings":"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"}

package/dist/core/four-pillars.js

@@ -0,0 +1,221 @@
+export const STEMS = ["甲", "乙", "丙", "丁", "戊", "己", "庚", "辛", "壬", "癸"];
+export const BRANCHES = ["子", "丑", "寅", "卯", "辰", "巳", "午", "未", "申", "酉", "戌", "亥"];
+export const STANDARD_PRESET = {
+    dayBoundary: "midnight",
+    useMeanSolarTimeForHour: false,
+    useMeanSolarTimeForBoundary: false,
+};
+export const TRADITIONAL_PRESET = {
+    dayBoundary: "zi23",
+    useMeanSolarTimeForHour: true,
+    useMeanSolarTimeForBoundary: true,
+};
+export const presetA = STANDARD_PRESET;
+export const presetB = TRADITIONAL_PRESET;
+function normDeg(x) {
+    x %= 360;
+    return x < 0 ? x + 360 : x;
+}
+function pillarFrom60(idx60) {
+    return STEMS[idx60 % 10] + BRANCHES[idx60 % 12];
+}
+function jdnFromDate(y, m, d) {
+    const a = Math.floor((14 - m) / 12);
+    const y2 = y + 4800 - a;
+    const m2 = m + 12 * a - 3;
+    return (d +
+        Math.floor((153 * m2 + 2) / 5) +
+        365 * y2 +
+        Math.floor(y2 / 4) -
+        Math.floor(y2 / 100) +
+        Math.floor(y2 / 400) -
+        32045);
+}
+export function dayPillarFromDate({ year, month, day, }) {
+    const jdn = jdnFromDate(year, month, day);
+    const idx60 = (jdn + 12) % 60;
+    return { idx60, pillar: pillarFrom60(idx60) };
+}
+export function applyMeanSolarTime(adapter, dtLocal, longitudeDeg, tzOffsetHours = 9) {
+    const deltaMinutes = 4 * (longitudeDeg - 15 * tzOffsetHours);
+    return adapter.plusMinutes(dtLocal, deltaMinutes);
+}
+function sunApparentLongitude(adapter, dtUtc) {
+    let y = adapter.getYear(dtUtc);
+    let m = adapter.getMonth(dtUtc);
+    const d = adapter.getDay(dtUtc) +
+        (adapter.getHour(dtUtc) + (adapter.getMinute(dtUtc) + adapter.getSecond(dtUtc) / 60) / 60) / 24;
+    if (m <= 2) {
+        y -= 1;
+        m += 12;
+    }
+    const A = Math.floor(y / 100);
+    const B = 2 - A + Math.floor(A / 4);
+    const JD = Math.floor(365.25 * (y + 4716)) + Math.floor(30.6001 * (m + 1)) + d + B - 1524.5;
+    const T = (JD - 2451545.0) / 36525.0;
+    const L0 = normDeg(280.46646 + 36000.76983 * T + 0.0003032 * T * T);
+    const M = normDeg(357.52911 + 35999.05029 * T - 0.0001537 * T * T);
+    const deg2rad = (deg) => (deg * Math.PI) / 180;
+    const C = (1.914602 - 0.004817 * T - 0.000014 * T * T) * Math.sin(deg2rad(M)) +
+        (0.019993 - 0.000101 * T) * Math.sin(deg2rad(2 * M)) +
+        0.000289 * Math.sin(deg2rad(3 * M));
+    const trueLong = L0 + C;
+    const omega = 125.04 - 1934.136 * T;
+    const lambda = trueLong - 0.00569 - 0.00478 * Math.sin(deg2rad(omega));
+    return normDeg(lambda);
+}
+function angleDiffDeg(a, b) {
+    return ((a - b + 540) % 360) - 180;
+}
+function findTermUtc(adapter, targetDeg, startUtc, endUtc) {
+    let a = startUtc;
+    let b = endUtc;
+    const f = (dt) => angleDiffDeg(sunApparentLongitude(adapter, dt), targetDeg);
+    let fa = f(a);
+    let fb = f(b);
+    let expand = 0;
+    while (fa * fb > 0 && expand < 10) {
+        a = adapter.minusDays(a, 1);
+        b = adapter.plusDays(b, 1);
+        fa = f(a);
+        fb = f(b);
+        expand += 1;
+    }
+    if (fa * fb > 0)
+        throw new Error("Failed to bracket solar term");
+    for (let i = 0; i < 80; i++) {
+        const midMillis = (adapter.toMillis(a) + adapter.toMillis(b)) / 2;
+        const mid = adapter.fromMillis(midMillis, "utc");
+        const fm = f(mid);
+        if (Math.abs(fm) < 1e-6)
+            return mid;
+        if (fa * fm <= 0) {
+            b = mid;
+            fb = fm;
+        }
+        else {
+            a = mid;
+            fa = fm;
+        }
+    }
+    return adapter.fromMillis((adapter.toMillis(a) + adapter.toMillis(b)) / 2, "utc");
+}
+function lichunUtc(adapter, year) {
+    const start = adapter.createUTC(year, 2, 1, 0, 0, 0);
+    const end = adapter.createUTC(year, 2, 7, 0, 0, 0);
+    return findTermUtc(adapter, 315.0, start, end);
+}
+export function yearPillar(adapter, dtLocal) {
+    const y = adapter.getYear(dtLocal);
+    const lichunLocal = adapter.setZone(lichunUtc(adapter, y), adapter.getZoneName(dtLocal));
+    const solarYear = adapter.isGreaterThanOrEqual(dtLocal, lichunLocal) ? y : y - 1;
+    const idx60 = (((solarYear - 1984) % 60) + 60) % 60;
+    return { idx60, pillar: pillarFrom60(idx60), solarYear };
+}
+function monthBranchIndexFromSunLon(lon) {
+    return (Math.floor(((lon + 45) % 360) / 30) + 2) % 12;
+}
+function firstMonthStemIndex(yearStemIdx) {
+    const map = new Map([
+        [0, 2],
+        [5, 2],
+        [1, 4],
+        [6, 4],
+        [2, 6],
+        [7, 6],
+        [3, 8],
+        [8, 8],
+        [4, 0],
+        [9, 0],
+    ]);
+    return map.get(yearStemIdx) ?? 0;
+}
+export function monthPillar(adapter, dtLocal) {
+    const { idx60: yIdx60 } = yearPillar(adapter, dtLocal);
+    const yearStemIdx = yIdx60 % 10;
+    const lon = sunApparentLongitude(adapter, adapter.toUTC(dtLocal));
+    const mBranchIdx = monthBranchIndexFromSunLon(lon);
+    const monthNo = (mBranchIdx - 2 + 12) % 12;
+    const mStemIdx = (firstMonthStemIndex(yearStemIdx) + monthNo) % 10;
+    return { pillar: STEMS[mStemIdx] + BRANCHES[mBranchIdx], sunLonDeg: lon };
+}
+export function effectiveDayDate(adapter, dtLocal, { dayBoundary = "midnight", longitudeDeg, tzOffsetHours = 9, useMeanSolarTimeForBoundary = false, } = {}) {
+    let dtChk = dtLocal;
+    if (useMeanSolarTimeForBoundary) {
+        if (typeof longitudeDeg !== "number")
+            throw new Error("longitudeDeg required when useMeanSolarTimeForBoundary=true");
+        dtChk = applyMeanSolarTime(adapter, dtLocal, longitudeDeg, tzOffsetHours);
+    }
+    let d = dtChk;
+    if (dayBoundary === "zi23") {
+        if (adapter.getHour(dtChk) >= 23)
+            d = adapter.plusDays(dtChk, 1);
+    }
+    else if (dayBoundary !== "midnight") {
+        throw new Error("dayBoundary must be 'midnight' or 'zi23'");
+    }
+    return { year: adapter.getYear(d), month: adapter.getMonth(d), day: adapter.getDay(d) };
+}
+function hourBranchIndexFromHour(h) {
+    // Traditional Chinese hours (時辰) mapping:
+    // Each branch represents a 2-hour period, starting from 子時 at 23:00
+    // 子時 (0): 23:00-01:00, 丑時 (1): 01:00-03:00, ..., 亥時 (11): 21:00-23:00
+    // Formula: (hour + 1) / 2 gives the branch index, but we need +1 offset
+    // because 23:00 (hour 23) should map to index 0 (子), wrapping around
+    return Math.floor((h + 1) / 2 + 1) % 12;
+}
+export function hourPillar(adapter, dtLocal, { longitudeDeg, tzOffsetHours = 9, useMeanSolarTimeForHour = false, dayBoundary = "midnight", useMeanSolarTimeForBoundary = false, } = {}) {
+    let dtUsed = dtLocal;
+    if (useMeanSolarTimeForHour) {
+        if (typeof longitudeDeg !== "number")
+            throw new Error("longitudeDeg required when useMeanSolarTimeForHour=true");
+        dtUsed = applyMeanSolarTime(adapter, dtLocal, longitudeDeg, tzOffsetHours);
+    }
+    const effDate = effectiveDayDate(adapter, dtLocal, {
+        dayBoundary,
+        longitudeDeg,
+        tzOffsetHours,
+        useMeanSolarTimeForBoundary,
+    });
+    const { idx60: dIdx60 } = dayPillarFromDate(effDate);
+    const dayStemIdx = dIdx60 % 10;
+    const hb = hourBranchIndexFromHour(adapter.getHour(dtUsed));
+    const hs = (dayStemIdx * 2 + hb) % 10;
+    return { pillar: STEMS[hs] + BRANCHES[hb], adjustedDt: dtUsed, effectiveDate: effDate };
+}
+export function getFourPillars(adapter, dtLocal, { longitudeDeg, tzOffsetHours = 9, preset = presetA, }) {
+    if (typeof longitudeDeg !== "number")
+        throw new Error("longitudeDeg is required");
+    const dayBoundary = preset.dayBoundary ?? "midnight";
+    const useMeanSolarTimeForHour = preset.useMeanSolarTimeForHour ?? false;
+    const useMeanSolarTimeForBoundary = preset.useMeanSolarTimeForBoundary ?? false;
+    const y = yearPillar(adapter, dtLocal);
+    const m = monthPillar(adapter, dtLocal);
+    const effDate = effectiveDayDate(adapter, dtLocal, {
+        dayBoundary,
+        longitudeDeg,
+        tzOffsetHours,
+        useMeanSolarTimeForBoundary,
+    });
+    const d = dayPillarFromDate(effDate);
+    const h = hourPillar(adapter, dtLocal, {
+        longitudeDeg,
+        tzOffsetHours,
+        useMeanSolarTimeForHour,
+        dayBoundary,
+        useMeanSolarTimeForBoundary,
+    });
+    return {
+        year: y.pillar,
+        month: m.pillar,
+        day: d.pillar,
+        hour: h.pillar,
+        meta: {
+            solarYearUsed: y.solarYear,
+            sunLonDeg: m.sunLonDeg,
+            effectiveDayDate: effDate,
+            adjustedDtForHour: adapter.toISO(h.adjustedDt),
+            preset,
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { DateAdapter } from "@/adapters/date-adapter";
+export { applyMeanSolarTime, BRANCHES, dayPillarFromDate, effectiveDayDate, getFourPillars, hourPillar, monthPillar, presetA, presetB, STANDARD_PRESET, STEMS, TRADITIONAL_PRESET, yearPillar, } from "@/core/four-pillars";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EACL,kBAAkB,EAClB,QAAQ,EACR,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,UAAU,EACV,WAAW,EACX,OAAO,EACP,OAAO,EACP,eAAe,EACf,KAAK,EACL,kBAAkB,EAClB,UAAU,GACX,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export { applyMeanSolarTime, BRANCHES, dayPillarFromDate, effectiveDayDate, getFourPillars, hourPillar, monthPillar, presetA, presetB, STANDARD_PRESET, STEMS, TRADITIONAL_PRESET, yearPillar, } from "@/core/four-pillars";

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@gracefullight/saju",
+  "version": "0.1.0",
+  "description": "Four Pillars (四柱) calculator with flexible date adapter support",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./adapters/luxon": {
+      "import": "./dist/adapters/luxon.js",
+      "types": "./dist/adapters/luxon.d.ts"
+    },
+    "./adapters/date-fns": {
+      "import": "./dist/adapters/date-fns.js",
+      "types": "./dist/adapters/date-fns.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage",
+    "lint": "biome check src",
+    "lint:fix": "biome check --write src",
+    "format": "biome format --write src"
+  },
+  "keywords": [
+    "saju",
+    "four-pillars",
+    "bazi",
+    "chinese-astrology",
+    "korean-astrology"
+  ],
+  "author": "gracefullight",
+  "license": "MIT",
+  "peerDependencies": {
+    "date-fns": "^4.0.0",
+    "date-fns-tz": "^3.0.0",
+    "luxon": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "date-fns": {
+      "optional": true
+    },
+    "date-fns-tz": {
+      "optional": true
+    },
+    "luxon": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/luxon": "^3.4.2",
+    "@vitest/coverage-v8": "^2.1.8",
+    "@vitest/ui": "^2.1.8",
+    "date-fns": "^4.1.0",
+    "date-fns-tz": "^3.2.0",
+    "luxon": "^3.5.0",
+    "vitest": "^2.1.8"
+  }
+}