Playing around to get a nice(r) API for the job management module.

gistfile1.js

/**
 * @param {Object} job The data you want to save for the job.
 * @param {int} processIn The job will not get service until this many ms have elapsed.
 * @param {function} done Callback.
 */
jobs.create(job, processIn, done);

// Form of callback for jobs.process():
// done(err, newJob, processIn)
var callback = function(job, done) {
 // Do stuff with job
 job.state = 'a_new_state';
 job.eatBananas = true;
 
 // Call done callback and update the job.  It will run again in > 200ms.
 done(null, job, 200);
}

/** Iterate through all scheduled jobs and service those that have served out their delay.
 * @param {function(job, done)} callback The callback to be called on each job.  Must call 
 * done() as per example above. 
 */
jobs.process(callback);

// Form of callback for jobs.processNow():
var callback = function(err, job, done) {
 // Do stuff with job
 job.state = 'a_new_state';
 job.eatBananas = true;
 
 // Call done callback and update the job.  It will run again in > 200ms.
 done(null, job, 200);
}

/** The job with the given id will be run now. TODO: Locking issues?
 * @param {int} id The ID of the job to run now.
 * @param {function} callback - The callback to be passed the job, of the same form as for jobs.process().
 */
jobs.processNow(id, callback);

var callback = function(err, jobHistory) {
  var latestJob = jobHistory[0];
  console.log(latestJob);
  
  var secondLatest = jobHistory[1];
  console.log(secondLatest);
}
/** Get the history of snapshots of a job for a given job id.
 * @param {int} id The job id.
 * @param {function} callback A callback that will be passed the job history.
 *                            That is, all the snapshots of a job from, sorted from latest to earliest in an array.
 */     
jobs.get(id, callback);