IANA timezones, DST, misfires, and overlap policies for SaaS schedules

“Run every 24 hours” and “run every day at 9am” only sound equivalent on quiet weeks in UTC. The first is elapsed time. The second is a wall-clock promise made to a person in a place.

Model that promise directly: frequency, interval, local time, timezone, start, and end condition. Store the next UTC instant as derived execution state, not as the source of truth for the recurrence.

This representation also gives you something intelligible to render back to the customer: “Every Monday and Friday at 9:00 AM Australia/Melbourne,” followed by the next few dates.

AEST is ambiguous and UTC+10 cannot tell you when an offset changes. An IANA identifier such as Australia/Melbourne names a ruleset with historical and future offset transitions.

Prefer the customer workspace’s timezone as a default, then let the creator confirm or change it. Do not silently substitute the browser timezone for an organization-wide report: the person configuring it may be travelling.

Daylight-saving transitions create two edge cases. In spring, some local times do not exist. In autumn, some occur twice. There is no universally correct answer, so a scheduler needs a deterministic one and its preview should make that answer visible.

For money movement or compliance cutoffs, a generic default may be inappropriate. Restrict problematic times, require an explicit policy, or use a business calendar owned by the application. “Run twice because the clock did” is rarely a safe surprise.

A misfire happens when the scheduler notices an occurrence after its intended time—perhaps because the service was unavailable or the schedule was paused. A delivery retry is different: the occurrence exists, but the receiver did not accept it.

Catch-up needs a bound. If a daily schedule wakes after a year, 365 simultaneous jobs are not a recovery plan. Set a maximum look-back window or batch the backlog, and show the operator what was condensed or skipped.

Suppose a sync runs every five minutes but sometimes takes eight. The next occurrence is on time; it simply collides with work already in progress. Your choices are to allow concurrency, skip the new occurrence, or queue it behind the active run.

The scheduler cannot infer whether two executions conflict inside your domain. If you allow overlap, the action still needs idempotency and whatever locking protects shared records. If you skip, record a skipped run rather than pretending the occurrence never existed.

Human-readable summaries are helpful, but examples are harder to misread. Show at least the next five local dates when a schedule is created or edited. In tests, choose a start date that crosses a real offset transition.

const preview = await tenantIncld.schedules.preview({
  recurrence: {
    frequency: "weekly",
    interval: 1,
    weekdays: ["sunday"],
    localTime: "02:30",
    timezone: "Australia/Melbourne",
  },
  count: 8,
  from: "2026-09-01T00:00:00Z",
})

for (const occurrence of preview.occurrences) {
  console.log(occurrence.local, occurrence.utc)
}

Cover these cases in fixtures rather than relying on the machine’s current timezone:

1. 1 A weekly local time stays constant while its UTC offset changes.
2. 2 A nonexistent local time resolves according to the documented rule.
3. 3 A repeated local time produces one deterministic occurrence.
4. 4 Day 31 behaves predictably in a shorter month.
5. 5 Pausing across several occurrences follows the chosen misfire policy.
6. 6 A slow active run follows the chosen overlap policy.

incld stores daily, weekly, monthly, and one-time recurrence rules with an IANA timezone and returns local and UTC values from the preview API. Its recurrence engine moves a nonexistent local time to the next valid instant and chooses the first instant when a local time repeats. Monthly day-of-month schedules clamp to the last valid day.

Show that preview beside the human-readable summary when customers create or edit a schedule. Concrete dates make the timezone and recurrence easy to verify before saving.