@cleverbrush/scheduler

A job scheduler for Node.js that runs tasks in worker threads on configurable schedules.

Installation

npm install @cleverbrush/scheduler
Copy

This library uses the Node.js worker_threads module. It is tested on Node.js v16+.

Quick Start

import { JobScheduler } from '@cleverbrush/scheduler';

const scheduler = new JobScheduler({
    rootFolder: '/path/to/your/jobs'
});

scheduler.addJob({
    id: 'my-job-1',
    path: 'job1.js',
    schedule: {
        every: 'minute',
        interval: 5
    }
});

scheduler.addJob({
    id: 'my-job-2',
    path: 'job2.js',
    schedule: {
        every: 'week',
        interval: 2,
        dayOfWeek: [1, 3, 5],
        hour: 9,
        minute: 30
    },
    timeout: 1000 * 60 * 4,
    maxRetries: 3
});

scheduler.start();
Copy

API

JobScheduler

The main class for scheduling and running jobs. Extends EventEmitter.

Constructor

const scheduler = new JobScheduler(props: JobSchedulerProps);
Copy

Methods

Events

scheduler.on('job:start', ({ jobId, instanceId, startDate }) => {
    console.log(`Job ${jobId} started`);
});

scheduler.on('job:end', ({ jobId, instanceId, startDate, endDate, stdout, stderr }) => {
    console.log(`Job ${jobId} finished`);
});

scheduler.on('job:error', ({ jobId, instanceId, startDate, endDate, stdout, stderr }) => {
    console.error(`Job ${jobId} failed`);
});

scheduler.on('job:timeout', ({ jobId, instanceId, startDate, endDate }) => {
    console.warn(`Job ${jobId} timed out`);
});

scheduler.on('job:message', ({ jobId, instanceId, message }) => {
    console.log(`Message from ${jobId}:`, message);
});
Copy

Job Configuration

scheduler.addJob({
    id: 'unique-job-id',
    path: 'relative/path/to/job.js',
    schedule: { /* see Schedule Types */ },
    timeout: 60000,                // timeout in milliseconds
    maxRetries: 3,                 // retry on failure
    maxConsequentFails: 10,        // disable after N consecutive failures
    noConcurrentRuns: true,        // prevent overlapping executions
    props: { key: 'value' }        // data passed to the worker
});
Copy

Schedule Types

All schedules share these optional properties:

Minute

{ every: 'minute', interval: 5 }
Copy

Runs every N minutes.

Day

{ every: 'day', interval: 1, hour: 9, minute: 30 }
Copy

Runs every N days at the specified time.

Week

{ every: 'week', interval: 2, dayOfWeek: [1, 3, 5], hour: 9, minute: 30 }
Copy

Runs every N weeks on the specified days (1 = Monday, 7 = Sunday).

Month

{ every: 'month', interval: 1, day: 15, hour: 0, minute: 0 }
// or on the last day of the month:
{ every: 'month', interval: 1, day: 'last', hour: 0, minute: 0 }
Copy

Runs every N months on the specified day (1–28 or 'last').

Year

{ every: 'year', interval: 1, month: 6, day: 1, hour: 12, minute: 0 }
Copy

Runs every N years on the specified month (1–12) and day (1–28 or 'last').

License

BSD-3-Clause