@arkstack/scheduler

Task scheduling for Arkstack. Define scheduled tasks fluently in code instead of managing a crowd of cron entries — a single system cron entry drives everything.

Install

pnpm add @arkstack/scheduler
ark publish --package @arkstack/scheduler   # writes src/routes/console.ts

Full app templates include it and a src/routes/console.ts already.

Define your schedule

In src/routes/console.ts:

import { Schedule } from '@arkstack/scheduler'

Schedule.command('cache:prune').hourly()

Schedule.call(async () => {
  await pruneTempFiles()
})
  .dailyAt('01:30')
  .withoutOverlapping()

Schedule.job(new SendDigest()).weeklyOn(1, '08:00')

Schedule.exec('backup.sh').daily().onOneServer()

Run it

The scheduler evaluates due tasks once a minute. In production, add one cron entry:

* * * * * cd /path/to/app && npx ark schedule:run >> /dev/null 2>&1

During development, run the foreground worker instead:

ark schedule:work    # evaluates the schedule every minute until stopped
ark schedule:list    # list tasks with their next run time

Frequencies

Schedule.command('x').everyMinute()
Schedule.command('x').everyFiveMinutes() // */5 * * * *
Schedule.command('x').everyThirtyMinutes()
Schedule.command('x').hourly()
Schedule.command('x').hourlyAt(15)
Schedule.command('x').daily()
Schedule.command('x').dailyAt('13:00')
Schedule.command('x').twiceDaily(1, 13)
Schedule.command('x').weekly()
Schedule.command('x').weeklyOn(1, '8:00') // Monday 08:00
Schedule.command('x').monthly()
Schedule.command('x').monthlyOn(15, '17:00')
Schedule.command('x').quarterly()
Schedule.command('x').yearly()
Schedule.command('x').cron('*/10 9-17 * * 1-5') // raw cron

Day-of-week constraints, with time layered on top:

Schedule.command('x').weekdays().at('9:00')
Schedule.command('x').weekends().hourly()
Schedule.command('x').mondays()
Schedule.command('x').days([1, 4]) // Monday & Thursday

Set the timezone the expression is evaluated in:

Schedule.command('x').dailyAt('09:00').timezone('America/New_York')

Constraints

Schedule.command('x')
  .daily()
  .when(async () => await featureEnabled('reports')) // run only when truthy
  .skip(() => isHoliday()) // skip when truthy
  .environments('production', 'staging') // limit by APP_ENV
  .between('09:00', '17:00') // only within a daily window

unlessBetween('22:00', '06:00') runs outside a window (overnight ranges handled).

Overlaps, single-server & background

Schedule.command('report:build').everyFiveMinutes().withoutOverlapping()
Schedule.exec('backup.sh').daily().onOneServer()
Schedule.exec('long-import.sh').daily().runInBackground()

withoutOverlapping() and onOneServer() coordinate through @arkstack/cache, so they work across processes and servers. Configure a shared cache store (redis or database) for onOneServer() to be effective; without a cache the scheduler falls back to a process-local lock.

Hooks

Schedule.command('report:build')
  .daily()
  .before(() => logger.info('building report'))
  .onSuccess(() => notifyOk())
  .onFailure((error) => notifyFailed(error))
  .after(() => logger.info('done'))

API

• Schedule.command / call / job / exec — register a task, returns a ScheduledEvent for chaining.
• Schedule.events() / Schedule.dueEvents(date?) — inspect registered / due events.
• ScheduledEvent — the fluent builder (frequencies, day constraints, timezone, when, skip, environments, between, unlessBetween, withoutOverlapping, onOneServer, runInBackground, before/after/onSuccess/onFailure, description, name).
• Commands: schedule:run, schedule:work, schedule:list.

Cron evaluation is powered by croner. See the scheduling guide for the full walkthrough.

License

MIT