navigation-stack 0.1.2 → 0.2.0

package/lib/esm/middleware/createNavigationBlockerMiddleware.js

@@ -1,25 +1,22 @@
 import ActionTypes from '../ActionTypes';
 import isPromise from '../isPromise';
 import { getNavigationBlockers, removeAllNavigationBlockers, runNavigationBlockers } from '../navigationBlockers';
-import onlyAllowedOnClientSide from '../onlyAllowedOnClientSide';
 
 // Creates a "middleware" that applies navigation blockers.
-export default function createNavigationBlockerMiddleware(environment, {
-  ignoreEnvironmentLocationUpdates
+export default function createNavigationBlockerMiddleware(session, {
+  ignoreLocationSubscriptionEvents
 }) {
-  // A "dummy" initial value that will be ignored.
-  let navigationBlockersEvaluationStatus = {
-    cancelled: false
-  };
   function createNavigationBlockersEvaluationStatus() {
-    onlyAllowedOnClientSide();
-    navigationBlockersEvaluationStatus.cancelled = true;
-    navigationBlockersEvaluationStatus = {
+    /* eslint-disable no-underscore-dangle */
+    if (session._navigationBlockersEvaluationStatus) {
+      session._navigationBlockersEvaluationStatus.cancelled = true;
+    }
+    session._navigationBlockersEvaluationStatus = {
       cancelled: false
     };
-    return navigationBlockersEvaluationStatus;
+    return session._navigationBlockersEvaluationStatus;
   }
-  return function navigationListenerMiddleware() {
+  return function navigationBlockerMiddleware() {
     return next => action => {
       const {
         type,
@@ -30,11 +27,25 @@ export default function createNavigationBlockerMiddleware(environment, {
       // "Unexpected lexical declaration in case block".
       let result;
       switch (type) {
-        // Prevent or allow navigation that was initiated by the application.
+        // Prevent or allow navigation that was initiated by the application
+        // by dispatching a `.push()` or `.replace()` action.
+        //
+        // It doesn't handle `.shift()` navigation actions because it doesn't yet know
+        // the `location` that it's gonna `shift` to. Instead, it waits for the web browser
+        // to "shift" to that `location` and then reads it and rewinds the "shift"
+        // if it should've been blocked. That is handled in the `case ActionTypes.UPDATE` block.
+        //
+        // This type of "shifting" and then rewinding the "shift" doesn't really matter to the application at all.
+        // 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.NAVIGATE:
           // `resultValue` variable name works around a stupid javascript error:
           // "Cannot redeclare block-scoped variable 'result'".
-          result = runNavigationBlockers(getNavigationBlockers(), payload);
+          result = runNavigationBlockers(getNavigationBlockers(session), payload);
           if (isPromise(result)) {
             const status = createNavigationBlockersEvaluationStatus();
             // eslint-disable-next-line consistent-return
@@ -51,15 +62,37 @@ export default function createNavigationBlockerMiddleware(environment, {
           // eslint-disable-next-line consistent-return
           return;
 
-        // Prevent or allow navigation that was initiated by the environment itself.
-        // For example, in a web browser, it could happen when the user clicks the "Back"/"Forward" buttons.
+        // One can notice that this "middleware" handles both `NAVIGATE` and `UPDATE` Redux actions,
+        // even though a `NAVIGATE` action normally always causes a follow-up `UPDATE` Redux action.
+        // There's no contradiction here: if a navigation blocker should block a certain navigation,
+        // it will do that at the `NAVIGATION` stage and it won't get to the `UPDATE` stage, so it
+        // won't be called "second time" or something like that.
+        //
+        // One could ask then: Why handle `UPDATE` Redux action at all?
+        // The reason why it handles `UPDATE` Redux actions here is because
+        // `NAVIGATE` Redux actions are only emitted for programmatic "push" or "replace" navigation
+        // initiated by the application code, and there're other cases of navigation such as
+        // programmatic "shift" navigation or when the user manually clicks "Back" or "Forward" button
+        // in a web browser. Such "other" cases could only be handled by reacting to an `UPDATE` Redux action
+        // which is only emitted after the URL in the browser's address bar has changed.
+        //
+        // But there's no real drawback in reacting to an `UPDATE` Redux action "post factum" because
+        // from the application's point of view the address bar 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.
         //
-        // In this scenario, the web browser is already at the new location, i.e. the navigation has already happened.
-        // It could be "prevented" by rewinding back to the previous location.
+        // So here, the "middleware" attempts to prevent or allow navigation that has already happened
+        // in the web browser's address bar but hasn't yet happened in Redux state.
+        // For example, it could be a user clicking a "Back"/"Forward" button in their web browser.
+        // If such navigation should've been blocked, it will simply not update the `locaiton` object in Redux state,
+        // and it will also "rewind" the change of the URL in the web browser's address bar so that it's consistent
+        // with the `location` in Redux state.
         //
         case ActionTypes.UPDATE:
           // If no navigation blockers to run, don't do anything.
-          if (getNavigationBlockers().length === 0) {
+          if (getNavigationBlockers(session).length === 0) {
             return next(action);
           }
 
@@ -69,21 +102,21 @@ export default function createNavigationBlockerMiddleware(environment, {
             return next(action);
           }
 
-          // It's not really possible for a location to not have a `delta` property in a web browser environment.
+          // It's not really possible for a location to not have a `delta` property in a web browser session.
           // So this case is not something that's supposed to happen in real life.
-          // Rather, it's a guard against an unsupported or incorrectly-implemented environment or something like that.
+          // Rather, it's a guard against an unsupported or incorrect session implementation or something like that.
           // If there's no `delta` property on the location, it means that the previous location can't be rewound to,
           // so it can't really "prevent" the navigation that has just happened.
           if (payload.delta === null) {
             return next(action);
           }
-          result = runNavigationBlockers(getNavigationBlockers(), payload);
+          result = runNavigationBlockers(getNavigationBlockers(session), payload);
           if (isPromise(result)) {
             const status = createNavigationBlockersEvaluationStatus();
 
             // While location blockers are running, rewind to the previous location.
-            ignoreEnvironmentLocationUpdates(() => {
-              environment.shift(-payload.delta);
+            ignoreLocationSubscriptionEvents(() => {
+              session.navigation.shift(-payload.delta);
             });
             result.then(promiseResult => {
               if (promiseResult) {
@@ -92,8 +125,8 @@ export default function createNavigationBlockerMiddleware(environment, {
               } else if (!status.cancelled) {
                 // Navigation not blocked.
                 // Rewind back to the new location.
-                ignoreEnvironmentLocationUpdates(() => {
-                  environment.shift(payload.delta);
+                ignoreLocationSubscriptionEvents(() => {
+                  session.navigation.shift(payload.delta);
                 });
                 // Update the location.
                 next(action);
@@ -101,8 +134,8 @@ export default function createNavigationBlockerMiddleware(environment, {
             });
           } else if (result) {
             // Prevent the navigation: rewind to the previous location.
-            ignoreEnvironmentLocationUpdates(() => {
-              environment.shift(-payload.delta);
+            ignoreLocationSubscriptionEvents(() => {
+              session.navigation.shift(-payload.delta);
             });
           } else {
             // Update the location.
@@ -113,7 +146,7 @@ export default function createNavigationBlockerMiddleware(environment, {
 
         // Remove any navigation blockers on `DISPOSE` event.
         case ActionTypes.DISPOSE:
-          removeAllNavigationBlockers();
+          removeAllNavigationBlockers(session);
           return next(action);
         default:
           return next(action);

package/lib/esm/middleware/createTransformLocationMiddleware.js

@@ -3,7 +3,7 @@ import ActionTypes from '../ActionTypes';
 // Creates a "middleware" that transforms action payload (location).
 export default function createTransformLocationMiddleware({
   transformInputLocation,
-  transformEnvironmentLocation
+  transformSubscriptionLocation
 }) {
   return function transformLocationMiddleware() {
     return next => action => {
@@ -23,7 +23,7 @@ export default function createTransformLocationMiddleware({
         case ActionTypes.UPDATE:
           return next({
             type,
-            payload: transformEnvironmentLocation(payload)
+            payload: transformSubscriptionLocation(payload)
           });
         default:
           return next(action);

package/lib/esm/navigationBlockers.js

@@ -1,59 +1,63 @@
+/* eslint-disable no-underscore-dangle */
+
 import isPromise from './isPromise';
-import onlyAllowedOnClientSide from './onlyAllowedOnClientSide';
-let navigationBlockersList = [];
-let removeBeforeDestroyListener;
-export function getNavigationBlockers() {
-  return navigationBlockersList;
+export function getNavigationBlockers(session) {
+  return session._navigationBlockersList || [];
 }
-function addNavigationBlockerToTheList(blocker) {
-  onlyAllowedOnClientSide();
-  navigationBlockersList.push(blocker);
+function addNavigationBlockerToTheList(blocker, session) {
+  if (!session._navigationBlockersList) {
+    session._navigationBlockersList = [];
+  }
+  session._navigationBlockersList.push(blocker);
 }
-function removeNavigationBlockerFromTheList(blocker) {
-  onlyAllowedOnClientSide();
-  navigationBlockersList = navigationBlockersList.filter(_ => _ !== blocker);
+function removeNavigationBlockerFromTheList(blocker, session) {
+  if (session._navigationBlockersList) {
+    session._navigationBlockersList = session._navigationBlockersList.filter(_ => _ !== blocker);
+  }
 }
-export function removeAllNavigationBlockers() {
-  onlyAllowedOnClientSide();
-  if (getNavigationBlockers().some(blocker => blocker.beforeDestroy)) {
-    removeBeforeDestroyListener();
-    removeBeforeDestroyListener = undefined;
+export function removeAllNavigationBlockers(session) {
+  if (getNavigationBlockers(session).some(blocker => blocker.beforeDestroy)) {
+    if (!session._removeBeforeDestroyListener) {
+      throw new Error('`_removeBeforeDestroyListener` property not found in the `session`');
+    }
+    session._removeBeforeDestroyListener();
+    session._removeBeforeDestroyListener = undefined;
   }
-  navigationBlockersList = [];
+  session._navigationBlockersList = [];
 }
 
-// Runs the `listener` while ignoring any errors that might be thrown by it.
+// Runs the `blocker` while ignoring any errors that might be thrown by it.
 function runNavigationBlocker({
-  listener
+  blocker
 }, location) {
   let result;
   try {
-    result = listener(location);
+    result = blocker(location);
   } catch (error) {
     // eslint-disable-next-line no-console
-    console.warn(`Ignoring navigation blocker \`${listener.name}\` that failed with \`${error}\`.`);
+    console.warn(`Ignoring navigation blocker \`${blocker.name}\` that failed with \`${error}\`.`);
     // eslint-disable-next-line no-console
     console.error(error);
   }
 
-  // If the listener returned a `Promise`, await for that `Promise`
+  // If the blocker returned a `Promise`, await for that `Promise`
   // and then return the result.
   if (isPromise(result)) {
     return result.catch(error => {
       // eslint-disable-next-line no-console
-      console.warn(`Ignoring navigation blocker \`${listener.name}\` that failed with \`${error}\`.`);
+      console.warn(`Ignoring navigation blocker \`${blocker.name}\` that failed with \`${error}\`.`);
       // eslint-disable-next-line no-console
       console.error(error);
     });
   }
-  // The listener didn't return a `Promise`.
+  // The blocker didn't return a `Promise`.
   // Return the "synchronous" result.
   return result;
 }
 
-// Runs all listeners in order.
-// If any listener returns a non-`null` result, it stops and returns the result.
-// If there's no such listener, returns `true`.
+// Runs all blockers in order.
+// If any blocker returns `true`, it stops and returns the result.
+// If there's no such blocker, returns `undefined`.
 export function runNavigationBlockers(navigationBlockers, toLocation) {
   if (navigationBlockers.length === 0) {
     return undefined;
@@ -80,17 +84,17 @@ export function runNavigationBlockers(navigationBlockers, toLocation) {
 }
 
 /* istanbul ignore next: not testable with Karma */
-function onBeforeDestroy() {
-  const result = runNavigationBlockers(getNavigationBlockers(), null);
+function onBeforeDestroy(session) {
+  const result = runNavigationBlockers(getNavigationBlockers(session), null);
 
-  // If no listener returned anything, don't prevent the "unload" event.
+  // If no blocker returned anything, don't prevent the "unload" event.
   if (!result) {
     return undefined;
   }
 
   // Web browsers don't allow displaying a custom modal in "beforeunload" phase.
   // They only allow displaying a standard one, with the default text.
-  // Hence, "asynchronous" listeners should be ignored.
+  // Hence, "asynchronous" blockers should be ignored.
   // https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event
   if (isPromise(result)) {
     return undefined;
@@ -99,40 +103,44 @@ function onBeforeDestroy() {
   // Prevent the "unload" event.
   return true;
 }
-export function addNavigationBlocker(environment, listener) {
-  onlyAllowedOnClientSide();
-
+export function addNavigationBlocker(session, blocker) {
   // All navigation blockers also run on `beforeDestroy` event.
   // If required, this could be a parameter of this function.
-  // The rationale could be that adding `beforeunload` a listener
+  // The rationale could be that adding a `beforeunload` listener
   // disables web page caching in some browsers like Firefox.
   const beforeDestroy = true;
 
-  // If it's the first "beforeDestroy" listener, add the global `onBeforeDestroy` listener.
+  // If it's the first "beforeDestroy" blocker, add the global `onBeforeDestroy` listener.
   //
   // Sidenote: Add the "beforeunload" event listener only as needed, as its presence
   // prevents the page from being added to the page navigation cache:
   //
   // "In Firefox, beforeunload is not compatible with the back/forward cache (bfcache):
-  //  that is, Firefox will not place pages in the bfcache if they have beforeunload listeners,
+  //  that is, Firefox will not place pages in the bfcache if they have "beforeunload" listeners,
   //  and this is bad for performance."
   //
   // https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event
-  if (beforeDestroy && !getNavigationBlockers().some(blocker => blocker.beforeDestroy)) {
-    removeBeforeDestroyListener = environment.addBeforeDestroyListener(onBeforeDestroy);
+  if (beforeDestroy && !getNavigationBlockers(session).some(navigationBlocker => navigationBlocker.beforeDestroy)) {
+    if (session._removeBeforeDestroyListener) {
+      throw new Error('Unexpected `_removeBeforeDestroyListener` property found in the `session`');
+    }
+    session._removeBeforeDestroyListener = session.addBeforeDestroyListener(() => onBeforeDestroy(session));
   }
-  const blocker = {
-    listener,
+  const newNavigationBlocker = {
+    blocker,
     beforeDestroy
   };
-  addNavigationBlockerToTheList(blocker);
+  addNavigationBlockerToTheList(newNavigationBlocker, session);
   return () => {
-    removeNavigationBlockerFromTheList(blocker);
+    removeNavigationBlockerFromTheList(newNavigationBlocker, session);
 
-    // If it was the last "beforeDestroy" listener, remove the global `onBeforeDestroy` listener.
-    if (beforeDestroy && !getNavigationBlockers().some(navigationBlocker => navigationBlocker.beforeDestroy)) {
-      removeBeforeDestroyListener();
-      removeBeforeDestroyListener = undefined;
+    // If it was the last "beforeDestroy" blocker, remove the global `onBeforeDestroy` listener.
+    if (beforeDestroy && !getNavigationBlockers(session).some(navigationBlocker => navigationBlocker.beforeDestroy)) {
+      if (!session._removeBeforeDestroyListener) {
+        throw new Error('`_removeBeforeDestroyListener` property not found in the `session`');
+      }
+      session._removeBeforeDestroyListener();
+      session._removeBeforeDestroyListener = undefined;
     }
   };
 }

package/lib/esm/normalizeInputLocation.js

@@ -35,6 +35,7 @@ export default function normalizeInputLocation(location) {
   // Set default values on `search` and `hash`
   // if those properties are not present.
   return Object.assign({}, location, {
+    query: location.query || {},
     search: location.search || '',
     hash: location.hash || ''
   });

package/lib/esm/parseLocationUrl.js

@@ -28,6 +28,8 @@ export default function parseLocationUrl(url) {
   const query = parseQueryFromSearch(search);
   if (query) {
     location.query = query;
+  } else {
+    location.query = {};
   }
   return location;
 }

package/lib/esm/parseQueryFromSearch.js

@@ -7,5 +7,5 @@ export default function parseQueryFromSearch(search) {
       // Ignore any query parsing errors.
     }
   }
-  return undefined;
+  return {};
 }

package/lib/esm/session/BrowserSession.js

@@ -0,0 +1,223 @@
+const _excluded = ["delta"];
+function _objectWithoutPropertiesLoose(r, e) { if (null == r) return {}; var t = {}; for (var n in r) if ({}.hasOwnProperty.call(r, n)) { if (-1 !== e.indexOf(n)) continue; t[n] = r[n]; } return t; }
+/* eslint-disable max-classes-per-file */
+
+import getLocationUrl from '../getLocationUrl';
+import parseQueryFromSearch from '../parseQueryFromSearch';
+const INITIAL_KEY_INDEX = -1;
+const INITIAL_INDEX = -1;
+const INIT_LOCATION_DELTA = 0;
+
+// A web browser has a notion of a "navigation history".
+// A "navigation history" exists within a given web browser's tab.
+// The user can click "Back" or "Forward" buttons in the web browser and it will automatically load
+// "previous" or "next" page from scratch.
+//
+// Later, web browsers added a `window.history` object that the application can,
+// but isn't required to, interact with. That `window.history` object allows the application
+// to programmatically control the URL in the address bar of the web browser, as well as
+// the "navigation history" by programmatically adding new entries to it or reading the current entry,
+// and it also allows the application to override the default web browser's behavior
+// when the user clicks "Back" or "Forward" buttons in the web browser.
+//
+// Specifically, the `window.history` object has a method called `.pushState()` which programmatically adds
+// a new entry in the "navigation history" and updates the URL in the address bar and also
+// tells the web browser that starting from the entry before this new entry in the "navigation history",
+// the application would prefer to manually handle any "Back"/"Forward" transition when the user clicks
+// those "Back" or "Forward" buttons in the web browser, and this behavior should persist for any future
+// "navigation history" entries programmatically added by the application via `window.history.pushState()`,
+// and will only stop if the user navigates from the page by the means of conventional navigation,
+// that is by clicking a standard hyperlink, at which point the current page gets "destroyed".
+//
+// So for manually "pushed" entries of the "navigation history", the web browser won't load those pages
+// from scratch after a user-initiated "Back" or "Forward" transition. In fact, it won't do anything and
+// it will just step aside and let the application itself do those transitions. The web browser will only
+// update the URL in the address bar and that's it.
+//
+// This whole thing allows the application to:
+//
+// * Load the "previous" or "next" page much faster than when using the default "from scratch" approach
+//   because it doesn't have to destroy the current page, then send a new HTTP request to the server,
+//   then parse the HTML response and initialize a new page, re-download all those images, etc.
+//
+// * Optionally render a snapshotted verison of the "previous" page thereby "restoring" the "previous" page
+//   rather than reloading it from scratch, i.e. the state of the "previous" page could be fully restored.
+//
+class BrowserNavigation {
+  constructor() {
+    // `this._keyPrefix` exists to avoid `this._keyIndex` collision after a page refresh.
+    // After a page refresh, `this._keyIndex` is reset to `0` while the previous navigation history
+    // still exists because web browser navigation history survives a page reload.
+    this._keyPrefix = Date.now().toString(36);
+    // `this._keyIndex` is incremented every time the current location changes.
+    this._keyIndex = INITIAL_KEY_INDEX;
+
+    // `this._index` is the index of the top element in the navigation stack.
+    // I.e. it's the index of the "current" location in the navigation stack.
+    this._index = INITIAL_INDEX;
+  }
+  init() {
+    return this._createEntryFromCurrentLocation();
+  }
+  _createEntryFromCurrentLocation() {
+    const {
+      pathname,
+      search,
+      hash
+    } = window.location;
+    const isSettingInitialLocation = this._index === INITIAL_INDEX;
+    const {
+      key,
+      index,
+      delta,
+      state
+    } = isSettingInitialLocation ? this._createAdditionalPropertiesForNewLocation({
+      delta: 1,
+      state: undefined
+    }) : this._restoreAdditionalPropertiesForCurrentLocation();
+    return {
+      action: isSettingInitialLocation ? 'INIT' : 'POP',
+      pathname,
+      search,
+      query: parseQueryFromSearch(search),
+      hash,
+      key,
+      index,
+      delta: isSettingInitialLocation ? INIT_LOCATION_DELTA : delta,
+      state
+    };
+  }
+
+  // Subscribes to changes in location,
+  // excluding ones that happened as a result of calling `.navigate()`.
+  subscribe(listener) {
+    const onPopState = () => {
+      listener(this._createEntryFromCurrentLocation());
+    };
+    window.addEventListener('popstate', onPopState);
+    return () => {
+      window.removeEventListener('popstate', onPopState);
+    };
+  }
+  navigate(location) {
+    const {
+      action,
+      state
+    } = location;
+    if (action !== 'PUSH' && action !== 'REPLACE') {
+      throw Error(`Unrecognized browser session action: ${action}`);
+    }
+    if (this._index === INITIAL_INDEX) {
+      throw Error('Browser session must be initialized before navigation');
+    }
+    const delta = action === 'PUSH' ? 1 : 0;
+    const additionalProperties = this._createAdditionalPropertiesForNewLocation({
+      delta,
+      state
+    });
+    this._storeAdditionalPropertiesForLocation(location, additionalProperties);
+    return Object.assign({}, location, additionalProperties);
+  }
+  shift(delta) {
+    window.history.go(delta);
+  }
+  _createKeyForKeyIndex(keyIndex) {
+    return `${this._keyPrefix}.${keyIndex.toString(36)}`;
+  }
+  _createAdditionalPropertiesForNewLocation({
+    delta,
+    state
+  }) {
+    this._keyIndex++;
+    this._index += delta;
+    return {
+      key: this._createKeyForKeyIndex(this._keyIndex),
+      index: this._index,
+      delta,
+      state
+    };
+  }
+  _restoreAdditionalPropertiesForCurrentLocation() {
+    // Initial location doesn't have any `window.history.state` assigned to it
+    // because it wasn't navigated to via a `window.history.pushState()` method.
+    // Because of that, the additional properties for the initial location can't be read
+    // from `window.history.state` and have to be reconstructed manually.
+    const {
+      key,
+      index,
+      state
+    } = window.history.state || this._getAdditionalPropertiesForInitialLocation();
+    const delta = index - this._index;
+    this._index = index;
+    return {
+      key,
+      index,
+      delta,
+      state
+    };
+  }
+  _storeAdditionalPropertiesForLocation(location, additionalProperties) {
+    const url = getLocationUrl(location);
+    // `delta` property is not stored in `window.history.state`
+    // because it is supposed to be recalculated every time when reading from `window.history.state`.
+    const {
+        delta
+      } = additionalProperties,
+      restProperties = _objectWithoutPropertiesLoose(additionalProperties, _excluded);
+    if (delta === 1) {
+      window.history.pushState(restProperties, null, url);
+    } else if (delta === 0) {
+      window.history.replaceState(restProperties, null, url);
+    } else {
+      throw new Error(`Unexpected \`delta\` when storing additional properties for location: ${delta}`);
+    }
+  }
+
+  // Initial location doesn't have any `window.history.state` assigned to it
+  // because it wasn't navigated to via a `window.history.pushState()` method.
+  // Because of that, the additional properties for the initial location can't be read
+  // from `window.history.state` and have to be reconstructed manually.
+  _getAdditionalPropertiesForInitialLocation() {
+    return {
+      key: this._createKeyForKeyIndex(INITIAL_KEY_INDEX + 1),
+      index: INITIAL_INDEX + 1,
+      delta: INIT_LOCATION_DELTA,
+      state: undefined
+    };
+  }
+}
+class BrowserDataStorage {
+  // Returns either a `string` value or `null` if the key doesn't exist.
+  get(key) {
+    // `sessionStorage` persists across page reloads, and so does web browser navigation history.
+    return window.sessionStorage.getItem(key);
+  }
+  remove(key) {
+    // `sessionStorage` persists across page reloads, and so does web browser navigation history.
+    window.sessionStorage.removeItem(key);
+  }
+  set(key, value) {
+    // `sessionStorage` persists across page reloads, and so does web browser navigation history.
+    window.sessionStorage.setItem(key, value);
+  }
+}
+export default class BrowserSession {
+  constructor() {
+    this.navigation = new BrowserNavigation();
+    this.dataStorage = new BrowserDataStorage();
+  }
+  addBeforeDestroyListener(onBeforeDestroy) {
+    const onBeforeUnload = event => {
+      if (onBeforeDestroy()) {
+        // Calling `event.preventDefault()` will cause a web browser
+        // to show a generic "Ok"/"Cancel" modal with some generic text:
+        // "Are you sure to leave the current page?".
+        event.preventDefault();
+      }
+    };
+    window.addEventListener('beforeunload', onBeforeUnload);
+    return () => {
+      window.removeEventListener('beforeunload', onBeforeUnload);
+    };
+  }
+}