Adds Grunt test task; updates documentation

Gruntfile.js

@@ -1,6 +1,8 @@
 "use strict";
 
 module.exports = function(grunt) {
+
+    var serverPort = grunt.option("port") || 9001;
 
     // project configuration
     grunt.initConfig({
@@ -40,6 +42,16 @@ module.exports = function(grunt) {
         qunit: {
             files: ["test/**/*.html"]
         },
+        connect: {
+            server: {
+                options: {
+                    port: serverPort,
+                    keepalive: true,
+                    base: ".",
+                    open: "http://localhost:" + serverPort + "/test/ajax-chain.html"
+                }
+            }
+        },
         jshint: {
             options: {
                 jshintrc: true,
@@ -77,10 +89,13 @@ module.exports = function(grunt) {
     grunt.loadNpmTasks("grunt-contrib-concat");
     grunt.loadNpmTasks("grunt-contrib-uglify");
     grunt.loadNpmTasks("grunt-contrib-qunit");
+    grunt.loadNpmTasks("grunt-contrib-connect");
     grunt.loadNpmTasks("grunt-contrib-jshint");
     grunt.loadNpmTasks("grunt-contrib-watch");
 
     // default task
     grunt.registerTask("default", ["jshint", "qunit", "clean", "concat", "uglify"]);
+    grunt.registerTask("test:headless", ["qunit"]);
+    grunt.registerTask("test:browser", ["connect"]);
 
 };

README.md

@@ -8,46 +8,46 @@ Documentation
 
 ### Constructor ###
 
-| *name* | *returns* | *description* |
-| :--    | :--       | :--           |
-| **`$.AjaxChain()`** | `AjaxChain` | The `$.ajaxChain` helper class extends the `JQueryPromise<T>` object ([http://api.jquery.com/Types/#Promise](http://api.jquery.com/Types/#Promise)) with custom methods. |
+| *name* | *description* |
+| :--    | :--           |
+| **`$.AjaxChain():JQueryAjaxChain`** | The `$.ajaxChain` helper class extends the `JQueryPromise<T>` object ([http://api.jquery.com/Types/#Promise](http://api.jquery.com/Types/#Promise)) with custom methods. |
 
 ### Public methods ###
 
-| *name* | *argument type* | *chainable* | *returns* | *description* |
-| :--    | :--             | :--         | :--       | :--           |
-| **`enqueue()`** | `Object` | `yes` | `AjaxChain` | Enqueues one or more [configuration objects](#configuration-object) for later processing. |
-| **`dequeue()`** | `-` | `yes` | `AjaxChain` | Sequentially and synchronously dequeues the [configuration objects](#configuration-object) enqueued via **`enqueue()`** method in the order they were added, triggering the related Ajax calls. |
-| **`clearQueue()`** | `-` | `yes` | `AjaxChain` | Clears the currently queued configuration objects. |
-| **`state()`** | `-` | `no` | `String` |  [jQuery API Reference](http://api.jquery.com/deferred.state/). |
-| **`then()`** | `Function | Array` | `yes` | `JQueryPromise<T>` | [jQuery API Reference](http://api.jquery.com/deferred.then/). |
-| **`done()`** | `Function | Array` | `yes` | `JQueryPromise<T>` | [jQuery API Reference](http://api.jquery.com/deferred.done/). |
-| **`fail()`** | `Function | Array` | `yes` | `JQueryPromise<T>` | [jQuery API Reference](http://api.jquery.com/deferred.fail/). |
-| **`always()`** | `Function | Array` | `yes` | `JQueryPromise<T>` | [jQuery API Reference](http://api.jquery.com/deferred.always/). |
-| **`progress()`** | `Function | Array` | `yes` | `JQueryPromise<T>` | [jQuery API Reference](http://api.jquery.com/deferred.progress/). |
+| *name* | *chainable* | *description* |
+| :--    | :--             | :--         |
+| **`enqueue(confObj: AjaxChainConfiguration | AjaxChainConfiguration[]):JQueryAjaxChain`** | `yes` | Enqueues one or more [configuration objects](#configuration-object) for later processing. |
+| **`dequeue():JQueryAjaxChain`** | `yes` | Sequentially and synchronously dequeues the [configuration objects](#configuration-object) enqueued via **`enqueue()`** method in the order they were added, triggering the related Ajax calls. |
+| **`clearQueue():JQueryAjaxChain`** | `yes` | Clears the currently queued configuration objects. |
+| **`state():string`** | `no` | [jQuery API Reference](http://api.jquery.com/deferred.state/). |
+| **`then<U>(doneFilter: (value?: T, ...values: any[]) => U | JQueryPromise<U>, failFilter?: (...reasons: any[]) => any, progressFilter?: (...progression: any[]) => any):JQueryPromise<U>`** | `yes` | [jQuery API Reference](http://api.jquery.com/deferred.then/). |
+| **`done(doneCallback1?: JQueryPromiseCallback<T> | JQueryPromiseCallback<T>[], ...doneCallbackN: Array<JQueryPromiseCallback<T> | JQueryPromiseCallback<T>[]>):JQueryPromise<T>`** | `yes` | [jQuery API Reference](http://api.jquery.com/deferred.done/). |
+| **`fail(failCallback1?: JQueryPromiseCallback<any>|JQueryPromiseCallback<any>[], ...failCallbacksN: Array<JQueryPromiseCallback<any> | JQueryPromiseCallback<any>[]>):JQueryPromise<T>`** | `yes` | [jQuery API Reference](http://api.jquery.com/deferred.fail/). |
+| **`always(alwaysCallback1?: JQueryPromiseCallback<any> | JQueryPromiseCallback<any>[], ...alwaysCallbacksN: Array<JQueryPromiseCallback<any> | JQueryPromiseCallback<any>[]>):JQueryPromise<T>`** | `yes` | [jQuery API Reference](http://api.jquery.com/deferred.always/). |
+| **`progress(progressCallback1?: JQueryPromiseCallback<any> | JQueryPromiseCallback<any>[], ...progressCallbackN: Array<JQueryPromiseCallback<any> | JQueryPromiseCallback<any>[]>):JQueryPromise<T>`** | `yes` | [jQuery API Reference](http://api.jquery.com/deferred.progress/). |
 
 #### Callback functions arguments
 
 **Note:** differently from the original jQuery implementation, callbacks specified as arguments of **`then()`**, **`done()`**, **`fail()`**, **`always()`** methods get passed an array of responses: **`[response[,responseN, ...]]`**. Furthermore, callbacks specified as arguments of **`progress()`** method get passed an object structured as follows:
 
-| *key* | *key value type* | *key value* |
-| :--   | :--              | :--         |
-|  **`index`** | `Number` | Dequeued Ajax call zero-based index |
-|  **`label`** | `String` | Dequeued Ajax call label, either user-defined or randomly generated |
-|  **`data`** | `Any` | Dequeued Ajax call response |
+| *key* | *value* |
+| :--   | :--         |
+|  **`index:number`** | Dequeued Ajax call zero-based index |
+|  **`label:string`** | Dequeued Ajax call label, either user-defined or randomly generated |
+|  **`data:any`** | Dequeued Ajax call response |
 
 ### Configuration object ###
 
-|*key*|*key value type*|*description*|
-| :-- | :--            | :--         |
-| **`ajaxSettings`** | `Object` | jQuery $.ajax method [settings](http://api.jquery.com/jQuery.ajax/#jQuery-ajax-settings). |
-| **`label?`** | `String` | Configuration object label (see **`progress()`** [callback functions argument](#callback-functions-arguments)). |
-| **`transform?`** | `Function` | Returning a truthy value allows to arbitrarily overwrite the next queued Ajax call 'data' property value specified in the original jQuery $.ajax method configuration object ('ajaxSettings'). See [example #1](#1-dynamically-passing-data-between-succeeding-ajax-calls). |
-| **`appendToUrl?`** | `Function` | Returning a truthy value (String) allows to append string fragments to the next queued Ajax call 'url' property value specified in original jQuery $.ajax method configuration object ('ajaxSettings'); handy when dealing with semantic urls. See [example #2](#2-dynamically-appending-url-fragments-between-succeeding-ajax-calls). |
-| **`hasErrors?`** | `Function` | Returning a truthy value determines any registered fail callback(s) to be called immediately, passing the former as an argument; the queue is then rejected. See [example #3](#3-dynamically-resolving-queue-upon-custom-errors). |
-| **`hasCache?`** | `Function` | Returning a truthy value allows to prevent the related Ajax call from being executed, passing the former as a parameter to any registered handler(s); useful to create caching mechanisms. See [example #4](#4-creating-caching-mechanisms). |
-| **`hasHaltingCapabilities?`** | `Function` | Returning a truthy value prevents the queue from further progressing to the succeeding Ajax calls; the queue is then resolved. See [example #5](#5-halting-queue-upon-conditional-logic). |
-| **`isSkippable?`** | `Function` | Returning a truthy value prevents the queue from being halted in case of $.Ajax error. See [example #6](#6-preventing-a-queue-from-being-halted-in-case-of-ajax-error). |
+| *key* | *description* |
+| :--   | :--           |
+| **`ajaxSettings:JQueryAjaxSettings`** | jQuery $.ajax method [settings](http://api.jquery.com/jQuery.ajax/#jQuery-ajax-settings). |
+| **`label?:string`** | Configuration object label (see **`progress()`** [callback functions argument](#callback-functions-arguments)). |
+| **`transform?:Function`** | Returning a truthy value allows to arbitrarily overwrite the next queued Ajax call 'data' property value specified in the original jQuery $.ajax method configuration object ('ajaxSettings'). See [example #1](#1-dynamically-passing-data-between-succeeding-ajax-calls). |
+| **`appendToUrl?:Function`** | Returning a truthy value (String) allows to append string fragments to the next queued Ajax call 'url' property value specified in original jQuery $.ajax method configuration object ('ajaxSettings'); handy when dealing with semantic urls. See [example #2](#2-dynamically-appending-url-fragments-between-succeeding-ajax-calls). |
+| **`hasErrors?:Function`** | Returning a truthy value determines any registered fail callback(s) to be called immediately, passing the former as an argument; the queue is then rejected. See [example #3](#3-dynamically-resolving-queue-upon-custom-errors). |
+| **`hasCache?:Function`** | Returning a truthy value allows to prevent the related Ajax call from being executed, passing the former as a parameter to any registered handler(s); useful to create caching mechanisms. See [example #4](#4-creating-caching-mechanisms). |
+| **`hasHaltingCapabilities?:Function`** | Returning a truthy value prevents the queue from further progressing to the succeeding Ajax calls; the queue is then resolved. See [example #5](#5-halting-queue-upon-conditional-logic). |
+| **`isSkippable?:Function`** | Returning a truthy value prevents the queue from being halted in case of $.Ajax error. See [example #6](#6-preventing-a-queue-from-being-halted-in-case-of-ajax-error). |
 
 **Note:** All functions specified as values of optional configuration object properties (marked with a question mark) are passed the dequeued Ajax call response as argument.
 
@@ -60,7 +60,7 @@ Examples
 var ajaxChain = new $.AjaxChain();
 ajaxChain.enqueue([configurationObject[,configurationObjectN, ... ]])
          .dequeue()
-		 .then(doneCallback, failCallback, progressCallback);
+         .then(doneCallback, failCallback, progressCallback);
 ```
 ### Common configuration patterns ###
 ```xml
@@ -111,7 +111,7 @@ configurationObj1 = {
 configurationObj2 = { . . . };
 ajaxChain.enqueue([configurationObj1, configurationObj2])
          .dequeue()
-		 .then(doneCallback, failCallback, progressCallback);
+         .then(doneCallback, failCallback, progressCallback);
 ```
 ##### 2. Dynamically appending url fragments between succeeding Ajax calls:
 ```javascript
@@ -130,7 +130,7 @@ configurationObj1 = {
         if (xmlResponse) {
             nextCallUrlFragment = "/" + $(xmlResponse).find('item')
                                                       .first()
-												      .attr('id');
+                                                      .attr('id');
         };                 
         return nextCallUrlFragment;               
     }               
@@ -139,7 +139,7 @@ configurationObj1 = {
 configurationObj2 = { . . . };
 ajaxChain.enqueue([configurationObj1, configurationObj2])
          .dequeue()
-		 .then(doneCallback, failCallback, progressCallback);
+         .then(doneCallback, failCallback, progressCallback);
 ```
 ##### 3. Dynamically resolving queue upon custom errors:
 ```javascript
@@ -160,8 +160,8 @@ configurationObj1 = {
         // check current Ajax call response for errors
         if ($tempXmlResponse.find("item").eq(0)
                             .find("categoryId")
-							.text()
-							.indexOf(categoryFilter) !== -1) {
+                            .text()
+                            .indexOf(categoryFilter) !== -1) {
             return "[Exception] forbidden category id: " + categoryFilter;
         }
         return false;         
@@ -171,7 +171,7 @@ configurationObj1 = {
 configurationObj2 = { . . . };
 ajaxChain.enqueue([configurationObj1, configurationObj2])
          .dequeue()
-		 .then(doneCallback, failCallback, progressCallback);
+         .then(doneCallback, failCallback, progressCallback);
 ```
 ##### 4. Creating caching mechanisms:
 ```javascript
@@ -197,7 +197,7 @@ configurationObj1 = {
 configurationObj2 = { . . . };
 ajaxChain.enqueue([configurationObj1, configurationObj2])
          .dequeue()
-		 .then(doneCallback, failCallback, progressCallback);
+         .then(doneCallback, failCallback, progressCallback);
 ```
 ##### 5. Halting queue upon conditional logic:
 ```javascript
@@ -215,8 +215,8 @@ configurationObj1 = {
         var $tempXmlResponse;
         $tempXmlResponse = $(xmlResponse);
         if ($tempXmlResponse.find("item").eq(0)
-		                    .find("categoryId")
-							.text().indexOf("1") !== -1) {
+                            .find("categoryId")
+                            .text().indexOf("1") !== -1) {
             return true;
         }
         return false;        
@@ -226,7 +226,7 @@ configurationObj1 = {
 configurationObj2 = { . . . };
 ajaxChain.enqueue([configurationObj1, configurationObj2])
          .dequeue()
-		 .then(doneCallback, failCallback, progressCallback);
+         .then(doneCallback, failCallback, progressCallback);
 ```
 ##### 6. Preventing a queue from being halted in case of $.Ajax error:
 ```javascript
@@ -248,7 +248,7 @@ configurationObj1 = {
 configurationObj2 = { . . . };
 ajaxChain.enqueue([configurationObj1, configurationObj2])
          .dequeue()
-		 .then(doneCallback, failCallback, progressCallback);
+         .then(doneCallback, failCallback, progressCallback);
 ```
 
 ### TypeScript ###
@@ -271,14 +271,13 @@ ajaxChain.enqueue([configurationObj1, configurationObj2])
 1. Open a shell in the package root folder
 2. `npm install`
 3. `bower install`
-4. `grunt qunit`
+4. `grunt test:headless`
 
 ##### Browser #####
 
 1. Open a shell in the package root folder
 2. `npm install`
 3. `bower install`
-4. Launch a Web server with document root in the current folder (e.g.: `python -m http.server 8888`)
-4. Browse to `/test/ajax-chain.html` page
+4. `grunt test:browser` (`--port` option available, e.g.: `grunt test:browser --port=8083`)
 
 **Note:** this project was packaged with [grunt-init-jquery](https://github.com/gruntjs/grunt-init-jquery).

package.json

@@ -1,48 +1,48 @@
 {
-    "name": "jquery-ajax-chain",
-    "description": "jQuery helper class meant to ease up the process of making multiple synchronously chained Ajax calls.",
-    "keywords": [
-        "jquery-plugin",
-        "javascript",
-        "ajax",
-        "chain",
-        "sequence",
-        "series",
-        "waterfall",
-        "async"
-    ],
-    "version": "1.0.5",
-    "dependencies": {
-        "jquery": ">=1.5.0"
-    },
-    "author": "Andrea Blasio (https://github.com/humana-fragilitas)",
-    "license": "MIT",
-    "main": "./dist/jquery.ajax-chain.min.js",
-    "homepage": "https://github.com/humana-fragilitas",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/humana-fragilitas/jQuery-Ajax-Chain.git"
-    },
-    "bugs": {
-        "url": "https://github.com/humana-fragilitas/jQuery-Ajax-Chain/issues",
-        "email": "[email protected]"
-    },
-    "engines": {
-        "node": ">= 0.8.0"
-    },
-    "scripts": {
-        "test": "grunt qunit"
-    },
-    "dependencies": {
-        "jquery": ">=1.5.0"
-    },
-    "devDependencies": {
-        "grunt-contrib-jshint": "~0.10.0",
-        "grunt-contrib-qunit": "~0.2.0",
-        "grunt-contrib-concat": "~0.3.0",
-        "grunt-contrib-uglify": "~0.2.0",
-        "grunt-contrib-watch": "~0.4.0",
-        "grunt-contrib-clean": "~0.4.0",
-        "grunt": "~0.4.5"
-    }
-}
+  "name": "jquery-ajax-chain",
+  "description": "jQuery helper class meant to ease up the process of making multiple synchronously chained Ajax calls.",
+  "keywords": [
+    "jquery-plugin",
+    "javascript",
+    "ajax",
+    "chain",
+    "sequence",
+    "series",
+    "waterfall",
+    "async"
+  ],
+  "version": "1.0.5",
+  "dependencies": {
+    "jquery": ">=1.5.0"
+  },
+  "author": "Andrea Blasio (https://github.com/humana-fragilitas)",
+  "license": "MIT",
+  "main": "./dist/jquery.ajax-chain.min.js",
+  "homepage": "https://github.com/humana-fragilitas",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/humana-fragilitas/jQuery-Ajax-Chain.git"
+  },
+  "bugs": {
+    "url": "https://github.com/humana-fragilitas/jQuery-Ajax-Chain/issues",
+    "email": "[email protected]"
+  },
+  "engines": {
+    "node": ">= 0.8.0"
+  },
+  "scripts": {
+    "test": "grunt qunit"
+  },
+  "devDependencies": {
+    "grunt": "~0.4.5",
+    "grunt-contrib-clean": "~0.4.0",
+    "grunt-contrib-concat": "~0.3.0",
+    "grunt-contrib-connect": "^1.0.0",
+    "grunt-contrib-jshint": "~0.10.0",
+    "grunt-contrib-qunit": "~0.2.0",
+    "grunt-contrib-uglify": "~0.2.0",
+    "grunt-contrib-watch": "~0.4.0",
+    "install": "^0.6.0",
+    "npm": "^3.8.2"
+  }
+}