.# stairway

Gives you the ability to run async tasks with ease

stairway is a library I have put together to provide the ability to easily run tasks in order without the complicated initiation processes. make a few steps, run them, and; when done; do the magic.

The reason for this library is to replace this:

mongoose.model("users").findOne({_id:id},function(err,data){
  if(err){}
  else{
    data.user = data;
    mongoose.model("notes").find({user_id:data.user.userid}, function(err,data){
      if(!err) {
        data.notes = data;
        // and so on
        mongoose.model("notes").find({user_id:data.user.userid}, function(err,data){
          if(!err) {
            data.notes = data;
            // and so on
            mongoose.model("notes").find({user_id:data.user.userid}, function(err,data){
              if(!err) {
                data.notes = data;
                // and so on
              }
            })
          }
        })
      }
    })
  }
})

With this:

// no-comment sample
var stairway = require('stairway');
var task = new stairway.Task();
var data = {};

task.step(function(next){
  mongoose.model("users").findOne({_id:id},function(err,data){
    if(err){}
    else{
      data.user = data;
      next();
    }
  })
});

task.step(function(next){
  mongoose.model("notes").find({user_id:data.user.userid}, function(err,data){
    if(!err) {
      data.notes = data;
      next()
    }
  })
})

task.run(function(){
  // done! steps are taken
  // queries are executed

})

// usage example:
// require stairway
var stairway = require('stairway');
// create a task
var task = new stairway.Task();

// add some containers to collect data
// EXAMPLE:
var users = [];
var timeout = 0;

//now, let's add some steps
task.step(function(next){

  // execute your code !
  // timeouts, queries, all welcome.
  setTimeout(function(){
    timeout = 1;
    // and, when done,
    next();    
  },400)

}).step(function(next){
  // note that the step awaits for the "next" method to be ran.
  // this gives you the control to tell it when it's ready.
  mongoose.model("users").find({},function(err,data){
    //do your stuff
    users = data;
    // data is in, take next step.
    next();        
  })
// at this point, we will run the task
}).run(function(){
  // and do the final stuff when it's done
  res.end({users:users, timeout:timeout});  
});

Library is super light-weight!

no, really. it's tiny. take a look:

// This will execute pipe runtime model //
module.exports = {
  Task: function(fn) {
    // create a new task object
    return {
      // list of "steps" to run in order
      steps: fn == null ? [] : [fn],
      // function that will add a next step
      step: function(fn) {
        // simply add a step to the list
        this.steps.push(fn);
        // return self to provide the ability to use single-line
        // type coding. task.step().step().step() runtime style
        return this;
      },
      // run the tasks in order
      run: function(then) {
        // get next task
        var task = this.steps[0];
        // if no tasks left, execute
        if(task==null){
          // of course, if there is something to execute
          if (typeof then == "function") then();
        } else {
          // otherwise, splice the task that will be executed.
          this.steps.splice(0, 1)// remove the task (completed!);
          // execute the given task.
          // this executes an external function, which means that
          // "THIS" element will not be correct, so let's save it as "me".
          var me = this;
          task(function(){
            // once the task fires "next()",
            // we execute me.run(), or [this.run()]. This will keep
            // happening until it's done.
            me.run(then);
          });
        }
      }
    };
  }
}