@robojs/cron - Plugin for task scheduling

[Pkmmte]

Description

A plugin to provide cron scheduling for Robo.js, leveraging the croner npm package. It supports persistence via Flashcore, the built-in key-value database of Robo.js. Users can create cron jobs using either files or code, with a JavaScript API for traditional programmatic usage.

Goals:

• Build on top of croner for the main scheduling functionality.
• Support Flashcore for persistence of cron jobs.
• File-based and JavaScript API for flexibility in defining cron jobs.
• Simple, aesthetically pleasing API similar to croner.
• Lightweight and minimal additional packages.

Key Points:

• Croner Integration: Use croner for cron syntax parsing, job creation, and scheduling. All cron jobs inherit the same methods as a Croner object, providing full functionality such as .pause(), .nextRun(), etc.
• Persistence Support: Only file-based jobs can be persisted to Flashcore. If the referenced job file no longer exists, a warning is logged.
• File-Based Jobs: Users can define cron jobs in files, providing flexibility and allowing easy persistence without serialization.
• JavaScript API: Developers can use the JavaScript API to define cron jobs programmatically.
• Compatibility: Plugin must be fully TypeScript compliant for easy integration.

API and Options Overview

The @robojs/cron plugin provides two main APIs:

• File-Based API: Users define cron jobs by creating files at specific paths, similar to node fs module. Only file-based jobs can be persisted.

• JavaScript API: Developers can use the JavaScript API to define cron jobs programmatically, but these jobs cannot be persisted as functions are not serializable.

• Cron Jobs Setup:

  • Accepts standard cron syntax ("0 9 * * 1" for every Monday at 9 AM).
  • The function to execute can be defined inline or through a reference to a file path (cron(time, 'path-to-file')).
  • File-based jobs can be persisted using .save() with an optional unique ID for easy management.

• Persistence:

  • All persisted jobs are restored automatically from Flashcore on startup through the plugin's _start event file.
  • If the file being referenced is missing, a warning will be logged with a reference to the missing job ID.
  • Use .save(id) to persist a job, where id is an optional unique identifier. If no id is provided, an auto-generated ID will be returned.
  • Use .remove(id) to delete a persisted job from Flashcore.

• Generated ID: Each persisted cron job is assigned an auto-generated ID for future management (e.g., deletion).

Example Usage

import { Cron } from '@robojs/cron'

// Direct usage
const jsJob = Cron("0 12 * * *", () => {
  console.log("This job runs every day at noon!")
})

// File-Based Cron Job
const job = Cron("0 9 * * 1", "jobs/specialJob.js")
job.save("uniqueJobID")  // Save with a specific ID
const jobId = job.save()  // Auto-generate and return an ID
Cron.remove("uniqueJobID")  // Remove the job later

// Using Croner Functions
job.pause()  // Pause the job
job.nextRun()  // Get the next run time

Job Persistence

The plugin includes a _start event file that automatically restores all persisted cron jobs at startup. If a job file reference is missing, the plugin will log a warning with details about the missing job ID.

The _start event will look up Flashcore for all existing jobs and recreate them using the croner API. This guarantees continuity, even after a server restart. Only file-based jobs can be persisted, which allows the plugin to restore them without needing to serialize inline functions. Persisted jobs can be saved using .save() and removed using .remove(id) when no longer needed.

Third Party Packages

• Croner: For cron scheduling.
• Flashcore (built-in with Robo.js): Used for persistence of jobs.
• Avoid large npm packages to keep the plugin lightweight. Only use croner for scheduling and Flashcore for persistence.