Add analytics.ready(name, fn) function

See segmentio/analytics.js#409

This adds the ability to set a ready callback per integration.

todo:

* document the function behaviour (need help here on what syntax to use)
* test for already readied integration

Author: f2prateek

lib/analytics.js

@@ -45,6 +45,7 @@ function Analytics() {
   this.Integrations = {};
   this._integrations = {};
   this._readied = false;
+  this._readiedIntegrations = {};
   this._timeout = 300;
   // XXX: BACKWARDS COMPATIBILITY
   this._user = user;
@@ -106,6 +107,7 @@ Analytics.prototype.init = Analytics.prototype.initialize = function(settings, o
 
   this._options(options);
   this._readied = false;
+  this._readiedIntegrations = {};
 
   // clean unknown integrations from settings
   var self = this;
@@ -146,8 +148,14 @@ Analytics.prototype.init = Analytics.prototype.initialize = function(settings, o
       integration.page = after(2, integration.page);
     }
 
+    var integrationReady = function() {
+      self._readiedIntegrations[integration.name] = true;
+      self.emit(integration.name + '-ready');
+      ready();
+    };
+
     integration.analytics = self;
-    integration.once('ready', ready);
+    integration.once('ready', integrationReady);
     integration.initialize();
   }, integrations);
 
@@ -496,14 +504,55 @@ Analytics.prototype.alias = function(to, from, options, fn) {
   return this;
 };
 
+/**
+ * Register a `fn` to be fired when integrations are ready.
+ * If the first parameter is a function `fn`, `fn` is firsted when all
+ * integrations are ready.
+ * If the first parameter is a name and the second parameter is a function `fn`,
+ * `fn` is fired when the given integration is ready.
+ *
+ * It is recommended that you use the latter, as the global ready callback may
+ * not be fired if a single integration fails to load.
+ * See https://github.com/segmentio/analytics.js/issues/409.
+ *
+ * @param {(Function|String)} a
+ * @param {Function} b
+ * @return {Analytics}
+ */
+
+Analytics.prototype.ready = function(a, b) {
+  if (is.fn(a)) {
+    return this._ready(a);
+  }
+  return this._integrationReady(a, b);
+};
+
+/**
+ * Register a `fn` to be fired when the given analytics service is ready.
+ *
+ * @param {Function} fn
+ * @return {Analytics}
+ */
+
+Analytics.prototype._integrationReady = function(name, fn) {
+  if (is.fn(fn)) {
+    if (this._readiedIntegrations[name]) {
+      nextTick(fn);
+    } else {
+      this.once(name + '-ready', fn);
+    }
+  }
+  return this;
+};
+
 /**
  * Register a `fn` to be fired when all the analytics services are ready.
  *
  * @param {Function} fn
  * @return {Analytics}
  */
 
-Analytics.prototype.ready = function(fn) {
+Analytics.prototype._ready = function(fn) {
   if (is.fn(fn)) {
     if (this._readied) {
       nextTick(fn);

package.json

@@ -69,12 +69,12 @@
     "eslint-plugin-require-path-exists": "^1.1.5",
     "istanbul": "^0.4.3",
     "jquery": "^1.12.3",
-    "karma": "^0.13.22",
+    "karma": "1.3.0",
     "karma-browserify": "^5.0.4",
     "karma-chrome-launcher": "^1.0.1",
     "karma-coverage": "^1.0.0",
     "karma-junit-reporter": "^1.0.0",
-    "karma-mocha": "^1.0.1",
+    "karma-mocha": "1.0.1",
     "karma-phantomjs-launcher": "^1.0.0",
     "karma-sauce-launcher": "^1.0.0",
     "karma-spec-reporter": "0.0.26",

test/analytics.test.js

@@ -65,6 +65,10 @@ describe('Analytics', function() {
     assert(analytics._readied === false);
   });
 
+  it('should setup an _readiedIntegrations object', function() {
+    assert(type(analytics._readiedIntegrations) === 'object');
+  });
+
   it('should set a default timeout', function() {
     analytics = new Analytics();
     assert(analytics._timeout === 300);
@@ -128,6 +132,13 @@ describe('Analytics', function() {
       assert(!analytics._readied);
     });
 
+    it('should reset analytics._readiedIntegrations to {}', function() {
+      analytics.addIntegration(Test);
+      analytics._readiedIntegrations = { Test: true };
+      analytics.initialize(settings);
+      assert(!analytics._readiedIntegrations.Test);
+    });
+
     it('should add integration instance', function(done) {
       Test.readyOnInitialize();
       analytics.addIntegration(Test);
@@ -159,6 +170,13 @@ describe('Analytics', function() {
       analytics.initialize({ Unknown: { key: 'key' } });
     });
 
+    it('should listen on integration ready events for integration', function(done) {
+      Test.readyOnInitialize();
+      analytics.addIntegration(Test);
+      analytics.ready('Test', done);
+      analytics.initialize(settings);
+    });
+
     it('should set analytics._readied to true', function(done) {
       analytics.ready(function() {
         assert(analytics._readied);