Fork me on GitHub
Ignitersworld Lab

fqueue

A micro-plugin to queue function execution to handle asynchronous flow and stepping through functions.

fqueue

fqueue is a micro-plugin to queue function execution to handle asynchronous flow and stepping through functions.
  • It support adding or removing of function after initialization of queue.
  • Support storing of data which can be used to all function within that queue
  • Support parallel 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.

Want to support and contribute to fqueue?

fqueue needs your contribution to become best of its kind. There are lot of things you can do to contribute and support plugin.

Author

This plugin is developed and maintained by me ( Sudhanshu Yadav ignitersworld.com/me ) . If you have any query you can contact me at sudhanshuyadav2@gmail.com.

You can also follow me on twitter and github Follow @s-yadav .

Check out my other open source work