Timezone

By default every job schedules relative to UTC. Use .inTimezone() to pin a job to a specific IANA timezone so its wall-clock time stays correct regardless of server location or DST transitions.

Basic Usage

import { scheduler, job } from "@warlock.js/scheduler";

scheduler.addJob(
  job("morning-digest", sendDailyDigest)
    .daily()
    .at("08:00")
    .inTimezone("America/New_York")   // fires at 8 AM Eastern, not 8 AM UTC
);

scheduler.start();

Per-Job Timezones

Each job has its own timezone. You can run the same logical task in multiple regions by registering separate jobs:

import { scheduler, job } from "@warlock.js/scheduler";

const regions = [
  { name: "us",  tz: "America/New_York" },
  { name: "eu",  tz: "Europe/Berlin" },
  { name: "asia", tz: "Asia/Tokyo" },
];

for (const { name, tz } of regions) {
  scheduler.addJob(
    job(`morning-report-${name}`, () => sendReport(name))
      .daily()
      .at("09:00")
      .inTimezone(tz)
  );
}

scheduler.start();

Common IANA Timezone Strings

Region	Timezone string
US Eastern	`America/New_York`
US Central	`America/Chicago`
US Mountain	`America/Denver`
US Pacific	`America/Los_Angeles`
UTC	`UTC`
UK / Ireland	`Europe/London`
Central Europe	`Europe/Berlin`
Eastern Europe	`Europe/Kiev`
India	`Asia/Kolkata`
Japan	`Asia/Tokyo`
Australia (Sydney)	`Australia/Sydney`

A full list is available at IANA Time Zone Database.

Signature

job.inTimezone(tz: string): this

The tz parameter must be a valid IANA timezone identifier. Invalid values will cause dayjs (the underlying library) to throw when calculating the next run time.

Interaction with `at()` and `on()`

The timezone applies to all time calculations for that job. When you write:

job("task", fn)
  .weekly()
  .on("monday")
  .at("09:00")
  .inTimezone("Europe/Berlin")

The job fires at 9:00 AM Berlin local time on Mondays — automatically shifting for CET/CEST as DST changes.