remoting/webapp/base/js/base.js

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 /**
   6  * @fileoverview
   7  * A module that contains basic utility components and methods for the
   8  * chromoting project
   9  *
  10  */
  11
  12 'use strict';
  13
  14 /** @suppress {duplicate} */
  15 var base = base || {};
  16
  17 base.debug = function() {};
  18
  19 /**
  20  * Whether to break in debugger and alert when an assertion fails.
  21  * Set it to true for debugging.
  22  * @type {boolean}
  23  */
  24 base.debug.throwOnAssert = false;
  25
  26 /**
  27  * Assert that |expr| is true else print the |opt_msg|.
  28  * @param {boolean} expr
  29  * @param {string=} opt_msg
  30  */
  31 base.debug.assert = function(expr, opt_msg) {
  32   if (!expr) {
  33     if (!opt_msg) {
  34       opt_msg = 'Assertion Failed.';
  35     }
  36     console.error(opt_msg);
  37     if (base.debug.throwOnAssert) {
  38       throw new Error(opt_msg);
  39     }
  40   }
  41 };
  42
  43 /**
  44  * @return {string} The callstack of the current method.
  45  */
  46 base.debug.callstack = function() {
  47   try {
  48     throw new Error();
  49   } catch (/** @type {Error} */ error) {
  50     var callstack = error.stack
  51       .replace(/^\s+(at eval )?at\s+/gm, '') // Remove 'at' and indentation.
  52       .split('\n');
  53     callstack.splice(0,2); // Remove the stack of the current function.
  54   }
  55   return callstack.join('\n');
  56 };
  57
  58 /**
  59   * @interface
  60   */
  61 base.Disposable = function() {};
  62 base.Disposable.prototype.dispose = function() {};
  63
  64 /**
  65  * @constructor
  66  * @param {...base.Disposable} var_args
  67  * @implements {base.Disposable}
  68  */
  69 base.Disposables = function(var_args) {
  70   /**
  71    * @type {Array<base.Disposable>}
  72    * @private
  73    */
  74   this.disposables_ = Array.prototype.slice.call(arguments, 0);
  75 };
  76
  77 /**
  78  * @param {...base.Disposable} var_args
  79  */
  80 base.Disposables.prototype.add = function(var_args) {
  81   var disposables = Array.prototype.slice.call(arguments, 0);
  82   for (var i = 0; i < disposables.length; i++) {
  83     var current = /** @type {base.Disposable} */ (disposables[i]);
  84     if (this.disposables_.indexOf(current) === -1) {
  85       this.disposables_.push(current);
  86     }
  87   }
  88 };
  89
  90 /**
  91  * @param {...base.Disposable} var_args  Dispose |var_args| and remove
  92  *    them from the current object.
  93  */
  94 base.Disposables.prototype.remove = function(var_args) {
  95   var disposables = Array.prototype.slice.call(arguments, 0);
  96   for (var i = 0; i < disposables.length; i++) {
  97     var disposable = /** @type {base.Disposable} */ (disposables[i]);
  98     var index = this.disposables_.indexOf(disposable);
  99     if(index !== -1) {
 100       this.disposables_.splice(index, 1);
 101       disposable.dispose();
 102     }
 103   }
 104 };
 105
 106 base.Disposables.prototype.dispose = function() {
 107   for (var i = 0; i < this.disposables_.length; i++) {
 108     this.disposables_[i].dispose();
 109   }
 110   this.disposables_ = null;
 111 };
 112
 113 /**
 114  * A utility function to invoke |obj|.dispose without a null check on |obj|.
 115  * @param {base.Disposable} obj
 116  */
 117 base.dispose = function(obj) {
 118   if (obj) {
 119     base.debug.assert(typeof obj.dispose == 'function');
 120     obj.dispose();
 121   }
 122 };
 123
 124 /**
 125  * Copy all properties from src to dest.
 126  * @param {Object} dest
 127  * @param {Object} src
 128  */
 129 base.mix = function(dest, src) {
 130   for (var prop in src) {
 131     if (src.hasOwnProperty(prop) && !(prop in dest)) {
 132       dest[prop] = src[prop];
 133     }
 134   }
 135 };
 136
 137 /**
 138  * Adds a mixin to a class.
 139  * @param {Object} dest
 140  * @param {Object} src
 141  * @suppress {checkTypes|reportUnknownTypes}
 142  */
 143 base.extend = function(dest, src) {
 144   base.mix(dest.prototype, src.prototype || src);
 145 };
 146
 147 /**
 148  * Inherits properties and methods from |parentCtor| at object construction time
 149  * using prototypical inheritance. e.g.
 150  *
 151  * var ParentClass = function(parentArg) {
 152  *   this.parentProperty = parentArg;
 153  * }
 154  *
 155  * var ChildClass = function() {
 156  *   base.inherits(this, ParentClass, 'parentArg'); // must be the first line.
 157  * }
 158  *
 159  * var child = new ChildClass();
 160  * child instanceof ParentClass // true
 161  *
 162  * See base_inherits_unittest.js for the guaranteed behavior of base.inherits().
 163  * This lazy approach is chosen so that it is not necessary to maintain proper
 164  * script loading order between the parent class and the child class.
 165  *
 166  * @param {*} childObject
 167  * @param {*} parentCtor
 168  * @param {...} parentCtorArgs
 169  * @suppress {checkTypes|reportUnknownTypes}
 170  */
 171 base.inherits = function(childObject, parentCtor, parentCtorArgs) {
 172   base.debug.assert(parentCtor && parentCtor.prototype,
 173                     'Invalid parent constructor.');
 174   var parentArgs = Array.prototype.slice.call(arguments, 2);
 175
 176   // Mix in the parent's prototypes so that they're available during the parent
 177   // ctor.
 178   base.mix(childObject, parentCtor.prototype);
 179   parentCtor.apply(childObject, parentArgs);
 180
 181   // Note that __proto__ is deprecated.
 182   //   https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/
 183   //   Global_Objects/Object/proto.
 184   // It is used so that childObject instanceof parentCtor will
 185   // return true.
 186   childObject.__proto__.__proto__ = parentCtor.prototype;
 187   base.debug.assert(childObject instanceof parentCtor);
 188 };
 189
 190 base.doNothing = function() {};
 191
 192 /**
 193  * Returns an array containing the values of |dict|.
 194  * @param {!Object} dict
 195  * @return {Array}
 196  */
 197 base.values = function(dict) {
 198   return Object.keys(dict).map(
 199     /** @param {string} key */
 200     function(key) {
 201       return dict[key];
 202     });
 203 };
 204
 205 /**
 206  * @param {*} value
 207  * @return {*} a recursive copy of |value| or null if |value| is not copyable
 208  *   (e.g. undefined, NaN).
 209  */
 210 base.deepCopy = function(value) {
 211   try {
 212     return JSON.parse(JSON.stringify(value));
 213   } catch (e) {}
 214   return null;
 215 };
 216
 217 /**
 218  * @type {boolean|undefined}
 219  * @private
 220  */
 221 base.isAppsV2_ = undefined;
 222
 223 /**
 224  * @return {boolean} True if this is a v2 app; false if it is a legacy app.
 225  */
 226 base.isAppsV2 = function() {
 227   if (base.isAppsV2_ === undefined) {
 228     var manifest = chrome.runtime.getManifest();
 229     base.isAppsV2_ =
 230         Boolean(manifest && manifest.app && manifest.app.background);
 231   }
 232   return base.isAppsV2_;
 233 };
 234
 235 /**
 236  * Joins the |url| with optional query parameters defined in |opt_params|
 237  * See unit test for usage.
 238  * @param {string} url
 239  * @param {Object<string>=} opt_params
 240  * @return {string}
 241  */
 242 base.urlJoin = function(url, opt_params) {
 243   if (!opt_params) {
 244     return url;
 245   }
 246   var queryParameters = [];
 247   for (var key in opt_params) {
 248     queryParameters.push(encodeURIComponent(key) + "=" +
 249                          encodeURIComponent(opt_params[key]));
 250   }
 251   return url + '?' + queryParameters.join('&');
 252 };
 253
 254
 255 /**
 256  * @return {Object<string, string>} The URL parameters.
 257  */
 258 base.getUrlParameters = function() {
 259   var result = {};
 260   var parts = window.location.search.substring(1).split('&');
 261   for (var i = 0; i < parts.length; i++) {
 262     var pair = parts[i].split('=');
 263     result[pair[0]] = decodeURIComponent(pair[1]);
 264   }
 265   return result;
 266 };
 267
 268 /**
 269  * Convert special characters (e.g. &, < and >) to HTML entities.
 270  *
 271  * @param {string} str
 272  * @return {string}
 273  */
 274 base.escapeHTML = function(str) {
 275   var div = document.createElement('div');
 276   div.appendChild(document.createTextNode(str));
 277   return div.innerHTML;
 278 };
 279
 280 /**
 281  * Promise is a great tool for writing asynchronous code. However, the construct
 282  *   var p = new promise(function init(resolve, reject) {
 283  *     ... // code that fulfills the Promise.
 284  *   });
 285  * forces the Promise-resolving logic to reside in the |init| function
 286  * of the constructor.  This is problematic when you need to resolve the
 287  * Promise in a member function(which is quite common for event callbacks).
 288  *
 289  * base.Deferred comes to the rescue.  It encapsulates a Promise
 290  * object and exposes member methods (resolve/reject) to fulfill it.
 291  *
 292  * Here are the recommended steps to follow when implementing an asynchronous
 293  * function that returns a Promise:
 294  * 1. Create a deferred object by calling
 295  *      var deferred = new base.Deferred();
 296  * 2. Call deferred.resolve() when the asynchronous operation finishes.
 297  * 3. Call deferred.reject() when the asynchronous operation fails.
 298  * 4. Return deferred.promise() to the caller so that it can subscribe
 299  *    to status changes using the |then| handler.
 300  *
 301  * Sample Usage:
 302  *  function myAsyncAPI() {
 303  *    var deferred = new base.Deferred();
 304  *    window.setTimeout(function() {
 305  *      deferred.resolve();
 306  *    }, 100);
 307  *    return deferred.promise();
 308  *  };
 309  *
 310  * @constructor
 311  * @template T
 312  */
 313 base.Deferred = function() {
 314   /**
 315    * @private {?function(?):void}
 316    */
 317   this.resolve_ = null;
 318
 319   /**
 320    * @private {?function(?):void}
 321    */
 322   this.reject_ = null;
 323
 324   /**
 325    * @this {base.Deferred}
 326    * @param {function(?):void} resolve
 327    * @param {function(*):void} reject
 328    */
 329   var initPromise = function(resolve, reject) {
 330     this.resolve_ = resolve;
 331     this.reject_ = reject;
 332   };
 333
 334   /**
 335    * @private {!Promise<T>}
 336    */
 337   this.promise_ = new Promise(initPromise.bind(this));
 338 };
 339
 340 /** @param {*} reason */
 341 base.Deferred.prototype.reject = function(reason) {
 342   this.reject_(reason);
 343 };
 344
 345 /** @param {*=} opt_value */
 346 base.Deferred.prototype.resolve = function(opt_value) {
 347   this.resolve_(opt_value);
 348 };
 349
 350 /** @return {!Promise<T>} */
 351 base.Deferred.prototype.promise = function() {
 352   return this.promise_;
 353 };
 354
 355 base.Promise = function() {};
 356
 357 /**
 358  * @param {number} delay
 359  * @return {Promise} a Promise that will be fulfilled after |delay| ms.
 360  */
 361 base.Promise.sleep = function(delay) {
 362   return new Promise(
 363     /** @param {function(*):void} fulfill */
 364     function(fulfill) {
 365       window.setTimeout(fulfill, delay);
 366     });
 367 };
 368
 369
 370 /**
 371  * @param {Promise} promise
 372  * @return {Promise} a Promise that will be fulfilled iff the specified Promise
 373  *     is rejected.
 374  */
 375 base.Promise.negate = function(promise) {
 376   return promise.then(
 377       /** @return {Promise} */
 378       function() {
 379         return Promise.reject();
 380       },
 381       /** @return {Promise} */
 382       function() {
 383         return Promise.resolve();
 384       });
 385 };
 386
 387 /**
 388  * Converts a |method| with callbacks into a Promise.
 389  *
 390  * @param {Function} method
 391  * @param {Array} params
 392  * @param {*=} opt_context
 393  * @param {boolean=} opt_hasErrorHandler whether the method has an error handler
 394  * @return {Promise}
 395  */
 396 base.Promise.as = function(method, params, opt_context, opt_hasErrorHandler) {
 397   return new Promise(function(resolve, reject) {
 398     params.push(resolve);
 399     if (opt_hasErrorHandler) {
 400       params.push(reject);
 401     }
 402     try {
 403       method.apply(opt_context, params);
 404     } catch (/** @type {*} */ e) {
 405       reject(e);
 406     }
 407   });
 408 };
 409
 410 /**
 411  * A mixin for classes with events.
 412  *
 413  * For example, to create an alarm event for SmokeDetector:
 414  * functionSmokeDetector() {
 415  *    base.inherits(this, base.EventSourceImpl);
 416  *    this.defineEvents(['alarm']);
 417  * };
 418  *
 419  * To fire an event:
 420  * SmokeDetector.prototype.onCarbonMonoxideDetected = function() {
 421  *   var param = {} // optional parameters
 422  *   this.raiseEvent('alarm', param);
 423  * }
 424  *
 425  * To listen to an event:
 426  * var smokeDetector = new SmokeDetector();
 427  * smokeDetector.addEventListener('alarm', listenerObj.someCallback)
 428  *
 429  */
 430
 431 /**
 432   * Helper interface for the EventSource.
 433   * @constructor
 434   */
 435 base.EventEntry = function() {
 436   /** @type {Array<function():void>} */
 437   this.listeners = [];
 438 };
 439
 440
 441 /** @interface */
 442 base.EventSource = function() {};
 443
 444  /**
 445   * Add a listener |fn| to listen to |type| event.
 446   * @param {string} type
 447   * @param {Function} fn
 448   */
 449 base.EventSource.prototype.addEventListener = function(type, fn) {};
 450
 451  /**
 452   * Remove a listener |fn| to listen to |type| event.
 453   * @param {string} type
 454   * @param {Function} fn
 455   */
 456 base.EventSource.prototype.removeEventListener = function(type, fn) {};
 457
 458
 459 /**
 460   * @constructor
 461   * Since this class is implemented as a mixin, the constructor may not be
 462   * called.  All initializations should be done in defineEvents.
 463   * @implements {base.EventSource}
 464   */
 465 base.EventSourceImpl = function() {
 466   /** @type {Object<string, base.EventEntry>} */
 467   this.eventMap_;
 468 };
 469
 470 /**
 471   * @param {base.EventSourceImpl} obj
 472   * @param {string} type
 473   */
 474 base.EventSourceImpl.isDefined = function(obj, type) {
 475   base.debug.assert(Boolean(obj.eventMap_),
 476                    "The object doesn't support events");
 477   base.debug.assert(Boolean(obj.eventMap_[type]), 'Event <' + type +
 478     '> is undefined for the current object');
 479 };
 480
 481 base.EventSourceImpl.prototype = {
 482   /**
 483     * Define |events| for this event source.
 484     * @param {Array<string>} events
 485     */
 486   defineEvents: function(events) {
 487     base.debug.assert(!Boolean(this.eventMap_),
 488                      'defineEvents can only be called once.');
 489     this.eventMap_ = {};
 490     events.forEach(
 491       /**
 492         * @this {base.EventSourceImpl}
 493         * @param {string} type
 494         */
 495       function(type) {
 496         base.debug.assert(typeof type == 'string');
 497         this.eventMap_[type] = new base.EventEntry();
 498     }, this);
 499   },
 500
 501   /**
 502     * @param {string} type
 503     * @param {Function} fn
 504     */
 505   addEventListener: function(type, fn) {
 506     base.debug.assert(typeof fn == 'function');
 507     base.EventSourceImpl.isDefined(this, type);
 508
 509     var listeners = this.eventMap_[type].listeners;
 510     listeners.push(fn);
 511   },
 512
 513   /**
 514     * @param {string} type
 515     * @param {Function} fn
 516     */
 517   removeEventListener: function(type, fn) {
 518     base.debug.assert(typeof fn == 'function');
 519     base.EventSourceImpl.isDefined(this, type);
 520
 521     var listeners = this.eventMap_[type].listeners;
 522     // find the listener to remove.
 523     for (var i = 0; i < listeners.length; i++) {
 524       var listener = listeners[i];
 525       if (listener == fn) {
 526         listeners.splice(i, 1);
 527         break;
 528       }
 529     }
 530   },
 531
 532   /**
 533     * Fire an event of a particular type on this object.
 534     * @param {string} type
 535     * @param {*=} opt_details The type of |opt_details| should be ?= to
 536     *     match what is defined in add(remove)EventListener.  However, JSCompile
 537     *     cannot handle invoking an unknown type as an argument to |listener|
 538     *     As a hack, we set the type to *=.
 539     */
 540   raiseEvent: function(type, opt_details) {
 541     base.EventSourceImpl.isDefined(this, type);
 542
 543     var entry = this.eventMap_[type];
 544     var listeners = entry.listeners.slice(0); // Make a copy of the listeners.
 545
 546     listeners.forEach(
 547       /** @param {function(*=):void} listener */
 548       function(listener){
 549         if (listener) {
 550           listener(opt_details);
 551         }
 552     });
 553   }
 554 };
 555
 556
 557 /**
 558   * A lightweight object that helps manage the lifetime of an event listener.
 559   *
 560   * For example, do the following if you want to automatically unhook events
 561   * when your object is disposed:
 562   *
 563   * var MyConstructor = function(domElement) {
 564   *   this.eventHooks_ = new base.Disposables(
 565   *     new base.EventHook(domElement, 'click', this.onClick_.bind(this)),
 566   *     new base.EventHook(domElement, 'keydown', this.onClick_.bind(this)),
 567   *     new base.ChromeEventHook(chrome.runtime.onMessage,
 568   *                              this.onMessage_.bind(this))
 569   *   );
 570   * }
 571   *
 572   * MyConstructor.prototype.dispose = function() {
 573   *   this.eventHooks_.dispose();
 574   *   this.eventHooks_ = null;
 575   * }
 576   *
 577   * @param {base.EventSource} src
 578   * @param {string} eventName
 579   * @param {Function} listener
 580   *
 581   * @constructor
 582   * @implements {base.Disposable}
 583   */
 584 base.EventHook = function(src, eventName, listener) {
 585   this.src_ = src;
 586   this.eventName_ = eventName;
 587   this.listener_ = listener;
 588   src.addEventListener(eventName, listener);
 589 };
 590
 591 base.EventHook.prototype.dispose = function() {
 592   this.src_.removeEventListener(this.eventName_, this.listener_);
 593 };
 594
 595 /**
 596   * An event hook implementation for DOM Events.
 597   *
 598   * @param {HTMLElement|Element|Window|HTMLDocument} src
 599   * @param {string} eventName
 600   * @param {Function} listener
 601   * @param {boolean} capture
 602   *
 603   * @constructor
 604   * @implements {base.Disposable}
 605   */
 606 base.DomEventHook = function(src, eventName, listener, capture) {
 607   this.src_ = src;
 608   this.eventName_ = eventName;
 609   this.listener_ = listener;
 610   this.capture_ = capture;
 611   src.addEventListener(eventName, listener, capture);
 612 };
 613
 614 base.DomEventHook.prototype.dispose = function() {
 615   this.src_.removeEventListener(this.eventName_, this.listener_, this.capture_);
 616 };
 617
 618
 619 /**
 620   * An event hook implementation for Chrome Events.
 621   *
 622   * @param {chrome.Event} src
 623   * @param {Function} listener
 624   *
 625   * @constructor
 626   * @implements {base.Disposable}
 627   */
 628 base.ChromeEventHook = function(src, listener) {
 629   this.src_ = src;
 630   this.listener_ = listener;
 631   src.addListener(listener);
 632 };
 633
 634 base.ChromeEventHook.prototype.dispose = function() {
 635   this.src_.removeListener(this.listener_);
 636 };
 637
 638 /**
 639  * A disposable repeating timer.
 640  *
 641  * @constructor
 642  * @implements {base.Disposable}
 643  */
 644 base.RepeatingTimer = function(/** Function */callback, /** number */interval) {
 645   /** @private */
 646   this.intervalId_ = window.setInterval(callback, interval);
 647 };
 648
 649 base.RepeatingTimer.prototype.dispose = function() {
 650   window.clearInterval(this.intervalId_);
 651   this.intervalId_ = null;
 652 };
 653
 654 /**
 655   * Converts UTF-8 string to ArrayBuffer.
 656   *
 657   * @param {string} string
 658   * @return {ArrayBuffer}
 659   */
 660 base.encodeUtf8 = function(string) {
 661   var utf8String = unescape(encodeURIComponent(string));
 662   var result = new Uint8Array(utf8String.length);
 663   for (var i = 0; i < utf8String.length; i++)
 664     result[i] = utf8String.charCodeAt(i);
 665   return result.buffer;
 666 };
 667
 668 /**
 669   * Decodes UTF-8 string from ArrayBuffer.
 670   *
 671   * @param {ArrayBuffer} buffer
 672   * @return {string}
 673   */
 674 base.decodeUtf8 = function(buffer) {
 675   return decodeURIComponent(
 676       escape(String.fromCharCode.apply(null, new Uint8Array(buffer))));
 677 };
 678
 679 /**
 680  * Generate a nonce, to be used as an xsrf protection token.
 681  *
 682  * @return {string} A URL-Safe Base64-encoded 128-bit random value. */
 683 base.generateXsrfToken = function() {
 684   var random = new Uint8Array(16);
 685   window.crypto.getRandomValues(random);
 686   var base64Token = window.btoa(String.fromCharCode.apply(null, random));
 687   return base64Token.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
 688 };
 689
 690 /**
 691  * @param {string} jsonString A JSON-encoded string.
 692  * @return {Object|undefined} The decoded object, or undefined if the string
 693  *     cannot be parsed.
 694  */
 695 base.jsonParseSafe = function(jsonString) {
 696   try {
 697     return /** @type {Object} */ (JSON.parse(jsonString));
 698   } catch (err) {
 699     return undefined;
 700   }
 701 };
 702
 703 /**
 704  * Size the current window to fit its content vertically.
 705  */
 706 base.resizeWindowToContent = function() {
 707   var appWindow = chrome.app.window.current();
 708   var outerBounds = appWindow.outerBounds;
 709   var borderY = outerBounds.height - appWindow.innerBounds.height;
 710   appWindow.resizeTo(outerBounds.width, document.body.clientHeight + borderY);
 711   // Sometimes, resizing the window causes its position to be reset to (0, 0),
 712   // so restore it explicitly.
 713   appWindow.moveTo(outerBounds.left, outerBounds.top);
 714 };