HORIZON PROJECT

# promise-queue [![NPM Version](https://badge.fury.io/js/promise-queue.png)](https://npmjs.org/package/promise-queue) [![Build Status](https://travis-ci.org/azproduction/promise-queue.png?branch=master)](https://travis-ci.org/azproduction/promise-queue) [![Coverage Status](https://coveralls.io/repos/azproduction/promise-queue/badge.png?branch=master)](https://coveralls.io/r/azproduction/promise-queue) [![Dependency Status](https://gemnasium.com/azproduction/promise-queue.png)](https://gemnasium.com/azproduction/promise-queue)

Promise-based queue

## Installation

`promise-queue` can be installed using `npm`:

```

npm install promise-queue

```

## Interface

 - `new Queue(Number maxConcurrent, Number maxQueued): Queue`

 - `Queue#add(Function generator): Promise` - adds function argument that generates a promise to the queue

 - `Queue#getQueueLength(): Number` - returns current length of buffer(added but not started promise generators) `it <= maxQueued`

 - `Queue#getPendingLength(): Number` - returns number of pending(concurrently running) promises `it <= maxConcurrent`

## Example

### Configure queue

By default `Queue` tries to use global Promises, but you can specify your own promises.

```js

Queue.configure(require('vow').Promise);

```

Or use old-style promises approach:

```js

Queue.configure(function (handler) {

    var dfd = $.Deferred();

    try {

        handler(dfd.resolve, dfd.reject, dfd.notify);

    } catch (e) {

        dfd.reject(e);

    }

    return dfd.promise();

});

```

### Queue one by one example

```js

var maxConcurrent = 1;

var maxQueue = Infinity;

var queue = new Queue(maxConcurrent, maxQueue);

app.get('/version/:user/:repo', function (req, res, next) {

    queue.add(function () {

        // Assume that this action is a way too expensive

        // Call of this function will be delayed on second request

        return downloadTarballFromGithub(req.params);

    })

    .then(parseJson('package.json'))

    .then(function (package) {

        res.send(package.version);

    })

    .catch(next);

});

```

### Getting number of pending promises and queue(buffered promises) length

```js

var maxConcurrent = 1;

var maxQueue = 1;

var queue = new Queue(maxConcurrent, maxQueue);

queue.add(function () {

    queue.getQueueLength() === 0;

    queue.getPendingLength() === 1;

    return somePromise();

});

queue.add(function () {

    queue.getQueueLength() === 0;

    queue.getPendingLength() === 0;

    return somePromise();

});

queue.getQueueLength() === 1;

queue.getPendingLength() === 1;

```

[Live example](http://jsfiddle.net/RVuEU/1/)