Promise rewrite (#557)

Rewrite Agenda API support promises. This is a breaking change.

No more callbacks! Instead of:

```
function graceful() {
  agenda.stop(function() {
    process.exit(0);
  });
}
```

You need to:
```
async function graceful() {
  await agenda.stop();
  process.exit(0);
}
```

You don't anymore have to listen for `start` event. Instead you can do:
```
await agenda.start();
agenda.every('10 minutes', 'example');
```

However, this will still work:
```
agenda.on('ready', function () {
  agenda.every('10 minutes', 'example');
  agenda.start();
});
```

See the documentation for more!

Drops support for Node.js versions 4, 5, 6

Contains also other small fixes:
- Jobs _emit_ errors instead of throwing them
- Fixes some flaky tests
- Adds docs generator (`npm run docs` to generate `/docs`)

.gitignore

@@ -1,3 +1,5 @@
 node_modules
 coverage.html
-.idea
+.idea
+.DS_Store
+docs

.jsdoc.json

@@ -0,0 +1,23 @@
+{
+    "tags": {
+        "allowUnknownTags": true,
+        "dictionaries": ["jsdoc"]
+    },
+    "source": {
+        "include": ["lib", "package.json", "README.md"],
+        "includePattern": ".js$",
+        "excludePattern": "(node_modules/|docs)"
+    },
+    "plugins": [
+        "plugins/markdown"
+    ],
+    "templates": {
+        "referenceTitle": "Agenda"
+    },
+    "opts": {
+        "destination": "./docs/",
+        "encoding": "utf8",
+        "recurse": true,
+        "template": "./node_modules/jsdoc-template"
+    }
+}

README.md

@@ -56,14 +56,14 @@ agenda.define('delete old users', function(job, done) {
   User.remove({lastLogIn: { $lt: twoDaysAgo }}, done);
 });
 
-agenda.on('ready', function() {
-  agenda.every('3 minutes', 'delete old users');
+(async function() { // IIFE to give access to async/await
+  await agenda.start();
 
-  // Alternatively, you could also do:
-  agenda.every('*/3 * * * *', 'delete old users');
+  await agenda.every('3 minutes', 'delete old users');
 
-  agenda.start();
-});
+  // Alternatively, you could also do:
+  await agenda.every('*/3 * * * *', 'delete old users');
+})();
 
 ```
 
@@ -78,18 +78,18 @@ agenda.define('send email report', {priority: 'high', concurrency: 10}, function
   }, done);
 });
 
-agenda.on('ready', function() {
-  agenda.schedule('in 20 minutes', 'send email report', {to: 'admin@example.com'});
-  agenda.start();
-});
+(async function() {
+  await agenda.start();
+  await agenda.schedule('in 20 minutes', 'send email report', {to: 'admin@example.com'});
+})();
 ```
 
 ```js
-agenda.on('ready', function() {
+(async function() {
   var weeklyReport = agenda.create('send email report', {to: 'another-guy@example.com'})
-  weeklyReport.repeatEvery('1 week').save();
-  agenda.start();
-});
+  await agenda.start();
+  await weeklyReport.repeatEvery('1 week').save();
+})();
 ```
 
 # Full documentation
@@ -153,7 +153,9 @@ You can also specify it during instantiation.
 var agenda = new Agenda({db: { address: 'localhost:27017/agenda-test', collection: 'agendaJobs' }});
 ```
 
-Agenda will emit a `ready` event (see [Agenda Events](#agenda-events)) when properly connected to the database and it is safe to start using Agenda.
+Agenda will emit a `ready` event (see [Agenda Events](#agenda-events)) when properly connected to the database.
+It is safe to call `agenda.start()` without waiting for this event, as this is handled internally.
+If you're using the `db` options, or call `database`, then you may still need to listen for `ready` before saving jobs.
 
 ### mongo(mongoClientInstance)
 
@@ -165,24 +167,29 @@ Please note that this must be a *collection*. Also, you will want to run the fol
 afterwards to ensure the database has the proper indexes:
 
 ```js
-agenda.on('ready', () => {
-  agenda._collection.createIndex({
-    disabled: 1,
-    lockedAt: 1,
-    name: 1,
-    nextRunAt: 1,
-    priority: -1
-  }, {
-    name: 'findAndLockNextJobIndex'
-  }, (err) => {
-    if (err) {
-      console.log('Failed to create Agenda index!');
-      console.error(err);
-    } else {
-      console.log('Agenda index created.');
-    }
-  });
-});
+(async () => {
+  await agenda._ready;
+
+  try {
+    agenda._collection.createIndex({
+      disabled: 1,
+      lockedAt: 1,
+      name: 1,
+      nextRunAt: 1,
+      priority: -1
+    }, {
+      name: 'findAndLockNextJobIndex'
+    });
+  } catch (err) {
+    console.log('Failed to create Agenda index!');
+    console.error(err);
+
+    throw err;
+  }
+
+  console.log('Agenda index created.');
+
+})();
 ```
 
 You can also specify it during instantiation.
@@ -320,13 +327,13 @@ By default it is `{ nextRunAt: 1, priority: -1 }`, which obeys a first in first
 
 An instance of an agenda will emit the following events:
 
-- `ready` - called when Agenda mongo connection is successfully opened
+- `ready` - called when Agenda mongo connection is successfully opened and indeces created.
+        If you're passing agenda an existing connection, ou shouldn't need to listen for this, as `agenda.start()` will not resolve until indeces have been created.
+        If you're using the `db` options, or call `database`, then you may still need to listen for `ready` before saving jobs. `agenda.start()` will still wait for the connection to be opened.
 - `error` - called when Agenda mongo connection process has thrown an error
 
 ```js
-agenda.on('ready', function() {
-  agenda.start();
-});
+  await agenda.start();
 ```
 
 ## Defining Job Processors
@@ -535,10 +542,9 @@ job queues can grab them / they are unlocked should the job queue start again. H
 shutdown.
 
 ```js
-function graceful() {
-  agenda.stop(function() {
-    process.exit(0);
-  });
+async function graceful() {
+  await agenda.stop();
+  process.exit(0);
 }
 
 process.on('SIGTERM', graceful);
@@ -948,10 +954,8 @@ jobTypes.forEach(function(type) {
   require('./lib/jobs/' + type)(agenda);
 })
 
-if(jobTypes.length) {
-  agenda.on('ready', function() {
-    agenda.start();
-  });
+if (jobTypes.length) {
+  agenda.start(); // Returns a promise, which should be handled appropriately
 }
 
 module.exports = agenda;

lib/agenda/cancel.js

@@ -3,21 +3,19 @@ const debug = require('debug')('agenda:cancel');
 
 /**
  * Cancels any jobs matching the passed MongoDB query, and removes them from the database.
- *  @param {Object} query MongoDB query to use when cancelling
- *  @param {Function} cb callback(error, numRemoved) when cancellation fails or passes
- *  @caller client code, Agenda.purge(), Job.remove()
- *  @returns {undefined}
+ * @name Agenda#cancel
+ * @function
+ * @param {Object} query MongoDB query to use when cancelling
+ * @caller client code, Agenda.purge(), Job.remove()
+ * @returns {Promise<Number>} A promise that contains the number of removed documents when fulfilled.
  */
-module.exports = function(query, cb) {
+module.exports = function(query) {
   debug('attempting to cancel all Agenda jobs', query);
-  this._collection.deleteMany(query, (error, result) => {
-    if (cb) {
-      if (error) {
-        debug('error trying to delete jobs from MongoDB');
-      } else {
-        debug('jobs cancelled');
-      }
-      cb(error, result && result.result ? result.result.n : undefined);
-    }
+  return this._collection.deleteMany(query).then(({result}) => {
+    debug('%s jobs cancelled', result.n);
+    return result.n;
+  }).catch(err => {
+    debug('error trying to delete jobs from MongoDB');
+    throw err;
   });
 };

lib/agenda/create.js

@@ -4,10 +4,11 @@ const Job = require('../job');
 
 /**
  * Given a name and some data, create a new job
+ * @name Agenda#create
+ * @function
  * @param {String} name name of job
  * @param {Object} data data to set for job
- * @access protected
- * @returns {module.Job} instance of new job
+ * @returns {Job} instance of new job
  */
 module.exports = function(name, data) {
   debug('Agenda.create(%s, [Object])', name);

lib/agenda/database.js

@@ -4,6 +4,8 @@ const debug = require('debug')('agenda:database');
 
 /**
  * Connect to the spec'd MongoDB server and database.
+ * @name Agenda#database
+ * @function
  * @param {String} url MongoDB server URI
  * @param {String} collection name of collection to use
  * @param {Object} options options for connecting

lib/agenda/db-init.js

@@ -3,6 +3,8 @@ const debug = require('debug')('agenda:db_init');
 
 /**
  * Setup and initialize the collection used to manage Jobs.
+ * @name Agenda#dbInit
+ * @function
  * @param {String} collection name or undefined for default 'agendaJobs'
  * @param {Function} cb called when the db is initialized
  * @returns {undefined}
@@ -12,19 +14,21 @@ module.exports = function(collection, cb) {
   debug('init database collection using name [%s]', collection);
   this._collection = this._mdb.collection(collection || 'agendaJobs');
   debug('attempting index creation');
-  this._collection.createIndex(this._indices, {
-    name: 'findAndLockNextJobIndex'
-  }, (err, result) => {
-    if (err) {
-      debug('index creation failed');
-      self.emit('error', err);
-    } else {
-      debug('index creation success');
-      self.emit('ready');
-    }
+  this._collection.createIndex(
+    this._indices,
+    {name: 'findAndLockNextJobIndex'},
+    err => {
+      if (err) {
+        debug('index creation failed');
+        self.emit('error', err);
+      } else {
+        debug('index creation success');
+        self.emit('ready');
+      }
 
-    if (cb) {
-      cb(err, self._collection);
+      if (cb) {
+        cb(err, self._collection);
+      }
     }
-  });
+  );
 };

lib/agenda/default-concurrency.js

@@ -3,6 +3,8 @@ const debug = require('debug')('agenda:defaultConcurrency');
 
 /**
  * Set the default concurrency for each job
+ * @name Agenda#defaultConcurrency
+ * @function
  * @param {Number} num default concurrency
  * @returns {exports} agenda instance
  */

lib/agenda/default-lock-lifetime.js

@@ -4,8 +4,10 @@ const debug = require('debug')('agenda:defaultLockLifetime');
 /**
  * Set the default lock time (in ms)
  * Default is 10 * 60 * 1000 ms (10 minutes)
+ * @name Agenda#defaultLockLifetime
+ * @function
  * @param {Number} ms time in ms to set default lock
- * @returns {exports} agenda instance
+ * @returns {Agenda} agenda instance
  */
 module.exports = function(ms) {
   debug('Agenda.defaultLockLifetime(%d)', ms);

lib/agenda/default-lock-limit.js

@@ -3,8 +3,10 @@ const debug = require('debug')('agenda:defaultLockLimit');
 
 /**
  * Set default lock limit per job type
+ * @name Agenda#defaultLockLimit
+ * @function
  * @param {Number} num Lock limit per job
- * @returns {exports} agenda instance
+ * @returns {Agenda} agenda instance
  */
 module.exports = function(num) {
   debug('Agenda.defaultLockLimit(%d)', num);

lib/agenda/define.js

@@ -4,6 +4,8 @@ const debug = require('debug')('agenda:define');
 /**
  * Setup definition for job
  * Method is used by consumers of lib to setup their functions
+ * @name Agenda#define
+ * @function
  * @param {String} name name of job
  * @param {Object} options options for job to run
  * @param {Function} processor function to be called to run actual job