simplify timezone handling

Author: noxify

README.md

@@ -108,26 +108,35 @@ await queue.add("health-check", payload, {
 
 ## Timezone Support
 
+Vorsteh Queue uses a **UTC-first approach** for reliable timezone handling:
+
 ```typescript
-// Schedule job for 9 AM New York time
+// Schedule job for 9 AM New York time - converted to UTC immediately
 await queue.add("daily-report", payload, {
   cron: "0 9 * * *",
-  timezone: "America/New_York"
+  timezone: "America/New_York"  // Timezone used for conversion only
 })
 
-// Schedule job for specific time in Tokyo
+// Schedule job for specific time in Tokyo - stored as UTC
 await queue.add("notification", payload, {
   runAt: new Date("2024-01-15T10:00:00"),
-  timezone: "Asia/Tokyo"
+  timezone: "Asia/Tokyo"  // Interprets runAt in Tokyo time
 })
 
-// Complex cron with timezone (every 15 min during business hours)
+// Complex cron with timezone - result always UTC
 await queue.add("business-task", payload, {
   cron: "*/15 9-17 * * 1-5",
-  timezone: "Europe/London"
+  timezone: "Europe/London"  // Business hours in London time
 })
 ```
 
+### How It Works
+
+1. **Timezone conversion happens at job creation** - not at execution
+2. **All timestamps stored in database are UTC** - no timezone ambiguity
+3. **Recurring jobs recalculate using original timezone** - maintains accuracy
+4. **Simple and predictable** - no runtime timezone complexity
+
 ## Progress Tracking
 
 ```typescript

packages/adapter-drizzle/src/drizzle-adapter.ts

@@ -67,7 +67,6 @@ export class DrizzleQueueAdapter extends BaseQueueAdapter {
         repeatEvery: job.repeatEvery,
         repeatLimit: job.repeatLimit,
         repeatCount: job.repeatCount,
-        timezone: job.timezone ?? "UTC",
       })
       .returning()
 
@@ -250,7 +249,6 @@ export class DrizzleQueueAdapter extends BaseQueueAdapter {
       repeatEvery: job.repeatEvery ?? undefined,
       repeatLimit: job.repeatLimit ?? undefined,
       repeatCount: job.repeatCount ?? 0,
-      timezone: job.timezone,
     }
   }
 }

packages/adapter-drizzle/src/schema.ts

@@ -19,7 +19,6 @@ export const queueJobs = pgTable(
     processedAt: timestamp("processed_at", { withTimezone: true }),
     completedAt: timestamp("completed_at", { withTimezone: true }),
     failedAt: timestamp("failed_at", { withTimezone: true }),
-    timezone: varchar("timezone", { length: 50 }).default("UTC").notNull(),
     error: jsonb("error"),
     progress: integer("progress").default(0),
     cron: varchar("cron", { length: 255 }),

packages/adapter-drizzle/tests/timezone.test.ts

@@ -11,7 +11,7 @@ import type {
   QueueStats,
 } from "../types"
 import { calculateDelay, waitFor } from "../utils/helpers"
-import { calculateNextRun, nowUtc, toUtcDate } from "../utils/scheduler"
+import { calculateNextRun, nowUtc, parseCron, toUtcDate } from "../utils/scheduler"
 import { createJobWrapper } from "./job-wrapper"
 
 type EventListener<TEventData> = (data: TEventData) => void | Promise<void>
@@ -126,11 +126,16 @@ export class Queue {
     let status: JobStatus = "pending"
 
     if (jobOptions.runAt) {
+      // Convert user-provided time to UTC using timezone context
       processAt = toUtcDate(jobOptions.runAt, timezone)
       status = processAt > now ? "delayed" : "pending"
     } else if (jobOptions.delay) {
       processAt = new Date(now.getTime() + jobOptions.delay)
       status = "delayed"
+    } else if (jobOptions.cron) {
+      // Parse cron in timezone, get UTC result
+      processAt = parseCron(jobOptions.cron, timezone, now)
+      status = "delayed"
     } else {
       processAt = now
     }
@@ -147,7 +152,6 @@ export class Queue {
       repeatEvery: jobOptions.repeat?.every,
       repeatLimit: jobOptions.repeat?.limit,
       repeatCount: 0,
-      timezone,
     })
 
     this.emit("job:added", job)
@@ -431,7 +435,7 @@ export class Queue {
     }
   }
 
-  private async handleRecurringJob(job: BaseJob): Promise<void> {
+  private async handleRecurringJob(job: BaseJob, originalTimezone?: string): Promise<void> {
     if (!job.cron && !job.repeatEvery) return
 
     const nextCount = (job.repeatCount ?? 0) + 1
@@ -443,7 +447,7 @@ export class Queue {
       const nextRun = calculateNextRun({
         cron: job.cron,
         repeatEvery: job.repeatEvery,
-        timezone: job.timezone,
+        timezone: originalTimezone ?? "UTC",
         lastRun: new Date(),
       })
 

packages/core/src/core/queue.ts

@@ -48,8 +48,6 @@ export interface BaseJob<TJobPayload = unknown> {
   readonly repeatLimit?: number
   /** Current repetition count for recurring jobs */
   readonly repeatCount?: number
-  /** Timezone for job scheduling (default: UTC) */
-  readonly timezone?: string
 }
 
 /**