ko-chrono 0.1.0 → 0.2.0

package/dist/resolve.js

@@ -1,3 +1,5 @@
+import { toRRule } from './parsers/recurrence.js';
+import { LUNAR_HOLIDAYS } 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)));
@@ -96,13 +114,45 @@ 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): 연도를 말했으면 그 해, 아니면 올해 것이 (연휴까지) 지났을 때 내년.
+    //    공식 자료가 없는 연도는 null
     const hasYear = c.year !== undefined || c.yearOffset !== undefined;
-    if (hasYear || c.month !== undefined || c.day !== undefined) {
+    if (c.lunar) {
+        const said = c.year ?? (c.yearOffset !== undefined ? ref.getFullYear() + c.yearOffset : undefined);
+        const tail = (c.dayOffset ?? 0) + (c.durationDays ? c.durationDays - 1 : 0);
+        const years = said !== undefined ? [said] : [ref.getFullYear(), ref.getFullYear() + 1];
+        let found = null;
+        for (const y of years) {
+            const md = LUNAR_HOLIDAYS[y]?.[c.lunar];
+            if (!md)
+                break;
+            const lastMoment = new Date(y, md[0] - 1, md[1] + tail, 23, 59);
+            if (said !== undefined || lastMoment >= ref) {
+                found = new Date(y, md[0] - 1, md[1]);
+                break;
+            }
+        }
+        if (!found)
+            return null;
+        d = found;
+        dateSet = true;
+    }
+    // 1. 절대 날짜
+    if (!c.lunar && (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 +190,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 +246,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,6 +275,9 @@ export function resolve(group, opts) {
     else {
         return null;
     }
+    // 안전장치: 어떤 경로로든 계산이 깨진 날짜는 내보내지 않는다
+    if (Number.isNaN(d.getTime()))
+        return null;
     const first = group[0];
     const last = group[group.length - 1];
     // text는 parseAll()에서 원문 slice로 채운다. _end는 그때 쓰는 내부 값.
@@ -260,8 +306,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 +324,78 @@ 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;
+}
 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,12 @@ export interface Components {
     weekdayDir?: 'past' | 'next';
     /** "1년 뒤", "내년 이맘때": 연/월/주 이동 시 기준일의 날짜를 유지 */
     sameDay?: boolean;
+    /** "내일 이 시간": 기준 시각의 시:분을 쓴다 */
+    sameTime?: boolean;
+    /** 음력 명절 (설날·추석·부처님 오신 날). 양력 날짜는 resolve가 util/lunarHolidays 표에서 찾는다 */
+    lunar?: 'seollal' | 'chuseok' | 'buddha';
+    /** "매주 월요일", "매달 15일": 반복 규칙 (rrule은 resolve가 만든다) */
+    recur?: Omit<Recurrence, 'rrule'>;
     /** 연 단위 이동 (내년=+1). 지정되면 "지난 월일 → 내년" 규칙을 적용하지 않는다 */
     yearOffset?: number;
     /** 월 단위 이동 (다음달=+1) */
@@ -52,6 +66,23 @@ 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;
@@ -68,5 +99,7 @@ export interface ParseResult {
     index: number;
     /** 시간이 명시되었는지 */
     hasTime: boolean;
+    /** 반복 일정이면 그 규칙. date는 기준 시각 이후 첫 발생 */
+    recurrence?: Recurrence;
 }
 export type Parser = (text: string) => Fragment[];

package/dist/util/lunarHolidays.d.ts

@@ -0,0 +1,3 @@
+export type LunarHoliday = 'seollal' | 'chuseok' | 'buddha';
+/** 연도 → [월, 일] (양력) */
+export declare const LUNAR_HOLIDAYS: Record<number, Record<LunarHoliday, [number, number]>>;

package/dist/util/lunarHolidays.js

@@ -0,0 +1,13 @@
+// 음력 명절의 양력 날짜. 런타임 의존성 없이 음력 변환을 하려면 표가 필요하다.
+//
+// 출처: 한국천문연구원 천문우주지식정보 "월별 양음력 대조" (astro.kasi.re.kr/life/post/calendarData)
+//       2025년은 관공서 공휴일 목록. 2026년 부처님 오신 날·추석은 공휴일 목록으로 교차 확인.
+// KASI는 2~3년 앞까지만 공식 자료를 낸다 (2026-10 기준 2028년까지). 새 연도가 공개되면 한 줄 추가할 것.
+// 표에 없는 연도는 추측하지 않고 null (규칙 10). 한국 설날은 한국 표준시 기준이라 중국 춘절과 하루 다를 수 있다.
+/** 연도 → [월, 일] (양력) */
+export const LUNAR_HOLIDAYS = {
+    2025: { seollal: [1, 29], buddha: [5, 5], chuseok: [10, 6] },
+    2026: { seollal: [2, 17], buddha: [5, 24], chuseok: [9, 25] },
+    2027: { seollal: [2, 7], buddha: [5, 13], chuseok: [9, 15] },
+    2028: { seollal: [1, 27], buddha: [5, 2], chuseok: [10, 3] },
+};

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.2.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",