Fix EZP-21963: create separate "promise-based" build

Gruntfile.js

@@ -1,60 +1,93 @@
 module.exports = function(grunt) {
 
-    var qPath = {
-            "q": "../node_modules/q/q"
-        },
-        testPaths = {
-            "q": "../node_modules/q/q",
-            "jasmineCAPIMatchers": "../test/jasmine/CAPIMatchers"
+    var testPaths = {
+            "jasmineCAPIMatchers": "../test/jasmine/CAPIMatchers",
+            "libs/q": "../node_modules/q/q"
         },
         coveragePaths = {
-            "q": "../node_modules/q/q",
-            "jasmineCAPIMatchers": "../../../test/jasmine/CAPIMatchers"
+            "jasmineCAPIMatchers": "../../../test/jasmine/CAPIMatchers",
+            "libs/q": "../../../node_modules/q/q"
         };
 
     grunt.initConfig({
         requirejs: {
             dist: {
                 options: {
                     almond: true,
-                    name : 'PromiseCAPI',
+                    name : 'CAPI',
                     optimize: "none",
                     baseUrl: "src/",
-                    paths: qPath,
                     out: "dist/CAPI.js",
                     wrap: {
                         startFile: 'wrap/wrap.start.js',
                         endFile: 'wrap/wrap.end.js'
                     }
                 }
             },
-            distmin: {
+            distMin: {
                 options: {
                     almond: true,
-                    name : 'PromiseCAPI',
+                    name : 'CAPI',
                     optimize: "uglify",
                     baseUrl: "src/",
-                    paths: qPath,
                     out: "dist/CAPI-min.js",
                     wrap: {
                         startFile: 'wrap/wrap.start.js',
                         endFile: 'wrap/wrap.end.js'
                     }
                 }
             },
-            testBundle: {
+            distPromise: {
                 options: {
                     almond: true,
                     name : 'PromiseCAPI',
                     optimize: "none",
                     baseUrl: "src/",
-                    paths: qPath,
+                    out: "dist/PromiseCAPI.js",
+                    wrap: {
+                        startFile: 'wrap/wrap.start.js',
+                        endFile: 'wrap/wrap.promise.end.js'
+                    }
+                }
+            },
+            distPromiseMin: {
+                options: {
+                    almond: true,
+                    name : 'PromiseCAPI',
+                    optimize: "uglify",
+                    baseUrl: "src/",
+                    out: "dist/PromiseCAPI-min.js",
+                    wrap: {
+                        startFile: 'wrap/wrap.start.js',
+                        endFile: 'wrap/wrap.promise.end.js'
+                    }
+                }
+            },
+            testBundle: {
+                options: {
+                    almond: true,
+                    name : 'CAPI',
+                    optimize: "none",
+                    baseUrl: "src/",
                     out: "test/manual/jsRestClientBundle/Resources/public/js/CAPI.js",
                     wrap: {
                         startFile: 'wrap/wrap.start.js',
                         endFile: 'wrap/wrap.end.js'
                     }
                 }
+            },
+            testBundlePromise: {
+                options: {
+                    almond: true,
+                    name : 'PromiseCAPI',
+                    optimize: "none",
+                    baseUrl: "src/",
+                    out: "test/manual/jsRestClientBundle/Resources/public/js/PromiseCAPI.js",
+                    wrap: {
+                        startFile: 'wrap/wrap.start.js',
+                        endFile: 'wrap/wrap.promise.end.js'
+                    }
+                }
             }
         },
         jshint: {

README.md

@@ -16,8 +16,18 @@ $ bower install --save ezsystems/ez-js-rest-client
 
 Then you can include in your project the file
 `bower\_components/ez-js-rest-client/dist/CAPI-min.js` (or the non minified
-version). It's also possible to directly take `dist/CAPI.js` or
-`dist/CAPI-min.js` in a clone of this repository.
+version).
+
+There is also an option to use promise-based version of the client (file
+`bower\_components/ez-js-rest-client/dist/PromiseCAPI.js` or
+`bower\_components/ez-js-rest-client/dist/PromiseCAPI-min.js`).
+It provides the same functional but all asynchronous methods are
+promise-wrapped which helps to make code more clean and readable.
+
+Read more about promise-based version in the **Build** section of this manual.
+
+It's also possible to directly take any of the mentioned files in a clone
+of this repository.
 
 ## Development
 
@@ -34,7 +44,7 @@ environment with a help of Grunt task runner.
   ```
 * Install the global dependencies (usually you need to be root)
   ```
-  # npm install -g grunt-cli yuidoc
+  # npm install -g grunt-cli yuidoc bower
   ```
 
 ### API Documentation
@@ -61,7 +71,21 @@ The library can be built with:
 $ grunt build
 ```
 
-This command will (re)generate the files `dist/CAPI.js` and `dist/CAPI-min.js`.
+This command will (re)generate the files `dist/CAPI.js`, `dist/CAPI-min.js`
+and `dist/PromiseCAPI.js`.
+First 2 files are full and minified versions of the regular client library
+which doesn't have any dependencies and is intended for general use.
+
+ The `PromiseCAPI.js` is a promise-based version of the library
+which has a dependency on the Q library. While using this version a developer
+himself is responsible for inclusion of Q library into the project.
+It can be done by using preferred dependency management system or by simply
+downloading and including Q library file into scripts.
+For example see the source file from manual testing bundle:
+`test/manual/jsRestClientBundle/Resources/views/promise.test.html.twig`.
+
+More info on Q and promises: https://github.com/kriskowal/q.
+
 
 ### Tests
 
@@ -108,10 +132,19 @@ using following instruction:
     jsRestClientBundle:
         resource: "@jsRestClientBundle/Resources/config/routing.yml"
     ```
-
+* If you intend to test promise-based version of the CAPI, additionally install
+Q library by running the following command **from the bundle directory**:
+```
+$ bower install
+```
 * Clear the Symfony 2 caches with ezpublish/console.
 
-After these steps you may access `/js-rest-client-test/` path where you will find
-testing html page.  Most of requests can be configured a little bit before
+After these steps you may access `/js-rest-client-test/` path where you will
+find testing html page.  Most of requests can be configured a little bit before
 executing them by changing input values.  See details of tests implementation in
-Resources/public/js/cookbook-*.js files.
+`Resources/public/js/cookbook-*.js` files.
+
+To test promise-based version of the CAPI you can use
+`/js-rest-client-promise-test/` path.
+This setup includes Q library as a bower package. See details of (rather basic)
+tests implementation in `Resources/public/js/cookbook-PromiseCAPI.js`.