Review calendar recurrence exceptions

Review exercise · TypeScript

Review brief

Advanced45 min

A calendar service expands a finite weekly series into an instant range. Events are defined in an IANA timezone, may cross daylight-saving transitions, and exceptions refer to the original local occurrence even when moving it elsewhere.

Behavioral contract

Generate exactly count weekly base occurrences from startLocal in timeZone by adding seven local calendar days, then converting each local date-time with the injected zone rules.
Exception keys are original local dates. A cancellation still consumes one base occurrence; a move replaces that occurrence with moveToLocal but retains the original date as identity.
Return occurrences whose final instant is at or after rangeStart and strictly before rangeEnd.
Return results in ascending final-instant order. If a move collides with another occurrence, preserve both entries.

Review instructions

1Trace a DST boundary, a cancelled occurrence, and a move that changes chronological order.
2Anchor each finding to the narrowest useful changed line and explain the calendar impact.
3Recommend a direction rather than writing replacement code.
4Prioritize no more than five findings.

Learning objectives

• Preserve wall-clock recurrence across offset changes
• Apply exceptions to original occurrence identity
• Separate series count from range filtering and output order

src/recurrence-types.tsTypeScript

@@ -0,0 +1,26 @@

1+export interface LocalDateTime {

2+ date: string;

3+ time: string;

4+}

6+export type RecurrenceException =

7+ | { type: "cancelled" }

8+ | { type: "moved"; moveToLocal: LocalDateTime };

10+export interface WeeklyRecurrence {

11+ startLocal: LocalDateTime;

12+ startInstant: Date;

13+ timeZone: string;

14+ count: number;

15+ exceptions: Readonly<Record<string, RecurrenceException>>;

16+}

17+

18+export interface ZoneRules {

19+ addLocalDays(value: LocalDateTime, days: number): LocalDateTime;

20+ toInstant(value: LocalDateTime, timeZone: string): Date;

21+}

22+

23+export interface Occurrence {

24+ originalLocalDate: string;

25+ instant: Date;

26+}

Reference solution

The findings below are ordered by priority.

Findings

1. Weekly instants drift from the event's local wall time across DST

Location: src/expand-weekly-recurrence.ts:6 and src/expand-weekly-recurrence.ts:18-21

The generator adds a fixed 168 hours to startInstant. When the timezone offset changes, a meeting defined at 09:00 local appears at 08:00 or 10:00 instead of staying at its wall-clock time.

Add seven calendar days to startLocal with the injected zone rules for each base occurrence, then convert that local value to an instant.

2. Exceptions are looked up by UTC date instead of original local date

Location: src/expand-weekly-recurrence.ts:21-23

toISOString().slice(0, 10) derives a UTC date. An evening occurrence west of UTC or early occurrence east of UTC may have a different UTC date, so its cancellation or move is not found.

Use the generated base occurrence's local calendar date as its stable exception key.

3. Cancelled occurrences do not consume the finite series count

Location: src/expand-weekly-recurrence.ts:17-28 and src/expand-weekly-recurrence.ts:35

The loop stops after count non-cancelled emissions because emitted increments only after the cancellation branch. A ten-occurrence series with one cancellation generates an unintended eleventh base occurrence.

Iterate exactly count base occurrences and apply cancellation or movement afterward.

4. The range end is incorrectly inclusive

Location: src/expand-weekly-recurrence.ts:37-39

An occurrence exactly equal to rangeEnd is included even though the query interval is half-open. Adjacent range queries can therefore return the same occurrence twice.

Use a strict less-than comparison for the end boundary.

5. Moved occurrences can be returned out of chronological order

Location: src/expand-weekly-recurrence.ts:37-42

Results retain base-series iteration order. Moving one occurrence after a later week, or moving it before an earlier one, produces an array that is not sorted by final instant and can break calendar pagination.

Collect every included replacement and sort by final instant without deduplicating collisions.

Reasonable non-findings

Looking up an exception before deciding whether to emit is appropriate once the original local key is correct.
A moved occurrence should use the supplied target local date-time and the series timezone.
Preserving both colliding occurrences is required; a sort must not collapse them.