Merge pull request #13 from lykmapipo/feature/unique_every_job

Feature/unique every job

README.md

@@ -27,7 +27,8 @@ $ npm install --save async lodash kue kue-scheduler
 ## Usage
 
 
-### Schedule a job to run every after specified time interval
+### Schedule a non unique job to run every after specified time interval
+Use this if you want to maintain different(multiple) job instances on every run
 
 Example `schedule a job to run every two seconds from now`
 ```js
@@ -52,7 +53,35 @@ Queue.process('every', function(job, done) {
 });
 ```
 
-### Schedule a job to run only once after specified interval elapsed
+### Schedule a unique job to run every after specified time interval
+Use this if you want to maintain a single job instance on every run.
+
+Example `schedule a job to run every two seconds from now`
+```js
+var kue = require('kue-scheduler');
+var Queue = kue.createQueue();
+
+//create a job instance
+var job = Queue
+            .createJob('unique_every', data)
+            .attempts(3)
+            .backoff(backoff)
+            .priority('normal')
+            .unique('unique_every');
+
+//schedule it to run every 2 seconds
+Queue.every('2 seconds', job);
+
+
+//somewhere process your scheduled jobs
+Queue.process('unique_every', function(job, done) {
+    ...
+    done();
+});
+```
+
+### Schedule a non unique job to run only once after specified interval elapsed
+Use this if you want to maintain different(multiple) job instances on every run
 
 Example `schedule a job to run only once two seconds from now`
 ```js
@@ -77,6 +106,33 @@ Queue.process('shedule', function(job, done) {
 });
 ```
 
+### Schedule a unique job to run only once after specified interval elapsed
+Use this if you want to maintain a single job instance on every run.
+
+Example `schedule a job to run only once two seconds from now`
+```js
+var kue = require('kue-scheduler');
+var Queue = kue.createQueue();
+
+//create a job instance
+var job = Queue
+            .createJob('unique_schedule', data)
+            .attempts(3)
+            .backoff(backoff)
+            .priority('normal')
+            .unique('unique_schedule');
+
+//schedule it to run once 2 seconds from now
+Queue.schedule('2 seconds from now', job);
+
+
+//somewhere process your scheduled jobs
+Queue.process('unique_shedule', function(job, done) {
+    ...
+    done();
+});
+```
+
 
 ### Schedule a job to run now
 ```js
@@ -116,7 +172,7 @@ Queue.enableExpiryNotifications();
 ```
 
 ### `every(interval, job)`
-Runs a given `job instance` every after a given `interval`.
+Runs a given `job instance` every after a given `interval`. If `unique key` is provided only single instance job will exists otherwise on every run new job istance will be used.
 
 `interval` can either be a [human-interval](https://github.com/rschmukler/human-interval) `String` format or a [cron](https://github.com/ncb000gt/node-cron) `String` format.
 
@@ -144,7 +200,7 @@ Queue.process('every', function(job, done) {
 
 
 ### `schedule(when, job)`
-Schedules a given `job instance` to run once at a given time. `when` can either be a `Date instance` or a [date.js](https://github.com/matthewmueller/date) `String` such as `tomorrow at 5pm`.
+Schedules a given `job instance` to run once at a given time. `when` can either be a `Date instance` or a [date.js](https://github.com/matthewmueller/date) `String` such as `tomorrow at 5pm`. If `unique key` is provided only single instance job will exists otherwise on every run new job istance will be used.
 
 ```js
 var kue = require('kue-scheduler');
@@ -193,7 +249,7 @@ Queue.process('now', function(job, done) {
 ```
 
 ## Events
-Currently the only way to interact with `kue-scheduler` is through its events. `kue-scheduler` fires `schedule error`, `schedule success` and `scheduler unknown job expiry key` events.
+Currently the only way to interact with `kue-scheduler` is through its events. `kue-scheduler` fires `schedule error`, `schedule success`, `already scheduled` and `scheduler unknown job expiry key` events.
 
 ### `schedule error`
 Use it to interact with `kue-scheduler` to get notified when an error occur.
@@ -233,6 +289,26 @@ var job = Queue
 Queue.now(job);
 ```
 
+### `already scheduled`
+Use it to interact with `kue-scheduler` to be notified if the current instance of job is unique and already schedule to run.
+
+*Note: Use this event to attach instance level job events* 
+
+```js
+//listen alrady scheduled jobs
+Queue.on('already scheduled', function(job) {
+    ...
+});
+
+var job = Queue
+    .createJob('now', data)
+    .attempts(3)
+    .backoff(backoff)
+    .priority('normal');
+
+Queue.now(job);
+```
+
 ### `scheduler unknown job expiry key`
 Fired when `kue-scheduler` receive unknown key event from redis. Use it to be notified on unknown key(s) events.
 
@@ -264,10 +340,10 @@ It will be nice, if you open an issue first so that we can know what is going on
 
 
 ## TODO
-- [ ] Scheduler restart after shutdown
-- [ ] Reschedule/scan jobs on restart
+- [x] Scheduler restart after shutdown
+- [x] Reschedule/scan jobs on restart
 - [ ] Test multi process scheduler
-- [ ] Support unique reccur jobs
+- [x] Support unique reccur jobs
 
 
 ## License 

examples/every_unique.js

@@ -0,0 +1,68 @@
+'use strict';
+
+/**
+ * @description example of scheduling a unique jobs to run every after specified interval
+ */
+
+//dependencies
+var path = require('path');
+
+//require('kue-scheduler') here
+var kue = require(path.join(__dirname, '..', 'index'));
+var Queue = kue.createQueue();
+
+
+//processing jobs
+Queue.process('unique_every', function(job, done) {
+    console.log('\nProcessing job with id %s at %s', job.id, new Date());
+    done(null, {
+        deliveredAt: new Date()
+    });
+});
+
+
+//listen on scheduler errors
+Queue.on('schedule error', function(error) {
+    //handle all scheduling errors here
+    console.log(error);
+});
+
+
+//listen on success scheduling
+Queue.on('schedule success', function(job) {
+    //a highly recommended place to attach 
+    //job instance level events listeners
+
+    job.on('complete', function(result) {
+        console.log('Job completed with data ', result);
+
+    }).on('failed attempt', function(errorMessage, doneAttempts) {
+        console.log('Job failed');
+
+    }).on('failed', function(errorMessage) {
+        console.log('Job failed');
+
+    }).on('progress', function(progress, data) {
+        console.log('\r  job #' + job.id + ' ' + progress + '% complete with data ', data);
+
+    });
+
+});
+
+//prepare a job to perform
+//dont save it
+var job = Queue
+    .createJob('unique_every', {
+        to: 'any'
+    })
+    .attempts(3)
+    .backoff({
+        delay: 60000,
+        type: 'fixed'
+    })
+    .priority('normal')
+    .unique('unique_every');
+
+
+//schedule a job then
+Queue.every('2 seconds', job);

examples/schedule.js

@@ -20,9 +20,6 @@ Queue.process('schedule', function(job, done) {
     });
 });
 
-//promote unless you use kue version with auto promote
-Queue.promote(3000);
-
 //listen on scheduler errors
 Queue.on('schedule error', function(error) {
     //handle all scheduling errors here

examples/schedule_unique.js

@@ -0,0 +1,68 @@
+'use strict';
+
+/**
+ * @description example of scheduling unique jobs to run once after specified interval
+ */
+
+//dependencies
+var path = require('path');
+
+//require('kue-scheduler') here
+var kue = require(path.join(__dirname, '..', 'index'));
+var Queue = kue.createQueue();
+
+
+//processing jobs
+Queue.process('unique_schedule', function(job, done) {
+    console.log('\nProcessing job with id %s at %s', job.id, new Date());
+    done(null, {
+        deliveredAt: new Date()
+    });
+});
+
+
+//listen on scheduler errors
+Queue.on('schedule error', function(error) {
+    //handle all scheduling errors here
+    console.log(error);
+});
+
+
+//listen on success scheduling
+Queue.on('schedule success', function(job) {
+    //a highly recommended place to attach 
+    //job instance level events listeners
+
+    job.on('complete', function(result) {
+        console.log('Job completed with data ', result);
+
+    }).on('failed attempt', function(errorMessage, doneAttempts) {
+        console.log('Job failed');
+
+    }).on('failed', function(errorMessage) {
+        console.log('Job failed');
+
+    }).on('progress', function(progress, data) {
+        console.log('\r  job #' + job.id + ' ' + progress + '% complete with data ', data);
+
+    });
+
+});
+
+//prepare a job to perform
+//dont save it
+var job = Queue
+    .createJob('unique_schedule', {
+        to: 'any'
+    })
+    .attempts(3)
+    .backoff({
+        delay: 60000,
+        type: 'fixed'
+    })
+    .priority('normal')
+    .unique('unique_schedule');
+
+
+//schedule a job then
+Queue.schedule('2 seconds from now', job);