1. module agenda
   1. function agenda.job (args)
   2. function agenda.super_ ()
   3. object agenda.job.prototype
2. module agenda.job
   1. function agenda.job (args)
3. module agenda.job.prototype
   1. function agenda.job.prototype.computeNextRunAt ()
   2. function agenda.job.prototype.disable ()
   3. function agenda.job.prototype.enable ()
   4. function agenda.job.prototype.fail (reason)
   5. function agenda.job.prototype.isRunning ()
   6. function agenda.job.prototype.priority (priority)
   7. function agenda.job.prototype.remove (cb)
   8. function agenda.job.prototype.repeatAt (time)
   9. function agenda.job.prototype.repeatEvery (interval, options)
   10. function agenda.job.prototype.run (cb)
   11. function agenda.job.prototype.save (cb)
   12. function agenda.job.prototype.schedule (time)
   13. function agenda.job.prototype.toJSON ()
   14. function agenda.job.prototype.touch (cb)
   15. function agenda.job.prototype.unique (unique, opts)

module agenda

function agenda.job (args)

• description and source-code

  function Job(args) {
    args = args || {};
  
    // Remove special args
    this.agenda = args.agenda;
    delete args.agenda;
  
    // Process args
    args.priority = parsePriority(args.priority) || 0;
  
    // Set attrs to args
    var attrs = {};
    for (var key in args) {
      if (args.hasOwnProperty(key)) {
        attrs[key] = args[key];
      }
    }
  
    // Set defaults if undefined
    attrs.nextRunAt = attrs.nextRunAt || new Date();
    attrs.type = attrs.type || 'once';
    this.attrs = attrs;
  }

• example usage

  n/a

function agenda.super_ ()

• description and source-code

  function EventEmitter() {
    EventEmitter.init.call(this);
  }

• example usage

  n/a

module agenda.job

function agenda.job (args)

• description and source-code

  function Job(args) {
    args = args || {};
  
    // Remove special args
    this.agenda = args.agenda;
    delete args.agenda;
  
    // Process args
    args.priority = parsePriority(args.priority) || 0;
  
    // Set attrs to args
    var attrs = {};
    for (var key in args) {
      if (args.hasOwnProperty(key)) {
        attrs[key] = args[key];
      }
    }
  
    // Set defaults if undefined
    attrs.nextRunAt = attrs.nextRunAt || new Date();
    attrs.type = attrs.type || 'once';
    this.attrs = attrs;
  }

• example usage

  n/a

module agenda.job.prototype

function agenda.job.prototype.computeNextRunAt ()

• description and source-code

  computeNextRunAt = function () {
    var interval = this.attrs.repeatInterval;
    var timezone = this.attrs.repeatTimezone;
    var repeatAt = this.attrs.repeatAt;
    this.attrs.nextRunAt = undefined;
  
    if (interval) {
      computeFromInterval.call(this);
    } else if (repeatAt) {
      computeFromRepeatAt.call(this);
    }
    return this;
  
    function dateForTimezone (d) {
      d = moment(d);
      if(timezone) d.tz(timezone);
      return d;
    }
  
    function computeFromInterval() {
      var lastRun = this.attrs.lastRunAt || new Date();
      lastRun = dateForTimezone(lastRun);
      try {
        var cronTime = new CronTime(interval);
        var nextDate = cronTime._getNextDateFrom(lastRun);
        if (nextDate.valueOf() == lastRun.valueOf()) {
          // Handle cronTime giving back the same date for the next run time
          nextDate = cronTime._getNextDateFrom(dateForTimezone(new Date(lastRun.valueOf() + 1000)));
        }
        this.attrs.nextRunAt = nextDate;
      } catch (e) {
        // Nope, humanInterval then!
        try {
          if (!this.attrs.lastRunAt && humanInterval(interval)) {
            this.attrs.nextRunAt = lastRun.valueOf();
          } else {
            this.attrs.nextRunAt = lastRun.valueOf() + humanInterval(interval);
          }
        } catch (e) {}
      } finally {
        if (isNaN(this.attrs.nextRunAt)) {
          this.attrs.nextRunAt = undefined;
          this.fail('failed to calculate nextRunAt due to invalid repeat interval');
        }
      }
    }
  
    function computeFromRepeatAt() {
      var lastRun = this.attrs.lastRunAt || new Date();
      var nextDate = date(repeatAt).valueOf();
  
      var offset = Date.now();  // if you do not specify offset date for below test it will fail for ms
      if (offset === date(repeatAt,offset).valueOf()) {
        this.attrs.nextRunAt = undefined;
        this.fail('failed to calculate repeatAt time due to invalid format');
      } else if (nextDate.valueOf() == lastRun.valueOf()) {
        this.attrs.nextRunAt = date('tomorrow at ', repeatAt);
      } else {
        this.attrs.nextRunAt = date(repeatAt);
      }
    }
  }

• example usage

  ...
    var self = this,
        agenda = self.agenda,
        definition = agenda._definitions[self.attrs.name];
  
    var setImmediate = setImmediate || process.nextTick;
    setImmediate(function() {
      self.attrs.lastRunAt = new Date();
      self.computeNextRunAt();
      self.save(function() {
        var jobCallback = function(err) {
  if (err) {
    self.fail(err);
  }
  
  self.attrs.lastFinishedAt = new Date();
  ...

function agenda.job.prototype.disable ()

• description and source-code

  disable = function () {
    this.attrs.disabled = true;
    return this;
  }

• example usage

  n/a

function agenda.job.prototype.enable ()

• description and source-code

  enable = function () {
    this.attrs.disabled = false;
    return this;
  }

• example usage

  n/a

function agenda.job.prototype.fail (reason)

• description and source-code

  fail = function (reason) {
    if(reason instanceof Error) {
      reason = reason.message;
    }
    this.attrs.failReason = reason;
    this.attrs.failCount = (this.attrs.failCount || 0) + 1;
    this.attrs.failedAt = new Date();
    return this;
  }

• example usage

  ...
  Sets `job.attrs.failedAt` to `now`, and sets `job.attrs.failReason`
  to `reason`.
  
  Optionally, `reason` can be an error, in which case `job.attrs.failReason` will
  be set to `error.message`
  
  ```js
  job.fail('insuficient disk space');
  // or
  job.fail(new Error('insufficient disk space'));
  job.save();
  ```
  
  ### run(callback)
  ...

function agenda.job.prototype.isRunning ()

• description and source-code

  isRunning = function () {
    if (!this.attrs.lastRunAt) return false;
    if (!this.attrs.lastFinishedAt) return true;
    if (this.attrs.lockedAt && this.attrs.lastRunAt.getTime() > this.attrs.lastFinishedAt.getTime()) {
      return true;
    }
    return false;
  }

• example usage

  n/a

function agenda.job.prototype.priority (priority)

• description and source-code

  priority = function (priority) {
    this.attrs.priority = parsePriority(priority);
    return this;
  }

• example usage

  ...
  
  ### priority(priority)
  
  Specifies the `priority` weighting of the job. Can be a number or a string from
  the above priority table.
  
  ```js
  job.priority('low');
  job.save();
  ```
  
  ### unique(properties, [options])
  
  Ensure that only one instance of this job exists with the specified properties
  ...

function agenda.job.prototype.remove (cb)

• description and source-code

  remove = function (cb) {
    // refactored NF 21/04/2015
    this.agenda.cancel( {_id: this.attrs._id}, cb );
  /*
    var self = this;
    this.agenda._db.remove({_id: this.attrs._id}, function(err, count) {
      if(err) {
        return cb(err);
      }
      cb(err, count);
    });
  */
  }

• example usage

  ...
  // or pass additional connection options:
  // var agenda = new Agenda({db: {address: mongoConnectionString, collection: "jobCollectionName", options: {server:{auto_reconnect
  :true}}}});
  
  // or pass in an existing mongodb-native MongoClient instance
  // var agenda = new Agenda({mongo: myMongoClient});
  
  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');
  
  // Alternatively, you could also do:
  agenda.every('*/3 * * * *', 'delete old users');
  ...

function agenda.job.prototype.repeatAt (time)

• description and source-code

  repeatAt = function (time) {
    this.attrs.repeatAt = time;
    return this;
  }

• example usage

  ...
  ```
  
  ### repeatAt(time)
  
  Specifies a `time` when the job should repeat. [Possible values](https://github.com/matthewmueller/date#examples)
  
  ```js
  job.repeatAt('3:30pm');
  job.save();
  ```
  
  ### schedule(time)
  
  Specifies the next `time` at which the job should run.
  ...

function agenda.job.prototype.repeatEvery (interval, options)

• description and source-code

  repeatEvery = function (interval, options) {
    options = options || {};
    this.attrs.repeatInterval = interval;
    this.attrs.repeatTimezone = options.timezone ? options.timezone : null;
    return this;
  }

• example usage

  ...
    agenda.start();
  });
  ```
  
  ```js
  agenda.on('ready', function() {
    var weeklyReport = agenda.create('send email report', {to: 'another-guy@example.com'})
    weeklyReport.repeatEvery('1 week').save();
    agenda.start();
  });
  ```
  
  # Full documentation
  
  Agenda's basic control structure is an instance of an agenda. Agenda's are
  ...

function agenda.job.prototype.run (cb)

• description and source-code

  run = function (cb) {
    var self = this,
        agenda = self.agenda,
        definition = agenda._definitions[self.attrs.name];
  
    var setImmediate = setImmediate || process.nextTick;
    setImmediate(function() {
      self.attrs.lastRunAt = new Date();
      self.computeNextRunAt();
      self.save(function() {
        var jobCallback = function(err) {
          if (err) {
            self.fail(err);
          }
  
          self.attrs.lastFinishedAt = new Date();
          self.attrs.lockedAt = null;
          self.save(function(saveErr, job) {
            cb && cb(err || saveErr, job);
            if (err) {
              agenda.emit('fail', err, self);
              agenda.emit('fail:' + self.attrs.name, err, self);
            } else {
              agenda.emit('success', self);
              agenda.emit('success:' + self.attrs.name, self);
            }
            agenda.emit('complete', self);
            agenda.emit('complete:' + self.attrs.name, self);
          });
        };
  
        try {
          agenda.emit('start', self);
          agenda.emit('start:' + self.attrs.name, self);
          if (!definition) {
            throw new Error('Undefined job');
          }
          if (definition.fn.length === 2) {
            definition.fn(self, jobCallback);
          } else {
            definition.fn(self);
            jobCallback();
          }
        } catch (e) {
          jobCallback(e);
        }
      });
    });
  }

• example usage

  ...
  
  ### run(callback)
  
  Runs the given `job` and calls `callback(err, job)` upon completion. Normally
  you never need to call this manually.
  
  ```js
  job.run(function(err, job) {
    console.log("I don't know why you would need to do this...");
  });
  ```
  
  ### save(callback)
  
  Saves the `job.attrs` into the database.
  ...

function agenda.job.prototype.save (cb)

• description and source-code

  save = function (cb) {
    this.agenda.saveJob(this, cb);
    return this;
  }

• example usage

  ...
    agenda.start();
  });
  ```
  
  ```js
  agenda.on('ready', function() {
    var weeklyReport = agenda.create('send email report', {to: 'another-guy@example.com'})
    weeklyReport.repeatEvery('1 week').save();
    agenda.start();
  });
  ```
  
  # Full documentation
  
  Agenda's basic control structure is an instance of an agenda. Agenda's are
  ...

function agenda.job.prototype.schedule (time)

• description and source-code

  schedule = function (time) {
    this._scheduled = true;
    this.attrs.nextRunAt = (time instanceof Date) ? time : date(time);
    return this;
  }

• example usage

  ...
    from: 'example@example.com',
    subject: 'Email Report',
    body: '...'
  }, done);
  });
  
  agenda.on('ready', function() {
  agenda.schedule('in 20 minutes', 'send email report', {to: '
  admin@example.com'});
  agenda.start();
  });
  ```
  
  ```js
  agenda.on('ready', function() {
  var weeklyReport = agenda.create('send email report', {to: 'another-guy@example.com'})
  ...

function agenda.job.prototype.toJSON ()

• description and source-code

  toJSON = function () { // create a persistable Mongo object -RR
      var self = this,
          attrs = self.attrs || {};
  
      var result = {};
  
      for (var prop in attrs) {
        if (attrs.hasOwnProperty(prop)) {
          result[prop] = attrs[prop];
        }
      }
  
      var dates = ['lastRunAt', 'lastFinishedAt', 'nextRunAt', 'failedAt', 'lockedAt'];
      dates.forEach(function(d) {
        if (result[d]) {
          result[d] = new Date(result[d]);
        }
      });
  
      return result;
  }

• example usage

  n/a

function agenda.job.prototype.touch (cb)

• description and source-code

  touch = function (cb) {
    this.attrs.lockedAt = new Date();
    this.save(cb);
  }

• example usage

  ...
  
  Resets the lock on the job. Useful to indicate that the job hasn't timed out
  when you have very long running jobs.
  
  ```js
  agenda.define('super long job', function(job, done) {
  doSomeLongTask(function() {
    job.touch(function() {
      doAnotherLongTask(function() {
        job.touch(function() {
          finishOurLongTasks(done);
        });
      });
    });
  });
  ...

function agenda.job.prototype.unique (unique, opts)

• description and source-code

  unique = function (unique, opts) {
    this.attrs.unique = unique;
    this.attrs.uniqueOpts = opts;
    return this;
  }

• example usage

  ...
  
  `options` is an optional argument which can overwrite the defaults. It can take
  the following:
  
  - `insertOnly`: `boolean` will prevent any properties from persisting if job already exists. Defaults to false.
  
  ```js
  job.unique({'data.type': 'active', 'data.userId': '
  ;123', nextRunAt(date)});
  job.save();
  ```
  
  ### fail(reason)
  
  Sets `job.attrs.failedAt` to `now`, and sets `job.attrs.failReason`
  to `reason`.
  ...