ikieEngineeringGet started
All posts

Data modelCalendarTypeScript

We don't store repeating events

ikie never stores the occurrences of a repeating event. It stores the rule and computes occurrences whenever you look. Here is how an unstored occurrence gets an address, and how that address survives editing "all events" or "this and following".

한국어
DoneDeletedMoved
Write weekly report
  1. Mon Oct 59:00Done
  2. Mon Oct 129:00Deleted
  3. Mon Oct 199:00Tue 20, 14:00
  4. Mon Oct 269:00
  5. Mon Nov 29:00
One task that repeats every Monday at 9:00. No occurrence is stored anywhere. What is stored is one rule (FREQ=WEEKLY;BYDAY=MO) and the records attached to the three occurrences that changed.

Repeating events are among the most used features of any calendar app: the weekly meeting, the monthly card bill, the yearly birthday. They are also the feature calendar builders wrestle with longest. Behind the three buttons "this event", "this and following" and "all events" hide far more cases than you'd expect.

ikie treats events and tasks as one model. A repeating task is completed separately on each occurrence, and a checklist inside a repeating event is checked off separately for each meeting. This post is about doing all of that without storing a single occurrence.

What happens when you store every occurrence

There are two ways to store repetition. Expand the occurrences up front and save each as a row, or store only the rule and compute occurrences when you look.

Store every occurrence

Weekly Monday meetingone row per occurrence
Row for Oct 5Row for Oct 12… and with no end, until when?

Changing the rule means rebuilding and reconciling rows

Store only the rule

One ruleRRULE · added dates · removed dates
Record only what changedCompute occurrences on read

Change the rule and you're done

Storing rows is easy at first. Each occurrence is just a row, so completions and alerts hang off it. The trouble comes with edits. An endless series forces you to decide how far to expand. Switch the rule to "every other week" and you have to work out which of the existing rows to delete and which to keep. And where should the completions and notes on those rows go? Google Calendar and Apple Calendar both exchange repetition as rules, too. Expanded rows would have to be folded back into a rule on every sync.

ikie stores only the rule. The table holds the RRULE, added occurrences (RDATE) and removed ones (EXDATE). Occurrences are computed only for the range of days on screen (in ikie we call that the board). In the words of one of our principles:

Store only facts, never what can be derived from them. Occurrences can always be rebuilt from the rule, so we don't store them.

An address for every occurrence

To attach a completion or a new time to an occurrence that isn't stored, you need a way to point at it. In ikie, an occurrence's address is (item id, original start). It's the same idea as Google Calendar's recurringEventId with originalStartTime, or iCalendar's RECURRENCE-ID.

/** Occurrence key: a date for all-day, a UTC instant (ISO Z) for timed, local wall time for floating. */
export function occurrenceKey(time: ItemTime): string {
  if (time.kind === "zoned") return iso(Date.parse(time.start));
  return time.start;
}

A changed occurrence gets one row in the item_override table, keyed by this address. It records only the fields that changed: a new time, a new title, a cancellation, and per-occurrence state such as a task being done. Move the Oct 19 occurrence in the figure to Tuesday 14:00 and its address is still "Mon Oct 19, 9:00". The row just carries the new time. The address is where the occurrence originally was, so it never changes no matter where the occurrence moves.

Expanding (expand) builds the addresses in range from the rule, drops removed ones, and lays the changed records on top. It also picks up occurrences moved into the range from outside. If you pulled next Monday's occurrence forward to this Friday, it has to show up on this week's board.

Nine o'clock stays nine o'clock across DST

Rules are expanded in the local wall time of the series' starting time zone, not in UTC. A 9:00 Monday meeting in New York must stay at 9:00 after daylight saving ends on November 1. Expand in UTC and overnight it becomes an 8:00 meeting.

// Test: EDT (-4) → EST (-5) on November 1
expect(starts(ny, "2026-10-25T00:00:00Z", "2026-11-10T00:00:00Z"))
  .toEqual(["2026-10-26T13:00:00Z", "2026-11-02T14:00:00Z", "2026-11-09T14:00:00Z"]);

The UTC instant moves from 13:00 to 14:00, but on the local wall clock all three are at 9:00. All-day events are read as dates. Floating times, received with no time zone as "9:00 wherever you are", are read in the viewer's zone. We didn't write our own RRULE parser and expander. That job goes to the long-standing rrule library. What we wrote is the bridge between local wall time and instants.

Old series slowed the board down

Doesn't computing occurrences on every read get expensive? Once, it did. On an account with many connected calendars and 366 repeating events, reading a single board took 2.3–2.6 seconds. The database took 0.04 seconds. All the rest was expanding repeats.

There were two causes. First, we were re-expanding each item for every day (21 times for a 21-day board). Second, rrule counts occurrences one by one from the rule's start. A daily series started in 2001 counts past 9,000 occurrences before it reaches this week. So we expanded each item once, and for rules that started years ago, we pulled the start close to the viewed range.

case RRule.DAILY:
case RRule.WEEKLY: {
  const period = (options.freq === RRule.DAILY ? 1 : 7) * n * DAY;
  // Shifting by whole periods yields the same occurrences
  return start + Math.max(0, Math.floor((lo - start) / period) - 1) * period;
}

Only a shift by whole periods yields the same occurrences. Fields a rule silently takes from its start, like the day of month in "every month on the 31st", are written into the rule before shifting. Rules with a COUNT have to be counted from the beginning, so they're left alone. Twelve tricky rules check that the shifted result matches counting from the start: Feb 29 every leap year, the 31st of every month, the last Sunday of March, every four years, and more.

Next, a month board turned out to spend most of its time resolving time zones. Re-counting occurrence ranges every day meant tens of thousands of Intl time zone conversions per month. Caching each resolved instant and counting ranges once took a 340-event month from 200ms to 50ms (measured locally).

"Move all" has to move the addresses too

This is the heart of the post. An occurrence's address is its original start. So what happens when you move the whole series one day later?

Before
  1. Mon Oct 5Done
  2. Mon Oct 12Deleted
  3. Mon Oct 19Own alert
  4. Mon Oct 26
Addresses left alone
  1. Tue Oct 6Done is lost
  2. Tue Oct 13Comes back
  3. Tue Oct 20Alert never fires
  4. Tue Oct 27
Addresses moved too
  1. Tue Oct 6Done
  2. Tue Oct 13Deleted
  3. Tue Oct 20Own alert
  4. Tue Oct 27
We moved every Monday occurrence to Tuesday. If the addresses stay put, the records point at occurrences that no longer exist. Completions vanish, and deleted occurrences come back.

When the series start moves by a day, every address the rule produces moves by a day too. But the completion record still points at "Mon Oct 5". That occurrence no longer exists, so the record attaches to nothing, and the user sees a finished task reopen. The removed occurrence (EXDATE) also points at the old address, so the deleted Oct 13 occurrence comes back.

So when ikie moves a series in time, it moves every occurrence address pointing into that series by the same amount: changed occurrences and completions (item_override), removed and added dates, per-occurrence alerts, records of alerts already sent, and occurrences other tasks depend on ("this must be done first"). Per-occurrence completions of a checklist inside a repeating event move along too. How far to move is decided by a pure function that knows nothing about the database. It measures how far the occurrence the user opened and edited moved on the local wall clock, and the data layer just writes the result.

export function shiftedKey(shift: OccurrenceShift, key: string): string {
  if (!shift) return key; // edits that don't touch time keep the original address string
  const wall = msWall(wallMs(keyWall(shift.series, key)) + shift.delta);
  if (shift.allDay) return wall.slice(0, 10);
  const instant = wallToInstant(wall, shift.tz);
  // If the shifted wall time doesn't exist in that zone, don't guess
  if (instantToWall(instant, shift.tz) !== wall) throw new OccurrenceShiftConflict("Nonexistent shifted wall time");
  return iso(instant);
}

There were a few traps.

  1. A new address can equal another occurrence's old one. Move a daily series a day later and Oct 5's new address is Oct 6's old address. Updating row by row collides with rows not yet moved. So we read every row to move, delete them, and insert them back under their new addresses.
  2. DST creates times that don't exist. In New York, 2:30 a.m. on March 8, 2026 never happens. Push a 1:30 series an hour later, and a record on that day's occurrence would get a new address that doesn't exist. Rather than guessing 3:00, we refuse the edit (series_split_conflict) and the original stays exactly as it was.
  3. Two addresses can collapse into one. Turn a series with two occurrences on the same day into all-day, and both new addresses become the same date. We don't drop one of the two records. We refuse.
  4. If the opened occurrence had its own moved time, we clear it. Say the Oct 19 occurrence was moved to Tuesday, and you open it and push "all" an hour later. The leftover moved time would hide the time you just picked. So we clear the moved time of the opened occurrence only, and keep the exceptions on other occurrences. Google Calendar and Apple Calendar behave the same way.

An occurrence's address is its identity. Whoever changes the series moves the addresses with it, and if they can't be moved, we refuse the edit rather than guess.

"This and following" splits the series in two

Choosing "this and following" splits the series, the same way Google and Apple do it. The earlier series gets an end (UNTIL) one second before that occurrence, and a new series starts at that occurrence, pointing back at the earlier one (split_from). For a COUNT rule, the occurrences already past are subtracted.

DoneFirst occurrence of the new series
Earlier series
  1. Mon Oct 59:00Done
  2. Mon Oct 129:00Done
New series
  1. Mon Oct 1910:00Split here
  2. Mon Oct 2610:00Alert carried over
  3. Mon Nov 210:00
We changed the time from the Oct 19 occurrence with 'this and following'. Past occurrences and their records stay on the earlier series. Future occurrences and their records move to the new series under new addresses.

The hard part isn't the rule. It's everything attached to it. The new series is the same piece of work, so it inherits the same relationships: sharing and edit permissions, attendees, tags, attachments, tasks placed inside, and for future occurrences, their completions, individual edits and alerts. Past occurrences and history stay with the earlier series. All of it happens in one transaction. If any step fails, the new series and every moved record roll back.

/** Why the series can't be split (null if it can) */
export function splitBlock(f: SplitFacts, from: string, expectedRevision: string | undefined, now: number) {
  const root = f.rows.find((r) => r.id === from);
  if (!root || root.deleted) return "series_not_found";
  if (root.calendarMoved || f.rows.some((r) => !r.deleted && r.calendarMoved) || expectedRevision === undefined || root.revision !== expectedRevision) return "series_split_conflict";
  if (f.external) return "series_split_sync_unsupported";
  if (f.pendingAlarmClaims.some((at) => now - at < ALARM_CLAIM_STALE_MS)) return "series_split_conflict";
  // …
  return null;
}

Before splitting, we lock the related rows and read the facts. Whether the split may go ahead is decided by one pure function. If the series was changed elsewhere after we read it (a different revision), we don't split. Even if two devices hit "this and following" on the same series almost at once, you don't end up with two new series. If an alert for the series is being sent right now, we don't split. A send stuck for more than five minutes, though, is treated as stalled and no longer blocks.

What the tests guard

Repetition is where fixing one thing easily breaks another, so what must hold is written down as tests.

  • Expansion (no database): 9:00 stays local across DST; removed and cancelled occurrences are gone while moved ones keep their address; occurrences moved in from outside the range show up; moved records of occurrences that fell out of an ended rule stay hidden; UNTIL on timed series.
  • Pulling old series forward: identical to counting from the start, across 12 rules.
  • Moving addresses: untouched times keep the exact address string; nonexistent times or colliding addresses are refused.
  • Splitting (on PGlite with every migration applied to an empty database): colliding addresses roll back the new series and deletions alike, preserving the original; a second split from the same revision fails without a duplicate; records of alerts already sent, and other people's alerts, survive; an owner-only item stays owner-only after the split.

What we learned

Storing repetition as a rule makes storage simple. The price is keeping the idea of an "address" intact all the way through. Occurrences don't exist, yet records pointing at them are everywhere: completions, alerts, sent alerts, dependencies, checklists inside. Code that changes a series has to know about all of them and move them together.

And when we don't know, we don't guess. Snapping a nonexistent time to the nearest real one, or dropping one of two colliding records, looks smooth in the moment. Days later, the user finds a checkmark gone. Leaving the original untouched and saying "this can't be done" is the better answer for a calendar.

The ikie teamikie is a calendar for your events and to-dos in one place. Here we write about the problems we run into while building it, and how we solve them.