Multi-Timezone Job Scheduler

Build a job scheduler that can execute tasks at specific times across different timezones. The scheduler should handle timezone-aware scheduling and support UTC offset configuration for regions without named timezone identifiers.

Requirements

Create a module that provides the following functionality:

1. Schedule Jobs with Named Timezones: Create scheduled jobs that execute at specific times in named timezones (e.g., 'America/New_York', 'Europe/London', 'Asia/Tokyo'). The jobs should respect Daylight Saving Time transitions automatically.

2. Schedule Jobs with UTC Offsets: Support scheduling jobs using UTC offset values in minutes for regions that don't have standard timezone names.

3. Query Next Execution Time: Provide functionality to query when a scheduled job will execute next, with the result reflecting the configured timezone.

4. Timezone Validation: Handle invalid timezone names gracefully by throwing appropriate errors when an invalid timezone is provided.

Implementation Notes

• Each scheduled job should log the current time when it executes
• The scheduler should support standard cron expression syntax
• Jobs should be configurable to start automatically or require manual start
• All timezone handling should respect DST transitions where applicable

API

/**
 * Creates a job that executes at a specific time in a named timezone
 * @param cronExpression - Cron expression for scheduling
 * @param timezone - IANA timezone name (e.g., 'America/Los_Angeles')
 * @param callback - Function to execute on schedule
 * @param autoStart - Whether to start the job immediately
 * @returns Job object with control methods
 */
export function createTimezoneJob(
  cronExpression: string,
  timezone: string,
  callback: () => void,
  autoStart: boolean
): any;

/**
 * Creates a job that executes at a specific time using a UTC offset
 * @param cronExpression - Cron expression for scheduling
 * @param utcOffsetMinutes - UTC offset in minutes
 * @param callback - Function to execute on schedule
 * @param autoStart - Whether to start the job immediately
 * @returns Job object with control methods
 */
export function createUtcOffsetJob(
  cronExpression: string,
  utcOffsetMinutes: number,
  callback: () => void,
  autoStart: boolean
): any;

/**
 * Gets the next execution time for a scheduled job in the job's configured timezone
 * @param job - The job to query
 * @returns The next scheduled execution time
 */
export function getNextExecutionTime(job: any): Date;

Test Cases

• Creating a job with timezone 'America/New_York' and expression '0 9 * * *' schedules for 9 AM Eastern Time @test
• Creating a job with timezone 'Europe/Paris' and expression '0 14 * * 1-5' schedules for 2 PM Paris time on weekdays @test
• Creating a job with UTC offset -300 (EST) executes at the correct time relative to UTC @test
• Calling getNextExecutionTime on a timezone-configured job returns the next scheduled time @test
• Creating a job with an invalid timezone name like 'Invalid/Timezone' throws an error @test

Dependencies { .dependencies }

cron { .dependency }

Provides timezone-aware job scheduling with support for named timezones and UTC offsets, including automatic DST handling.

@satisfied-by