navigation-stack 0.1.2 → 0.2.0

package/src/session/BrowserSession.js

@@ -0,0 +1,225 @@
+/* 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 { ...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, ...restProperties } = additionalProperties;
+    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);
+    };
+  }
+}

package/src/session/MemorySession.js

@@ -0,0 +1,219 @@
+/* eslint-disable max-classes-per-file */
+
+import normalizeInputLocation from '../normalizeInputLocation';
+
+// eslint-disable-next-line no-underscore-dangle
+function _loadState(load, isValidLoadedData) {
+  try {
+    const data = JSON.parse(load());
+
+    // Check that the stack and index at least seem reasonable before using
+    // them as state. This isn't foolproof, but it might prevent mistakes.
+    // Also perform a basic validation of `state`.
+    if (isValidLoadedData(data)) {
+      return data;
+    }
+  } catch (error) {} // eslint-disable-line no-empty
+
+  return null;
+}
+
+// eslint-disable-next-line no-underscore-dangle
+function _saveState(save, data) {
+  try {
+    save(JSON.stringify(data));
+  } catch (error) {} // eslint-disable-line no-empty
+}
+
+class MemoryNavigation {
+  constructor(initialLocation, { save, load } = {}) {
+    this._save = save;
+
+    this._keyPrefix = Date.now().toString(36);
+    this._keyIndex = 0;
+
+    this._subscriptionListener = null;
+
+    const initialState = load
+      ? _loadState(load, this._isValidLoadedData)
+      : null;
+    if (initialState) {
+      this._stack = initialState.stack;
+      this._index = initialState.index;
+    } else {
+      this._stack = [
+        {
+          ...normalizeInputLocation(initialLocation),
+          key: this._getNextKey(),
+        },
+      ];
+      this._index = 0;
+    }
+  }
+
+  _isValidLoadedData({ stack, index }) {
+    // Check that the `stack` and `index` at least seem reasonable before using them.
+    // This isn't foolproof, but it might prevent mistakes.
+    return Array.isArray(stack) && typeof index === 'number' && stack[index];
+  }
+
+  init() {
+    return this._createLocationObject({ action: 'INIT', delta: 0 });
+  }
+
+  subscribe(listener) {
+    this._subscriptionListener = listener;
+
+    return () => {
+      this._subscriptionListener = null;
+    };
+  }
+
+  navigate(location) {
+    const { action, pathname, search, query, hash, state } = location;
+
+    if (action !== 'PUSH' && action !== 'REPLACE') {
+      throw Error(`Unrecognized browser session action: ${action}`);
+    }
+
+    const delta = action === 'PUSH' ? 1 : 0;
+    this._index += delta;
+
+    const key = this._getNextKey();
+
+    this._stack[this._index] = { pathname, search, query, hash, state, key };
+    if (action === 'PUSH') {
+      this._stack.length = this._index + 1;
+    }
+
+    if (this._save) {
+      _saveState(this._save, {
+        stack: this._stack,
+        index: this._index,
+      });
+    }
+
+    return { ...location, key, index: this._index, delta };
+  }
+
+  shift(delta) {
+    const prevIndex = this._index;
+
+    this._index = Math.min(
+      Math.max(this._index + delta, 0),
+      this._stack.length - 1,
+    );
+
+    if (this._index === prevIndex) {
+      return;
+    }
+
+    if (this._save) {
+      _saveState(this._save, {
+        stack: this._stack,
+        index: this._index,
+      });
+    }
+
+    if (this._subscriptionListener) {
+      this._subscriptionListener(
+        this._createLocationObject({
+          action: 'POP',
+          delta: this._index - prevIndex,
+        }),
+      );
+    }
+  }
+
+  _getNextKey() {
+    const key = `${this._keyPrefix}.${this._keyIndex.toString(36)}`;
+    this._keyIndex++;
+    return key;
+  }
+
+  _createLocationObject({ action, delta }) {
+    return {
+      ...this._stack[this._index],
+      action,
+      index: this._index,
+      delta,
+    };
+  }
+}
+
+class MemoryDataStorage {
+  constructor({ load, save } = {}) {
+    this._save = save;
+
+    const initialState = load
+      ? _loadState(load, this._isValidLoadedData)
+      : null;
+    if (initialState) {
+      this._state = initialState.state;
+    } else {
+      this._state = {};
+    }
+  }
+
+  // Returns either a `string` value or `null` if the key doesn't exist.
+  get(key) {
+    if (key in this._state) {
+      return this._state[key];
+    }
+    return null;
+  }
+
+  remove(key) {
+    if (key in this._state) {
+      delete this._state[key];
+    }
+
+    if (this._save) {
+      _saveState(this._save, {
+        state: this._state,
+      });
+    }
+  }
+
+  set(key, value) {
+    this._state[key] = value;
+
+    if (this._save) {
+      _saveState(this._save, {
+        state: this._state,
+      });
+    }
+  }
+
+  _isValidLoadedData({ state }) {
+    // Perform a basic validation of `state`.
+    return typeof state === 'object' && state !== null;
+  }
+}
+
+function createNestedStateSaveLoadFunctions({ save, load }, key) {
+  return {
+    save: save ? (data) => save(key, data) : undefined,
+    load: load ? () => load(key) : undefined,
+  };
+}
+
+export default class MemorySession {
+  constructor(initialLocation, { save, load } = {}) {
+    this.navigation = new MemoryNavigation(
+      initialLocation,
+      createNestedStateSaveLoadFunctions({ save, load }, 'navigation'),
+    );
+    this.dataStorage = new MemoryDataStorage(
+      createNestedStateSaveLoadFunctions({ save, load }, 'dataStorage'),
+    );
+  }
+
+  // "Before destroy" listeners are currently ignored.
+  // If required, one could implement a `_destroy()` method
+  // and there check that the listeners actually do get called.
+  // eslint-disable-next-line no-unused-vars
+  addBeforeDestroyListener(listener) {
+    return () => {};
+  }
+}

package/src/{environment/ServerEnvironment.js → session/ServerSession.js}

@@ -1,3 +1,5 @@
+/* eslint-disable max-classes-per-file */
+
 import normalizeInputLocation from '../normalizeInputLocation';
 
 function noop() {}
@@ -6,49 +8,60 @@ function serverSideNavigationNotPossible() {
   throw new Error('Server-side navigation is not possible');
 }
 
-export default class ServerEnvironment {
+class ServerNavigation {
   constructor(initialLocation) {
     this._location = normalizeInputLocation(initialLocation);
   }
 
   init() {
     return {
-      action: 'POP',
+      action: 'INIT',
       ...this._location,
+      index: 0,
+      key: '0',
     };
   }
 
   subscribe() {
-    // Server environment emits no location events.
+    // Server-side environment emits no location subscription events.
     return noop;
   }
 
-  // Navigation methods are not implemented, because `ServerPEnvironment` instances
+  // Navigation methods are not implemented, because `ServerSession` instances
   // cannot navigate.
   navigate() {
     serverSideNavigationNotPossible();
   }
 
-  // Navigation methods are not implemented, because `ServerEnvironment` instances
+  // Navigation methods are not implemented, because `ServerSession` instances
   // cannot navigate.
   shift() {
     serverSideNavigationNotPossible();
   }
+}
 
-  // "Before destroy" listeners are currently ignored.
-  // If required, one could implement a `_destroy()` method
-  // and there check that the listeners actually do get called.
-  addBeforeDestroyListener() {
-    return () => {};
-  }
-
+class ServerDataStorage {
   // It doesn't seem to make any sense to store anything on server side.
   // Hence, state management methods are "no op" stubs.
-  getState() {
+  get() {
     return null;
   }
 
-  removeState() {}
+  remove() {}
+
+  set() {}
+}
 
-  setState() {}
+export default class ServerSession {
+  constructor(initialLocation) {
+    this.navigation = new ServerNavigation(initialLocation);
+    this.dataStorage = new ServerDataStorage();
+  }
+
+  // "Before destroy" listeners are currently ignored.
+  // If required, one could implement a `_destroy()` method
+  // and there check that the listeners actually do get called.
+  addBeforeDestroyListener() {
+    return noop;
+  }
 }

package/test/{LocationStateStorage.test.js → LocationDataStorage.test.js}

@@ -1,8 +1,8 @@
-import LocationStateStorage from '../src/LocationStateStorage';
-import MemoryEnvironment from '../src/environment/MemoryEnvironment';
+import LocationDataStorage from '../src/LocationDataStorage';
+import MemorySession from '../src/session/MemorySession';
 
-describe('LocationStateStorage', () => {
-  let environment;
+describe('LocationDataStorage', () => {
+  let session;
   let stateStorage;
 
   const location = {
@@ -12,8 +12,8 @@ describe('LocationStateStorage', () => {
   beforeEach(() => {
     window.sessionStorage.clear();
 
-    environment = new MemoryEnvironment('/initial-location');
-    stateStorage = new LocationStateStorage(environment, {
+    session = new MemorySession('/initial-location');
+    stateStorage = new LocationDataStorage(session, {
       namespace: 'test',
     });
   });

package/test/createMiddlewares.test.js

@@ -2,8 +2,8 @@ import { applyMiddleware, createStore } from 'redux';
 
 import Actions from '../src/Actions';
 import createMiddlewares from '../src/createMiddlewares';
-import MemoryEnvironment from '../src/environment/MemoryEnvironment';
 import locationReducer from '../src/locationReducer';
+import MemorySession from '../src/session/MemorySession';
 
 describe('createMiddlewares', () => {
   let store;
@@ -11,7 +11,7 @@ describe('createMiddlewares', () => {
   beforeEach(() => {
     store = createStore(
       locationReducer,
-      applyMiddleware(...createMiddlewares(new MemoryEnvironment('/foo'))),
+      applyMiddleware(...createMiddlewares(new MemorySession('/foo'))),
     );
     store.dispatch(Actions.init());
   });

package/test/helpers.js

@@ -23,7 +23,7 @@ export function transformInputLocationUsingMiddleware(middleware, location) {
   }).payload;
 }
 
-export function transformEnvironmentLocationUsingMiddleware(
+export function transformSubscriptionLocationUsingMiddleware(
   middleware,
   location,
 ) {

package/test/index.test.js

@@ -13,8 +13,8 @@ describe('index', () => {
     expect(exports.parseLocationUrl).to.exist();
     expect(exports.createMiddlewares).to.exist();
     expect(exports.locationReducer).to.exist();
-    expect(exports.BrowserEnvironment).to.exist();
-    expect(exports.MemoryEnvironment).to.exist();
-    expect(exports.ServerEnvironment).to.exist();
+    expect(exports.BrowserSession).to.exist();
+    expect(exports.MemorySession).to.exist();
+    expect(exports.ServerSession).to.exist();
   });
 });

package/test/middleware/createBasePathMiddleware.test.js

@@ -1,7 +1,7 @@
 import createBasePathMiddleware from '../../src/middleware/createBasePathMiddleware';
 import {
-  transformEnvironmentLocationUsingMiddleware,
   transformInputLocationUsingMiddleware,
+  transformSubscriptionLocationUsingMiddleware,
 } from '../helpers';
 
 describe('createBasePathMiddleware', () => {
@@ -22,9 +22,9 @@ describe('createBasePathMiddleware', () => {
         });
       });
 
-      it('should strip `basePath` from `location.pathname` on environment locations', () => {
+      it('should strip `basePath` from `location.pathname` on subscription locations', () => {
         expect(
-          transformEnvironmentLocationUsingMiddleware(basePathMiddleware, {
+          transformSubscriptionLocationUsingMiddleware(basePathMiddleware, {
             pathname: '/foo/path',
           }),
         ).to.eql({
@@ -32,9 +32,9 @@ describe('createBasePathMiddleware', () => {
         });
       });
 
-      it('should handle unrecognized paths on environment locations', () => {
+      it('should handle unrecognized paths on subscription locations', () => {
         expect(
-          transformEnvironmentLocationUsingMiddleware(basePathMiddleware, {
+          transformSubscriptionLocationUsingMiddleware(basePathMiddleware, {
             pathname: '/bar/path',
           }),
         ).to.eql({
@@ -54,10 +54,10 @@ describe('createBasePathMiddleware', () => {
       ).to.equal(location);
     });
 
-    it('should not modify `location.pathname` of environment locations', () => {
+    it('should not modify `location.pathname` of subscription locations', () => {
       const location = { pathname: '/path' };
       expect(
-        transformEnvironmentLocationUsingMiddleware(
+        transformSubscriptionLocationUsingMiddleware(
           basePathMiddleware,
           location,
         ),