docs

README.md

@@ -1,22 +1,169 @@
-# breeze-queue
+# breeze-queue [![Build Status](https://secure.travis-ci.org/qualiancy/breeze-queue.png?branch=master)](https://travis-ci.org/qualiancy/breeze-queue)
 
 > Throttled parallel function invocation.
 
-### Installation
+## Installation
 
-#### Node.js
+### Node.js
 
 `breeze-queue` is available on [npm](http://npmjs.org).
 
     $ npm install breeze-queue
 
-#### Component
+### Component
 
 `breeze-queue` is available as a [component](https://github.com/component/component).
 
     $ component install qualiancy/breeze-queue
 
-#### License
+## Usage
+
+### Queue (iterator, concurrency)
+
+* **@param** _{Function}_ iterator 
+* **@param** _{Number}_ concurrency (defaults to 10)
+* **@return** _{Object}_  queue api
+
+The queue mechanism allows for a any number of
+data objects to be processed by an iterator
+when they become available. The queue will processes
+items in parellel, up to a given concurrently value,
+then will wait until an item has finished until
+beginning to process the next. The items queued
+can have a callback executed when it has completed
+its iterator.
+
+In addition, a queue may also have
+functions attached to listen for specific events.
+On such event is an error. Should any item in the queue
+fail to process and provide an error to it's `next`
+callback, no further items will be processed.
+
+```js
+var Queue = require('breeze-queue');
+
+var queue = Queue(function (obj, next) {
+  setTimeout(next, 10);
+}, 5);
+```
+
+
+### .length
+
+* **@return** _{Number}_  count of queued items
+
+Property indicating the number of items current
+in the queue. An item is removed from this list
+prior to being processed.
+
+
+### .push (items[, callback[, autostart]])
+
+* **@param** _{Array}_ item or items to be added to the queue
+* **@param** _{Function}_ callback for completion of each item
+* **@param** _{Boolean}_ autostart process (defaults to false)
+
+You can push an item or an array of items into
+the queue for processing. The callback will be
+called for the completion of each item if the queue
+has not entered into an error state. A `autostart`
+boolean my also be provided if you wish to start
+processing the queue with this push of items. If
+no pushes provide the autostart, then the queue
+must be started manually with `.process()`.
+
+Note that if the queue has already been started but
+has been drained of items, it will not start again
+with another push unless the `autostart` toggle is present.
+
+```js
+// single item
+queue.push({ hello: 'universe' });
+
+// multiple items
+queue.push([
+    { hello: 'world' }
+  , { hello: 'universe' }
+]);
+
+// notify callback
+queue.push({ hello: 'universe' }, notify);
+
+// autostart
+queue.push({ hello: 'universe' }, true);
+
+// notify + autostart
+queue.push({ hello: 'univeerse' }, notify, true);
+```
+
+
+### .process ()
+
+
+Begin the queue processing cycle. Has no impact if
+the queue is already processing.
+
+```js
+queue.process();
+```
+
+
+### .onerror
+
+* **@cb** {Error} object that was passed as error during iteration
+
+Setting this to a function will provide a listener
+should an error occur. It will not be executed otherwise.
+
+```js
+queue.onerror = function (err) {
+  console.error(err.message);
+};
+```
+
+
+### .saturated
+
+
+This listener will be executed when the number of
+queued items exceeds the current concurrency value.
+This will be executed directly after the push of
+said items.
+
+```js
+queue.saturated = function () {
+  console.log('the queue is saturated');
+};
+```
+
+
+### .empty
+
+
+This listener will be executed when the queue is empty.
+In other words, prior to the last item in the queue
+being processed.
+
+```js
+queue.empty = function () {
+  console.log('the queue is on the last item');
+};
+```
+
+
+### .drain
+
+
+This listener will be executed when all queued
+items have been executed through the iterator.
+
+```js
+queue.drain = function () {
+  console.log('the queue has processed all tiems');
+};
+```
+
+## License
 
 (The MIT License)
 

lib/queue.js

@@ -3,7 +3,7 @@ var nextTick = require('breeze-nexttick');
 var noop = function () {};
 
 /**
- * ### queue (iterator, concurrency)
+ * ### Queue (iterator, concurrency)
  *
  * The queue mechanism allows for a any number of
  * data objects to be processed by an iterator
@@ -12,15 +12,25 @@ var noop = function () {};
  * then will wait until an item has finished until
  * beginning to process the next. The items queued
  * can have a callback executed when it has completed
- * its iterator. In addition, a queue may also have
+ * its iterator.
+ *
+ * In addition, a queue may also have
  * functions attached to listen for specific events.
  * On such event is an error. Should any item in the queue
- * fail to process and provide an error to it's `done`
+ * fail to process and provide an error to it's `next`
  * callback, no further items will be processed.
  *
+ * ```js
+ * var Queue = require('breeze-queue');
+ *
+ * var queue = Queue(function (obj, next) {
+ *   setTimeout(next, 10);
+ * }, 5);
+ * ```
+ *
  * @param {Function} iterator
  * @param {Number} concurrency (defaults to 10)
- * @returns {Object} queue
+ * @return {Object} queue api
  * @name queue
  * @api public
  */
@@ -50,13 +60,13 @@ function Queue (iterator, concurrency) {
 }
 
 /**
- * #### .length
+ * ### .length
  *
  * Property indicating the number of items current
  * in the queue. An item is removed from this list
  * prior to being processed.
  *
- * @returns {Number} count of queued items
+ * @return {Number} count of queued items
  * @api public
  */
 
@@ -67,7 +77,7 @@ Object.defineProperty(Queue.prototype, 'length',
 });
 
 /**
- * #### .push (items[, callback[, autostart]])
+ * ### .push (items[, callback[, autostart]])
  *
  * You can push an item or an array of items into
  * the queue for processing. The callback will be
@@ -82,6 +92,26 @@ Object.defineProperty(Queue.prototype, 'length',
  * has been drained of items, it will not start again
  * with another push unless the `autostart` toggle is present.
  *
+ * ```js
+ * // single item
+ * queue.push({ hello: 'universe' });
+ *
+ * // multiple items
+ * queue.push([
+ *     { hello: 'world' }
+ *   , { hello: 'universe' }
+ * ]);
+ *
+ * // notify callback
+ * queue.push({ hello: 'universe' }, notify);
+ *
+ * // autostart
+ * queue.push({ hello: 'universe' }, true);
+ *
+ * // notify + autostart
+ * queue.push({ hello: 'univeerse' }, notify, true);
+ * ```
+ *
  * @param {Array} item or items to be added to the queue
  * @param {Function} callback for completion of each item
  * @param {Boolean} autostart process (defaults to false)
@@ -93,20 +123,29 @@ Queue.prototype.push = function (items, cb, start) {
   if ('boolean' === typeof cb) start = cb, cb = noop;
   if (!Array.isArray(items)) items = [ items ];
   cb = cb || noop;
+
   var cc = this._concurrency
     , sat = this.saturated;
+
   for (var i = 0, l = items.length; i < l; i ++) {
     var task = items[i];
     this._tasks.push({ task: task , cb: cb });
     if (sat && this._tasks.length === cc) sat();
     if (start) nextTick(this.process.bind(this));
   }
+
+  return this;
 };
 
 /**
- * #### .process ()
+ * ### .process ()
+ *
+ * Begin the queue processing cycle. Has no impact if
+ * the queue is already processing.
  *
- * Begin the queue processing cycle.
+ * ```js
+ * queue.process();
+ * ```
  *
  * @name process
  * @api public
@@ -116,6 +155,7 @@ Queue.prototype.process = function () {
   var self = this
     , cc = this._concurrency
     , iterator = this._iterator
+
   if (this.workers < cc && this.length && !this._err) {
     var task = this._tasks.shift();
     if (this.empty && !this.length) this.empty();
@@ -132,14 +172,22 @@ Queue.prototype.process = function () {
     });
     this.process();
   }
+
+  return this;
 };
 
 /**
- * #### .onerror
+ * ### .onerror
  *
  * Setting this to a function will provide a listener
  * should an error occur. It will not be executed otherwise.
  *
+ * ```js
+ * queue.onerror = function (err) {
+ *   console.error(err.message);
+ * };
+ * ```
+ *
  * @default null
  * @expected {Function} on error callback
  * @cb {Error} object that was passed as error during iteration
@@ -149,12 +197,18 @@ Queue.prototype.process = function () {
 Queue.prototype.onerror = null;
 
 /**
- * #### .saturated
+ * ### .saturated
  *
  * This listener will be executed when the number of
  * queued items exceeds the current concurrency value.
  * This will be executed directly after the push of
- * said items
+ * said items.
+ *
+ * ```js
+ * queue.saturated = function () {
+ *   console.log('the queue is saturated');
+ * };
+ * ```
  *
  * @default null
  * @expected {Function}
@@ -164,12 +218,18 @@ Queue.prototype.onerror = null;
 Queue.prototype.saturated = null;
 
 /**
- * #### .empty
+ * ### .empty
  *
  * This listener will be executed when the queue is empty.
  * In other words, prior to the last item in the queue
  * being processed.
  *
+ * ```js
+ * queue.empty = function () {
+ *   console.log('the queue is on the last item');
+ * };
+ * ```
+ *
  * @default null
  * @expected {Function}
  * @api public
@@ -178,11 +238,17 @@ Queue.prototype.saturated = null;
 Queue.prototype.empty = null;
 
 /**
- * #### .drain
+ * ### .drain
  *
  * This listener will be executed when all queued
  * items have been executed through the iterator.
  *
+ * ```js
+ * queue.drain = function () {
+ *   console.log('the queue has processed all tiems');
+ * };
+ * ```
+ *
  * @default null
  * @expected {Function}
  * @api public