Promises extras update

src/promise/HISTORY.md

@@ -4,6 +4,12 @@ Promise Change History
 @VERSION@
 ------
 
+* Split the module into promise-core and promise-extras
+* then() no longer returns an instance of this.constructor
+* Added combinators, factories and extra methods
+* [!] Deprecated Y.batch() in favor of Y.Promise.every()
+* The first function received as parameter of the Promise init function is now
+  a reference to resolve() instead of fulfill()
 * Changed the value of |this| inside callbacks to undefined to match the
   Promises A+ spec
 

src/promise/build.json

@@ -2,12 +2,19 @@
 	"name": "promise",
 
 	"builds": {
-		"promise": {
+		"promise-core": {
 			"jsfiles": [
 				"promise.js",
-				"resolver.js",
-				"when.js",
-				"batch.js"
+				"resolver.js"
+			]
+		},
+		"promise-extras": {
+			"jsfiles": [
+				"extras/when.js",
+				"extras/methods.js",
+				"extras/factories.js",
+				"extras/combinators.js",
+				"extras/batch.js"
 			]
 		}
 	}

src/promise/docs/basic-example.mustache

@@ -56,15 +56,15 @@ getUser: function (name) {
 ```
 // Fetches a URL, stores a promise in the cache and returns it
 function fetch(url) {
-    var promise = new Y.Promise(function (fulfill, reject) {
+    var promise = new Y.Promise(function (resolve, reject) {
         Y.jsonp(url, function (res) {
             var meta = res.meta,
                 data = res.data;
 
             // Check for a successful response, otherwise reject the
             // promise with the message returned by the GitHub API.
             if (meta.status >= 200 && meta.status < 300) {
-                fulfill(data);
+                resolve(data);
             } else {
                 reject(new Error(data.message));
             }

src/promise/docs/component.json

@@ -18,13 +18,6 @@
 	        "modules": ["promise", "jsonp"],
 	        "useModules": ["promise", "jsonp"]
         },
-        {
-            "name": "subclass-example",
-	        "displayName": "Subclassing Y.Promise",
-	        "description": "Extend Y.Promise to create classes that encapsulate standard transaction logic in descriptive method names",
-	        "modules": ["promise", "jsonp"],
-	        "useModules": ["promise", "jsonp"]
-        },
         {
             "name"       : "plugin-example",
             "displayName": "Creating a Node Plugin that chains transitions",

src/promise/docs/index.mustache

@@ -476,33 +476,33 @@ MyDatabase.prototype.save = function (key, data) {
 };
 ```
 
-<h3>Non-serial Operation Batching</h3>
+<h3>Handling multiple non-sequential operations</h3>
 
 <p>
     Promise chaining works great to serialize synchronous and asynchronous
     operations, but often several asynchronous operations can be performed
-    simultaneously. This is where `Y.batch()` comes in.
+    simultaneously. This is where `Y.Promise.every()` comes in.
 </p>
 
 <p>
-    `Y.batch()` takes any number of promises as arguments, and returns a new
-    promise that will resolve when all the batched promises have resolved. The
+    `Y.Promise.every()` takes an array of promises, and returns a new promise
+    that will resolve when all the promises in the array have resolved. The
     resolved value will be an array of values from the individual promises, in
-    the order they were passed to `Y.batch()`.
+    the order they were passed to `Y.Promise.every()`.
 </p>
 
 <p>
-    If any one of the batched promises should be rejected, the batch promise
-    is immediately rejected with that reason, so failures can be dealt with
-    sooner rather than later.
+    If any one of the promises in the list should be rejected, the returned
+    promise is immediately rejected with that reason, so failures can be dealt
+    with sooner rather than later.
 </p>
 
 ```
-Y.batch(
+Y.Promise.every([
         getUserAccountInfo(userId),
         getUserPosts(userId, { page: 1, postsPerPage: 5 }),
         getUserRank(userId)
-    )
+    ])
     .then(function (data) {
         var account = data[0],
             posts   = data[1],
@@ -564,13 +564,13 @@ Y.batch(
 <h4>`Y.Parallel`</h4>
 
 <p>
-    `Y.Parallel` is similar to `Y.batch` in that it provides a mechanism to
-    execute a callback when several independent asynchronous operations have
-    completed. However, it doesn't handle errors or guarantee asynchronous
-    callback execution. It is also transactional, but the batch of operations
-    is bound to a specific callback, where `Y.batch()` returns a promise that
-    represents the aggregated values of those operations. The promise can be
-    used by multiple consumers if necessary.
+    `Y.Parallel` is similar to `Y.Promise.every()` in that it provides a
+    mechanism to execute a callback when several independent asynchronous
+    operations have completed. However, it doesn't handle errors or guarantee
+    asynchronous callback execution. It is also transactional, but the list of
+    operations is bound to a specific callback, where `Y.Promise.every()`
+    returns a promise that represents the aggregated values of those operations.
+    The promise can be used by multiple consumers if necessary.
 </p>
 
 <h3 id="plans">What are the plans for Promises in the library?</h3>

src/promise/docs/partials/github-cache.mustache

@@ -12,15 +12,15 @@ var GitHub = (function () {
 
     // Fetches a URL, stores a promise in the cache and returns it
     function fetch(url) {
-        var promise = new Y.Promise(function (fulfill, reject) {
+        var promise = new Y.Promise(function (resolve, reject) {
             Y.jsonp(url, function (res) {
                 var meta = res.meta,
                     data = res.data;
 
                 // Check for a successful response, otherwise reject the
                 // promise with the message returned by the GitHub API.
                 if (meta.status >= 200 && meta.status < 300) {
-                    fulfill(data);
+                    resolve(data);
                 } else {
                     reject(new Error(data.message));
                 }

src/promise/docs/partials/node-plugin-plugin.mustache

@@ -1,8 +1,8 @@
 function PromisePlugin(config) {
     // Create a private NodePromise instance that points to the plugin host
-    this._promise = new NodePromise(function (fulfill) {
+    this._promise = new NodePromise(function (resolve) {
         // Since this is a Node plugin, config.host will be an instance of Node
-        fulfill(config.host);
+        resolve(config.host);
     });
 }
 

src/promise/docs/partials/node-plugin-transition.mustache

@@ -1,19 +1,17 @@
 // This method takes the same "config" parameter as Node's transition method
 // but returns a NodePromise instead
 NodePromise.prototype.transition = function (config) {
-    // We call this.then to ensure the promise is fulfilled.
-    // Since we will be creating a chain of transitions this means we will be
-    // waiting for the previous transition to end
-    return this.then(function (node) {
-        // As noted in the user guide, returning a promise inside the then()
-        // callback causes the promise returned by then() to be synced with this
-        // new promise. This is a way to control when the returned promise is
-        // fulfilled
-        return new Y.Promise(function (fulfill, reject) {
+    var promise = this;
+
+    // Return a new NodePromise so that chaining calls to transition()
+    // results in transition executed sequentially
+    return new NodePromise(function (resolve, reject) {
+        // Call promise.then to the previous transition ended
+        promise.then(function (node) {
             node.transition(config, function () {
                 // The transition is done, signal the promise that all is ready
                 // by fulfilling it with the same node
-                fulfill(node);
+                resolve(node);
             });
         });
     });

src/promise/js/batch.js → src/promise/js/extras/batch.js

@@ -1,17 +1,18 @@
-var slice = [].slice;
-
 /**
 Returns a new promise that will be resolved when all operations have completed.
-Takes both any numer of values as arguments. If an argument is a not a promise,
-it will be wrapped in a new promise, same as in `Y.when()`.
+Takes both callbacks and promises as arguments. If an argument is a callback,
+it will be wrapped in a new promise.
 
 @for YUI
 @method batch
-@param {Any} operation* Any number of Y.Promise objects or regular JS values
-@return {Promise} Promise to be fulfilled when all provided promises are
-                    resolved
+@param {Function|Promise} operation* Any number of functions or Y.Promise
+            objects
+@return {Promise}
+@deprecated @SINCE@
 **/
 Y.batch = function () {
+    Y.log('batch() was deprecated in YUI @SINCE@. Use Promise.every()', 'warn');
+
     var funcs     = slice.call(arguments),
         remaining = funcs.length,
         i         = 0,