@procedures/schedule 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @procedures/schedule
 
+## 0.5.0
+
+### Minor Changes
+
+- 6a98b23: IANA time zones, and a lock file for `FileScheduleStore` across processes:
+  
+  - `schedule.add`, `schedule.next` and the stored schedules take a time zone `utc`, `local` or an IANA name, for example `Europe/Berlin`. `Intl` examines the name and gives the offsets: the package has no time zone database. An unknown name gives the new error `BAD_TIME_ZONE`.
+  - `createScheduleModule({ timeZone })` and `new Scheduler({ timeZone })` give the IANA zone of `local`. The default is the time zone of the process.
+  - The changes of daylight saving time follow Vixie cron. A fixed time (no `*` at the start of the minute and hour fields) in the hour that does not exist runs once, at the first minute after the change. A fixed time in the hour that occurs twice runs once, at its first occurrence. An expression with `*` in the minute or hour field follows the clock.
+  - The zone `local` uses these rules too. Before, a time in the skipped hour did not run, and a time in the repeated hour could run two times.
+  - `FileScheduleStore` holds a lock file (`<path>.lock`, made with the flag `wx`) for each read-change-write. Two processes on one file thus lose no write. A lock older than `staleMs` (default 30 seconds) is stale, and the next store takes it over. A store that waits for twice `staleMs` gives the new error `LOCKED`.
+  - The new exports: `checkTimeZone`, `hostTimeZone`, `zoneFor`, `DEFAULT_LOCK_STALE_MS` and `FileScheduleStoreOptions`. `CronExpression` has the new field `fixedTime`.
+
+### Patch Changes
+
+- 0f75644: The dependencies go to `@mark1russell7/algebra` `^0.7.0` and `@mark1russell7/service` `^0.4.1`. A host that uses algebra 0.7.0 gets one copy of it. Algebra 0.7.0 only adds to 0.6.0.
+- Updated dependencies [0f75644]
+- Updated dependencies [09e5566]
+- Updated dependencies [ab77f75]
+- Updated dependencies [a47bee6]
+- Updated dependencies [89481b0]
+- Updated dependencies [bc74091]
+- Updated dependencies [bc74091]
+  - @procedures/client@0.5.0
+  - @procedures/store@0.5.0
+
 ## 0.4.0
 
 ### Patch Changes

package/README.md

@@ -22,8 +22,10 @@ A cron for stored programs. The procedures add, list and remove schedules. A `Sc
 - `schedule.next` reads no store. Its output comes from its input and the time.
 - A store can be a file, so the procedures that read or write the schedules declare `fs` too.
 
+- The time zone of `schedule.add` and `schedule.next` is `local` by default. It can be `utc` or an IANA name, for example `Europe/Berlin` (refer to [Time zones](#time-zones)).
+
 ```ts
-await client.call(["schedule", "add"], { cron: "0 9 * * mon-fri", program: "reports.daily", input: { team: "core" } });
+await client.call(["schedule", "add"], { cron: "0 9 * * mon-fri", program: "reports.daily", input: { team: "core" }, timeZone: "Europe/Berlin" });
 await client.call(["schedule", "next"], { cron: "*/15 * * * *", count: 3 });
 ```
 
@@ -60,20 +62,40 @@ await scheduler.start();
 | `policy` | The policy of the host, from `hostPolicy()`. |
 | `clock` | The clock of the timers and of the durations. The default is `realClock`. |
 | `now` | The wall time in milliseconds. The default is `Date.now`. |
+| `timeZone` | The IANA time zone of the schedules with the time zone `local`. The default is the time zone of the process. |
 | `runTimeoutMs` | The time limit of a run. 0 sets no limit. |
 | `onRun`, `onError` | Functions that get each run and each error of the scheduler. |
 
 A test gives `fakeClock` of `@mark1russell7/service/testing`, and a wall time from it: `now: () => start + clock.now()`. It gives the same `now` to `createScheduleModule()`.
 
+A host gives the same `timeZone` to `createScheduleModule()` and to its `Scheduler`. Then `nextRunAt` of the procedures and the runs of the scheduler agree.
+
 ## The stores
 
 - `MemoryScheduleStore` keeps the schedules while the process runs. The default module uses `defaultScheduleStore`, one store in memory for the process.
-- `FileScheduleStore` keeps them in a JSON file. A write goes through a temporary file and a rename. The store is for one process.
+- `FileScheduleStore` keeps them in a JSON file. A write goes through a temporary file and a rename, so a reader does not see a part of a write.
 - `update()` changes one schedule in one step. The record of a run thus does not lose a change of `schedule.add`, and it does not touch a schedule that replaced the old one.
 
+### Two processes on one file
+
+Two processes can use the same `FileScheduleStore` file, and they lose no write. Each change holds a lock file next to the store file: `schedules.json.lock`.
+
+1. The store makes the lock file with the flag `wx`. Only one process can make it. The other processes wait and try again.
+2. Under the lock, the store reads the file again, makes its change, writes the file and removes the lock. An error also removes the lock.
+3. A lock file older than `staleMs` is stale: its process stopped. The next store takes it over. The default of `staleMs` is 30 seconds.
+4. A store that waits for twice `staleMs` gives up with the error `LOCKED`.
+
+```ts
+const store = new FileScheduleStore("schedules.json", { staleMs: 30_000 });
+```
+
+- To take over a stale lock, a store makes a second lock file (`.lock.break`) with `wx`. It examines the age of the lock again under it, and then it removes the stale lock. Two stores thus cannot both remove the lock.
+- The lock file holds a token of its store. A store removes only its own lock, so a slow store does not remove the lock of the store that took it over.
+- The lock uses only `node:fs`, with no dependency. A store on a network file system gets the guarantees of the flag `wx` on that system.
+
 ## Cron expressions
 
-This package parses cron itself. The format is small, and a cron library brings a time zone database or another format that this package does not need.
+This package parses cron itself. The format is small, and `Intl` gives the offsets of the time zones. A cron library brings a time zone database or another format that this package does not need.
 
 | Field | Values |
 |---|---|
@@ -86,10 +108,35 @@ This package parses cron itself. The format is small, and a cron library brings
 - Each field takes `*`, a number, a range `a-b`, a step after `/` (`*/15`, `a-b/n`, `a/n`), and lists of these with commas.
 - The names `@yearly`, `@annually`, `@monthly`, `@weekly`, `@daily`, `@midnight` and `@hourly` replace the 5 fields.
 - When the two day fields have a limit, a day matches when one of the two matches, as in Vixie cron. A field that starts with `*` has no limit.
-- The time zone is `local` (the time of the host) by default, or `utc`.
-- In local time, a time that the change to summer time skips gives no run. A time that the change back repeats can give two runs.
 - An expression without a time in the next 9 years is an error of `schedule.add`.
 
+## Time zones
+
+The time zone of a schedule is `local` by default. It can also be `utc` or an IANA name, for example `Europe/Berlin`, `Australia/Adelaide` or `Asia/Kolkata`.
+
+- `local` is the time zone of the process. The option `timeZone` of `createScheduleModule()` and of `Scheduler` gives another zone to `local`.
+- `Intl.DateTimeFormat` examines a name and gives the offsets of the zone. The package has no time zone database.
+- A name that `Intl` does not know gives the error `BAD_TIME_ZONE`. An offset, for example `+05:30`, is not an IANA name.
+- A name that differs from the name of `Intl` only in the case gets the case of `Intl`: `europe/berlin` becomes `Europe/Berlin`.
+- `nextRunAt` and the times of `schedule.next` have the offset of the zone at that time: `2026-10-17T09:00:00+02:00`. An offset of 0 gives `Z`.
+
+### The changes of daylight saving time
+
+The changes of daylight saving time follow Vixie cron. The rules depend on the minute field and the hour field of the expression.
+
+A fixed time has no `*` at the start of its minute field and of its hour field, for example `30 2 * * *`:
+
+- A time in the hour that does not exist runs once, at the first minute after the change. In `Europe/Berlin` on 2026-03-29, `30 2 * * *` runs at 03:00 CEST.
+- Two times of one expression in that hour give one run.
+- A time in the hour that occurs twice runs once, at its first occurrence. In `Europe/Berlin` on 2026-10-25, `30 2 * * *` runs at 02:30 CEST, and not at 02:30 CET.
+
+An expression with `*` at the start of its minute field or of its hour field follows the clock, for example `0 * * * *` or `*/15 * * * *`:
+
+- A time in the hour that does not exist has no run. The clock does not show it.
+- A time in the hour that occurs twice runs at the two occurrences. So `*/15 * * * *` runs each 15 minutes of real time across the two changes.
+
+The same rules apply to the zones with a change of 30 minutes, for example `Australia/Lord_Howe`.
+
 ## MCP
 
 `schedule.next` and `schedule.list` change nothing, and they are good tools. `schedule.add` makes the host start a program later, at each time, so a host gives it to Claude only on purpose. `schedule.remove` stops the runs that the owner wants.
@@ -97,3 +144,6 @@ This package parses cron itself. The format is small, and a cron library brings
 ## Tests
 
 `pnpm --filter @procedures/schedule test` examines the procedures, the stores and the cron expressions. The tests of the scheduler use `fakeClock`, so each time is exact and no test waits.
+
+- The tests of the time zones use fixed dates across the two changes of `Europe/Berlin` and `Australia/Adelaide`, a zone with a half-hour offset.
+- The tests of the lock start two child processes. Each one writes 50 schedules to one file, and the file then holds all 100. The Windows job of the nightly workflow runs them too.