diff --git a/dist/browser-matrix-dev.js b/dist/browser-matrix-dev.js index 93b1e65b6..7aad831fd 100644 --- a/dist/browser-matrix-dev.js +++ b/dist/browser-matrix-dev.js @@ -22,7 +22,7 @@ function MatrixClient(opts) { utils.checkObjectHasNoAdditionalKeys(opts, ["baseUrl", "request", "usePromises", "accessToken", "userId", "store"] ); - + this.store = opts.store || null; // track our position in the overall eventstream this.fromToken = undefined; @@ -308,7 +308,7 @@ MatrixClient.prototype = { 'bind': bind }; return this._http.authedRequestWithPrefix( - callback, "POST", path, qps, data, httpApi.PREFIX_V2_ALPHA + callback, "POST", path, null, data, httpApi.PREFIX_V2_ALPHA ); }, @@ -464,7 +464,7 @@ MatrixClient.prototype = { }, isLoggedIn: function() { - return this._http.opts.accessToken !== undefined + return this._http.opts.accessToken !== undefined; }, @@ -741,6 +741,7 @@ var HEADERS = { /** * Construct a MatrixHttpApi. + * @constructor * @param {Object} opts The options to use for this HTTP API. * @param {string} opts.baseUrl Required. The base client-server URL e.g. * 'http://localhost:8008'. @@ -869,7 +870,7 @@ MatrixHttpApi.prototype = { _request: function(callback, method, uri, queryParams, data) { if (callback !== undefined && !utils.isFunction(callback)) { throw Error( - "Expected callback to be a function but got "+typeof callback + "Expected callback to be a function but got " + typeof callback ); } @@ -937,7 +938,7 @@ module.exports.request = function(r) { request = r; }; -/* +/** * Construct a Matrix Client. Identical to {@link client/MatrixClient} except * the 'request' option is already specified. * @param {(Object|string)} opts The configuration options for this client. If @@ -946,6 +947,7 @@ module.exports.request = function(r) { * @param {boolean} opts.usePromises True to use promises rather than callbacks. * @param {string} opts.accessToken The access_token for this user. * @param {string} opts.userId The user ID for this user. + * @return {MatrixClient} A new matrix client. */ module.exports.createClient = function(opts) { if (typeof opts === "string") { @@ -1166,7 +1168,12 @@ module.exports = MatrixInMemoryStore; "use strict"; -// avoiding deps on jquery and co +/** + * Encode a dictionary of query parameters. + * @param {Object} params A dict of key/values to encode e.g. + * {"foo": "bar", "baz": "taz"} + * @return {string} The encoded string e.g. foo=bar&baz=taz + */ module.exports.encodeParams = function(params) { var qs = ""; for (var key in params) { @@ -1177,6 +1184,14 @@ module.exports.encodeParams = function(params) { return qs.substring(1); }; +/** + * Encodes a URI according to a set of template variables. Variables will be + * passed through encodeURIComponent. + * @param {string} pathTemplate The path with template variables e.g. '/foo/$bar'. + * @param {Object} variables The key/value pairs to replace the template + * variables with. E.g. { "$bar": "baz" }. + * @return {string} The result of replacing all template variables e.g. '/foo/baz'. + */ module.exports.encodeUri = function(pathTemplate, variables) { for (var key in variables) { if (!variables.hasOwnProperty(key)) { continue; } @@ -1187,6 +1202,13 @@ module.exports.encodeUri = function(pathTemplate, variables) { return pathTemplate; }; +/** + * Applies a map function to the given array. + * @param {Array} array The array to apply the function to. + * @param {Function} fn The function that will be invoked for each element in + * the array. + * @return {Array} A new array with the results of the function. + */ module.exports.map = function(array, fn) { var results = new Array(array.length); for (var i = 0; i < array.length; i++) { @@ -1195,26 +1217,44 @@ module.exports.map = function(array, fn) { return results; }; +/** + * Checks if the given thing is a function. + * @param {*} value The thing to check. + * @return {boolean} True if it is a function. + */ module.exports.isFunction = function(value) { return Object.prototype.toString.call(value) == "[object Function]"; }; +/** + * Checks that the given object has the specified keys. + * @param {Object} obj The object to check. + * @param {string[]} keys The list of keys that 'obj' must have. + * @throws If the object is missing keys. + */ module.exports.checkObjectHasKeys = function(obj, keys) { for (var i = 0; i < keys.length; i++) { if (!obj.hasOwnProperty(keys[i])) { - throw new Error("Missing required key: "+keys[i]); + throw new Error("Missing required key: " + keys[i]); } } }; +/** + * Checks that the given object has no extra keys other than the specified ones. + * @param {Object} obj The object to check. + * @param {string[]} allowedKeys The list of allowed key names. + * @throws If there are extra keys. + */ module.exports.checkObjectHasNoAdditionalKeys = function(obj, allowedKeys) { for (var key in obj) { if (!obj.hasOwnProperty(key)) { continue; } if (allowedKeys.indexOf(key) === -1) { - throw new Error("Unknown key: "+key); + throw new Error("Unknown key: " + key); } } }; + },{}],7:[function(require,module,exports){ // Browser Request // diff --git a/lib/client.js b/lib/client.js index 019338d4f..e8aff561c 100644 --- a/lib/client.js +++ b/lib/client.js @@ -21,7 +21,7 @@ function MatrixClient(opts) { utils.checkObjectHasNoAdditionalKeys(opts, ["baseUrl", "request", "usePromises", "accessToken", "userId", "store"] ); - + this.store = opts.store || null; // track our position in the overall eventstream this.fromToken = undefined; @@ -307,7 +307,7 @@ MatrixClient.prototype = { 'bind': bind }; return this._http.authedRequestWithPrefix( - callback, "POST", path, qps, data, httpApi.PREFIX_V2_ALPHA + callback, "POST", path, null, data, httpApi.PREFIX_V2_ALPHA ); }, @@ -463,7 +463,7 @@ MatrixClient.prototype = { }, isLoggedIn: function() { - return this._http.opts.accessToken !== undefined + return this._http.opts.accessToken !== undefined; }, diff --git a/lib/http-api.js b/lib/http-api.js index 56b416d2c..abbcf8dd8 100644 --- a/lib/http-api.js +++ b/lib/http-api.js @@ -26,6 +26,7 @@ var HEADERS = { /** * Construct a MatrixHttpApi. + * @constructor * @param {Object} opts The options to use for this HTTP API. * @param {string} opts.baseUrl Required. The base client-server URL e.g. * 'http://localhost:8008'. @@ -154,7 +155,7 @@ MatrixHttpApi.prototype = { _request: function(callback, method, uri, queryParams, data) { if (callback !== undefined && !utils.isFunction(callback)) { throw Error( - "Expected callback to be a function but got "+typeof callback + "Expected callback to be a function but got " + typeof callback ); } diff --git a/lib/matrix.js b/lib/matrix.js index 44678ab38..303a39773 100644 --- a/lib/matrix.js +++ b/lib/matrix.js @@ -20,7 +20,7 @@ module.exports.request = function(r) { request = r; }; -/* +/** * Construct a Matrix Client. Identical to {@link client/MatrixClient} except * the 'request' option is already specified. * @param {(Object|string)} opts The configuration options for this client. If @@ -29,6 +29,7 @@ module.exports.request = function(r) { * @param {boolean} opts.usePromises True to use promises rather than callbacks. * @param {string} opts.accessToken The access_token for this user. * @param {string} opts.userId The user ID for this user. + * @return {MatrixClient} A new matrix client. */ module.exports.createClient = function(opts) { if (typeof opts === "string") { diff --git a/lib/utils.js b/lib/utils.js index 5ca6632f6..3f6748369 100644 --- a/lib/utils.js +++ b/lib/utils.js @@ -1,7 +1,12 @@ "use strict"; -// avoiding deps on jquery and co +/** + * Encode a dictionary of query parameters. + * @param {Object} params A dict of key/values to encode e.g. + * {"foo": "bar", "baz": "taz"} + * @return {string} The encoded string e.g. foo=bar&baz=taz + */ module.exports.encodeParams = function(params) { var qs = ""; for (var key in params) { @@ -12,6 +17,14 @@ module.exports.encodeParams = function(params) { return qs.substring(1); }; +/** + * Encodes a URI according to a set of template variables. Variables will be + * passed through encodeURIComponent. + * @param {string} pathTemplate The path with template variables e.g. '/foo/$bar'. + * @param {Object} variables The key/value pairs to replace the template + * variables with. E.g. { "$bar": "baz" }. + * @return {string} The result of replacing all template variables e.g. '/foo/baz'. + */ module.exports.encodeUri = function(pathTemplate, variables) { for (var key in variables) { if (!variables.hasOwnProperty(key)) { continue; } @@ -22,6 +35,13 @@ module.exports.encodeUri = function(pathTemplate, variables) { return pathTemplate; }; +/** + * Applies a map function to the given array. + * @param {Array} array The array to apply the function to. + * @param {Function} fn The function that will be invoked for each element in + * the array. + * @return {Array} A new array with the results of the function. + */ module.exports.map = function(array, fn) { var results = new Array(array.length); for (var i = 0; i < array.length; i++) { @@ -30,23 +50,40 @@ module.exports.map = function(array, fn) { return results; }; +/** + * Checks if the given thing is a function. + * @param {*} value The thing to check. + * @return {boolean} True if it is a function. + */ module.exports.isFunction = function(value) { return Object.prototype.toString.call(value) == "[object Function]"; }; +/** + * Checks that the given object has the specified keys. + * @param {Object} obj The object to check. + * @param {string[]} keys The list of keys that 'obj' must have. + * @throws If the object is missing keys. + */ module.exports.checkObjectHasKeys = function(obj, keys) { for (var i = 0; i < keys.length; i++) { if (!obj.hasOwnProperty(keys[i])) { - throw new Error("Missing required key: "+keys[i]); + throw new Error("Missing required key: " + keys[i]); } } }; +/** + * Checks that the given object has no extra keys other than the specified ones. + * @param {Object} obj The object to check. + * @param {string[]} allowedKeys The list of allowed key names. + * @throws If there are extra keys. + */ module.exports.checkObjectHasNoAdditionalKeys = function(obj, allowedKeys) { for (var key in obj) { if (!obj.hasOwnProperty(key)) { continue; } if (allowedKeys.indexOf(key) === -1) { - throw new Error("Unknown key: "+key); + throw new Error("Unknown key: " + key); } } -}; \ No newline at end of file +};