@owlmeans/queue 0.1.18-rc.22 → 0.1.18-rc.23

package/README.md

@@ -6,8 +6,8 @@ than about five seconds, accepted work must survive a process restart, or the wo
 against a third party (payment capture, provider sync, bulk mail, report generation, model
 pipelines). A request that finishes in under about two seconds and makes no external call should
 not queue: do it inline. Check for a smaller fix first, such as an index, a batch write or a cached
-aggregate. The framework has no scheduler, so recurring work is triggered by a platform cron that
-calls an entrypoint or enqueues a job.
+aggregate. Recurring work is a declared schedule: the broker produces a job on an interval or a
+cron pattern and a registered processor runs it.
 
 This package is contracts only and carries no broker code. A driver implements them
 (`@owlmeans/redis-queue` does, over BullMQ). Depend on this package from a shared contract package,
@@ -16,7 +16,7 @@ and on the driver only where the application wires itself up.
 ## Installation
 
 ```bash
-bun add @owlmeans/queue@^0.1.18-rc.22
+bun add @owlmeans/queue@^0.1.18-rc.23
 ```
 
 ## Concepts
@@ -36,6 +36,9 @@ bun add @owlmeans/queue@^0.1.18-rc.22
   a `JobContext`. It must be safe to run twice and must `touch()` in long loops.
 - **Single-flight id**: a `JobOptions.id` derived from what the job is about (`develop:<storyId>`).
   A duplicate enqueue then returns the existing job instead of a second one.
+- **Schedule**: `declareSchedule(cfg, { id, queue, name, every | pattern, … })` in the shared config.
+  Every process that listens to the queue reconciles the broker with the declared schedules when its
+  worker starts; each run is an ordinary job, and `JobContext.scheduled` names the schedule.
 
 ## Usage
 
@@ -155,6 +158,41 @@ await context.jobs(APP_OPS).flow({
 })
 ```
 
+### Recurring jobs
+
+```ts
+import { declareQueue, declareSchedule } from '@owlmeans/queue'
+
+// Shared config: the queue first, then its schedules.
+declareQueue(cfg, APP_MAINTENANCE, ['app:maintenance:reconcile', 'app:maintenance:purge'], {
+  worker: { concurrency: 1, lockDuration: 60_000 }
+})
+declareSchedule(cfg, {
+  id: 'app-nightly-reconcile', queue: APP_MAINTENANCE, name: 'app:maintenance:reconcile',
+  pattern: '17 3 * * *', tz: 'UTC', data: {},
+})
+declareSchedule(cfg, {
+  id: 'app-purge', queue: APP_MAINTENANCE, name: 'app:maintenance:purge', every: 15 * 60_000,
+})
+```
+
+The process that `listenQueues(cfg, APP_MAINTENANCE)` registers the processors; nothing else is
+wired. A scheduled run carries no caller and no credentials, so it goes to a processor, never to a
+guarded entrypoint:
+
+```ts
+worker.process(APP_MAINTENANCE, 'app:maintenance:reconcile', async job => {
+  for await (const page of organizations()) {
+    await job.touch()
+    await reconcile(page)              // safe to run twice: a restart re-runs the whole sweep
+  }
+  return { scheduled: job.scheduled }  // 'app-nightly-reconcile'
+})
+```
+
+Renaming a schedule id removes the old scheduler and creates a new one; deleting a declaration
+removes its scheduler at the next worker start.
+
 ### Jobs are records
 
 ```ts
@@ -197,6 +235,9 @@ not the job, so read the job back to learn what became of it.
 | `declareQueue(cfg, name, jobs, opts?)` | function | Declare a queue and the job names it accepts; re-declaring replaces |
 | `listenQueues(cfg, ...names)` | function | Name the queues this process consumes |
 | `queueOf(cfg, name)`, `queueOfJob(cfg, job)`, `isListening(cfg, name)` | function | Read declarations back; `queueOf` throws `UnknownQueue` |
+| `declareSchedule(cfg, schedule)` | function | Declare a recurring job after checking it; re-declaring an id replaces |
+| `schedulesOf(cfg, queue?)` | function | The declared schedules, of one queue when named |
+| `assertSchedule(cfg, schedule)`, `assertSchedules(cfg)` | function | Check one schedule, or every declared one plus duplicate ids |
 | `enqueueProtocol(ctx, protocol, request, options?)` | function | Enqueue a QUEUE protocol with `JobOptions`, typed by the protocol |
 | `waitForProtocol(ctx, protocol, job, { timeout }?)` | function | Wait for that job and unwrap the typed reply |
 | `queueJobOf(request)` | function | `QueueJobMeta` of the broker job behind a handler's request, or `null` |
@@ -204,11 +245,11 @@ not the job, so read the job back to learn what became of it.
 | `queueWorkerMiddleware(alias?)` | function | Start the worker at the Ready stage, only in a process that listens |
 | `handleJob(ctx, job)`, `entrypointProcessor(ctx)`, `servedJobs(ctx)` | function | The bridge a driver dispatches entrypoint jobs through |
 | `requestOf(envelope)`, `assertFresh(envelope, ttl?)` | function | Rebuild a request from an envelope; enforce `envelopeTtl` |
-| `QueueConfig`, `QueueDeclaration`, `QueueWorkerOptions`, `JobOptions` | type | Configuration shapes |
+| `QueueConfig`, `QueueDeclaration`, `QueueWorkerOptions`, `JobOptions`, `ScheduleDeclaration` | type | Configuration shapes |
 | `QueueResource<D, R>` | type | A queue as a resource, plus `queue`, `wait`, `flow`, `counts`, `close` |
 | `JobRecord<D, R>`, `JobEvent<R>`, `FlowSpec<D>` | type | A job as a record, a lifecycle event, a graph node |
 | `QueueWorkerService` | type | `process`, `start`, `stop`, `listening`, `hooks` |
-| `JobContext<D>`, `JobProcessor<D, R>` | type | What a processor receives; the processor signature |
+| `JobContext<D>`, `JobProcessor<D, R>` | type | What a processor receives (`scheduled` names the schedule of a scheduled run); the processor signature |
 | `QueueHooks` | type | `wrapHandler`, `onJobResult`, `onJobStalled`, `onJobDead` |
 | `QueueJobMeta`, `JobEnvelope`, `JobReply<T>` | type | Broker identity for a handler, the call envelope, the reply shape |
 | `QueueAppend`, `QueueDriver` | type | The `ctx.jobs(queue?)` mixin a driver installs; what a driver supplies |
@@ -216,7 +257,7 @@ not the job, so read the job back to learn what became of it.
 | `JobState`, `JobEventType` | enum | Job lifecycle states and event types |
 | `isSettled(state?)` | function | Whether a state is final |
 | `DEFAULT_ALIAS`, `DEFAULT_JOB_TIMEOUT`, `DEFAULT_ATTEMPTS` | const | `'queue'`, `60_000` ms, `1` |
-| `QueueError`, `QueueTimeout`, `UnknownJob`, `UnknownJobName`, `UnknownQueue`, `QueueNotListening`, `JobNotServed`, `EnvelopeExpired` | class | Error family |
+| `QueueError`, `QueueTimeout`, `UnknownJob`, `UnknownJobName`, `UnknownQueue`, `QueueNotListening`, `JobNotServed`, `EnvelopeExpired`, `ScheduleMisdeclared` | class | Error family |
 
 ## Common pitfalls
 
@@ -233,7 +274,13 @@ not the job, so read the job back to learn what became of it.
 - **Long loops without `touch()`**, or processors that are not safe to run twice.
 - **Throwing from a child for a domain failure.** Return `{ ok: false, error }` instead.
 - **Equal child ids across queues in one flow.** `children()` is keyed by bare id and collapses them.
-- **A self-re-enqueueing job as a cron.** Use a platform `CronJob`. `delay` defers a single job once.
+- **A self-re-enqueueing job as a cron.** Declare a schedule. `delay` defers a single job once.
+- **A schedule on a queue nothing consumes.** Only a listening worker creates the scheduler, and the
+  broker produces each next run when the previous one starts.
+- **Loading different schedule lists in two processes that listen to one queue.** Each start removes
+  the schedules its own list does not name.
+- **Declaring a schedule before its queue.** `declareSchedule` checks the queue and the job name and
+  throws `UnknownQueue` / `UnknownJobName`.
 - **Calling `ctx.jobs()` with no name once a second queue exists.** It throws `UnknownQueue`.
 
 ## Related packages
@@ -253,7 +300,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.27
+npx @owlmeans/agent-skills@^0.1.18-rc.28
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,10 +1,17 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/queue",
-  "version": "0.1.18-rc.22",
-  "generatedAt": "2026-09-15T13:19:14.375Z",
+  "version": "0.1.18-rc.23",
+  "generatedAt": "2026-09-17T08:16:11.196Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
+    {
+      "kind": "skill",
+      "name": "scheduled-jobs",
+      "category": "multi-package",
+      "file": "skills/scheduled-jobs/SKILL.md",
+      "canonicalPath": ".agents/skills/scheduled-jobs/SKILL.md"
+    },
     {
       "kind": "skill",
       "name": "queue",

package/agent-meta/skills/queue/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: queue
-description: How to use @owlmeans/queue — protocol-object enqueue/wait, job queues as resources, QUEUE declarations, producer/consumer split, single-flight job ids, lifecycle hooks, and processor rules. Auto-invoked when importing queue types or declaring a job protocol.
+description: How to use @owlmeans/queue — protocol-object enqueue/wait, job queues as resources, QUEUE declarations, producer/consumer split, single-flight job ids, recurring schedules, lifecycle hooks, and processor rules. Auto-invoked when importing queue types, declaring a job protocol, or declaring a schedule.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/queue
 
 **Layer:** Infra
-**Install:** `"@owlmeans/queue": "^0.1.18-rc.22"` in `dependencies`
+**Install:** `"@owlmeans/queue": "^0.1.18-rc.23"` in `dependencies`
 
 Contracts only. It carries no broker code — a driver package (`@owlmeans/redis-queue`) implements
 them. Depend on this one from a shared contract package; depend on the driver only where the
@@ -142,6 +142,43 @@ run twice — skip work already recorded, delete the rows a previous attempt cre
 regenerating over a baseline. Decide this per job and say so in a comment; there is no way to make
 it automatic.
 
+## Recurring jobs
+
+A recurring sweep is a SCHEDULE on a queue, run by a registered processor:
+
+```typescript
+declareQueue(cfg, APP_MAINTENANCE, ['app:maintenance:reconcile'], {
+  worker: { concurrency: 1, lockDuration: 60_000 }
+})
+declareSchedule(cfg, {
+  id: 'app-nightly-reconcile', queue: APP_MAINTENANCE, name: 'app:maintenance:reconcile',
+  pattern: '17 3 * * *', tz: 'UTC', data: {},
+})
+```
+
+- **Declare it in the shared package, after its queue.** `declareSchedule` runs `assertSchedule`
+  first: the queue must be declared (`UnknownQueue`) and must accept the job name
+  (`UnknownJobName`), exactly one of `every` (a positive integer of milliseconds) and `pattern`
+  (cron), `tz` and `immediately` only with a pattern, never `immediately` with `startDate`, and
+  `opts.id` / `opts.delay` refused — the broker names and places every run
+  (`ScheduleMisdeclared`, message `<id>:<reason>`). Re-declaring an id replaces it.
+- **The id is the identity.** Changing any other field updates the schedule in place; renaming the
+  id is one schedule removed and another created.
+- **Every process that listens to the queue reconciles it at worker start** — the driver creates
+  and updates what is declared and removes the schedules it owns that are not. Two listeners of one
+  queue must therefore load the same schedule list, which is why it lives in the shared package.
+  A producer creates nothing.
+- **A scheduled run is a processor job, never a guarded entrypoint.** Nobody's credentials travel
+  with it. `job.scheduled` carries the schedule id; it is absent on a job enqueued any other way.
+- **It needs a consumer.** The broker produces the next run when the previous one starts
+  processing, so a schedule on a queue nothing consumes stops producing.
+- **The processor obeys every rule above** — `touch()` through the sweep, and safe to run twice,
+  because a restart mid-sweep re-runs it from the start.
+
+`schedulesOf(cfg, queue?)` reads the declarations back; `assertSchedules(cfg)` checks all of them,
+including one written into `cfg.queue.schedules` directly, and refuses a duplicate id.
+Which recurring work belongs on a schedule at all is `scheduled-jobs`.
+
 ## A queued call is still a guarded call
 
 `handleJob` rebuilds the request from the envelope and runs the entrypoint as the HTTP boundary
@@ -183,20 +220,21 @@ listens to, grouped by queue, which is what a driver binds.
 | `enqueueProtocol` / `waitForProtocol` | Typed protocol-object enqueue and result wait; validates protocol kind and queue configuration. |
 | `queueJobOf(request)` / `QueueJobMeta` | Explicit broker identity boundary for a protocol handler, including `touch()` for long work. |
 | `declareQueue` / `listenQueues` | Configuration — what exists, and what this process consumes |
+| `declareSchedule` / `schedulesOf` / `assertSchedule` / `assertSchedules` | Recurring jobs — declare, read back, check |
 | `queueOf` / `queueOfJob` / `isListening` | Reading it back; `queueOf` throws `UnknownQueue` |
-| `QueueConfig` / `QueueDeclaration` / `QueueWorkerOptions` / `JobOptions` | The configuration shapes |
+| `QueueConfig` / `QueueDeclaration` / `QueueWorkerOptions` / `JobOptions` / `ScheduleDeclaration` | The configuration shapes |
 | `QueueResource<D, R>` | A queue addressed as a resource, plus `wait` / `flow` / `counts` / `close` |
 | `JobRecord<D, R>` / `JobState` / `isSettled` / `JobEvent` / `JobEventType` | The record shape and lifecycle |
 | `FlowSpec<D>` | A graph node — `name`, optional `queue`, `data`, `opts`, `children` |
 | `QueueWorkerService` | `process(queue, name, fn)`, `start`, `stop`, `listening`, `hooks` |
-| `JobContext<D>` | What a processor gets: `id`, `name`, `queue`, `attempt`, `data`, `signal`, `touch`, `progress`, `children`, `failedChildren` |
+| `JobContext<D>` | What a processor gets: `id`, `name`, `queue`, `attempt`, `data`, `signal`, `scheduled?`, `touch`, `progress`, `children`, `failedChildren` |
 | `QueueHooks` | `wrapHandler`, `onJobResult`, `onJobStalled`, `onJobDead` — the compensation seam |
 | `QueueAppend` | The `ctx.jobs(queue?)` mixin a driver installs; `QueueDriver` is what a driver supplies |
 | `appendQueueTransport` / `makeQueueTransport` | Binds the QUEUE protocol so `call()` routes through the broker |
 | `queueWorkerMiddleware` | Starts the worker at Ready stage |
 | `handleJob` / `servedJobs` / `entrypointProcessor` | The bridge a driver dispatches through |
 | `requestOf` / `assertFresh` / `JobEnvelope` / `JobReply` | The envelope, and rebuilding a request from it |
-| Errors | `QueueError`, `QueueTimeout`, `UnknownJob`, `UnknownJobName`, `UnknownQueue`, `QueueNotListening`, `JobNotServed`, `EnvelopeExpired` |
+| Errors | `QueueError`, `QueueTimeout`, `UnknownJob`, `UnknownJobName`, `UnknownQueue`, `QueueNotListening`, `JobNotServed`, `EnvelopeExpired`, `ScheduleMisdeclared` |
 | Constants | `DEFAULT_ALIAS` (`queue`), `DEFAULT_JOB_TIMEOUT` (60 000 ms), `DEFAULT_ATTEMPTS` (1) |
 
 ## Depends On
@@ -210,7 +248,8 @@ listens to, grouped by queue, which is what a driver binds.
 
 ## Related
 
-- `redis-queue` — the BullMQ driver; integration tests for queue behaviour live there
+- `redis-queue` — the BullMQ driver; how schedules are reconciled; integration tests live there
+- `scheduled-jobs` — when recurring work is a schedule, and how to write the sweep it runs
 - `server-job` / `client-job` — exposing a queue's jobs to an application's UI (list, cancel,
   progress over a socket), without touching the contracts here
 - `entrypoint` — protocol declarations, bindings, and the transport lookup

package/agent-meta/skills/scheduled-jobs/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: scheduled-jobs
+description: Recurring background work on OwlMeans queues — declareSchedule in @owlmeans/queue, reconciled into BullMQ job schedulers by @owlmeans/redis-queue when a listening worker starts. Covers interval vs cron schedules, the processor a sweep runs, overlap and restart semantics, renaming and removing a schedule, multi-replica and rolling-deploy behaviour, and testing. Use when adding a nightly or periodic job, replacing a platform CronJob or a setInterval with a schedule, or diagnosing a schedule that does not run.
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Scheduled jobs
+
+**Layer:** Infra · **Packages:** `@owlmeans/queue` (lead — the declaration), `@owlmeans/redis-queue`
+(the reconciliation)
+
+A schedule is a declaration that makes the broker produce an ordinary job on an interval or a cron
+pattern. A worker that consumes the queue runs it with a processor. There is no second scheduler
+process, no cron table and no timer in application code.
+
+## When a schedule is the answer
+
+| Situation | Answer |
+|---|---|
+| Periodic sweep, reconciliation, digest, retention delete, rollup | A schedule on a queue a worker consumes |
+| "Remind this user in 20 minutes" | `JobOptions.delay` on one job — a schedule is not per record |
+| A far-future or cancellable per-record deadline | A row with a due date, swept by one schedule |
+| A deployment that runs no worker | A platform `CronJob` calling a guarded entrypoint |
+| A `setInterval` inside a request handler or a long-lived service | A schedule — the interval dies with the process and runs once per replica |
+
+Whether the work belongs on a queue at all is `resource-choice`.
+
+## Declaring
+
+In the SHARED package every process loads, after the queue:
+
+```typescript
+declareQueue(cfg, APP_MAINTENANCE, ['app:maintenance:reconcile', 'app:maintenance:purge'], {
+  worker: { concurrency: 1, lockDuration: 60_000 }
+})
+declareSchedule(cfg, {
+  id: 'app-nightly-reconcile', queue: APP_MAINTENANCE, name: 'app:maintenance:reconcile',
+  pattern: '17 3 * * *', tz: 'UTC', data: {},
+})
+declareSchedule(cfg, {
+  id: 'app-purge-expired', queue: APP_MAINTENANCE, name: 'app:maintenance:purge', every: 15 * 60_000,
+})
+```
+
+And only in the process that runs them: `listenQueues(cfg, APP_MAINTENANCE)` plus a processor per
+job name, registered while the context is wired.
+
+- **`pattern` for the calendar, `every` for a frequency.** A nightly job is a pattern with an
+  explicit `tz`; "every quarter hour, whenever" is `every`. Pick an odd minute (`17 3 * * *`) so
+  many applications' sweeps do not stampede one Redis at the top of the hour.
+- **`every` runs at once** when the scheduler is created (unless `startDate` says otherwise); a
+  pattern waits for its next match unless `immediately: true`, which fires only when the scheduler
+  is created or its declaration changes — never on an unchanged restart.
+- **The id is permanent.** It is the scheduler's identity in the broker: any other field changes in
+  place, a renamed id is a removed schedule plus a new one. Prefix it with the application
+  (`app-…`) — ids share one namespace per queue.
+- **Declaration errors surface at boot.** `declareSchedule` throws `UnknownQueue`,
+  `UnknownJobName` or `ScheduleMisdeclared` (`<id>:<reason>`) rather than letting the broker fail
+  on every tick.
+- **`opts` sets retries and retention for every run; `id` and `delay` are refused** — the broker
+  names each run and places it on the schedule.
+
+## Writing the processor
+
+```typescript
+worker.process<Record<string, never>, SweepReport>(APP_MAINTENANCE, 'app:maintenance:reconcile',
+  async job => {
+    const report = { scanned: 0, repaired: 0, failed: 0 }
+    for await (const page of organizations({ size: 200 })) {
+      await job.touch()
+      for (const organization of page) {
+        try {
+          report.repaired += await reconcile(organization.entityId) ? 1 : 0
+        } catch (error) {
+          report.failed++
+          console.error(`reconcile ${organization.entityId}`, error)
+        }
+        report.scanned++
+      }
+    }
+    console.info(`[maintenance] ${job.scheduled}`, report)
+    return report
+  })
+```
+
+- **A scheduled run has no caller.** No credentials, no entity, no request: it is a processor job,
+  never a guarded entrypoint. A step that must go through another service's guard calls that
+  service with service credentials.
+- **Idempotent per item, not per run.** A worker rolled out mid-sweep, a stalled lock or a manual
+  re-run repeats the whole sweep; each item's repair must be a no-op the second time.
+- **One item's failure is logged and counted, never thrown.** A thrown sweep is retried from the
+  start, or dropped after its attempts — either way the other items pay for one bad record.
+- **`touch()` per page.** A sweep over every organization outlives `lockDuration` easily; silence
+  hands the job to another worker while this one is still going.
+- **Return a small report.** It lands on the completed job, where an operator reads it.
+
+## Overlap, replicas and deploys
+
+- **One job per tick, whatever the replica count.** The broker produces one job; one worker takes
+  it. Several replicas listening to the queue do not multiply runs.
+- **Runs can overlap on a concurrent queue.** The next run is produced when the previous one
+  starts, so a run that outlasts the interval meets its successor. Put sweeps on their own queue
+  with `concurrency: 1`, apart from interactive lanes.
+- **A schedule needs a consumer.** Only a listening worker creates the scheduler, and the next run
+  is produced only when the previous one starts processing. A queue nothing consumes stops.
+- **Every listener reconciles at start, from its own configuration.** It creates or updates what it
+  declares and removes the schedules it owns (`owlmeans:` scheduler ids) that it does not. Every
+  process listening to one queue must load the same schedule list; during a rolling deploy the
+  newest process to start wins, and the old pods leave the broker alone after their own start.
+- **Removing a schedule is deleting its declaration.** The next worker start removes the scheduler.
+  So is a declaration whose job name the queue no longer accepts, or whose `endDate` has passed.
+- **Scheduling never costs consumption.** A refused declaration or a broker failure while
+  reconciling is logged and skipped; the worker keeps consuming. Look for
+  `redis-queue-schedules:<queue>` in the worker's log when a schedule does not appear.
+
+## Diagnosing "it never ran"
+
+1. Is some process listening to the queue (`listenQueues`) and is its worker up?
+2. Did that process's start log a `redis-queue-schedules:<queue>` refusal?
+3. Does `new Queue(queue, { connection, prefix }).getJobSchedulers()` list `owlmeans:<id>` with the
+   expected `pattern`/`every`, `tz` and `next`?
+4. Is a processor registered for the job name? A run without one fails once as `UnknownJobName`
+   and shows in the failed state.
+5. Is a previous run still active on a `concurrency: 1` queue?
+
+## Testing
+
+- **The declaration** is category A in the application's own shared package: build the config,
+  `assertSchedules(cfg)`, and pin ids and job names against the queue declaration.
+- **The processor** is tested as a function over a fake `JobContext` or a real context — it is
+  ordinary code with a `touch`.
+- **Against a broker** (Redis-gated): the worker's Ready-stage start is not awaited by
+  `context.init()`, so poll the broker (`getJobSchedulers`) or wait for the first run instead of
+  asserting straight after boot. A queue's schedulers go with `obliterate()`.
+
+## External docs
+
+- https://docs.bullmq.io/guide/job-schedulers — `upsertJobScheduler(id, { every | pattern, tz,
+  startDate, endDate, limit, immediately }, { name, data, opts })` creates or updates one scheduler
+  per id and replaces its pending run; `getJobSchedulers()` / `removeJobScheduler(id)`. The next job
+  is added when the previous one starts processing, so a worker must be consuming. Produced jobs
+  carry `repeatJobKey` = the scheduler id.
+
+## Related
+
+- `queue` — `declareSchedule`, `JobContext.scheduled`, processor rules
+- `redis-queue` — `syncSchedules`, the `owlmeans:` ownership prefix, the reconciliation rules
+- `resource-choice` — whether recurring work belongs on a queue at all

package/build/config.d.ts

@@ -1,4 +1,4 @@
-import type { Config, JobOptions, QueueDeclaration, QueueWorkerOptions } from './types.js';
+import type { Config, JobOptions, QueueDeclaration, QueueWorkerOptions, ScheduleDeclaration } from './types.js';
 /**
  * Add a queue to the shared configuration. Every process in the monorepo loads the same
  * declarations — a producer needs them to know a queue exists and what it accepts, a worker needs
@@ -19,4 +19,32 @@ export declare const listenQueues: <C extends Config>(cfg: C, ...names: string[]
 export declare const queueOf: <C extends Config>(cfg: C, name: string) => QueueDeclaration;
 export declare const queueOfJob: <C extends Config>(cfg: C, job: string) => QueueDeclaration | undefined;
 export declare const isListening: <C extends Config>(cfg: C, name: string) => boolean;
+/**
+ * Whether the broker can carry a schedule out as written. Nothing is recorded or changed.
+ *
+ * @throws {ScheduleMisdeclared} naming the schedule id and the reason.
+ * @throws {UnknownQueue} when the schedule's queue is not declared.
+ * @throws {UnknownJobName} when that queue does not accept the schedule's job name — a scheduled
+ * run of a name nothing declares would fail on every tick instead of once, at declaration.
+ */
+export declare const assertSchedule: <C extends Config>(cfg: C, schedule: ScheduleDeclaration) => void;
+/**
+ * Add a recurring job to the shared configuration. Declare the queue first — a schedule is checked
+ * against it here. Declaring an id twice replaces, like `declareQueue`.
+ *
+ * Declaring is all this does: the driver creates, updates and removes the broker's schedulers when
+ * a worker that listens to the queue starts.
+ *
+ * @throws {ScheduleMisdeclared} / {UnknownQueue} / {UnknownJobName} — see `assertSchedule`.
+ */
+export declare const declareSchedule: <C extends Config>(cfg: C, schedule: ScheduleDeclaration) => C;
+/** The declared schedules, of one queue when it is named. */
+export declare const schedulesOf: <C extends Config>(cfg: C, queue?: string) => ScheduleDeclaration[];
+/**
+ * Check every declared schedule, including any written into the configuration without
+ * `declareSchedule`, and refuse two under one id.
+ *
+ * @throws {ScheduleMisdeclared} / {UnknownQueue} / {UnknownJobName} for the first one that fails.
+ */
+export declare const assertSchedules: <C extends Config>(cfg: C) => void;
 //# sourceMappingURL=config.d.ts.map

package/build/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAG1F;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,MAAM,OACtC,CAAC,QAAQ,MAAM,QAAQ,MAAM,EAAE,SAAS;IAAE,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,EAAE,UAAU,CAAA;CAAE,KAClG,CAcF,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,MAAM,OAAO,CAAC,YAAY,MAAM,EAAE,KAAG,CAM3E,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,SAAS,MAAM,OAAO,CAAC,QAAQ,MAAM,KAAG,gBAQhE,CAAA;AAED,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS,MAAM,OAAO,CAAC,OAAO,MAAM,KAAG,gBAAgB,GAAG,SACpB,CAAA;AAElE,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,MAAM,OAAO,CAAC,QAAQ,MAAM,KAAG,OACzB,CAAA"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,MAAM,EAAE,UAAU,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,mBAAmB,EAC9E,MAAM,YAAY,CAAA;AAGnB;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,MAAM,OACtC,CAAC,QAAQ,MAAM,QAAQ,MAAM,EAAE,SAAS;IAAE,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,EAAE,UAAU,CAAA;CAAE,KAClG,CAcF,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,MAAM,OAAO,CAAC,YAAY,MAAM,EAAE,KAAG,CAM3E,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,SAAS,MAAM,OAAO,CAAC,QAAQ,MAAM,KAAG,gBAQhE,CAAA;AAED,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS,MAAM,OAAO,CAAC,OAAO,MAAM,KAAG,gBAAgB,GAAG,SACpB,CAAA;AAElE,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,MAAM,OAAO,CAAC,QAAQ,MAAM,KAAG,OACzB,CAAA;AAM5C;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,MAAM,OAAO,CAAC,YAAY,mBAAmB,KAAG,IAoDxF,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,SAAS,MAAM,OAAO,CAAC,YAAY,mBAAmB,KAAG,CAezF,CAAA;AAED,6DAA6D;AAC7D,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,MAAM,OAAO,CAAC,UAAU,MAAM,KAAG,mBAAmB,EACE,CAAA;AAE5F;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,SAAS,MAAM,OAAO,CAAC,KAAG,IAS1D,CAAA"}

package/build/config.js

@@ -1,4 +1,4 @@
-import { UnknownQueue } from './errors.js';
+import { ScheduleMisdeclared, UnknownJobName, UnknownQueue } from './errors.js';
 /**
  * Add a queue to the shared configuration. Every process in the monorepo loads the same
  * declarations — a producer needs them to know a queue exists and what it accepts, a worker needs
@@ -38,4 +38,104 @@ export const queueOf = (cfg, name) => {
 };
 export const queueOfJob = (cfg, job) => cfg.queue?.queues?.find(declared => declared.jobs.includes(job));
 export const isListening = (cfg, name) => cfg.queue?.listen?.includes(name) === true;
+/** A date option the broker can read — a `Date`, epoch milliseconds or a parsable string. */
+const isInstant = (value) => Number.isFinite((value instanceof Date ? value : new Date(value)).getTime());
+/**
+ * Whether the broker can carry a schedule out as written. Nothing is recorded or changed.
+ *
+ * @throws {ScheduleMisdeclared} naming the schedule id and the reason.
+ * @throws {UnknownQueue} when the schedule's queue is not declared.
+ * @throws {UnknownJobName} when that queue does not accept the schedule's job name — a scheduled
+ * run of a name nothing declares would fail on every tick instead of once, at declaration.
+ */
+export const assertSchedule = (cfg, schedule) => {
+    const { id } = schedule;
+    if (typeof id !== 'string' || id.trim() === '') {
+        throw new ScheduleMisdeclared('(empty):id');
+    }
+    const queue = queueOf(cfg, schedule.queue);
+    if (!queue.jobs.includes(schedule.name)) {
+        throw new UnknownJobName(`${schedule.queue}:${schedule.name}`);
+    }
+    const every = schedule.every != null;
+    const pattern = schedule.pattern != null;
+    if (every === pattern) {
+        throw new ScheduleMisdeclared(`${id}:every-or-pattern`);
+    }
+    if (every && !(Number.isSafeInteger(schedule.every) && schedule.every > 0)) {
+        throw new ScheduleMisdeclared(`${id}:every`);
+    }
+    if (pattern && (typeof schedule.pattern !== 'string' || schedule.pattern.trim() === '')) {
+        throw new ScheduleMisdeclared(`${id}:pattern`);
+    }
+    // Both only mean something to a cron pattern: an interval has no wall clock to read in a time
+    // zone, and its first run is immediate already.
+    if (!pattern && schedule.tz != null) {
+        throw new ScheduleMisdeclared(`${id}:tz`);
+    }
+    if (!pattern && schedule.immediately === true) {
+        throw new ScheduleMisdeclared(`${id}:immediately`);
+    }
+    if (schedule.immediately === true && schedule.startDate != null) {
+        throw new ScheduleMisdeclared(`${id}:immediately-start-date`);
+    }
+    if (schedule.limit != null && !(Number.isSafeInteger(schedule.limit) && schedule.limit > 0)) {
+        throw new ScheduleMisdeclared(`${id}:limit`);
+    }
+    if (schedule.startDate != null && !isInstant(schedule.startDate)) {
+        throw new ScheduleMisdeclared(`${id}:start-date`);
+    }
+    if (schedule.endDate != null && !isInstant(schedule.endDate)) {
+        throw new ScheduleMisdeclared(`${id}:end-date`);
+    }
+    // The type already omits both; a declaration assembled at runtime still reaches this check. The
+    // broker names every run itself and places it on the schedule, so either would be overridden.
+    const opts = schedule.opts;
+    if (opts?.id != null) {
+        throw new ScheduleMisdeclared(`${id}:opts-id`);
+    }
+    if (opts?.delay != null) {
+        throw new ScheduleMisdeclared(`${id}:opts-delay`);
+    }
+};
+/**
+ * Add a recurring job to the shared configuration. Declare the queue first — a schedule is checked
+ * against it here. Declaring an id twice replaces, like `declareQueue`.
+ *
+ * Declaring is all this does: the driver creates, updates and removes the broker's schedulers when
+ * a worker that listens to the queue starts.
+ *
+ * @throws {ScheduleMisdeclared} / {UnknownQueue} / {UnknownJobName} — see `assertSchedule`.
+ */
+export const declareSchedule = (cfg, schedule) => {
+    assertSchedule(cfg, schedule);
+    const schedules = cfg.queue?.schedules ?? [];
+    const existing = schedules.findIndex(declared => declared.id === schedule.id);
+    if (existing < 0) {
+        schedules.push(schedule);
+    }
+    else {
+        schedules[existing] = schedule;
+    }
+    cfg.queue = { ...cfg.queue, schedules };
+    return cfg;
+};
+/** The declared schedules, of one queue when it is named. */
+export const schedulesOf = (cfg, queue) => (cfg.queue?.schedules ?? []).filter(schedule => queue == null || schedule.queue === queue);
+/**
+ * Check every declared schedule, including any written into the configuration without
+ * `declareSchedule`, and refuse two under one id.
+ *
+ * @throws {ScheduleMisdeclared} / {UnknownQueue} / {UnknownJobName} for the first one that fails.
+ */
+export const assertSchedules = (cfg) => {
+    const seen = new Set();
+    for (const schedule of schedulesOf(cfg)) {
+        assertSchedule(cfg, schedule);
+        if (seen.has(schedule.id)) {
+            throw new ScheduleMisdeclared(`${schedule.id}:duplicate`);
+        }
+        seen.add(schedule.id);
+    }
+};
 //# sourceMappingURL=config.js.map

package/build/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE1C;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,GAAM,EAAE,IAAY,EAAE,IAAc,EAAE,IAA6D,EAChG,EAAE;IACL,MAAM,KAAK,GAAqB,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,CAAA;IACvD,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,EAAE,MAAM,IAAI,EAAE,CAAA;IACtC,MAAM,QAAQ,GAAG,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,KAAK,IAAI,CAAC,CAAA;IAErE,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QACjB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACpB,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,QAAQ,CAAC,GAAG,KAAK,CAAA;IAC1B,CAAC;IAED,GAAG,CAAC,KAAK,GAAG,EAAE,GAAG,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,CAAA;IAEpC,OAAO,GAAG,CAAA;AACZ,CAAC,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAmB,GAAM,EAAE,GAAG,KAAe,EAAK,EAAE;IAC9E,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,IAAI,EAAE,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,CAAA;IAEhE,GAAG,CAAC,KAAK,GAAG,EAAE,GAAG,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC,EAAE,CAAA;IAEjD,OAAO,GAAG,CAAA;AACZ,CAAC,CAAA;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAmB,GAAM,EAAE,IAAY,EAAoB,EAAE;IAClF,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,KAAK,IAAI,CAAC,CAAA;IAEzE,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;QAClB,MAAM,IAAI,YAAY,CAAC,IAAI,CAAC,CAAA;IAC9B,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,UAAU,GAAG,CAAmB,GAAM,EAAE,GAAW,EAAgC,EAAE,CAChG,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAA;AAElE,MAAM,CAAC,MAAM,WAAW,GAAG,CAAmB,GAAM,EAAE,IAAY,EAAW,EAAE,CAC7E,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,IAAI,CAAA"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/build/errors.d.ts

@@ -56,4 +56,13 @@ export declare class EnvelopeExpired extends QueueError {
     static typeName: string;
     constructor(msg: string);
 }
+/**
+ * A schedule the broker could not carry out as written: no id, both or neither of `every` and
+ * `pattern`, an option that only means something for the other one, or a job option the broker
+ * owns for a scheduled run. The message names the schedule id and the reason.
+ */
+export declare class ScheduleMisdeclared extends QueueError {
+    static typeName: string;
+    constructor(msg: string);
+}
 //# sourceMappingURL=errors.d.ts.map

package/build/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,qBAAa,UAAW,SAAQ,cAAc;IAC5C,OAAuB,QAAQ,SAAe;IAE9C,YAAY,OAAO,GAAE,MAAgB,EAEpC;CACF;AAED;;;GAGG;AACH,qBAAa,YAAa,SAAQ,UAAU;IAC1C,OAAuB,QAAQ,SAAkC;IAEjE,YAAY,GAAG,EAAE,MAAM,EAGtB;CACF;AAED,gGAAgG;AAChG,qBAAa,UAAW,SAAQ,UAAU;IACxC,OAAuB,QAAQ,SAAqC;IAEpE,YAAY,GAAG,EAAE,MAAM,EAGtB;CACF;AAED;;;GAGG;AACH,qBAAa,cAAe,SAAQ,UAAU;IAC5C,OAAuB,QAAQ,SAAyC;IAExE,YAAY,GAAG,EAAE,MAAM,EAGtB;CACF;AAED,mDAAmD;AACnD,qBAAa,YAAa,SAAQ,UAAU;IAC1C,OAAuB,QAAQ,SAAuC;IAEtE,YAAY,GAAG,EAAE,MAAM,EAGtB;CACF;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,UAAU;IAC/C,OAAuB,QAAQ,SAAuC;IAEtE,YAAY,GAAG,EAAE,MAAM,EAGtB;CACF;AAED;;;;GAIG;AACH,qBAAa,YAAa,SAAQ,UAAU;IAC1C,OAAuB,QAAQ,SAAuC;IAEtE,YAAY,GAAG,EAAE,MAAM,EAGtB;CACF;AAED;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,UAAU;IAC7C,OAAuB,QAAQ,SAA0C;IAEzE,YAAY,GAAG,EAAE,MAAM,EAGtB;CACF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,qBAAa,UAAW,SAAQ,cAAc;IAC5C,OAAuB,QAAQ,SAAe;IAE9C,YAAY,OAAO,GAAE,MAAgB,EAEpC;CACF;AAED;;;GAGG;AACH,qBAAa,YAAa,SAAQ,UAAU;IAC1C,OAAuB,QAAQ,SAAkC;IAEjE,YAAY,GAAG,EAAE,MAAM,EAGtB;CACF;AAED,gGAAgG;AAChG,qBAAa,UAAW,SAAQ,UAAU;IACxC,OAAuB,QAAQ,SAAqC;IAEpE,YAAY,GAAG,EAAE,MAAM,EAGtB;CACF;AAED;;;GAGG;AACH,qBAAa,cAAe,SAAQ,UAAU;IAC5C,OAAuB,QAAQ,SAAyC;IAExE,YAAY,GAAG,EAAE,MAAM,EAGtB;CACF;AAED,mDAAmD;AACnD,qBAAa,YAAa,SAAQ,UAAU;IAC1C,OAAuB,QAAQ,SAAuC;IAEtE,YAAY,GAAG,EAAE,MAAM,EAGtB;CACF;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,UAAU;IAC/C,OAAuB,QAAQ,SAAuC;IAEtE,YAAY,GAAG,EAAE,MAAM,EAGtB;CACF;AAED;;;;GAIG;AACH,qBAAa,YAAa,SAAQ,UAAU;IAC1C,OAAuB,QAAQ,SAAuC;IAEtE,YAAY,GAAG,EAAE,MAAM,EAGtB;CACF;AAED;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,UAAU;IAC7C,OAAuB,QAAQ,SAA0C;IAEzE,YAAY,GAAG,EAAE,MAAM,EAGtB;CACF;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,UAAU;IACjD,OAAuB,QAAQ,SAA8C;IAE7E,YAAY,GAAG,EAAE,MAAM,EAGtB;CACF"}

package/build/errors.js

@@ -79,6 +79,18 @@ export class EnvelopeExpired extends QueueError {
         this.type = EnvelopeExpired.typeName;
     }
 }
+/**
+ * A schedule the broker could not carry out as written: no id, both or neither of `every` and
+ * `pattern`, an option that only means something for the other one, or a job option the broker
+ * owns for a scheduled run. The message names the schedule id and the reason.
+ */
+export class ScheduleMisdeclared extends QueueError {
+    static typeName = `${QueueError.typeName}ScheduleMisdeclared`;
+    constructor(msg) {
+        super(`schedule-misdeclared:${msg}`);
+        this.type = ScheduleMisdeclared.typeName;
+    }
+}
 ResilientError.registerErrorClass(QueueError);
 ResilientError.registerErrorClass(QueueTimeout);
 ResilientError.registerErrorClass(UnknownJob);
@@ -87,4 +99,5 @@ ResilientError.registerErrorClass(UnknownQueue);
 ResilientError.registerErrorClass(QueueNotListening);
 ResilientError.registerErrorClass(JobNotServed);
 ResilientError.registerErrorClass(EnvelopeExpired);
+ResilientError.registerErrorClass(ScheduleMisdeclared);
 //# sourceMappingURL=errors.js.map

package/build/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/build/types.d.ts

@@ -19,6 +19,56 @@ export interface QueueConfig {
      * check and the nonce cache, so a job delayed behind a long backlog is still admitted.
      */
     envelopeTtl?: number;
+    /**
+     * Recurring jobs. Declared beside the queues, in the shared package, because every process that
+     * listens to a schedule's queue reconciles the broker against this list when its worker starts —
+     * two listeners loading different lists would remove each other's schedules.
+     */
+    schedules?: ScheduleDeclaration[];
+}
+/**
+ * A job the broker produces on its own, on an interval or a cron pattern.
+ *
+ * A scheduled run is an ordinary job of a name the queue declares, dispatched to the processor
+ * registered for that name — never to a guarded entrypoint, because nobody's credentials travel
+ * with it. Only a process that listens to the queue creates the scheduler, and the broker produces
+ * each next run when the previous one STARTS processing — a schedule needs a running consumer.
+ */
+export interface ScheduleDeclaration {
+    /**
+     * The schedule's stable identity: the broker keeps one scheduler per id, so changing any other
+     * field updates it in place, while renaming the id removes one schedule and creates another.
+     */
+    id: string;
+    queue: string;
+    /** A job name the queue declares. */
+    name: string;
+    /**
+     * Milliseconds between runs. Exactly one of `every` and `pattern`. Without `startDate` the first
+     * run is produced as soon as the scheduler is created.
+     */
+    every?: number;
+    /** A cron pattern (an optional leading seconds field is accepted). Exactly one of the two. */
+    pattern?: string;
+    /** The IANA time zone `pattern` is read in. Pattern only. */
+    tz?: string;
+    startDate?: Date | number | string;
+    /** Once passed, the schedule is treated as absent and a scheduler left from it is removed. */
+    endDate?: Date | number | string;
+    /** Stop after this many runs. */
+    limit?: number;
+    /**
+     * Run once as soon as the scheduler is created or its declaration changes, then follow the
+     * pattern. Pattern only, and never together with `startDate`. A restart that finds the
+     * declaration unchanged does not run it again.
+     */
+    immediately?: boolean;
+    data?: unknown;
+    /**
+     * Options every run is enqueued with, over the queue's defaults. `id` and `delay` belong to the
+     * broker for a scheduled run and are refused.
+     */
+    opts?: Omit<JobOptions, 'id' | 'delay'>;
 }
 export interface QueueDeclaration {
     name: string;
@@ -147,6 +197,11 @@ export interface JobContext<D = unknown> {
     attempt: number;
     data: D;
     signal: AbortSignal;
+    /**
+     * The id of the schedule that produced this run (`ScheduleDeclaration.id`). Absent for a job
+     * enqueued any other way.
+     */
+    scheduled?: string;
     /**
      * Renew the lock. A processor that runs a long loop MUST call it as it goes: the broker judges
      * liveness by the lock, so silence for longer than `lockDuration` is indistinguishable from a

package/build/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/queue",
-  "version": "0.1.18-rc.22",
+  "version": "0.1.18-rc.23",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -31,12 +31,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@owlmeans/auth": "^0.1.18-rc.26",
-    "@owlmeans/auth-common": "^0.1.18-rc.28",
-    "@owlmeans/context": "^0.1.18-rc.24",
-    "@owlmeans/entrypoint": "^0.1.18-rc.27",
-    "@owlmeans/error": "^0.1.18-rc.26",
-    "@owlmeans/resource": "^0.1.18-rc.26",
-    "@owlmeans/route": "^0.1.18-rc.25"
+    "@owlmeans/auth": "^0.1.18-rc.27",
+    "@owlmeans/auth-common": "^0.1.18-rc.29",
+    "@owlmeans/context": "^0.1.18-rc.25",
+    "@owlmeans/entrypoint": "^0.1.18-rc.28",
+    "@owlmeans/error": "^0.1.18-rc.27",
+    "@owlmeans/resource": "^0.1.18-rc.27",
+    "@owlmeans/route": "^0.1.18-rc.26"
   }
 }

package/src/config.ts

@@ -1,5 +1,7 @@
-import type { Config, JobOptions, QueueDeclaration, QueueWorkerOptions } from './types.js'
-import { UnknownQueue } from './errors.js'
+import type {
+  Config, JobOptions, QueueDeclaration, QueueWorkerOptions, ScheduleDeclaration
+} from './types.js'
+import { ScheduleMisdeclared, UnknownJobName, UnknownQueue } from './errors.js'
 
 /**
  * Add a queue to the shared configuration. Every process in the monorepo loads the same
@@ -54,3 +56,116 @@ export const queueOfJob = <C extends Config>(cfg: C, job: string): QueueDeclarat
 
 export const isListening = <C extends Config>(cfg: C, name: string): boolean =>
   cfg.queue?.listen?.includes(name) === true
+
+/** A date option the broker can read — a `Date`, epoch milliseconds or a parsable string. */
+const isInstant = (value: Date | number | string): boolean =>
+  Number.isFinite((value instanceof Date ? value : new Date(value)).getTime())
+
+/**
+ * Whether the broker can carry a schedule out as written. Nothing is recorded or changed.
+ *
+ * @throws {ScheduleMisdeclared} naming the schedule id and the reason.
+ * @throws {UnknownQueue} when the schedule's queue is not declared.
+ * @throws {UnknownJobName} when that queue does not accept the schedule's job name — a scheduled
+ * run of a name nothing declares would fail on every tick instead of once, at declaration.
+ */
+export const assertSchedule = <C extends Config>(cfg: C, schedule: ScheduleDeclaration): void => {
+  const { id } = schedule
+  if (typeof id !== 'string' || id.trim() === '') {
+    throw new ScheduleMisdeclared('(empty):id')
+  }
+
+  const queue = queueOf(cfg, schedule.queue)
+  if (!queue.jobs.includes(schedule.name)) {
+    throw new UnknownJobName(`${schedule.queue}:${schedule.name}`)
+  }
+
+  const every = schedule.every != null
+  const pattern = schedule.pattern != null
+  if (every === pattern) {
+    throw new ScheduleMisdeclared(`${id}:every-or-pattern`)
+  }
+  if (every && !(Number.isSafeInteger(schedule.every) && (schedule.every as number) > 0)) {
+    throw new ScheduleMisdeclared(`${id}:every`)
+  }
+  if (pattern && (typeof schedule.pattern !== 'string' || schedule.pattern.trim() === '')) {
+    throw new ScheduleMisdeclared(`${id}:pattern`)
+  }
+  // Both only mean something to a cron pattern: an interval has no wall clock to read in a time
+  // zone, and its first run is immediate already.
+  if (!pattern && schedule.tz != null) {
+    throw new ScheduleMisdeclared(`${id}:tz`)
+  }
+  if (!pattern && schedule.immediately === true) {
+    throw new ScheduleMisdeclared(`${id}:immediately`)
+  }
+  if (schedule.immediately === true && schedule.startDate != null) {
+    throw new ScheduleMisdeclared(`${id}:immediately-start-date`)
+  }
+  if (schedule.limit != null && !(Number.isSafeInteger(schedule.limit) && schedule.limit > 0)) {
+    throw new ScheduleMisdeclared(`${id}:limit`)
+  }
+  if (schedule.startDate != null && !isInstant(schedule.startDate)) {
+    throw new ScheduleMisdeclared(`${id}:start-date`)
+  }
+  if (schedule.endDate != null && !isInstant(schedule.endDate)) {
+    throw new ScheduleMisdeclared(`${id}:end-date`)
+  }
+
+  // The type already omits both; a declaration assembled at runtime still reaches this check. The
+  // broker names every run itself and places it on the schedule, so either would be overridden.
+  const opts = schedule.opts as JobOptions | undefined
+  if (opts?.id != null) {
+    throw new ScheduleMisdeclared(`${id}:opts-id`)
+  }
+  if (opts?.delay != null) {
+    throw new ScheduleMisdeclared(`${id}:opts-delay`)
+  }
+}
+
+/**
+ * Add a recurring job to the shared configuration. Declare the queue first — a schedule is checked
+ * against it here. Declaring an id twice replaces, like `declareQueue`.
+ *
+ * Declaring is all this does: the driver creates, updates and removes the broker's schedulers when
+ * a worker that listens to the queue starts.
+ *
+ * @throws {ScheduleMisdeclared} / {UnknownQueue} / {UnknownJobName} — see `assertSchedule`.
+ */
+export const declareSchedule = <C extends Config>(cfg: C, schedule: ScheduleDeclaration): C => {
+  assertSchedule(cfg, schedule)
+
+  const schedules = cfg.queue?.schedules ?? []
+  const existing = schedules.findIndex(declared => declared.id === schedule.id)
+
+  if (existing < 0) {
+    schedules.push(schedule)
+  } else {
+    schedules[existing] = schedule
+  }
+
+  cfg.queue = { ...cfg.queue, schedules }
+
+  return cfg
+}
+
+/** The declared schedules, of one queue when it is named. */
+export const schedulesOf = <C extends Config>(cfg: C, queue?: string): ScheduleDeclaration[] =>
+  (cfg.queue?.schedules ?? []).filter(schedule => queue == null || schedule.queue === queue)
+
+/**
+ * Check every declared schedule, including any written into the configuration without
+ * `declareSchedule`, and refuse two under one id.
+ *
+ * @throws {ScheduleMisdeclared} / {UnknownQueue} / {UnknownJobName} for the first one that fails.
+ */
+export const assertSchedules = <C extends Config>(cfg: C): void => {
+  const seen = new Set<string>()
+  for (const schedule of schedulesOf(cfg)) {
+    assertSchedule(cfg, schedule)
+    if (seen.has(schedule.id)) {
+      throw new ScheduleMisdeclared(`${schedule.id}:duplicate`)
+    }
+    seen.add(schedule.id)
+  }
+}

package/src/errors.ts

@@ -96,6 +96,20 @@ export class EnvelopeExpired extends QueueError {
   }
 }
 
+/**
+ * A schedule the broker could not carry out as written: no id, both or neither of `every` and
+ * `pattern`, an option that only means something for the other one, or a job option the broker
+ * owns for a scheduled run. The message names the schedule id and the reason.
+ */
+export class ScheduleMisdeclared extends QueueError {
+  public static override typeName = `${QueueError.typeName}ScheduleMisdeclared`
+
+  constructor(msg: string) {
+    super(`schedule-misdeclared:${msg}`)
+    this.type = ScheduleMisdeclared.typeName
+  }
+}
+
 ResilientError.registerErrorClass(QueueError)
 ResilientError.registerErrorClass(QueueTimeout)
 ResilientError.registerErrorClass(UnknownJob)
@@ -104,3 +118,4 @@ ResilientError.registerErrorClass(UnknownQueue)
 ResilientError.registerErrorClass(QueueNotListening)
 ResilientError.registerErrorClass(JobNotServed)
 ResilientError.registerErrorClass(EnvelopeExpired)
+ResilientError.registerErrorClass(ScheduleMisdeclared)

package/src/types.ts

@@ -20,6 +20,57 @@ export interface QueueConfig {
    * check and the nonce cache, so a job delayed behind a long backlog is still admitted.
    */
   envelopeTtl?: number
+  /**
+   * Recurring jobs. Declared beside the queues, in the shared package, because every process that
+   * listens to a schedule's queue reconciles the broker against this list when its worker starts —
+   * two listeners loading different lists would remove each other's schedules.
+   */
+  schedules?: ScheduleDeclaration[]
+}
+
+/**
+ * A job the broker produces on its own, on an interval or a cron pattern.
+ *
+ * A scheduled run is an ordinary job of a name the queue declares, dispatched to the processor
+ * registered for that name — never to a guarded entrypoint, because nobody's credentials travel
+ * with it. Only a process that listens to the queue creates the scheduler, and the broker produces
+ * each next run when the previous one STARTS processing — a schedule needs a running consumer.
+ */
+export interface ScheduleDeclaration {
+  /**
+   * The schedule's stable identity: the broker keeps one scheduler per id, so changing any other
+   * field updates it in place, while renaming the id removes one schedule and creates another.
+   */
+  id: string
+  queue: string
+  /** A job name the queue declares. */
+  name: string
+  /**
+   * Milliseconds between runs. Exactly one of `every` and `pattern`. Without `startDate` the first
+   * run is produced as soon as the scheduler is created.
+   */
+  every?: number
+  /** A cron pattern (an optional leading seconds field is accepted). Exactly one of the two. */
+  pattern?: string
+  /** The IANA time zone `pattern` is read in. Pattern only. */
+  tz?: string
+  startDate?: Date | number | string
+  /** Once passed, the schedule is treated as absent and a scheduler left from it is removed. */
+  endDate?: Date | number | string
+  /** Stop after this many runs. */
+  limit?: number
+  /**
+   * Run once as soon as the scheduler is created or its declaration changes, then follow the
+   * pattern. Pattern only, and never together with `startDate`. A restart that finds the
+   * declaration unchanged does not run it again.
+   */
+  immediately?: boolean
+  data?: unknown
+  /**
+   * Options every run is enqueued with, over the queue's defaults. `id` and `delay` belong to the
+   * broker for a scheduled run and are refused.
+   */
+  opts?: Omit<JobOptions, 'id' | 'delay'>
 }
 
 export interface QueueDeclaration {
@@ -152,6 +203,11 @@ export interface JobContext<D = unknown> {
   attempt: number
   data: D
   signal: AbortSignal
+  /**
+   * The id of the schedule that produced this run (`ScheduleDeclaration.id`). Absent for a job
+   * enqueued any other way.
+   */
+  scheduled?: string
   /**
    * Renew the lock. A processor that runs a long loop MUST call it as it goes: the broker judges
    * liveness by the lock, so silence for longer than `lockDuration` is indistinguishable from a

package/tests/schedule.spec.ts

@@ -0,0 +1,100 @@
+import { describe, test, expect } from 'bun:test'
+import {
+  assertSchedule, assertSchedules, declareQueue, declareSchedule, queueOf, schedulesOf
+} from '../src/config.js'
+import { ScheduleMisdeclared, UnknownJobName, UnknownQueue } from '../src/errors.js'
+import type { Config, ScheduleDeclaration } from '../src/types.js'
+
+const cfg = (): Config => declareQueue(
+  declareQueue({ ready: false, service: 'test', type: 'backend' } as unknown as Config,
+    'maintenance', ['reconcile', 'sweep']),
+  'work', ['story:code']
+)
+
+const nightly: ScheduleDeclaration = {
+  id: 'nightly-reconcile', queue: 'maintenance', name: 'reconcile', pattern: '17 3 * * *', tz: 'UTC',
+}
+
+const misdeclared = (schedule: Partial<ScheduleDeclaration>): () => void =>
+  () => assertSchedule(cfg(), { ...nightly, ...schedule } as ScheduleDeclaration)
+
+describe('declaring schedules', () => {
+  test('a declaration is recorded and read back by its queue', () => {
+    const config = declareSchedule(cfg(), nightly)
+
+    expect(schedulesOf(config, 'maintenance')).toEqual([nightly])
+    expect(schedulesOf(config, 'work')).toEqual([])
+    expect(schedulesOf(config)).toHaveLength(1)
+  })
+
+  test('re-declaring an id replaces rather than appends', () => {
+    let config = declareSchedule(cfg(), nightly)
+    config = declareSchedule(config, { ...nightly, pattern: '0 4 * * *' })
+
+    expect(schedulesOf(config)).toHaveLength(1)
+    expect(schedulesOf(config)[0].pattern).toBe('0 4 * * *')
+  })
+
+  /**
+   * A scheduled run of a name the queue does not accept would fail on every tick. Refusing at
+   * declaration turns that into one error at boot, and the refused schedule is not recorded.
+   */
+  test('a schedule for an undeclared queue or job name is refused and not recorded', () => {
+    const config = cfg()
+
+    expect(() => declareSchedule(config, { ...nightly, queue: 'missing' })).toThrow(UnknownQueue)
+    expect(() => declareSchedule(config, { ...nightly, name: 'story:code' })).toThrow(UnknownJobName)
+    expect(schedulesOf(config)).toHaveLength(0)
+  })
+
+  test('re-declaring the queue keeps its schedules', () => {
+    const config = declareQueue(declareSchedule(cfg(), nightly), 'maintenance', ['reconcile'])
+
+    expect(queueOf(config, 'maintenance').jobs).toEqual(['reconcile'])
+    expect(schedulesOf(config)).toEqual([nightly])
+  })
+})
+
+describe('asserting a schedule', () => {
+  test('exactly one of every and pattern', () => {
+    expect(misdeclared({ every: 1_000 })).toThrow(/every-or-pattern/)
+    expect(misdeclared({ pattern: undefined, tz: undefined })).toThrow(/every-or-pattern/)
+    expect(misdeclared({ pattern: undefined, tz: undefined, every: 0 })).toThrow(/:every$/)
+    expect(misdeclared({ pattern: undefined, tz: undefined, every: 1.5 })).toThrow(ScheduleMisdeclared)
+  })
+
+  test('tz and immediately belong to a pattern only', () => {
+    expect(misdeclared({ pattern: undefined, every: 1_000 })).toThrow(/:tz$/)
+    expect(misdeclared({ pattern: undefined, tz: undefined, every: 1_000, immediately: true }))
+      .toThrow(/:immediately$/)
+    expect(misdeclared({ immediately: true, startDate: new Date() })).toThrow(/immediately-start-date/)
+    expect(misdeclared({ immediately: true })).not.toThrow()
+  })
+
+  test('the broker owns a scheduled run\'s id and delay', () => {
+    expect(misdeclared({ opts: { id: 'fixed' } as ScheduleDeclaration['opts'] })).toThrow(/opts-id/)
+    expect(misdeclared({ opts: { delay: 10 } as ScheduleDeclaration['opts'] })).toThrow(/opts-delay/)
+    expect(misdeclared({ opts: { attempts: 3 } })).not.toThrow()
+  })
+
+  test('an empty id is refused', () => {
+    expect(misdeclared({ id: ' ' })).toThrow(ScheduleMisdeclared)
+  })
+})
+
+describe('asserting every schedule', () => {
+  test('two schedules under one id are refused', () => {
+    const config = declareSchedule(cfg(), nightly)
+    config.queue?.schedules?.push({ ...nightly, pattern: '0 5 * * *' })
+
+    expect(() => assertSchedules(config)).toThrow(/duplicate/)
+  })
+
+  /** The configuration is plain data; a schedule written into it directly is checked too. */
+  test('a schedule written past declareSchedule is still checked', () => {
+    const config = declareSchedule(cfg(), nightly)
+    config.queue?.schedules?.push({ id: 'orphan', queue: 'maintenance', name: 'gone', every: 1_000 })
+
+    expect(() => assertSchedules(config)).toThrow(UnknownJobName)
+  })
+})