ko-chrono 0.1.0 → 0.3.0

package/dist/cjs/resolve.js

@@ -0,0 +1,446 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.groupFragments = groupFragments;
+exports.merge = merge;
+exports.isTimeOnly = isTimeOnly;
+exports.isWeekdayOnly = isWeekdayOnly;
+exports.isDayOnly = isDayOnly;
+exports.alignEnd = alignEnd;
+exports.resolve = resolve;
+const recurrence_js_1 = require("./parsers/recurrence.js");
+const lunarHolidays_js_1 = require("./util/lunarHolidays.js");
+function startOfWeek(d, weekStart) {
+    const r = new Date(d);
+    r.setHours(0, 0, 0, 0);
+    const dow = r.getDay(); // 0=일
+    const diff = weekStart === 'monday' ? (dow + 6) % 7 : dow;
+    r.setDate(r.getDate() - diff);
+    return r;
+}
+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)));
+}
+// 조각 사이에 와도 같은 표현으로 묶는 것: "내일 오후", "내일은 오후", "토요일쯤 저녁", "모레도 2시"
+// "이나/아니면/랑"은 다른 선택지일 수 있어 묶지 않는다.
+const JOINER = /^(?:\s|,|에|의|엔|은|는|도|쯤|경|께|부터)*$/;
+/**
+ * 인접한 조각(fragment)을 하나로 합친다.
+ * 예: "다음주 화요일" + "오후 3시" → 하나의 결과.
+ * 인접 기준: 사이에 공백/쉼표/조사(에,의,엔,은,는,도)/어림말(쯤,경,께)만 있을 때.
+ */
+function groupFragments(fragments, text) {
+    const sorted = [...fragments].sort((a, b) => a.index - b.index);
+    const groups = [];
+    for (const f of sorted) {
+        const g = groups[groups.length - 1];
+        if (g) {
+            const last = g[g.length - 1];
+            const between = text.slice(last.index + last.text.length, f.index);
+            const conflict = hasConflict(merge(g.map((x) => x.components)), f.components);
+            if (JOINER.test(between) && !conflict) {
+                g.push(f);
+                continue;
+            }
+        }
+        groups.push([f]);
+    }
+    return groups;
+}
+function merge(list) {
+    return Object.assign({}, ...list);
+}
+const DATE_KEYS = [
+    'year', 'yearOffset', 'month', 'day', 'dayOffset', 'weekOffset', 'weekday', 'monthOffset', 'monthPart',
+    'lunar', 'lunarDate',
+];
+/** 날짜 정보 없이 시각만 있는 조각인지 ("5시까지", "17:00") */
+function isTimeOnly(c) {
+    return (c.hour !== undefined &&
+        c.hourOffset === undefined &&
+        c.minuteOffset === undefined &&
+        !DATE_KEYS.some((k) => c[k] !== undefined));
+}
+/** 날짜 정보가 요일뿐인 조각인지 ("금요일까지") */
+function isWeekdayOnly(c) {
+    return c.weekday !== undefined && DATE_KEYS.every((k) => k === 'weekday' || c[k] === undefined);
+}
+/** 날짜 정보가 "N일"뿐인 조각인지 ("3일까지") */
+function isDayOnly(c) {
+    return c.day !== undefined && DATE_KEYS.every((k) => k === 'day' || c[k] === undefined);
+}
+/**
+ * 시 범위의 끝을 시작에 맞춘다 (규칙 16).
+ * 끝을 시작과 같은 날에 놓고, 시작보다 이르면 오전/오후를 이어받거나(+12h) 다음날로 넘긴다.
+ * "오후 3~5시" → 17시, "오후 11시부터 1시까지" → 다음날 1시, "오후 3시부터 오전 1시까지" → 다음날 1시
+ */
+function alignEnd(start, end) {
+    const hour = end.hour;
+    const r = new Date(start);
+    r.setHours(hour, end.minute ?? 0, 0, 0);
+    if (r <= start) {
+        if (!end.meridiem && hour < 12 && hour + 12 > start.getHours())
+            r.setHours(hour + 12);
+        else
+            r.setDate(r.getDate() + 1);
+    }
+    return r;
+}
+/** 같은 종류의 정보가 두 번 나오면 다른 날짜 표현으로 본다 (예: "3일 5일"). */
+function hasConflict(a, b) {
+    const dayKeys = ['day', 'dayOffset', 'weekday', 'monthPart'];
+    const timeKeys = ['hour'];
+    const both = (keys) => keys.some((k) => a[k] !== undefined) && keys.some((k) => b[k] !== undefined);
+    // 규칙 15: "내일" + "30분 후"는 서로 다른 표현
+    const dateKeys = DATE_KEYS;
+    const relKeys = ['hourOffset', 'minuteOffset'];
+    const has = (x, keys) => keys.some((k) => x[k] !== undefined);
+    const dateVsRel = (has(a, dateKeys) && has(b, relKeys)) || (has(a, relKeys) && has(b, dateKeys));
+    // "11월 5일 목요일": 날짜 뒤의 요일은 덧붙이는 말이라 충돌이 아니다
+    const weekdayNote = (x, y) => x.day !== undefined && y.weekday !== undefined && !y.weekend &&
+        y.weekOffset === undefined && y.day === undefined && y.dayOffset === undefined && y.monthPart === undefined;
+    const dayConflict = both(dayKeys) && !weekdayNote(a, b) && !weekdayNote(b, a);
+    return dayConflict || both(timeKeys) || dateVsRel;
+}
+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;
+    // 0. 음력 명절·음력 날짜 (규칙 29, 32): 연도를 말했으면 그 음력 해, 아니면 (연휴까지) 지나지 않은 가장 가까운 것.
+    //    음력 12월은 양력으로 다음 해 1월이라 작년 음력부터 본다. 표에 없는 날짜는 null
+    const hasYear = c.year !== undefined || c.yearOffset !== 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 ? (0, lunarHolidays_js_1.lunarHoliday)(y, c.lunar) : (0, lunarHolidays_js_1.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();
+        // 연도 미지정 + 이미 지났으면 내년으로.
+        // 월일("3월 1일")은 그 날이, 월("3월", "2월 말")은 그 달이 통째로 지났을 때.
+        if (!hasYear && c.month !== undefined) {
+            const lastDay = c.day ?? lastDayOfMonth(y, m0);
+            if (new Date(y, m0, lastDay, 23, 59) < ref)
+                y += 1;
+        }
+        let day = c.day ?? (c.month !== undefined || (hasYear && !c.sameDay) ? 1 : ref.getDate());
+        if (c.monthPart)
+            day = partDay(y, m0, c.monthPart);
+        if (c.sameDay)
+            day = Math.min(day, lastDayOfMonth(y, m0));
+        // 2월 30일, 11월 31일처럼 없는 날짜는 다음 달로 넘기지 않고 버린다
+        if (day > lastDayOfMonth(y, m0))
+            return null;
+        d = new Date(y, m0, day);
+        dateSet = true;
+    }
+    // 2. 상대 월
+    if (c.monthOffset !== undefined) {
+        const y = ref.getFullYear();
+        const m0 = ref.getMonth() + c.monthOffset;
+        const day = c.monthPart ? partDay(y, m0, c.monthPart) : c.day ?? 1;
+        if (day > lastDayOfMonth(y, m0))
+            return null;
+        // "다음달 이맘때" → 오늘 날짜 유지
+        d = c.sameDay ? sameDayIn(y, m0, ref.getDate()) : new Date(y, m0, day);
+        dateSet = true;
+    }
+    // 3. N째 주 (규칙 22): 달은 1·2단계에서 정해진 달, 없으면 기준 달
+    if (c.nthWeek !== undefined) {
+        const y = dateSet ? d.getFullYear() : ref.getFullYear();
+        const m0 = dateSet ? d.getMonth() : ref.getMonth();
+        const target = c.weekday ?? (opts.weekStart === 'monday' ? 1 : 0);
+        const day = nthWeekdayOfMonth(y, m0, target, c.nthWeek);
+        // "11월 다섯째 주 토요일"처럼 없는 날짜는 null
+        if (day === null)
+            return null;
+        d = new Date(y, m0, day);
+        dateSet = true;
+    }
+    else if (c.weekday !== undefined && c.weekOffset === undefined && c.day !== undefined) {
+        // 4. 주 + 요일. "11월 5일 목요일": 날짜가 우선. 요일이 안 맞으면 어느 쪽이 맞는지 모르므로 null
+        if (d.getDay() !== c.weekday)
+            return null;
+    }
+    else if (c.weekOffset !== undefined || c.weekday !== undefined) {
+        if (c.weekOffset !== undefined && c.sameDay) {
+            // "다음주 이맘때" → 7일 뒤
+            d = new Date(ref);
+            d.setHours(0, 0, 0, 0);
+            d.setDate(d.getDate() + c.weekOffset * 7);
+        }
+        else if (c.weekOffset !== undefined) {
+            const sow = startOfWeek(ref, opts.weekStart);
+            sow.setDate(sow.getDate() + c.weekOffset * 7);
+            if (c.weekday !== undefined) {
+                const offsetInWeek = opts.weekStart === 'monday' ? (c.weekday + 6) % 7 : c.weekday;
+                sow.setDate(sow.getDate() + offsetInWeek);
+            }
+            d = sow;
+        }
+        else {
+            // 요일 단독: 오늘 포함, 가장 가까운 미래의 그 요일
+            const today = new Date(ref);
+            today.setHours(0, 0, 0, 0);
+            const dow = today.getDay();
+            // "주말" 단독인데 오늘이 일요일이면 오늘
+            let diff = c.weekend && dow === 0 ? 0 : (c.weekday - dow + 7) % 7;
+            // "다음 금요일"은 오늘 제외 미래, "지난 금요일"은 오늘 제외 과거
+            if (c.weekdayDir === 'next' && diff === 0)
+                diff = 7;
+            if (c.weekdayDir === 'past')
+                diff = diff === 0 ? -7 : diff - 7;
+            today.setDate(today.getDate() + diff);
+            d = today;
+        }
+        dateSet = true;
+    }
+    // 5. 일 단위 상대 이동
+    if (c.dayOffset !== undefined) {
+        if (!dateSet) {
+            d = new Date(ref);
+            d.setHours(0, 0, 0, 0);
+        }
+        d.setDate(d.getDate() + c.dayOffset);
+        dateSet = true;
+    }
+    // 6. 시각
+    if (c.hour !== undefined) {
+        const hour = clockHour(c);
+        if (!dateSet) {
+            d = new Date(ref);
+            // 시간만 있고 날짜가 없으면: 오늘, 이미 지났으면 내일
+            d.setHours(hour, c.minute ?? 0, 0, 0);
+            if (d < ref)
+                d.setDate(d.getDate() + 1);
+        }
+        else {
+            d.setHours(hour, c.minute ?? 0, 0, 0);
+            // "내일 자정" = 내일이 끝나는 시점
+            if (c.midnight)
+                d.setDate(d.getDate() + 1);
+        }
+    }
+    else if (c.hourOffset !== undefined || c.minuteOffset !== undefined) {
+        d = new Date(ref);
+        d.setSeconds(0, 0);
+        if (c.hourOffset)
+            d.setHours(d.getHours() + c.hourOffset);
+        if (c.minuteOffset)
+            d.setMinutes(d.getMinutes() + c.minuteOffset);
+    }
+    else if (dateSet) {
+        d.setHours(opts.defaultHour, 0, 0, 0);
+    }
+    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) {
+        if (!dateSet && !hasTime)
+            return null;
+        const end = new Date(d);
+        if (c.durationMinutes !== undefined) {
+            end.setMinutes(end.getMinutes() + c.durationMinutes);
+        }
+        else {
+            if (c.durationMonths !== undefined)
+                end.setMonth(end.getMonth() + c.durationMonths);
+            if (c.durationDays !== undefined)
+                end.setDate(end.getDate() + c.durationDays);
+            end.setDate(end.getDate() - 1);
+            end.setHours(23, 59, 0, 0);
+        }
+        result.end = end;
+        return result;
+    }
+    if (c.isEnd || c.whole) {
+        // "~까지", "~이내": 시작은 기준 시각, 끝은 해당 시점(시간 없으면 그날 23:59)
+        // "~내내": 시작은 그 기간의 시작, 끝은 기간의 끝
+        result.end = hasTime ? new Date(d) : periodEnd(d, c);
+        // 규칙 30: "어제까지"처럼 이미 지난 마감은 구간이 아니라 그 시점 (date = end)
+        if (c.isEnd)
+            result.date = result.end < ref ? new Date(result.end) : new Date(ref);
+    }
+    return result;
+}
+/** 날짜 표현이 가리키는 기간의 마지막 시각. "이번 주" → 일요일, "이번달" → 말일, "올해" → 12/31, 그 외는 그날 23:59 */
+function periodEnd(d, c) {
+    let end = new Date(d);
+    if (c.weekOffset !== undefined && c.weekday === undefined)
+        end.setDate(end.getDate() + 6);
+    else if (c.monthOffset !== undefined && c.monthPart === undefined && c.day === undefined)
+        end = new Date(end.getFullYear(), end.getMonth(), lastDayOfMonth(end.getFullYear(), end.getMonth()));
+    else if ((c.year !== undefined || c.yearOffset !== undefined) && c.month === undefined && !c.sameDay)
+        end = new Date(end.getFullYear(), 11, 31);
+    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: (0, recurrence_js_1.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;
+    if (part === 'middle')
+        return 15;
+    return lastDayOfMonth(y, m0);
+}

package/dist/cjs/types.d.ts

@@ -0,0 +1,125 @@
+export type WeekStart = 'monday' | 'sunday';
+export interface ParseOptions {
+    /** 기준 시각. 기본값: new Date() */
+    referenceDate?: Date;
+    /** 주의 시작 요일. "이번주/다음주" 계산 기준. 기본값: 'monday' */
+    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;
+    month?: number;
+    day?: number;
+    hour?: number;
+    minute?: number;
+    /** 기준일로부터 일 단위 이동 (내일=+1) */
+    dayOffset?: number;
+    /** 기준 주로부터 주 단위 이동 (다음주=+1) */
+    weekOffset?: number;
+    /** 0=일 … 6=토 (JS getDay 규약) */
+    weekday?: number;
+    /** "주말" 단독: 오늘이 토/일이면 오늘, 아니면 다가오는 토요일 */
+    weekend?: boolean;
+    /** "지난 금요일"(오늘 제외 과거) / "다음 금요일"(오늘 제외 미래) */
+    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) */
+    monthOffset?: number;
+    /** 월 안의 위치: 초(1일)/중순(15일)/말(마지막날) */
+    monthPart?: 'start' | 'middle' | 'end';
+    /** 오전/오후 등이 명시됨 (15:30 같은 24시간 표기 포함). 시 범위의 끝을 맞출 때 쓴다 */
+    meridiem?: boolean;
+    /** "자정", "24시", "밤 12시": 날짜가 있으면 그 날의 끝(다음날 00:00) */
+    midnight?: boolean;
+    /** 시/분 단위 상대 이동 */
+    hourOffset?: number;
+    minuteOffset?: number;
+    /** "3일간", "2주 동안", "3박 4일": 앞의 날짜부터 이어지는 기간. 날짜 없이 단독이면 null */
+    durationDays?: number;
+    durationMonths?: number;
+    durationMinutes?: number;
+    /** "N째 주": 1~5, 마지막은 -1. weekday가 있으면 그 달의 N번째 그 요일, 없으면 N번째 주 시작일 */
+    nthWeek?: number;
+    /** "이번 주 내내": 그 기간 전체. date는 시작, end는 기간의 끝 */
+    whole?: boolean;
+    /** 이 조각이 "~까지" 종료점인지 */
+    isEnd?: boolean;
+    /** 이 조각이 "~부터" 시작점인지 */
+    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;
+    /** 구간의 끝. "~까지", "A부터 B까지" 인 경우만 */
+    end?: Date;
+    /** 입력에서 날짜로 인식된 부분 */
+    text: string;
+    /** 입력 내 위치 */
+    index: number;
+    /** 시간이 명시되었는지 */
+    hasTime: boolean;
+    /** 반복 일정이면 그 규칙. date는 기준 시각 이후 첫 발생 */
+    recurrence?: Recurrence;
+    /** 해석이 갈릴 수 있으면 그 이유와 다른 후보. 사용자에게 되묻거나 LLM에 넘길지 판단할 때 쓴다 */
+    ambiguity?: Ambiguity;
+}
+export type Parser = (text: string) => Fragment[];

package/dist/cjs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/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/cjs/util/lunarHolidays.js

@@ -0,0 +1,82 @@
+"use strict";
+// 음력 → 양력 변환표. 런타임 의존성 없이 음력을 다루려면 표가 필요하다.
+//
+// 출처: 한국천문연구원 천문우주지식정보 "월별 양음력 대조" (astro.kasi.re.kr/life/post/calendarData)
+//       2025~2028년 페이지에서 음력 초하루(1일)가 되는 양력 날짜를 옮겼다.
+//       설날·부처님 오신 날·추석 12개가 관공서 공휴일 목록과 일치하는지 tests/lunar.test.ts에서 확인한다.
+// KASI는 2~3년 앞까지만 공식 자료를 낸다 (2026-10 기준 2028년까지).
+// 새 연도가 공개되면 그 해의 초하루 목록을 추가하고, 직전 해 마지막 달의 길이가 확정되는지 확인할 것.
+// 표에 없는 날짜는 추측하지 않고 null (규칙 10). 한국 음력은 한국 표준시 기준이라 중국과 하루 다를 수 있다.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LUNAR_YEARS = void 0;
+exports.lunarToSolar = lunarToSolar;
+exports.lunarHoliday = lunarHoliday;
+exports.monthLengths = monthLengths;
+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],
+    ],
+};
+exports.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일까지만 받는다.
+ */
+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)의 양력 날짜 */
+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 */
+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/cjs/util/number.d.ts

@@ -0,0 +1,5 @@
+/**
+ * "3", "세", "열", "십이", "열두" → number. 실패 시 null.
+ * v0.1: 1~99 범위만 다룬다.
+ */
+export declare function parseKoreanNumber(s: string): number | null;