feat(schedule): add getSchedule() and previewSchedule()

Reading one schedule and answering "when does this next fire?" are both common in
admin tooling and in libraries that wrap schedule(), and both are awkward today.

getSchedules(name, key) already narrows to the single row a (name, key) pair can
hold, but still returns an array, so every caller destructures and then checks for
undefined. getSchedule(name, key) returns the row or null.

Previewing upcoming occurrences means reaching for cron-parser directly, which
duplicates the expression/time zone validation schedule() performs and evaluates
against the local clock rather than database time. previewSchedule() reuses the
same validation (extracted as assertRecurrence, now shared with schedule()) and
defaults its reference point to database time, the reading the cron pass itself
evaluates against.

previewSchedule() is pure computation: no query, no started instance needed.
Occurrences are strictly after `from`, so passing the last one back in pages
forward. count is capped at 1000 so a per-second expression cannot be asked for
an unbounded walk.

Author: kibertoad

docs/api/scheduling.md

@@ -103,4 +103,65 @@ Returns all scheduled jobs by queue name and unique key.
 
 ```js
 const [schedule] = await boss.getSchedules('report', 'eu')
+```
+
+### `getSchedule(name, key)`
+
+Returns the schedule for a queue name and unique key, or `null` if there is none. `key` defaults to
+the empty string, the key `schedule()` uses when none is supplied.
+
+Unlike `getSchedules(name, key)`, which always returns an array, this reads the one row a
+`(name, key)` pair can have.
+
+```js
+const schedule = await boss.getSchedule('report', 'eu')
+
+if (schedule) {
+  console.log(`${schedule.cron} ${schedule.timezone}`)
+}
+```
+
+### `previewSchedule(cron, options)`
+
+Returns the next occurrences a cron expression produces, as an array of `Date`. The expression and
+time zone are validated exactly as `schedule()` validates them, so anything this previews can also
+be stored.
+
+This is pure computation: it does not query the database and does not require a started instance.
+
+**Arguments**
+
+- `cron`: string, *required*
+- `options`: object
+
+**options**
+
+* **tz**, string, *default: `UTC`*
+
+  Time zone the expression is evaluated in.
+
+* **from**, Date, *default: database time*
+
+  Reference point the walk starts from. The default is this instance's clock plus the cached skew,
+  the same reading the cron pass evaluates against. Occurrences are strictly after it, so passing
+  the last occurrence of one page back in yields the next page.
+
+* **count**, number, *default: 5*
+
+  How many occurrences to return. Must be an integer between 1 and 1000.
+
+```js
+const occurrences = boss.previewSchedule('0 3 * * *', { tz: 'America/Chicago', count: 3 })
+```
+
+The result describes the expression, not the delivery. Schedules are checked every
+`cronMonitorIntervalSeconds` and an occurrence within the preceding 60 seconds is sent, so a job
+lands at or shortly after each listed time.
+
+To preview a stored schedule, read it first:
+
+```js
+const schedule = await boss.getSchedule('report', 'eu')
+
+const upcoming = boss.previewSchedule(schedule.cron, { tz: schedule.timezone })
 ```

src/index.ts

@@ -519,6 +519,14 @@ export class PgBoss extends EventEmitter<types.PgBossEventMap> {
     return this.#timekeeper.getSchedules(name, key)
   }
 
+  getSchedule (name: string, key?: string): Promise<types.Schedule | null> {
+    return this.#timekeeper.getSchedule(name, key)
+  }
+
+  previewSchedule (cron: string, options?: types.PreviewScheduleOptions): Date[] {
+    return this.#timekeeper.previewSchedule(cron, options)
+  }
+
   async getBamStatus (): Promise<types.BamStatusSummary[]> {
     const sql = plans.getBamStatus(this.#config.schema)
     const { rows } = await this.#db.executeSql(sql)

src/timekeeper.ts

@@ -1,4 +1,5 @@
 import { CronExpressionParser } from 'cron-parser'
+import assert from 'node:assert'
 import EventEmitter from 'node:events'
 
 import * as Attorney from './attorney.ts'
@@ -29,6 +30,12 @@ const WARNING_TYPES = {
   INVALID_SCHEDULE: 'invalid_schedule'
 } as const
 
+// previewSchedule() defaults and ceiling. The ceiling is not a database limit, since the walk is
+// pure cron-parser arithmetic, but an unbounded count on a per-second expression is a foot-gun.
+// A caller that genuinely wants more can page by passing the last occurrence back as `from`.
+const PREVIEW_DEFAULT_COUNT = 5
+const PREVIEW_MAX_COUNT = 1000
+
 /**
  * Asserts that `tz` is a time zone cron evaluation can actually use.
  *
@@ -50,6 +57,20 @@ function assertTimezone (tz: string): void {
   }
 }
 
+/**
+ * Validates a recurrence exactly as schedule() does, so previewSchedule() rejects the same inputs
+ * schedule() rejects rather than previewing an expression that could never be stored.
+ *
+ * Expression first, so a bad expression reports as one rather than as a time zone problem. The
+ * check is deliberately run against UTC rather than the supplied tz: it only works today because
+ * cron-parser is lazy about an unusable zone, and if that ever changes this call would throw the
+ * opaque "CronDate: unhandled timestamp" that assertTimezone exists to replace.
+ */
+function assertRecurrence (cron: string, tz: string): void {
+  CronExpressionParser.parse(cron, { tz: 'UTC', strict: false })
+  assertTimezone(tz)
+}
+
 class Timekeeper extends EventEmitter implements types.EventsMixin {
   db: types.IDatabase
   config: types.ResolvedConstructorOptions
@@ -294,15 +315,55 @@ class Timekeeper extends EventEmitter implements types.EventsMixin {
     return rows
   }
 
+  async getSchedule (name: string, key = ''): Promise<types.Schedule | null> {
+    Attorney.assertQueueName(name)
+    Attorney.assertKey(key)
+
+    const [schedule] = await this.getSchedules(name, key)
+
+    return schedule ?? null
+  }
+
+  /**
+   * The occurrences a cron expression produces, computed in process without touching the database
+   * or the schedule table.
+   *
+   * `from` defaults to database time (this instance's clock plus the cached skew), the same reading
+   * the cron pass evaluates against, so a preview taken from a running instance lines up with what
+   * that instance will actually send. Occurrences are strictly after `from`, so paging is a matter
+   * of passing the last one back in.
+   *
+   * The result describes the expression, not the delivery. The cron pass runs every
+   * `cronMonitorIntervalSeconds` and matches an occurrence within the preceding 60 seconds, so a
+   * job lands at or shortly after each listed time.
+   */
+  previewSchedule (cron: string, options: types.PreviewScheduleOptions = {}): Date[] {
+    const { tz = 'UTC', count = PREVIEW_DEFAULT_COUNT } = options
+
+    assert(Number.isInteger(count) && count >= 1 && count <= PREVIEW_MAX_COUNT,
+      `count must be an integer between 1 and ${PREVIEW_MAX_COUNT}`)
+
+    const from = options.from ?? new Date(Date.now() + this.clockSkew)
+
+    assert(from instanceof Date && !Number.isNaN(from.getTime()), 'from must be a valid Date')
+
+    assertRecurrence(cron, tz)
+
+    const interval = CronExpressionParser.parse(cron, { tz, strict: false, currentDate: from })
+
+    const occurrences: Date[] = []
+
+    for (let i = 0; i < count; i++) {
+      occurrences.push(interval.next().toDate())
+    }
+
+    return occurrences
+  }
+
   async schedule (name: string, cron: string, data?: unknown, options: types.ScheduleOptions = {}): Promise<void> {
     const { tz = 'UTC', key = '', ...rest } = options
 
-    // Expression first, so a bad expression reports as one rather than as a time zone problem. The
-    // check is deliberately run against UTC rather than the supplied tz: it only works today
-    // because cron-parser is lazy about an unusable zone, and if that ever changes this call would
-    // throw the opaque "CronDate: unhandled timestamp" that assertTimezone exists to replace.
-    CronExpressionParser.parse(cron, { tz: 'UTC', strict: false })
-    assertTimezone(tz)
+    assertRecurrence(cron, tz)
 
     Attorney.checkSendArgs([name, data, { ...rest }])
     Attorney.assertKey(key)

src/types.ts

@@ -701,6 +701,25 @@ export interface QueueResult extends Queue {
 
 export type ScheduleOptions = SendOptions & { tz?: string, key?: string }
 
+export interface PreviewScheduleOptions {
+  /**
+   * Time zone the expression is evaluated in.
+   * @default 'UTC'
+   */
+  tz?: string;
+  /**
+   * Reference point the walk starts from. Occurrences are strictly after it, so passing the last
+   * occurrence of one page back in yields the next page.
+   * @default database time (the instance clock plus the cached skew)
+   */
+  from?: Date;
+  /**
+   * How many occurrences to return. Must be an integer between 1 and 1000.
+   * @default 5
+   */
+  count?: number;
+}
+
 /**
  * How long a worker waits between fetches. The delay before each fetch is chosen by
  * precedence — **burst → notify → base**:

test/scheduleReadTest.ts

@@ -0,0 +1,164 @@
+import { expect } from 'vitest'
+import * as helper from './testHelper.ts'
+import Timekeeper from '../src/timekeeper.ts'
+import { ctx } from './hooks.ts'
+
+describe('getSchedule', function () {
+  it('should return a single schedule by queue name and key', async function () {
+    ctx.boss = await helper.start({ ...ctx.bossConfig })
+
+    await ctx.boss.schedule(ctx.schema, '* * * * *')
+    await ctx.boss.schedule(ctx.schema, '0 1 * * *', null, { key: 'a' })
+
+    const schedule = await ctx.boss.getSchedule(ctx.schema, 'a')
+
+    helper.assertTruthy(schedule)
+    expect(schedule.name).toBe(ctx.schema)
+    expect(schedule.key).toBe('a')
+    expect(schedule.cron).toBe('0 1 * * *')
+  })
+
+  it('should return the default-key schedule when no key is given', async function () {
+    ctx.boss = await helper.start({ ...ctx.bossConfig })
+
+    await ctx.boss.schedule(ctx.schema, '* * * * *')
+    await ctx.boss.schedule(ctx.schema, '0 1 * * *', null, { key: 'a' })
+
+    const schedule = await ctx.boss.getSchedule(ctx.schema)
+
+    helper.assertTruthy(schedule)
+    expect(schedule.key).toBe('')
+    expect(schedule.cron).toBe('* * * * *')
+  })
+
+  it('should return null when the schedule does not exist', async function () {
+    ctx.boss = await helper.start({ ...ctx.bossConfig })
+
+    await ctx.boss.schedule(ctx.schema, '* * * * *')
+
+    expect(await ctx.boss.getSchedule(ctx.schema, 'nope')).toBeNull()
+  })
+
+  it('should reject a missing queue name', async function () {
+    ctx.boss = await helper.start({ ...ctx.bossConfig })
+
+    await expect(async () => {
+      // @ts-expect-error deliberately calling without the required queue name
+      await ctx.boss.getSchedule()
+    }).rejects.toThrow()
+  })
+})
+
+// Pure computation: no database, no running instance.
+describe('previewSchedule', function () {
+  function makeTk (config: object = {}) {
+    const db = { executeSql: async () => ({ rows: [] }) }
+    return new Timekeeper(db as any, {} as any, { schema: 'test', ...config } as any)
+  }
+
+  it('should return the next occurrences after the reference date', function () {
+    const tk = makeTk()
+
+    const occurrences = tk.previewSchedule('0 3 * * *', { from: new Date('2026-03-01T00:00:00Z'), count: 3 })
+
+    expect(occurrences.map(d => d.toISOString())).toEqual([
+      '2026-03-01T03:00:00.000Z',
+      '2026-03-02T03:00:00.000Z',
+      '2026-03-03T03:00:00.000Z'
+    ])
+  })
+
+  it('should evaluate the expression in the supplied time zone', function () {
+    const tk = makeTk()
+
+    const [first] = tk.previewSchedule('0 3 * * *', {
+      tz: 'America/Chicago',
+      from: new Date('2026-03-01T00:00:00Z'),
+      count: 1
+    })
+
+    // 3am US central on March 1 is still standard time (UTC-6)
+    expect(first.toISOString()).toBe('2026-03-01T09:00:00.000Z')
+  })
+
+  it('should default to five occurrences', function () {
+    const tk = makeTk()
+
+    expect(tk.previewSchedule('* * * * *').length).toBe(5)
+  })
+
+  it('should exclude the reference date itself so pages do not overlap', function () {
+    const tk = makeTk()
+
+    const from = new Date('2026-03-01T03:00:00Z')
+    const [first] = tk.previewSchedule('0 3 * * *', { from, count: 1 })
+
+    expect(first.toISOString()).toBe('2026-03-02T03:00:00.000Z')
+
+    // handing the last occurrence back in yields the next page
+    const [next] = tk.previewSchedule('0 3 * * *', { from: first, count: 1 })
+    expect(next.toISOString()).toBe('2026-03-03T03:00:00.000Z')
+  })
+
+  it('should start from database time when no reference date is given', function () {
+    const tk = makeTk()
+
+    // an hour of clock skew has to move the first occurrence of an hourly expression
+    tk.clockSkew = 60 * 60 * 1000
+
+    const [skewed] = tk.previewSchedule('0 * * * *', { count: 1 })
+
+    tk.clockSkew = 0
+
+    const [local] = tk.previewSchedule('0 * * * *', { count: 1 })
+
+    expect(skewed.getTime()).toBeGreaterThan(local.getTime())
+  })
+
+  it('should reject an expression schedule() would reject', function () {
+    const tk = makeTk()
+
+    expect(() => tk.previewSchedule('bogus')).toThrow()
+  })
+
+  it('should reject an unusable time zone', function () {
+    const tk = makeTk()
+
+    expect(() => tk.previewSchedule('* * * * *', { tz: 'Mars/Phobos' })).toThrow(/time zone/)
+  })
+
+  it('should reject a count outside the supported range', function () {
+    const tk = makeTk()
+
+    expect(() => tk.previewSchedule('* * * * *', { count: 0 })).toThrow(/count/)
+    expect(() => tk.previewSchedule('* * * * *', { count: 1001 })).toThrow(/count/)
+    expect(() => tk.previewSchedule('* * * * *', { count: 1.5 })).toThrow(/count/)
+  })
+
+  it('should reject an invalid reference date', function () {
+    const tk = makeTk()
+
+    expect(() => tk.previewSchedule('* * * * *', { from: new Date('nope') })).toThrow(/from/)
+  })
+
+  it('should agree with the expression a schedule was stored with', async function () {
+    ctx.boss = await helper.start({ ...ctx.bossConfig })
+
+    await ctx.boss.schedule(ctx.schema, '0 3 * * *', null, { key: 'daily', tz: 'America/Chicago' })
+
+    const schedule = await ctx.boss.getSchedule(ctx.schema, 'daily')
+
+    helper.assertTruthy(schedule)
+
+    const occurrences = ctx.boss.previewSchedule(schedule.cron, {
+      tz: schedule.timezone,
+      from: new Date('2026-03-01T00:00:00Z'),
+      count: 2
+    })
+
+    expect(occurrences.map(d => d.toISOString())).toEqual([
+      '2026-03-01T09:00:00.000Z',
+      '2026-03-02T09:00:00.000Z'
+    ])
+  })
+})