Skip to content

feat: expand recurring events into their occurrences - #94

Open
janbaer wants to merge 2 commits into
dominik1001:mainfrom
janbaer:feat/expand-recurring-events
Open

janbaer wants to merge 2 commits into
dominik1001:mainfrom
janbaer:feat/expand-recurring-events

Conversation

@janbaer

@janbaer janbaer commented Aug 16, 2026

Copy link
Copy Markdown
Contributor

list-events answers a query for next week with the DTSTART of a series that began two years ago, and the occurrences that actually fall inside the window are missing.

getEvents can ask the server to expand a series (RFC 4791 <C:expand>), but a server may ignore it, and Open-Xchange does: it returns the master with the RRULE intact. I verified that the <C:expand> element has no effect there.

This expands client side with the RRULE engine from ical.js, already a transitive dependency, now declared directly. Expansion runs on the wall clock of the event's own zone, so a weekly 14:00 appointment stays at 14:00 across a DST change instead of drifting an hour, and a whole-day event keeps its date rather than moving a day east of Greenwich. EXDATE is honoured as far as ts-caldav preserves it (it keeps only the first value of each property).

Behaviour change: a series now contributes one entry per occurrence, so several entries can share a uid. Each entry carries a recurring flag. Marked as a breaking change in the commit footer.

Nine unit tests added, including DST and whole-day cases. Verified against mailbox.org: the week that previously reported three 2024 dates now reports the seven actual appointments.

@janbaer

janbaer commented Aug 16, 2026

Copy link
Copy Markdown
Contributor Author

Related to #91, which fixes the same class of bug on the write path. This one is the read path: on expansion a whole-day occurrence was reported a day early for the same reason, because ical.js hands a VALUE=DATE over as local midnight and reading it back as UTC loses a day east of Greenwich.

No overlapping files, so the two should apply independently.

@janbaer
janbaer marked this pull request as draft August 16, 2026 15:39
@janbaer

janbaer commented Aug 16, 2026

Copy link
Copy Markdown
Contributor Author

Pushed a follow-up after a closer review of my own diff:

  • Rescheduled occurrences were reported twice. Moving a single instance of a series is an everyday operation, and the server answers it with two events sharing one uid: the master with its RRULE and a replacement carrying RECURRENCE-ID. Expanding the master still produced an occurrence at the slot the replacement vacated. RFC 5545 does not require an EXDATE there. RECURRENCE-ID survives in customFields but with its TZID parameter dropped, so matching happens on the wall clock rather than on an instant.
  • The iteration guard counted from the series' DTSTART, so a daily series older than about 27 years hit the cap before reaching a present-day window and silently returned nothing — the very failure this expansion exists to prevent. The walk now compares wall clocks and only converts occurrences near the window into instants, which is cheap enough to raise the cap and removes the repeated Intl.DateTimeFormat construction as a side effect.
  • A TZID that Intl rejects — the Windows zone names Exchange emits, for instance — threw out of the expansion and failed the entire list-events call rather than the one event. Such a zone now falls back to the local one.

Also dropped two unreachable branches in the EXDATE handling whose comment claimed the opposite.

@janbaer
janbaer marked this pull request as ready for review August 16, 2026 15:50
@janbaer

janbaer commented Aug 16, 2026

Copy link
Copy Markdown
Contributor Author

One more pass, this time on the shape of the change rather than its correctness. Four things came out of it.

Every occurrence now carries a handle. Expansion turned one series into many rows, each looking like a single meeting, while the only identifier on them was the series uid — so acting on one through update-event or delete-event hits every instance. Before expansion the stale DTSTART at least made such a row obviously wrong; afterwards it looks safe to act on. Each occurrence now carries occurrence, the wall-clock key in the shape of a RECURRENCE-ID, and recurring is derived rather than inferred from the presence of a rule, which was wrong for replacement instances.

The master/override correlation moved into the module as expandEvents. As a parameter on occurrencesWithin it encoded a precondition the signature could not state, and forgetting it produced duplicates rather than an error.

getEvents now asks for server-side expansion. Servers that honour expand return occurrences already correct, EXDATE and replacements included, and the local path stays for the ones that ignore it — which is the case this PR exists for.

Performance. The iterator was always seeded at the series DTSTART, so a daily series from 1990 cost roughly 13,000 steps to yield seven dates, measured at 185ms per event. Whole periods are now skipped for daily and weekly rules, which preserves the phase BYDAY evaluates; COUNT rules are left alone because there the position from the start decides when the series ends. Verified by comparing a jumped walk against a full one.

Also removed on the way through: a hand-written RRULE serializer that ICAL.Recur.fromData replaces, a wall-clock struct that ICAL.Time already is, a key builder that ICAL.Time.toString already produces, and a dead comma split in the EXDATE handling.

Two limits I could not fix, now stated in the module header rather than left implicit: RecurrenceRule drops BYSETPOS and friends before this code sees them, so "last weekday of the month" expands too generously; and only the first value of a repeated EXDATE survives getFirstValue().

Verified against mailbox.org for a summer and a winter week after the change.

@janbaer

janbaer commented Aug 16, 2026

Copy link
Copy Markdown
Contributor Author

Ran the review again over the rewritten branch, which turned up three more things.

  • The README tool docs were stale. npm run docs:check failed: the returns string gained occurrence but the generated section was never committed alongside it. Fixed and regenerated.
  • The warning about uid only existed in a source comment. An MCP caller never sees that. Since neither update-event nor delete-event takes anything finer than a uid, occurrence is display-only, and someone reading just the tool description would reasonably assume the two fields together address a single instance — and quietly rewrite the whole series instead. The description now spells it out.
  • An event carrying both a RECURRENCE-ID and a rule of its own was treated as a replacement, which stamped every occurrence it expanded into with the same key. RFC 5545 does not allow that combination, but surviving what servers actually send is the point of this module, so it is now ignored rather than honoured.

Also noted in the source that seeding the iterator somewhere other than the real DTSTART is not something ical.js documents as supported. It holds because the jump is an exact multiple of the period and the algorithm only looks at the phase, but an ical.js upgrade is a reason to re-verify it.

The core recurrence arithmetic came through this pass clean: seedNear was fuzz-checked against a from-scratch iterator over intervals 1 to 5, single and multiple BYDAY, windows before the series start, and month, year and leap boundaries; toRecur's key names and value shapes were checked against what ical.js actually accepts; and the occurrence-key comparison was confirmed to produce the same shape on both sides for whole-day series and for a TZID that Intl rejects.

@janbaer
janbaer force-pushed the feat/expand-recurring-events branch from 38def01 to 79489b3 Compare October 12, 2026 07:28
dominik1001 added a commit to janbaer/caldav-mcp that referenced this pull request Oct 23, 2026
Events that began before the query window but still overlap it must be
listed. Guards against regressions like the one in dominik1001#94, where only
events starting inside the window are returned.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@dominik1001 dominik1001 left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for working on this. Expanding recurring events closes a real gap in list-events, and the coverage in recurrence.test.ts is appreciated. However, the review turned up one regression in existing behaviour and several correctness problems in the expansion itself, so I am requesting changes for now.

Regression

Events that started before the query window but still overlap it are no longer returned. The previous implementation passed through everything the server's time-range filter matched; the new code keeps only events whose start lies inside the window. #114 adds a test for this on main, which is why the test job now fails on this branch: includes events that started before the window but overlap it returns only inside-window. Affected are multi-day events, meetings already running when the window starts, multi-day series occurrences, and all-day events in zones east of UTC (a Berlin all-day event on 21 Aug starts at 2026-08-20T22:00Z and is lost for a window starting at 2026-08-21T00:00Z).

Expansion correctness

The inline comments describe the individual problems: UNTIL compared at the wrong offset, a DATE-valued UNTIL dropping the last day, UTC-anchored series falling back to the system zone, UTC EXDATE and RECURRENCE-ID values never matching, Windows TZIDs, RDATE being ignored, RRULE parts lost in ts-caldav's RecurrenceRule, and all-day occurrences on DST days. The first four were reproduced by running recurrence.ts with TZ=Europe/Berlin; the remainder come from reading the code against ts-caldav and ical.js 2.2.1.

Design

Most of these share one root cause. recurrence.ts rebuilds rules, time zones and exception keys from ts-caldav's partial Event model, because ts-caldav discards the raw iCalendar data. ical.js already implements this: ICAL.Event with its iterator (RecurExpansion) handles the full RRULE, RDATE, EXDATE, RECURRENCE-ID and VTIMEZONE. On one hand, each case could be patched here; on the other hand, every further RFC 5545 edge case would then need another special case. I would prefer obtaining the raw VCALENDAR from ts-caldav (or upstreaming a raw/expand helper there) and letting ical.js do the expansion.

Suggested next steps

Fixing the overlap regression first would get CI green again. After that, it would be good to agree on the design question before addressing the remaining points, since several of them disappear if expansion moves to ical.js.

Comment thread src/tools/recurrence.ts Outdated
const recur = rule ? toRecur(rule) : undefined;

if (!recur || !rule) {
const inWindow = event.start >= windowStart && event.start < windowEnd;

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A non-recurring event is only kept when its start lies inside the window, so events that overlap the window are dropped. For example, an event from 2026-08-20T09:00Z to 2026-08-22T09:00Z, queried for 2026-08-21T00:00Z–2026-08-22T00:00Z, returns nothing; before this PR it was listed. The usual overlap condition would be event.start < windowEnd && event.end > windowStart. This is the case covered by the test from #114.

Comment thread src/tools/recurrence.ts Outdated
if (filtering && (skip.has(key) || replaced.has(key))) continue;

const start = instantOf(next, timeZone);
if (start >= windowStart && start < windowEnd) found.push({ start, key });

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same overlap issue for series occurrences: an occurrence that starts before windowStart but is still running is skipped. This needs the occurrence's end (start plus the series duration) to be compared against windowStart, and the lower walking bound has to reach back at least one duration for such occurrences to be visited.

Comment thread src/tools/recurrence.ts Outdated
const rule = event.recurrenceRule;
const recur = rule ? toRecur(rule) : undefined;

if (!recur || !rule) {

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

RDATE is not considered here. An event whose DTSTART lies before the window but has an RDATE inside it (e.g. DTSTART 2026-01-05 plus RDATE:20260821T100000Z, queried for the week of 21 Aug) is returned by the server because the RDATE instance overlaps. It is not treated as a series, its DTSTART is outside the window, and it disappears from the result. Before this PR it was listed.

Comment thread src/tools/recurrence.ts
freq: rule.freq,
...(rule.interval ? { interval: rule.interval } : {}),
...(rule.count ? { count: rule.count } : {}),
...(rule.until ? { until: ICAL.Time.fromJSDate(rule.until, true) } : {}),

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two problems with UNTIL here.

First, UNTIL becomes a UTC ICAL.Time, but the iterator walks floating wall-clock times, which ical.js compares with a zero offset. UNTIL is therefore shifted by the zone's UTC offset. A weekly series with DTSTART;TZID=Europe/Berlin:...T143000 and UNTIL=20260821T123000Z (the last occurrence, the form Outlook, Google and Apple write) yields 08-07 and 08-14 only; 08-21 is missing. In zones west of UTC, occurrences after UNTIL appear instead.

Second, for an all-day series with a DATE-valued UNTIL, ts-caldav turns the date into local midnight, and fromJSDate(..., true) makes that the previous day in UTC. A daily all-day series from 2026-08-17 with UNTIL=20260819 yields 17 and 18 Aug in Berlin; 19 Aug is missing.

Comment thread src/tools/recurrence.ts Outdated
* one falls back instead of taking the whole query down.
*/
function zoneOf(event: Event): string {
if (!event.startTzid) return systemZone();

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A DTSTART in UTC (the Z form, no TZID) falls back to the system zone here. The series is then expanded on local wall-clock time, so it drifts across DST: a weekly series with DTSTART:20261016T123000Z yields 13:30Z instead of 12:30Z after 25 Oct when the process runs in Berlin. Additionally, UTC EXDATE and RECURRENCE-ID keys no longer match the occurrence keys, so a cancelled instance is still listed and a moved instance appears twice. A UTC DTSTART should probably be walked in UTC.

Comment thread src/tools/recurrence.ts Outdated
): string | undefined {
const m = value
.trim()
.match(/^(\d{4})-?(\d{2})-?(\d{2})(?:T(\d{2}):?(\d{2}):?(\d{2}))?/);

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The key drops the trailing Z, so an EXDATE or RECURRENCE-ID given in UTC is compared as if it were wall-clock time in the series' zone. With DTSTART;TZID=Europe/Berlin:...T143000 and EXDATE:20260821T123000Z (valid per RFC 5545), the key 2026-08-21T12:30:00 never equals 2026-08-21T14:30:00, and the excluded date is shown. Server-expanded instances are affected as well, since RFC 4791 returns RECURRENCE-ID in UTC. UTC values would need to be converted into the series' zone before building the key.

Comment thread src/tools/recurrence.ts
formatterFor(event.startTzid);
return event.startTzid;
} catch {
return systemZone();

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When Intl rejects the TZID (for example Exchange's Windows names such as W. Europe Standard Time), expansion falls back to the system zone, while event.start was resolved through the event's VTIMEZONE. With the server running in UTC, such a series is walked at 12:30 instead of 14:30 wall time. EXDATE and RECURRENCE-ID keys then never match, near midnight BYDAY can land on the wrong day, and DST transitions are applied for the wrong zone. Using the VTIMEZONE from the calendar data would avoid this, which ts-caldav does not currently expose.

Comment thread src/tools/recurrence.ts
function toRecur(rule: RecurrenceRule): ICAL.Recur | undefined {
if (!rule.freq) return undefined;
const wkst = Number(rule.wkst);
return ICAL.Recur.fromData({

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The rule is rebuilt from ts-caldav's RecurrenceRule, which keeps no BYSETPOS, BYWEEKNO, BYYEARDAY or BYHOUR. Rules that use them now produce occurrences that do not exist, where the previous code showed only the master. For example, Apple's "first weekday of the month" (FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=1) expands to every weekday of every month, roughly 20 phantom meetings per month. For an agent reading list-events, each of these looks like a real conflict. If the raw RRULE cannot be obtained, it would be safer to fall back to returning the master for rules containing parts that cannot be represented.

Comment thread src/tools/list-events.ts
uid: event.uid,
summary: event.summary,
start,
end: new Date(

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The occurrence end is computed as start plus the master's duration in milliseconds. For all-day occurrences on a DST transition day this does not end at midnight: in Berlin, the 25 Oct 2026 occurrence of a daily all-day series (a 25-hour local day) ends at 23:00 local on 25 Oct instead of midnight on 26 Oct, and on the spring-forward day the end is 01:00 the next day. For all-day events, the duration would need to be applied in calendar days rather than milliseconds.

@janbaer

janbaer commented Nov 14, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for the review. I agree with the design point: most of the findings come from rebuilding rules, time zones and exception keys out of ts-caldav's partial Event, and patching each case would only move the problem.

I looked into doing it your way, and ts-caldav 0.4.5 doesn't give me what I'd need. Event carries no raw iCalendar data. getIcs() exists but is private, and the exported VTimezone type with a raw field isn't attached to Event. So there is nothing to hand to ICAL.Event and RecurExpansion.

Server-side expansion doesn't help either. getEvents({ expand: true }) only works on servers that honour it, and mailbox.org doesn't. I sent the same calendar-query for November and December 2026 with and without <c:expand> and got identical bodies: the masters with their RRULE, no RECURRENCE-ID instances.

A clean version needs a raw-data accessor or an expand helper in ts-caldav, or a dependency on the private getIcs(), which I'd rather not ship. Until then I don't want to keep patching recurrence.ts, so I'll put this PR on hold.

If a small raw-data or expand change in ts-caldav would be acceptable to you, I can start there and rebuild this on ical.js afterwards. The overlap regression you found is independent of all this, and I can split it into its own fix if you want it sooner.

list-events returned only the master of a recurring series, so a window
showed one entry (at the series' original date) instead of its
occurrences. Each occurrence now carries its own start and end,
`recurring`, and `occurrence`, the wall-clock key in the shape of a
RECURRENCE-ID. Servers that honour `expand` are asked to do the work;
the rest are expanded locally with ical.js.

`uid` still addresses the whole series: update-event and delete-event
take nothing finer, so the tool description says they change every
instance. Events that started before the window but still overlap it are
kept, for single events and for series occurrences alike.
@janbaer
janbaer force-pushed the feat/expand-recurring-events branch from a130fa9 to 040ff92 Compare November 14, 2026 11:37
…pand

Asking the server to expand made list-events fail on Radicale for a
recurring whole-day event: it answers with an instance carrying
`RECURRENCE-ID:20261117` without VALUE=DATE, which ts-caldav cannot parse
("invalid date-time value"), so the whole call errored. Servers that
ignore `expand` (mailbox.org) never hit this. The master is now always
expanded locally, which is the path the tests cover.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants