navigation-stack 0.5.3 → 0.6.0

package/src/environment/ServerSideRenderEnvironment.js

@@ -0,0 +1,10 @@
+import InMemoryEnvironment from './InMemoryEnvironment';
+import ServerSideNavigation from './navigation/ServerSideNavigation';
+
+// `ServerSideRenderSession` is just a `InMemorySession` that specifically prohibits any navigation.
+export default class ServerSideRenderEnvironment extends InMemoryEnvironment {
+  constructor() {
+    super();
+    this.navigation = new ServerSideNavigation();
+  }
+}

package/src/environment/WebBrowserEnvironment.js

@@ -1,9 +1,15 @@
 import WebBrowserDataStorage from './data-storage/WebBrowserDataStorage';
+import WebBrowserSessionLifecycle from './lifecycle/WebBrowserSessionLifecycle';
+import WebBrowserLog from './log/WebBrowserLog';
+import WebBrowserNavigation from './navigation/WebBrowserNavigation';
 import WebBrowserScrollPosition from './scroll-position/WebBrowserScrollPosition';
 
 export default class WebBrowserEnvironment {
   constructor() {
     this.dataStorage = new WebBrowserDataStorage();
     this.scrollPosition = new WebBrowserScrollPosition();
+    this.lifecycle = new WebBrowserSessionLifecycle();
+    this.log = new WebBrowserLog();
+    this.navigation = new WebBrowserNavigation();
   }
 }

package/src/environment/log/InMemoryLog.js

@@ -0,0 +1,20 @@
+const DEBUG_ENABLED = false;
+
+export default class InMemoryLog {
+  debug(...args) {
+    if (DEBUG_ENABLED) {
+      // eslint-disable-next-line no-console
+      console.log(...args);
+    }
+  }
+
+  warn(...args) {
+    // eslint-disable-next-line no-console
+    console.warn(...args);
+  }
+
+  error(...args) {
+    // eslint-disable-next-line no-console
+    console.error(...args);
+  }
+}

package/src/environment/log/WebBrowserLog.js

@@ -0,0 +1,18 @@
+export default class WebBrowserLog {
+  debug(...args) {
+    if (window.NAVIGATION_STACK_DEBUG_ENABLED) {
+      // eslint-disable-next-line no-console
+      console.log(...args);
+    }
+  }
+
+  warn(...args) {
+    // eslint-disable-next-line no-console
+    console.warn(...args);
+  }
+
+  error(...args) {
+    // eslint-disable-next-line no-console
+    console.error(...args);
+  }
+}

package/src/{session → environment}/navigation/InMemoryNavigation.js

@@ -6,12 +6,23 @@ export default class InMemoryNavigation {
     this._stack = [];
   }
 
+  // Subscribes to any "asynchronous" changes of the current location,
+  // "asynchronous" changes being ones that happen out-of-sync with the code
+  // that might have potentially triggered those changes.
+  //
+  // For example, in a web browser, "Back"/"Forward" navigation happens out-of-sync
+  // with the code that calls `window.pushState()` or `window.replaceState()` function.
+  //
+  // Additionally, in a web browser, "Back"/"Forward" navigation could be triggered
+  // outside of the application code by user clicking those "Back"/"Forward" buttons manually
+  // in their web browser.
+  //
   // eslint-disable-next-line no-unused-vars
-  subscribe(listener) {
-    // `InMemoryNavigation` doesn't have any "asynchronycity" about it
-    // and performs any navigation immediately at the time of the call.
-    // Hence, no asynchronous listener would ever be called
-    // due to no asynchronous events being dispatched.
+  subscribeToAsyncrhonousLocationUpdates(listener) {
+    // `InMemoryNavigation` location changes are always "synchronous"
+    // with the code that initiated such changes, i.e. it always performs
+    // any navigation immediately at the time such navigation is triggered in code.
+    // Hence, this function doesn't have to "subscribe" to anything, so it's a "no op".
     return () => {};
   }
 

package/src/{session → environment}/navigation/ServerSideNavigation.js

@@ -1,6 +1,6 @@
 /* eslint-disable no-underscore-dangle, max-classes-per-file */
 
-import ServerSideNavigationError from './error/ServerSideNavigationError';
+import ServerSideRedirectError from './error/ServerSideRedirectError';
 
 export default class ServerSideNavigation {
   init(initialLocation, { operation, key, index, delta }) {
@@ -13,18 +13,27 @@ export default class ServerSideNavigation {
     };
   }
 
+  // Subscribes to any "asynchronous" changes of the current location,
+  // "asynchronous" changes being ones that happen out-of-sync with the code
+  // that might have potentially triggered those changes.
+  //
+  // For example, in a web browser, "Back"/"Forward" navigation happens out-of-sync
+  // with the code that calls `window.pushState()` or `window.replaceState()` function.
+  //
+  // Additionally, in a web browser, "Back"/"Forward" navigation could be triggered
+  // outside of the application code by user clicking those "Back"/"Forward" buttons manually
+  // in their web browser.
+  //
   // eslint-disable-next-line no-unused-vars
-  subscribe(listener) {
-    // `ServerSideNavigation` doesn't have any "asynchronycity" about it
-    // and any navigation is prohibited and would result in an error.
-    // So no asynchronous listener would ever be called
-    // due to no asynchronous events being dispatched.
+  subscribeToAsyncrhonousLocationUpdates(listener) {
+    // `ServerSideNavigation` location changes are prohibited, so they couldn't happen.
+    // Hence, this function doesn't have to "subscribe" to anything, so it's a "no op".
     return () => {};
   }
 
   // eslint-disable-next-line no-unused-vars
   navigate(location, { operation, key, index, delta }) {
-    throw new ServerSideNavigationError(location);
+    throw new ServerSideRedirectError(location);
   }
 
   // eslint-disable-next-line no-unused-vars

package/src/{session → environment}/navigation/WebBrowserNavigation.js

@@ -48,15 +48,30 @@ export default class WebBrowserNavigation {
     this._currentLocationIndex = NO_LOCATION_INDEX;
   }
 
-  // Subscribes to changes in the current location.
+  // Subscribes to any "asynchronous" changes of the current location,
+  // "asynchronous" changes being ones that happen out-of-sync with the code
+  // that might have potentially triggered those changes.
+  //
+  // For example, in a web browser, "Back"/"Forward" navigation happens out-of-sync
+  // with the code that calls `window.pushState()` or `window.replaceState()` function.
+  //
+  // Additionally, in a web browser, "Back"/"Forward" navigation could be triggered
+  // outside of the application code by user clicking those "Back"/"Forward" buttons manually
+  // in their web browser.
+  //
   // Returns an `unsubscribe()` function which is "idempotent", i.e. it can be called multiple times.
-  subscribe(listener) {
+  //
+  subscribeToAsyncrhonousLocationUpdates(listener) {
     const onPopState = () => {
       // If "popstate" event is received before navigation is initialized,
-      // ignore such "popstate" event. This behavior is logical from the application code's view.
+      // ignore such "popstate" event. Such "ignore" behavior is logical from
+      // the application code's point of view: it doesn't expect any navigation events
+      // to be recorded before it has initialized the navigation.
       // And besides, `this._currentLocationIndex` is not defined in such conditions.
       if (this._currentLocationIndex === NO_LOCATION_INDEX) {
-        throw new Error('Received a "popstate" event before initialized');
+        throw new Error(
+          'Received a "popstate" event before finished initializing navigation',
+        );
       }
       const prevIndex = this._currentLocationIndex;
       const { index } = this._getCurrentLocationState();
@@ -93,6 +108,15 @@ export default class WebBrowserNavigation {
     };
   }
 
+  // When run in a web browser, it could not only "start" a new navigation session
+  // but also "resume" a previously-started navigation session. That could happen
+  // when the user refreshes a page in a web browser which still retains
+  // the previous navigation session's data but at the same time restarts
+  // the javascript code from scratch.
+  //
+  // So this `init()` method handles both cases: when there's previous navigation session's data
+  // that should be restored and when there's no previous navigation session's data.
+  //
   init(initialLocation, { operation, key, index, delta }) {
     // Validate that `initialLocation` is same as `window.location`.
     const isCurrentLocation =
@@ -109,7 +133,8 @@ export default class WebBrowserNavigation {
     // by calling `window.history.replaceState()` on page load.
     // Otherwise, `window.history.state` would be `null` for the initial location
     // and there'd be no place to store the additional properties of the initial location
-    // such as `location.key`.
+    // such as `location.key`. Without `location.key` always being present the initial location object,
+    // there'd be a bug of incorrect scroll position being set on the initial location URL in some scenarios:
     // https://github.com/taion/scroll-behavior/issues/215
     //
     // If the user opens the initial page for the first time, `window.history.state` will be `null`.
@@ -120,7 +145,7 @@ export default class WebBrowserNavigation {
       // Create additional properties for the initial locaiton.
       const additionalProperties = { key, index };
       // Call `history.replaceState()`.
-      this._storeAdditionalPropertiesForLocation(
+      this._navigateToLocationAndKeepItsAdditionalPropertiesInHistory(
         initialLocation,
         additionalProperties,
         delta,
@@ -136,7 +161,7 @@ export default class WebBrowserNavigation {
   navigate(location, { operation, key, index, delta }) {
     const additionalProperties = { key, index };
 
-    this._storeAdditionalPropertiesForLocation(
+    this._navigateToLocationAndKeepItsAdditionalPropertiesInHistory(
       location,
       additionalProperties,
       delta,
@@ -205,7 +230,22 @@ export default class WebBrowserNavigation {
     };
   }
 
-  _storeAdditionalPropertiesForLocation(
+  // Stores "additional" properties associated with `location` in web browser's history storage.
+  // Web browser's history storage is not intended for large datasets and should only be used
+  // to store small bits of data.
+  //
+  // "Some browsers save state objects to the user's disk so they can be restored after the user restarts
+  //  the browser, and impose a size limit on the serialized representation of a state object, and will throw
+  //  an exception if you pass a state object whose serialized representation is larger than that size limit.
+  //  So in cases where you want to ensure you have more space than what some browsers might impose,
+  //  you're encouraged to use sessionStorage and/or localStorage."
+  //
+  // Source: https://developer.mozilla.org/en-US/docs/Web/API/History/pushState
+  //
+  // To store large amounts of data, one could use `window.sessionStorage` instead.
+  // It is accessible via `DataStorage(session)` class.
+  //
+  _navigateToLocationAndKeepItsAdditionalPropertiesInHistory(
     location,
     additionalProperties,
     delta,

package/src/{session/navigation/error/ServerSideNavigationError.js → environment/navigation/error/ServerSideRedirectError.js}

@@ -1,6 +1,6 @@
 import getLocationUrl from '../../../getLocationUrl';
 
-export default class ServerSideNavigationError extends Error {
+export default class ServerSideRedirectError extends Error {
   constructor(location) {
     super(
       location

package/src/environment/scroll-position/WebBrowserScrollPosition.js

@@ -61,10 +61,25 @@ export default class WebBrowserScrollPosition {
   }
 
   enableAutomaticScrollRestoration() {
+    // The default "auto" behavior seems to work in the following way:
+    //
+    // * It doesn't scroll to top on `window.history.pushState()` or `window.history.replaceState()`.
+    //
+    // * It does restore scroll position on "popstate" event
+    //   (they say, in Firefox it happens before the event is dispatched,
+    //    while in Chrome it happens after the event is dispatched)
+    //
+    // https://v5.reactrouter.com/web/guides/scroll-restoration
+    //
     window.history.scrollRestoration = 'auto';
   }
 
   disableAutomaticScrollRestoration() {
+    // Setting `window.history.scrollRestoration` value updates it in the current history entry
+    // and any subsequent history entries.
+    // This means that it should be set at application initialization stage,
+    // that is before any navigation.
+    // https://majido.github.io/scroll-restoration-proposal/history-based-api.html
     window.history.scrollRestoration = 'manual';
   }
 

package/src/getLocationBaseFromLocation.js

@@ -0,0 +1,7 @@
+// Converts `Location` object to a `LocationBase` object.
+// It hides properties of location such as `key` or `index`.
+export default function getLocationBaseFromLocation(location) {
+  // eslint-disable-next-line no-unused-vars
+  const { key, index, ...locationBase } = location;
+  return locationBase;
+}

package/src/getLocationUrl.js

@@ -1,11 +1,8 @@
-import { stringify as stringifyQuery } from 'query-string';
+import stringifyQueryAsSearch from './stringifyQueryAsSearch';
 
 export default function getLocationUrl({ pathname, search, query, hash }) {
   if (!search && query) {
-    const queryString = stringifyQuery(query);
-    if (queryString) {
-      search = `?${queryString}`;
-    }
+    search = stringifyQueryAsSearch(query);
   }
 
   return `${pathname}${search || ''}${hash || ''}`;

package/src/index.js

@@ -1,14 +1,11 @@
 export { addBasePath, removeBasePath } from './basePath';
-export addNavigationBlocker from './addNavigationBlocker';
-export getLocationUrl from './getLocationUrl';
-export parseLocationUrl from './parseLocationUrl';
-export parseInputLocation from './parseInputLocation';
-export NavigationStack from './NavigationStack';
-export DataStorage from './data-storage/DataStorage';
-export LocationDataStorage from './data-storage/LocationDataStorage';
-export Session from './session/Session';
-export InMemorySession from './session/InMemorySession';
-export WebBrowserSession from './session/WebBrowserSession';
-export ServerSideRenderSession from './session/ServerSideRenderSession';
-export ServerSideNavigationError from './session/navigation/error/ServerSideNavigationError';
-export NavigationOutOfBoundsError from './session/navigation/error/NavigationOutOfBoundsError';
+export { default as addNavigationBlocker } from './addNavigationBlocker';
+export { default as getLocationUrl } from './getLocationUrl';
+export { default as parseLocationUrl } from './parseLocationUrl';
+export { default as parseInputLocation } from './parseInputLocation';
+export { default as NavigationStack } from './NavigationStack';
+export { default as InMemoryEnvironment } from './environment/InMemoryEnvironment';
+export { default as WebBrowserEnvironment } from './environment/WebBrowserEnvironment';
+export { default as ServerSideRenderEnvironment } from './environment/ServerSideRenderEnvironment';
+export { default as ServerSideRedirectError } from './environment/navigation/error/ServerSideRedirectError';
+export { default as NavigationOutOfBoundsError } from './environment/navigation/error/NavigationOutOfBoundsError';

package/src/navigationBlockers.js

@@ -1,30 +1,33 @@
 /* eslint-disable no-underscore-dangle */
 
-import debug from './debug';
 import isPromise from './isPromise';
 
-export function getNavigationBlockers(session) {
-  return session._navigationBlockersList || [];
+export function getNavigationBlockers(container) {
+  return container._navigationBlockersList || [];
 }
 
-function addNavigationBlockerToTheList(blocker, session) {
-  if (!session._navigationBlockersList) {
-    session._navigationBlockersList = [];
+function addNavigationBlockerToTheList(blocker, container) {
+  if (!container._navigationBlockersList) {
+    container._navigationBlockersList = [];
   }
-  session._navigationBlockersList.push(blocker);
+  container._navigationBlockersList.push(blocker);
 }
 
-function removeNavigationBlockerFromTheList(blocker, session) {
-  if (session._navigationBlockersList) {
-    session._navigationBlockersList = session._navigationBlockersList.filter(
-      (_) => _ !== blocker,
-    );
+function removeNavigationBlockerFromTheList(blocker, container) {
+  if (container._navigationBlockersList) {
+    container._navigationBlockersList =
+      container._navigationBlockersList.filter((_) => _ !== blocker);
   }
 }
 
 export function removeAllNavigationBlockers(session) {
+  // `navigationBlockers` are stored in `session`.
+  const container = session;
+
   if (
-    getNavigationBlockers(session).some((blocker) => blocker.beforeTermination)
+    getNavigationBlockers(container).some(
+      (blocker) => blocker.beforeTermination,
+    )
   ) {
     if (!session._removeTerminationBlocker) {
       throw new Error(
@@ -34,33 +37,29 @@ export function removeAllNavigationBlockers(session) {
     session._removeTerminationBlocker();
     session._removeTerminationBlocker = undefined;
   }
-  session._navigationBlockersList = [];
+  container._navigationBlockersList = [];
 }
 
 // Runs the `blocker` while ignoring any errors that might be thrown by it.
-function runNavigationBlocker({ blocker }, location) {
+function runNavigationBlocker({ blocker }, location, environment) {
   let result;
   try {
     result = blocker(location);
   } catch (error) {
-    // eslint-disable-next-line no-console
-    console.warn(
+    environment.log.warn(
       `Ignoring navigation blocker \`${blocker.name}\` that failed with \`${error}\`.`,
     );
-    // eslint-disable-next-line no-console
-    console.error(error);
+    environment.log.error(error);
   }
 
   // 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(
+      environment.log.warn(
         `Ignoring navigation blocker \`${blocker.name}\` that failed with \`${error}\`.`,
       );
-      // eslint-disable-next-line no-console
-      console.error(error);
+      environment.log.error(error);
     });
   }
   // The blocker didn't return a `Promise`.
@@ -71,23 +70,35 @@ function runNavigationBlocker({ blocker }, location) {
 // 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) {
+export function runNavigationBlockers(
+  navigationBlockers,
+  toLocation,
+  environment,
+) {
   if (navigationBlockers.length === 0) {
     return undefined;
   }
 
   // Call the first blocker in the list.
-  const result = runNavigationBlocker(navigationBlockers[0], toLocation);
+  const result = runNavigationBlocker(
+    navigationBlockers[0],
+    toLocation,
+    environment,
+  );
 
   const next = () => {
     // Proceed to the next blocker.
-    return runNavigationBlockers(navigationBlockers.slice(1), toLocation);
+    return runNavigationBlockers(
+      navigationBlockers.slice(1),
+      toLocation,
+      environment,
+    );
   };
 
   if (isPromise(result)) {
     return result.then((resultValue) => {
       if (resultValue) {
-        debug('Navigation blocked', toLocation.pathname);
+        environment.log.debug('Navigation blocked', toLocation.pathname);
         return resultValue;
       }
       return next();
@@ -95,7 +106,7 @@ export function runNavigationBlockers(navigationBlockers, toLocation) {
   }
 
   if (result) {
-    debug('Navigation blocked', toLocation.pathname);
+    environment.log.debug('Navigation blocked', toLocation.pathname);
     return result;
   }
   return next();
@@ -103,7 +114,14 @@ export function runNavigationBlockers(navigationBlockers, toLocation) {
 
 /* istanbul ignore next: not testable with Karma */
 function terminationBlocker(session) {
-  const result = runNavigationBlockers(getNavigationBlockers(session), null);
+  // `navigationBlockers` are stored in `session`.
+  const container = session;
+
+  const result = runNavigationBlockers(
+    getNavigationBlockers(container),
+    null,
+    session.environment,
+  );
 
   // If no blocker returned anything, so don't prevent the navigation.
   if (!result) {
@@ -123,6 +141,9 @@ function terminationBlocker(session) {
 }
 
 export function addNavigationBlocker(session, blocker) {
+  // `navigationBlockers` are stored in `session`.
+  const container = session;
+
   // All navigation blockers also run on `beforeTermination` event.
   // If required, this could be a parameter of this function.
   // The rationale could be that adding a `beforeunload` listener
@@ -141,7 +162,7 @@ export function addNavigationBlocker(session, blocker) {
   // https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event
   if (
     beforeTermination &&
-    !getNavigationBlockers(session).some(
+    !getNavigationBlockers(container).some(
       (navigationBlocker) => navigationBlocker.beforeTermination,
     )
   ) {
@@ -151,21 +172,21 @@ export function addNavigationBlocker(session, blocker) {
       );
     }
     session._removeTerminationBlocker =
-      session.lifecycle.addTerminationBlocker(() => {
+      session.environment.lifecycle.addTerminationBlocker(() => {
         return terminationBlocker(session);
       });
   }
 
   const newNavigationBlocker = { blocker, beforeTermination };
-  addNavigationBlockerToTheList(newNavigationBlocker, session);
+  addNavigationBlockerToTheList(newNavigationBlocker, container);
 
   return () => {
-    removeNavigationBlockerFromTheList(newNavigationBlocker, session);
+    removeNavigationBlockerFromTheList(newNavigationBlocker, container);
 
     // If it was the last "beforeTermination" blocker, remove navigation blocker.
     if (
       beforeTermination &&
-      !getNavigationBlockers(session).some(
+      !getNavigationBlockers(container).some(
         (navigationBlocker) => navigationBlocker.beforeTermination,
       )
     ) {