norc
v1.1.0
Published
Simple cron library for node.js. With failsafes.
Downloads
3
Readme
norc
Simple cron library for node.js. With failsafes.
Installation
Using NPM:
npm install norc
Using yarn:
yarn add norc
Basic usage
const norc = require('norc')
norc.addJob('wakeUp', {
dow: '1-5', // weekday
hour: 7,
minute: 30,
}, () => {
console.log('Rise and shine!')
})
norc.addJob('wakeUpWeekend', {
dow: '6,7', // sutarday, sunday
hour: 9,
minute: 0,
}, () => {
console.log("It's weekend - consider waking up...")
})
setTimeout(() => {
norc.removeJob('wakeUp')
norc.removeJob('wakeUpWeekend')
}, 70e3)
Permanent state
Norc defaults to RAM storage. Everything should work fine until there is a crash. If your node.js crashes, tasks scheduled in the same minute will execute again after restart. To prevent this, you need some kind of permanent storage. Library provides simple way to store state as mtime for specified file, but you can use any method you like.
File storage example
const norc = require('norc')
norc.changeStore(norc.createFileStore('somefilename'))
norc.addJob('wakeUp', {
dow: '1-5', // weekday
hour: 7,
minute: 30,
}, () => {
console.log('Rise and shine!')
})
Custom storage example
Custom storage requires promise returnign true
when current minute has not been executed yet and false
when it has already.
const norc = require('norc')
norc.changeStore((() => {
let lastTs = 0
return (ts) => new Promise(resolve => {
if (ts === lastTs) {
return resolve(false)
}
lastTs = ts
return resolve(true)
})
})()) // we're creating closure here
norc.addJob('wakeUp', {
dow: '1-5', // weekday
hour: 7,
minute: 30,
}, () => {
console.log('Rise and shine!')
})
Error handling
Errors thrown by storage methods can be caught using error
event:
norc.on('error', (e) => {
// your handler goes here...
})
API reference
addJob(name, cronspec, job)
Adds new job to cron according to arguments:
name - name of the job
cronspec - object with following properties:
year - year range
month - month (1 - 12)
day - day of the month (1-31)
hour - hour (0 - 23)
minute - minute (0 - 59)
dow - day of week (1 = monday, 2 = tuesday, ...) all fields are optional and default to
*
, which matches any value. You can specify:ranges:
15-20
- matches any number between 15 and 20 inclusivelists:
1,3,7
- matches numbers 1, 3 and 7lists of ranges:
1-3,5-8
steps:
*/2
- any number divisible by 2job - function that will be invoked every minute matching cronspec criteria. No return value is expected.
removeJob(name)
Removes job from cron:
- name - name of the job to be removed
changeStore(store)
Sets new storage method used to ensure permanent storage of minutes that already passed:
- store is a function that takes parameter
ts
(UNIX timestamp - ms since the unix epoch) and is expected to return Promise. Result of the promise is expected to beBoolean
:true
will cause tasks to run whilefalse
means that tasks for this minute had already run.
There are two stores built in the library:
norc.createMemStore()
(default) - stores state in memory - not safe during crashes - can cause tasks to be executed again in event of process crashnorc.createFileStore(filename)
- creates a store keeping timestamp asmtime
of thefilename
(will be created if not exists)
License
MIT