chatra:synced-cron

This package is a fork of littledata:synced-cron, maintained under the name chatra:synced-cron.

Define and run scheduled jobs across multiple servers in a synchronized manner using Meteor and MongoDB.

Table of Contents

• Introduction
• Installation
• Usage
  • Adding Jobs
  • Starting the Scheduler
  • Pausing and Stopping
  • Removing Jobs
  • Configuration
• Examples
• Logging
• Tests
• License

---

Introduction

The chatra:synced-cron package allows you to schedule and run cron-like jobs in a Meteor application, synchronized across multiple server instances. It uses MongoDB to store job history and ensures that jobs are not executed multiple times across different servers.

---

Installation

Install the package using Meteor's package manager:

meteor add chatra:synced-cron

---

Usage

Adding Jobs

Define a job by providing a unique name, a schedule, and a job function:

import { SyncedCron } from 'meteor/chatra:synced-cron';

SyncedCron.add({
  name: 'My Job',
  schedule(parser) {
    // Parser is Later.js parser
    return parser.cron('0 * * * *'); // Runs every hour at minute 0
  },
  job(intendedAt) {
    // Your job logic here
    console.log('Running my job at', intendedAt);
    // Return a result if needed
    return 'Job completed';
  },
});

• Parameters:
  • name (string): Unique name for the job.
  • schedule (function): Function that returns a Later.js schedule.
  • job (function): The function to execute at scheduled times.
  • persist (boolean, optional): Whether to persist job history. Defaults to true.

Starting the Scheduler

Start processing the added jobs:

SyncedCron.start();

This should typically be called on the server during startup.

Pausing and Stopping

• Pause: Temporarily stop processing jobs without removing them.

  SyncedCron.pause();

• Stop: Stop processing and remove all jobs.

  SyncedCron.stop();

Removing Jobs

Remove a specific job by its name:

SyncedCron.remove('My Job');

Configuration

Configure SyncedCron by setting options:

SyncedCron.config({
  log: true, // Enable or disable logging
  logger: null, // Provide a custom logger function
  collectionName: 'cronHistory', // Name of the MongoDB collection
  utc: false, // Use UTC time or local time
  collectionTTL: 172800, // Time in seconds for history records to expire (e.g., 48 hours)
});

• Options:
  • log (boolean): Enable or disable logging. Defaults to true.
  • logger (function): Custom logger function. Defaults to console.
  • collectionName (string): Name of the MongoDB collection for job history.
  • utc (boolean): Use UTC time for scheduling. Defaults to false (local time).
  • collectionTTL (number): Time-to-live in seconds for job history records. Set to null to disable expiration.

---

Examples

Scheduling a Job Every Day at Midnight

SyncedCron.add({
  name: 'Midnight Job',
  schedule(parser) {
    return parser.cron('0 0 * * *'); // Every day at midnight
  },
  job() {
    // Job logic
    console.log('Running midnight job');
  },
});

Using a Custom Logger

SyncedCron.config({
  logger(opts) {
    // opts: { level, message, tag }
    console.log(`[${opts.level}] ${opts.tag}: ${opts.message}`);
  },
});

Disabling Job Persistence

SyncedCron.add({
  name: 'Transient Job',
  persist: false, // Do not store job history
  schedule(parser) {
    return parser.cron('*/5 * * * *'); // Every 5 minutes
  },
  job() {
    console.log('Running transient job');
  },
});

---

Logging

By default, SyncedCron logs job start, completion, and errors to the console. You can customize logging behavior:

• Disable Logging:

  SyncedCron.config({
    log: false,
  });

• Custom Logger Function:

  Provide a function to handle log messages:

  SyncedCron.config({
    logger({ level, message, tag }) {
      // Handle log messages
      myCustomLogger.log(level, `${tag}: ${message}`);
    },
  });
  • Parameters:
    • level (string): Log level (info, warn, error, debug).
    • message (string): Log message.
    • tag (string): Tag identifying the source ('SyncedCron').

---

Tests

The package includes a comprehensive test suite. To run the tests:

meteor test-packages ./

---

License

This package is licensed under the MIT License