Skip to main content

Overview

Balda includes a cron job decorator that lets you schedule background tasks directly from your controllers or services. This feature is available only in Node.js compatible environments.

Peer dependency — Balda intentionally leaves the scheduling engine to the community-standard node-cron. To enable cron support you must install it yourself:

# with npm
npm install node-cron

# or with yarn / pnpm / bun
yarn add node-cron
pnpm add node-cron
bun add node-cron

Basic Usage​

import { cron } from 'balda';

class TickCron {
// Run every minute
@cron('* * * * *')
async handle() {
    console.log('Cron executed!');
  }
}

The decorator accepts any valid cron expression supported by node-cron.

Advanced Options​

You can pass an options object as the second argument to control timezone, concurrency, etc.

@cron('0 0 * * *', { timezone: 'UTC' })
async handle() {
  await this.cleanupService.run();
}

Error Handling​

By default, if the decorated method throws, Balda will log the error (using the configured logger) but will not crash your server.

You can set a global cron error handler to handle the errors:

import { setCronGlobalErrorHandler } from 'balda';

setCronGlobalErrorHandler((context) => {
  console.error(context.execution?.error);
  // Send to Sentry, log to file, etc.
});

Starting Cron Jobs​

You can import registered cron jobs classes that have one or more @cron decorated methods or directly import the @cron decorator and use it to decorate your own methods.

import { CronService } from 'balda';

// Import all cron jobs from patterns
await CronService.massiveImportCronJobs(['src/cron/**/*.{ts,js}']);

// Start the cron scheduler
await CronService.run();

console.log('Cron jobs started');

Option 2: Manual import​

import { CronService } from 'balda';
import './cron/specific_cron_job.js';

// Start the cron scheduler
await CronService.run();