every

In-memory job schedule library for simple Node.js projects.

• interval based or time based scheule job.
• multiple run mode of job function: normal, worker, or async functions
• no external storage is required

Usage

Example:

function something() {...}

every.mins(15).do( something )

every.run({
  begin:()=>{console.log("Runner start...")},
  beforeStop:()=>{console.log("Runner stop...")}
})
process.on("SIGINT",()=>{
  every.stop()
})

Interval based jobs

Define jobs which will run after an interval of time has passed after the previous finish time.

function something() { ...}

// define a job which does something every 30 mins
every.minutes(30).do( something )

Time based jobs

Define jobs which will run every time a specific time or times meet. The string expressing the specific times is called tick.

• If the minute is not specified, it will be assumed that the job will run at minute "00".
• If the hour is not specified, it will be assumed that the job will run every hour.
• If the day or week is not specified, it will be assumed that the job will run every day.

// Define a job which does something every time the system clock shows 30 in the minute's position.
every.minute("30").do(something)

// Define a job which does something every time the system clock shows 1 in the hour's position and 15 in the minute's position.
every.hour("01").minute("15").do(something)

• The tick can be defined as mulitple value with seperating by space.

// Define a job which does something every time 
// the system clock shows 1 or 13 in the hour's position and 15 or 45 in the minute's position.
// That is, the job will run at 01:15 , 01:45, 13:15 and 13:45 every day.
every.hour("01 13").minute("15 45").do(something)

• The tick of week may accept the sunday, monday, ..., and saturday. Short form such as sun, mon, ... and sat may be also accepted.
• If ticks of both week and day are defined, the library will combine (union) them.

// Define a job which does someting at 14:20 on every Monday and Friday.
every.week("Monday Fri").hour("14").minute("20").do(something)

// Define a job which does something at 03:00 on every 10th and 20th and Sundays.
every.week("sun").day("10 20").hour("03").do(something)

• The tick of day can be assigned with a special value monthend which represent the month end of a month.

// Define a job which does something at 00:00 on every month end.
every.day("monthend").hour('00').do(something)

// Define a job which does something at 03:00 on every 15th and month end.
every.day("15 monthend").hour('03').do(something)

Jobs run mode

There are 3 types of run mode of every to execute a job.

• normal mode: with .do( fn ) method to run a normal JS function.
• worker mode: with .doWorker('path/script.js', data, cb(..)) method to run a worker_threads script file.
• async mode: with .do( asyncFn ) method to run a async/await JS function.

function fn() {console.log("It works!")}
async function asyncFn() { let res = await fetch('...'); return res;}

every.mins(10).do(fn)
every.mins(10).do(asyncFn)
every.mins(10).doWorker("./worker.js")

Pre-processing

You may define a preprocessing function with pre before the job execution.

every.mins(10).pre( preparation ).do( something)

Data passing to jobs

You may require to pass values to a job function every time for

• job function reusablity or generalization.
• different handling for different situation at the moment the job function executed.

If you just have a generalized job function for two different cases, you may hard code a wrapper of the job function.

// a generalized function 
function task(case:number){
  if(case == 0) { ... }
  if(case == 1) { ... }
}

// since the case is fixed for each job, we directly hard-code it.
every.mins(10).name('case-0').job(()=>{task(0)})
every.mins(15).name('case-1').job(()=>{task(1)})

You may directly define with .data attr.

// define job for case = 0
let job1 = every.mins(10)
job1.data = {case:0}
job1.do(function(){task(this.data.case))

// define job for case = 1
let job2 = every.mins(15)
job2.data = {case:1}
job2.do((data)=>{task(data.case)})

However, if your use case requires dynamical assignment of the values to the job function every time, you may need pre.

// the job's behavior depends on the value of minutes of the system clock.
every.mins(1).name('case-x').pre((q)=>{
  let x = new Date().getMinutes() % 2
  q.data = {case : x}
}).do((data)=>{
  task(data.case)
})

Name of jobs

Every job have its name. If not provided, the name may be guessed from job function name. It may be empty string if the name cannot be guess from job function name.

Define the name of a job with name. If define two jobs with the same name, the name will only represent the last defined one.

every.mins(10).name('peter').do( somethingGood ) // it will not be run.
every.mins(20).name('peter').do( somethingBad ) // it will be the queue to run.

Hooks

Hooks for runner and hooks for tasks.

• hooks.begin a hook when the runner just being called
• hooks.beforeCreate a hook before the global queue list created
• (sync GlobalQueueDictionary to GlobalQueueList)
• hooks.created a hook after global queue list created
• (timer for timetick based queues loop created)
• (timer for interval based queues loop created)
• hooks.timetickStep a hook on a new timetick step reach
• hooks.intervalStep a hook on a new interval step reach
• hooks.enter a hook on task begin
• hooks.leave a hook on task complete
• hooks.beforeStop a hook when the runer stop being called
• hooks.timetickKilled a hook when timetick based tasks loop timer killed
• hooks.intervalKilled a hook when interval based tasks loop timer killed

The hooks may be defined in the every.run(hooks) at design time.

Example:

every.hour("01 13").minute("15 45").do(something);

every.run({
  begin:()=>{console.log("runner start..")}
})

Examples

Scheduling jobs:

function something() = {...}

// define a job which does something every 30 mins
every.minutes(30).do(something)

// define a job which does something every 120 mins (i.e. every 1.5 hr)
every.minutes(120).do(something)

// define a job which does something every hour.
every.hours(1).do(something)

// define a job which does something every day. 
every.days(1).do(something)

// define a job which does something every 7 days.
every.days(7).do(something)

// define a job which does something every time the system clock shows 30 in the minute's position.
every.minute("30").do(something)

// define a job which does something every time the system clock shows 1 in the hour's position and 14 in the minute's position.
every.hour("01").minute("15").do(something)

// define a job which does something every time the system clock shows 3 in the hour's position on the 3rd day of a month.
every.day("03").hour("00").do(something)

// define a job which does something every time the system clock shows 0 in the hour's position and 45 in the minute's position on the end of a month.
every.day("monthend").hour("00").minute("45").do(something)

// define a job which does something every time the system clock shows 14 in the hour's position and 20 in the minute's position on Sundays.
every.week("sunday").hour("14").minute("20").do(something)

Reference

Job Scheduling for Python

https://schedule.readthedocs.io/en/stable/

Job Scheduling for Node.js

https://blog.logrocket.com/comparing-best-node-js-schedulers/

Oracle Schedule

https://docs.oracle.com/cd/B31315_01/190/JOS%20Implementation%20Guide/Output/scheduler.htm