navigation-stack 0.1.2 → 0.2.0

package/.github/workflows/main.yml

@@ -1,39 +1,39 @@
-name: Build and test
-on:
-  push:
-    branches: [master]
-  pull_request:
-    branches: [master]
-
-env:
-  DISPLAY: :99.0
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        browser: ['ChromeCi', 'Firefox']
-        node-version: [16.x]
-
-    steps:
-      - uses: actions/checkout@v2
-      - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v1
-        with:
-          node-version: ${{ matrix.node-version }}
-
-      - name: Setup firefox
-        if: ${{ matrix.browser == 'Firefox' }}
-        uses: browser-actions/setup-firefox@latest
-        with:
-          firefox-version: 'latest'
-      - name: Setup xvfb
-        run: |
-          sudo apt-get install xvfb
-          Xvfb $DISPLAY -screen 0 1024x768x24 > /dev/null 2>&1 &
-      - run: yarn install --frozen-lockfile
-      - env:
-          BROWSER: ${{ matrix.browser }}
-        run: yarn test --coverage
-      - run: node_modules/.bin/codecov
+name: Build and test
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+env:
+  DISPLAY: :99.0
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        browser: ['ChromeCi', 'Firefox']
+        node-version: [16.x]
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v1
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Setup firefox
+        if: ${{ matrix.browser == 'Firefox' }}
+        uses: browser-actions/setup-firefox@latest
+        with:
+          firefox-version: 'latest'
+      - name: Setup xvfb
+        run: |
+          sudo apt-get install xvfb
+          Xvfb $DISPLAY -screen 0 1024x768x24 > /dev/null 2>&1 &
+      - run: yarn install --frozen-lockfile
+      - env:
+          BROWSER: ${{ matrix.browser }}
+        run: yarn test --coverage
+      - run: node_modules/.bin/codecov

package/README.md

@@ -24,14 +24,16 @@ import {
   createMiddlewares,
   locationReducer,
   Actions,
-  BrowserEnvironment
+  BrowserSession
 } from 'navigation-stack'
 
+// Create a Redux store.
 const store = createStore(
   locationReducer, // Reducer function. For example, `locationReducer()`.
-  applyMiddleware(...createMiddlewares(new BrowserEnvironment()))
+  applyMiddleware(...createMiddlewares(new BrowserSession()))
 )
 
+// Initialize navigation.
 store.dispatch(Actions.init())
 ```
 
@@ -88,53 +90,100 @@ With this reducer, `store.getState()` will return the current location.
 
 Calling `store.dispatch(Actions.init())` will trigger the initial `ActionTypes.UPDATE` action which will set the initial current location. From then on, the current location will always stay in sync with the web browser's URL bar, including "Back"/"Forward" navigation.
 
+A `location` object has all the properties of a [standard web browser location](https://developer.mozilla.org/en-US/docs/Web/API/Window/location) with the addition of:
+* `query: object` — URL query parameters.
+* `index: number` — The index of the location in the navigation history, starting with `0` for the initial location.
+* `action: string` — The type of navigation that led to the location.
+  * `INIT` in case of the initial location before any navigation has taken place.
+  * `POP` when the user performs a "Back" or "Forward" navigation, or after a `.shift()` navigation which is essentially a "back or forward navigation".
+  * `PUSH` in case of a `.push()` navigation, i.e. "normal navigation via a hyperlink".
+  * `REPLACE` in case of a `.replace()` navigation, i.e. "redirect".
+* `delta: number` — the difference between the `index` of the current location and the `index` of the previous location.
+  * `0` for the initial location before any navigation has taken place.
+  * `1` after a `.push()` navigation, i.e. "normal navigation via a hyperlink".
+  * `0` after a `.replace()` navigation, i.e. "redirect".
+  * `delta: number` after a `.shift(delta)` navigation, i.e. "back or forward navigation".
+  * `-1` after the user clicks a "Back" button in their web browser.
+  * `1` after the user clicks a "Forward" button in their web browser.
+* `key: string` — a unique ID of the `location` object within the navigation history.
+
+## Subscribe to Location Changes
+
 One could use Redux'es standard [subscription mechanisms](https://redux.js.org/api/store#subscribelistener) to immediately get notified of current location changes.
 
+```js
+let currentLocation
+
+// Create a Redux store.
+const store = createStore(
+  locationReducer, // Reducer function. For example, `locationReducer()`.
+  applyMiddleware(...createMiddlewares(new BrowserSession()))
+)
+
+// Subscribe to any potential Redux state changes.
+const unsubscribe = store.subscribe(() => {
+  const previousLocation = currentLocation
+  currentLocation = store.getState() // In case of using `locationReducer()`.
+  if (currentLocation !== previousLocation) {
+    console.log('Location has changed')
+  }
+})
+
+// Initialize navigation.
+// Emitting a Redux action will trigger the listener.
+store.dispatch(Actions.init())
+
+// Stop listening to current location changes.
+unsubscribe()
+```
+
 ## Why Redux?
 
 Why complicate things by providing "middlewares", "actions" and a "reducer" when it could be just a conventional API? That's because always knowing the "current location" means having to deal with "state management" in one way or another, and the simplest and most popular "state management" toolkit to date seems to be Redux.
 
 If it was just about dispatching the `Actions` then of course it wouldn't require any "state management". But it's the "get current location" piece that changes the whole picture. One could say that using Redux for such a simple task is an overkill but actually reinventing a wheel is what I would consider "overkill". It's like crafting your own screwdriver just because the one from Walmart feels too bulky.
 
-## Environment
+## Session
+
+Navigation is performed within a given "session". A "session" sets the boundaries within a given navigation session exists, so that each user (and then each their browser tab) would have a separate navigation session. A specific "session" implementation maps `navigation-stack` concepts to their physical execution, such as web browser API. Three different "session" implementations are shipped with this package: `BrowserSession`, `ServerSession` and `MemorySession`.
 
 ```js
 import {
-  BrowserEnvironment,
-  ServerEnvironment,
-  MemoryEnvironment
+  BrowserSession,
+  ServerSession,
+  MemorySession
 } from 'navigation-stack'
 
-new BrowserEnvironment()
-new ServerEnvironment('/location-url')
-new MemoryEnvironment('/location-url')
+new BrowserSession()
+new ServerSession('/initial-location-url')
+new MemorySession('/initial-location-url')
 ```
 
-- Use `BrowserEnvironment` in a web browser.
-- Use `ServerEnvironment` in server-side rendering.
-- Use `MemoryEnvironment` in tests.
-  - `MemoryEnvironment` supports an optional second argument — an `options` object with properties:
-    - `save(state)` — Saves the environment state.
-    - `load()` — Loads a previously-saved environment state.
+- Use `BrowserSession` in a web browser. The navigation session is automatically limited to a given web browser tab and survives a page refresh.
+- Use `ServerSession` in server-side rendering. Create a separate `ServerSession` for each incoming HTTP request.
+- Use `MemorySession` in tests to mimick a `BrowserSession`. Create a separate `MemorySession` for each separate navigation session.
+  - `MemorySession` supports saving and restoring its state, althrough there doesn't seem to be any real-world use for this feature. Yet, it exists. To enable state restoration, pass an optional second argument — an `options` object with properties:
+    - `save(key: string, data: string)` — Saves `data` under the `key`.
+    - `load(key: string)` — Loads the data stored under the `key`.
 
 ## Base Path
 
 If the web application is hosted under a certain URL prefix, it should be specified in `createMiddlewares()` call as `basePath` parameter.
 
 ```js
-createMiddlewares(environment, { basePath?: '/base/path' })
+createMiddlewares(session, { basePath?: '/base/path' })
 ```
 
 ## Location State Storage
 
-One could use an environment-specific `LocationStateStorage` in order to store location-specific state. For example, one could store scroll position of a page and then restore that scroll position when the user decides to navigate "Back" to the page.
+One could use `LocationDataStorage` in order to store location-specific data. For example, one could store scroll position of a page and then restore that scroll position when the user decides to navigate "Back" to the page.
 
 ```js
-import { BrowserEnvironment, LocationStateStorage } from 'navigation-stack'
+import { BrowserSession, LocationDataStorage } from 'navigation-stack'
 
-const environment = new BrowserEnvironment()
+const session = new BrowserSession()
 
-const storage = new LocationStateStorage(environment, { namespace?: 'optional-namespace' })
+const storage = new LocationDataStorage(session, { namespace?: 'optional-namespace' })
 
 const location = { pathname: '/abc' }
 
@@ -142,10 +191,57 @@ storage.set(location, 'key', 123)
 storage.get(location, 'key') === 123
 ```
 
-`LocationStateStorage` doesn't provide any guarantees about actually storing the data: if it encounters any errors in the process, it simply ignores them. This simplifies the API in a way that the application doesn't have to wrap `.get()`/`.set()` calls in a `try/catch` block. And judging by the nature of location-specific state, that type of data is inherently non-essential and rather "nice-to-have".
+`LocationDataStorage` doesn't provide any guarantees about actually storing the data: if it encounters any errors in the process, it simply ignores them. This simplifies the API in a way that the application doesn't have to wrap `.get()`/`.set()` calls in a `try/catch` block. And judging by the nature of location-specific data, that type of data is inherently non-essential and rather "nice-to-have".
+
+One might ask: Why use `LocationDataStorage` when one could simply store the data in a usual variable? The answer is that a usual variable doesn't survive if the user decides to refresh the page. But the entire navigation history does survive because that's how web browsers work. So if the user decides to go "Back" after refreshing the current page, the data associated to that previous location would already be lost and can't be recovered. In contrast, when using a `LocationDataStorage` with a `BrowserSession`, the stored data does survive a page refresh, which feels more consistent and coherent with the persistence behavior of the navigation history itself.
+
+## Get Notified Before Location Changes
+
+One could subscribe to "before change" events of the current location by calling `addBeforeLocationChangeListener()` exported function. The listener function will be called before the `location` object in Redux state is updated. This might be a suitable opportunity to save location-specific state such as the scroll position.
+
+```js
+import { createStore, applyMiddleware } from 'redux'
+
+import {
+  createMiddlewares,
+  locationReducer,
+  Actions,
+  BrowserSession,
+  addBeforeLocationChangeListener
+} from 'navigation-stack'
+
+const session = new BrowserSession()
+
+// Create a Redux store.
+const store = createStore(
+  locationReducer, // Reducer function. For example, `locationReducer()`.
+  applyMiddleware(...createMiddlewares(session))
+)
+
+// Subscribe to "before location change" events.
+const removeBeforeLocationChangeListener = addBeforeLocationChangeListener(
+  session,
+  (newLocation) => {
+    console.log(newLocation)
+  }
+);
+
+// Initialize navigation.
+// This will not trigger the listener because it's not a navigation.
+store.dispatch(Actions.init())
+
+// This navigation event will trigger the listener.
+// `newLocation.action` will be "PUSH".
+store.dispatch(Actions.push('/new/location'))
+
+// Unsubscribe from "before location change" events.
+removeBeforeLocationChangeListener()
+```
 
 ## Block Navigation
 
+`navigation-stack` provides the ability to block navigation. Call `addNavigationBlocker()` exported function to set up a navigation blocker.
+
 ```js
 import { createStore, applyMiddleware } from 'redux'
 
@@ -153,21 +249,24 @@ import {
   createMiddlewares,
   locationReducer,
   Actions,
-  BrowserEnvironment,
+  BrowserSession,
   addNavigationBlocker
 } from 'navigation-stack'
 
-const environment = new BrowserEnvironment()
+const session = new BrowserSession()
 
+// Create a Redux store.
 const store = createStore(
   locationReducer, // Reducer function. For example, `locationReducer()`.
-  applyMiddleware(...createMiddlewares(environment))
+  applyMiddleware(...createMiddlewares(session))
 )
 
+// Initialize navigation.
 store.dispatch(Actions.init())
 
+// Add navigation blocker.
 const removeNavigationBlocker = addNavigationBlocker(
-  environment,
+  session,
   (newLocation) => {
     // Returning `true` means "block this navigation".
     return true
@@ -177,7 +276,7 @@ const removeNavigationBlocker = addNavigationBlocker(
 // This navigation won't be performed.
 store.dispatch(Actions.push('/new/location'))
 
-// Disable the navigation blocker.
+// Remove the navigation blocker.
 removeNavigationBlocker()
 
 // This navigation now will be performed.
@@ -186,6 +285,8 @@ store.dispatch(Actions.push('/new/location'))
 
 Navigation blocker should be a function that receives a `newLocation` argument and could be "synchronous" or "asynchronous" (i.e. return a `Promise`, aka `async`/`await`).
 
+The `newLocation` argument of a blocker function won't necessarily have a `key` or `index` property but other properties are present.
+
 Navigation blockers fire both when navigating from one page to another and when closing the current browser tab. In the latter case, `newLocation` argument will be `null`, the function can't return a `Promise`, and returning `true` will cause the web browser to show a confirmation modal with a non-customizable browser-specific text.
 
 ## Utility
@@ -201,7 +302,7 @@ import {
 } from 'navigation-stack'
 
 // Parses a location URL to a location object.
-// If there're no query parameters, `query` property will not be added.
+// If there're no query parameters, `query` property will be an empty object.
 parseLocationUrl('/abc?d=e') === {
   pathname: '/abc',
   search: '?d=e',

package/lib/cjs/{LocationStateStorage.js → LocationDataStorage.js}

@@ -4,7 +4,7 @@ exports.__esModule = true;
 exports.default = void 0;
 var _getLocationUrl = _interopRequireDefault(require("./getLocationUrl"));
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-class LocationStateStorage {
+class LocationDataStorage {
   constructor(environment, {
     namespace
   } = {}) {
@@ -15,7 +15,7 @@ class LocationStateStorage {
   get(location, key) {
     const stateKey = this._getStateKey(location, key);
     try {
-      const value = this._environment.getState(stateKey);
+      const value = this._environment.dataStorage.get(stateKey);
       // === null is probably sufficient.
       if (value === null) {
         return undefined;
@@ -33,7 +33,7 @@ class LocationStateStorage {
     const stateKey = this._getStateKey(location, key);
     if (value === undefined) {
       try {
-        this._environment.removeState(stateKey);
+        this._environment.dataStorage.remove(stateKey);
       } catch (error) {
         // No need to handle errors here.
       }
@@ -44,7 +44,7 @@ class LocationStateStorage {
     // value here is provided by the caller of this method.
     const valueString = JSON.stringify(value);
     try {
-      this._environment.setState(stateKey, valueString);
+      this._environment.dataStorage.set(stateKey, valueString);
     } catch (error) {
       // No need to handle errors here either. If it didn't work, it didn't
       // work. We make no guarantees about actually saving the value.
@@ -56,5 +56,5 @@ class LocationStateStorage {
     return `${keyPrefix}|${key}`;
   }
 }
-exports.default = LocationStateStorage;
+exports.default = LocationDataStorage;
 module.exports = exports.default;

package/lib/cjs/addBeforeLocationChangeListener.js

@@ -0,0 +1,7 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _beforeLocationChangeListeners = require("./beforeLocationChangeListeners");
+exports.default = _beforeLocationChangeListeners.addBeforeLocationChangeListener;
+module.exports = exports.default;

package/lib/cjs/beforeLocationChangeListeners.js

@@ -0,0 +1,51 @@
+"use strict";
+
+exports.__esModule = true;
+exports.addBeforeLocationChangeListener = addBeforeLocationChangeListener;
+exports.getBeforeLocationChangeListeners = getBeforeLocationChangeListeners;
+exports.removeAllBeforeLocationChangeListeners = removeAllBeforeLocationChangeListeners;
+exports.runBeforeLocationChangeListeners = runBeforeLocationChangeListeners;
+/* eslint-disable no-underscore-dangle */
+
+function getBeforeLocationChangeListeners(session) {
+  return session._beforeLocationChangeListenersList || [];
+}
+function addBeforeLocationChangeListenerToTheList(listener, session) {
+  if (!session._beforeLocationChangeListenersList) {
+    session._beforeLocationChangeListenersList = [];
+  }
+  session._beforeLocationChangeListenersList.push(listener);
+}
+function removeBeforeLocationChangeListenerFromTheList(listener, session) {
+  if (session._beforeLocationChangeListenersList) {
+    session._beforeLocationChangeListenersList = session._beforeLocationChangeListenersList.filter(_ => _ !== listener);
+  }
+}
+function removeAllBeforeLocationChangeListeners(session) {
+  session._beforeLocationChangeListenersList = [];
+}
+
+// Runs the `listener` while ignoring any errors that might be thrown by it.
+function runBeforeLocationChangeListener(listener, location) {
+  try {
+    listener(location);
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.warn(`Ignoring before location change listener \`${listener.name}\` that failed with \`${error}\`.`);
+    // eslint-disable-next-line no-console
+    console.error(error);
+  }
+}
+
+// Runs all listeners in order.
+function runBeforeLocationChangeListeners(navigationListeners, toLocation) {
+  for (const listener of navigationListeners) {
+    runBeforeLocationChangeListener(listener, toLocation);
+  }
+}
+function addBeforeLocationChangeListener(session, listener) {
+  addBeforeLocationChangeListenerToTheList(listener, session);
+  return () => {
+    removeBeforeLocationChangeListenerFromTheList(listener, session);
+  };
+}

package/lib/cjs/createMiddlewares.js

@@ -3,18 +3,19 @@
 exports.__esModule = true;
 exports.default = createMiddlewares;
 var _createBasePathMiddleware = _interopRequireDefault(require("./middleware/createBasePathMiddleware"));
-var _createEnvironmentMiddleware = _interopRequireDefault(require("./middleware/createEnvironmentMiddleware"));
+var _createBeforeLocationChangeListenerMiddleware = _interopRequireDefault(require("./middleware/createBeforeLocationChangeListenerMiddleware"));
+var _createLocationMiddleware = _interopRequireDefault(require("./middleware/createLocationMiddleware"));
 var _createNavigationBlockerMiddleware = _interopRequireDefault(require("./middleware/createNavigationBlockerMiddleware"));
 var _navigationActionMiddleware = _interopRequireDefault(require("./middleware/navigationActionMiddleware"));
 var _normalizeInputLocationMiddleware = _interopRequireDefault(require("./middleware/normalizeInputLocationMiddleware"));
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-function createMiddlewares(environment, options) {
-  // Allows temporarily ignoring certain environment location updates.
-  let shouldIgnoreEnvironmentLocationUpdates = false;
-  const ignoreEnvironmentLocationUpdates = func => {
-    shouldIgnoreEnvironmentLocationUpdates = true;
+function createMiddlewares(session, options) {
+  // Allows temporarily ignoring location update events.
+  let shouldIgnoreLocationSubscriptionEvents = false;
+  const ignoreLocationSubscriptionEvents = func => {
+    shouldIgnoreLocationSubscriptionEvents = true;
     func();
-    shouldIgnoreEnvironmentLocationUpdates = false;
+    shouldIgnoreLocationSubscriptionEvents = false;
   };
   return [
   // Validates that the action "payload" (input location) is a proper `NormalizedInputLocation`.
@@ -26,18 +27,21 @@ function createMiddlewares(environment, options) {
   (0, _createBasePathMiddleware.default)(options && options.basePath),
   // Allows blocking navigation.
   // Handles `NAVIGATE` actions dispatched by the application itself.
-  (0, _createNavigationBlockerMiddleware.default)(environment, {
-    ignoreEnvironmentLocationUpdates
+  (0, _createNavigationBlockerMiddleware.default)(session, {
+    ignoreLocationSubscriptionEvents
   }),
-  // This "middleware" performs the actual navigation according to the `environment` being used.
-  // For example, when `BrowserEnvironment` is used, it calls methods of the `history` object.
-  (0, _createEnvironmentMiddleware.default)(environment, {
-    shouldIgnoreEnvironmentLocationUpdates: () => shouldIgnoreEnvironmentLocationUpdates
+  // This "middleware" performs the actual navigation according to the `session` being used.
+  // For example, when `BrowserSession` is used, it calls methods of the `history` object.
+  (0, _createLocationMiddleware.default)(session, {
+    shouldIgnoreLocationSubscriptionEvents: () => shouldIgnoreLocationSubscriptionEvents
   }),
   // Allows blocking navigation.
-  // Handles location `UPDATE` actions dispatched by the environment.
-  (0, _createNavigationBlockerMiddleware.default)(environment, {
-    ignoreEnvironmentLocationUpdates
-  })];
+  // Handles location `UPDATE` actions dispatched in response to location update events.
+  (0, _createNavigationBlockerMiddleware.default)(session, {
+    ignoreLocationSubscriptionEvents
+  }),
+  // Allows subscribing to upcoming location changes
+  // before those changes are applied in the `location` object in the state.
+  (0, _createBeforeLocationChangeListenerMiddleware.default)(session)];
 }
 module.exports = exports.default;

package/lib/cjs/index.js

@@ -1,7 +1,7 @@
 "use strict";
 
 exports.__esModule = true;
-exports.removeBasePath = exports.parseLocationUrl = exports.locationReducer = exports.getLocationUrl = exports.createMiddlewares = exports.addNavigationBlocker = exports.addBasePath = exports.ServerEnvironment = exports.MemoryEnvironment = exports.LocationStateStorage = exports.BrowserEnvironment = exports.Actions = exports.ActionTypes = void 0;
+exports.removeBasePath = exports.parseLocationUrl = exports.locationReducer = exports.getLocationUrl = exports.createMiddlewares = exports.addNavigationBlocker = exports.addBasePath = exports.ServerSession = exports.MemorySession = exports.LocationDataStorage = exports.BrowserSession = exports.Actions = exports.ActionTypes = void 0;
 var _Actions = _interopRequireDefault(require("./Actions"));
 exports.Actions = _Actions.default;
 var _ActionTypes = _interopRequireDefault(require("./ActionTypes"));
@@ -19,12 +19,12 @@ var _createMiddlewares = _interopRequireDefault(require("./createMiddlewares"));
 exports.createMiddlewares = _createMiddlewares.default;
 var _locationReducer = _interopRequireDefault(require("./locationReducer"));
 exports.locationReducer = _locationReducer.default;
-var _LocationStateStorage = _interopRequireDefault(require("./LocationStateStorage"));
-exports.LocationStateStorage = _LocationStateStorage.default;
-var _BrowserEnvironment = _interopRequireDefault(require("./environment/BrowserEnvironment"));
-exports.BrowserEnvironment = _BrowserEnvironment.default;
-var _MemoryEnvironment = _interopRequireDefault(require("./environment/MemoryEnvironment"));
-exports.MemoryEnvironment = _MemoryEnvironment.default;
-var _ServerEnvironment = _interopRequireDefault(require("./environment/ServerEnvironment"));
-exports.ServerEnvironment = _ServerEnvironment.default;
+var _LocationDataStorage = _interopRequireDefault(require("./LocationDataStorage"));
+exports.LocationDataStorage = _LocationDataStorage.default;
+var _BrowserSession = _interopRequireDefault(require("./session/BrowserSession"));
+exports.BrowserSession = _BrowserSession.default;
+var _MemorySession = _interopRequireDefault(require("./session/MemorySession"));
+exports.MemorySession = _MemorySession.default;
+var _ServerSession = _interopRequireDefault(require("./session/ServerSession"));
+exports.ServerSession = _ServerSession.default;
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }

package/lib/cjs/middleware/createBasePathMiddleware.js

@@ -14,9 +14,9 @@ function createBasePathMiddleware(basePath) {
     transformInputLocation: location => {
       return (0, _basePath.addBasePath)(location, basePath);
     },
-    // Transforms environment `Location` object:
+    // Transforms subscription `Location` object:
     // removes `basePath` from the URL.
-    transformEnvironmentLocation: location => {
+    transformSubscriptionLocation: location => {
       return (0, _basePath.removeBasePath)(location, basePath);
     }
   });

package/lib/cjs/middleware/createBeforeLocationChangeListenerMiddleware.js

@@ -0,0 +1,39 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = createBeforeLocationChangeListenerMiddleware;
+var _ActionTypes = _interopRequireDefault(require("../ActionTypes"));
+var _beforeLocationChangeListeners = require("../beforeLocationChangeListeners");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+// Creates a "middleware" that calls upcoming navigation listeners.
+function createBeforeLocationChangeListenerMiddleware(session) {
+  return function navigationListenerMiddleware() {
+    return next => action => {
+      const {
+        type,
+        payload
+      } = action;
+      switch (type) {
+        // Trigger navigation listeners before the `location` has been updated in Redux state.
+        // It doesn't matter that the new location URL has already been updated in the web browser's
+        // address bar, or that the web browser's history has already switched to the new locaiton.
+        // From the application's point of view, all of that doesn't matter and even doesn't exist.
+        // All that exists from the application's point of view is the `location` object in the Redux state.
+        // Until the `location` object in the Redux state is updated, the old page is still rendered.
+        // The appliation is only concerned with the updates of the `location` object in the Redux state
+        // and completely ignores any updates to the URL in the web browser's address bar.
+        case _ActionTypes.default.UPDATE:
+          (0, _beforeLocationChangeListeners.runBeforeLocationChangeListeners)((0, _beforeLocationChangeListeners.getBeforeLocationChangeListeners)(session), payload);
+          return next(action);
+
+        // Remove any navigation listeners on `DISPOSE` event.
+        case _ActionTypes.default.DISPOSE:
+          (0, _beforeLocationChangeListeners.removeAllBeforeLocationChangeListeners)(session);
+          return next(action);
+        default:
+          return next(action);
+      }
+    };
+  };
+}
+module.exports = exports.default;

package/lib/cjs/middleware/{createEnvironmentMiddleware.js → createLocationMiddleware.js}

@@ -1,7 +1,7 @@
 "use strict";
 
 exports.__esModule = true;
-exports.default = createEnvironmentMiddleware;
+exports.default = createLocationMiddleware;
 var _ActionTypes = _interopRequireDefault(require("../ActionTypes"));
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 function updateLocation(location) {
@@ -11,19 +11,17 @@ function updateLocation(location) {
   };
 }
 
-// Creates a "middleware" that performs the actual navigation according to the `environment` being used.
-// For example, when `BrowserProtocol` is used, it calls methods of the `history` object.
-// A better name for this function could be something like `createProtocolMiddleware(environment)`.
-// A better name for "environment" could be something like "environment".
-function createEnvironmentMiddleware(environment, {
-  shouldIgnoreEnvironmentLocationUpdates
+// Creates a "middleware" that performs the actual navigation according to the `session` being used.
+// For example, when `BrowserSession` is used, it calls methods of the `window.history` object.
+function createLocationMiddleware(session, {
+  shouldIgnoreLocationSubscriptionEvents
 }) {
-  return function environmentMiddleware() {
+  return function locationMiddleware() {
     return next => {
       // Whenever browser location changes,
       // perform the same changes with the internal `location` object.
-      const unsubscribe = environment.subscribe(location => {
-        if (!shouldIgnoreEnvironmentLocationUpdates()) {
+      const unsubscribe = session.navigation.subscribe(location => {
+        if (!shouldIgnoreLocationSubscriptionEvents()) {
           next(updateLocation(location));
         }
       });
@@ -34,14 +32,14 @@ function createEnvironmentMiddleware(environment, {
         } = action;
         switch (type) {
           case _ActionTypes.default.INIT:
-            return next(updateLocation(environment.init()));
+            return next(updateLocation(session.navigation.init()));
           case _ActionTypes.default.NAVIGATE:
-            // `environment.navigate()` doesn't trigger the `subscribe()` listener.
-            return next(updateLocation(environment.navigate(payload)));
+            // `session.navigate()` doesn't trigger the `subscribe()` listener.
+            return next(updateLocation(session.navigation.navigate(payload)));
           case _ActionTypes.default.SHIFT:
             // `shift()` will trigger the `subscribe()` listener,
             // which will call `updateLocation()`.
-            environment.shift(payload);
+            session.navigation.shift(payload);
             // eslint-disable-next-line consistent-return
             return;
           case _ActionTypes.default.DISPOSE: