Add cause/from

Pass through metadata about the request. Useful for logging purposes.

Author: matthewwithanm

README.md

@@ -153,6 +153,18 @@ their APIs.
 - **fragment:String**: The hash portion of the requested URL, excluding the hash
   mark. e.g. `'this-is-the-hash'`
 - **first:Boolean**: Is this the first request being handled by this router?
+- **from(causes:String...):Boolean**: Check the cause of the request. Causes
+  that monorouter sends are:
+
+  * `"startup"` - When a request is triggered by the router initialization in
+    the browser.
+  * `"popstate"` - When a request is triggered by a popstate event
+  * `"link"` - When a request is triggered by a link click captured by the link
+    hijacker
+
+  You may also send custom causes. For example, [connect-monorouter] uses the
+  string '"httprequest"'. Generally, causes shouldn't be used to affect routing
+  behavior—they are meant primarily for logging.
 
 
 ### Handler Context

lib/LinkHijacker.js

@@ -80,7 +80,7 @@ LinkHijacker.prototype.handleClick = function(event) {
   event.preventDefault();
 
   // Dispatch the URL.
-  this.router.history.navigate(fullPath);
+  this.router.history.navigate(fullPath, {cause: 'link'});
 };
 
 module.exports = LinkHijacker;

lib/Request.js

@@ -52,6 +52,7 @@ function Request(url, opts) {
   this.fragment = parsed.hash.replace(/^#/, '');
   this.initialOnly = opts && opts.initialOnly;
   this.first = opts && opts.first;
+  this.cause = opts && opts.cause;
 }
 
 // Make requests event emitters.
@@ -67,6 +68,22 @@ Request.prototype.param = function(indexOrName) {
   return this.params[indexOrName];
 };
 
+/**
+ * Check whether the request triggered by one of the the specified causes.
+ */
+Request.prototype.from = function() {
+  var causes;
+  if (typeof arguments[0] === 'string') causes = arguments;
+  else causes = arguments[0];
+
+  if (causes && causes.length) {
+    for (var i = 0, len = causes.length; i < len; i++) {
+      if (causes[i] === this.cause) return true;
+    }
+  }
+  return false;
+};
+
 Request.prototype.cancel = function() {
   if (!this.canceled) {
     this.canceled = true;

lib/Router.js

@@ -132,8 +132,10 @@ Router.prototype.dispatch = function(url, opts, callback) {
     if (callback) callback(err, err ? null : res);
   }.bind(this);
 
+  var first = (opts && opts.first) || !this._dispatchedFirstRequest;
   var req = new Request(url, extend(opts, {
-    first: (opts && opts.first) || !this._dispatchedFirstRequest,
+    cause: opts && opts.cause,
+    first: first,
     root: RouterClass.rootUrl
   }));
   this._dispatchedFirstRequest = true;

lib/__tests__/Request-test.js

@@ -49,4 +49,14 @@ describe('Request', function() {
     expect(req.originalUrl).toBe('/a/b/c?search=hi');
   });
 
+  it('can tell you the cause', function() {
+    var req = new Request('http://example.com/a/b/c?search=hi',
+                          {cause: 'popstate'});
+    expect(req.from('popstate')).toBe(true);
+    expect(req.from('somethingelse')).toBe(false);
+    expect(req.from('somethingelse', 'popstate')).toBe(true);
+    expect(req.from(['somethingelse', 'popstate'])).toBe(true);
+    expect(req.from(['somethingelse'])).toBe(false);
+  });
+
 });

lib/attach.js

@@ -22,30 +22,30 @@ function attach(Router, element, opts) {
     // Now that the view has been bootstrapped (i.e. is in its inital state), it
     // can be updated.
     update();
-    history.on('update', function() {
-      update();
+    history.on('update', function(meta) {
+      update(meta);
     });
   };
 
   var previousURL;
-  var update = function(isInitial) {
+  var update = function(meta) {
     var url = history.currentURL();
     if (url === previousURL) return;
     previousURL = url;
 
-    var res = router.dispatch(url, function(err) {
+    var res = router.dispatch(url, meta, function(err) {
       if (err && (err.name !== 'Unhandled') && (err.name !== 'Cancel')) {
         throw err;
       }
     });
 
-    if (isInitial) {
+    if (meta && meta.cause === 'startup') {
       res.once('initialReady', onInitialReady);
     }
   };
 
   // Start the process.
-  update(true);
+  update({cause: 'startup'});
 
   return router;
 }

lib/history/BaseHistory.js

@@ -11,11 +11,11 @@ inherits(BaseHistory, EventEmitter);
  * Navigate to the provided URL without creating a duplicate history entry if
  * you're already there.
  */
-BaseHistory.prototype.navigate = function(url) {
+BaseHistory.prototype.navigate = function(url, meta) {
     if (url !== this.currentURL()) {
-        this.push(url);
+        this.push(url, meta);
     } else {
-        this.replace(url);
+        this.replace(url, meta);
     }
 };
 

lib/history/DummyHistory.js

@@ -12,15 +12,15 @@ DummyHistory.prototype.currentURL = function() {
   return this.history[this.history.length - 1];
 };
 
-DummyHistory.prototype.push = function(path) {
+DummyHistory.prototype.push = function(path, meta) {
   this.history.push(path);
-  this.emit('update');
+  this.emit('update', meta);
 };
 
-DummyHistory.prototype.replace = function(path) {
+DummyHistory.prototype.replace = function(path, meta) {
   this.history.pop();
   this.history.push(path);
-  this.emit('update');
+  this.emit('update', meta);
 };
 
 DummyHistory.prototype.pop = function() {

lib/history/FallbackHistory.js

@@ -24,13 +24,13 @@ FallbackHistory.prototype.push = function(path) {
   window.location = path;
 };
 
-FallbackHistory.prototype.replace = function(path) {
+FallbackHistory.prototype.replace = function(path, meta) {
   // For the fallback history, `replace` won't actually change the browser
   // address, but will update its own URL. This is because `replace` usually
   // corresponds to "lesser" state changes: having a stale browser URL is
   // considered more acceptable than refreshing the entire page.
   this._url = path;
-  this.emit('update');
+  this.emit('update', meta);
 };
 
 module.exports = FallbackHistory;

lib/history/PushStateHistory.js

@@ -8,7 +8,7 @@ var urllite = require ('urllite');
  */
 function PushStateHistory() {
   window.addEventListener('popstate', function(event) {
-    this.emit('update');
+    this.emit('update', {cause: 'popstate'});
   }.bind(this));
 }
 
@@ -20,14 +20,14 @@ PushStateHistory.prototype.currentURL = function() {
   return parsed.pathname + parsed.search + parsed.hash;
 };
 
-PushStateHistory.prototype.push = function(path) {
+PushStateHistory.prototype.push = function(path, meta) {
   window.history.pushState({}, '', path);
-  this.emit('update');
+  this.emit('update', meta);
 };
 
-PushStateHistory.prototype.replace = function(path) {
+PushStateHistory.prototype.replace = function(path, meta) {
   window.history.replaceState({}, '', path);
-  this.emit('update');
+  this.emit('update', meta);
 };
 
 module.exports = PushStateHistory;