ko-chrono 0.1.0 → 0.3.0

package/dist/resolve.js

@@ -1,3 +1,5 @@
+import { toRRule } from './parsers/recurrence.js';
+import { lunarHoliday, lunarToSolar } from './util/lunarHolidays.js';
 function startOfWeek(d, weekStart) {
     const r = new Date(d);
     r.setHours(0, 0, 0, 0);
@@ -9,6 +11,22 @@ function startOfWeek(d, weekStart) {
 function lastDayOfMonth(y, m0) {
     return new Date(y, m0 + 1, 0).getDate();
 }
+/** 그 달의 N번째 요일이 며칠인지. nth = -1이면 마지막. 없으면 null ("다섯째 주 토요일") */
+function nthWeekdayOfMonth(y, m0, weekday, nth) {
+    const last = lastDayOfMonth(y, m0);
+    let day = 1 + ((weekday - new Date(y, m0, 1).getDay() + 7) % 7);
+    if (nth > 0)
+        day += (nth - 1) * 7;
+    else
+        while (day + 7 <= last)
+            day += 7;
+    return day > last ? null : day;
+}
+/** 규칙 20: 오전/오후 없는 1~6시는 오후 ("3시에 보자" → 15시). 7~11시는 그대로 */
+function clockHour(c) {
+    const h = c.hour;
+    return !c.meridiem && h >= 1 && h <= 6 ? h + 12 : h;
+}
 /** 기준일의 "일"을 유지하되 그 달에 없으면 말일로 (2월 29일 + 1년 → 2월 28일) */
 function sameDayIn(y, m0, day) {
     return new Date(y, m0, Math.min(day, lastDayOfMonth(y, m0)));
@@ -44,6 +62,7 @@ export function merge(list) {
 }
 const DATE_KEYS = [
     'year', 'yearOffset', 'month', 'day', 'dayOffset', 'weekOffset', 'weekday', 'monthOffset', 'monthPart',
+    'lunar', 'lunarDate',
 ];
 /** 날짜 정보 없이 시각만 있는 조각인지 ("5시까지", "17:00") */
 export function isTimeOnly(c) {
@@ -96,13 +115,48 @@ function hasConflict(a, b) {
 export function resolve(group, opts) {
     const c = merge(group.map((f) => f.components));
     const ref = opts.referenceDate;
+    // "내일 이 시간" → 기준 시각의 시:분. "다음 주 이 시간"은 7일 뒤 (그 주 월요일이 아니라)
+    if (c.sameTime && c.hour === undefined) {
+        c.hour = ref.getHours();
+        c.minute = ref.getMinutes();
+        c.meridiem = true;
+        if (c.weekOffset !== undefined && c.weekday === undefined)
+            c.sameDay = true;
+    }
+    if (c.recur)
+        return resolveRecurrence(group, c, opts);
     let d = new Date(ref);
     d.setSeconds(0, 0);
     let dateSet = false;
     const hasTime = c.hour !== undefined || c.hourOffset !== undefined || c.minuteOffset !== undefined;
-    // 1. 절대 날짜
+    // 0. 음력 명절·음력 날짜 (규칙 29, 32): 연도를 말했으면 그 음력 해, 아니면 (연휴까지) 지나지 않은 가장 가까운 것.
+    //    음력 12월은 양력으로 다음 해 1월이라 작년 음력부터 본다. 표에 없는 날짜는 null
     const hasYear = c.year !== undefined || c.yearOffset !== undefined;
-    if (hasYear || c.month !== undefined || c.day !== undefined) {
+    const isLunar = c.lunar !== undefined || c.lunarDate !== undefined;
+    if (isLunar) {
+        const said = c.year ?? (c.yearOffset !== undefined ? ref.getFullYear() + c.yearOffset : undefined);
+        const tail = (c.dayOffset ?? 0) + (c.durationDays ? c.durationDays - 1 : 0);
+        const y0 = ref.getFullYear();
+        const years = said !== undefined ? [said] : [y0 - 1, y0, y0 + 1, y0 + 2];
+        const solarOf = (y) => c.lunar ? lunarHoliday(y, c.lunar) : lunarToSolar(y, c.lunarDate.month, c.lunarDate.day, c.lunarDate.leap);
+        let found = null;
+        for (const y of years) {
+            const s = solarOf(y);
+            if (!s)
+                continue; // 그 해에 없는 날 ("음력 2월 30일", 윤달)
+            const lastMoment = new Date(s.getFullYear(), s.getMonth(), s.getDate() + tail, 23, 59);
+            if (said !== undefined || lastMoment >= ref) {
+                found = s;
+                break;
+            }
+        }
+        if (!found)
+            return null;
+        d = found;
+        dateSet = true;
+    }
+    // 1. 절대 날짜
+    if (!isLunar && (hasYear || c.month !== undefined || c.day !== undefined)) {
         let y = c.year ?? ref.getFullYear() + (c.yearOffset ?? 0);
         // "작년", "내년"처럼 연도만 있으면 1월 1일. "내년 이맘때", "1년 뒤"는 오늘 날짜 유지
         const m0 = c.month !== undefined ? c.month - 1 : hasYear && !c.sameDay ? 0 : ref.getMonth();
@@ -140,15 +194,9 @@ export function resolve(group, opts) {
         const y = dateSet ? d.getFullYear() : ref.getFullYear();
         const m0 = dateSet ? d.getMonth() : ref.getMonth();
         const target = c.weekday ?? (opts.weekStart === 'monday' ? 1 : 0);
-        const last = lastDayOfMonth(y, m0);
-        let day = 1 + ((target - new Date(y, m0, 1).getDay() + 7) % 7);
-        if (c.nthWeek > 0)
-            day += (c.nthWeek - 1) * 7;
-        else
-            while (day + 7 <= last)
-                day += 7;
+        const day = nthWeekdayOfMonth(y, m0, target, c.nthWeek);
         // "11월 다섯째 주 토요일"처럼 없는 날짜는 null
-        if (day > last)
+        if (day === null)
             return null;
         d = new Date(y, m0, day);
         dateSet = true;
@@ -202,8 +250,7 @@ export function resolve(group, opts) {
     }
     // 6. 시각
     if (c.hour !== undefined) {
-        // 규칙 20: 오전/오후 없는 1~6시는 오후 ("3시에 보자" → 15시). 7~11시는 그대로.
-        const hour = !c.meridiem && c.hour >= 1 && c.hour <= 6 ? c.hour + 12 : c.hour;
+        const hour = clockHour(c);
         if (!dateSet) {
             d = new Date(ref);
             // 시간만 있고 날짜가 없으면: 오늘, 이미 지났으면 내일
@@ -232,10 +279,16 @@ export function resolve(group, opts) {
     else {
         return null;
     }
+    // 안전장치: 어떤 경로로든 계산이 깨진 날짜는 내보내지 않는다
+    if (Number.isNaN(d.getTime()))
+        return null;
+    const ambiguity = ambiguityOf(c, d, dateSet, opts);
     const first = group[0];
     const last = group[group.length - 1];
     // text는 parseAll()에서 원문 slice로 채운다. _end는 그때 쓰는 내부 값.
     const result = { date: d, text: '', index: first.index, hasTime };
+    if (ambiguity)
+        result.ambiguity = ambiguity;
     result._end = last.index + last.text.length;
     // "오늘부터 3일간", "3시부터 2시간 동안": 시작일을 포함한 기간의 끝
     if (c.durationDays !== undefined || c.durationMonths !== undefined || c.durationMinutes !== undefined) {
@@ -260,8 +313,9 @@ export function resolve(group, opts) {
         // "~까지", "~이내": 시작은 기준 시각, 끝은 해당 시점(시간 없으면 그날 23:59)
         // "~내내": 시작은 그 기간의 시작, 끝은 기간의 끝
         result.end = hasTime ? new Date(d) : periodEnd(d, c);
+        // 규칙 30: "어제까지"처럼 이미 지난 마감은 구간이 아니라 그 시점 (date = end)
         if (c.isEnd)
-            result.date = new Date(ref);
+            result.date = result.end < ref ? new Date(result.end) : new Date(ref);
     }
     return result;
 }
@@ -277,6 +331,103 @@ function periodEnd(d, c) {
     end.setHours(23, 59, 0, 0);
     return end;
 }
+/**
+ * 반복 일정 (규칙 27): date = 기준 시각 이후 첫 발생.
+ * 시각이 있으면 지난 시각은 건너뛰고, 날짜만 있으면 오늘도 포함한다.
+ * "매달 31일"은 31일이 없는 달을 건너뛴다 (RRULE과 같은 동작).
+ */
+function resolveRecurrence(group, c, opts) {
+    const r = c.recur;
+    const ref = opts.referenceDate;
+    const hasTime = c.hour !== undefined;
+    const today = new Date(ref);
+    today.setHours(0, 0, 0, 0);
+    const at = (day) => {
+        const x = new Date(day);
+        x.setHours(hasTime ? clockHour(c) : opts.defaultHour, hasTime ? c.minute ?? 0 : 0, 0, 0);
+        return x;
+    };
+    const ok = (x) => (hasTime ? x >= ref : x >= today);
+    let d = null;
+    if (r.freq === 'MINUTELY' || r.freq === 'HOURLY') {
+        d = new Date(ref);
+        d.setSeconds(0, 0);
+        d.setMinutes(d.getMinutes() + r.interval * (r.freq === 'HOURLY' ? 60 : 1));
+    }
+    else if (r.freq === 'DAILY') {
+        d = at(today);
+        if (!ok(d))
+            d.setDate(d.getDate() + 1);
+    }
+    else if (r.freq === 'WEEKLY') {
+        for (let i = 0; i < 14 && !d; i++) {
+            const day = new Date(today.getFullYear(), today.getMonth(), today.getDate() + i);
+            if (r.byWeekday?.includes(day.getDay()) && ok(at(day)))
+                d = at(day);
+        }
+    }
+    else if (r.freq === 'MONTHLY') {
+        for (let k = 0; k < 24 && !d; k++) {
+            const y = today.getFullYear(), m0 = today.getMonth() + k;
+            const dom = r.byWeekdayNth !== undefined
+                ? nthWeekdayOfMonth(y, m0, r.byWeekday[0], r.byWeekdayNth)
+                : r.byMonthDay === -1 ? lastDayOfMonth(y, m0) : r.byMonthDay;
+            if (dom === null || dom > lastDayOfMonth(y, m0))
+                continue;
+            const x = at(new Date(y, m0, dom));
+            if (ok(x))
+                d = x;
+        }
+    }
+    else {
+        // YEARLY: 2월 29일은 다음 윤년까지
+        for (let k = 0; k < 9 && !d; k++) {
+            const y = today.getFullYear() + k, m0 = r.byMonth - 1;
+            if (r.byMonthDay > lastDayOfMonth(y, m0))
+                continue;
+            const x = at(new Date(y, m0, r.byMonthDay));
+            if (ok(x))
+                d = x;
+        }
+    }
+    if (!d)
+        return null;
+    const last = group[group.length - 1];
+    const result = {
+        date: d,
+        text: '',
+        index: group[0].index,
+        hasTime: hasTime || r.freq === 'HOURLY' || r.freq === 'MINUTELY',
+        recurrence: { ...r, rrule: toRRule(r) },
+    };
+    result._end = last.index + last.text.length;
+    return result;
+}
+/** 규칙 31: 해석이 갈릴 수 있는 지점과 다른 후보 */
+function ambiguityOf(c, d, dateSet, opts) {
+    const ref = opts.referenceDate;
+    // 오전/오후 없는 1~12시: 반대쪽 12시간이 후보 (날짜가 없으면 규칙 4대로 다음 발생)
+    if (c.hour !== undefined && !c.meridiem && !c.midnight && c.hour >= 1 && c.hour <= 12) {
+        const used = clockHour(c);
+        const altHour = used === 12 ? 0 : used < 12 ? used + 12 : used - 12;
+        const alt = new Date(dateSet ? d : ref);
+        alt.setHours(altHour, c.minute ?? 0, 0, 0);
+        if (!dateSet && alt < ref)
+            alt.setDate(alt.getDate() + 1);
+        return { reason: 'meridiem', alternatives: [alt] };
+    }
+    // "다음 토요일": 규칙 23(오늘 제외 가장 가까운)과 "다음 주 토요일"이 다르면 후보로
+    if (c.weekdayDir === 'next' && c.weekday !== undefined) {
+        const alt = startOfWeek(ref, opts.weekStart);
+        alt.setDate(alt.getDate() + 7 + (opts.weekStart === 'monday' ? (c.weekday + 6) % 7 : c.weekday));
+        alt.setHours(d.getHours(), d.getMinutes(), 0, 0);
+        if (alt.getTime() !== d.getTime())
+            return { reason: 'next-weekday', alternatives: [alt] };
+    }
+    if (c.approximate)
+        return { reason: 'approximate-time', alternatives: [] };
+    return undefined;
+}
 function partDay(y, m0, part) {
     if (part === 'start')
         return 1;

package/dist/types.d.ts

@@ -6,7 +6,15 @@ export interface ParseOptions {
     weekStart?: WeekStart;
     /** 시간이 명시되지 않았을 때 넣을 시(hour). 기본값: 0 (00:00) */
     defaultHour?: number;
+    /**
+     * "오후 3시"를 어느 시간대의 3시로 볼지. IANA 이름 ('Asia/Seoul', 'UTC', 'America/New_York').
+     * 기본값: 실행 환경의 시간대. 서버(UTC)에서 한국 사용자 문장을 처리할 땐 'Asia/Seoul'을 넘긴다.
+     * 없는 이름이면 RangeError.
+     */
+    timezone?: string;
 }
+/** resolve()가 쓰는 옵션. timezone은 parseAll()이 앞뒤에서 처리하므로 빠진다. */
+export type ResolveOptions = Required<Omit<ParseOptions, 'timezone'>>;
 /** 파서들이 추출하는 중간 결과. 날짜/시간 중 아는 것만 채운다. */
 export interface Components {
     year?: number;
@@ -26,6 +34,20 @@ export interface Components {
     weekdayDir?: 'past' | 'next';
     /** "1년 뒤", "내년 이맘때": 연/월/주 이동 시 기준일의 날짜를 유지 */
     sameDay?: boolean;
+    /** "저녁", "아침"처럼 관례로 정한 시각 */
+    approximate?: boolean;
+    /** "내일 이 시간": 기준 시각의 시:분을 쓴다 */
+    sameTime?: boolean;
+    /** 음력 명절 (설날·추석·부처님 오신 날). 양력 날짜는 resolve가 util/lunarHolidays 표에서 찾는다 */
+    lunar?: 'seollal' | 'chuseok' | 'buddha';
+    /** "음력 3월 3일", "음력 윤5월 1일" */
+    lunarDate?: {
+        month: number;
+        day: number;
+        leap: boolean;
+    };
+    /** "매주 월요일", "매달 15일": 반복 규칙 (rrule은 resolve가 만든다) */
+    recur?: Omit<Recurrence, 'rrule'>;
     /** 연 단위 이동 (내년=+1). 지정되면 "지난 월일 → 내년" 규칙을 적용하지 않는다 */
     yearOffset?: number;
     /** 월 단위 이동 (다음달=+1) */
@@ -52,11 +74,38 @@ export interface Components {
     /** 이 조각이 "~부터" 시작점인지 */
     isStart?: boolean;
 }
+export type Frequency = 'MINUTELY' | 'HOURLY' | 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'YEARLY';
+/** 반복 일정. 필드 이름과 값은 RFC 5545 RRULE을 따른다 */
+export interface Recurrence {
+    freq: Frequency;
+    /** 몇 번째마다 (격주 = 2) */
+    interval: number;
+    /** 요일들. 0=일 … 6=토 */
+    byWeekday?: number[];
+    /** 매달 N번째 요일 ("마지막 주 금요일" = -1). byWeekday와 함께 쓴다 */
+    byWeekdayNth?: number;
+    /** 매달 며칠 (말일 = -1) */
+    byMonthDay?: number;
+    /** 매년 몇 월 */
+    byMonth?: number;
+    /** 'FREQ=WEEKLY;BYDAY=MO,WE,FR'. date를 DTSTART로 함께 쓰면 캘린더에 그대로 넣을 수 있다 */
+    rrule: string;
+}
 export interface Fragment {
     text: string;
     index: number;
     components: Components;
 }
+/**
+ * 해석이 갈릴 수 있다는 표시 (규칙 31). 기본 해석은 결과의 date(마감이면 end)이고, 다른 후보가 alternatives.
+ * - meridiem: 오전/오후 없는 시각 ("3시" → 15시, 후보 3시)
+ * - next-weekday: "다음 토요일"이 이번 주의 다음 토요일인지 다음 주 토요일인지
+ * - approximate-time: "저녁", "아침"처럼 관례로 정한 시각 (후보 없음)
+ */
+export interface Ambiguity {
+    reason: 'meridiem' | 'next-weekday' | 'approximate-time';
+    alternatives: Date[];
+}
 export interface ParseResult {
     /** 해석된 시각 (구간이면 시작) */
     date: Date;
@@ -68,5 +117,9 @@ export interface ParseResult {
     index: number;
     /** 시간이 명시되었는지 */
     hasTime: boolean;
+    /** 반복 일정이면 그 규칙. date는 기준 시각 이후 첫 발생 */
+    recurrence?: Recurrence;
+    /** 해석이 갈릴 수 있으면 그 이유와 다른 후보. 사용자에게 되묻거나 LLM에 넘길지 판단할 때 쓴다 */
+    ambiguity?: Ambiguity;
 }
 export type Parser = (text: string) => Fragment[];

package/dist/util/lunarHolidays.d.ts

@@ -0,0 +1,11 @@
+export type LunarHoliday = 'seollal' | 'chuseok' | 'buddha';
+export declare const LUNAR_YEARS: number[];
+/**
+ * 음력 → 양력. 그 달에 없는 날(29일인 달의 30일)이나 표에 없는 날짜는 null.
+ * 마지막 달처럼 길이를 모르면 29일까지만 받는다.
+ */
+export declare function lunarToSolar(year: number, month: number, day: number, leap?: boolean): Date | null;
+/** 설날(1/1)·부처님 오신 날(4/8)·추석(8/15)의 양력 날짜 */
+export declare function lunarHoliday(year: number, which: LunarHoliday): Date | null;
+/** 각 음력 달의 길이 (검증용). 모르면 null */
+export declare function monthLengths(year: number): (number | null)[];

package/dist/util/lunarHolidays.js

@@ -0,0 +1,76 @@
+// 음력 → 양력 변환표. 런타임 의존성 없이 음력을 다루려면 표가 필요하다.
+//
+// 출처: 한국천문연구원 천문우주지식정보 "월별 양음력 대조" (astro.kasi.re.kr/life/post/calendarData)
+//       2025~2028년 페이지에서 음력 초하루(1일)가 되는 양력 날짜를 옮겼다.
+//       설날·부처님 오신 날·추석 12개가 관공서 공휴일 목록과 일치하는지 tests/lunar.test.ts에서 확인한다.
+// KASI는 2~3년 앞까지만 공식 자료를 낸다 (2026-10 기준 2028년까지).
+// 새 연도가 공개되면 그 해의 초하루 목록을 추가하고, 직전 해 마지막 달의 길이가 확정되는지 확인할 것.
+// 표에 없는 날짜는 추측하지 않고 null (규칙 10). 한국 음력은 한국 표준시 기준이라 중국과 하루 다를 수 있다.
+const MONTH_STARTS = {
+    2025: [
+        [1, false, 2025, 1, 29], [2, false, 2025, 2, 28], [3, false, 2025, 3, 29], [4, false, 2025, 4, 28],
+        [5, false, 2025, 5, 27], [6, false, 2025, 6, 25], [6, true, 2025, 7, 25], [7, false, 2025, 8, 23],
+        [8, false, 2025, 9, 22], [9, false, 2025, 10, 21], [10, false, 2025, 11, 20], [11, false, 2025, 12, 20],
+        [12, false, 2026, 1, 19],
+    ],
+    2026: [
+        [1, false, 2026, 2, 17], [2, false, 2026, 3, 19], [3, false, 2026, 4, 17], [4, false, 2026, 5, 17],
+        [5, false, 2026, 6, 15], [6, false, 2026, 7, 14], [7, false, 2026, 8, 13], [8, false, 2026, 9, 11],
+        [9, false, 2026, 10, 11], [10, false, 2026, 11, 9], [11, false, 2026, 12, 9], [12, false, 2027, 1, 8],
+    ],
+    2027: [
+        [1, false, 2027, 2, 7], [2, false, 2027, 3, 8], [3, false, 2027, 4, 7], [4, false, 2027, 5, 6],
+        [5, false, 2027, 6, 5], [6, false, 2027, 7, 4], [7, false, 2027, 8, 2], [8, false, 2027, 9, 1],
+        [9, false, 2027, 9, 30], [10, false, 2027, 10, 29], [11, false, 2027, 11, 28], [12, false, 2027, 12, 28],
+    ],
+    2028: [
+        [1, false, 2028, 1, 27], [2, false, 2028, 2, 25], [3, false, 2028, 3, 26], [4, false, 2028, 4, 25],
+        [5, false, 2028, 5, 24], [5, true, 2028, 6, 23], [6, false, 2028, 7, 22], [7, false, 2028, 8, 20],
+        [8, false, 2028, 9, 19], [9, false, 2028, 10, 18], [10, false, 2028, 11, 16], [11, false, 2028, 12, 16],
+        [12, false, 2029, 1, 15],
+    ],
+};
+export const LUNAR_YEARS = Object.keys(MONTH_STARTS).map(Number);
+const DAY = 86_400_000;
+const solar = (s) => new Date(s[2], s[3] - 1, s[4]);
+/** 그 음력 달의 다음 달 초하루 (모르면 null) */
+function nextStart(year, index) {
+    const months = MONTH_STARTS[year];
+    if (index + 1 < months.length)
+        return solar(months[index + 1]);
+    const next = MONTH_STARTS[year + 1];
+    return next ? solar(next[0]) : null;
+}
+/**
+ * 음력 → 양력. 그 달에 없는 날(29일인 달의 30일)이나 표에 없는 날짜는 null.
+ * 마지막 달처럼 길이를 모르면 29일까지만 받는다.
+ */
+export function lunarToSolar(year, month, day, leap = false) {
+    const months = MONTH_STARTS[year];
+    if (!months || day < 1 || day > 30)
+        return null;
+    const index = months.findIndex(([m, l]) => m === month && l === leap);
+    if (index < 0)
+        return null;
+    const start = solar(months[index]);
+    const next = nextStart(year, index);
+    const length = next ? Math.round((next.getTime() - start.getTime()) / DAY) : 29;
+    if (day > length)
+        return null;
+    return new Date(start.getFullYear(), start.getMonth(), start.getDate() + day - 1);
+}
+/** 설날(1/1)·부처님 오신 날(4/8)·추석(8/15)의 양력 날짜 */
+export function lunarHoliday(year, which) {
+    if (which === 'seollal')
+        return lunarToSolar(year, 1, 1);
+    if (which === 'buddha')
+        return lunarToSolar(year, 4, 8);
+    return lunarToSolar(year, 8, 15);
+}
+/** 각 음력 달의 길이 (검증용). 모르면 null */
+export function monthLengths(year) {
+    return MONTH_STARTS[year].map((s, i) => {
+        const next = nextStart(year, i);
+        return next ? Math.round((next.getTime() - solar(s).getTime()) / DAY) : null;
+    });
+}

package/dist/util/timezone.d.ts

@@ -0,0 +1,4 @@
+/** 실제 시점 → 그 시간대의 벽시계 시각을 로컬 필드로 갖는 Date */
+export declare function toWallClock(instant: Date, timeZone: string): Date;
+/** 로컬 필드를 그 시간대의 벽시계 시각으로 보고 → 실제 시점 */
+export declare function fromWallClock(wall: Date, timeZone: string): Date;

package/dist/util/timezone.js

@@ -0,0 +1,51 @@
+// IANA 시간대 변환. 런타임 의존성 없이 Intl만 쓴다.
+//
+// resolve.ts는 Date의 로컬 getter/setter로 계산한다. timezone 옵션이 있으면
+// 기준 시각을 그 시간대의 벽시계 시각(로컬 필드가 같은 Date)으로 바꿔 계산하고,
+// 결과의 벽시계 시각을 다시 실제 시점으로 되돌린다.
+const formatters = new Map();
+function formatter(timeZone) {
+    let f = formatters.get(timeZone);
+    if (!f) {
+        // 없는 시간대면 여기서 RangeError
+        f = new Intl.DateTimeFormat('en-US', {
+            timeZone,
+            hourCycle: 'h23',
+            year: 'numeric',
+            month: 'numeric',
+            day: 'numeric',
+            hour: 'numeric',
+            minute: 'numeric',
+            second: 'numeric',
+        });
+        formatters.set(timeZone, f);
+    }
+    return f;
+}
+/** 시점 t에서 그 시간대의 벽시계 필드 */
+function fieldsAt(t, timeZone) {
+    const parts = {};
+    for (const p of formatter(timeZone).formatToParts(new Date(t))) {
+        if (p.type !== 'literal')
+            parts[p.type] = +p.value;
+    }
+    return [parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second];
+}
+/** 시점 t에서 그 시간대의 UTC 오프셋(ms). 서울 = +9h */
+function offsetAt(t, timeZone) {
+    const [y, m0, d, h, mi, s] = fieldsAt(t, timeZone);
+    return Date.UTC(y, m0, d, h, mi, s) - (t - (t % 1000));
+}
+/** 실제 시점 → 그 시간대의 벽시계 시각을 로컬 필드로 갖는 Date */
+export function toWallClock(instant, timeZone) {
+    const [y, m0, d, h, mi, s] = fieldsAt(instant.getTime(), timeZone);
+    return new Date(y, m0, d, h, mi, s, instant.getMilliseconds());
+}
+/** 로컬 필드를 그 시간대의 벽시계 시각으로 보고 → 실제 시점 */
+export function fromWallClock(wall, timeZone) {
+    const asUtc = Date.UTC(wall.getFullYear(), wall.getMonth(), wall.getDate(), wall.getHours(), wall.getMinutes(), wall.getSeconds(), wall.getMilliseconds());
+    // 오프셋은 시점에 따라 달라지므로(서머타임) 한 번 더 맞춘다
+    const first = offsetAt(asUtc, timeZone);
+    const second = offsetAt(asUtc - first, timeZone);
+    return new Date(asUtc - second);
+}

package/package.json

@@ -1,19 +1,27 @@
 {
   "name": "ko-chrono",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "한국어 자연어 날짜/시간 파서 — '다음주 화요일 오후 3시' → Date",
   "type": "module",
-  "main": "./dist/index.js",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
     }
   },
+  "sideEffects": false,
   "files": ["dist", "README.md", "LICENSE"],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.cjs.json && node scripts/mark-cjs.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",