@zudojs/scheduler 1.2.2 → 1.3.0

package/README.md

@@ -82,9 +82,12 @@ day-of-week`) with ranges, lists, steps and three-letter names, plus the
 `@daily`/`@hourly`/`@weekly`/`@monthly`/`@yearly` macros. An invalid expression
 throws where the schedule is declared, not at fire time.
 
-Only `timezone: "UTC"` and the system local zone are supported. Any other zone
-is rejected rather than silently ignored — honouring an arbitrary IANA zone
-needs real zone data this package does not carry.
+`timezone` accepts any IANA zone name (`"Africa/Lagos"`, `"America/New_York"`,
+`"Asia/Kolkata"`), `"UTC"`, or nothing for the host's local zone. Zones are
+resolved through Node's `Intl` data, so daylight-saving transitions are
+honoured: `0 9 * * *` in `America/New_York` fires at 09:00 wall-clock on both
+sides of a DST change. An unknown zone name throws `InvalidScheduleError` where
+the schedule is declared rather than being silently ignored.
 
 ## Controlling a schedule
 

package/dist/index.d.ts

@@ -34,6 +34,8 @@ export type { ScheduleHandleBinding } from "./scheduler/scheduleHandle/index.js"
 export { DateTrigger, DelayTrigger, IntervalTrigger, CronTrigger, } from "./scheduler/trigger/index.js";
 export { parseCron, nextCronDate } from "./scheduler/trigger/index.js";
 export type { ParsedCron } from "./scheduler/trigger/index.js";
+export { LOCAL_ZONE, UTC_ZONE, createIntlZone, resolveCronZone, } from "./scheduler/trigger/index.js";
+export type { CronWallClock, CronZone } from "./scheduler/trigger/index.js";
 export { SystemClock, createSystemClock } from "./scheduler/clock/index.js";
 export type { Clock } from "./scheduler/clock/index.js";
 export { JobRegistry } from "./scheduler/registry/index.js";
@@ -42,4 +44,3 @@ export { PriorityQueue } from "./scheduler/priorityQueue/index.js";
 export { parseDuration } from "./scheduler/duration/index.js";
 export { Scheduler } from "./scheduler/scheduler.core.js";
 export type { SchedulerOptions, SchedulerErrorEvent, } from "./scheduler/scheduler.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -35,6 +35,7 @@ export { ScheduleHandleImpl } from "./scheduler/scheduleHandle/index.js";
 // Trigger
 export { DateTrigger, DelayTrigger, IntervalTrigger, CronTrigger, } from "./scheduler/trigger/index.js";
 export { parseCron, nextCronDate } from "./scheduler/trigger/index.js";
+export { LOCAL_ZONE, UTC_ZONE, createIntlZone, resolveCronZone, } from "./scheduler/trigger/index.js";
 // Clock
 export { SystemClock, createSystemClock } from "./scheduler/clock/index.js";
 // Registry
@@ -47,4 +48,3 @@ export { PriorityQueue } from "./scheduler/priorityQueue/index.js";
 export { parseDuration } from "./scheduler/duration/index.js";
 // Scheduler
 export { Scheduler } from "./scheduler/scheduler.core.js";
-//# sourceMappingURL=index.js.map

package/dist/scheduler/clock/index.d.ts

@@ -1,3 +1,2 @@
 export type { Clock } from "./schedulerClock.type.js";
 export { SystemClock, createSystemClock } from "./schedulerClock.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/scheduler/clock/index.js

@@ -1,2 +1 @@
 export { SystemClock, createSystemClock } from "./schedulerClock.type.js";
-//# sourceMappingURL=index.js.map

package/dist/scheduler/clock/schedulerClock.type.d.ts

@@ -18,4 +18,3 @@ export declare class SystemClock implements Clock {
  * Creates a new system clock.
  */
 export declare function createSystemClock(): SystemClock;
-//# sourceMappingURL=schedulerClock.type.d.ts.map

package/dist/scheduler/clock/schedulerClock.type.js

@@ -15,4 +15,3 @@ export class SystemClock {
 export function createSystemClock() {
     return new SystemClock();
 }
-//# sourceMappingURL=schedulerClock.type.js.map

package/dist/scheduler/constants/index.d.ts

@@ -1,2 +1 @@
 export { DEFAULT_JOB_TIMEOUT, DEFAULT_MAX_CONCURRENCY, DEFAULT_MAX_RETRIES, DEFAULT_RETRY_DELAY, MAX_TIMER_DELAY, MAX_JOBS, MAX_SCHEDULES, MAX_EXECUTION_HISTORY, DEFAULT_MISFIRE_POLICY, DEFAULT_OVERLAP_POLICY, } from "./schedulerConstants.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/scheduler/constants/index.js

@@ -1,2 +1 @@
 export { DEFAULT_JOB_TIMEOUT, DEFAULT_MAX_CONCURRENCY, DEFAULT_MAX_RETRIES, DEFAULT_RETRY_DELAY, MAX_TIMER_DELAY, MAX_JOBS, MAX_SCHEDULES, MAX_EXECUTION_HISTORY, DEFAULT_MISFIRE_POLICY, DEFAULT_OVERLAP_POLICY, } from "./schedulerConstants.core.js";
-//# sourceMappingURL=index.js.map

package/dist/scheduler/constants/schedulerConstants.core.d.ts

@@ -45,4 +45,3 @@ export declare const DEFAULT_MISFIRE_POLICY: MisfirePolicy;
  * Default overlap policy.
  */
 export declare const DEFAULT_OVERLAP_POLICY: OverlapPolicy;
-//# sourceMappingURL=schedulerConstants.core.d.ts.map

package/dist/scheduler/constants/schedulerConstants.core.js

@@ -43,4 +43,3 @@ export const DEFAULT_MISFIRE_POLICY = "run-once";
  * Default overlap policy.
  */
 export const DEFAULT_OVERLAP_POLICY = "allow";
-//# sourceMappingURL=schedulerConstants.core.js.map

package/dist/scheduler/duration/duration.parser.d.ts

@@ -16,4 +16,3 @@
  * @throws {InvalidDurationError} when the string is malformed or out of range.
  */
 export declare function parseDuration(duration: string): number;
-//# sourceMappingURL=duration.parser.d.ts.map

package/dist/scheduler/duration/duration.parser.js

@@ -66,4 +66,3 @@ export function parseDuration(duration) {
     }
     return total;
 }
-//# sourceMappingURL=duration.parser.js.map

package/dist/scheduler/duration/index.d.ts

@@ -1,2 +1 @@
 export { parseDuration } from "./duration.parser.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/scheduler/duration/index.js

@@ -1,2 +1 @@
 export { parseDuration } from "./duration.parser.js";
-//# sourceMappingURL=index.js.map

package/dist/scheduler/errors/index.d.ts

@@ -1,3 +1,2 @@
 export { SchedulerError, SchedulerAlreadyStartedError, SchedulerStoppedError, SchedulerJobNotFoundError, SchedulerJobAlreadyExistsError, InvalidJobError, InvalidScheduleError, CronParseError, InvalidDurationError, SchedulerJobExecutionError, SchedulerJobTimeoutError, SchedulerJobCancelledError, createSchedulerError, isSchedulerError, } from "./scheduler.errors.js";
 export type { SchedulerErrorOptions } from "./scheduler.errors.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/scheduler/errors/index.js

@@ -1,2 +1 @@
 export { SchedulerError, SchedulerAlreadyStartedError, SchedulerStoppedError, SchedulerJobNotFoundError, SchedulerJobAlreadyExistsError, InvalidJobError, InvalidScheduleError, CronParseError, InvalidDurationError, SchedulerJobExecutionError, SchedulerJobTimeoutError, SchedulerJobCancelledError, createSchedulerError, isSchedulerError, } from "./scheduler.errors.js";
-//# sourceMappingURL=index.js.map

package/dist/scheduler/errors/scheduler.errors.d.ts

@@ -13,4 +13,3 @@
  */
 export { SchedulerError, SchedulerAlreadyStartedError, SchedulerStoppedError, SchedulerJobNotFoundError, SchedulerJobAlreadyExistsError, InvalidJobError, InvalidScheduleError, CronParseError, InvalidDurationError, SchedulerJobExecutionError, SchedulerJobTimeoutError, SchedulerJobCancelledError, createSchedulerError, isSchedulerError, } from "@zudojs/errors";
 export type { SchedulerErrorOptions } from "@zudojs/errors";
-//# sourceMappingURL=scheduler.errors.d.ts.map

package/dist/scheduler/errors/scheduler.errors.js

@@ -12,4 +12,3 @@
  * @zudojs/errors for a durable scheduler built on top.
  */
 export { SchedulerError, SchedulerAlreadyStartedError, SchedulerStoppedError, SchedulerJobNotFoundError, SchedulerJobAlreadyExistsError, InvalidJobError, InvalidScheduleError, CronParseError, InvalidDurationError, SchedulerJobExecutionError, SchedulerJobTimeoutError, SchedulerJobCancelledError, createSchedulerError, isSchedulerError, } from "@zudojs/errors";
-//# sourceMappingURL=scheduler.errors.js.map

package/dist/scheduler/executor/index.d.ts

@@ -1,2 +1 @@
 export { JobExecutor, retryDelay } from "./jobExecutor.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/scheduler/executor/index.js

@@ -1,2 +1 @@
 export { JobExecutor, retryDelay } from "./jobExecutor.core.js";
-//# sourceMappingURL=index.js.map

package/dist/scheduler/executor/jobExecutor.core.d.ts

@@ -40,4 +40,3 @@ export declare class JobExecutor {
  * package was written; none of it was ever applied.
  */
 export declare function retryDelay(policy: RetryPolicy | undefined, attempt: number): number;
-//# sourceMappingURL=jobExecutor.core.d.ts.map

package/dist/scheduler/executor/jobExecutor.core.js

@@ -176,4 +176,3 @@ function sleep(ms, signal) {
         signal.addEventListener("abort", finish, { once: true });
     });
 }
-//# sourceMappingURL=jobExecutor.core.js.map

package/dist/scheduler/job/index.d.ts

@@ -4,4 +4,3 @@ export { createJobContext } from "./jobContext.type.js";
 export type { JobDefinition } from "./jobDefinition.type.js";
 export { createJobDefinition } from "./jobDefinition.type.js";
 export type { JobOptions, RetryPolicy, RetryStrategy, } from "./jobOptions.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/scheduler/job/index.js

@@ -1,3 +1,2 @@
 export { createJobContext } from "./jobContext.type.js";
 export { createJobDefinition } from "./jobDefinition.type.js";
-//# sourceMappingURL=index.js.map

package/dist/scheduler/job/jobContext.type.d.ts

@@ -23,4 +23,3 @@ export interface JobContext<T = unknown> {
  * Creates a job context.
  */
 export declare function createJobContext<T = unknown>(jobId: string, executionId: string, scheduledAt: Date, startedAt: Date, attempt: number, data: T, signal: AbortSignal): JobContext<T>;
-//# sourceMappingURL=jobContext.type.d.ts.map

package/dist/scheduler/job/jobContext.type.js

@@ -13,4 +13,3 @@ export function createJobContext(jobId, executionId, scheduledAt, startedAt, att
         signal,
     });
 }
-//# sourceMappingURL=jobContext.type.js.map

package/dist/scheduler/job/jobDefinition.type.d.ts

@@ -13,4 +13,3 @@ export interface JobDefinition {
  * Creates a job definition.
  */
 export declare function createJobDefinition(id: string, name: string, handler: JobHandler, options?: JobOptions): JobDefinition;
-//# sourceMappingURL=jobDefinition.type.d.ts.map

package/dist/scheduler/job/jobDefinition.type.js

@@ -9,4 +9,3 @@ export function createJobDefinition(id, name, handler, options = {}) {
         options: Object.freeze(options),
     });
 }
-//# sourceMappingURL=jobDefinition.type.js.map

package/dist/scheduler/job/jobHandler.type.d.ts

@@ -3,4 +3,3 @@ import type { JobContext } from "./jobContext.type.js";
  * Handler for a scheduled job.
  */
 export type JobHandler<T = unknown> = (context: JobContext<T>) => Promise<void> | void;
-//# sourceMappingURL=jobHandler.type.d.ts.map

package/dist/scheduler/job/jobHandler.type.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=jobHandler.type.js.map

package/dist/scheduler/job/jobOptions.type.d.ts

@@ -33,4 +33,3 @@ export interface RetryPolicy {
  * Retry strategy.
  */
 export type RetryStrategy = "fixed" | "linear" | "exponential";
-//# sourceMappingURL=jobOptions.type.d.ts.map

package/dist/scheduler/job/jobOptions.type.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=jobOptions.type.js.map

package/dist/scheduler/priorityQueue/index.d.ts

@@ -1,2 +1 @@
 export { PriorityQueue } from "./schedulerPriorityQueue.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/scheduler/priorityQueue/index.js

@@ -1,2 +1 @@
 export { PriorityQueue } from "./schedulerPriorityQueue.core.js";
-//# sourceMappingURL=index.js.map

package/dist/scheduler/priorityQueue/schedulerPriorityQueue.core.d.ts

@@ -55,4 +55,3 @@ export declare class PriorityQueue {
      */
     private sinkDown;
 }
-//# sourceMappingURL=schedulerPriorityQueue.core.d.ts.map

package/dist/scheduler/priorityQueue/schedulerPriorityQueue.core.js

@@ -145,4 +145,3 @@ export class PriorityQueue {
         }
     }
 }
-//# sourceMappingURL=schedulerPriorityQueue.core.js.map

package/dist/scheduler/registry/index.d.ts

@@ -1,2 +1 @@
 export { JobRegistry } from "./jobRegistry.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/scheduler/registry/index.js

@@ -1,2 +1 @@
 export { JobRegistry } from "./jobRegistry.core.js";
-//# sourceMappingURL=index.js.map

package/dist/scheduler/registry/jobRegistry.core.d.ts

@@ -37,4 +37,3 @@ export declare class JobRegistry {
      */
     clear(): void;
 }
-//# sourceMappingURL=jobRegistry.core.d.ts.map

package/dist/scheduler/registry/jobRegistry.core.js

@@ -63,4 +63,3 @@ export class JobRegistry {
         this.jobs.clear();
     }
 }
-//# sourceMappingURL=jobRegistry.core.js.map

package/dist/scheduler/schedule/index.d.ts

@@ -1,4 +1,3 @@
 export type { Schedule, ScheduleType } from "./schedule.type.js";
 export { createSchedule } from "./schedule.type.js";
 export type { ScheduleOptions } from "./scheduleOptions.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/scheduler/schedule/index.js

@@ -1,2 +1 @@
 export { createSchedule } from "./schedule.type.js";
-//# sourceMappingURL=index.js.map

package/dist/scheduler/schedule/schedule.type.d.ts

@@ -26,4 +26,3 @@ export interface Schedule {
  * @returns A frozen, active schedule.
  */
 export declare function createSchedule(id: string, jobId: string, type: ScheduleType, nextRunAt: Date, options?: ScheduleOptions, expression?: string): Schedule;
-//# sourceMappingURL=schedule.type.d.ts.map

package/dist/scheduler/schedule/schedule.type.js

@@ -20,4 +20,3 @@ export function createSchedule(id, jobId, type, nextRunAt, options = {}, express
         ...(expression === undefined ? {} : { expression }),
     });
 }
-//# sourceMappingURL=schedule.type.js.map

package/dist/scheduler/schedule/scheduleOptions.type.d.ts

@@ -3,7 +3,11 @@ import type { MisfirePolicy, OverlapPolicy } from "../types/schedulerTypes.core.
  * Options for a schedule.
  */
 export interface ScheduleOptions {
-    /** IANA timezone name. Only "UTC" is currently honoured by CronTrigger. */
+    /**
+     * Zone a cron expression is read in: an IANA name such as `"Africa/Lagos"`
+     * (DST honoured through `Intl`), `"UTC"`, or omitted for the host's local
+     * zone. Ignored by non-cron schedules.
+     */
     readonly timezone?: string;
     /**
      * How to handle a fire time that has already passed (default: "run-once").
@@ -30,4 +34,3 @@ export interface ScheduleOptions {
     /** Payload handed to the job handler as `context.data`. */
     readonly data?: unknown;
 }
-//# sourceMappingURL=scheduleOptions.type.d.ts.map

package/dist/scheduler/schedule/scheduleOptions.type.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=scheduleOptions.type.js.map

package/dist/scheduler/scheduleHandle/index.d.ts

@@ -1,4 +1,3 @@
 export type { ScheduleHandle } from "./scheduleHandle.type.js";
 export { ScheduleHandleImpl } from "./scheduleHandle.type.js";
 export type { ScheduleHandleBinding } from "./scheduleHandle.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/scheduler/scheduleHandle/index.js

@@ -1,2 +1 @@
 export { ScheduleHandleImpl } from "./scheduleHandle.type.js";
-//# sourceMappingURL=index.js.map

package/dist/scheduler/scheduleHandle/scheduleHandle.type.d.ts

@@ -46,4 +46,3 @@ export declare class ScheduleHandleImpl implements ScheduleHandle {
     cancel(): Promise<void>;
     nextRun(): Date | undefined;
 }
-//# sourceMappingURL=scheduleHandle.type.d.ts.map

package/dist/scheduler/scheduleHandle/scheduleHandle.type.js

@@ -42,4 +42,3 @@ export class ScheduleHandleImpl {
         return this.binding?.getNextRun();
     }
 }
-//# sourceMappingURL=scheduleHandle.type.js.map

package/dist/scheduler/scheduler.core.d.ts

@@ -217,4 +217,3 @@ export declare class Scheduler {
      */
     private calculateDelay;
 }
-//# sourceMappingURL=scheduler.core.d.ts.map

package/dist/scheduler/scheduler.core.js

@@ -665,4 +665,3 @@ function statusFor(error) {
         return "cancelled";
     return "failed";
 }
-//# sourceMappingURL=scheduler.core.js.map

package/dist/scheduler/trigger/cron.parser.d.ts

@@ -8,6 +8,7 @@
  * comma-separated list of any of those. Month and day-of-week also accept the
  * usual three-letter names. A leading `@yearly`-style macro is expanded first.
  */
+import type { CronZone } from "./cron.zone.js";
 /** A parsed cron expression: the permitted values for each field. */
 export interface ParsedCron {
     readonly minute: ReadonlySet<number>;
@@ -33,12 +34,14 @@ export declare function parseCron(expression: string): ParsedCron;
  *
  * Search is minute-by-minute with whole-field skips, bounded by
  * {@link MAX_SEARCH_YEARS} so an unsatisfiable expression (30 February) fails
- * rather than looping.
+ * rather than looping. Every skip is computed in wall-clock terms of the
+ * schedule's zone, so a DST transition neither skips nor repeats an hour of
+ * scheduling, and a half-hour zone (Asia/Kolkata) still visits every minute.
  *
  * @param parsed - The parsed expression.
  * @param after - The instant to search forward from (exclusive).
- * @param utc - Interpret the fields in UTC rather than local time.
+ * @param zone - The zone the fields are read in: a {@link CronZone}, or for
+ *   compatibility `true` for UTC and `false` (the default) for local time.
  * @returns The next fire time, or null when none exists within the horizon.
  */
-export declare function nextCronDate(parsed: ParsedCron, after: Date, utc?: boolean): Date | null;
-//# sourceMappingURL=cron.parser.d.ts.map
+export declare function nextCronDate(parsed: ParsedCron, after: Date, zone?: CronZone | boolean): Date | null;

package/dist/scheduler/trigger/cron.parser.js

@@ -9,6 +9,7 @@
  * usual three-letter names. A leading `@yearly`-style macro is expanded first.
  */
 import { CronParseError } from "../errors/scheduler.errors.js";
+import { LOCAL_ZONE, UTC_ZONE } from "./cron.zone.js";
 /** Inclusive bounds for each cron field. */
 const FIELD_BOUNDS = [
     { name: "minute", min: 0, max: 59 },
@@ -173,50 +174,44 @@ function resolveValue(raw, bounds, expression, rawDayOfWeek = false) {
  *
  * Search is minute-by-minute with whole-field skips, bounded by
  * {@link MAX_SEARCH_YEARS} so an unsatisfiable expression (30 February) fails
- * rather than looping.
+ * rather than looping. Every skip is computed in wall-clock terms of the
+ * schedule's zone, so a DST transition neither skips nor repeats an hour of
+ * scheduling, and a half-hour zone (Asia/Kolkata) still visits every minute.
  *
  * @param parsed - The parsed expression.
  * @param after - The instant to search forward from (exclusive).
- * @param utc - Interpret the fields in UTC rather than local time.
+ * @param zone - The zone the fields are read in: a {@link CronZone}, or for
+ *   compatibility `true` for UTC and `false` (the default) for local time.
  * @returns The next fire time, or null when none exists within the horizon.
  */
-export function nextCronDate(parsed, after, utc = false) {
-    const get = {
-        minute: (d) => (utc ? d.getUTCMinutes() : d.getMinutes()),
-        hour: (d) => (utc ? d.getUTCHours() : d.getHours()),
-        date: (d) => (utc ? d.getUTCDate() : d.getDate()),
-        month: (d) => (utc ? d.getUTCMonth() : d.getMonth()) + 1,
-        day: (d) => (utc ? d.getUTCDay() : d.getDay()),
-        year: (d) => (utc ? d.getUTCFullYear() : d.getFullYear()),
-    };
+export function nextCronDate(parsed, after, zone = false) {
+    const clock = typeof zone === "boolean" ? (zone ? UTC_ZONE : LOCAL_ZONE) : zone;
     // Start at the next whole minute after `after`, with seconds cleared.
-    const candidate = new Date(after.getTime());
-    if (utc)
-        candidate.setUTCSeconds(0, 0);
-    else
-        candidate.setSeconds(0, 0);
-    candidate.setTime(candidate.getTime() + 60_000);
-    const limitYear = get.year(after) + MAX_SEARCH_YEARS;
-    while (get.year(candidate) <= limitYear) {
-        if (!parsed.month.has(get.month(candidate))) {
-            advanceMonth(candidate, utc);
+    let candidate = Math.floor(after.getTime() / 60_000) * 60_000 + 60_000;
+    const limitYear = clock.fields(after.getTime()).year + MAX_SEARCH_YEARS;
+    for (;;) {
+        const now = clock.fields(candidate);
+        if (now.year > limitYear) {
+            return null;
+        }
+        if (!parsed.month.has(now.month)) {
+            candidate = advanceTo(candidate, clock.instantOf(now.year, now.month + 1, 1, 0, 0));
             continue;
         }
-        if (!matchesDay(parsed, candidate, get.date, get.day)) {
-            advanceDay(candidate, utc);
+        if (!matchesDay(parsed, now)) {
+            candidate = advanceTo(candidate, clock.instantOf(now.year, now.month, now.date + 1, 0, 0));
             continue;
         }
-        if (!parsed.hour.has(get.hour(candidate))) {
-            advanceHour(candidate, utc);
+        if (!parsed.hour.has(now.hour)) {
+            candidate = advanceHour(candidate, now.minute, clock);
             continue;
         }
-        if (!parsed.minute.has(get.minute(candidate))) {
-            candidate.setTime(candidate.getTime() + 60_000);
+        if (!parsed.minute.has(now.minute)) {
+            candidate += 60_000;
             continue;
         }
-        return candidate;
+        return new Date(candidate);
     }
-    return null;
 }
 /**
  * Applies the cron day-matching rule.
@@ -226,9 +221,9 @@ export function nextCronDate(parsed, after, utc = false) {
  * implementation preserves, because `0 0 1,15 * mon` is widely used to mean
  * "the 1st, the 15th, and every Monday".
  */
-function matchesDay(parsed, candidate, getDate, getDay) {
-    const domMatches = parsed.dayOfMonth.has(getDate(candidate));
-    const dowMatches = parsed.dayOfWeek.has(getDay(candidate));
+function matchesDay(parsed, now) {
+    const domMatches = parsed.dayOfMonth.has(now.date);
+    const dowMatches = parsed.dayOfWeek.has(now.day);
     if (parsed.dayOfMonthUnrestricted && parsed.dayOfWeekUnrestricted) {
         return true;
     }
@@ -240,48 +235,28 @@ function matchesDay(parsed, candidate, getDate, getDay) {
     }
     return domMatches || dowMatches;
 }
-/** Moves to 00:00 on the first day of the next month. */
-function advanceMonth(candidate, utc) {
-    if (utc) {
-        candidate.setUTCDate(1);
-        candidate.setUTCHours(0, 0, 0, 0);
-        candidate.setUTCMonth(candidate.getUTCMonth() + 1);
-    }
-    else {
-        candidate.setDate(1);
-        candidate.setHours(0, 0, 0, 0);
-        candidate.setMonth(candidate.getMonth() + 1);
-    }
-}
-/** Moves to 00:00 on the next day. */
-function advanceDay(candidate, utc) {
-    if (utc) {
-        candidate.setUTCHours(0, 0, 0, 0);
-        candidate.setUTCDate(candidate.getUTCDate() + 1);
-    }
-    else {
-        candidate.setHours(0, 0, 0, 0);
-        candidate.setDate(candidate.getDate() + 1);
-    }
+/**
+ * Moves the search to `target`, never backwards.
+ *
+ * A wall-clock midnight that does not exist in the zone (a DST gap at
+ * 00:00) can resolve to an instant before the candidate; falling back to
+ * the next minute keeps the search advancing until the gap is behind it.
+ */
+function advanceTo(candidate, target) {
+    return Number.isFinite(target) && target > candidate
+        ? target
+        : candidate + 60_000;
 }
 /**
  * Moves to the top of the next hour.
  *
  * Uses wall-clock arithmetic rather than adding an hour of milliseconds, so a
- * DST transition does not skip or repeat an hour of scheduling. In UTC mode
- * the top of the hour is taken in UTC: a host on a half-hour offset
- * (Asia/Kolkata) would otherwise land every skip on :30 UTC and never visit
- * minutes 0-29 of a restricted hour.
+ * DST transition does not skip or repeat an hour of scheduling. The top of the
+ * hour is taken in the schedule's zone: a host on a half-hour offset
+ * (Asia/Kolkata) evaluating a UTC schedule would otherwise land every skip
+ * on :30 UTC and never visit minutes 0-29 of a restricted hour.
  */
-function advanceHour(candidate, utc) {
-    if (utc) {
-        candidate.setUTCMinutes(0, 0, 0);
-        candidate.setTime(candidate.getTime() + 3_600_000);
-        candidate.setUTCMinutes(0, 0, 0);
-        return;
-    }
-    candidate.setMinutes(0, 0, 0);
-    candidate.setTime(candidate.getTime() + 3_600_000);
-    candidate.setMinutes(0, 0, 0);
+function advanceHour(candidate, minute, clock) {
+    const nextHour = candidate - minute * 60_000 + 3_600_000;
+    return nextHour - clock.fields(nextHour).minute * 60_000;
 }
-//# sourceMappingURL=cron.parser.js.map

package/dist/scheduler/trigger/cron.zone.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Wall-clock arithmetic for cron evaluation in a named time zone.
+ *
+ * A cron expression is written in wall-clock terms (09:00 on Mondays), so
+ * computing its next fire time needs two operations: reading the wall-clock
+ * fields of an instant in the schedule's zone, and turning a wall-clock time
+ * back into an instant. Node ships full IANA zone data through `Intl`, which
+ * is what makes `Africa/Lagos` or `America/New_York` work without a
+ * dependency.
+ *
+ * @module scheduler/trigger/cron.zone
+ */
+/** The wall-clock fields cron matches against. Month is 1-12, day 0-6. */
+export interface CronWallClock {
+    readonly year: number;
+    readonly month: number;
+    readonly date: number;
+    readonly hour: number;
+    readonly minute: number;
+    readonly day: number;
+}
+/** A time zone as the cron evaluator sees it. */
+export interface CronZone {
+    /** Canonical IANA name, `"UTC"`, or `undefined` for the host's local zone. */
+    readonly name: string | undefined;
+    /** Wall-clock fields of `instant` in this zone. */
+    fields(instant: number): CronWallClock;
+    /**
+     * The instant at which the given wall-clock time occurs in this zone.
+     * A time inside a DST gap resolves to the instant the clocks jumped to; a
+     * repeated time resolves to its first occurrence. Overflowing fields
+     * (month 13, date 32) roll over like `Date.UTC`.
+     */
+    instantOf(year: number, month: number, date: number, hour: number, minute: number): number;
+}
+/** The host's local zone, as `Date`'s local accessors report it. */
+export declare const LOCAL_ZONE: CronZone;
+/** Coordinated Universal Time. */
+export declare const UTC_ZONE: CronZone;
+/** Builds a zone backed by `Intl` zone data; `undefined` for an unknown name. */
+export declare function createIntlZone(timezone: string): CronZone | undefined;
+/**
+ * Resolves the zone a cron schedule is evaluated in.
+ *
+ * `undefined` selects the host's local zone, `"UTC"` (any case) or
+ * `"Etc/UTC"` selects UTC, and any other value is looked up as an IANA name.
+ *
+ * @returns The zone, or `undefined` when the name is not a known zone.
+ */
+export declare function resolveCronZone(timezone?: string): CronZone | undefined;

package/dist/scheduler/trigger/cron.zone.js

@@ -0,0 +1,118 @@
+/**
+ * Wall-clock arithmetic for cron evaluation in a named time zone.
+ *
+ * A cron expression is written in wall-clock terms (09:00 on Mondays), so
+ * computing its next fire time needs two operations: reading the wall-clock
+ * fields of an instant in the schedule's zone, and turning a wall-clock time
+ * back into an instant. Node ships full IANA zone data through `Intl`, which
+ * is what makes `Africa/Lagos` or `America/New_York` work without a
+ * dependency.
+ *
+ * @module scheduler/trigger/cron.zone
+ */
+/** Freezes a zone while keeping its methods contextually typed. */
+function defineZone(zone) {
+    return Object.freeze(zone);
+}
+/** The host's local zone, as `Date`'s local accessors report it. */
+export const LOCAL_ZONE = defineZone({
+    name: undefined,
+    fields(instant) {
+        const d = new Date(instant);
+        return {
+            year: d.getFullYear(),
+            month: d.getMonth() + 1,
+            date: d.getDate(),
+            hour: d.getHours(),
+            minute: d.getMinutes(),
+            day: d.getDay(),
+        };
+    },
+    instantOf(year, month, date, hour, minute) {
+        return new Date(year, month - 1, date, hour, minute).getTime();
+    },
+});
+/** Coordinated Universal Time. */
+export const UTC_ZONE = defineZone({
+    name: "UTC",
+    fields(instant) {
+        const d = new Date(instant);
+        return {
+            year: d.getUTCFullYear(),
+            month: d.getUTCMonth() + 1,
+            date: d.getUTCDate(),
+            hour: d.getUTCHours(),
+            minute: d.getUTCMinutes(),
+            day: d.getUTCDay(),
+        };
+    },
+    instantOf(year, month, date, hour, minute) {
+        return Date.UTC(year, month - 1, date, hour, minute);
+    },
+});
+const PART_TYPES = ["year", "month", "day", "hour", "minute"];
+/** Builds a zone backed by `Intl` zone data; `undefined` for an unknown name. */
+export function createIntlZone(timezone) {
+    let formatter;
+    try {
+        formatter = new Intl.DateTimeFormat("en-US", {
+            timeZone: timezone,
+            hourCycle: "h23",
+            year: "numeric",
+            month: "numeric",
+            day: "numeric",
+            hour: "numeric",
+            minute: "numeric",
+        });
+    }
+    catch {
+        return undefined;
+    }
+    const name = formatter.resolvedOptions().timeZone;
+    const wallAsUtc = (instant) => {
+        const values = {};
+        for (const part of formatter.formatToParts(new Date(instant))) {
+            if (PART_TYPES.includes(part.type)) {
+                values[part.type] = Number(part.value);
+            }
+        }
+        return Date.UTC(values.year ?? 1970, (values.month ?? 1) - 1, values.day ?? 1, (values.hour ?? 0) % 24, values.minute ?? 0);
+    };
+    const offsetAt = (instant) => wallAsUtc(instant) - instant;
+    return defineZone({
+        name,
+        fields(instant) {
+            const wall = new Date(wallAsUtc(instant));
+            return {
+                year: wall.getUTCFullYear(),
+                month: wall.getUTCMonth() + 1,
+                date: wall.getUTCDate(),
+                hour: wall.getUTCHours(),
+                minute: wall.getUTCMinutes(),
+                day: wall.getUTCDay(),
+            };
+        },
+        instantOf(year, month, date, hour, minute) {
+            const wall = Date.UTC(year, month - 1, date, hour, minute);
+            const guess = wall - offsetAt(wall);
+            return wall - offsetAt(guess);
+        },
+    });
+}
+/**
+ * Resolves the zone a cron schedule is evaluated in.
+ *
+ * `undefined` selects the host's local zone, `"UTC"` (any case) or
+ * `"Etc/UTC"` selects UTC, and any other value is looked up as an IANA name.
+ *
+ * @returns The zone, or `undefined` when the name is not a known zone.
+ */
+export function resolveCronZone(timezone) {
+    if (timezone === undefined) {
+        return LOCAL_ZONE;
+    }
+    if (/^utc$/i.test(timezone) || timezone === "Etc/UTC") {
+        return UTC_ZONE;
+    }
+    return createIntlZone(timezone);
+}

package/dist/scheduler/trigger/index.d.ts

@@ -2,4 +2,5 @@ export type { Trigger } from "./trigger.type.js";
 export { DateTrigger, DelayTrigger, IntervalTrigger, CronTrigger, } from "./schedulerTrigger.core.js";
 export { parseCron, nextCronDate } from "./cron.parser.js";
 export type { ParsedCron } from "./cron.parser.js";
-//# sourceMappingURL=index.d.ts.map
+export { LOCAL_ZONE, UTC_ZONE, createIntlZone, resolveCronZone, } from "./cron.zone.js";
+export type { CronWallClock, CronZone } from "./cron.zone.js";

package/dist/scheduler/trigger/index.js

@@ -1,3 +1,3 @@
 export { DateTrigger, DelayTrigger, IntervalTrigger, CronTrigger, } from "./schedulerTrigger.core.js";
 export { parseCron, nextCronDate } from "./cron.parser.js";
-//# sourceMappingURL=index.js.map
+export { LOCAL_ZONE, UTC_ZONE, createIntlZone, resolveCronZone, } from "./cron.zone.js";

package/dist/scheduler/trigger/schedulerTrigger.core.d.ts

@@ -40,17 +40,18 @@ export declare class IntervalTrigger implements Trigger {
 export declare class CronTrigger implements Trigger {
     private readonly expression;
     private readonly parsed;
-    private readonly utc;
+    private readonly zone;
     /**
      * @param expression - A five-field cron expression, or a macro such as `@daily`.
-     * @param timezone - Pass `"UTC"` to interpret the fields in UTC. Any other
-     *   value is rejected: honouring an arbitrary IANA zone needs real zone data,
-     *   and silently ignoring the argument is what made the previous
-     *   implementation's `timezone` parameter meaningless.
+     * @param timezone - The zone the fields are read in: an IANA name such as
+     *   `"Africa/Lagos"` or `"America/New_York"` (resolved through `Intl`, so
+     *   DST is honoured), `"UTC"`, or omitted for the host's local zone. An
+     *   unknown name is rejected rather than silently ignored.
      */
     constructor(expression: string, timezone?: string);
     /** The expression this trigger was built from. */
     get source(): string;
+    /** The canonical zone the fields are read in; `undefined` for local time. */
+    get timezone(): string | undefined;
     next(after: Date): Date | null;
 }
-//# sourceMappingURL=schedulerTrigger.core.d.ts.map

package/dist/scheduler/trigger/schedulerTrigger.core.js

@@ -1,4 +1,5 @@
 import { parseCron, nextCronDate } from "./cron.parser.js";
+import { resolveCronZone } from "./cron.zone.js";
 import { InvalidScheduleError } from "../errors/scheduler.errors.js";
 /**
  * Trigger that fires once at a specific date.
@@ -65,33 +66,33 @@ export class IntervalTrigger {
 export class CronTrigger {
     expression;
     parsed;
-    utc;
+    zone;
     /**
      * @param expression - A five-field cron expression, or a macro such as `@daily`.
-     * @param timezone - Pass `"UTC"` to interpret the fields in UTC. Any other
-     *   value is rejected: honouring an arbitrary IANA zone needs real zone data,
-     *   and silently ignoring the argument is what made the previous
-     *   implementation's `timezone` parameter meaningless.
+     * @param timezone - The zone the fields are read in: an IANA name such as
+     *   `"Africa/Lagos"` or `"America/New_York"` (resolved through `Intl`, so
+     *   DST is honoured), `"UTC"`, or omitted for the host's local zone. An
+     *   unknown name is rejected rather than silently ignored.
      */
     constructor(expression, timezone) {
         this.expression = expression;
         this.parsed = parseCron(expression);
-        if (timezone === undefined) {
-            this.utc = false;
-        }
-        else if (/^utc$/i.test(timezone) || timezone === "Etc/UTC") {
-            this.utc = true;
-        }
-        else {
-            throw new InvalidScheduleError(`CronTrigger supports only "UTC" or the system local zone, got "${timezone}"`, expression);
+        const zone = resolveCronZone(timezone);
+        if (zone === undefined) {
+            throw new InvalidScheduleError(`CronTrigger received an unknown time zone "${timezone}"; use an IANA name such as "Africa/Lagos", or "UTC"`, expression);
         }
+        this.zone = zone;
     }
     /** The expression this trigger was built from. */
     get source() {
         return this.expression;
     }
+    /** The canonical zone the fields are read in; `undefined` for local time. */
+    get timezone() {
+        return this.zone.name;
+    }
     next(after) {
-        return nextCronDate(this.parsed, after, this.utc);
+        return nextCronDate(this.parsed, after, this.zone);
     }
 }
 /**
@@ -114,4 +115,3 @@ function assertUsableInterval(ms, what) {
         throw new InvalidScheduleError(`${what} interval ${ms}ms exceeds the representable date range`, what);
     }
 }
-//# sourceMappingURL=schedulerTrigger.core.js.map

package/dist/scheduler/trigger/trigger.type.d.ts

@@ -9,4 +9,3 @@
 export interface Trigger {
     next(after: Date): Date | null;
 }
-//# sourceMappingURL=trigger.type.d.ts.map

package/dist/scheduler/trigger/trigger.type.js

@@ -4,4 +4,3 @@
  * Trigger types for the scheduler package.
  */
 export {};
-//# sourceMappingURL=trigger.type.js.map

package/dist/scheduler/types/index.d.ts

@@ -10,4 +10,3 @@ export type { JobOptions, RetryPolicy, RetryStrategy, JobDefinition, JobHandler,
 export type { Schedule, ScheduleOptions } from "../schedule/index.js";
 export type { ScheduleHandle } from "../scheduleHandle/index.js";
 export type { Trigger } from "../trigger/index.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/scheduler/types/index.js

@@ -6,4 +6,3 @@
  * type a consumer imports is the one the implementation actually uses.
  */
 export {};
-//# sourceMappingURL=index.js.map

package/dist/scheduler/types/schedulerTypes.core.d.ts

@@ -63,4 +63,3 @@ export interface JobExecutionResult {
     readonly success: boolean;
     readonly error?: unknown;
 }
-//# sourceMappingURL=schedulerTypes.core.d.ts.map

package/dist/scheduler/types/schedulerTypes.core.js

@@ -10,4 +10,3 @@
  * `scheduler.every(..., { overlap: "skip" })` did not typecheck.
  */
 export {};
-//# sourceMappingURL=schedulerTypes.core.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/scheduler",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "Scheduled task and job infrastructure with cron-like scheduling, persistence, and worker management.",
   "license": "MIT",
   "author": {
@@ -27,9 +27,9 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@zudojs/errors": "1.3.2",
-    "@zudojs/constants": "1.1.4",
-    "@zudojs/types": "1.2.0"
+    "@zudojs/errors": "1.4.0",
+    "@zudojs/constants": "1.2.0",
+    "@zudojs/types": "1.3.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",