navigation-stack 0.3.0 → 0.4.0

package/lib/cjs/session/navigation/error/NavigationOutOfBoundsError.js

@@ -0,0 +1,12 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+class NavigationOutOfBoundsError extends Error {
+  constructor(index) {
+    super(`Location index ${index} is out of navigation history bounds`);
+    this.index = index;
+  }
+}
+exports.default = NavigationOutOfBoundsError;
+module.exports = exports.default;

package/lib/cjs/session/navigation/error/ServerSideNavigationError.js

@@ -0,0 +1,21 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _getLocationUrl = _interopRequireDefault(require("../../../getLocationUrl"));
+const _excluded = ["operation"];
+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; }
+class ServerSideNavigationError extends Error {
+  constructor(location) {
+    super(location ? `Navigate to ${(0, _getLocationUrl.default)(location)}` : 'Navigate to previous or next location');
+    if (location) {
+      // Remove `operation` property from `location`.
+      // eslint-disable-next-line no-unused-vars
+      const locationBase = _objectWithoutPropertiesLoose(location, _excluded);
+      this.location = locationBase;
+    }
+  }
+}
+exports.default = ServerSideNavigationError;
+module.exports = exports.default;

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

@@ -0,0 +1,11 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _default = exports.default = {
+  INIT: 'INIT',
+  PUSH: 'PUSH',
+  REPLACE: 'REPLACE',
+  SHIFT: 'SHIFT'
+};
+module.exports = exports.default;

package/lib/cjs/session/subscription/Subscription.js

@@ -0,0 +1,81 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+class Subscription {
+  constructor({
+    activateSubscription
+  } = {}) {
+    this.notifySubscribers = argument => {
+      // `._latest` is only used in tests.
+      this._latest = argument;
+      for (const {
+        listener
+      } of this._listeners) {
+        listener(argument);
+      }
+    };
+    this._activateSubscription = activateSubscription;
+
+    // This property is accessed in tests.
+    this._listeners = [];
+  }
+  subscribe(listener) {
+    // If subscriptions are stopped, i.e. no new subscriptions are to be added,
+    // then don't add any listeners and return a "do nothing" function.
+    if (this._stopped) {
+      return () => {};
+    }
+
+    // Creating a `listenerEntry` object ensures that the `.filter()` function
+    // during "unsubscribe" step doesn't accidentally remove another listeners
+    // having the same `listener` function.
+    // I.e. it's not illegal to call `.subscribe(listener)` multiple times
+    // with the same argument, and those would be considered different subscriptions.
+    const listenerEntry = {
+      listener
+    };
+
+    // If it's the first listener, activate subscription.
+    if (this._listeners.length === 0) {
+      this._deactivateSubscription = this._activateSubscription(this.notifySubscribers);
+    }
+
+    // Add the `listener` to the list.
+    this._listeners.push(listenerEntry);
+
+    // The returned `unsubscribe()` function is "idempotent", i.e. it can be called multiple times.
+    return () => {
+      // Remove the listener, if not already removed.
+      this._removeListener(listenerEntry);
+    };
+  }
+  stop() {
+    if (this._stopped) {
+      throw new Error('Already stopped');
+    }
+    this._stopped = true;
+
+    // Clear any remaining listeners.
+    for (const listener of this._listeners.slice()) {
+      this._removeListener(listener);
+    }
+  }
+  _removeListener(listenerEntry) {
+    // If no listeners are left, no need to do anything.
+    if (this._listeners.length === 0) {
+      return;
+    }
+
+    // Remove the `listener` from the list.
+    this._listeners = this._listeners.filter(_ => _ !== listenerEntry);
+
+    // If it was the last listener, deactivate subscription.
+    if (this._listeners.length === 0) {
+      this._deactivateSubscription();
+      this._deactivateSubscription = undefined;
+    }
+  }
+}
+exports.default = Subscription;
+module.exports = exports.default;

package/lib/data-storage/index.d.ts

@@ -0,0 +1,35 @@
+// TypeScript Version: 3.0
+
+import { Session } from '../index.d.js';
+
+export {};
+
+export type GenericValue =
+  | string
+  | number
+  | boolean
+  | Record<string, unknown>
+  | null
+  | undefined;
+
+export class DataStorage<
+  Key extends string = string,
+  Value extends GenericValue = GenericValue,
+> {
+  constructor(session: Session, options: { namespace: string });
+
+  get(key: Key): Value;
+
+  set(key: Key, value: Value): void;
+}
+
+export class LocationDataStorage<
+  Key extends string = string,
+  Value extends GenericValue = GenericValue,
+> {
+  constructor(session: Session, options: { namespace: string });
+
+  get(location: Location, key: Key): Value;
+
+  set(location: Location, key: Key, value: Value): void;
+}

package/lib/esm/NavigationStack.js

@@ -0,0 +1,66 @@
+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';
+export default class NavigationStack {
+  constructor(session, options) {
+    this._session = session;
+
+    // Create a Redux store.
+    this._store = createStore(locationReducer, applyMiddleware(...createMiddlewares(session, options)));
+
+    // Create `ScrollPositionRestoration`.
+    if (options && options.maintainScrollPosition) {
+      this._scrollPositionRestoration = new ScrollPositionRestoration(session);
+    }
+  }
+  addScrollableContainer(scrollableContainerKey, scrollableContainer) {
+    if (!this._scrollPositionRestoration) {
+      throw new Error('`maintainScrollPosition: true` option not passed');
+    }
+    return this._scrollPositionRestoration.addScrollableContainer(scrollableContainerKey, scrollableContainer);
+  }
+  subscribe(listener) {
+    // Subscribe to any potential Redux state changes.
+    return this._store.subscribe(() => {
+      // Initially, calls the listener when setting the initial location.
+      // After that, calls it on any location change.
+      const location = this.current();
+      if (!this._latestLocation || location !== this._latestLocation) {
+        this._latestLocation = location;
+        listener(location);
+      }
+    });
+  }
+  init(initialLocation) {
+    if (this._latestLocation) {
+      throw new Error('Already initialized');
+    }
+    this._store.dispatch(Actions.init(initialLocation));
+    this._latestLocation = this.current();
+  }
+  current() {
+    return this._store.getState();
+  }
+  push(location) {
+    this._store.dispatch(Actions.push(location));
+  }
+  replace(location) {
+    this._store.dispatch(Actions.replace(location));
+  }
+  shift(delta) {
+    this._store.dispatch(Actions.shift(delta));
+  }
+  stop() {
+    if (this._scrollPositionRestoration) {
+      this._scrollPositionRestoration.stop();
+    }
+    this._store.dispatch(Actions.stop());
+  }
+  locationRendered() {
+    if (this._scrollPositionRestoration) {
+      this._scrollPositionRestoration.locationRendered(this.current());
+    }
+  }
+}

package/lib/esm/data-storage/DataStorage.js

@@ -0,0 +1,65 @@
+export default class DataStorage {
+  constructor(session, {
+    namespace
+  }) {
+    if (!session.key) {
+      throw new Error('`DataStorage` requires a `session.key`');
+    }
+    this._sessionKey = session.key;
+    this._dataStorage = session.environment.dataStorage;
+    this._namespace = namespace;
+  }
+  get(key) {
+    const storageKey = this._getStorageKey(key);
+    try {
+      const value = this._dataStorage.get(storageKey);
+      // === null is probably sufficient.
+      if (value === null) {
+        return undefined;
+      }
+
+      // We want to catch JSON parse errors in case someone separately threw
+      // junk into sessionStorage under our namespace.
+      return JSON.parse(value);
+    } catch (error) {
+      // eslint-disable-next-line no-console
+      console.error('[navigation-stack] Could not read data from storage');
+
+      // Pretend that the entry doesn't exist.
+      return undefined;
+    }
+  }
+  set(key, value) {
+    const storageKey = this._getStorageKey(key);
+    if (value === undefined) {
+      try {
+        this._dataStorage.remove(storageKey);
+      } catch (error) {
+        // No need to handle errors here.
+        // eslint-disable-next-line no-console
+        console.error('[navigation-stack] Could not delete data from storage');
+      }
+      return;
+    }
+
+    // Unlike with read, we want to fail on invalid values here, since the
+    // value here is provided by the caller of this method.
+    const valueString = JSON.stringify(value);
+    try {
+      this._dataStorage.set(storageKey, valueString);
+    } catch (error) {
+      // No need to handle errors here either. If it didn't work, it didn't
+      // work. We make no guarantees about actually saving the value.
+      // eslint-disable-next-line no-console
+      console.error('[navigation-stack] Could not save data in storage');
+    }
+  }
+
+  // It could also implement a method that would clean up any data written so far,
+  // but so far it doesn't seem to be required by any real-world use case.
+  // cleanUp() {}
+
+  _getStorageKey(key) {
+    return `${this._sessionKey}|${this.namespace}|${key}`;
+  }
+}

package/lib/esm/data-storage/LocationDataStorage.js

@@ -0,0 +1,22 @@
+import DataStorage from './DataStorage';
+import getLocationUrl from '../getLocationUrl';
+export default class LocationDataStorage {
+  constructor(session, {
+    namespace
+  }) {
+    this._storage = new DataStorage(session, {
+      namespace
+    });
+    this._getFallbackLocationKey = getLocationUrl;
+  }
+  get(location, key) {
+    return this._storage.get(this._getKey(location, key));
+  }
+  set(location, key, value) {
+    this._storage.set(this._getKey(location, key), value);
+  }
+  _getKey(location, key) {
+    const locationKey = location.key || this._getFallbackLocationKey(location);
+    return `${locationKey}|${key}`;
+  }
+}

package/lib/esm/data-storage/index.js

@@ -0,0 +1,2 @@
+export { default as DataStorage } from './DataStorage';
+export { default as LocationDataStorage } from './LocationDataStorage';

package/lib/esm/environment/InMemoryEnvironment.js

@@ -0,0 +1,8 @@
+import InMemoryDataStorage from './data-storage/InMemoryDataStorage';
+import InMemoryScrollPosition from './scroll-position/InMemoryScrollPosition';
+export default class InMemoryEnvironment {
+  constructor() {
+    this.dataStorage = new InMemoryDataStorage();
+    this.scrollPosition = new InMemoryScrollPosition();
+  }
+}

package/lib/esm/environment/WebBrowserEnvironment.js

@@ -0,0 +1,8 @@
+import WebBrowserDataStorage from './data-storage/WebBrowserDataStorage';
+import WebBrowserScrollPosition from './scroll-position/WebBrowserScrollPosition';
+export default class WebBrowserEnvironment {
+  constructor() {
+    this.dataStorage = new WebBrowserDataStorage();
+    this.scrollPosition = new WebBrowserScrollPosition();
+  }
+}

package/lib/esm/environment/data-storage/InMemoryDataStorage.js

@@ -0,0 +1,21 @@
+export default class InMemoryDataStorage {
+  constructor() {
+    this._state = {};
+  }
+
+  // Returns either a `string` value or `null` if the key doesn't exist.
+  get(key) {
+    if (key in this._state) {
+      return this._state[key];
+    }
+    return null;
+  }
+  remove(key) {
+    if (key in this._state) {
+      delete this._state[key];
+    }
+  }
+  set(key, value) {
+    this._state[key] = value;
+  }
+}

package/lib/esm/environment/data-storage/WebBrowserDataStorage.js

@@ -0,0 +1,15 @@
+export default class WebBrowserDataStorage {
+  // Returns either a `string` value or `null` if the key doesn't exist.
+  get(key) {
+    // `sessionStorage` persists across page reloads, and so does web browser navigation history.
+    return window.sessionStorage.getItem(key);
+  }
+  remove(key) {
+    // `sessionStorage` persists across page reloads, and so does web browser navigation history.
+    window.sessionStorage.removeItem(key);
+  }
+  set(key, value) {
+    // `sessionStorage` persists across page reloads, and so does web browser navigation history.
+    window.sessionStorage.setItem(key, value);
+  }
+}

package/lib/esm/environment/scroll-position/InMemoryScrollPosition.js

@@ -0,0 +1,38 @@
+export default class InMemoryScrollPosition {
+  constructor() {
+    this.init();
+  }
+  getPageScrollPosition() {
+    return this._pageScrollPosition || [0, 0];
+  }
+  setPageScrollPosition(scrollPosition) {
+    this._pageScrollPosition = scrollPosition;
+  }
+
+  // eslint-disable-next-line no-unused-vars
+  setPageScrollPositionAtAnchor(anchor) {
+    this.setPageScrollPosition([0, 0]);
+  }
+  getScrollableContainerScrollPosition(key) {
+    return this._scrollableContainerScrollPositions[key] || [0, 0];
+  }
+  setScrollableContainerScrollPosition(key, scrollPosition) {
+    this._scrollableContainerScrollPositions[key] = scrollPosition;
+  }
+
+  // eslint-disable-next-line no-unused-vars
+  addPageScrollListener(listener) {
+    return () => {};
+  }
+
+  // eslint-disable-next-line no-unused-vars
+  addScrollableContainerScrollListener(scrollableContainerElement, listener) {
+    return () => {};
+  }
+  enableAutomaticScrollRestoration() {}
+  disableAutomaticScrollRestoration() {}
+  init() {
+    this._pageScrollPosition = undefined;
+    this._scrollableContainerScrollPositions = {};
+  }
+}

package/lib/esm/environment/scroll-position/WebBrowserScrollPosition.js

@@ -0,0 +1,54 @@
+export default class WebBrowserScrollPosition {
+  getPageScrollPosition() {
+    return [window.pageXOffset, window.pageYOffset];
+  }
+  setPageScrollPosition(scrollPosition) {
+    const [scrollX, scrollY] = scrollPosition;
+    window.scrollTo(scrollX, scrollY);
+  }
+  setPageScrollPositionAtAnchor(anchor) {
+    const anchorElement = document.getElementById(anchor) || document.getElementsByName(anchor)[0];
+    if (anchorElement) {
+      // By default it scrolls the element into view
+      // so that it's visible at the top of the window.
+      anchorElement.scrollIntoView();
+    } else {
+      this.setPageScrollPosition([0, 0]);
+    }
+  }
+  getScrollableContainerScrollPosition(scrollableContainerElement) {
+    return [scrollableContainerElement.scrollLeft, scrollableContainerElement.scrollTop];
+  }
+  setScrollableContainerScrollPosition(scrollableContainerElement, scrollPosition) {
+    const [scrollX, scrollY] = scrollPosition;
+    scrollableContainerElement.scrollLeft = scrollX;
+    scrollableContainerElement.scrollTop = scrollY;
+  }
+  addPageScrollListener(listener) {
+    // eslint-disable-next-line no-unused-vars
+    const scrollListener = event => {
+      listener();
+    };
+    window.addEventListener('scroll', scrollListener);
+    return () => {
+      window.removeEventListener('scroll', scrollListener);
+    };
+  }
+  addScrollableContainerScrollListener(scrollableContainerElement, listener) {
+    // eslint-disable-next-line no-unused-vars
+    const scrollListener = event => {
+      listener();
+    };
+    scrollableContainerElement.addEventListener('scroll', scrollListener);
+    return () => {
+      scrollableContainerElement.removeEventListener('scroll', scrollListener);
+    };
+  }
+  enableAutomaticScrollRestoration() {
+    window.history.scrollRestoration = 'auto';
+  }
+  disableAutomaticScrollRestoration() {
+    window.history.scrollRestoration = 'manual';
+  }
+  init() {}
+}

package/lib/esm/getLocationFromInternalLocation.js

@@ -0,0 +1,9 @@
+const _excluded = ["operation", "index", "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`.
+export default function getLocationFromInternalLocation(internalLocation) {
+  // eslint-disable-next-line no-unused-vars
+  const location = _objectWithoutPropertiesLoose(internalLocation, _excluded);
+  return location;
+}

package/lib/esm/index.js

@@ -1,12 +1,14 @@
-export { default as Actions } from './Actions';
-export { default as ActionTypes } from './ActionTypes';
 export { addBasePath, removeBasePath } from './basePath';
 export { default as addNavigationBlocker } from './addNavigationBlocker';
 export { default as getLocationUrl } from './getLocationUrl';
 export { default as parseLocationUrl } from './parseLocationUrl';
-export { default as createMiddlewares } from './createMiddlewares';
-export { default as locationReducer } from './locationReducer';
-export { default as LocationDataStorage } from './LocationDataStorage';
-export { default as BrowserSession } from './session/BrowserSession';
-export { default as MemorySession } from './session/MemorySession';
-export { default as ServerSession } from './session/ServerSession';
+export { default as parseInputLocation } from './parseInputLocation';
+export { default as NavigationStack } from './NavigationStack';
+export { default as DataStorage } from './data-storage/DataStorage';
+export { default as LocationDataStorage } from './data-storage/LocationDataStorage';
+export { default as Session } from './session/Session';
+export { default as InMemorySession } from './session/InMemorySession';
+export { default as WebBrowserSession } from './session/WebBrowserSession';
+export { default as ServerSideRenderSession } from './session/ServerSideRenderSession';
+export { default as ServerSideNavigationError } from './session/navigation/error/ServerSideNavigationError';
+export { default as NavigationOutOfBoundsError } from './session/navigation/error/NavigationOutOfBoundsError';

package/lib/esm/navigationBlockers.js

@@ -16,12 +16,12 @@ function removeNavigationBlockerFromTheList(blocker, session) {
   }
 }
 export function removeAllNavigationBlockers(session) {
-  if (getNavigationBlockers(session).some(blocker => blocker.beforeDestroy)) {
-    if (!session._removeBeforeDestroyListener) {
-      throw new Error('`_removeBeforeDestroyListener` property not found in the `session`');
+  if (getNavigationBlockers(session).some(blocker => blocker.beforeTermination)) {
+    if (!session._removeTerminationBlocker) {
+      throw new Error('`_removeTerminationBlocker` property not found in the `session`');
     }
-    session._removeBeforeDestroyListener();
-    session._removeBeforeDestroyListener = undefined;
+    session._removeTerminationBlocker();
+    session._removeTerminationBlocker = undefined;
   }
   session._navigationBlockersList = [];
 }
@@ -84,33 +84,33 @@ export function runNavigationBlockers(navigationBlockers, toLocation) {
 }
 
 /* istanbul ignore next: not testable with Karma */
-function onBeforeDestroy(session) {
+function terminationBlocker(session) {
   const result = runNavigationBlockers(getNavigationBlockers(session), null);
 
-  // If no blocker returned anything, don't prevent the "unload" event.
+  // If no blocker returned anything, so don't prevent the navigation.
   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" blockers should be ignored.
+  // Hence, "asynchronous" blockers should be ignored because web browsers won't wait for those to finish anyway.
   // https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event
   if (isPromise(result)) {
     return undefined;
   }
 
-  // Prevent the "unload" event.
+  // Block the navigation.
   return true;
 }
 export function addNavigationBlocker(session, blocker) {
-  // All navigation blockers also run on `beforeDestroy` event.
+  // 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
   // disables web page caching in some browsers like Firefox.
-  const beforeDestroy = true;
+  const beforeTermination = true;
 
-  // If it's the first "beforeDestroy" blocker, add the global `onBeforeDestroy` listener.
+  // If it's the first "beforeTermination" blocker, add a `terminationBlocker`.
   //
   // Sidenote: Add the "beforeunload" event listener only as needed, as its presence
   // prevents the page from being added to the page navigation cache:
@@ -120,27 +120,29 @@ export function addNavigationBlocker(session, blocker) {
   //  and this is bad for performance."
   //
   // https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event
-  if (beforeDestroy && !getNavigationBlockers(session).some(navigationBlocker => navigationBlocker.beforeDestroy)) {
-    if (session._removeBeforeDestroyListener) {
-      throw new Error('Unexpected `_removeBeforeDestroyListener` property found in the `session`');
+  if (beforeTermination && !getNavigationBlockers(session).some(navigationBlocker => navigationBlocker.beforeTermination)) {
+    if (session._removeTerminationBlocker) {
+      throw new Error('Unexpected `_removeTerminationBlocker` property found in the `session`');
     }
-    session._removeBeforeDestroyListener = session.addBeforeDestroyListener(() => onBeforeDestroy(session));
+    session._removeTerminationBlocker = session.lifecycle.addTerminationBlocker(() => {
+      return terminationBlocker(session);
+    });
   }
   const newNavigationBlocker = {
     blocker,
-    beforeDestroy
+    beforeTermination
   };
   addNavigationBlockerToTheList(newNavigationBlocker, session);
   return () => {
     removeNavigationBlockerFromTheList(newNavigationBlocker, session);
 
-    // If it was the last "beforeDestroy" blocker, remove the global `onBeforeDestroy` listener.
-    if (beforeDestroy && !getNavigationBlockers(session).some(navigationBlocker => navigationBlocker.beforeDestroy)) {
-      if (!session._removeBeforeDestroyListener) {
-        throw new Error('`_removeBeforeDestroyListener` property not found in the `session`');
+    // If it was the last "beforeTermination" blocker, remove navigation blocker.
+    if (beforeTermination && !getNavigationBlockers(session).some(navigationBlocker => navigationBlocker.beforeTermination)) {
+      if (!session._removeTerminationBlocker) {
+        throw new Error('`_removeTerminationBlocker` property not found in the `session`');
       }
-      session._removeBeforeDestroyListener();
-      session._removeBeforeDestroyListener = undefined;
+      session._removeTerminationBlocker();
+      session._removeTerminationBlocker = undefined;
     }
   };
 }

package/lib/esm/{normalizeInputLocation.js → parseInputLocation.js}

@@ -2,10 +2,10 @@ import createSearchFromQuery from './createSearchFromQuery';
 import parseLocationUrl from './parseLocationUrl';
 import parseQueryFromSearch from './parseQueryFromSearch';
 
-// * If `location` is a string, it parses it into a `NormalizedInputLocation`.
+// * If `location` is a string, it parses it into a `LocationBase`.
 // * If `location` is an object, it ensures that `search` and `hash` properties aren't `undefined`,
-//   i.e. it "ensures" that the `location` object can be used as a `NormalizedInputLocation`.
-export default function normalizeInputLocation(location) {
+//   i.e. it "ensures" that the `location` object can be used as a `LocationBase`.
+export default function parseInputLocation(location) {
   if (typeof location === 'string') {
     return parseLocationUrl(location);
   }
@@ -13,7 +13,13 @@ export default function normalizeInputLocation(location) {
   // Convert `query` property values to strings.
   if (location.query) {
     for (const key of Object.keys(location.query)) {
-      location.query[key] = String(location.query[key]);
+      if (typeof location.query[key] !== 'string') {
+        location = Object.assign({}, location, {
+          query: Object.assign({}, location.query, {
+            [key]: String(location.query[key])
+          })
+        });
+      }
     }
   }
 
@@ -32,11 +38,21 @@ export default function normalizeInputLocation(location) {
     });
   }
 
-  // Set default values on `search` and `hash`
-  // if those properties are not present.
-  return Object.assign({}, location, {
+  // Set default values for properties that're not present.
+  // Ignore unknown properties.
+  const {
+    state
+  } = location;
+  location = {
+    pathname: location.pathname,
     query: location.query || {},
     search: location.search || '',
     hash: location.hash || ''
-  });
+  };
+  if (state) {
+    location.state = state;
+  }
+
+  // Return `location`.
+  return location;
 }