navigation-stack 0.1.3 → 0.2.0

package/src/index.js

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

package/src/middleware/createBasePathMiddleware.js

@@ -11,9 +11,9 @@ export default function createBasePathMiddleware(basePath) {
       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/src/middleware/createBeforeLocationChangeListenerMiddleware.js

@@ -0,0 +1,40 @@
+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/src/middleware/{createEnvironmentMiddleware.js → createLocationMiddleware.js}

@@ -7,20 +7,18 @@ 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));
         }
       });
@@ -30,16 +28,16 @@ export default function createEnvironmentMiddleware(
 
         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;
 

package/src/middleware/createNavigationBlockerMiddleware.js

@@ -5,24 +5,22 @@ import {
   removeAllNavigationBlockers,
   runNavigationBlockers,
 } from '../navigationBlockers';
-import onlyAllowedOnClientSide from '../onlyAllowedOnClientSide';
 
 // Creates a "middleware" that applies navigation blockers.
 export default function createNavigationBlockerMiddleware(
-  environment,
-  { ignoreEnvironmentLocationUpdates },
+  session,
+  { ignoreLocationSubscriptionEvents },
 ) {
-  // A "dummy" initial value that will be ignored.
-  let navigationBlockersEvaluationStatus = { cancelled: false };
-
   function createNavigationBlockersEvaluationStatus() {
-    onlyAllowedOnClientSide();
-    navigationBlockersEvaluationStatus.cancelled = true;
-    navigationBlockersEvaluationStatus = { cancelled: false };
-    return navigationBlockersEvaluationStatus;
+    /* eslint-disable no-underscore-dangle */
+    if (session._navigationBlockersEvaluationStatus) {
+      session._navigationBlockersEvaluationStatus.cancelled = true;
+    }
+    session._navigationBlockersEvaluationStatus = { cancelled: false };
+    return session._navigationBlockersEvaluationStatus;
   }
 
-  return function navigationListenerMiddleware() {
+  return function navigationBlockerMiddleware() {
     return (next) => (action) => {
       const { type, payload } = action;
 
@@ -31,11 +29,28 @@ export default function createNavigationBlockerMiddleware(
       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
@@ -52,15 +67,37 @@ export default function createNavigationBlockerMiddleware(
           // 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);
           }
 
@@ -70,23 +107,26 @@ export default function createNavigationBlockerMiddleware(
             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) => {
@@ -96,8 +136,8 @@ export default function createNavigationBlockerMiddleware(
               } 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);
@@ -105,8 +145,8 @@ export default function createNavigationBlockerMiddleware(
             });
           } 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.
@@ -117,7 +157,7 @@ export default function createNavigationBlockerMiddleware(
 
         // Remove any navigation blockers on `DISPOSE` event.
         case ActionTypes.DISPOSE:
-          removeAllNavigationBlockers();
+          removeAllNavigationBlockers(session);
           return next(action);
 
         default:

package/src/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) => {
@@ -18,7 +18,7 @@ export default function createTransformLocationMiddleware({
         case ActionTypes.UPDATE:
           return next({
             type,
-            payload: transformEnvironmentLocation(payload),
+            payload: transformSubscriptionLocation(payload),
           });
 
         default:

package/src/navigationBlockers.js

@@ -1,67 +1,75 @@
-import isPromise from './isPromise';
-import onlyAllowedOnClientSide from './onlyAllowedOnClientSide';
-
-let navigationBlockersList = [];
+/* eslint-disable no-underscore-dangle */
 
-let removeBeforeDestroyListener;
+import isPromise from './isPromise';
 
-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.
-function runNavigationBlocker({ listener }, location) {
+// Runs the `blocker` while ignoring any errors that might be thrown by it.
+function runNavigationBlocker({ 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}\`.`,
+      `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}\`.`,
+        `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;
@@ -91,17 +99,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;
@@ -111,48 +119,59 @@ function onBeforeDestroy() {
   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)
+    !getNavigationBlockers(session).some(
+      (navigationBlocker) => navigationBlocker.beforeDestroy,
+    )
   ) {
-    removeBeforeDestroyListener =
-      environment.addBeforeDestroyListener(onBeforeDestroy);
+    if (session._removeBeforeDestroyListener) {
+      throw new Error(
+        'Unexpected `_removeBeforeDestroyListener` property found in the `session`',
+      );
+    }
+    session._removeBeforeDestroyListener = session.addBeforeDestroyListener(
+      () => onBeforeDestroy(session),
+    );
   }
 
-  const blocker = { listener, beforeDestroy };
-  addNavigationBlockerToTheList(blocker);
+  const newNavigationBlocker = { blocker, beforeDestroy };
+  addNavigationBlockerToTheList(newNavigationBlocker, session);
 
   return () => {
-    removeNavigationBlockerFromTheList(blocker);
+    removeNavigationBlockerFromTheList(newNavigationBlocker, session);
 
-    // If it was the last "beforeDestroy" listener, remove the global `onBeforeDestroy` listener.
+    // If it was the last "beforeDestroy" blocker, remove the global `onBeforeDestroy` listener.
     if (
       beforeDestroy &&
-      !getNavigationBlockers().some(
+      !getNavigationBlockers(session).some(
         (navigationBlocker) => navigationBlocker.beforeDestroy,
       )
     ) {
-      removeBeforeDestroyListener();
-      removeBeforeDestroyListener = undefined;
+      if (!session._removeBeforeDestroyListener) {
+        throw new Error(
+          '`_removeBeforeDestroyListener` property not found in the `session`',
+        );
+      }
+      session._removeBeforeDestroyListener();
+      session._removeBeforeDestroyListener = undefined;
     }
   };
 }

package/src/normalizeInputLocation.js

@@ -38,6 +38,7 @@ export default function normalizeInputLocation(location) {
   // if those properties are not present.
   return {
     ...location,
+    query: location.query || {},
     search: location.search || '',
     hash: location.hash || '',
   };

package/src/parseLocationUrl.js

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

package/src/parseQueryFromSearch.js

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