navigation-stack 0.3.0 → 0.4.0

package/lib/cjs/session/BrowserSession.js

@@ -1,235 +0,0 @@
-"use strict";
-
-exports.__esModule = true;
-exports.default = void 0;
-var _getLocationUrl = _interopRequireDefault(require("../getLocationUrl"));
-var _parseQueryFromSearch = _interopRequireDefault(require("../parseQueryFromSearch"));
-const _excluded = ["delta"];
-/* eslint-disable max-classes-per-file */
-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; }
-const INITIAL_KEY_INDEX = -1;
-const INITIAL_INDEX = -1;
-const INIT_LOCATION_DELTA = 0;
-
-// A web browser has a notion of a "navigation history".
-// A "navigation history" exists within a given web browser's tab.
-// The user can click "Back" or "Forward" buttons in the web browser and it will automatically load
-// "previous" or "next" page from scratch.
-//
-// Later, web browsers added a `window.history` object that the application can,
-// but isn't required to, interact with. That `window.history` object allows the application
-// to programmatically control the URL in the address bar of the web browser, as well as
-// the "navigation history" by programmatically adding new entries to it or reading the current entry,
-// and it also allows the application to override the default web browser's behavior
-// when the user clicks "Back" or "Forward" buttons in the web browser.
-//
-// Specifically, the `window.history` object has a method called `.pushState()` which programmatically adds
-// a new entry in the "navigation history" and updates the URL in the address bar and also
-// tells the web browser that starting from the entry before this new entry in the "navigation history",
-// the application would prefer to manually handle any "Back"/"Forward" transition when the user clicks
-// those "Back" or "Forward" buttons in the web browser, and this behavior should persist for any future
-// "navigation history" entries programmatically added by the application via `window.history.pushState()`,
-// and will only stop if the user navigates from the page by the means of conventional navigation,
-// that is by clicking a standard hyperlink, at which point the current page gets "destroyed".
-//
-// So for manually "pushed" entries of the "navigation history", the web browser won't load those pages
-// from scratch after a user-initiated "Back" or "Forward" transition. In fact, it won't do anything and
-// it will just step aside and let the application itself do those transitions. The web browser will only
-// update the URL in the address bar and that's it.
-//
-// This whole thing allows the application to:
-//
-// * Load the "previous" or "next" page much faster than when using the default "from scratch" approach
-//   because it doesn't have to destroy the current page, then send a new HTTP request to the server,
-//   then parse the HTML response and initialize a new page, re-download all those images, etc.
-//
-// * Optionally render a snapshotted verison of the "previous" page thereby "restoring" the "previous" page
-//   rather than reloading it from scratch, i.e. the state of the "previous" page could be fully restored.
-//
-class BrowserNavigation {
-  constructor() {
-    // `this._keyPrefix` exists to avoid `this._keyIndex` collision after a page refresh.
-    // After a page refresh, `this._keyIndex` is reset to `0` while the previous navigation history
-    // still exists because web browser navigation history survives a page reload.
-    this._keyPrefix = Date.now().toString(36);
-    // `this._keyIndex` is incremented every time the current location changes.
-    this._keyIndex = INITIAL_KEY_INDEX;
-
-    // `this._index` is the index of the top element in the navigation stack.
-    // I.e. it's the index of the "current" location in the navigation stack.
-    this._index = INITIAL_INDEX;
-  }
-  init() {
-    return this._createEntryFromCurrentLocation('INIT');
-  }
-  _createEntryFromCurrentLocation(action) {
-    const {
-      pathname,
-      search,
-      hash
-    } = window.location;
-    const isSettingInitialLocation = this._index === INITIAL_INDEX;
-    if (action === 'INIT' && !isSettingInitialLocation) {
-      throw Error('Browser session has already been initialized');
-    }
-    if (isSettingInitialLocation && action !== 'INIT') {
-      throw Error('Browser session must be initialized before reacting to location changes');
-    }
-    const {
-      key,
-      index,
-      delta,
-      state
-    } = isSettingInitialLocation ? this._createAdditionalPropertiesForNewLocation({
-      delta: 1,
-      state: undefined
-    }) : this._restoreAdditionalPropertiesForCurrentLocation();
-    return {
-      action,
-      pathname,
-      search,
-      query: (0, _parseQueryFromSearch.default)(search),
-      hash,
-      key,
-      index,
-      delta: isSettingInitialLocation ? INIT_LOCATION_DELTA : delta,
-      state
-    };
-  }
-
-  // Subscribes to changes in location,
-  // excluding ones that happened as a result of calling `.navigate()`.
-  subscribe(listener) {
-    const onPopState = () => {
-      listener(this._createEntryFromCurrentLocation('SHIFT'));
-    };
-    window.addEventListener('popstate', onPopState);
-    return () => {
-      window.removeEventListener('popstate', onPopState);
-    };
-  }
-  navigate(location) {
-    const {
-      action,
-      state
-    } = location;
-    if (action !== 'PUSH' && action !== 'REPLACE') {
-      throw Error(`Unrecognized browser session action: ${action}`);
-    }
-    if (this._index === INITIAL_INDEX) {
-      throw Error('Browser session must be initialized before navigation');
-    }
-    const delta = action === 'PUSH' ? 1 : 0;
-    const additionalProperties = this._createAdditionalPropertiesForNewLocation({
-      delta,
-      state
-    });
-    this._storeAdditionalPropertiesForLocation(location, additionalProperties);
-    return Object.assign({}, location, additionalProperties);
-  }
-  shift(delta) {
-    window.history.go(delta);
-  }
-  _createKeyForKeyIndex(keyIndex) {
-    return `${this._keyPrefix}.${keyIndex.toString(36)}`;
-  }
-  _createAdditionalPropertiesForNewLocation({
-    delta,
-    state
-  }) {
-    this._keyIndex++;
-    this._index += delta;
-    return {
-      key: this._createKeyForKeyIndex(this._keyIndex),
-      index: this._index,
-      delta,
-      state
-    };
-  }
-  _restoreAdditionalPropertiesForCurrentLocation() {
-    // Initial location doesn't have any `window.history.state` assigned to it
-    // because it wasn't navigated to via a `window.history.pushState()` method.
-    // Because of that, the additional properties for the initial location can't be read
-    // from `window.history.state` and have to be reconstructed manually.
-    const {
-      key,
-      index,
-      state
-    } = window.history.state || this._getAdditionalPropertiesForInitialLocation();
-    const delta = index - this._index;
-    this._index = index;
-    return {
-      key,
-      index,
-      delta,
-      state
-    };
-  }
-  _storeAdditionalPropertiesForLocation(location, additionalProperties) {
-    const url = (0, _getLocationUrl.default)(location);
-    // `delta` property is not stored in `window.history.state`
-    // because it is supposed to be recalculated every time when reading from `window.history.state`.
-    const {
-        delta
-      } = additionalProperties,
-      restProperties = _objectWithoutPropertiesLoose(additionalProperties, _excluded);
-    if (delta === 1) {
-      window.history.pushState(restProperties, null, url);
-    } else if (delta === 0) {
-      window.history.replaceState(restProperties, null, url);
-    } else {
-      throw new Error(`Unexpected \`delta\` when storing additional properties for location: ${delta}`);
-    }
-  }
-
-  // Initial location doesn't have any `window.history.state` assigned to it
-  // because it wasn't navigated to via a `window.history.pushState()` method.
-  // Because of that, the additional properties for the initial location can't be read
-  // from `window.history.state` and have to be reconstructed manually.
-  _getAdditionalPropertiesForInitialLocation() {
-    return {
-      key: this._createKeyForKeyIndex(INITIAL_KEY_INDEX + 1),
-      index: INITIAL_INDEX + 1,
-      delta: INIT_LOCATION_DELTA,
-      state: undefined
-    };
-  }
-}
-class BrowserDataStorage {
-  // 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);
-  }
-}
-class BrowserSession {
-  constructor() {
-    this.navigation = new BrowserNavigation();
-    this.dataStorage = new BrowserDataStorage();
-  }
-  addBeforeDestroyListener(onBeforeDestroy) {
-    const onBeforeUnload = event => {
-      if (onBeforeDestroy()) {
-        // Calling `event.preventDefault()` will cause a web browser
-        // to show a generic "Ok"/"Cancel" modal with some generic text:
-        // "Are you sure to leave the current page?".
-        event.preventDefault();
-      }
-    };
-    window.addEventListener('beforeunload', onBeforeUnload);
-    return () => {
-      window.removeEventListener('beforeunload', onBeforeUnload);
-    };
-  }
-}
-exports.default = BrowserSession;
-module.exports = exports.default;

package/lib/cjs/session/MemorySession.js

@@ -1,223 +0,0 @@
-"use strict";
-
-exports.__esModule = true;
-exports.default = void 0;
-var _normalizeInputLocation = _interopRequireDefault(require("../normalizeInputLocation"));
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-/* eslint-disable max-classes-per-file */
-
-// eslint-disable-next-line no-underscore-dangle
-function _loadState(load, isValidLoadedData) {
-  try {
-    const data = JSON.parse(load());
-
-    // Check that the stack and index at least seem reasonable before using
-    // them as state. This isn't foolproof, but it might prevent mistakes.
-    // Also perform a basic validation of `state`.
-    if (isValidLoadedData(data)) {
-      return data;
-    }
-  } catch (error) {} // eslint-disable-line no-empty
-
-  return null;
-}
-
-// eslint-disable-next-line no-underscore-dangle
-function _saveState(save, data) {
-  try {
-    save(JSON.stringify(data));
-  } catch (error) {} // eslint-disable-line no-empty
-}
-class MemoryNavigation {
-  constructor(initialLocation, {
-    save,
-    load
-  } = {}) {
-    this._save = save;
-    this._keyPrefix = Date.now().toString(36);
-    this._keyIndex = 0;
-    this._subscriptionListener = null;
-    const initialState = load ? _loadState(load, this._isValidLoadedData) : null;
-    if (initialState) {
-      this._stack = initialState.stack;
-      this._index = initialState.index;
-    } else {
-      this._stack = [Object.assign({}, (0, _normalizeInputLocation.default)(initialLocation), {
-        key: this._getNextKey()
-      })];
-      this._index = 0;
-    }
-  }
-  _isValidLoadedData({
-    stack,
-    index
-  }) {
-    // Check that the `stack` and `index` at least seem reasonable before using them.
-    // This isn't foolproof, but it might prevent mistakes.
-    return Array.isArray(stack) && typeof index === 'number' && stack[index];
-  }
-  init() {
-    return this._createLocationObject({
-      action: 'INIT',
-      delta: 0
-    });
-  }
-  subscribe(listener) {
-    this._subscriptionListener = listener;
-    return () => {
-      this._subscriptionListener = null;
-    };
-  }
-  navigate(location) {
-    const {
-      action,
-      pathname,
-      search,
-      query,
-      hash,
-      state
-    } = location;
-    if (action !== 'PUSH' && action !== 'REPLACE') {
-      throw Error(`Unrecognized browser session action: ${action}`);
-    }
-    const delta = action === 'PUSH' ? 1 : 0;
-    this._index += delta;
-    const key = this._getNextKey();
-    this._stack[this._index] = {
-      pathname,
-      search,
-      query,
-      hash,
-      state,
-      key
-    };
-    if (action === 'PUSH') {
-      this._stack.length = this._index + 1;
-    }
-    if (this._save) {
-      _saveState(this._save, {
-        stack: this._stack,
-        index: this._index
-      });
-    }
-    return Object.assign({}, location, {
-      key,
-      index: this._index,
-      delta
-    });
-  }
-  shift(delta) {
-    const prevIndex = this._index;
-    this._index = Math.min(Math.max(this._index + delta, 0), this._stack.length - 1);
-    if (this._index === prevIndex) {
-      return;
-    }
-    if (this._save) {
-      _saveState(this._save, {
-        stack: this._stack,
-        index: this._index
-      });
-    }
-    if (this._subscriptionListener) {
-      this._subscriptionListener(this._createLocationObject({
-        action: 'SHIFT',
-        delta: this._index - prevIndex
-      }));
-    }
-  }
-  _getNextKey() {
-    const key = `${this._keyPrefix}.${this._keyIndex.toString(36)}`;
-    this._keyIndex++;
-    return key;
-  }
-  _createLocationObject({
-    action,
-    delta
-  }) {
-    return Object.assign({}, this._stack[this._index], {
-      action,
-      index: this._index,
-      delta
-    });
-  }
-}
-class MemoryDataStorage {
-  constructor({
-    load,
-    save
-  } = {}) {
-    this._save = save;
-    const initialState = load ? _loadState(load, this._isValidLoadedData) : null;
-    if (initialState) {
-      this._state = initialState.state;
-    } else {
-      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];
-    }
-    if (this._save) {
-      _saveState(this._save, {
-        state: this._state
-      });
-    }
-  }
-  set(key, value) {
-    this._state[key] = value;
-    if (this._save) {
-      _saveState(this._save, {
-        state: this._state
-      });
-    }
-  }
-  _isValidLoadedData({
-    state
-  }) {
-    // Perform a basic validation of `state`.
-    return typeof state === 'object' && state !== null;
-  }
-}
-function createNestedStateSaveLoadFunctions({
-  save,
-  load
-}, key) {
-  return {
-    save: save ? data => save(key, data) : undefined,
-    load: load ? () => load(key) : undefined
-  };
-}
-class MemorySession {
-  constructor(initialLocation, {
-    save,
-    load
-  } = {}) {
-    this.navigation = new MemoryNavigation(initialLocation, createNestedStateSaveLoadFunctions({
-      save,
-      load
-    }, 'navigation'));
-    this.dataStorage = new MemoryDataStorage(createNestedStateSaveLoadFunctions({
-      save,
-      load
-    }, 'dataStorage'));
-  }
-
-  // "Before destroy" listeners are currently ignored.
-  // If required, one could implement a `_destroy()` method
-  // and there check that the listeners actually do get called.
-  // eslint-disable-next-line no-unused-vars
-  addBeforeDestroyListener(listener) {
-    return () => {};
-  }
-}
-exports.default = MemorySession;
-module.exports = exports.default;

package/lib/cjs/session/ServerSession.js

@@ -1,65 +0,0 @@
-"use strict";
-
-exports.__esModule = true;
-exports.default = void 0;
-var _normalizeInputLocation = _interopRequireDefault(require("../normalizeInputLocation"));
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-/* eslint-disable max-classes-per-file */
-
-function noop() {}
-function serverSideNavigationNotPossible() {
-  throw new Error('Server-side navigation is not possible');
-}
-class ServerNavigation {
-  constructor(initialLocation) {
-    this._location = (0, _normalizeInputLocation.default)(initialLocation);
-  }
-  init() {
-    return Object.assign({
-      action: 'INIT'
-    }, this._location, {
-      index: 0,
-      key: '0'
-    });
-  }
-  subscribe() {
-    // Server-side environment emits no location subscription events.
-    return noop;
-  }
-
-  // Navigation methods are not implemented, because `ServerSession` instances
-  // cannot navigate.
-  navigate() {
-    serverSideNavigationNotPossible();
-  }
-
-  // Navigation methods are not implemented, because `ServerSession` instances
-  // cannot navigate.
-  shift() {
-    serverSideNavigationNotPossible();
-  }
-}
-class ServerDataStorage {
-  // It doesn't seem to make any sense to store anything on server side.
-  // Hence, state management methods are "no op" stubs.
-  get() {
-    return null;
-  }
-  remove() {}
-  set() {}
-}
-class ServerSession {
-  constructor(initialLocation) {
-    this.navigation = new ServerNavigation(initialLocation);
-    this.dataStorage = new ServerDataStorage();
-  }
-
-  // "Before destroy" listeners are currently ignored.
-  // If required, one could implement a `_destroy()` method
-  // and there check that the listeners actually do get called.
-  addBeforeDestroyListener() {
-    return noop;
-  }
-}
-exports.default = ServerSession;
-module.exports = exports.default;

package/lib/esm/LocationDataStorage.js

@@ -1,53 +0,0 @@
-import getLocationUrl from './getLocationUrl';
-export default class LocationDataStorage {
-  constructor(environment, {
-    namespace
-  } = {}) {
-    this._environment = environment;
-    this._getFallbackLocationKey = getLocationUrl;
-    this._stateKeyPrefix = namespace ? `${namespace}|` : '';
-  }
-  get(location, key) {
-    const stateKey = this._getStateKey(location, key);
-    try {
-      const value = this._environment.dataStorage.get(stateKey);
-      // === 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) {
-      // Pretend that the entry doesn't exist.
-      return undefined;
-    }
-  }
-  set(location, key, value) {
-    const stateKey = this._getStateKey(location, key);
-    if (value === undefined) {
-      try {
-        this._environment.dataStorage.remove(stateKey);
-      } catch (error) {
-        // No need to handle errors here.
-      }
-      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._environment.dataStorage.set(stateKey, 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.
-    }
-  }
-  _getStateKey(location, key) {
-    const locationKey = location.key || this._getFallbackLocationKey(location);
-    const keyPrefix = `${this._stateKeyPrefix}${locationKey}`;
-    return `${keyPrefix}|${key}`;
-  }
-}

package/lib/esm/addBeforeLocationChangeListener.js

@@ -1,2 +0,0 @@
-// eslint-disable-next-line no-restricted-exports
-export { addBeforeLocationChangeListener as default } from './beforeLocationChangeListeners';

package/lib/esm/beforeLocationChangeListeners.js

@@ -1,44 +0,0 @@
-/* eslint-disable no-underscore-dangle */
-
-export function getBeforeLocationChangeListeners(session) {
-  return session._beforeLocationChangeListenersList || [];
-}
-function addBeforeLocationChangeListenerToTheList(listener, session) {
-  if (!session._beforeLocationChangeListenersList) {
-    session._beforeLocationChangeListenersList = [];
-  }
-  session._beforeLocationChangeListenersList.push(listener);
-}
-function removeBeforeLocationChangeListenerFromTheList(listener, session) {
-  if (session._beforeLocationChangeListenersList) {
-    session._beforeLocationChangeListenersList = session._beforeLocationChangeListenersList.filter(_ => _ !== listener);
-  }
-}
-export function removeAllBeforeLocationChangeListeners(session) {
-  session._beforeLocationChangeListenersList = [];
-}
-
-// Runs the `listener` while ignoring any errors that might be thrown by it.
-function runBeforeLocationChangeListener(listener, location) {
-  try {
-    listener(location);
-  } catch (error) {
-    // eslint-disable-next-line no-console
-    console.warn(`Ignoring before location change listener \`${listener.name}\` that failed with \`${error}\`.`);
-    // eslint-disable-next-line no-console
-    console.error(error);
-  }
-}
-
-// Runs all listeners in order.
-export function runBeforeLocationChangeListeners(navigationListeners, toLocation) {
-  for (const listener of navigationListeners) {
-    runBeforeLocationChangeListener(listener, toLocation);
-  }
-}
-export function addBeforeLocationChangeListener(session, listener) {
-  addBeforeLocationChangeListenerToTheList(listener, session);
-  return () => {
-    removeBeforeLocationChangeListenerFromTheList(listener, session);
-  };
-}

package/lib/esm/createMiddlewares.js

@@ -1,41 +0,0 @@
-import createBasePathMiddleware from './middleware/createBasePathMiddleware';
-import createBeforeLocationChangeListenerMiddleware from './middleware/createBeforeLocationChangeListenerMiddleware';
-import createLocationMiddleware from './middleware/createLocationMiddleware';
-import createNavigationBlockerMiddleware from './middleware/createNavigationBlockerMiddleware';
-import navigationActionMiddleware from './middleware/navigationActionMiddleware';
-import normalizeInputLocationMiddleware from './middleware/normalizeInputLocationMiddleware';
-export default function createMiddlewares(session, options) {
-  // Allows temporarily ignoring location update events.
-  let shouldIgnoreLocationSubscriptionEvents = false;
-  const ignoreLocationSubscriptionEvents = func => {
-    shouldIgnoreLocationSubscriptionEvents = true;
-    func();
-    shouldIgnoreLocationSubscriptionEvents = false;
-  };
-  return [
-  // Validates that the action "payload" (input location) is a proper `NormalizedInputLocation`.
-  normalizeInputLocationMiddleware,
-  // Transforms a "PUSH" / "REPLACE" action into a "NAVIGATE" action.
-  navigationActionMiddleware,
-  // If a website is hosted under a certain path (`basePath`)
-  // then this middleware will automatically strip that starting segment from the `pathname` of `location`s.
-  createBasePathMiddleware(options && options.basePath),
-  // Allows blocking navigation.
-  // Handles `NAVIGATE` actions dispatched by the application itself.
-  createNavigationBlockerMiddleware(session, {
-    ignoreLocationSubscriptionEvents
-  }),
-  // This "middleware" performs the actual navigation according to the `session` being used.
-  // For example, when `BrowserSession` is used, it calls methods of the `history` object.
-  createLocationMiddleware(session, {
-    shouldIgnoreLocationSubscriptionEvents: () => shouldIgnoreLocationSubscriptionEvents
-  }),
-  // Allows blocking navigation.
-  // Handles location `UPDATE` actions dispatched in response to location update events.
-  createNavigationBlockerMiddleware(session, {
-    ignoreLocationSubscriptionEvents
-  }),
-  // Allows subscribing to upcoming location changes
-  // before those changes are applied in the `location` object in the state.
-  createBeforeLocationChangeListenerMiddleware(session)];
-}

package/lib/esm/middleware/createBasePathMiddleware.js

@@ -1,19 +0,0 @@
-import { addBasePath, removeBasePath } from '../basePath';
-import createTransformLocationMiddleware from './createTransformLocationMiddleware';
-
-// Creates a "middleware" that, when a website is hosted under a certain path (`basePath`),
-// automatically strips that starting segment from the `pathname` of `location`s.
-export default function createBasePathMiddleware(basePath) {
-  return createTransformLocationMiddleware({
-    // Transforms input `Location`:
-    // prepends `basePath` to the URL.
-    transformInputLocation: location => {
-      return addBasePath(location, basePath);
-    },
-    // Transforms subscription `Location` object:
-    // removes `basePath` from the URL.
-    transformSubscriptionLocation: location => {
-      return removeBasePath(location, basePath);
-    }
-  });
-}