Programmatic API

The cron() factory lets you schedule recurring jobs without decorators, throwaway classes or massiveImport* glob imports. It returns a handle you can start, stop and destroy directly.

Prefer the programmatic API for new code. The @cron decorator remains fully supported and is useful when you want a class-based cron job with a scoped logger.

Usage

import { cron } from "balda";

const cleanup = cron("*/2 * * * *", {
  name: "cleanup",
  timezone: "Europe/Rome",
});

await cleanup.start(() => {
  console.log("Cleaning up...");
});

// Later, stop the job
cleanup.stop();

The handle

cron() returns a CronHandle with:

Method	Description
name	The unique job name (used for identification and the cron UI).
start(fn)	Schedules the job with the given handler. Throws if already started.
stop()	Pauses the job. It can be restarted with start().
destroy()	Stops the job and releases its resources.

const job = cron("* * * * *", { name: "metrics" });

await job.start(async () => {
  await collectMetrics();
});

job.stop();      // pause
await job.start(collectMetrics); // resume
job.destroy();   // fully release

Options

import { cron } from "balda";

const job = cron("0 0 * * *", {
  name: "nightly-sync",
  timezone: "UTC",
  onFailed: (context) => {
    console.error("Sync failed", context.execution?.error);
  },
});

• name — required when used programmatically. Uniquely identifies the job.
• timezone — IANA timezone the schedule is expressed in.
• onFailed — per-job error handler. Falls back to the global handler when omitted.

Works as a decorator too

cron() doubles as the @cron decorator. The name is derived from the class and method when not supplied:

class Cleanup {
  @cron("0 0 * * *", { name: "cleanup" })
  run() {
    console.log("Cleaning up...");
  }
}

Bootstrap with the Server

When using the Server, you can wire cron jobs through the background option so they start automatically on listen():

import { Server } from "balda";

const server = new Server({
  background: {
    crons: [
      {
        schedule: "*/10 * * * *",
        options: { name: "heartbeat" },
        handler: () => console.log("alive"),
      },
    ],
  },
});

This is an explicit alternative to CronService.massiveImportCronJobs() + CronService.run().