ikieEngineeringGet started
All posts

Data modelTime zonesCalendars

Time comes in four kinds

A birthday is a whole day, a call with a colleague in New York is one instant, and an 8 am pill is 8 am wherever you are. Here's how ikie stores time as four kinds, and where time tripped us up, from a block shifted nine hours to an event whose end landed before its start on a DST day.

한국어

"9 o'clock" means more than you'd think. A call with a New York colleague set for 9 in Seoul is the same instant no matter where you see it from. In New York it's 8 pm the evening before (during daylight saving time). But "take my pill at 8 am" should be 8 am wherever you've traveled. A birthday isn't a time but a whole day. And "write the report" may have no time at all.

Try to fit all of that into one column, and something goes wrong somewhere. So ikie splits time into four kinds and stores them separately.

Four kinds, four sets of columns

KindMeaningStored in
dateAll day. The end day is exclusiveStart date, end date
zonedAn instant, the same everywhereStart and end instants (UTC), start and end time zones (IANA)
floatingA wall-clock time, that time wherever you areStart and end local times, no zone
noneNo timeNothing

An exclusive end day (a single day on the 10th runs from the 10th to the 11th) matches iCalendar's DTEND and Google's end.date, so syncing never drifts by a day. Floating time exists in iCalendar and Apple Calendar, but not in Google Calendar. When we send one to Google, we convert it to the user's default time zone.

The database enforces which columns each kind must use.

time_kind text check (time_kind in ('date', 'zoned', 'floating')),   -- NULL = no time
constraint item_time_date check (time_kind <> 'date' or (start_date is not null and end_date is not null and end_date > start_date)),
constraint item_time_zoned check (time_kind <> 'zoned' or (start_at is not null and end_at is not null and start_tz is not null and end_tz is not null and end_at >= start_at)),
constraint item_time_floating check (time_kind <> 'floating' or (start_local is not null and end_local is not null and end_local >= start_local)),
constraint item_rrule_needs_time check (rrule is null or time_kind is not null)

The range indexes used to read a day's items are separate for each kind too: instant ranges, date ranges and zoneless time ranges. And only an item with a time can repeat.

Events and tasks end differently

Events and tasks are the same kind of item, but how they end tells them apart. An event ends when its time passes. A task ends only when you finish it. So the same time columns are a commitment on an event and a plan on a task.

  • A task with only a day keeps that day in a single "do on" column, not in the time columns. If the day passes before it's done, it rolls over to today.
  • A task with a time that passes unfinished doesn't disappear. It comes back at the top of the inbox (the list of undated tasks) as a "missed task". A task in progress isn't missed even past its time, since you're still on it.
  • A deadline is separate from the planned time. "By Friday" stores only a deadline day and means the end of that day. Say a time too, like "by 3 pm tomorrow", and that instant is stored as well.

Whose time zone?

Showing time is as hard as storing it. The "10th" of an all-day event and the "8 o'clock" of a floating time have to be read in the viewer's time zone, and that zone also decides when "today" ends.

In ikie, one function decides the viewer's time zone.

export function viewerTz(fixedTz, deviceTz, accountTz): string {
  return pickTz(fixedTz, deviceTz, accountTz); // first valid one, else UTC
}
  1. A time zone pinned in settings
  2. The device's time zone (the app sends it in a request header, the web in a cookie)
  3. The account's time zone
  4. Failing all of those, UTC

The account's time zone follows the device. When the device reports a new zone, it's written back to the account. Work that runs without a request (alerts, syncing external calendars, syncing task sources) uses the same order, with the most recently registered push device standing in for the device. A test blocks use-case code that guesses "UTC" when it doesn't know the zone.

Daylight saving time

Where daylight saving time exists, a day isn't always 24 hours. It's 23 hours in spring and 25 in fall. So adding a day doesn't add 24 hours. It counts calendar dates on the wall clock. On iOS, the timeline draws that day as 23 or 25 hours, and its hour labels follow the real wall clock (no 2:00, or 1:00 twice).

Times that don't exist, or exist twice, need a rule too. In New York, 2:30 am skipped in spring moves forward, and 1:30 am that happens twice in fall takes the first one. That's what RFC 5545, Google and Apple do.

Repeating series expand in the local time of wherever the series started. A Monday 9 am meeting stays at 9 when daylight saving time begins. Expand it in UTC and it slides to 8 or 10 across the change.

Where time tripped us up

  • A block shifted nine hours. iOS read an instant like …T05:00:00Z by dropping the trailing Z and treating it as wall-clock time. In Seoul, a block you long-pressed to drag was drawn nine hours early, off the screen. The demo data had no time zones, so the simulator never showed it.
  • A day early in the east. The inbox's "Add to an event" picker wrote all-day event dates as UTC dates, so east of UTC (Korea included) they showed a day early. On iOS, the edit sheet also opened with times clipped to the day, so editing only a title could cut short an event that ran past midnight.
  • Inputs without a zone. If an API input for moving an event or scheduling a task lacked Z or +09:00, the server read it as UTC and shifted it by the user's offset. Now an instant without a zone is refused as invalid_time. We chose a clear failure over a guess.
  • New York in 1970. The offset shown next to a time zone name in the sheet (like GMT+9) was computed for January 1, 1970, so New York showed GMT-5 during daylight saving time. It's now computed for the current date.
  • Adding 24 hours. Where an all-day end was computed by adding 24 hours, on the day daylight saving time ended the end landed before the start.
  • The sign-up time zone. The account's time zone stayed at its sign-up value, so the connected Claude (over MCP) read "today" in a stale zone. Alerts used the zone the first registered device had when it registered. Now the account's zone follows the device, and alerts look at the most recent device.
  • Slack tasks in UTC. Tasks created from Slack messages arrived in "UTC" because the zone was unknown. Work without a request now resolves the zone in the same order, and a test blocks guessing UTC in use cases.

Handle floating with care

Floating time means "8 o'clock wherever I am", which suits an event you keep to yourself but is hard to share. The same "8 o'clock" is a different instant for each viewer. So floating blocks are locked against dragging on the timeline and are edited in the sheet instead. Dragging a repeating occurrence goes to the sheet too when it would change the time kind (all-day ↔ timed) or involves floating time. When looking at someone else's free time, their floating times are read in their time zone.

What we learned

Most of our time bugs came from assuming time is one thing: putting instants, wall-clock times and whole days in the same column, treating every day as 24 hours, or guessing UTC when the zone was unknown. Storing the kinds separately, letting the database enforce each kind's columns, and having one function decide the viewer's zone made that class of bug rarer. And we chose clear failure over guessing. A time without a zone isn't accepted.

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.