@craftguild/jscalendar 0.2.0 → 0.3.1

package/dist/recurrence/expand.js

@@ -0,0 +1,294 @@
+import { applyPatch } from "../patch.js";
+import { dateTimeInTimeZone, localDateTimeFromDate, localDateTimeToUtcDate } from "../utils.js";
+import { TYPE_EVENT, TYPE_TASK } from "./constants.js";
+import { expandRule } from "./rules.js";
+/**
+ * Expand recurrence into occurrences.
+ * @param items JSCalendar objects to expand.
+ * @param range Date range bounds.
+ * @return Generator of expanded occurrences.
+ */
+export function* expandRecurrence(items, range) {
+    for (const item of items) {
+        if (item["@type"] === TYPE_EVENT) {
+            yield* expandEvent(item, range);
+        }
+        else if (item["@type"] === TYPE_TASK) {
+            yield* expandTask(item, range);
+        }
+        else {
+            yield item;
+        }
+    }
+}
+/**
+ * Expand recurrence paged into occurrences.
+ * @param items JSCalendar objects to expand.
+ * @param range Date range bounds.
+ * @param options Pagination options.
+ * @return Page of expanded items plus an optional next cursor.
+ */
+export function expandRecurrencePaged(items, range, options) {
+    const result = [];
+    let nextCursor;
+    for (const occurrence of expandRecurrence(items, range)) {
+        const key = occurrenceKey(occurrence);
+        if (options.cursor && key) {
+            if (key <= options.cursor) {
+                continue;
+            }
+        }
+        else if (options.cursor && !key) {
+            continue;
+        }
+        result.push(occurrence);
+        if (key) {
+            nextCursor = key;
+        }
+        if (result.length >= options.limit) {
+            break;
+        }
+    }
+    return { items: result, nextCursor };
+}
+/**
+ * Expand event into occurrences.
+ * @param event Event to expand.
+ * @param range Date range bounds.
+ * @return Generator of expanded occurrences.
+ */
+function expandEvent(event, range) {
+    return expandObject(event, range, event.start, event.recurrenceRules, event.excludedRecurrenceRules, event.recurrenceOverrides, event.timeZone ?? null);
+}
+/**
+ * Expand task into occurrences.
+ * @param task Task to expand.
+ * @param range Date range bounds.
+ * @return Generator of expanded occurrences.
+ */
+function expandTask(task, range) {
+    const anchor = task.start ?? task.due;
+    if (!anchor) {
+        return (function* empty() { })();
+    }
+    return expandObject(task, range, anchor, task.recurrenceRules, task.excludedRecurrenceRules, task.recurrenceOverrides, task.timeZone ?? null);
+}
+/**
+ * Build a stable ordering key for an occurrence.
+ * @param value Occurrence object.
+ * @return Sort key or undefined when not available.
+ */
+function occurrenceKey(value) {
+    if (value.recurrenceId)
+        return value.recurrenceId;
+    if (value["@type"] === TYPE_EVENT)
+        return value.start;
+    if (value["@type"] === TYPE_TASK)
+        return value.start ?? value.due;
+    return undefined;
+}
+/**
+ * Expand object into occurrences.
+ * @param base Base JSCalendar object.
+ * @param range Date range bounds.
+ * @param anchor Anchor LocalDateTime for the series.
+ * @param rules Inclusion recurrence rules.
+ * @param excludedRules Exclusion recurrence rules.
+ * @param overrides Recurrence overrides keyed by LocalDateTime.
+ * @param recurrenceIdTimeZone Optional time zone for recurrence IDs.
+ * @return Generator of expanded occurrences.
+ */
+function* expandObject(base, range, anchor, rules, excludedRules, overrides, recurrenceIdTimeZone) {
+    const hasZone = Boolean(recurrenceIdTimeZone);
+    const fromLocal = hasZone && recurrenceIdTimeZone
+        ? dateTimeInTimeZone(range.from, recurrenceIdTimeZone)
+        : localDateTimeFromDate(range.from);
+    const toLocal = hasZone && recurrenceIdTimeZone
+        ? dateTimeInTimeZone(range.to, recurrenceIdTimeZone)
+        : localDateTimeFromDate(range.to);
+    const fromDate = range.from;
+    const toDate = range.to;
+    const overrideKeys = overrides ? Object.keys(overrides) : [];
+    if (!rules || rules.length === 0) {
+        if (hasZone && recurrenceIdTimeZone) {
+            if (isInRangeWithZone(anchor, fromDate, toDate, recurrenceIdTimeZone)) {
+                yield base;
+            }
+        }
+        else if (isInRange(anchor, fromLocal, toLocal)) {
+            yield base;
+        }
+        for (const key of overrideKeys) {
+            const patch = overrides ? overrides[key] : undefined;
+            const instance = buildInstance(base, key, recurrenceIdTimeZone, patch);
+            if (!instance)
+                continue;
+            if (hasZone && recurrenceIdTimeZone) {
+                if (isInRangeWithZone(key, fromDate, toDate, recurrenceIdTimeZone)) {
+                    yield instance;
+                }
+            }
+            else if (isInRange(key, fromLocal, toLocal)) {
+                yield instance;
+            }
+        }
+        return;
+    }
+    const occurrences = [];
+    for (const rule of rules) {
+        const expanded = expandRule(anchor, rule, fromLocal, toLocal, true, recurrenceIdTimeZone ?? undefined, fromDate, toDate);
+        occurrences.push(...expanded);
+    }
+    const excluded = new Set();
+    if (excludedRules && excludedRules.length > 0) {
+        for (const rule of excludedRules) {
+            const expanded = expandRule(anchor, rule, fromLocal, toLocal, true, recurrenceIdTimeZone ?? undefined, fromDate, toDate);
+            for (const value of expanded) {
+                excluded.add(value);
+            }
+        }
+    }
+    if (!occurrences.includes(anchor)) {
+        occurrences.push(anchor);
+    }
+    for (const key of overrideKeys) {
+        if (!occurrences.includes(key)) {
+            occurrences.push(key);
+        }
+    }
+    let sorted = Array.from(new Set(occurrences)).sort((a, b) => compareLocal(a, b, recurrenceIdTimeZone ?? undefined));
+    if (rules[0]?.count && sorted.length > rules[0].count) {
+        sorted = sorted.slice(0, rules[0].count);
+    }
+    for (const dt of sorted) {
+        if (excluded.has(dt))
+            continue;
+        const patch = overrides ? overrides[dt] : undefined;
+        const instance = buildInstance(base, dt, recurrenceIdTimeZone, patch);
+        if (!instance)
+            continue;
+        if (hasZone && recurrenceIdTimeZone) {
+            if (isInRangeWithZone(dt, fromDate, toDate, recurrenceIdTimeZone)) {
+                yield instance;
+            }
+        }
+        else if (isInRange(dt, fromLocal, toLocal)) {
+            yield instance;
+        }
+    }
+}
+/**
+ * Build an occurrence instance from a base object plus override patch.
+ * @param base Base JSCalendar object.
+ * @param recurrenceId LocalDateTime recurrence id.
+ * @param recurrenceIdTimeZone Optional time zone for recurrence id.
+ * @param patch Override patch for the occurrence.
+ * @return Occurrence instance or null if excluded.
+ */
+function buildInstance(base, recurrenceId, recurrenceIdTimeZone, patch) {
+    const patched = patch ? applyPatch(base, patch) : base;
+    if (isExcludedInstance(patched)) {
+        return null;
+    }
+    const overridesStart = patchHasKey(patch, "start");
+    const overridesDue = patchHasKey(patch, "due");
+    let shifted;
+    if (patched["@type"] === TYPE_EVENT) {
+        shifted = overridesStart ? patched : { ...patched, start: recurrenceId };
+    }
+    else if (patched["@type"] === TYPE_TASK) {
+        if (patched.start) {
+            shifted = overridesStart ? patched : { ...patched, start: recurrenceId };
+        }
+        else if (patched.due) {
+            shifted = overridesDue ? patched : { ...patched, due: recurrenceId };
+        }
+        else {
+            shifted = patched;
+        }
+    }
+    else {
+        shifted = patched;
+    }
+    const instance = {
+        ...stripRecurrenceProperties(shifted),
+        recurrenceId,
+    };
+    if (recurrenceIdTimeZone) {
+        instance.recurrenceIdTimeZone = recurrenceIdTimeZone;
+    }
+    return instance;
+}
+/**
+ * Check if a patch contains a key or pointer.
+ * @param patch Patch object to inspect.
+ * @param key Field name to look up.
+ * @return True when the patch modifies the field.
+ */
+function patchHasKey(patch, key) {
+    if (!patch)
+        return false;
+    if (Object.prototype.hasOwnProperty.call(patch, key))
+        return true;
+    if (Object.prototype.hasOwnProperty.call(patch, `/${key}`))
+        return true;
+    return false;
+}
+/**
+ * Strip recurrence properties from value.
+ * @param object JSCalendar object to clean.
+ * @return Object without recurrence rule fields.
+ */
+function stripRecurrenceProperties(object) {
+    const { recurrenceRules: _recurrenceRules, excludedRecurrenceRules: _excludedRecurrenceRules, recurrenceOverrides: _recurrenceOverrides, ...rest } = object;
+    return rest;
+}
+/**
+ * Check whether value is excluded instance.
+ * @param object JSCalendar object.
+ * @return True when the occurrence is excluded.
+ */
+function isExcludedInstance(object) {
+    return object.excluded === true;
+}
+/**
+ * Check whether value is in range.
+ * @param value LocalDateTime string.
+ * @param from LocalDateTime lower bound.
+ * @param to LocalDateTime upper bound.
+ * @return True when value is within the range.
+ */
+function isInRange(value, from, to) {
+    return value >= from && value <= to;
+}
+/**
+ * Check whether value is in range with zone.
+ * @param value LocalDateTime string.
+ * @param from Date lower bound.
+ * @param to Date upper bound.
+ * @param timeZone Time zone for LocalDateTime conversion.
+ * @return True when value is within the range.
+ */
+function isInRangeWithZone(value, from, to, timeZone) {
+    const utc = localDateTimeToUtcDate(value, timeZone);
+    return utc >= from && utc <= to;
+}
+/**
+ * Compare local date-time strings, optionally using a time zone.
+ * @param a LocalDateTime string A.
+ * @param b LocalDateTime string B.
+ * @param timeZone Optional time zone for comparison.
+ * @return Negative/zero/positive comparison result.
+ */
+function compareLocal(a, b, timeZone) {
+    if (!timeZone) {
+        if (a === b)
+            return 0;
+        return a < b ? -1 : 1;
+    }
+    const aUtc = localDateTimeToUtcDate(a, timeZone).getTime();
+    const bUtc = localDateTimeToUtcDate(b, timeZone).getTime();
+    if (aUtc === bUtc)
+        return 0;
+    return aUtc < bUtc ? -1 : 1;
+}

package/dist/recurrence/rule-candidates.d.ts

@@ -0,0 +1,21 @@
+import type { RecurrenceRule } from "../types.js";
+import type { DateCandidate, DateTime, DayOfWeek } from "./types.js";
+/**
+ * Build candidate dates for the current recurrence period.
+ * @param periodStart Start of the current recurrence period.
+ * @param rule Normalized recurrence rule.
+ * @param firstDay First day of the week for weekly calculations.
+ * @param skip Skip policy for invalid month days.
+ * @return Candidate dates for further filtering.
+ */
+export declare function generateDateCandidates(periodStart: DateTime, rule: RecurrenceRule, firstDay: DayOfWeek, skip: string): DateCandidate[];
+/**
+ * Apply BY* filters and skip behavior to candidate dates.
+ * @param candidates Candidate dates for the period.
+ * @param rule Normalized recurrence rule.
+ * @param periodStart Start of the current recurrence period.
+ * @param firstDay First day of the week for weekly calculations.
+ * @param skip Skip policy for invalid month days.
+ * @return Filtered candidate dates.
+ */
+export declare function filterDateCandidates(candidates: DateCandidate[], rule: RecurrenceRule, periodStart: DateTime, firstDay: DayOfWeek, skip: string): DateCandidate[];

package/dist/recurrence/rule-candidates.js

@@ -0,0 +1,120 @@
+import { FREQ_DAILY, FREQ_HOURLY, FREQ_MINUTELY, FREQ_MONTHLY, FREQ_SECONDLY, FREQ_WEEKLY, FREQ_YEARLY, SKIP_BACKWARD, SKIP_FORWARD, SKIP_OMIT } from "./constants.js";
+import { addDays, addMonths, daysInMonth, pad } from "./date-utils.js";
+import { matchesByDay, matchesByMonthDay, matchesByWeekNo, matchesByYearDay } from "./rule-matchers.js";
+/**
+ * Build candidate dates for the current recurrence period.
+ * @param periodStart Start of the current recurrence period.
+ * @param rule Normalized recurrence rule.
+ * @param firstDay First day of the week for weekly calculations.
+ * @param skip Skip policy for invalid month days.
+ * @return Candidate dates for further filtering.
+ */
+export function generateDateCandidates(periodStart, rule, firstDay, skip) {
+    const result = [];
+    const wantsInvalid = skip !== SKIP_OMIT && rule.byMonthDay && rule.byMonthDay.length > 0;
+    if (rule.frequency === FREQ_YEARLY) {
+        for (let month = 1; month <= 12; month += 1) {
+            const maxDays = wantsInvalid ? 31 : daysInMonth(periodStart.year, month);
+            for (let day = 1; day <= maxDays; day += 1) {
+                const valid = day <= daysInMonth(periodStart.year, month);
+                result.push({ year: periodStart.year, month, day, valid });
+            }
+        }
+        return result;
+    }
+    if (rule.frequency === FREQ_MONTHLY) {
+        const maxDays = wantsInvalid ? 31 : daysInMonth(periodStart.year, periodStart.month);
+        for (let day = 1; day <= maxDays; day += 1) {
+            const valid = day <= daysInMonth(periodStart.year, periodStart.month);
+            result.push({ year: periodStart.year, month: periodStart.month, day, valid });
+        }
+        return result;
+    }
+    if (rule.frequency === FREQ_WEEKLY) {
+        let cursor = periodStart;
+        for (let i = 0; i < 7; i += 1) {
+            result.push({ year: cursor.year, month: cursor.month, day: cursor.day, valid: true });
+            cursor = addDays(cursor, 1);
+        }
+        return result;
+    }
+    if (rule.frequency === FREQ_DAILY) {
+        result.push({ year: periodStart.year, month: periodStart.month, day: periodStart.day, valid: true });
+        return result;
+    }
+    if (rule.frequency === FREQ_HOURLY || rule.frequency === FREQ_MINUTELY || rule.frequency === FREQ_SECONDLY) {
+        result.push({ year: periodStart.year, month: periodStart.month, day: periodStart.day, valid: true });
+        return result;
+    }
+    return result;
+}
+/**
+ * Apply BY* filters and skip behavior to candidate dates.
+ * @param candidates Candidate dates for the period.
+ * @param rule Normalized recurrence rule.
+ * @param periodStart Start of the current recurrence period.
+ * @param firstDay First day of the week for weekly calculations.
+ * @param skip Skip policy for invalid month days.
+ * @return Filtered candidate dates.
+ */
+export function filterDateCandidates(candidates, rule, periodStart, firstDay, skip) {
+    let result = candidates;
+    if (rule.byMonth && rule.byMonth.length > 0) {
+        const months = rule.byMonth.map((m) => parseInt(m, 10)).filter((m) => !Number.isNaN(m));
+        result = result.filter((d) => months.includes(d.month));
+    }
+    if (rule.byWeekNo && rule.byWeekNo.length > 0) {
+        const byWeekNo = rule.byWeekNo.filter((d) => d !== 0);
+        result = result.filter((d) => d.valid && matchesByWeekNo(d, byWeekNo, firstDay));
+    }
+    if (rule.byYearDay && rule.byYearDay.length > 0) {
+        const byYearDay = rule.byYearDay.filter((d) => d !== 0);
+        result = result.filter((d) => d.valid && matchesByYearDay(d, byYearDay));
+    }
+    if (rule.byMonthDay && rule.byMonthDay.length > 0) {
+        const byMonthDay = rule.byMonthDay.filter((d) => d !== 0);
+        result = result.filter((d) => matchesByMonthDay(d, byMonthDay));
+    }
+    const byDay = rule.byDay;
+    if (byDay && byDay.length > 0) {
+        result = result.filter((d) => matchesByDay(d, byDay, rule.frequency, periodStart, firstDay));
+    }
+    if (skip !== SKIP_OMIT && rule.byMonthDay && rule.byMonthDay.length > 0) {
+        result = adjustInvalidMonthDays(result, skip);
+    }
+    else {
+        result = result.filter((d) => d.valid);
+    }
+    return result;
+}
+/**
+ * Shift invalid month-day candidates using the skip policy.
+ * @param candidates Candidate dates that may include invalid month days.
+ * @param skip Skip policy for invalid month days.
+ * @return Candidates with invalid days adjusted or removed.
+ */
+function adjustInvalidMonthDays(candidates, skip) {
+    const adjusted = [];
+    for (const candidate of candidates) {
+        if (candidate.valid) {
+            adjusted.push(candidate);
+            continue;
+        }
+        if (skip === SKIP_FORWARD) {
+            const next = addMonths({ year: candidate.year, month: candidate.month, day: 1, hour: 0, minute: 0, second: 0 }, 1);
+            adjusted.push({ year: next.year, month: next.month, day: 1, valid: true });
+        }
+        else if (skip === SKIP_BACKWARD) {
+            const day = daysInMonth(candidate.year, candidate.month);
+            adjusted.push({ year: candidate.year, month: candidate.month, day, valid: true });
+        }
+    }
+    const deduped = new Map();
+    for (const candidate of adjusted) {
+        const key = `${pad(candidate.year, 4)}-${pad(candidate.month, 2)}-${pad(candidate.day, 2)}`;
+        if (!deduped.has(key)) {
+            deduped.set(key, candidate);
+        }
+    }
+    return Array.from(deduped.values());
+}

package/dist/recurrence/rule-generate.d.ts

@@ -0,0 +1,11 @@
+import type { RecurrenceRule } from "../types.js";
+import type { DateTime, DayOfWeek } from "./types.js";
+/**
+ * Generate date-time strings for the current period using rule filters.
+ * @param periodStart Start of the current recurrence period.
+ * @param rule Normalized recurrence rule.
+ * @param firstDay First day of the week for weekly calculations.
+ * @param skip Skip policy for invalid month days.
+ * @return Date-time strings for this period.
+ */
+export declare function generateDateTimes(periodStart: DateTime, rule: RecurrenceRule, firstDay: DayOfWeek, skip: string): string[];

package/dist/recurrence/rule-generate.js

@@ -0,0 +1,36 @@
+import { formatLocalDateTime } from "./date-utils.js";
+import { filterDateCandidates, generateDateCandidates } from "./rule-candidates.js";
+/**
+ * Generate date-time strings for the current period using rule filters.
+ * @param periodStart Start of the current recurrence period.
+ * @param rule Normalized recurrence rule.
+ * @param firstDay First day of the week for weekly calculations.
+ * @param skip Skip policy for invalid month days.
+ * @return Date-time strings for this period.
+ */
+export function generateDateTimes(periodStart, rule, firstDay, skip) {
+    const dateCandidates = generateDateCandidates(periodStart, rule, firstDay, skip);
+    const filteredDates = filterDateCandidates(dateCandidates, rule, periodStart, firstDay, skip);
+    const hours = rule.byHour && rule.byHour.length > 0 ? rule.byHour : [periodStart.hour];
+    const minutes = rule.byMinute && rule.byMinute.length > 0 ? rule.byMinute : [periodStart.minute];
+    const seconds = rule.bySecond && rule.bySecond.length > 0 ? rule.bySecond : [periodStart.second];
+    const result = [];
+    for (const date of filteredDates) {
+        for (const hour of hours) {
+            for (const minute of minutes) {
+                for (const second of seconds) {
+                    const dt = formatLocalDateTime({
+                        year: date.year,
+                        month: date.month,
+                        day: date.day,
+                        hour,
+                        minute,
+                        second,
+                    });
+                    result.push(dt);
+                }
+            }
+        }
+    }
+    return result;
+}

package/dist/recurrence/rule-matchers.d.ts

@@ -0,0 +1,34 @@
+import type { NDay, RecurrenceRule } from "../types.js";
+import type { DateCandidate, DateTime, DayOfWeek } from "./types.js";
+/**
+ * Check whether a candidate date matches BYMONTHDAY values.
+ * @param date Candidate date.
+ * @param byMonthDay BYMONTHDAY values (positive or negative).
+ * @return True when the candidate date matches any BYMONTHDAY value.
+ */
+export declare function matchesByMonthDay(date: DateCandidate, byMonthDay: number[]): boolean;
+/**
+ * Check whether a candidate date matches BYYEARDAY values.
+ * @param date Candidate date.
+ * @param byYearDay BYYEARDAY values (positive or negative).
+ * @return True when the candidate date matches any BYYEARDAY value.
+ */
+export declare function matchesByYearDay(date: DateCandidate, byYearDay: number[]): boolean;
+/**
+ * Check whether a candidate date matches BYWEEKNO values.
+ * @param date Candidate date.
+ * @param byWeekNo BYWEEKNO values (positive or negative).
+ * @param firstDay First day of the week for week number calculations.
+ * @return True when the candidate date matches any BYWEEKNO value.
+ */
+export declare function matchesByWeekNo(date: DateCandidate, byWeekNo: number[], firstDay: DayOfWeek): boolean;
+/**
+ * Check whether a candidate date matches BYDAY rules.
+ * @param date Candidate date.
+ * @param byDay BYDAY rules (with optional nth-of-period entries).
+ * @param frequency Rule frequency.
+ * @param periodStart Start of the current recurrence period.
+ * @param firstDay First day of the week for weekly calculations.
+ * @return True when the candidate date matches any BYDAY rule.
+ */
+export declare function matchesByDay(date: DateCandidate, byDay: NDay[], frequency: RecurrenceRule["frequency"], periodStart: DateTime, firstDay: DayOfWeek): boolean;

package/dist/recurrence/rule-matchers.js

@@ -0,0 +1,120 @@
+import { FREQ_MONTHLY, FREQ_YEARLY } from "./constants.js";
+import { addDays, dayOfWeek, dayOfYear, daysInMonth, daysInYear, totalWeeksInYear, weekNumber } from "./date-utils.js";
+/**
+ * Check whether a candidate date matches BYMONTHDAY values.
+ * @param date Candidate date.
+ * @param byMonthDay BYMONTHDAY values (positive or negative).
+ * @return True when the candidate date matches any BYMONTHDAY value.
+ */
+export function matchesByMonthDay(date, byMonthDay) {
+    const dim = daysInMonth(date.year, date.month);
+    for (const v of byMonthDay) {
+        if (v > 0 && date.day === v)
+            return true;
+        if (v < 0 && date.day === dim + v + 1)
+            return true;
+    }
+    return false;
+}
+/**
+ * Check whether a candidate date matches BYYEARDAY values.
+ * @param date Candidate date.
+ * @param byYearDay BYYEARDAY values (positive or negative).
+ * @return True when the candidate date matches any BYYEARDAY value.
+ */
+export function matchesByYearDay(date, byYearDay) {
+    const diy = daysInYear(date.year);
+    const doy = dayOfYear({ year: date.year, month: date.month, day: date.day, hour: 0, minute: 0, second: 0 });
+    for (const v of byYearDay) {
+        if (v > 0 && doy === v)
+            return true;
+        if (v < 0 && doy === diy + v + 1)
+            return true;
+    }
+    return false;
+}
+/**
+ * Check whether a candidate date matches BYWEEKNO values.
+ * @param date Candidate date.
+ * @param byWeekNo BYWEEKNO values (positive or negative).
+ * @param firstDay First day of the week for week number calculations.
+ * @return True when the candidate date matches any BYWEEKNO value.
+ */
+export function matchesByWeekNo(date, byWeekNo, firstDay) {
+    const week = weekNumber({ year: date.year, month: date.month, day: date.day, hour: 0, minute: 0, second: 0 }, firstDay);
+    const total = totalWeeksInYear(date.year, firstDay);
+    for (const v of byWeekNo) {
+        if (v > 0 && week === v)
+            return true;
+        if (v < 0 && week === total + v + 1)
+            return true;
+    }
+    return false;
+}
+/**
+ * Check whether a candidate date matches BYDAY rules.
+ * @param date Candidate date.
+ * @param byDay BYDAY rules (with optional nth-of-period entries).
+ * @param frequency Rule frequency.
+ * @param periodStart Start of the current recurrence period.
+ * @param firstDay First day of the week for weekly calculations.
+ * @return True when the candidate date matches any BYDAY rule.
+ */
+export function matchesByDay(date, byDay, frequency, periodStart, firstDay) {
+    const weekday = dayOfWeek({ year: date.year, month: date.month, day: date.day, hour: 0, minute: 0, second: 0 });
+    for (const entry of byDay) {
+        if (entry.nthOfPeriod === undefined) {
+            if (entry.day === weekday)
+                return true;
+            continue;
+        }
+        if (frequency !== FREQ_MONTHLY && frequency !== FREQ_YEARLY) {
+            continue;
+        }
+        const matches = listNthPeriodDates(date, frequency, periodStart, firstDay)
+            .filter((d) => dayOfWeek(d) === entry.day);
+        const index = entry.nthOfPeriod > 0 ? entry.nthOfPeriod - 1 : matches.length + entry.nthOfPeriod;
+        if (index >= 0 && index < matches.length) {
+            const target = matches[index];
+            if (target && target.year === date.year && target.month === date.month && target.day === date.day) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * List dates in the current period for nth-of-period matching.
+ * @param date Candidate date (year/month used for period selection).
+ * @param frequency Rule frequency.
+ * @param periodStart Start of the current recurrence period.
+ * @param firstDay First day of the week for weekly calculations.
+ * @return Date list used to resolve nth-of-period BYDAY entries.
+ */
+function listNthPeriodDates(date, frequency, periodStart, firstDay) {
+    if (frequency === FREQ_YEARLY) {
+        const result = [];
+        for (let month = 1; month <= 12; month += 1) {
+            const days = daysInMonth(date.year, month);
+            for (let day = 1; day <= days; day += 1) {
+                result.push({ year: date.year, month, day, hour: 0, minute: 0, second: 0 });
+            }
+        }
+        return result;
+    }
+    if (frequency === FREQ_MONTHLY) {
+        const result = [];
+        const days = daysInMonth(date.year, date.month);
+        for (let day = 1; day <= days; day += 1) {
+            result.push({ year: date.year, month: date.month, day, hour: 0, minute: 0, second: 0 });
+        }
+        return result;
+    }
+    const result = [];
+    let cursor = periodStart;
+    for (let i = 0; i < 7; i += 1) {
+        result.push({ year: cursor.year, month: cursor.month, day: cursor.day, hour: 0, minute: 0, second: 0 });
+        cursor = addDays(cursor, 1);
+    }
+    return result;
+}

package/dist/recurrence/rule-normalize.d.ts

@@ -0,0 +1,9 @@
+import type { RecurrenceRule } from "../types.js";
+import type { DateTime } from "./types.js";
+/**
+ * Normalize rule fields by copying arrays and filling defaults from the start date-time.
+ * @param rule Recurrence rule to normalize.
+ * @param start Anchor date-time that supplies default by* values.
+ * @return Normalized recurrence rule with default by* fields filled.
+ */
+export declare function normalizeRule(rule: RecurrenceRule, start: DateTime): RecurrenceRule;