Merge 3b0b911 into 8694de0

README.md

@@ -730,6 +730,15 @@ agenda.on('fail:send email', function(err, job) {
 
 ## Frequently Asked Questions
 
+### What is the order in which jobs run?
+
+Jobs are run **with priority in a first in first out order** (so they will be run in the order they were queued/created _AND_ with respect to highest priority).  We utilize MongoDB's ObjectID through the job record property of `_id` as a sorting value (since it is a [timestamp](https://docs.mongodb.com/manual/reference/method/ObjectId.getTimestamp/) in itself).
+
+For example, if we have two jobs named "send-email" queued (both with the same priority), and the first job is queued at 3:00 PM and second job is queued at 3:05 PM with the same `priority` value, then the first job will run first if we start to send "send-email" jobs at 3:10 PM. However if the first job has a priority of `5` and the second job has a priority of `10`, then the second will run first (priority takes precedence) at 3:10 PM.
+
+The default MongoDB sort object is `{ _id: 1, priority: -1 }` and can be changed through the option `sort` when configuring Agenda.
+
+
 ### Sample Project Structure?
 
 Agenda doesn't have a preferred project structure and leaves it to the user to
@@ -951,6 +960,7 @@ Agenda has some great community members that help a great deal.
 - [@liamdon](http://github.com/liamdon)
 - [@loris](http://github.com/loris)
 - [@jakeorr](http://github.com/jakeorr)
+- [@niftylettuce](http://github.com/niftylettuce)
 
 
 # License

lib/agenda.js

@@ -24,6 +24,7 @@ var Agenda = module.exports = function(config, cb) {
   this._lockedJobs = [];
   this._jobQueue = [];
   this._defaultLockLifetime = config.defaultLockLifetime || 10 * 60 * 1000; // 10 minute default lockLifetime
+  this._sort = config.sort || { _id: 1, priority: -1 };
 
   this._isLockingOnTheFly = false;
   this._jobsToLock = [];
@@ -640,9 +641,9 @@ Agenda.prototype._findAndLockNextJob = function(jobName, definition, cb) {
 
     /**
     * Query used to affect what gets returned
-    * @type {{returnOriginal: boolean, priority: number}}
+    * @type {{returnOriginal: boolean, sort: object}}
     */
-    var JOB_RETURN_QUERY = { returnOriginal: false, 'priority': -1 };
+    var JOB_RETURN_QUERY = { returnOriginal: false, sort: this._sort };
 
     // Find ONE and ONLY ONE job and set the 'lockedAt' time so that job begins to be processed
     this._collection.findOneAndUpdate(JOB_PROCESS_WHERE_QUERY, JOB_PROCESS_SET_QUERY, JOB_RETURN_QUERY,