@procedures/schedule 0.4.0 → 0.6.0

package/src/cron.ts

@@ -1,8 +1,8 @@
 /**
  * Cron expressions (roadmap R46): the parse and the next times.
  *
- * This package parses cron itself. The format is small, and a dependency for it gives a time
- * zone database or a second format that this package does not need.
+ * This package parses cron itself. The format is small, and `Intl` gives the offsets of each time
+ * zone. A dependency gives a time zone database or a second format that this package does not need.
  *
  * - 5 fields: minute (0-59), hour (0-23), day of the month (1-31), month (1-12), day of the week
  *   (0-7, with 0 and 7 for Sunday).
@@ -13,8 +13,16 @@
  * - The days, as in Vixie cron: when the two day fields have a limit (they do not start with
  *   `*`), a day matches when one of the two matches. Else the field with a limit decides.
  *
- * The times are in UTC or in the local time of the host. In local time, a time that the change
- * to summer time skips does not run, and a time that the change back repeats can run two times.
+ * The time zone is `utc`, `local` (the time zone of the host) or an IANA name, for example
+ * `Europe/Berlin`. The changes of daylight saving time follow Vixie cron:
+ *
+ * - A fixed time has no `*` at the start of its minute field and of its hour field: `30 2 * * *`.
+ * - A fixed time in the hour that does not exist runs once, at the first minute after the change.
+ *   Two such times of one expression give one run.
+ * - A fixed time in the hour that occurs twice runs once, at its first occurrence.
+ * - An expression with `*` at the start of its minute field or of its hour field follows the
+ *   clock. It has no run for a time that does not exist, and it runs at the two occurrences of a
+ *   time that occurs twice. Thus `0 * * * *` runs each hour of real time.
  */
 
 import { ScheduleError } from "./errors.js";
@@ -33,6 +41,11 @@ export interface CronExpression {
   readonly dayLimited: boolean;
   /** True when the field of the day of the week does not start with `*`. */
   readonly weekdayLimited: boolean;
+  /**
+   * True when the minute field and the hour field do not start with `*`. A fixed time obeys the
+   * rules of Vixie cron for the changes of daylight saving time (see the comment of the file).
+   */
+  readonly fixedTime: boolean;
 }
 
 const MONTHS = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
@@ -133,10 +146,107 @@ export function parseCron(text: string): CronExpression {
     weekdays,
     dayLimited: !fields[2]!.startsWith("*"),
     weekdayLimited: !fields[4]!.startsWith("*"),
+    fixedTime: !fields[0]!.startsWith("*") && !fields[1]!.startsWith("*"),
   };
 }
 
-/** The fields of a time in a time zone. */
+// =============================================================================
+// Time zones
+// =============================================================================
+
+const MINUTE = 60_000;
+const DAY = 86_400_000;
+
+/** The form of an IANA name: `Europe/Berlin`, `UTC`, `Etc/GMT+5`. An offset such as `+05:30` is not one. */
+const IANA_NAME = /^[A-Za-z][A-Za-z0-9_+-]*(\/[A-Za-z0-9_+-]+)*$/;
+
+/** The names that `checkTimeZone` accepted, with its result: a file store examines each schedule at each read. */
+const checked = new Map<string, string>();
+
+/**
+ * This function checks a time zone and gives its name: `utc`, `local`, or an IANA name that `Intl`
+ * knows. A name that differs from the name of `Intl` only by the case gets the case of `Intl`. The
+ * function throws a `BAD_TIME_ZONE` error for another name.
+ */
+export function checkTimeZone(timeZone: string): ScheduleTimeZone {
+  if (timeZone === "utc" || timeZone === "local") return timeZone;
+  const known = checked.get(timeZone);
+  if (known !== undefined) return known;
+  let resolved: string | undefined;
+  if (timeZone.length <= 100 && IANA_NAME.test(timeZone)) {
+    try {
+      resolved = new Intl.DateTimeFormat("en-US", { timeZone }).resolvedOptions().timeZone;
+    } catch {
+      resolved = undefined;
+    }
+  }
+  if (resolved === undefined) {
+    throw new ScheduleError("BAD_TIME_ZONE", `The time zone ${JSON.stringify(timeZone)} is not utc, local or an IANA name that Intl knows, for example Europe/Berlin`);
+  }
+  const name = resolved.toLowerCase() === timeZone.toLowerCase() ? resolved : timeZone;
+  // The cache stays small: a process uses few zones
+  if (checked.size >= 1000) checked.clear();
+  checked.set(timeZone, name);
+  return name;
+}
+
+/** This function gives the IANA name of the time zone of the process, from `Intl`. */
+export function hostTimeZone(): string {
+  return new Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+}
+
+/** The offsets of one time zone of `Intl`. */
+class Zone {
+  private readonly format: Intl.DateTimeFormat;
+
+  constructor(name: string) {
+    this.format = new Intl.DateTimeFormat("en-US", {
+      timeZone: name,
+      hourCycle: "h23",
+      year: "numeric",
+      month: "numeric",
+      day: "numeric",
+      hour: "numeric",
+      minute: "numeric",
+      second: "numeric",
+    });
+  }
+
+  /** This method gives the offset of the zone at a time: the wall time minus the time, in milliseconds. */
+  offset(time: number): number {
+    const value: Partial<Record<Intl.DateTimeFormatPartTypes, number>> = {};
+    for (const part of this.format.formatToParts(time)) if (part.type !== "literal") value[part.type] = Number(part.value);
+    const wall = Date.UTC(value.year ?? 1970, (value.month ?? 1) - 1, value.day ?? 1, (value.hour ?? 0) % 24, value.minute ?? 0, value.second ?? 0);
+    return wall - Math.floor(time / 1000) * 1000;
+  }
+}
+
+/** The zones, by the name in lower case: `Intl` ignores the case of a name. */
+const zones = new Map<string, Zone>();
+
+/** The zone of a name. It throws `BAD_TIME_ZONE` for a name that `Intl` does not know. */
+function zoneOf(timeZone: string): Zone {
+  const key = timeZone.toLowerCase();
+  let zone = zones.get(key);
+  if (zone === undefined) {
+    zone = new Zone(checkTimeZone(timeZone));
+    zones.set(key, zone);
+  }
+  return zone;
+}
+
+/** The IANA name of a time zone that is not `utc`: `local` is the time zone of the host. */
+const ianaName = (timeZone: ScheduleTimeZone): string => (timeZone === "local" ? hostTimeZone() : timeZone);
+
+// =============================================================================
+// Wall times
+// =============================================================================
+
+/**
+ * A wall time is the time that a clock shows, as milliseconds with the arithmetic of UTC: the
+ * fields of `new Date(wall)` in UTC are the fields of the clock. A time is a real time. In a zone,
+ * the wall time of a time is the time plus the offset of the zone at that time.
+ */
 interface Fields {
   year: number;
   month: number;
@@ -146,28 +256,11 @@ interface Fields {
   weekday: number;
 }
 
-/** The calendar of a time zone: the fields of a time, and the time of fields (which can overflow). */
-interface Calendar {
-  fields(time: number): Fields;
-  make(year: number, month: number, day: number, hour: number, minute: number): number;
+function fieldsOf(wall: number): Fields {
+  const date = new Date(wall);
+  return { year: date.getUTCFullYear(), month: date.getUTCMonth() + 1, day: date.getUTCDate(), hour: date.getUTCHours(), minute: date.getUTCMinutes(), weekday: date.getUTCDay() };
 }
 
-const UTC: Calendar = {
-  fields(time) {
-    const date = new Date(time);
-    return { year: date.getUTCFullYear(), month: date.getUTCMonth() + 1, day: date.getUTCDate(), hour: date.getUTCHours(), minute: date.getUTCMinutes(), weekday: date.getUTCDay() };
-  },
-  make: (year, month, day, hour, minute) => Date.UTC(year, month - 1, day, hour, minute),
-};
-
-const LOCAL: Calendar = {
-  fields(time) {
-    const date = new Date(time);
-    return { year: date.getFullYear(), month: date.getMonth() + 1, day: date.getDate(), hour: date.getHours(), minute: date.getMinutes(), weekday: date.getDay() };
-  },
-  make: (year, month, day, hour, minute) => new Date(year, month - 1, day, hour, minute).getTime(),
-};
-
 /** The years that a search covers: Feb 29 can be 8 years away (2096 to 2104). */
 const SEARCH_YEARS = 9;
 
@@ -182,28 +275,154 @@ function dayMatches(cron: CronExpression, fields: Fields): boolean {
 }
 
 /**
- * This function gives the first time of the expression after `after` (milliseconds since 1970),
- * or undefined when the expression has no time in the next 9 years.
+ * This function gives the first wall time of the expression after the wall time `after` (a whole
+ * minute), or undefined when the expression has no wall time in the next 9 years.
  */
-export function nextTime(cron: CronExpression, after: number, timeZone: ScheduleTimeZone = "local"): number | undefined {
-  const calendar = timeZone === "utc" ? UTC : LOCAL;
-  let time = Math.floor(after / 60_000) * 60_000 + 60_000;
-  const lastYear = calendar.fields(after).year + SEARCH_YEARS;
+function nextWall(cron: CronExpression, after: number): number | undefined {
+  let wall = after + MINUTE;
+  const lastYear = fieldsOf(after).year + SEARCH_YEARS;
   for (let step = 0; step < 1_000_000; step++) {
-    const fields = calendar.fields(time);
+    const fields = fieldsOf(wall);
     if (fields.year > lastYear) return undefined;
-    let next: number;
-    if (!cron.months.has(fields.month)) next = calendar.make(fields.year, fields.month + 1, 1, 0, 0);
-    else if (!dayMatches(cron, fields)) next = calendar.make(fields.year, fields.month, fields.day + 1, 0, 0);
-    else if (!cron.hours.has(fields.hour)) next = calendar.make(fields.year, fields.month, fields.day, fields.hour + 1, 0);
-    else if (!cron.minutes.has(fields.minute)) next = time + 60_000;
-    else return time;
-    // A change of the clock can give a time that is not later: go one minute on
-    time = next > time ? next : time + 60_000;
+    if (!cron.months.has(fields.month)) wall = Date.UTC(fields.year, fields.month, 1);
+    else if (!dayMatches(cron, fields)) wall = Date.UTC(fields.year, fields.month - 1, fields.day + 1);
+    else if (!cron.hours.has(fields.hour)) wall = Date.UTC(fields.year, fields.month - 1, fields.day, fields.hour + 1);
+    else if (!cron.minutes.has(fields.minute)) wall += MINUTE;
+    else return wall;
+  }
+  return undefined;
+}
+
+/**
+ * This function gives the first minute in `(from, to]` with another offset than `from`. The
+ * offsets of `from` and `to` differ, and one change of the offset is between them.
+ */
+function changeIn(zone: Zone, from: number, to: number): number {
+  const offset = zone.offset(from);
+  let low = from;
+  let high = to;
+  while (high - low > MINUTE) {
+    const middle = low + Math.floor((high - low) / 2 / MINUTE) * MINUTE;
+    if (zone.offset(middle) === offset) low = middle;
+    else high = middle;
+  }
+  return high;
+}
+
+/**
+ * The times of a wall time, sorted: one time, two times in the hour that occurs twice, or none in
+ * the hour that does not exist. For none, `change` is the time of the change: its wall time is
+ * the first wall time after the gap.
+ */
+function timesOf(zone: Zone, wall: number): { times: number[]; change?: number } {
+  // The offsets a day before and a day after: a change of the clock near the wall time is between them
+  const before = zone.offset(wall - DAY);
+  const after = zone.offset(wall + DAY);
+  const times = [...new Set([wall - before, wall - after])].filter((time) => time + zone.offset(time) === wall).sort((a, b) => a - b);
+  if (times.length > 0 || before >= after) return { times };
+  return { times, change: changeIn(zone, wall - after, wall - before) };
+}
+
+/**
+ * The highest wall time of the minutes up to the minute `time`. After a change back, the clock
+ * shows an hour a second time, and this wall time stays above the wall time of `time`.
+ */
+function highWall(zone: Zone, time: number): number {
+  const offset = zone.offset(time);
+  const earlier = zone.offset(time - DAY);
+  if (earlier <= offset) return time + offset;
+  const change = changeIn(zone, time - DAY, time);
+  return Math.max(time + offset, change - MINUTE + earlier);
+}
+
+/**
+ * The next time of a fixed time after the minute `after`. Each wall time runs at the first time
+ * whose wall time is the same or later. Thus a wall time in a gap runs at the change, and a wall
+ * time that occurs twice runs at its first occurrence. The wall times after the highest wall time
+ * of `after` are the wall times that did not run.
+ */
+function nextFixed(cron: CronExpression, zone: Zone, after: number): number | undefined {
+  let wall = highWall(zone, after);
+  for (let step = 0; step < 1000; step++) {
+    const next = nextWall(cron, wall);
+    if (next === undefined) return undefined;
+    const { times, change } = timesOf(zone, next);
+    if (times.length > 0) return times[0];
+    if (change !== undefined) return change;
+    wall = next;
   }
   return undefined;
 }
 
+/**
+ * The next time of an expression that follows the clock, after the minute `after`: the first time
+ * whose wall time matches. A wall time in a gap has no time. A wall time that occurs twice has two.
+ */
+function nextByClock(cron: CronExpression, zone: Zone, after: number): number | undefined {
+  // The first occurrences: the wall times after the highest wall time
+  let first: number | undefined;
+  let wall = highWall(zone, after);
+  for (let step = 0; step < 1000 && first === undefined; step++) {
+    const next = nextWall(cron, wall);
+    if (next === undefined) break;
+    const { times, change } = timesOf(zone, next);
+    if (times.length > 0) first = times[0];
+    // A wall time in a gap has no time: the search goes on after the gap
+    else wall = change === undefined ? next : change + zone.offset(change) - MINUTE;
+  }
+  const second = secondOccurrence(cron, zone, after);
+  if (first === undefined) return second;
+  return second === undefined ? first : Math.min(first, second);
+}
+
+/**
+ * The first time after the minute `after` in the hour that the clock shows a second time, when a
+ * change back is near `after`, or undefined.
+ */
+function secondOccurrence(cron: CronExpression, zone: Zone, after: number): number | undefined {
+  const offset = zone.offset(after);
+  const earlier = zone.offset(after - DAY);
+  const later = zone.offset(after + DAY);
+  let change: number;
+  let shift: number;
+  let repeated: number;
+  if (earlier > offset) {
+    change = changeIn(zone, after - DAY, after);
+    shift = earlier - offset;
+    repeated = offset;
+  } else if (later < offset) {
+    change = changeIn(zone, after, after + DAY);
+    shift = offset - later;
+    repeated = later;
+  } else {
+    return undefined;
+  }
+  // The second occurrences are the times from the change to the end of the shift, with the offset `repeated`
+  const end = change + shift;
+  const start = Math.max(after + MINUTE, change);
+  if (start >= end) return undefined;
+  const wall = nextWall(cron, start + repeated - MINUTE);
+  if (wall === undefined) return undefined;
+  const time = wall - repeated;
+  return time < end ? time : undefined;
+}
+
+// =============================================================================
+// The next times
+// =============================================================================
+
+/**
+ * This function gives the first time of the expression after `after` (milliseconds since 1970),
+ * or undefined when the expression has no time in the next 9 years. The time zone is `utc`,
+ * `local` or an IANA name. An unknown name gives a `BAD_TIME_ZONE` error.
+ */
+export function nextTime(cron: CronExpression, after: number, timeZone: ScheduleTimeZone = "local"): number | undefined {
+  const minute = Math.floor(after / MINUTE) * MINUTE;
+  if (timeZone === "utc") return nextWall(cron, minute);
+  const zone = zoneOf(ianaName(timeZone));
+  return cron.fixedTime ? nextFixed(cron, zone, minute) : nextByClock(cron, zone, minute);
+}
+
 /** This function gives the next `count` times of the expression after `after`. */
 export function nextTimes(cron: CronExpression, after: number, count: number, timeZone: ScheduleTimeZone = "local"): number[] {
   const times: number[] = [];
@@ -217,14 +436,24 @@ export function nextTimes(cron: CronExpression, after: number, count: number, ti
   return times;
 }
 
-const pad = (value: number, length = 2): string => String(value).padStart(length, "0");
+const pad = (value: number): string => String(value).padStart(2, "0");
 
-/** The ISO text of a time in a time zone: `2026-10-17T09:00:00Z`, or with the offset of the host: `2026-10-17T09:00:00+02:00`. */
+/**
+ * The ISO text of a time in a time zone: `2026-10-17T09:00:00Z` in UTC, or with the offset of the
+ * zone at that time: `2026-10-17T09:00:00+02:00`. An offset of 0 gives `Z`.
+ */
 export function formatTime(time: number, timeZone: ScheduleTimeZone = "local"): string {
-  const date = new Date(time);
-  if (timeZone === "utc") return `${date.toISOString().slice(0, 19)}Z`;
-  const offset = -date.getTimezoneOffset();
-  const sign = offset >= 0 ? "+" : "-";
-  const zone = offset === 0 ? "Z" : `${sign}${pad(Math.floor(Math.abs(offset) / 60))}:${pad(Math.abs(offset) % 60)}`;
-  return `${pad(date.getFullYear(), 4)}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}${zone}`;
+  if (timeZone === "utc") return `${new Date(time).toISOString().slice(0, 19)}Z`;
+  const offset = zoneOf(ianaName(timeZone)).offset(time);
+  const minutes = Math.round(offset / MINUTE);
+  const zone = minutes === 0 ? "Z" : `${minutes > 0 ? "+" : "-"}${pad(Math.floor(Math.abs(minutes) / 60))}:${pad(Math.abs(minutes) % 60)}`;
+  return `${new Date(time + offset).toISOString().slice(0, 19)}${zone}`;
+}
+
+/**
+ * This function gives the time zone of a computation. The zone `local` becomes `local` (the zone
+ * of the process) or the zone that the host gives for it.
+ */
+export function zoneFor(timeZone: ScheduleTimeZone, local: string | undefined): ScheduleTimeZone {
+  return timeZone === "local" && local !== undefined ? local : timeZone;
 }

package/src/errors.ts

@@ -6,6 +6,10 @@
 export type ScheduleErrorCode =
   /** The cron expression is not correct, or it has no time in the next 9 years. */
   | "BAD_CRON"
+  /** The time zone is not `utc`, `local` or an IANA name that `Intl` knows. */
+  | "BAD_TIME_ZONE"
+  /** Another process holds the lock file of a `FileScheduleStore` for longer than the wait. */
+  | "LOCKED"
   /** A schedule of the name exists, and the input does not replace it. */
   | "EXISTS"
   /** No stored program has the key: not in the registry, not in the program store. */

package/src/index.ts

@@ -3,8 +3,16 @@ export * from "./module.js";
 export * from "./types.js";
 export { scheduleAdd, scheduleList, scheduleRemove, scheduleNext, viewOf } from "./procedures/schedule/index.js";
 // The cron expressions, the stores and the scheduler (roadmap R46)
-export { CRON_NAMES, formatTime, nextTime, nextTimes, parseCron, type CronExpression } from "./cron.js";
+export { checkTimeZone, CRON_NAMES, formatTime, hostTimeZone, nextTime, nextTimes, parseCron, zoneFor, type CronExpression } from "./cron.js";
 export { ScheduleError, type ScheduleErrorCode } from "./errors.js";
-export { checkSchedule, defaultScheduleStore, FileScheduleStore, MemoryScheduleStore, type ScheduleStore } from "./store.js";
+export {
+  checkSchedule,
+  DEFAULT_LOCK_STALE_MS,
+  defaultScheduleStore,
+  FileScheduleStore,
+  MemoryScheduleStore,
+  type FileScheduleStoreOptions,
+  type ScheduleStore,
+} from "./store.js";
 export { DEFAULT_SCHEDULE_SETTINGS, findProgram, PROGRAM_KEY, type ScheduleSettings } from "./programs.js";
 export { DEFAULT_RUN_TIMEOUT_MS, Scheduler, type ScheduleRunEvent, type SchedulerOptions } from "./scheduler.js";

package/src/module.ts

@@ -25,6 +25,7 @@ import { scheduleAdd } from "./procedures/schedule/add.js";
 import { scheduleList } from "./procedures/schedule/list.js";
 import { scheduleRemove } from "./procedures/schedule/remove.js";
 import { scheduleNext } from "./procedures/schedule/next.js";
+import { checkTimeZone } from "./cron.js";
 import { DEFAULT_SCHEDULE_SETTINGS, PROGRAM_KEY, type ScheduleSettings } from "./programs.js";
 import type { ScheduleStore } from "./store.js";
 import type {
@@ -44,7 +45,11 @@ import type {
 // =============================================================================
 
 const cron = z.string().min(1).max(200).describe("The cron expression: 5 fields (minute hour day month weekday), or @hourly, @daily, @weekly, @monthly, @yearly");
-const timeZone = z.enum(["utc", "local"]).describe("The time zone of the expression (default local)");
+const timeZone = z
+  .string()
+  .min(1)
+  .max(100)
+  .describe("The time zone of the expression: utc, local (default) or an IANA name such as Europe/Berlin");
 const scheduleId = z
   .string()
   .regex(/^[A-Za-z0-9._:-]{1,200}$/, "Letters, digits, and . _ : -")
@@ -63,7 +68,7 @@ const view = z.object({
   cron: z.string(),
   program: z.string(),
   input: z.unknown().optional(),
-  timeZone: z.enum(["utc", "local"]),
+  timeZone: z.string().describe("The time zone: utc, local or an IANA name"),
   createdAt: z.number().describe("When the schedule was added, in milliseconds since 1970"),
   capability: z
     .custom<NonNullable<Schedule["capability"]>>((value) => value !== null && typeof value === "object")
@@ -196,6 +201,11 @@ export interface ScheduleModuleOptions {
   readonly store?: ScheduleStore | undefined;
   /** The wall time, in milliseconds since 1970. The default is `Date.now`. A test gives the time of its fake clock. */
   readonly now?: (() => number) | undefined;
+  /**
+   * The IANA time zone of the schedules with the time zone `local`, for example `Europe/Berlin`.
+   * The default is the time zone of the process. A host gives the same zone to its `Scheduler`.
+   */
+  readonly timeZone?: string | undefined;
 }
 
 /**
@@ -214,6 +224,7 @@ export function createScheduleModule(options: ScheduleModuleOptions = {}): Proce
   const settings: ScheduleSettings = {
     store: options.store ?? DEFAULT_SCHEDULE_SETTINGS.store,
     now: options.now ?? DEFAULT_SCHEDULE_SETTINGS.now,
+    ...(options.timeZone !== undefined ? { timeZone: checkTimeZone(options.timeZone) } : {}),
   };
   return defineModule("@procedures/schedule", scheduleProcedures(settings));
 }

package/src/procedures/schedule/add.ts

@@ -7,20 +7,25 @@
  */
 
 import { PROCEDURE_REGISTRY, type ProcedureContext } from "@procedures/client";
-import { formatTime, nextTime, parseCron } from "../../cron.js";
+import { checkTimeZone, formatTime, nextTime, parseCron, zoneFor } from "../../cron.js";
 import { ScheduleError } from "../../errors.js";
 import { DEFAULT_SCHEDULE_SETTINGS, findProgram, type ScheduleSettings } from "../../programs.js";
 import type { Schedule, ScheduleAddInput, ScheduleAddOutput, ScheduleView } from "../../types.js";
 
-/** The view of a schedule: with its next time after `now`. */
-export function viewOf(schedule: Schedule, now: number): ScheduleView {
-  let next: number | undefined;
+/**
+ * The view of a schedule: with its next time after `now`. The optional `local` is the IANA time
+ * zone of `local`. Without it, `local` is the time zone of the process.
+ */
+export function viewOf(schedule: Schedule, now: number, local?: string): ScheduleView {
+  let nextRunAt: string | null;
   try {
-    next = nextTime(parseCron(schedule.cron), now, schedule.timeZone);
+    const zone = zoneFor(schedule.timeZone, local);
+    const next = nextTime(parseCron(schedule.cron), now, zone);
+    nextRunAt = next === undefined ? null : formatTime(next, zone);
   } catch {
-    next = undefined;
+    nextRunAt = null;
   }
-  return { ...schedule, nextRunAt: next === undefined ? null : formatTime(next, schedule.timeZone) };
+  return { ...schedule, nextRunAt };
 }
 
 /** The capability of the caller to keep: its clearance and its permitted effects, without its deadline. */
@@ -38,9 +43,9 @@ function callerCapability(ctx: Pick<ProcedureContext, "capability"> | undefined)
  */
 export async function scheduleAdd(input: ScheduleAddInput, ctx?: Pick<ProcedureContext, "capability" | "registry">, settings: ScheduleSettings = DEFAULT_SCHEDULE_SETTINGS): Promise<ScheduleAddOutput> {
   const now = settings.now();
-  const timeZone = input.timeZone ?? "local";
   const cron = parseCron(input.cron);
-  if (nextTime(cron, now, timeZone) === undefined) {
+  const timeZone = checkTimeZone(input.timeZone ?? "local");
+  if (nextTime(cron, now, zoneFor(timeZone, settings.timeZone)) === undefined) {
     throw new ScheduleError("BAD_CRON", `The cron expression ${JSON.stringify(input.cron)} has no time in the next 9 years`);
   }
   await findProgram(ctx?.registry ?? PROCEDURE_REGISTRY, input.program);
@@ -62,5 +67,5 @@ export async function scheduleAdd(input: ScheduleAddInput, ctx?: Pick<ProcedureC
     throw new ScheduleError("EXISTS", `A schedule named ${id} exists: give replace: true, or another id`);
   }
   await settings.store.put(schedule);
-  return { schedule: viewOf(schedule, now) };
+  return { schedule: viewOf(schedule, now, settings.timeZone) };
 }

package/src/procedures/schedule/list.ts

@@ -15,6 +15,6 @@ export async function scheduleList(input: ScheduleListInput, settings: ScheduleS
   const now = settings.now();
   const schedules = await settings.store.list();
   return {
-    schedules: schedules.filter((schedule) => input.program === undefined || schedule.program === input.program).map((schedule) => viewOf(schedule, now)),
+    schedules: schedules.filter((schedule) => input.program === undefined || schedule.program === input.program).map((schedule) => viewOf(schedule, now, settings.timeZone)),
   };
 }

package/src/procedures/schedule/next.ts

@@ -5,7 +5,7 @@
  * from the time.
  */
 
-import { formatTime, nextTimes, parseCron } from "../../cron.js";
+import { checkTimeZone, formatTime, nextTimes, parseCron, zoneFor } from "../../cron.js";
 import { ScheduleError } from "../../errors.js";
 import { DEFAULT_SCHEDULE_SETTINGS, type ScheduleSettings } from "../../programs.js";
 import type { ScheduleNextInput, ScheduleNextOutput } from "../../types.js";
@@ -13,9 +13,9 @@ import type { ScheduleNextInput, ScheduleNextOutput } from "../../types.js";
 /**
  * The next times of a cron expression
  */
-export async function scheduleNext(input: ScheduleNextInput, settings: Pick<ScheduleSettings, "now"> = DEFAULT_SCHEDULE_SETTINGS): Promise<ScheduleNextOutput> {
-  const timeZone = input.timeZone ?? "local";
+export async function scheduleNext(input: ScheduleNextInput, settings: Pick<ScheduleSettings, "now" | "timeZone"> = DEFAULT_SCHEDULE_SETTINGS): Promise<ScheduleNextOutput> {
   const cron = parseCron(input.cron);
+  const timeZone = zoneFor(checkTimeZone(input.timeZone ?? "local"), settings.timeZone);
   let after = settings.now();
   if (input.after !== undefined) {
     after = Date.parse(input.after);

package/src/programs.ts

@@ -11,11 +11,13 @@ import { getProgramStore } from "@procedures/store";
 import { ScheduleError } from "./errors.js";
 import { defaultScheduleStore, type ScheduleStore } from "./store.js";
 
-/** What the procedures of a module use: the store and the wall clock. */
+/** What the procedures of a module use: the store, the wall clock and the time zone of `local`. */
 export interface ScheduleSettings {
   readonly store: ScheduleStore;
   /** The wall time, in milliseconds since 1970. */
   readonly now: () => number;
+  /** The IANA time zone of the schedules with the time zone `local`. Without it, `local` is the time zone of the process. */
+  readonly timeZone?: string | undefined;
 }
 
 /** The settings of the default module: `defaultScheduleStore` and `Date.now`. */

package/src/scheduler.ts

@@ -17,6 +17,8 @@
  *   missed during a run or a slow minute give one run, not one for each time.
  * - The timers use an injectable `Clock` (`after` and `now`), and the calendar uses an injectable
  *   wall clock (`now`, default `Date.now`). A test gives `fakeClock` of `@mark1russell7/service/testing`.
+ * - Each schedule runs in its time zone: `utc`, `local` or an IANA name. The option `timeZone`
+ *   gives the zone of `local`. The changes of daylight saving time follow Vixie cron (`cron.ts`).
  */
 
 import {
@@ -36,7 +38,7 @@ import {
   type InvokeOptions,
   type ProcedureRegistry,
 } from "@procedures/client";
-import { nextTime, parseCron } from "./cron.js";
+import { checkTimeZone, nextTime, parseCron, zoneFor } from "./cron.js";
 import { ScheduleError } from "./errors.js";
 import { findProgram } from "./programs.js";
 import { defaultScheduleStore, type ScheduleStore } from "./store.js";
@@ -70,6 +72,11 @@ export interface SchedulerOptions {
   readonly clock?: Clock | undefined;
   /** The wall time, in milliseconds since 1970. The default is `Date.now`. */
   readonly now?: (() => number) | undefined;
+  /**
+   * The IANA time zone of the schedules with the time zone `local`, for example `Europe/Berlin`.
+   * The default is the time zone of the process. The host gives the same zone to `createScheduleModule()`.
+   */
+  readonly timeZone?: string | undefined;
   /** The time limit of a run, in milliseconds. 0: no limit. The default is 10 minutes. */
   readonly runTimeoutMs?: number | undefined;
   /** This function gets each run and each skipped time. */
@@ -93,10 +100,10 @@ function errorInfo(error: unknown): { code?: string; message: string } {
   return typeof code === "string" ? { code, message } : { message };
 }
 
-/** The next time of a schedule after a time, or undefined for an expression that is not correct. */
-function nextOf(schedule: Schedule, after: number): number | undefined {
+/** The next time of a schedule after a time, or undefined for an expression or a time zone that is not correct. */
+function nextOf(schedule: Schedule, after: number, local: string | undefined): number | undefined {
   try {
-    return nextTime(parseCron(schedule.cron), after, schedule.timeZone);
+    return nextTime(parseCron(schedule.cron), after, zoneFor(schedule.timeZone, local));
   } catch {
     return undefined;
   }
@@ -109,6 +116,8 @@ export class Scheduler {
   private readonly clock: Clock;
   private readonly now: () => number;
   private readonly runTimeoutMs: number;
+  /** The IANA time zone of `local`, or undefined for the time zone of the process. */
+  private readonly timeZone: string | undefined;
   private readonly options: SchedulerOptions;
   private readonly due = new Map<string, Due>();
   private readonly runs = new Map<string, { promise: Promise<void>; controller: AbortController }>();
@@ -124,6 +133,7 @@ export class Scheduler {
     this.now = options.now ?? (() => Date.now());
     this.runTimeoutMs = options.runTimeoutMs ?? DEFAULT_RUN_TIMEOUT_MS;
     if (!(this.runTimeoutMs >= 0)) throw new TypeError("Scheduler: runTimeoutMs must be 0 or more");
+    this.timeZone = options.timeZone === undefined ? undefined : checkTimeZone(options.timeZone);
   }
 
   /** True after `start()` and before `stop()`. */
@@ -199,12 +209,12 @@ export class Scheduler {
       let due = this.due.get(schedule.id);
       if (due === undefined || due.version !== version) {
         // A new or a changed schedule: its first time is after it was added, and after the start
-        due = { version, at: nextOf(schedule, Math.max(schedule.createdAt, this.startedAt) - 1) };
+        due = { version, at: nextOf(schedule, Math.max(schedule.createdAt, this.startedAt) - 1, this.timeZone) };
         this.due.set(schedule.id, due);
       }
       if (due.at === undefined || due.at > now) continue;
       // The times that passed give one run: the next time comes after now
-      due.at = nextOf(schedule, now);
+      due.at = nextOf(schedule, now, this.timeZone);
       if (!this.launch(schedule, now)) void this.skip(schedule, now);
     }
   }