navigation-stack 0.1.3 → 0.2.0

package/lib/cjs/session/MemorySession.js

@@ -0,0 +1,223 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _normalizeInputLocation = _interopRequireDefault(require("../normalizeInputLocation"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/* eslint-disable max-classes-per-file */
+
+// 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 = [Object.assign({}, (0, _normalizeInputLocation.default)(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 Object.assign({}, 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 Object.assign({}, 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
+  };
+}
+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 () => {};
+  }
+}
+exports.default = MemorySession;
+module.exports = exports.default;

package/lib/cjs/{environment/ServerEnvironment.js → session/ServerSession.js}

@@ -4,50 +4,62 @@ exports.__esModule = true;
 exports.default = void 0;
 var _normalizeInputLocation = _interopRequireDefault(require("../normalizeInputLocation"));
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/* eslint-disable max-classes-per-file */
+
 function noop() {}
 function serverSideNavigationNotPossible() {
   throw new Error('Server-side navigation is not possible');
 }
-class ServerEnvironment {
+class ServerNavigation {
   constructor(initialLocation) {
     this._location = (0, _normalizeInputLocation.default)(initialLocation);
   }
   init() {
     return Object.assign({
-      action: 'POP'
-    }, this._location);
+      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();
   }
+}
+class ServerDataStorage {
+  // It doesn't seem to make any sense to store anything on server side.
+  // Hence, state management methods are "no op" stubs.
+  get() {
+    return null;
+  }
+  remove() {}
+  set() {}
+}
+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 () => {};
-  }
-
-  // It doesn't seem to make any sense to store anything on server side.
-  // Hence, state management methods are "no op" stubs.
-  getState() {
-    return null;
+    return noop;
   }
-  removeState() {}
-  setState() {}
 }
-exports.default = ServerEnvironment;
+exports.default = ServerSession;
 module.exports = exports.default;

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

@@ -1,5 +1,5 @@
 import getLocationUrl from './getLocationUrl';
-export default class LocationStateStorage {
+export default class LocationDataStorage {
   constructor(environment, {
     namespace
   } = {}) {
@@ -10,7 +10,7 @@ export default 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;
@@ -28,7 +28,7 @@ export default 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.
       }
@@ -39,7 +39,7 @@ export default 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.

package/lib/esm/addBeforeLocationChangeListener.js

@@ -0,0 +1,2 @@
+// eslint-disable-next-line no-restricted-exports
+export { addBeforeLocationChangeListener as default } from './beforeLocationChangeListeners';

package/lib/esm/beforeLocationChangeListeners.js

@@ -0,0 +1,44 @@
+/* eslint-disable no-underscore-dangle */
+
+export 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);
+  }
+}
+export 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.
+export function runBeforeLocationChangeListeners(navigationListeners, toLocation) {
+  for (const listener of navigationListeners) {
+    runBeforeLocationChangeListener(listener, toLocation);
+  }
+}
+export function addBeforeLocationChangeListener(session, listener) {
+  addBeforeLocationChangeListenerToTheList(listener, session);
+  return () => {
+    removeBeforeLocationChangeListenerFromTheList(listener, session);
+  };
+}

package/lib/esm/createMiddlewares.js

@@ -1,15 +1,16 @@
 import createBasePathMiddleware from './middleware/createBasePathMiddleware';
-import createEnvironmentMiddleware from './middleware/createEnvironmentMiddleware';
+import createBeforeLocationChangeListenerMiddleware from './middleware/createBeforeLocationChangeListenerMiddleware';
+import createLocationMiddleware from './middleware/createLocationMiddleware';
 import createNavigationBlockerMiddleware from './middleware/createNavigationBlockerMiddleware';
 import navigationActionMiddleware from './middleware/navigationActionMiddleware';
 import normalizeInputLocationMiddleware from './middleware/normalizeInputLocationMiddleware';
-export default function createMiddlewares(environment, options) {
-  // Allows temporarily ignoring certain environment location updates.
-  let shouldIgnoreEnvironmentLocationUpdates = false;
-  const ignoreEnvironmentLocationUpdates = func => {
-    shouldIgnoreEnvironmentLocationUpdates = true;
+export default 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`.
@@ -21,17 +22,20 @@ export default function createMiddlewares(environment, options) {
   createBasePathMiddleware(options && options.basePath),
   // Allows blocking navigation.
   // Handles `NAVIGATE` actions dispatched by the application itself.
-  createNavigationBlockerMiddleware(environment, {
-    ignoreEnvironmentLocationUpdates
+  createNavigationBlockerMiddleware(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.
-  createEnvironmentMiddleware(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.
+  createLocationMiddleware(session, {
+    shouldIgnoreLocationSubscriptionEvents: () => shouldIgnoreLocationSubscriptionEvents
   }),
   // Allows blocking navigation.
-  // Handles location `UPDATE` actions dispatched by the environment.
-  createNavigationBlockerMiddleware(environment, {
-    ignoreEnvironmentLocationUpdates
-  })];
+  // Handles location `UPDATE` actions dispatched in response to location update events.
+  createNavigationBlockerMiddleware(session, {
+    ignoreLocationSubscriptionEvents
+  }),
+  // Allows subscribing to upcoming location changes
+  // before those changes are applied in the `location` object in the state.
+  createBeforeLocationChangeListenerMiddleware(session)];
 }

package/lib/esm/index.js

@@ -6,7 +6,7 @@ export { default as getLocationUrl } from './getLocationUrl';
 export { default as parseLocationUrl } from './parseLocationUrl';
 export { default as createMiddlewares } from './createMiddlewares';
 export { default as locationReducer } from './locationReducer';
-export { default as LocationStateStorage } from './LocationStateStorage';
-export { default as BrowserEnvironment } from './environment/BrowserEnvironment';
-export { default as MemoryEnvironment } from './environment/MemoryEnvironment';
-export { default as ServerEnvironment } from './environment/ServerEnvironment';
+export { default as LocationDataStorage } from './LocationDataStorage';
+export { default as BrowserSession } from './session/BrowserSession';
+export { default as MemorySession } from './session/MemorySession';
+export { default as ServerSession } from './session/ServerSession';

package/lib/esm/middleware/createBasePathMiddleware.js

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

package/lib/esm/middleware/createBeforeLocationChangeListenerMiddleware.js

@@ -0,0 +1,34 @@
+import ActionTypes from '../ActionTypes';
+import { getBeforeLocationChangeListeners, removeAllBeforeLocationChangeListeners, runBeforeLocationChangeListeners } from '../beforeLocationChangeListeners';
+
+// Creates a "middleware" that calls upcoming navigation listeners.
+export default 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.UPDATE:
+          runBeforeLocationChangeListeners(getBeforeLocationChangeListeners(session), payload);
+          return next(action);
+
+        // Remove any navigation listeners on `DISPOSE` event.
+        case ActionTypes.DISPOSE:
+          removeAllBeforeLocationChangeListeners(session);
+          return next(action);
+        default:
+          return next(action);
+      }
+    };
+  };
+}

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

@@ -6,19 +6,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".
-export default 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.
+export default 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));
         }
       });
@@ -29,14 +27,14 @@ export default function createEnvironmentMiddleware(environment, {
         } = action;
         switch (type) {
           case ActionTypes.INIT:
-            return next(updateLocation(environment.init()));
+            return next(updateLocation(session.navigation.init()));
           case ActionTypes.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.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.DISPOSE: