Bake in support for promises.

This means we can specify the SDK's dependency on Q to make setting things up
significantly easier.

lib/client.js

@@ -3,7 +3,6 @@
  * This is an internal module. See {@link MatrixClient} for the public class.
  * @module client
  */
-
 var httpApi = require("./http-api");
 var MatrixEvent = require("./models/event").MatrixEvent;
 var MatrixInMemoryStore = require("./store/memory").MatrixInMemoryStore;
@@ -12,27 +11,6 @@ var utils = require("./utils");
 // TODO:
 // Internal: rate limiting
 
-/**
- * The standard MatrixClient callback interface. Functions which accept this
- * will specify 2 return arguments. These arguments map to the 2 parameters
- * specified in this callback.
- * @callback module:client.callback
- * @param {Object} err The error value, the "rejected" value or null.
- * @param {Object} data The data returned, the "resolved" value.
- */
-
- /**
-  * {@link https://github.com/kriskowal/q|A promise implementation (Q)}. Functions
-  * which return this will specify 2 return arguments. These arguments map to the
-  * "onFulfilled" and "onRejected" values of the Promise.
-  * @typedef {Object} Promise
-  * @static
-  * @property {Function} then promise.then(onFulfilled, onRejected, onProgress)
-  * @property {Function} catch promise.catch(onRejected)
-  * @property {Function} finally promise.finally(callback)
-  * @property {Function} done promise.done(onFulfilled, onRejected, onProgress)
-  */
-
 /**
  * Construct a Matrix Client.
  * @constructor
@@ -746,4 +724,25 @@ module.exports.MatrixClient.prototype = {
     stopClient: function() {
         this.clientRunning = false;
     },
-};
+};
+
+/**
+ * The standard MatrixClient callback interface. Functions which accept this
+ * will specify 2 return arguments. These arguments map to the 2 parameters
+ * specified in this callback.
+ * @callback module:client.callback
+ * @param {Object} err The error value, the "rejected" value or null.
+ * @param {Object} data The data returned, the "resolved" value.
+ */
+
+ /**
+  * {@link https://github.com/kriskowal/q|A promise implementation (Q)}. Functions
+  * which return this will specify 2 return arguments. These arguments map to the
+  * "onFulfilled" and "onRejected" values of the Promise.
+  * @typedef {Object} Promise
+  * @static
+  * @property {Function} then promise.then(onFulfilled, onRejected, onProgress)
+  * @property {Function} catch promise.catch(onRejected)
+  * @property {Function} finally promise.finally(callback)
+  * @property {Function} done promise.done(onFulfilled, onRejected, onProgress)
+  */

lib/http-api.js

@@ -3,7 +3,7 @@
  * This is an internal module. See {@link MatrixHttpApi} for the public class.
  * @module http-api
  */
-
+var q = require("q");
 var utils = require("./utils");
 
 /*
@@ -162,36 +162,39 @@ module.exports.MatrixHttpApi.prototype = {
                 "Expected callback to be a function but got " + typeof callback
             );
         }
-
-        return this.opts.request(
-        {
-            uri: uri,
-            method: method,
-            withCredentials: false,
-            qs: queryParams,
-            body: data,
-            json: true,
-            headers: HEADERS,
-            _matrix_opts: this.opts
-        },
-        requestCallback(callback)
+        var defer = q.defer();
+        this.opts.request(
+            {
+                uri: uri,
+                method: method,
+                withCredentials: false,
+                qs: queryParams,
+                body: data,
+                json: true,
+                headers: HEADERS,
+                _matrix_opts: this.opts
+            },
+            requestCallback(defer, callback)
         );
+        return defer.promise;
     }
 };
 
 
-var requestCallback = function(userDefinedCallback) {
-    if (!userDefinedCallback) {
-        return undefined;
-    }
+var requestCallback = function(defer, userDefinedCallback) {
+    userDefinedCallback = userDefinedCallback || function(){};
+    
     return function(err, response, body) {
-        if (err) {
-            return userDefinedCallback(err);
+        if (!err && response.statusCode >= 400) {
+            err = new module.exports.MatrixError(body);
         }
-        if (response.statusCode >= 400) {
-            return userDefinedCallback(new Error(body));
+
+        if (err) {
+            defer.reject(err);
+            userDefinedCallback(err);
         }
         else {
+            defer.resolve(body);
             userDefinedCallback(null, body);
         }
     };
@@ -212,4 +215,4 @@ module.exports.MatrixError = function MatrixError(errorJson) {
     this.data = errorJson;
 }
 module.exports.MatrixError.prototype = Object.create(Error.prototype);
-module.exports.MatrixError.prototype.constructor = MatrixError;
+module.exports.MatrixError.prototype.constructor = module.exports.MatrixError;

lib/matrix-promise.js

@@ -1,42 +0,0 @@
-// Wraps all matrix.js API calls in Q promises. To use this, simply
-// require("matrix-promise") instead of require("matrix").
-//
-// API calls usually accept callback functions. However, all API calls
-// also return the result from request(opts, callback). It seems pointless
-// to return from this since it is always "undefined". However, the "request"
-// module is also injected into the SDK. This allows us to wrap the
-// "request" module to return a promise, which is then passed all the
-// way back up to the public facing API call.
-//
-// This wrapper is designed for Node.js development, but a similar
-// technique can be trivially applied on the browser (e.g. for AngularJS)
-"use strict";
-
-var matrixcs = require("./matrix");
-var request = require("request");
-var q = require("q");
-
-matrixcs.request(function(opts, callback) {
-    var defer = q.defer();
-    request(opts, function(err, response, body) {
-        // TODO possibly expose a responseHandler API
-        // to avoid duplicating the 400 check with the core lib.
-        if (err) {
-            defer.reject(err);
-            return;
-        }
-        if (response.statusCode >= 400) {
-            defer.reject(body);
-        }
-        else {
-            defer.resolve(body);
-        }
-    });
-    return defer.promise;
-});
-
-/**
- * Export a modified matrix library with Promise support.
- */
-module.exports = matrixcs;
-

package.json

@@ -20,6 +20,7 @@
   "dependencies": {
     "browser-request": "^0.3.3",
     "browserify": "^10.2.3",
+    "q": "^1.4.1",
     "request": "^2.53.0"
   },
   "devDependencies": {