navigation-stack 0.5.3 → 0.6.1

package/lib/esm/navigationBlockers.js

@@ -1,54 +1,51 @@
 /* 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) {
-  if (getNavigationBlockers(session).some(blocker => blocker.beforeTermination)) {
+  // `navigationBlockers` are stored in `session`.
+  const container = session;
+  if (getNavigationBlockers(container).some(blocker => blocker.beforeTermination)) {
     if (!session._removeTerminationBlocker) {
       throw new Error('`_removeTerminationBlocker` property not found in the `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) {
+}, location, environment) {
   let result;
   try {
     result = blocker(location);
   } catch (error) {
-    // eslint-disable-next-line no-console
-    console.warn(`Ignoring navigation blocker \`${blocker.name}\` that failed with \`${error}\`.`);
-    // eslint-disable-next-line no-console
-    console.error(error);
+    environment.log.warn(`Ignoring navigation blocker \`${blocker.name}\` that failed with \`${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(`Ignoring navigation blocker \`${blocker.name}\` that failed with \`${error}\`.`);
-      // eslint-disable-next-line no-console
-      console.error(error);
+      environment.log.warn(`Ignoring navigation blocker \`${blocker.name}\` that failed with \`${error}\`.`);
+      environment.log.error(error);
     });
   }
   // The blocker didn't return a `Promise`.
@@ -59,28 +56,28 @@ function runNavigationBlocker({
 // 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();
     });
   }
   if (result) {
-    debug('Navigation blocked', toLocation.pathname);
+    environment.log.debug('Navigation blocked', toLocation.pathname);
     return result;
   }
   return next();
@@ -88,7 +85,9 @@ 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) {
@@ -107,6 +106,9 @@ function terminationBlocker(session) {
   return true;
 }
 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
@@ -123,11 +125,11 @@ export function addNavigationBlocker(session, blocker) {
   //  and this is bad for performance."
   //
   // https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event
-  if (beforeTermination && !getNavigationBlockers(session).some(navigationBlocker => navigationBlocker.beforeTermination)) {
+  if (beforeTermination && !getNavigationBlockers(container).some(navigationBlocker => navigationBlocker.beforeTermination)) {
     if (session._removeTerminationBlocker) {
       throw new Error('Unexpected `_removeTerminationBlocker` property found in the `session`');
     }
-    session._removeTerminationBlocker = session.lifecycle.addTerminationBlocker(() => {
+    session._removeTerminationBlocker = session.environment.lifecycle.addTerminationBlocker(() => {
       return terminationBlocker(session);
     });
   }
@@ -135,12 +137,12 @@ export function addNavigationBlocker(session, blocker) {
     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(navigationBlocker => navigationBlocker.beforeTermination)) {
+    if (beforeTermination && !getNavigationBlockers(container).some(navigationBlocker => navigationBlocker.beforeTermination)) {
       if (!session._removeTerminationBlocker) {
         throw new Error('`_removeTerminationBlocker` property not found in the `session`');
       }

package/lib/esm/navigationBlockersEvaluation.js

@@ -0,0 +1,145 @@
+import getLocationBaseFromLocation from './getLocationBaseFromLocation';
+import getLocationFromInternalLocation from './getLocationFromInternalLocation';
+import isPromise from './isPromise';
+import { getNavigationBlockers, runNavigationBlockers } from './navigationBlockers';
+
+// Creates "navigation blockers evaluation" status object.
+// It tracks the "cancelled" status of the evaluation:
+// when next navigation happens, the previous one is no longer relevant
+// so the evaluation of navigation blockers for it can be cancelled.
+function createNavigationBlockersEvaluationStatus(container) {
+  /* eslint-disable no-underscore-dangle */
+  if (container._navigationBlockersEvaluationStatus) {
+    container._navigationBlockersEvaluationStatus.cancelled = true;
+  }
+  container._navigationBlockersEvaluationStatus = {
+    cancelled: false
+  };
+  return container._navigationBlockersEvaluationStatus;
+}
+
+// Prevents or allows navigation that was initiated by the application code
+// by making a `.push()` or `.replace()` method call.
+//
+// It doesn't handle `.shift()` method calls 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 the `location` from the address bar
+// and, if such "shift" should've been blocked, it "rewinds" the address bar back
+// to the previous location. This part is handled by another function.
+//
+// Such type of "shifting" and then rewinding the "shift" doesn't really matter to the application code at all.
+// From the application code's point of view, all web browser's address bar doesn't matter and even doesn't exist.
+// All that exists from the application code's point of view is the `location` object in the `NavigationStack`'s state.
+// Until the `location` object in the `NavigationStack`'s state is updated, the "old" page is still rendered.
+// The appliation is only concerned with the updates of the `location` object in the `NavigationStack`'s state
+// and completely ignores any updates to the URL in the web browser's address bar.
+//
+export function blockProgrammaticNavigationIfRequired(toLocationBase,
+// `location` of type `LocationBase`
+session) {
+  // `resultValue` variable name works around a stupid javascript error:
+  // "Cannot redeclare block-scoped variable 'result'".
+  const result = runNavigationBlockers(getNavigationBlockers(session),
+  // Here `payload.location` is `LocationBase`.
+  toLocationBase, session.environment);
+  if (isPromise(result)) {
+    const evaluationStatus = createNavigationBlockersEvaluationStatus(session);
+    // eslint-disable-next-line consistent-return
+    return result.then(promiseResult => {
+      if (evaluationStatus.cancelled) {
+        return true;
+      }
+      return promiseResult;
+    });
+  }
+  return result;
+}
+
+// Runs navigation blockers on internal location update and "undoes" the location update
+// if it should've been blocked.
+//
+// One could ask: Why the hassle of running navigation blockers on internal location update
+// and then rewinding back if the location change should've been blocked?
+// Why not just run navigation blockers on `.push()`/`.replace()`/`.shift()`?
+//
+// The reason why it runs on internal location update here is because
+// aside from programmatic `.shift()` that can be initiated from the application code,
+// there's non-programmatic "shift" navigation when the user manually clicks "Back" or "Forward" button
+// in a web browser. And even if a "shift" navigation is initiated programmatically in the application code,
+// it still doesn't know yet what the new location is gonna be cause it only knows the numeric `delta`.
+// Such cases could only be handled by reacting to internal location updates which,
+// in case of "Back"/"Forward", only happen after the URL in the browser's address bar has changed.
+//
+// There's no real drawback in reacting to an internal location update "post factum" because
+// from the application code's point of view, web browser's address bar doesn't matter and even doesn't exist.
+// All that exists from the application code's point of view is the `navigationStack.current` location
+// returned from  the `NavigationStack`. Until that location is updated, the "old" page is still rendered.
+// The appliation is only concerned with the updates of the internal `location` object in the `NavigationStack``
+// and completely ignores any updates to the URL in the web browser's address bar.
+//
+// So here, the code attempts to prevent or allow navigation that has already happened
+// in the web browser's address bar but hasn't yet happened in the `NavigationStack`'s state.
+// For example, it could be a user clicking a "Back"/"Forward" button in a web browser.
+// If such navigation should've been blocked, it will simply not update the `location` object
+// in the `NavigationStack`'s 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 the `NavigationStack`'s state.
+//
+// Returns either a `boolean` value or a `Promise` that resolves to a `boolean` value:
+// * `false` when navigation should not have been blocked and therefore was not "rewinded".
+// * `true` when navigation should have been blocked and therefore was "rewinded".
+// * `true` when it "rewinded" the navigation "just in case" and then started evaluating async blockers,
+//   but while doing that, next navigation already happened so this one is no longer relevant.
+//
+export function blockNonProgrammaticNavigationIfRequired(toLocationInternal,
+// `location` of type `LocationInternal`
+session, doAndIgnoreLocationUpdates) {
+  // If there're no navigation blockers to run, don't do anything.
+  if (getNavigationBlockers(session).length === 0) {
+    return false;
+  }
+
+  // If it was the initial page load or a redirect,
+  // it's not really a navigation that could be rolled back.
+  if (toLocationInternal.delta === 0) {
+    return false;
+  }
+  const result = runNavigationBlockers(getNavigationBlockers(session), getLocationBaseFromLocation(getLocationFromInternalLocation(toLocationInternal)), session.environment);
+
+  // If some navigation blocker returned a `Promise`.
+  if (isPromise(result)) {
+    const evaluationStatus = createNavigationBlockersEvaluationStatus(session);
+
+    // While location blockers are running, rewind to the previous location.
+    doAndIgnoreLocationUpdates(() => {
+      session.shift(-toLocationInternal.delta);
+    });
+    return result.then(promiseResult => {
+      if (evaluationStatus.cancelled) {
+        return true;
+      }
+      if (promiseResult) {
+        // Navigation blocked.
+        // Already rewound to a previous location.
+        return true;
+      }
+      // Navigation not blocked.
+      // Rewind back to the new location.
+      doAndIgnoreLocationUpdates(() => {
+        session.shift(toLocationInternal.delta);
+      });
+      // Update the location.
+      return false;
+    });
+  }
+
+  // Navigation blockers did not return a `Promise`.
+  if (result) {
+    // Prevent the navigation: rewind to the previous location.
+    doAndIgnoreLocationUpdates(() => {
+      session.shift(-toLocationInternal.delta);
+    });
+    return true;
+  }
+  // Update the location.
+  return false;
+}

package/lib/esm/parseInputLocation.js

@@ -1,6 +1,6 @@
-import createSearchFromQuery from './createSearchFromQuery';
 import parseLocationUrl from './parseLocationUrl';
 import parseQueryFromSearch from './parseQueryFromSearch';
+import stringifyQueryAsSearch from './stringifyQueryAsSearch';
 function stringifyQueryParameterValue(value) {
   if (value === null || value === undefined) {
     return value;
@@ -40,7 +40,7 @@ export default function parseInputLocation(location) {
   // if `query` is present but `search` is not.
   if (location.query && !location.search) {
     location = Object.assign({}, location, {
-      search: createSearchFromQuery(location.query)
+      search: stringifyQueryAsSearch(location.query)
     });
   }
 

package/lib/esm/parseQueryFromSearch.js

@@ -1,11 +1,7 @@
-import { parse as parseQuery } from 'query-string';
+import parseQueryString from './parseQueryString';
 export default function parseQueryFromSearch(search) {
   if (search.length > '?'.length) {
-    try {
-      return parseQuery(search.slice(1));
-    } catch (error) {
-      // Ignore any query parsing errors.
-    }
+    return parseQueryString(search.slice('?'.length));
   }
   return {};
 }

package/lib/esm/parseQueryString.js

@@ -0,0 +1,72 @@
+function splitAtFirstOccurence(string, separator) {
+  const separatorIndex = string.indexOf(separator);
+  if (separatorIndex === -1) {
+    return [string, ''];
+  }
+  return [string.slice(0, separatorIndex), string.slice(separatorIndex + separator.length)];
+}
+function decode(value) {
+  // There's a convention that a space character could be encoded
+  // either as "%20" or as "+". Both of them are valid.
+  // The "+" character is unusally preferred because it results in a more
+  // human-readable URL.
+  //
+  // https://dev.to/lico/understanding-how-spaces-are-encoded-20-with-encodeuri-vs-with-url-2d6c
+  // https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding
+  //
+  // Those "+" characters don't get transformed to spaces by `decodeURIComponent()` function.
+  // This means that they should be transformed to spaces manually.
+  //
+  // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#decoding_query_parameters_from_a_url
+  //
+  value = value.replaceAll('+', ' ');
+
+  // `decodeURIComponent()` could throw an error of class `URIError`.
+  //
+  // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/URIError
+  //
+  // Example: "URIError: malformed URI sequence".
+  try {
+    return decodeURIComponent(value);
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.error(error);
+    return value;
+  }
+}
+export default function parseQueryString(queryString) {
+  // Create an object with no prototype
+  const query = Object.create(null);
+
+  // query parameter parsing is described in the specification:
+  // https://url.spec.whatwg.org/#urlencoded-parsing
+  for (const keyValuePair of queryString.split('&')) {
+    if (!keyValuePair) {
+      continue;
+    }
+    let [key, value] = splitAtFirstOccurence(keyValuePair, '=');
+
+    // If `key` is empty, the specification considers this a valid case with `key: null`.
+    // But, there seems to be no practical use for a query parameter with `key: null`.
+    // So just skip it.
+    if (!key) {
+      continue;
+    }
+    key = decode(key);
+
+    // According to the specification, missing `=` should be treated as `value: null`.
+    if (value === '') {
+      value = null;
+    } else {
+      value = decode(value);
+    }
+
+    // The handling of duplicate URL query parameters is not explicitly defined by a single,
+    // universally enforced specification. Hence, we just assume such query parameters invalid
+    // and only include the first occurrence of the query parameter in the query string.
+    if (query[key] === undefined) {
+      query[key] = value;
+    }
+  }
+  return query;
+}

package/lib/esm/scroll-position/ScrollPositionAutoSaver.js

@@ -2,14 +2,15 @@
 
 import { PAGE_SCROLLABLE_CONTAINER_KEY } from './constants';
 import scheduleNextTick from './scheduleNextTick';
-import debug from '../debug';
 export default class ScrollPositionAutoSaver {
   constructor({
+    log,
     scrollPosition,
     scrollPositionSaver,
     getScrollableContainers,
     shouldSaveScrollPosition
   }) {
+    this._log = log;
     this._scrollPosition = scrollPosition;
     this._scrollPositionSaver = scrollPositionSaver;
     this._shouldSaveScrollPosition = shouldSaveScrollPosition;
@@ -61,7 +62,7 @@ export default class ScrollPositionAutoSaver {
   cancelSavePageScrollPosition(hasRun) {
     if (this._cancelSavePageScrollPosition) {
       if (!hasRun) {
-        debug('cancel delayed save scroll position', PAGE_SCROLLABLE_CONTAINER_KEY);
+        this._log.debug('cancel delayed save scroll position', PAGE_SCROLLABLE_CONTAINER_KEY);
       }
       this._cancelSavePageScrollPosition();
       this._cancelSavePageScrollPosition = null;
@@ -71,7 +72,7 @@ export default class ScrollPositionAutoSaver {
     const scrollableContainerEntry = this._getScrollableContainers()[scrollableContainerKey];
     if (scrollableContainerEntry.cancelSaveScrollPosition) {
       if (!hasRun) {
-        debug('cancel delayed save scroll position', scrollableContainerKey);
+        this._log.debug('cancel delayed save scroll position', scrollableContainerKey);
       }
       scrollableContainerEntry.cancelSaveScrollPosition();
       scrollableContainerEntry.cancelSaveScrollPosition = null;
@@ -103,9 +104,9 @@ export default class ScrollPositionAutoSaver {
       // because there might be too many in a given short period of time
       // which could affect the performance of the application.
       if (!scrollableContainerEntry.cancelSaveScrollPosition) {
-        debug('scroll detected', scrollableContainerKey);
+        this._log.debug('scroll detected', scrollableContainerKey);
         scrollableContainerEntry.cancelSaveScrollPosition = scheduleNextTick(() => {
-          debug('auto-save scroll position after scroll', scrollableContainerKey);
+          this._log.debug('auto-save scroll position after scroll', scrollableContainerKey);
           this._scrollPositionSaver.saveScrollableContainerScrollPosition(scrollableContainerKey, scrollableContainerEntry.scrollableContainer);
         });
       }
@@ -114,7 +115,7 @@ export default class ScrollPositionAutoSaver {
   addPageScrollListener() {
     // Set up scroll listener on the page.
     this._removePageScrollListener = this._scrollPosition.addPageScrollListener(() => {
-      debug('scroll detected', PAGE_SCROLLABLE_CONTAINER_KEY);
+      this._log.debug('scroll detected', PAGE_SCROLLABLE_CONTAINER_KEY);
 
       // This flag is not used in real life and is only used in tests (for some reason).
       if (!this._shouldSaveScrollPosition()) {

package/lib/esm/scroll-position/ScrollPositionRestoration.js

@@ -5,7 +5,6 @@ import ScrollPositionSaver from './ScrollPositionSaver';
 import ScrollPositionSetter from './ScrollPositionSetter';
 import { PAGE_SCROLLABLE_CONTAINER_KEY } from './constants';
 import LocationDataStorage from '../data-storage/LocationDataStorage';
-import debug from '../debug';
 function areEqualScrollPositions(scrollPosition1, scrollPosition2) {
   let i = 0;
   while (i < scrollPosition1.length) {
@@ -17,7 +16,7 @@ function areEqualScrollPositions(scrollPosition1, scrollPosition2) {
   return true;
 }
 export default class ScrollPositionRestoration {
-  constructor(session, _options) {
+  constructor(session, options) {
     // Once configured, scroll restoration mode persists across page reloads.
     // I.e. even if a user refreshes the page in a web browser, the custom
     // `window.history.scrollRestoration` value will still remain.
@@ -49,10 +48,10 @@ export default class ScrollPositionRestoration {
       running
     }) => {
       if (running) {
-        debug('▶ running');
+        this._log.debug('▶ running');
         this._disableAutomaticScrollRestoration();
       } else {
-        debug('⏹ not running');
+        this._log.debug('⏹ not running');
         this._enableAutomaticScrollRestoration();
 
         // There might be previous scroll position already saved in the data storage.
@@ -80,27 +79,30 @@ export default class ScrollPositionRestoration {
       try {
         this._scrollPosition.disableAutomaticScrollRestoration();
       } catch (error) {
-        // eslint-disable-next-line no-console
-        console.error('[navigation-stack] could not disable default scroll restoration mode');
+        this._log.error('[navigation-stack] could not disable default scroll restoration mode');
       }
     };
     this._enableAutomaticScrollRestoration = () => {
       try {
         this._scrollPosition.enableAutomaticScrollRestoration();
       } catch (error) {
-        // eslint-disable-next-line no-console
-        console.error('[navigation-stack] could not enable default scroll restoration mode');
+        this._log.error('[navigation-stack] could not enable default scroll restoration mode');
       }
     };
     this._saveScrollPositionForLocation = (location, scrollableContainerKey, scrollPosition) => {
       this._locationDataStorage.set(location, scrollableContainerKey || PAGE_SCROLLABLE_CONTAINER_KEY, scrollPosition);
     };
+    this._log = session.environment.log;
     this._scrollPosition = session.environment.scrollPosition;
-    this._sessionLifecycle = session.lifecycle;
+
+    // Custom `ScrollPositionSetter`.
+    this._scrollPositionSetter = options.scrollPositionSetter;
+    this._sessionLifecycle = session.environment.lifecycle;
     this._locationDataStorage = new LocationDataStorage(session, {
-      namespace: 'navigation-stack/scroll-position'
+      namespace: 'navigation-stack-scroll-position'
     });
     this._scrollPositionSaver = new ScrollPositionSaver({
+      log: this._log,
       scrollPosition: this._scrollPosition,
       saveScrollPositionForLocation: this._saveScrollPositionForLocation,
       getScrollableContainers: () => this._scrollableContainers,
@@ -122,20 +124,22 @@ export default class ScrollPositionRestoration {
       // Using this option, a developer could theoretically provide their own implementation
       // of setting a scroll position. For example, it could use "smooth" (animated) scrolling, etc.
       // This could be part of the public API if anyone provided a sensible real-world use case for it.
-      scrollPositionSetter: _options && _options._pageScrollPositionSetter ||
-      // The default page scroll position setter.
+      scrollPositionSetter: options && options._pageScrollPositionSetter ||
+      // eslint-disable-next-line new-cap
+      this._scrollPositionSetter && new this._scrollPositionSetter() ||
+      // A default `ScrollPositionSetter` for a page (sets page scroll position twice with a momentary delay).
       new PageScrollPositionSetter(),
       // This function is only used in tests.
       // There seems to be no use of it in real life, hence it's not public API.
       // It's only used in tests.
-      _getSavedScrollPositionOnLocationChange: _options && _options._getSavedPageScrollPositionOnLocationChange,
+      _getSavedScrollPositionOnLocationChange: options && options._getSavedPageScrollPositionOnLocationChange,
       // This function is only used in tests.
       // There seems to be no use of it in real life, hence it's not public API.
       // It's only used in tests.
-      _shouldSetScrollPositionOnLocationChange: _options && _options._shouldSetPageScrollPositionOnLocationChange
+      shouldChangeScrollPositionOnLocationChange: options && options.shouldChangePageScrollPositionOnLocationChange
     };
   }
-  addScrollableContainer(scrollableContainerKey, scrollableContainer, _options) {
+  addScrollableContainer(scrollableContainerKey, scrollableContainer, options) {
     // Originally, `scrollableContainerKey` was auto-generated,
     // but then it didn't work with the concept of dynamically adding or removing
     // scrollable containers after `ScrollPositionRestoration` has already started.
@@ -152,7 +156,7 @@ export default class ScrollPositionRestoration {
     if (this._scrollableContainers[scrollableContainerKey]) {
       throw new Error(`Scrollable container key "${scrollableContainerKey}" is already added`);
     }
-    debug('add scrollable container', scrollableContainerKey);
+    this._log.debug('add scrollable container', scrollableContainerKey);
 
     // Add scrollable container entry.
     this._scrollableContainers[scrollableContainerKey] = {
@@ -161,17 +165,17 @@ export default class ScrollPositionRestoration {
       // Using this option, a developer could theoretically provide their own implementation
       // of setting a scroll position. For example, it could use "smooth" (animated) scrolling, etc.
       // This could be part of the public API if anyone provided a sensible real-world use case for it.
-      scrollPositionSetter: _options && _options._scrollPositionSetter ||
+      scrollPositionSetter: options && options._scrollPositionSetter || this._scrollPositionSetter && new this._scrollPositionSetter() ||
       // The default basic "immediate" scroll position setter.
       new ScrollPositionSetter(),
       // This function is only used in tests.
       // There seems to be no use of it in real life, hence it's not public API.
       // It's only used in tests.
-      _shouldSetScrollPositionOnLocationChange: _options && _options._shouldSetScrollPositionOnLocationChange,
+      shouldChangeScrollPositionOnLocationChange: options && options.shouldChangeScrollPositionOnLocationChange,
       // This function is only used in tests.
       // There seems to be no use of it in real life, hence it's not public API.
       // It's only used in tests.
-      _getSavedScrollPositionOnLocationChange: _options && _options._getSavedScrollPositionOnLocationChange
+      _getSavedScrollPositionOnLocationChange: options && options._getSavedScrollPositionOnLocationChange
     };
 
     // Scrollable containers could be added at any time, including page mount.
@@ -183,10 +187,10 @@ export default class ScrollPositionRestoration {
     if (this._location) {
       const previouslySavedScrollPosition = this._getSavedScrollPositionForLocation(this._location, scrollableContainerKey);
       if (previouslySavedScrollPosition) {
-        debug('restore scroll position on add scrollable container', this._location.pathname, scrollableContainerKey, previouslySavedScrollPosition);
+        this._log.debug('restore scroll position on add scrollable container', this._location.pathname, scrollableContainerKey, previouslySavedScrollPosition);
         this._scrollPosition.setScrollableContainerScrollPosition(scrollableContainer, previouslySavedScrollPosition);
       } else {
-        debug('save scroll position on add scrollable container', this._location.pathname, scrollableContainerKey);
+        this._log.debug('save scroll position on add scrollable container', this._location.pathname, scrollableContainerKey);
         this._scrollPositionSaver.saveScrollableContainerScrollPosition(scrollableContainerKey, scrollableContainer);
       }
     }
@@ -196,7 +200,7 @@ export default class ScrollPositionRestoration {
 
     // Removes the scrollable container.
     return () => {
-      debug('remove scrollable container', scrollableContainerKey);
+      this._log.debug('remove scrollable container', scrollableContainerKey);
       this._scrollPositionSaver._scrollPositionAutoSaver.cancelSaveScrollableContainerScrollPosition(scrollableContainerKey);
       this._scrollPositionSaver._scrollPositionAutoSaver.removeScrollableContainerScrollListener(scrollableContainerKey);
       delete this._scrollableContainers[scrollableContainerKey];
@@ -268,7 +272,7 @@ export default class ScrollPositionRestoration {
     if (!location.key) {
       throw new Error('`location` must have a `key`');
     }
-    debug('rendered location', location.pathname);
+    this._log.debug('rendered location', location.pathname);
     this._prevLocation = this._location;
     this._location = location;
     this._scrollPosition.init();
@@ -329,8 +333,8 @@ export default class ScrollPositionRestoration {
       // This function is only used in tests.
       // There seems to be no use of it in real life, hence it's not public API.
       // It's only used in tests.
-      if (scrollableContainerEntry._shouldSetScrollPositionOnLocationChange) {
-        if (!scrollableContainerEntry._shouldSetScrollPositionOnLocationChange(this._location, this._prevLocation)) {
+      if (scrollableContainerEntry.shouldChangeScrollPositionOnLocationChange) {
+        if (!scrollableContainerEntry.shouldChangeScrollPositionOnLocationChange(this._prevLocation, this._location)) {
           return Promise.resolve();
         }
       }
@@ -342,14 +346,14 @@ export default class ScrollPositionRestoration {
       // There seems to be no use of it in real life, hence it's not public API.
       // It's only used in tests.
       if (scrollableContainerEntry._getSavedScrollPositionOnLocationChange) {
-        scrollPositionOrAnchorToSet = scrollableContainerEntry._getSavedScrollPositionOnLocationChange(this._location, this._prevLocation);
+        scrollPositionOrAnchorToSet = scrollableContainerEntry._getSavedScrollPositionOnLocationChange(this._prevLocation, this._location);
       }
 
       // Get scroll position (or anchor) to set.
       if (!scrollPositionOrAnchorToSet) {
         scrollPositionOrAnchorToSet = scrollableContainerKey === PAGE_SCROLLABLE_CONTAINER_KEY ? this._getPageScrollPositionOrAnchorToSet(this._location) : this._getScrollableContainerScrollPositionToSet(this._location, scrollableContainerKey);
       }
-      debug('restore scroll position', this._location.pathname, scrollableContainerKey, scrollPositionOrAnchorToSet);
+      this._log.debug('restore scroll position', this._location.pathname, scrollableContainerKey, scrollPositionOrAnchorToSet);
 
       // Set scroll position of scrollable container.
       return scrollableContainerEntry.scrollPositionSetter.set(scrollableContainerEntry.scrollableContainer, scrollPositionOrAnchorToSet, this._scrollPosition);