navigation-stack 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# 0.5.0 / 07.09.2025
+
+- Added `location.index` property.
+- `location.operation` is now lowercase:
+  - `"INIT"` → `"init"`
+  - `"PUSH"` → `"push"`
+  - `"REPLACE"` → `"replace"`
+  - `"SHIFT"` → `"shift"`
+
+# 0.4.0 / 06.09.2025
+
+- Initial release after a refactoring.

package/README.md

@@ -65,7 +65,8 @@ navigationStack.push('/new-location')
 navigationStack.replace('/new-location')
 
 // Sets the `location` to be a previous one (if there is one).
-// If there's no such `location` in the navigation history, throws a `NavigationOutOfBoundsError`.
+// If there's no such `location` in the navigation history,
+// throws a `NavigationOutOfBoundsError` error that has an `index` property.
 //
 // One could think of it as an equivalent of clicking a "Back" button in a web browser.
 //
@@ -76,7 +77,8 @@ navigationStack.replace('/new-location')
 navigationStack.shift(-1)
 
 // Sets the `location` to be a next one (if there is one).
-// If there's no such `location` in the navigation history, throws a `NavigationOutOfBoundsError`.
+// If there's no such `location` in the navigation history,
+// throws a `NavigationOutOfBoundsError` error that has an `index` property.
 //
 // One could think of it as an equivalent of clicking a "Forward" button in a web browser.
 //
@@ -134,7 +136,8 @@ To get the current location, use `navigationStack.current()`.
 
 Current `location` object has all the properties of a [standard web browser location](https://developer.mozilla.org/en-US/docs/Web/API/Window/location) with the addition of:
 * `query: object` — URL query parameters.
-* `key: string` — a unique ID of the `location` object within the session.
+* `key: string` — A string ID of the location that is guaranteed to be unique within the session's limits and could be used as a "key" to store any supplementary data associated to this location.
+* `index: number` — The index of the location in the navigation stack, starting with `0` for the initial location.
 
 <!-- ## Subscribe to Location Changes -->
 
@@ -224,7 +227,7 @@ navigationStack.init()
 // Render the initial location.
 document.body.innerHTML = '<div> Initial Location </div>'
 
-// When a page has been rendered, tell `NavigationStack` to restore
+// As soon as a page has been rendered, without any delay, tell `NavigationStack` to restore
 // a previously-saved scroll position, if there's any.
 //
 // This method must be called both for the initial location and any subsequent location.
@@ -244,6 +247,7 @@ navigationStack.push('/new-location')
 document.body.innerHTML = '<div> New Location </div>'
 
 // The new location is now rendered.
+// Immediately after it has been rendered, call `.locationRenered()`.
 // There's no scroll position to restore because it's not a previously-visited location.
 navigationStack.locationRendered()
 
@@ -260,6 +264,7 @@ navigationStack.shift(-1)
 document.body.innerHTML = '<div> Initial Location </div>'
 
 // The initial location is now rendered.
+// Immediately after it has been rendered, call `.locationRenered()`.
 // Restores the scroll position at the initial location.
 navigationStack.locationRendered()
 
@@ -276,7 +281,7 @@ navigationStack.stop()
 `NavigationStack` provides methods:
 
 * `addScrollableContainer(key: string, element: Element)` — Use it in cases when it should restore not only the page scroll position but also the scroll position(s) of any other scrollable container(s). Returns a "remove scrollable container" function.
-* `locationRendered()` — Call it every time a different location has been rendered, i.e. immediately after a different location has been rendered, including the initial location.
+* `locationRendered()` — Call it every time a different location has been rendered, including the initial location, without any delay, i.e. immediately after a different location has been rendered.
 
 <details>
 <summary>Using scroll position restoration feature without <code>NavigationStack</code></summary>
@@ -309,8 +314,8 @@ window.history.replaceState({ key: '123' }, '', '/initial-location')
 // Render the initial location.
 document.body.innerHTML = '<div> Initial Location </div>'
 
-// When a page has been rendered, call "did render location" listener
-// with the "current location" object as the argument.
+// Immediately after a page has been rendered, without any delay,
+// call `.locationRendered()` method with the "current location" object as the argument.
 scrollPositionRestoration.locationRendered({ key: '123', pathname: '/initial-location' })
 
 //----------------------------------------------------------------------------------------
@@ -329,6 +334,7 @@ window.history.pushState({ key: '456' }, '', '/new-location')
 document.body.innerHTML = '<div> New Location </div>'
 
 // The new location is now rendered.
+// Call `.locationRendered()` immediately after it has been rendered, i.e. without any delay.
 // There's no scroll position to restore because it's not a previously-visited location.
 // The "current location" object must have a `key`.
 scrollPositionRestoration.locationRendered({ key: '456', pathname: '/new-location' })
@@ -349,7 +355,8 @@ window.history.go(-1)
 document.body.innerHTML = '<div> Initial Location </div>'
 
 // The initial location is now rendered.
-// Restores the scroll position at the initial location.
+// Call `.locationRendered()` immediately after it has been rendered, i.e. without any delay.
+// It will restore the scroll position at the initial location.
 // The "current location" object must have a `key`.
 scrollPositionRestoration.locationRendered({ key: '123', pathname: '/initial-location' })
 
@@ -372,7 +379,7 @@ scrollPositionRestoration.stop()
 `ScrollPositionRestoration` provides methods:
 
 * `addScrollableContainer(key: string, element: Element)` — Use it in cases when it should restore not only the page scroll position but also the scroll position(s) of any other scrollable container(s). Returns a "remove scrollable container" function.
-* `locationRendered(location)` — Call it every time a different location has been rendered, i.e. immediately after a different location has been rendered, including the initial location. The location argument should be a `navigation-stack` location.
+* `locationRendered(location)` — Call it every time a different location has been rendered, including the initial location, without any delay, i.e. immediately after a different location has been rendered. The location argument must have a `key`.
 * `stop()` — Stops scroll position restoration and clears any listeners or timers.
 </details>
 
@@ -449,6 +456,8 @@ navigationStack.push('/new-location')
 
 ######
 
+Every "session" has a unique `key`.
+
 Once created, a "session" is simply passed to the `NavigationStack` constructor and then you don't have to deal with it anymore — `NavigationStack` will pull all the strings for you.
 
 However, if someone prefers to completely bypass `NavigationStack` and interact with a "session" object directly, they could do so.
@@ -460,7 +469,6 @@ However, if someone prefers to completely bypass `NavigationStack` and interact
 
 * `key: string` — A unique ID of the session.
 * `subscribe(listener: (location) => {}): () => {}` — Subscribes to location changes, including setting the initial location. Returns an "unsubscribe" function. The `location` argument of the listener function is an "extended" location object having additional properties:
-  * `index: number` — The index of the location in the session's navigation history, starting with `0` for the initial location.
   * `operation: string` — The type of navigation that led to the location.
     * `INIT` in case of the initial location before any navigation has taken place.
     * `SHIFT` when the user performs a "Back" or "Forward" navigation, or after a `.shift()` navigation which is essentially a "back or forward navigation".
@@ -474,7 +482,7 @@ However, if someone prefers to completely bypass `NavigationStack` and interact
     * `-1` after the user clicks a "Back" button in their web browser.
     * `1` after the user clicks a "Forward" button in their web browser.
 <!-- * `getInitialLocation(): object?` — Returns the initial location, if the session can get it from somewhere. For example, in a web browser, the initial location can be read from `window.location`. In other environments, such as server side, the initial location can't be read from anywhere. -->
-* `start(initialLocation?: object)` — Starts the session.
+* `start(initialLocation?: object)` — Starts the session. The `initialLocation` argument is optional when the session can read it from somewhere. For example, `WebBrowserSession` can read `initialLocation` from `window.location`.
 * `stop()` — Stops the session. Cleans up any listeners, etc.
 * `navigate(operation: string, location: object)` — Navigates to a `location` using either `"PUSH"` or `"REPLACE"` operation. The `location` argument should be a result of calling `parseInputLocation()` function.
 * `shift(delta: number)` — Navigates "back" or "forward" by skipping a specified count of pages. Negative `delta` skips backwards, positive `delta` skips forward.
@@ -586,7 +594,7 @@ navigationStack.push('/new-location')
 
 Navigation blocker should be a function that receives a `newLocation` argument and could be "synchronous" or "asynchronous" (i.e. return a `Promise`, aka `async`/`await`).
 
-The `newLocation` argument of a blocker function won't necessarily have a `key` property but other properties are present.
+The `newLocation` argument of a blocker function might not necessarily have a `key` or `index` property but other properties are present.
 
 Navigation blockers fire both when navigating from one page to another and when closing the current browser tab. In the latter case, `newLocation` argument will be `null`, and also the blocker function can't return a `Promise` (because it won't wait), and returning `true` from it will cause the web browser will to show a confirmation modal with a non-customizable generic browser-specific text like "Leave site? Changes you made might not be saved".
 

package/lib/cjs/NavigationStack.js

@@ -7,13 +7,23 @@ var _Actions = _interopRequireDefault(require("./redux/Actions"));
 var _createMiddlewares = _interopRequireDefault(require("./redux/createMiddlewares"));
 var _locationReducer = _interopRequireDefault(require("./redux/locationReducer"));
 var _ScrollPositionRestoration = _interopRequireDefault(require("./scroll-position/ScrollPositionRestoration"));
+const _excluded = ["maintainScrollPosition"];
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+function _objectWithoutPropertiesLoose(r, e) { if (null == r) return {}; var t = {}; for (var n in r) if ({}.hasOwnProperty.call(r, n)) { if (-1 !== e.indexOf(n)) continue; t[n] = r[n]; } return t; }
+function getCreateMiddlewaresOptions(navigationStackOptions) {
+  if (!navigationStackOptions) {
+    return undefined;
+  }
+  // eslint-disable-next-line no-unused-vars
+  const restOptions = _objectWithoutPropertiesLoose(navigationStackOptions, _excluded);
+  return restOptions;
+}
 class NavigationStack {
   constructor(session, options) {
     this._session = session;
 
     // Create a Redux store.
-    this._store = (0, _redux.createStore)(_locationReducer.default, (0, _redux.applyMiddleware)(...(0, _createMiddlewares.default)(session, options)));
+    this._store = (0, _redux.createStore)(_locationReducer.default, (0, _redux.applyMiddleware)(...(0, _createMiddlewares.default)(session, getCreateMiddlewaresOptions(options))));
 
     // Create `ScrollPositionRestoration`.
     if (options && options.maintainScrollPosition) {
@@ -65,8 +75,13 @@ class NavigationStack {
   }
   locationRendered() {
     if (this._scrollPositionRestoration) {
-      this._scrollPositionRestoration.locationRendered(this.current());
+      const location = this.current();
+      if (!location) {
+        throw new Error('Not initialized');
+      }
+      return this._scrollPositionRestoration.locationRendered(location);
     }
+    return Promise.resolve();
   }
 }
 exports.default = NavigationStack;

package/lib/cjs/debug.js

@@ -0,0 +1,12 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = debug;
+const DEBUG = false;
+function debug(...args) {
+  if (DEBUG) {
+    // eslint-disable-next-line no-console
+    console.log(...args);
+  }
+}
+module.exports = exports.default;

package/lib/cjs/getLocationFromInternalLocation.js

@@ -2,10 +2,10 @@
 
 exports.__esModule = true;
 exports.default = getLocationFromInternalLocation;
-const _excluded = ["operation", "index", "delta"];
+const _excluded = ["operation", "delta"];
 function _objectWithoutPropertiesLoose(r, e) { if (null == r) return {}; var t = {}; for (var n in r) if ({}.hasOwnProperty.call(r, n)) { if (-1 !== e.indexOf(n)) continue; t[n] = r[n]; } return t; }
 // Converts `LocationInternal` object to a publicly-visible `Location` object.
-// It hides non-essential properties of location such as `operation`, `index`, `delta`.
+// It hides non-essential properties of location such as `operation` and `delta`.
 function getLocationFromInternalLocation(internalLocation) {
   // eslint-disable-next-line no-unused-vars
   const location = _objectWithoutPropertiesLoose(internalLocation, _excluded);

package/lib/cjs/navigationBlockers.js

@@ -5,6 +5,7 @@ exports.addNavigationBlocker = addNavigationBlocker;
 exports.getNavigationBlockers = getNavigationBlockers;
 exports.removeAllNavigationBlockers = removeAllNavigationBlockers;
 exports.runNavigationBlockers = runNavigationBlockers;
+var _debug = _interopRequireDefault(require("./debug"));
 var _isPromise = _interopRequireDefault(require("./isPromise"));
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 /* eslint-disable no-underscore-dangle */
@@ -80,12 +81,14 @@ function runNavigationBlockers(navigationBlockers, toLocation) {
   if ((0, _isPromise.default)(result)) {
     return result.then(resultValue => {
       if (resultValue) {
+        (0, _debug.default)('Navigation blocked', toLocation.pathname);
         return resultValue;
       }
       return next();
     });
   }
   if (result) {
+    (0, _debug.default)('Navigation blocked', toLocation.pathname);
     return result;
   }
   return next();

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

@@ -4,6 +4,7 @@ exports.__esModule = true;
 exports.default = void 0;
 var _constants = require("./constants");
 var _scheduleNextTick = _interopRequireDefault(require("./scheduleNextTick"));
+var _debug = _interopRequireDefault(require("../debug"));
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 /* eslint-disable no-underscore-dangle */
 
@@ -62,15 +63,21 @@ class ScrollPositionAutoSaver {
       }
     }
   }
-  cancelSavePageScrollPosition() {
+  cancelSavePageScrollPosition(hasRun) {
     if (this._cancelSavePageScrollPosition) {
+      if (!hasRun) {
+        (0, _debug.default)('cancel delayed save scroll position', _constants.PAGE_SCROLLABLE_CONTAINER_KEY);
+      }
       this._cancelSavePageScrollPosition();
       this._cancelSavePageScrollPosition = null;
     }
   }
-  cancelSaveScrollableContainerScrollPosition(scrollableContainerKey) {
+  cancelSaveScrollableContainerScrollPosition(scrollableContainerKey, hasRun) {
     const scrollableContainerEntry = this._getScrollableContainers()[scrollableContainerKey];
     if (scrollableContainerEntry.cancelSaveScrollPosition) {
+      if (!hasRun) {
+        (0, _debug.default)('cancel delayed save scroll position', scrollableContainerKey);
+      }
       scrollableContainerEntry.cancelSaveScrollPosition();
       scrollableContainerEntry.cancelSaveScrollPosition = null;
     }
@@ -101,7 +108,9 @@ 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) {
+        (0, _debug.default)('scroll detected', scrollableContainerKey);
         scrollableContainerEntry.cancelSaveScrollPosition = (0, _scheduleNextTick.default)(() => {
+          (0, _debug.default)('auto-save scroll position after scroll', scrollableContainerKey);
           this._scrollPositionSaver.saveScrollableContainerScrollPosition(scrollableContainerKey, scrollableContainerEntry.scrollableContainer);
         });
       }
@@ -110,6 +119,8 @@ class ScrollPositionAutoSaver {
   addPageScrollListener() {
     // Set up scroll listener on the page.
     this._removePageScrollListener = this._scrollPosition.addPageScrollListener(() => {
+      (0, _debug.default)('scroll detected', _constants.PAGE_SCROLLABLE_CONTAINER_KEY);
+
       // This flag is not used in real life and is only used in tests (for some reason).
       if (!this._shouldSaveScrollPosition()) {
         return;

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

@@ -7,6 +7,7 @@ var _ScrollPositionSaver = _interopRequireDefault(require("./ScrollPositionSaver
 var _ScrollPositionSetter = _interopRequireDefault(require("./ScrollPositionSetter"));
 var _constants = require("./constants");
 var _LocationDataStorage = _interopRequireDefault(require("../data-storage/LocationDataStorage"));
+var _debug = _interopRequireDefault(require("../debug"));
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 /* eslint-disable no-underscore-dangle */
 
@@ -53,8 +54,10 @@ class ScrollPositionRestoration {
       running
     }) => {
       if (running) {
+        (0, _debug.default)('▶ running');
         this._disableAutomaticScrollRestoration();
       } else {
+        (0, _debug.default)('⏹ not running');
         this._enableAutomaticScrollRestoration();
 
         // There might be previous scroll position already saved in the data storage.
@@ -145,10 +148,17 @@ class ScrollPositionRestoration {
     // this._scrollableContainerKeyCounter++;
     // const scrollableContainerKey = String(this._scrollableContainerKeyCounter);
 
+    // Validate `scrollableContainerKey`.
     if (scrollableContainerKey === _constants.PAGE_SCROLLABLE_CONTAINER_KEY) {
       throw new Error(`Scrollable container key "${scrollableContainerKey}" is not allowed`);
     }
 
+    // Check that it hasn't already been added.
+    if (this._scrollableContainers[scrollableContainerKey]) {
+      throw new Error(`Scrollable container key "${scrollableContainerKey}" is already added`);
+    }
+    (0, _debug.default)('add scrollable container', scrollableContainerKey);
+
     // Add scrollable container entry.
     this._scrollableContainers[scrollableContainerKey] = {
       // Scrollable container element.
@@ -178,8 +188,10 @@ class ScrollPositionRestoration {
     if (this._location) {
       const previouslySavedScrollPosition = this._getSavedScrollPositionForLocation(this._location, scrollableContainerKey);
       if (previouslySavedScrollPosition) {
+        (0, _debug.default)('restore scroll position on add scrollable container', this._location.pathname, scrollableContainerKey, previouslySavedScrollPosition);
         this._scrollPosition.setScrollableContainerScrollPosition(scrollableContainer, previouslySavedScrollPosition);
       } else {
+        (0, _debug.default)('save scroll position on add scrollable container', this._location.pathname, scrollableContainerKey);
         this._scrollPositionSaver.saveScrollableContainerScrollPosition(scrollableContainerKey, scrollableContainer);
       }
     }
@@ -189,6 +201,7 @@ class ScrollPositionRestoration {
 
     // Removes the scrollable container.
     return () => {
+      (0, _debug.default)('remove scrollable container', scrollableContainerKey);
       this._scrollPositionSaver._scrollPositionAutoSaver.cancelSaveScrollableContainerScrollPosition(scrollableContainerKey);
       this._scrollPositionSaver._scrollPositionAutoSaver.removeScrollableContainerScrollListener(scrollableContainerKey);
       delete this._scrollableContainers[scrollableContainerKey];
@@ -247,14 +260,20 @@ class ScrollPositionRestoration {
   //
   //   // Save the current scroll position on the current page while it's still rendered.
   //   // This saved scroll position could later be restored in case of returing to this page.
+  //   // Even if the current scroll position is a default one (scrolled to top), it should still
+  //   // be saved in order to overwrite any potential previously-saved non-default scroll position.
   //   this._scrollPositionSaver.saveScrollPosition();
   // };
 
+  // Should be called whenever a different location has been rendered (i.e. immediately after).
+  // Returns a Promise that resolves when finished restoring scroll position.
+  // There's no need to await for that Promise. It's just there because it exists.
   locationRendered(location) {
     // Validate that `location` has a `key`.
     if (!location.key) {
       throw new Error('`location` must have a `key`');
     }
+    (0, _debug.default)('rendered location', location.pathname);
     this._prevLocation = this._location;
     this._location = location;
     this._scrollPosition.init();
@@ -285,7 +304,7 @@ class ScrollPositionRestoration {
 
     // Set the scroll position for the new page:
     // either restore a previously-saved one or set it to a default scroll position.
-    this._setScrollPosition();
+    return this._setScrollPosition();
   }
 
   // Tells if the current scroll position is the default one.
@@ -304,8 +323,12 @@ class ScrollPositionRestoration {
     }
     return true;
   }
+
+  // Restores scroll position.
+  // Returns a Promise that resolves when finished setting scroll position.
+  // There's no need to await for this Promise. It just exists.
   _setScrollPosition() {
-    for (const scrollableContainerKey of Object.keys(this._scrollableContainers)) {
+    return Promise.all(Object.keys(this._scrollableContainers).map(scrollableContainerKey => {
       const scrollableContainerEntry = this._scrollableContainers[scrollableContainerKey];
 
       // This function is only used in tests.
@@ -313,7 +336,7 @@ class ScrollPositionRestoration {
       // It's only used in tests.
       if (scrollableContainerEntry._shouldUpdateScrollPositionForLocation) {
         if (!scrollableContainerEntry._shouldUpdateScrollPositionForLocation(this._location, this._prevLocation)) {
-          continue;
+          return Promise.resolve();
         }
       }
 
@@ -331,10 +354,11 @@ class ScrollPositionRestoration {
       if (!scrollPositionOrAnchorToSet) {
         scrollPositionOrAnchorToSet = scrollableContainerKey === _constants.PAGE_SCROLLABLE_CONTAINER_KEY ? this._getPageScrollPositionOrAnchorToSet(this._location) : this._getScrollableContainerScrollPositionToSet(this._location, scrollableContainerKey);
       }
+      (0, _debug.default)('restore scroll position', this._location.pathname, scrollableContainerKey, scrollPositionOrAnchorToSet);
 
       // Set scroll position of scrollable container.
-      scrollableContainerEntry.scrollPositionSetter.set(scrollableContainerEntry.scrollableContainer, scrollPositionOrAnchorToSet, this._scrollPosition);
-    }
+      return scrollableContainerEntry.scrollPositionSetter.set(scrollableContainerEntry.scrollableContainer, scrollPositionOrAnchorToSet, this._scrollPosition);
+    }));
   }
   _getSavedScrollPositionForLocation(location, scrollableContainerKey = _constants.PAGE_SCROLLABLE_CONTAINER_KEY) {
     return this._locationDataStorage.get(location, scrollableContainerKey);

package/lib/cjs/scroll-position/ScrollPositionSaver.js

@@ -4,6 +4,7 @@ exports.__esModule = true;
 exports.default = void 0;
 var _ScrollPositionAutoSaver = _interopRequireDefault(require("./ScrollPositionAutoSaver"));
 var _constants = require("./constants");
+var _debug = _interopRequireDefault(require("../debug"));
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 /* eslint-disable no-underscore-dangle */
 
@@ -41,6 +42,7 @@ class ScrollPositionSaver {
     if (!this._shouldSaveScrollPosition()) {
       return;
     }
+    (0, _debug.default)('save scroll position', this._getLocation().pathname);
 
     // Get scrollable containers.
     const scrollableContainers = this._getScrollableContainers();
@@ -55,23 +57,27 @@ class ScrollPositionSaver {
     }
   }
   savePageScrollPosition() {
+    (0, _debug.default)('save scroll position', this._getLocation().pathname, _constants.PAGE_SCROLLABLE_CONTAINER_KEY, this._scrollPosition.getPageScrollPosition());
+
     // * If this is not a scheduled "auto-save" of scroll position
     //   and there already exists any scheduled "auto-save" of scroll position,
     //   cancel it and save scroll position right now instead.
     // * If this is a scheduled "auto-save" of scroll position,
     //   clear the "cancel" function because it's no longer of use.
-    this._scrollPositionAutoSaver.cancelSavePageScrollPosition();
+    this._scrollPositionAutoSaver.cancelSavePageScrollPosition(true);
 
     // Save scroll position.
     this._saveScrollPositionForLocation(this._getLocation(), undefined, this._scrollPosition.getPageScrollPosition());
   }
   saveScrollableContainerScrollPosition(scrollableContainerKey, scrollableContainer) {
+    (0, _debug.default)('save scroll position', this._getLocation().pathname, scrollableContainerKey, this._scrollPosition.getScrollableContainerScrollPosition(scrollableContainer));
+
     // * If this is not a scheduled "auto-save" of scroll position
     //   and there already exists any scheduled "auto-save" of scroll position,
     //   cancel it and save scroll position right now instead.
     // * If this is a scheduled "auto-save" of scroll position,
     //   clear the "cancel" function because it's no longer of use.
-    this._scrollPositionAutoSaver.cancelSaveScrollableContainerScrollPosition(scrollableContainerKey);
+    this._scrollPositionAutoSaver.cancelSaveScrollableContainerScrollPosition(scrollableContainerKey, true);
 
     // Save scroll position.
     this._saveScrollPositionForLocation(this._getLocation(), scrollableContainerKey, this._scrollPosition.getScrollableContainerScrollPosition(scrollableContainer));

package/lib/cjs/session/Session.js

@@ -2,6 +2,7 @@
 
 exports.__esModule = true;
 exports.default = void 0;
+var _debug = _interopRequireDefault(require("../debug"));
 var _parseInputLocation = _interopRequireDefault(require("../parseInputLocation"));
 var _createSessionKey = _interopRequireDefault(require("./key/createSessionKey"));
 var _NavigationOutOfBoundsError = _interopRequireDefault(require("./navigation/error/NavigationOutOfBoundsError"));
@@ -56,6 +57,7 @@ class Session {
       // but if it was possible, this call would be required. It would also be required
       // by `navigation` to call `session.getNextKey()` function to increment `locationKeyIndex`.
       this._updateTerminalLocationIndex(location);
+      (0, _debug.default)('current location', location.pathname, 'index', this._currentLocationIndex);
     });
   }
 
@@ -95,6 +97,7 @@ class Session {
     if (this._currentLocationIndex !== INITIAL_INDEX) {
       throw new Error('Already started');
     }
+    (0, _debug.default)('▶ start session', initialLocation.pathname);
     this._started = true;
     const key = this._getNextLocationKey();
     const index = INITIAL_INDEX + 1;
@@ -113,6 +116,7 @@ class Session {
     if (this._stopped) {
       throw Error('Already stopped');
     }
+    (0, _debug.default)('⏹ stop session');
 
     // Once stopped, it won't be able to be restarted.
     this._stopped = true;
@@ -138,6 +142,7 @@ class Session {
     });
     const key = this._getNextLocationKey();
     const index = this._currentLocationIndex + delta;
+    (0, _debug.default)(operation === _operations.default.PUSH ? '↓' : '⇅', operation, location.pathname, 'index', index);
 
     // Navigate to the location.
     const locationResult = this._navigation.navigate(location, {
@@ -160,6 +165,7 @@ class Session {
       return;
     }
     const index = this._currentLocationIndex + delta;
+    (0, _debug.default)(delta > 0 ? '→' : '←', 'shift', delta, 'index', index);
 
     // Validate that the new `index` is not out of bounds.
     if (index < 0 || index > this._terminalLocationIndex) {

package/lib/cjs/session/navigation/operation/operations.js

@@ -3,9 +3,9 @@
 exports.__esModule = true;
 exports.default = void 0;
 var _default = exports.default = {
-  INIT: 'INIT',
-  PUSH: 'PUSH',
-  REPLACE: 'REPLACE',
-  SHIFT: 'SHIFT'
+  INIT: 'init',
+  PUSH: 'push',
+  REPLACE: 'replace',
+  SHIFT: 'shift'
 };
 module.exports = exports.default;

package/lib/esm/NavigationStack.js

@@ -1,14 +1,24 @@
+const _excluded = ["maintainScrollPosition"];
+function _objectWithoutPropertiesLoose(r, e) { if (null == r) return {}; var t = {}; for (var n in r) if ({}.hasOwnProperty.call(r, n)) { if (-1 !== e.indexOf(n)) continue; t[n] = r[n]; } return t; }
 import { applyMiddleware, createStore } from 'redux';
 import Actions from './redux/Actions';
 import createMiddlewares from './redux/createMiddlewares';
 import locationReducer from './redux/locationReducer';
 import ScrollPositionRestoration from './scroll-position/ScrollPositionRestoration';
+function getCreateMiddlewaresOptions(navigationStackOptions) {
+  if (!navigationStackOptions) {
+    return undefined;
+  }
+  // eslint-disable-next-line no-unused-vars
+  const restOptions = _objectWithoutPropertiesLoose(navigationStackOptions, _excluded);
+  return restOptions;
+}
 export default class NavigationStack {
   constructor(session, options) {
     this._session = session;
 
     // Create a Redux store.
-    this._store = createStore(locationReducer, applyMiddleware(...createMiddlewares(session, options)));
+    this._store = createStore(locationReducer, applyMiddleware(...createMiddlewares(session, getCreateMiddlewaresOptions(options))));
 
     // Create `ScrollPositionRestoration`.
     if (options && options.maintainScrollPosition) {
@@ -60,7 +70,12 @@ export default class NavigationStack {
   }
   locationRendered() {
     if (this._scrollPositionRestoration) {
-      this._scrollPositionRestoration.locationRendered(this.current());
+      const location = this.current();
+      if (!location) {
+        throw new Error('Not initialized');
+      }
+      return this._scrollPositionRestoration.locationRendered(location);
     }
+    return Promise.resolve();
   }
 }

package/lib/esm/debug.js

@@ -0,0 +1,7 @@
+const DEBUG = false;
+export default function debug(...args) {
+  if (DEBUG) {
+    // eslint-disable-next-line no-console
+    console.log(...args);
+  }
+}

package/lib/esm/getLocationFromInternalLocation.js

@@ -1,7 +1,7 @@
-const _excluded = ["operation", "index", "delta"];
+const _excluded = ["operation", "delta"];
 function _objectWithoutPropertiesLoose(r, e) { if (null == r) return {}; var t = {}; for (var n in r) if ({}.hasOwnProperty.call(r, n)) { if (-1 !== e.indexOf(n)) continue; t[n] = r[n]; } return t; }
 // Converts `LocationInternal` object to a publicly-visible `Location` object.
-// It hides non-essential properties of location such as `operation`, `index`, `delta`.
+// It hides non-essential properties of location such as `operation` and `delta`.
 export default function getLocationFromInternalLocation(internalLocation) {
   // eslint-disable-next-line no-unused-vars
   const location = _objectWithoutPropertiesLoose(internalLocation, _excluded);

package/lib/esm/navigationBlockers.js

@@ -1,5 +1,6 @@
 /* eslint-disable no-underscore-dangle */
 
+import debug from './debug';
 import isPromise from './isPromise';
 export function getNavigationBlockers(session) {
   return session._navigationBlockersList || [];
@@ -72,12 +73,14 @@ export function runNavigationBlockers(navigationBlockers, toLocation) {
   if (isPromise(result)) {
     return result.then(resultValue => {
       if (resultValue) {
+        debug('Navigation blocked', toLocation.pathname);
         return resultValue;
       }
       return next();
     });
   }
   if (result) {
+    debug('Navigation blocked', toLocation.pathname);
     return result;
   }
   return next();

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

@@ -2,6 +2,7 @@
 
 import { PAGE_SCROLLABLE_CONTAINER_KEY } from './constants';
 import scheduleNextTick from './scheduleNextTick';
+import debug from '../debug';
 export default class ScrollPositionAutoSaver {
   constructor({
     scrollPosition,
@@ -57,15 +58,21 @@ export default class ScrollPositionAutoSaver {
       }
     }
   }
-  cancelSavePageScrollPosition() {
+  cancelSavePageScrollPosition(hasRun) {
     if (this._cancelSavePageScrollPosition) {
+      if (!hasRun) {
+        debug('cancel delayed save scroll position', PAGE_SCROLLABLE_CONTAINER_KEY);
+      }
       this._cancelSavePageScrollPosition();
       this._cancelSavePageScrollPosition = null;
     }
   }
-  cancelSaveScrollableContainerScrollPosition(scrollableContainerKey) {
+  cancelSaveScrollableContainerScrollPosition(scrollableContainerKey, hasRun) {
     const scrollableContainerEntry = this._getScrollableContainers()[scrollableContainerKey];
     if (scrollableContainerEntry.cancelSaveScrollPosition) {
+      if (!hasRun) {
+        debug('cancel delayed save scroll position', scrollableContainerKey);
+      }
       scrollableContainerEntry.cancelSaveScrollPosition();
       scrollableContainerEntry.cancelSaveScrollPosition = null;
     }
@@ -96,7 +103,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);
         scrollableContainerEntry.cancelSaveScrollPosition = scheduleNextTick(() => {
+          debug('auto-save scroll position after scroll', scrollableContainerKey);
           this._scrollPositionSaver.saveScrollableContainerScrollPosition(scrollableContainerKey, scrollableContainerEntry.scrollableContainer);
         });
       }
@@ -105,6 +114,8 @@ 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 flag is not used in real life and is only used in tests (for some reason).
       if (!this._shouldSaveScrollPosition()) {
         return;