ko-chrono 0.1.0 → 0.2.0

package/dist/cjs/resolve.js

@@ -0,0 +1,414 @@
+"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',
+];
+/** 날짜 정보 없이 시각만 있는 조각인지 ("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): 연도를 말했으면 그 해, 아니면 올해 것이 (연휴까지) 지났을 때 내년.
+    //    공식 자료가 없는 연도는 null
+    const hasYear = c.year !== undefined || c.yearOffset !== 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 = lunarHolidays_js_1.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();
+        // 연도 미지정 + 이미 지났으면 내년으로.
+        // 월일("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 first = group[0];
+    const last = group[group.length - 1];
+    // text는 parseAll()에서 원문 slice로 채운다. _end는 그때 쓰는 내부 값.
+    const result = { date: d, text: '', index: first.index, hasTime };
+    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;
+}
+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,105 @@
+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;
+    /** "내일 이 시간": 기준 시각의 시:분을 쓴다 */
+    sameTime?: boolean;
+    /** 음력 명절 (설날·추석·부처님 오신 날). 양력 날짜는 resolve가 util/lunarHolidays 표에서 찾는다 */
+    lunar?: 'seollal' | 'chuseok' | 'buddha';
+    /** "매주 월요일", "매달 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;
+}
+export interface ParseResult {
+    /** 해석된 시각 (구간이면 시작) */
+    date: Date;
+    /** 구간의 끝. "~까지", "A부터 B까지" 인 경우만 */
+    end?: Date;
+    /** 입력에서 날짜로 인식된 부분 */
+    text: string;
+    /** 입력 내 위치 */
+    index: number;
+    /** 시간이 명시되었는지 */
+    hasTime: boolean;
+    /** 반복 일정이면 그 규칙. date는 기준 시각 이후 첫 발생 */
+    recurrence?: Recurrence;
+}
+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,3 @@
+export type LunarHoliday = 'seollal' | 'chuseok' | 'buddha';
+/** 연도 → [월, 일] (양력) */
+export declare const LUNAR_HOLIDAYS: Record<number, Record<LunarHoliday, [number, number]>>;

package/dist/cjs/util/lunarHolidays.js

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

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

package/dist/cjs/util/number.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseKoreanNumber = parseKoreanNumber;
+const NATIVE = {
+    한: 1, 하나: 1, 두: 2, 둘: 2, 세: 3, 셋: 3, 네: 4, 넷: 4,
+    다섯: 5, 여섯: 6, 일곱: 7, 여덟: 8, 아홉: 9, 열: 10,
+    열흘: 10, 보름: 15, 스무: 20, 스물: 20,
+    이틀: 2, 사흘: 3, 나흘: 4, 닷새: 5, 엿새: 6, 이레: 7, 여드레: 8, 아흐레: 9,
+};
+const SINO = {
+    일: 1, 이: 2, 삼: 3, 사: 4, 오: 5, 육: 6, 칠: 7, 팔: 8, 구: 9, 십: 10,
+};
+/**
+ * "3", "세", "열", "십이", "열두" → number. 실패 시 null.
+ * v0.1: 1~99 범위만 다룬다.
+ */
+function parseKoreanNumber(s) {
+    if (/^\d+$/.test(s))
+        return parseInt(s, 10);
+    if (s in NATIVE)
+        return NATIVE[s];
+    // 고유어 합성: 열두, 열다섯, 스무 ...
+    for (const tens of ['스물', '스무', '열']) {
+        if (s.startsWith(tens) && s.length > tens.length) {
+            const rest = NATIVE[s.slice(tens.length)];
+            if (rest != null)
+                return NATIVE[tens] + rest;
+        }
+    }
+    // 한자어: 십, 십이, 이십, 이십삼
+    if (/^[일이삼사오육칠팔구십]+$/.test(s)) {
+        const parts = s.split('십');
+        if (parts.length === 1)
+            return SINO[s] ?? null;
+        const tens = parts[0] === '' ? 1 : SINO[parts[0]];
+        const ones = parts[1] === '' ? 0 : SINO[parts[1]];
+        if (tens == null || ones == null)
+            return null;
+        return tens * 10 + ones;
+    }
+    return null;
+}

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

@@ -0,0 +1,55 @@
+"use strict";
+// IANA 시간대 변환. 런타임 의존성 없이 Intl만 쓴다.
+//
+// resolve.ts는 Date의 로컬 getter/setter로 계산한다. timezone 옵션이 있으면
+// 기준 시각을 그 시간대의 벽시계 시각(로컬 필드가 같은 Date)으로 바꿔 계산하고,
+// 결과의 벽시계 시각을 다시 실제 시점으로 되돌린다.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toWallClock = toWallClock;
+exports.fromWallClock = fromWallClock;
+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 */
+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());
+}
+/** 로컬 필드를 그 시간대의 벽시계 시각으로 보고 → 실제 시점 */
+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/dist/event.d.ts

@@ -0,0 +1,18 @@
+import type { ParseResult, Recurrence } from './types.js';
+/** parseEvent()의 결과: 할 일·일정 한 줄을 제목과 시점으로 나눈 것 */
+export interface ParsedEvent {
+    /** 날짜 부분을 뺀 나머지 ("내일 3시 치과" → "치과"). 없으면 '' */
+    title: string;
+    /** 첫 번째 날짜 표현의 date. 날짜가 없으면 null */
+    date: Date | null;
+    /** 구간의 끝이나 마감 */
+    end?: Date;
+    hasTime: boolean;
+    /** 반복 일정이면 그 규칙 */
+    recurrence?: Recurrence;
+}
+/**
+ * 문장에서 날짜로 인식된 부분과 거기 붙은 조사를 빼서 제목을 만든다 (규칙 28).
+ * 장소("강남역에서")나 동사("만나기")는 그대로 남긴다.
+ */
+export declare function toEvent(text: string, results: ParseResult[]): ParsedEvent;