Review a recurring reminder scheduler

Review exercise · TypeScript

Intermediate35 min

Review brief

A notification service is adding daily reminders for recipients around the world. The worker calculates occurrences, durably enqueues deliveries, and records the next run. Review the change for calendar-time correctness and reliable retry behavior.

Behavioral contract

Each reminder runs daily at its configured wall-clock hour and minute in the recipient's IANA timezone; the server timezone must not affect the result.
Choose the earliest occurrence strictly after the supplied instant, and derive every later occurrence by advancing one local calendar day rather than adding a fixed duration.
When clocks move backward, choose the earlier of the two matching instants. When clocks move forward over the configured time, choose the first valid instant after the gap.
A queue enqueue resolves only after the message is durable. Advance `nextRunAt` only after that resolution; an enqueue failure must leave the same occurrence due for retry.
The queue deduplicates retries by `reminderId` and `scheduledFor`, so retrying an enqueue whose later schedule update failed is safe.

Review instructions

1Review only the changed code against the stated scheduling and durability contract.
2Anchor each finding to the narrowest useful line range and explain the recipient or operational impact.
3Prioritize no more than five findings, including meaningful test gaps.

Learning objectives

• Reason about calendar time rather than elapsed duration
• Apply explicit policies to ambiguous and nonexistent local times
• Order schedule state around durable delivery

src/reminder-scheduler-types.tsTypeScript

@@ -0,0 +1,42 @@

1+export interface LocalTime {

2+ hour: number;

3+ minute: number;

4+}

5+

6+export interface Reminder {

7+ id: string;

8+ recipientId: string;

9+ recipientTimeZone: string;

10+ localTime: LocalTime;

11+ nextRunAt: Date;

12+}

13+

14+export interface ZonedCalendar {

15+ nextDateAfter(instant: Date, timeZone: string, time: LocalTime): string;

16+ resolve(

17+ date: string,

18+ time: LocalTime,

19+ timeZone: string,

20+ policy: { ambiguous: "earlier" | "later"; nonexistent: "next-valid" | "reject" },

21+ ): Date;

22+}

23+

24+export interface ReminderRepository {

25+ listDue(now: Date): Promise<Reminder[]>;

26+ updateNextRunAt(reminderId: string, nextRunAt: Date): Promise<void>;

27+}

28+

29+export interface DeliveryQueue {

30+ enqueue(message: {

31+ reminderId: string;

32+ recipientId: string;

33+ scheduledFor: Date;

34+ }): Promise<void>;

35+}

36+

37+export interface SchedulerDependencies {

38+ calendar: ZonedCalendar;

39+ queue: DeliveryQueue;

40+ reminders: ReminderRepository;

41+ serverTimeZone: string;

42+}

Reference solution

The findings below are ordered by priority.

Findings

1. The schedule advances before the delivery is durable

Location: src/reminder-scheduler.ts:39-44

updateNextRunAt runs before queue.enqueue. If the enqueue rejects, the persisted schedule already points at the following day, so the failed occurrence is no longer due and an ordinary retry loses that reminder.

Durably enqueue the current occurrence before advancing the schedule. If the later state update fails, retry the same occurrence using the queue's documented reminderId and scheduledFor deduplication key.

2. Initial occurrences use the server timezone instead of the recipient timezone

Location: src/reminder-scheduler.ts:10-22

Although firstOccurrenceAfter receives recipientTimeZone, both calendar operations use serverTimeZone. A 09:00 reminder for a recipient outside the server timezone is therefore resolved as 09:00 on the server's calendar rather than the recipient's.

Pass the recipient's IANA timezone to both the local-date selection and local-time resolution operations. The server timezone should not participate in reminder calculation.

3. A fixed 24-hour step changes wall-clock delivery time at daylight-saving transitions

Location: src/reminder-scheduler.ts:8,25-27

The following occurrence is the previous instant plus exactly 24 hours. On a 23-hour or 25-hour local day, that instant is an hour later or earlier than the recipient's chosen wall-clock time.

Advance the recipient's local calendar date by one day and resolve the configured local time in that recipient's timezone for every occurrence.

4. Transition resolution contradicts both documented policies

Location: src/reminder-scheduler.ts:19-22

The resolver chooses the later instant when a local time occurs twice and rejects a nonexistent local time. The contract instead requires the earlier instant for an overlap and the first valid instant after a gap. Recipients near either clock transition can receive the reminder at the wrong instant or have scheduling fail.

Pass the explicit ambiguous: "earlier" and nonexistent: "next-valid" policies to the calendar resolver and cover each transition with a representative timezone.

5. The tests avoid every timezone transition

Location: src/reminder-scheduler.test.ts:6-50

Both examples use UTC on ordinary February dates. They cannot detect use of the server timezone, fixed-duration drift, or either ambiguous/nonexistent-time policy. The enqueue test also checks calls without exercising a rejection, so it cannot protect retry ordering.

Add cases with different server and recipient timezones, a spring gap, a fall overlap, and an enqueue rejection that verifies the occurrence remains due.

Reasonable non-findings

Processing due reminders sequentially is acceptable; the contract sets no throughput or parallelism target.
Sending the current nextRunAt value as scheduledFor is correct. That stable occurrence identity is what allows an idempotent enqueue retry.
Keeping calendar conversion behind ZonedCalendar is a reasonable way to avoid coupling the scheduler to a particular date library.