Skip to content

Latest commit

 

History

History
131 lines (93 loc) · 5.22 KB

README.md

File metadata and controls

131 lines (93 loc) · 5.22 KB
Raw

xnode-scheduler

NPM Version NPM Downloads

Simple In-memory Node.js job scheduler library to execute tasks within fixed intervals

  • Useful to run sync/async(promise based) jobs every fixed interval with delay 'x'. Uses NodeJS SetInterval under the wraps.
  • Not suitable to run cron expressions yet
  • Supports milliseconds, seconds, minutes, hours, days as inputs. Range of delays supported : 1 millisecond to 2147483646 milliseconds
  • Created in Typescript.
  • No dependency on any external package
  • Does not support caching
  • Created for NodeJS. Not yet tested for browsers.

Getting started

Installation:

npm i xnode-scheduler

Usage Example:

const { JobStatus, IntervalBasedJob, XnodeScheduler } = require('../dist/index');

// Create Scheduler instance
const scheduler = new XnodeScheduler();

// Define job and errorHandler(optional)
const fn = function() { counter++}
const errorHandler = function(error){ console.log(error.message )}

// Create Jobs
const j1 = new IntervalBasedJob('j1', fn, { seconds: 1 });
const j2 = new IntervalBasedJob('j2', fn, { hours: 2 }, {
    async: true,
    errorHandler: (error)=>{console.log(error)},
    runImmediately: true
});

// Add Jobs to scheduler
scheduler.addJob(j1);
scheduler.addJob(j2);

scheduler.removeJob('jn'); // Removes and stops the job

scheduler.getJob('jx') // throws error for non existent Job ID

const test = scheduler.getJob('j1');
assert(test instanceof IntervalBasedJob);

// Stop a particular job
scheduler.stopJob('j1');

// Job Statuses mapped to JobStatus Enum
assert(j1.status === JobStatus.STOPPED);

// Individual Jobs can also be stopped directly through Job instance
j2.stop();

// Scheduler Status
scheduler.status();

// Stop All running jobs
scheduler.stop()

Notes for Usage

  • For asyncronous Jobs, we need to provide async : true within JobOptions. Using sync tasks with async:true might lead to unhandled rejections.
  • This library does not do throttling or caching.
  • Firing too many async Jobs in a short interval might lead to queuing up requests - leading to low performance. Delays should be used with caution.
  • For Async Jobs, it is highly recommended to use promise chaining instead of async/await pattern within function definition. This is to avoid memory leaks due to calling contexts.

Error Handling

  • For both sync/async, JobOptions has errorHandler function which takes e: Error parameter.
  • This is optional and if not provided (or falsy), default error handler will print the Job ID + error message to console.
  • For Async Jobs, the error handler function is appended to the function chain as a .catch() block at the end.

API Documentation

IntervalBasedJob

  • constructor(id: string, fn, intervalOptions: IntervalOptions, jobOptions: JobOptions)

    • id: Unique Job ID to be used to Query Jobs and stop/remove
    • fn: Task function definition - can be sync/async function
    • intervalOptions: Interval timer settings. API described below
    • jobOptions: Job Settings. API described below

  • id and status can be accessed directly.

  • status: JobStatus - stores the status of the job, which can be NOT_STARTED, RUNNING, STOPPED. JobStatus enum can be used to validate status at any state.

  • start(): void - starts, or restarts (if it's already running) the job;

  • stop(): void - stops the job. Can be restarted again with start command

  • A Job can be started and stopped any number of times.

IntervalOptions

  • days?: number - how many days to wait before executing the job for the next time
  • hours?: number - how many hours to wait before executing the job for the next time
  • minutes?: number - how many minutes to wait before executing the job for the next time
  • seconds?: number - how many seconds to wait before executing the job for the next time
  • milliseconds?: number - how many milliseconds to wait before executing the job for the next time

JobOptions

  • async?: boolean - Whether the task is asynchronous
  • errorHandler?: Fn(e:Error) - Error handler for each invocation. Optional - By default - it prints Job ID and error message to console.
  • runImmediately?: boolean - If true, Job's first run will be immediately when started. By default - it is undefined.

XnodeScheduler

  • A scheduler instance can have only 1 job by a unique name.
  • addJob(j: JobSync | JobAsync) : void - Add Job by ID within scheduler and Start it.
  • getJob(id: string): JobSync | JobAsync - Get Job by ID. For invalid IDs , error is thrown
  • startJob(id: string): void - Start a Job by ID. For invalid IDs, error is thrown
  • stopJob(id: string): void - Start a Job by ID. For invalid IDs, error is thrown
  • removeJob(id: string) - Stops the given job and removes it from scheduler. For invalid IDs , No error is thrown.
  • stop(): void - Stop all jobs in scheduler
  • status() - Returns a POJO representing various metrics related to current statuses of all jobs.