README

fqueue

fqueue is a micro-plugin to queue function execution to handle asyncronous flow and stepping though functions.

It support adding or removing of function after initialization of queue.
Support storing of data which can be used to all function whithin that queue
Support parrallel and series async call.
Give full control over queue like, stop , start (from any index), hold, continue, call next function.
Can define ignore indexes if you are running queue again and don't want to run ignore some functions.
Make your code more clean (especially if you are node - mongo developer it can save you from dirty callbacks)

** fqueue passes queue object as this in all function but be sure to store this on some variable and use that inside any callback function, because there value of this will be different.

Installation

For node

npm install f-queue

For browser just include fqueue.min.js file or fqueue.js in your directory.

Updates

In version 0.3.0, Added step method.

In version 0.2.0 , code to include f-queue

var fqueue=require("f-queue");

In version 0.1.* , code to include f-queue

var fqueue=require("f-queue").fqueue;

Methods

Methods	Parameters	Description
next	Any number of arguments which you want to pass on next function of queue.	Execute the next method in queue.
step	Any number of arguments which you want to pass on next function of queue.	Execute the next method in queue after all functions in particular index of queue is finished. However it is different form next and complete as next and complete can't be pass directly to callback functions. Whereas step can be passed and will maintain this as fqueue object for next method. Originial this (passed on callback by any way ) will be stored on originialThis key of fqueue object.
add	1. function (mandatory) : function you want to add 2. pos (optional) : Index at which function will be add. If not defined, add function on last.	To add function on the queue after initialization.
remove	1. index (mandatory) : Index of function which you want to remove.	Remove a function at particular index from a queue.
hold	no parameter	To hold the queue to go next item if autoStep option is enabled.
continue	no parameter	Continue the queue to go to next item.
complete	Any number of arguments which you want to pass on next function of queue.	To tell an async call have been finished
start	index (mandatory) : Index at which you want to start the queue. Any arguments starting followed by first argument will be passed to to function through which queue is starting.	To start the queue.
stop	no parameter	To stop the queue.
ignore	idxAry : A array of indexes for which you don't want to execute your function.	To define array of indexes to ignore.

Options

Options	Default	Parameters
autoStart	true	Auto start a queue.
autoStep	true	Auto step to next function in a queue on finish of a function execution.
startParams	[] - empty array	An array of parameters which you want to pass on first function.

You can change the defauls globally like


    fqueue.defaults.autoStart=false;

Examples

Simple Example

var queue=fqueue(
function(){
    //do somthing synchronous
    },
function(){
    //do somthing synchronous
    },
function(){
    //do somthing synchronous
    }		
);

In this example queue will start during initialization and auto step through each function. If you don't want so you can disable those options like.

var queue=fqueue({autoStart:false,autoStep:false}
function(){
    //do somthing synchronous
    },
function(){
    //do somthing synchronous
    },
function(){
    //do somthing synchronous
    }		
);

And then when you want you can start it using queue.start(index) and step through functions using queue.next();

You can use .add() method to add function in queue after initializtion of queue or inside a function of queue.

var queue=fqueue({autoStart:false}
function(){
    //do somthing synchronous
    },
function(){
    //do somthing synchronous
    //to get current index
    var index=this.current;
    //to add function next to current function
    this.add(function(){
            //do something else
        },++index);
    },
function(){
    //do somthing synchronous
    }		
);
or
queue.add(function(){
//do something else
});

Same you can use .remove() method.

You can step to next method in middle of any function too.

var queue=fqueue(
function(){
    //do somthing synchronous
    this.next();
    //do something else
    },
function(){
    //do somthing synchronous
    },
function(){
    //do somthing synchronous
    }		
);

** However if you are using .next() method when execution of the function completes it bypass all those function which are already been called by .next() method.

To run asynchronous function you have to use one or two methods among .hold() , .complete() and .step().
You need to use .hold() method only if autoStep is enabled.
.hold() and .complete() tells that a async function is completed and now to step to next method. While it go to next method only after executing all parallel method in particular index of queue.

You can also use .next() method if there is only one function on a particular index of queue.

**step method can be directly passed as callback while next and and complete can't be. And this method is very handy while you are dealing of hierarchy of callbacks in node.js.

var queue=fqueue(
    function(){
        queue.hold(); //only required if autoStep option is true
        $.get('get.php',function(){
                //do something
                //you can pass parameter to next function
                queue.complete('Sudhanshu','23');
            });
    },
function(name,age){
    //do somthing synchronous
    },
function(){
    queue.hold();
    $.get('get.php',function(){
            //do something
            queue.complete();
        });
    }		
);

or with steps

var queue=fqueue(
function(){
    $.get('get.php',this.step);
    },
function(result){
     //do something
     $.get('get1.php',this.step);
    },
function(result){
    //do something
    console.log("queue is finished");
    }
);


or

var queue=fqueue({autoStep:false}
function(){
    $.get('get.php',function(){
            //do something
            //you can pass parameter to next function
            queue.next('Sudhanshu','23');
        });
    },
function(name,age){
    //do somthing synchronous
     queue.next();
    },
function(){
    //you can also use this instead of queue name, but be sure to save it on some variable
    // because "this" will change inside callback function.
    self=this;
    $.get('get.php',function(){
            //do something
            self.next();
        });
    }		
);

You can also run async functions in parrallel by sending those functions in a array.

var queue=fqueue(
//send function in array to run them in parrallel
[function(){
    queue.hold();
    $.get('get.php',function(){
            //do something
            queue.complete();
        });
    },
function(){
    queue.hold();
    $.get('get.php',function(){
            //do something
            queue.complete();
        });
    }],
function(){
    //this will be executed after first two parrallel function's execution completes.
    //do somthing synchronous
    }		
);

You can use .data,.previousResult,.results to store data, get return value of previous function and to get result of all functions.

var queue=fqueue(
function(){
    //do somthing synchronous
    var name="Sudhanshu";
    this.data.name=name;
    return 1;
    },
function(){
    //do somthing synchronous
    console.log(this.data.name);
    //will log Sudhanshu
    return 2;
    },
function(){
    //do somthing synchronous
    console.log(this.previousResult);
    //will log 2;
    return 3;
    },
function(){
    //do something synchronous
    return 4;
}
            
);

console.log(queue.results);
//will log [1,2,3,4];

In some case you want to call the same queue but you want to ignore some functions in the queue. Suppose the first function was used only to get name and third function only log was done and while calling again the queue you want to ignore first and third function.

queue.ignore([0,2]) //you have to give the index of function in a array which you want to ignore.
queue.start(0); //this will ignore the first and third function.

Usage no npm install needed!

README

fqueue