@yaebal/cron

pnpm add @yaebal/cron

import { cron } from "@yaebal/cron";

bot.install(
  cron({
    tz: "Europe/Moscow", // default zone for every job below; UTC if omitted
    jobs: {
      digest: {
        schedule: "0 9 * * *", // every day at 09:00 local
        task: async () => {
          await bot.api.sendMessage({ chat_id: adminId, text: "good morning" });
        },
        retries: 2,
        timeoutMs: 10_000,
      },
      heartbeat: {
        schedule: 30_000, // every 30s
        task: () => probe.ping(),
      },
    },
  }),
);

// the plugin also decorates ctx.cron — any handler can reach trigger/pause/resume/states/nextRuns
bot.command("run-digest", async (ctx) => {
  await ctx.reply(`digest: ${await ctx.cron.trigger("digest")}`);
});

import { createCron } from "@yaebal/cron";

const jobs = createCron()
  .job("cleanup", "*/15 * * * *", () => cleanupExpiredSessions())
  .job("digest", "0 9 * * *", sendDailyDigest, { timeoutMs: 60_000 });

jobs.start();
// ...
await jobs.stop();

import { cron, cronAdmin } from "@yaebal/cron";

bot
  .install(cron({ jobs: { digest: { schedule: "0 9 * * *", task: sendDailyDigest } } }))
  .install(cronAdmin({ isAdmin: (ctx) => ctx.from?.id === adminId }));

// /cron                — every job's state: paused/running, run/failure counts, next & last run
// /cron run digest      — trigger a job immediately, respecting its overlap policy
// /cron pause digest     — stop its automatic schedule (trigger() still works)
// /cron resume digest    — restart it
// /cron next digest      — preview its next 3 scheduled fire times

cron({
  tz: "Europe/Moscow", // default zone for every job — UTC if omitted
  jobs: {
    // inherits the "Europe/Moscow" default above
    digest: { schedule: "0 9 * * *", task: sendDailyDigest },
    // overrides it per job
    nyReport: { schedule: "0 17 * * *", task: sendReport, tz: "America/New_York" },
  },
});
// resolved per-instant via Intl — DST-correct, no timezone database bundled.
// a wall-clock time that's skipped on a spring-forward day is simply never matched.

jobs.job(
  "syncInventory",
  "*/5 * * * *",
  async (ctx) => {
    // ctx.attempt is 1 on the first try, 2 on the first retry, ...
    await fetch("https://example.com/inventory", { signal: ctx.signal });
  },
  {
    retries: 2, // up to 2 extra attempts after the first failure
    retryDelayMs: (attempt) => attempt * 1_000, // 1s, then 2s
    timeoutMs: 10_000, // races the task; the scheduler stops waiting either way
  },
);
// only the FINAL attempt counts toward state().failures and calls onError —
// an eventual success after retries is not a failure.

jobs.job("sync", 5_000, syncInventory, { overlap: "wait" });
// "skip"  (default) drops a run that arrives while the previous one is still going.
// "wait"  queues exactly one run to fire right after the current one finishes.
// "allow" fires concurrently — no skipping or queueing at all.

import { fileStorage } from "@yaebal/sklad/file";

const jobs = createCron({ store: fileStorage("./cron-state.json") })
  .job("digest", "0 9 * * *", sendDailyDigest, { catchUp: true });
// with catchUp + a store, a missed occurrence (the process was down at 09:00) fires
// once at the next start() instead of silently vanishing until tomorrow.
// store only needs get/set (delete optional), sync or async — any @yaebal/sklad
// adapter (MemoryStorage, redisStorage, sqliteStorage, kvStorage, fileStorage) works.

const jobs = createCron({
  // one instance wins per job name; the rest skip that fire with reason: "lock"
  acquireLock: async (name) => {
    const acquired = await redis.set(`lock:${name}`, "1", "NX", "PX", 30_000);
    return acquired ? () => redis.del(`lock:${name}`) : false;
  },
}).job("digest", "0 9 * * *", sendDailyDigest);
// no backend bundled — wire it to redis, postgres advisory locks, or whatever your fleet has.
// a throwing/rejecting hook is treated as "denied", never as a scheduler crash.

jobs.pause("digest");             // stop its automatic schedule; trigger() still works
jobs.resume("digest");            // re-arm it
jobs.reschedule("digest", "0 8 * * *"); // swap the schedule in place, re-arms immediately
jobs.remove("digest");            // unregister it and clear its timer
jobs.nextRuns("digest", 3);       // preview the next 3 fire times, without arming anything

const jobs = createCron({
  onEvent: (event) => console.log(event.type, event),
  graceful: true,
  drainTimeoutMs: 30_000,
});
// scheduled / run_started / run_completed / run_failed / run_retry /
// run_skipped (reason: "overlap" | "lock") / run_timeout / store_error / schedule_error
// every event carries `at`; run-scoped ones carry `run`/`attempt` too.

import { createCron } from "@yaebal/cron";
import { installTestClock } from "@yaebal/test";

const jobs = createCron().job("digest", 60_000, sendDigest);
await jobs.trigger("digest"); // run it once, right now, bypassing the schedule — resolves "ran"

// schedule-driven behavior (start(), timers, retry delays): drive the virtual clock
const clock = installTestClock();
try {
  jobs.start();
  await clock.advance(60_000);
  assert.equal(jobs.state("digest")?.runs, 1);
} finally {
  clock.restore();
}