Calendar and Time Zones on macOS: Civil Time, Recurrence, and DST

Foundation’s Date represents an absolute instant. It does not retain the user’s calendar, time zone, locale, or the intent “every day at 9:00 local time.” Those rules belong in Calendar, TimeZone, Locale, and DateComponents. Bugs appear when an app stores only an instant for a future civil event or adds a fixed number of seconds to represent a calendar day.

First decide what the product means. “Run again in 24 hours” is an elapsed duration. “Run tomorrow at 9:00 in the user’s current time zone” is a wall-clock recurrence. “The appointment remains at 9:00 New York time while the user travels” is a recurrence pinned to a named time zone. These are different policies and should be represented as different data.

Model an instant and a civil schedule separately

Persist actual event timestamps as Date when the event has occurred or is committed to a specific instant. For a future rule, persist the components that express user intent, the calendar identifier when relevant, and a time-zone identifier or explicit “follow current zone” policy. Recompute the next occurrence when the time-zone database or user’s settings change.

import Foundation

func nextLocalOccurrence(after now: Date, timeZoneID: String) -> Date? {
    guard let zone = TimeZone(identifier: timeZoneID) else { return nil }
    var calendar = Calendar(identifier: .gregorian)
    calendar.timeZone = zone

    let target = DateComponents(hour: 2, minute: 30)
    return calendar.nextDate(
        after: now,
        matching: target,
        matchingPolicy: .nextTime,
        repeatedTimePolicy: .first,
        direction: .forward
    )
}

This example defines a daily wall-clock time in an explicit named zone. The .nextTime matching policy asks Calendar to find the next time matching the components when an exact wall time does not exist; .first chooses the first occurrence when a wall time repeats. Those are product decisions, not universally correct defaults. A different application may need the last repeated time, a strict failure for a missing time, or a policy that skips a date.

Do not put the Date returned by this helper into a database as the only durable representation of a repeating schedule. It is the next computed instant under the current calendar rules. Preserve the civil components and time-zone policy so later occurrences can be recalculated correctly.

Daylight-saving gaps and repeated times

When clocks move forward, a local time can be skipped. When clocks move backward, one local time can occur twice. Calendar.nextDate exposes a matching policy and a repeated-time policy so callers can make the behavior explicit. A schedule for a missing local time must choose whether to advance to a nearby time, skip the occurrence, or surface a conflict.

Avoid assuming that daylight-saving transitions always happen on the same dates or shift by one hour. Time-zone rules are political and can change. Use an IANA time-zone identifier such as America/Argentina/Cordoba or America/New_York for regional civil behavior, not a fixed seconds-from-GMT offset. A fixed offset represents an offset; it does not encode the future rules of a region.

Test both gap and repeated-time transitions for zones your app supports. Do not hard-code a current transition date as a permanent rule. Calendar and time-zone data can be updated by the operating system, so a future schedule may need to be recalculated after an OS update or a user changes their zone.

Calendar arithmetic is not duration arithmetic

Adding 86,400 seconds always adds that duration. It does not always land on the same local time on the next calendar day. Adding one calendar day asks the calendar system to advance the day component under the configured calendar and time zone. Use DateComponents arithmetic for civil recurrences and TimeInterval arithmetic for elapsed durations such as a timeout or a five-minute cache lease.

Calendar.current captures the user’s current calendar settings at the time you access it. Calendar.autoupdatingCurrent tracks changes to the user’s preferred calendar. Choose intentionally: a historical document may need the calendar and time zone under which it was created, while a “show me today’s schedule” view should usually adapt to current preferences.

Locale controls presentation such as date order and localized names; it is not a replacement for a time zone. Format a Date for display with a locale-aware formatter, and do not use a localized date string as a machine-readable database key. Preserve stable identifiers and numeric components internally, then format at the UI boundary.

Recurring rules and missed occurrences

For recurring reminders, store the recurrence rule and its intended zone rather than a fixed list of future timestamps extending indefinitely. A daily rule at 9:00 local time should be recalculated using Calendar. A job that must run exactly once at a fixed instant should store that instant and not reinterpret it as local civil time later.

If an app was closed or offline, decide how missed occurrences are handled. Catching up every missed event can produce a burst of notifications or duplicate work. Skipping old reminders may be appropriate for ephemeral items but wrong for billing or audit records. Calendar computes dates; it does not choose the product’s missed-event policy or make a background app run on time.

Use system scheduling APIs for user-facing reminders when they fit the workflow, and a durable backend scheduler for work that must run independently of the app process. An in-process timer is only a wakeup while the process can execute. Persist the schedule and reconciliation state so relaunching the app can decide whether an occurrence is pending, missed, or already completed.

Parsing and user input

Parse user-entered dates with an explicit locale and calendar policy. Ambiguous inputs such as 03/04/2027 depend on locale, and a bare hour has no zone or date. If the user enters a local date and time, retain those components until the app has enough information to resolve them according to the selected zone and repeated-time policy.

For server protocols, use a specified wire representation such as an ISO 8601 instant when the value truly denotes an instant. Do not serialize a regional recurring time as a UTC timestamp and expect to reconstruct its original local intent. If the server owns recurrence, send the rule’s canonical zone identifier and the rule’s semantics.

Business hours and calendar boundaries

Business-day calculations need a calendar, locale, and holiday policy in addition to arithmetic. “Next weekday” is not “next business day” when regional holidays, company closure dates, or custom weekends matter. Keep the holiday calendar as explicit product data and apply it after Foundation computes a candidate date. Do not encode a country’s holiday rule as a fixed list of seconds or infer holidays from the user’s display locale.

The first moment of a calendar day is not always a fixed clock time. Use Calendar.startOfDay(for:) when the requirement is the beginning of a local day, and avoid constructing midnight by adding components that may not exist under a zone transition. For date intervals, use calendar APIs to compute the interval that contains an instant rather than assuming every day has the same duration.

When a user changes the calendar system, clarify which records are absolute instants and which are civil dates. A birthday or all-day holiday is usually a date without a time-of-day, whereas a meeting invitation identifies an instant plus a display zone. Converting both into one UTC timestamp can shift an all-day event onto the previous or next visible date for users in another zone.

Keep recurrence policy testable

Represent a recurrence rule in a small domain type with named fields for zone policy, calendar, local components, gap handling, repeat handling, and end condition. Make the rule serializable and versioned so a future app release can migrate it. Avoid storing only an opaque formatted string or the output of one call to nextDate; the system cannot reconstruct the original choices from a computed instant.

Use deterministic tests with fixed time zones and reference dates, then add integration tests on systems whose time-zone database can update. Assertions should focus on both semantic intent and resulting instant. For example, a “09:00 local” recurrence should still format as 09:00 in its chosen region on dates when the offset changes, even though the UTC time differs.

Validation and diagnostics

Test a normal date, leap day, month-end addition, spring-forward gap, fall-back repeated hour, a region that changes its time-zone policy, travel to another zone, a changed system calendar, and app relaunch after the next occurrence. Assert both the computed absolute instant and the formatted civil time. A test that checks only a UTC timestamp can miss a user-visible local-time error.

Record the calendar identifier, time-zone identifier, rule components, matching policy, and computed occurrence when diagnosing a schedule. Avoid logging precise personal appointment data unless the diagnostic is explicitly user-controlled. When a schedule changes because a time-zone database update changes the computed date, explain the policy and preserve the user’s intended civil components.

The Foundation date model is reliable when the application keeps instants, durations, and civil schedules distinct. Store the intent, select calendar and zone policies explicitly, and test gaps and repeated times. This prevents a successful date calculation from silently encoding the wrong human meaning.

Related:

Sources: