DOCSEARCHbyAlgolia
Submit Docs

Pulse Job Scheduler

repository·main·Indexed 41 days ago

https://github.com/pulsecron/pulse

A modern, MongoDB-powered job scheduling library for Node.js and a maintained successor to the Agenda project. Pulse provides resilient task management with features including exponential and fixed backoff retry logic, resumable tasks after system restarts, and full compatibility with the latest MongoDB drivers. It supports complex job orchestration through methods for defining job types, managing concurrency, and scheduling recurring tasks via cron patterns or human-readable intervals.

Tokens
20.6K
Snippets
67
Records
109
Agent score
49%

What's inside Pulse

  1. What is Pulse?

    main

    Pulse is an open-source job scheduling tool for the Node.js ecosystem. It is a fork of the discontinued Agenda project and uses MongoDB to manage job data, making it suitable for high-scale applications.

    Key capabilities include:

    • Resilience: Automatically resumes incomplete or queued tasks after a system restart.
    • Retry Logic: Supports configurable retry mechanisms using both exponential and fixed backoff strategies.
    • Modern Compatibility: Fully compatible with the latest MongoDB drivers.
    • Scalability: Designed for scenarios ranging from simple automation to complex job orchestration in distributed systems.

  2. Overview of Pulse

    main
    Pulse is a modern MongoDB-powered job scheduler library for Node.js. It is a fork of the Agenda project, designed to provide advanced functionalities, improved scalability, and contemporary features for complex scheduling challenges. It is actively maintained and used in production services.

  4. Unique Features in Pulse

    main

    Pulse provides several key features for reliable job scheduling:

    • Latest MongoDB Driver Support: Full compatibility with the latest MongoDB driver features.
    • Resumable Tasks: Automatically resumes incomplete or queued tasks after a system restart.
    • Retry Mechanisms: Supports configurable retry attempts using both exponential backoff and fixed backoff strategies.
    • Production Ready: Actively maintained and used in production environments.

  5. Initialize Pulse with MongoDB

    main

    To initialize a new Pulse instance, import Pulse and provide a database configuration. You can provide a MongoDB connection string, override the default collection name, pass additional connection options, or provide an existing MongoClient instance.

    Supported configuration patterns:

    • Connection String: Use the db.address key.
    • Custom Collection: Use the db.collection key.
    • Connection Options: Use the db.options key (e.g., for SSL).
    • Existing Client: Pass a mongo property containing a native MongoClient instance.
    import Pulse from '@pulsecron/pulse';

const mongoConnectionString = 'mongodb://localhost:27017/pulse';

// Basic initialization
const pulse = new Pulse({ db: { address: mongoConnectionString } });

// With custom collection and options
// const pulse = new Pulse({db: {address: mongoConnectionString, collection: 'jobCollectionName', options: {ssl: true}}});

// Using an existing MongoClient
// const pulse = new Pulse({mongo: myMongoClient});

  6. Schedule a job using `job.schedule(time)`

    main

    Use the schedule method to set a job to run at a specific time. The method accepts either a Date object or a date string.

    Important: Calling schedule() does NOT persist the job to the database. To ensure the scheduled job is saved, you must explicitly call await job.save() after scheduling.

    const job = pulse.create('test', {});
job.schedule(new Date(2023, 11, 17, 10, 30));  
await job.save(); // Required to persist the schedule to the database

  7. Disable a job using `job.disable()`

    main

    The disable() method sets a job's status to disabled, which prevents the job processing system from executing it. This is intended for temporarily halting a job without deleting it from the queue.

    Important: Calling disable() does NOT automatically persist the change to the database. To ensure the job remains disabled after the current process finishes, you must explicitly call job.save().

    const job = pulse.create('test', {});
job.disable();
job.save(); // Required to persist the disabled status to the database

  8. Create a new job instance with `pulse.create(name, data)`

    main

    Use the pulse.create(name, data) method to generate a new job instance. This method allows you to customize job parameters before scheduling or execution.

    Important: Calling create does NOT automatically save the job to the database. To persist the job, you must explicitly call the .save() method on the returned job instance.

    const pulse = new Pulse();

// Create a new job for data analysis
const analysisJob = pulse.create('dataAnalysis', { datasetId: 101 });

// You must call save() if you want the job to be persisted in the database
analysisJob.save();

  11. Configure job uniqueness with `job.unique()`

    main

    Use the job.unique(filter, options?) method to prevent duplicate job entries in the database. This method ensures that no other job exists that matches the provided MongoDB filter criteria.

    Important: Calling .unique() does NOT persist the job to the database. You must explicitly call .save() to commit the job with its uniqueness constraints.

    const job = pulse.create('test', {});
job.unique({ 'data.type': 'email', 'data.userId': '12345' });
await job.save(); // Required to persist the job

  12. Schedule a job to run immediately with `pulse.now()`

    main

    Use the pulse.now(name, data?) method to schedule a job for immediate execution. This is useful for high-priority tasks that need to be processed as soon as possible. The method creates a job instance and schedules it for the current time. Note that execution timing may be affected if the job queue is full or if other jobs are already scheduled for the same timestamp.

    Parameters:

    • name (string): The name of the job to be scheduled. This must match a job type previously defined using the define method.
    • data (T, optional): The payload or data required by the job for its execution.
    const pulse = new Pulse();

// Schedule a job to run immediately to handle a high priority update
pulse.now('urgentUpdate', { updateDetails: 'Fix critical security issue' })