Awesome

fqueue

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

<ul> <li> It support adding or removing of function after initialization of queue.</li> <li>Support storing of data which can be used to all function whithin that queue</li> <li>Support parrallel and series async call.</li> <li>Give full control over queue like, stop , start (from any index), hold, continue, call next function.</li> <li>Can define ignore indexes if you are running queue again and don't want to run ignore some functions.</li> <li>Make your code more clean (especially if you are node - mongo developer it can save you from dirty callbacks)</li> </ul> ** 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 <pre> npm install f-queue </pre> 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 <pre> var fqueue=require("f-queue"); </pre> In version 0.1.* , code to include f-queue <pre> var fqueue=require("f-queue").fqueue; </pre> Methods <table width="100%" border="0" cellspacing="0" cellpadding="10"> <tr> <td width="20%">Methods</td> <td width="40%">Parameters</td> <td width="40%">Description</td> </tr> <tr> <td>next</td> <td>Any number of arguments which you want to pass on next function of queue.</td> <td>Execute the next method in queue.</td> </tr> <tr> <td>step</td> <td>Any number of arguments which you want to pass on next function of queue.</td> <td>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. </td> </tr> <tr> <td>add</td> <td>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.</td> <td>To add function on the queue after initialization.</td> </tr> <tr> <td>remove</td> <td>1. index (mandatory) : Index of function which you want to remove.</td> <td>Remove a function at particular index from a queue.</td> </tr> <tr> <td>hold</td> <td>no parameter</td> <td>To hold the queue to go next item if autoStep option is enabled.</td> </tr> <tr> <td>continue</td> <td>no parameter</td> <td>Continue the queue to go to next item.</td> </tr> <tr> <td>complete</td> <td>Any number of arguments which you want to pass on next function of queue.</td> <td>To tell an async call have been finished</td> </tr> <tr> <td>start</td> <td>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.</td> <td>To start the queue.</td> </tr> <tr> <td>stop</td> <td>no parameter</td> <td>To stop the queue.</td> </tr> <tr> <td>ignore</td> <td>idxAry :  A array of indexes for which you don't want to execute your function.</td> <td>To define array of indexes to ignore.</td> </tr> </table> Options <table width="100%" border="0" cellspacing="0" cellpadding="10"> <tr> <td width="17%">Options</td> <td width="25%">Default</td> <td width="58%">Parameters</td> </tr> <tr> <td>autoStart</td> <td>true</td> <td>Auto start a queue.</td> </tr> <tr> <td>autoStep</td> <td>true</td> <td>Auto step to next function in a queue on finish of a function execution.</td> </tr> <tr> <td>startParams</td> <td>[] - empty array</td> <td>An array of parameters which you want to pass on first function.</td> </tr> </table> You can change the defauls globally like <pre><code> fqueue.defaults.autoStart=false; </code></pre> Examples Simple Example <pre> var queue=fqueue( function(){ //do somthing synchronous }, function(){ //do somthing synchronous }, function(){ //do somthing synchronous } ); </pre> 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. <pre> var queue=fqueue({autoStart:false,autoStep:false} function(){ //do somthing synchronous }, function(){ //do somthing synchronous }, function(){ //do somthing synchronous } ); </pre> 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. <pre> 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 }); </pre>

Same you can use .remove() method. You can step to next method in middle of any function too. <pre> var queue=fqueue( function(){ //do somthing synchronous this.next(); //do something else }, function(){ //do somthing synchronous }, function(){ //do somthing synchronous } ); </pre> ** 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.

<pre> 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(); }); } ); </pre> You can also run async functions in parrallel by sending those functions in a array. <pre> 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 } ); </pre>

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

<pre> 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]; </pre>

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.

<pre> 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. </pre>