navigation-stack 0.3.0 → 0.4.0

package/lib/esm/middleware/createBeforeLocationChangeListenerMiddleware.js

@@ -1,34 +0,0 @@
-import ActionTypes from '../ActionTypes';
-import { getBeforeLocationChangeListeners, removeAllBeforeLocationChangeListeners, runBeforeLocationChangeListeners } from '../beforeLocationChangeListeners';
-
-// Creates a "middleware" that calls upcoming navigation listeners.
-export default function createBeforeLocationChangeListenerMiddleware(session) {
-  return function navigationListenerMiddleware() {
-    return next => action => {
-      const {
-        type,
-        payload
-      } = action;
-      switch (type) {
-        // Trigger navigation listeners before the `location` has been updated in Redux state.
-        // It doesn't matter that the new location URL has already been updated in the web browser's
-        // address bar, or that the web browser's history has already switched to the new locaiton.
-        // From the application's point of view, all of that doesn't matter and even doesn't exist.
-        // All that exists from the application's point of view is the `location` object in the Redux state.
-        // Until the `location` object in the Redux state is updated, the old page is still rendered.
-        // The appliation is only concerned with the updates of the `location` object in the Redux state
-        // and completely ignores any updates to the URL in the web browser's address bar.
-        case ActionTypes.UPDATE:
-          runBeforeLocationChangeListeners(getBeforeLocationChangeListeners(session), payload);
-          return next(action);
-
-        // Remove any navigation listeners on `DISPOSE` event.
-        case ActionTypes.DISPOSE:
-          removeAllBeforeLocationChangeListeners(session);
-          return next(action);
-        default:
-          return next(action);
-      }
-    };
-  };
-}

package/lib/esm/middleware/createLocationMiddleware.js

@@ -1,50 +0,0 @@
-import ActionTypes from '../ActionTypes';
-function updateLocation(location) {
-  return {
-    type: ActionTypes.UPDATE,
-    payload: location
-  };
-}
-
-// Creates a "middleware" that performs the actual navigation according to the `session` being used.
-// For example, when `BrowserSession` is used, it calls methods of the `window.history` object.
-export default function createLocationMiddleware(session, {
-  shouldIgnoreLocationSubscriptionEvents
-}) {
-  return function locationMiddleware() {
-    return next => {
-      // Whenever browser location changes,
-      // perform the same changes with the internal `location` object.
-      const unsubscribe = session.navigation.subscribe(location => {
-        if (!shouldIgnoreLocationSubscriptionEvents()) {
-          next(updateLocation(location));
-        }
-      });
-      return action => {
-        const {
-          type,
-          payload
-        } = action;
-        switch (type) {
-          case ActionTypes.INIT:
-            return next(updateLocation(session.navigation.init()));
-          case ActionTypes.NAVIGATE:
-            // `session.navigate()` doesn't trigger the `subscribe()` listener.
-            return next(updateLocation(session.navigation.navigate(payload)));
-          case ActionTypes.SHIFT:
-            // `shift()` will trigger the `subscribe()` listener,
-            // which will call `updateLocation()`.
-            session.navigation.shift(payload);
-            // eslint-disable-next-line consistent-return
-            return;
-          case ActionTypes.DISPOSE:
-            unsubscribe();
-            // eslint-disable-next-line consistent-return
-            return;
-          default:
-            return next(action);
-        }
-      };
-    };
-  };
-}

package/lib/esm/middleware/createNavigationBlockerMiddleware.js

@@ -1,156 +0,0 @@
-import ActionTypes from '../ActionTypes';
-import isPromise from '../isPromise';
-import { getNavigationBlockers, removeAllNavigationBlockers, runNavigationBlockers } from '../navigationBlockers';
-
-// Creates a "middleware" that applies navigation blockers.
-export default function createNavigationBlockerMiddleware(session, {
-  ignoreLocationSubscriptionEvents
-}) {
-  function createNavigationBlockersEvaluationStatus() {
-    /* eslint-disable no-underscore-dangle */
-    if (session._navigationBlockersEvaluationStatus) {
-      session._navigationBlockersEvaluationStatus.cancelled = true;
-    }
-    session._navigationBlockersEvaluationStatus = {
-      cancelled: false
-    };
-    return session._navigationBlockersEvaluationStatus;
-  }
-  return function navigationBlockerMiddleware() {
-    return next => action => {
-      const {
-        type,
-        payload
-      } = action;
-
-      // Declaring `result` variable here fixes ESLint error:
-      // "Unexpected lexical declaration in case block".
-      let result;
-      switch (type) {
-        // Prevent or allow navigation that was initiated by the application
-        // by dispatching a `.push()` or `.replace()` action.
-        //
-        // It doesn't handle `.shift()` navigation actions 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 it and rewinds the "shift"
-        // if it should've been blocked. That is handled in the `case ActionTypes.UPDATE` block.
-        //
-        // This type of "shifting" and then rewinding the "shift" doesn't really matter to the application at all.
-        // From the application's point of view, all of that doesn't matter and even doesn't exist.
-        // All that exists from the application's point of view is the `location` object in the Redux state.
-        // Until the `location` object in the Redux state is updated, the old page is still rendered.
-        // The appliation is only concerned with the updates of the `location` object in the Redux state
-        // and completely ignores any updates to the URL in the web browser's address bar.
-        //
-        case ActionTypes.NAVIGATE:
-          // `resultValue` variable name works around a stupid javascript error:
-          // "Cannot redeclare block-scoped variable 'result'".
-          result = runNavigationBlockers(getNavigationBlockers(session), payload);
-          if (isPromise(result)) {
-            const status = createNavigationBlockersEvaluationStatus();
-            // eslint-disable-next-line consistent-return
-            result.then(resultValue => {
-              if (!status.cancelled) {
-                if (!resultValue) {
-                  return next(action);
-                }
-              }
-            });
-          } else if (!result) {
-            return next(action);
-          }
-          // eslint-disable-next-line consistent-return
-          return;
-
-        // One can notice that this "middleware" handles both `NAVIGATE` and `UPDATE` Redux actions,
-        // even though a `NAVIGATE` action normally always causes a follow-up `UPDATE` Redux action.
-        // There's no contradiction here: if a navigation blocker should block a certain navigation,
-        // it will do that at the `NAVIGATION` stage and it won't get to the `UPDATE` stage, so it
-        // won't be called "second time" or something like that.
-        //
-        // One could ask then: Why handle `UPDATE` Redux action at all?
-        // The reason why it handles `UPDATE` Redux actions here is because
-        // `NAVIGATE` Redux actions are only emitted for programmatic "push" or "replace" navigation
-        // initiated by the application code, and there're other cases of navigation such as
-        // programmatic "shift" navigation or when the user manually clicks "Back" or "Forward" button
-        // in a web browser. Such "other" cases could only be handled by reacting to an `UPDATE` Redux action
-        // which is only emitted after the URL in the browser's address bar has changed.
-        //
-        // But there's no real drawback in reacting to an `UPDATE` Redux action "post factum" because
-        // from the application's point of view the address bar doesn't matter and even doesn't exist.
-        // All that exists from the application's point of view is the `location` object in the Redux state.
-        // Until the `location` object in the Redux state is updated, the old page is still rendered.
-        // The appliation is only concerned with the updates of the `location` object in the Redux state
-        // and completely ignores any updates to the URL in the web browser's address bar.
-        //
-        // So here, the "middleware" attempts to prevent or allow navigation that has already happened
-        // in the web browser's address bar but hasn't yet happened in Redux state.
-        // For example, it could be a user clicking a "Back"/"Forward" button in their web browser.
-        // If such navigation should've been blocked, it will simply not update the `locaiton` object in Redux 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 Redux state.
-        //
-        case ActionTypes.UPDATE:
-          // If no navigation blockers to run, don't do anything.
-          if (getNavigationBlockers(session).length === 0) {
-            return next(action);
-          }
-
-          // If it was the initial page load or a redirect,
-          // it's not really a navigation that could be rolled back.
-          if (payload.delta === 0) {
-            return next(action);
-          }
-
-          // It's not really possible for a location to not have a `delta` property in a web browser session.
-          // So this case is not something that's supposed to happen in real life.
-          // Rather, it's a guard against an unsupported or incorrect session implementation or something like that.
-          // If there's no `delta` property on the location, it means that the previous location can't be rewound to,
-          // so it can't really "prevent" the navigation that has just happened.
-          if (payload.delta === null) {
-            return next(action);
-          }
-          result = runNavigationBlockers(getNavigationBlockers(session), payload);
-          if (isPromise(result)) {
-            const status = createNavigationBlockersEvaluationStatus();
-
-            // While location blockers are running, rewind to the previous location.
-            ignoreLocationSubscriptionEvents(() => {
-              session.navigation.shift(-payload.delta);
-            });
-            result.then(promiseResult => {
-              if (promiseResult) {
-                // Navigation blocked.
-                // Already rewound to a previous location.
-              } else if (!status.cancelled) {
-                // Navigation not blocked.
-                // Rewind back to the new location.
-                ignoreLocationSubscriptionEvents(() => {
-                  session.navigation.shift(payload.delta);
-                });
-                // Update the location.
-                next(action);
-              }
-            });
-          } else if (result) {
-            // Prevent the navigation: rewind to the previous location.
-            ignoreLocationSubscriptionEvents(() => {
-              session.navigation.shift(-payload.delta);
-            });
-          } else {
-            // Update the location.
-            return next(action);
-          }
-          // eslint-disable-next-line consistent-return
-          return;
-
-        // Remove any navigation blockers on `DISPOSE` event.
-        case ActionTypes.DISPOSE:
-          removeAllNavigationBlockers(session);
-          return next(action);
-        default:
-          return next(action);
-      }
-    };
-  };
-}

package/lib/esm/middleware/createTransformLocationMiddleware.js

@@ -1,33 +0,0 @@
-import ActionTypes from '../ActionTypes';
-
-// Creates a "middleware" that transforms action payload (location).
-export default function createTransformLocationMiddleware({
-  transformInputLocation,
-  transformSubscriptionLocation
-}) {
-  return function transformLocationMiddleware() {
-    return next => action => {
-      const {
-        type,
-        payload
-      } = action;
-      switch (type) {
-        // Transforms `NAVIGATE` action payload (`location`).
-        case ActionTypes.NAVIGATE:
-          return next({
-            type,
-            payload: transformInputLocation(payload)
-          });
-
-        // Transforms `UPDATE` action payload (input `location`).
-        case ActionTypes.UPDATE:
-          return next({
-            type,
-            payload: transformSubscriptionLocation(payload)
-          });
-        default:
-          return next(action);
-      }
-    };
-  };
-}

package/lib/esm/onlyAllowedOnClientSide.js

@@ -1,5 +0,0 @@
-export default function onlyAllowedOnClientSide() {
-  if (typeof window === 'undefined') {
-    throw new Error('This function can only be called on client side');
-  }
-}

package/lib/esm/session/BrowserSession.js

@@ -1,229 +0,0 @@
-const _excluded = ["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; }
-/* eslint-disable max-classes-per-file */
-
-import getLocationUrl from '../getLocationUrl';
-import parseQueryFromSearch from '../parseQueryFromSearch';
-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: parseQueryFromSearch(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 = getLocationUrl(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);
-  }
-}
-export default 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);
-    };
-  }
-}