navigation-stack 0.1.0

package/lib/cjs/createMiddlewares.js

@@ -0,0 +1,43 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = createMiddlewares;
+var _createBasePathMiddleware = _interopRequireDefault(require("./middleware/createBasePathMiddleware"));
+var _createEnvironmentMiddleware = _interopRequireDefault(require("./middleware/createEnvironmentMiddleware"));
+var _createNavigationBlockerMiddleware = _interopRequireDefault(require("./middleware/createNavigationBlockerMiddleware"));
+var _navigationActionMiddleware = _interopRequireDefault(require("./middleware/navigationActionMiddleware"));
+var _normalizeInputLocationMiddleware = _interopRequireDefault(require("./middleware/normalizeInputLocationMiddleware"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+function createMiddlewares(environment, options) {
+  // Allows temporarily ignoring certain environment location updates.
+  let shouldIgnoreEnvironmentLocationUpdates = false;
+  const ignoreEnvironmentLocationUpdates = func => {
+    shouldIgnoreEnvironmentLocationUpdates = true;
+    func();
+    shouldIgnoreEnvironmentLocationUpdates = false;
+  };
+  return [
+  // Validates that the action "payload" (input location) is a proper `NormalizedInputLocation`.
+  _normalizeInputLocationMiddleware.default,
+  // Transforms a "PUSH" / "REPLACE" action into a "NAVIGATE" action.
+  _navigationActionMiddleware.default,
+  // 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.
+  (0, _createBasePathMiddleware.default)(options && options.basePath),
+  // Allows blocking navigation.
+  // Handles `NAVIGATE` actions dispatched by the application itself.
+  (0, _createNavigationBlockerMiddleware.default)(environment, {
+    ignoreEnvironmentLocationUpdates
+  }),
+  // This "middleware" performs the actual navigation according to the `environment` being used.
+  // For example, when `BrowserEnvironment` is used, it calls methods of the `history` object.
+  (0, _createEnvironmentMiddleware.default)(environment, {
+    shouldIgnoreEnvironmentLocationUpdates: () => shouldIgnoreEnvironmentLocationUpdates
+  }),
+  // Allows blocking navigation.
+  // Handles location `UPDATE` actions dispatched by the environment.
+  (0, _createNavigationBlockerMiddleware.default)(environment, {
+    ignoreEnvironmentLocationUpdates
+  })];
+}
+module.exports = exports.default;

package/lib/cjs/createSearchFromQuery.js

@@ -0,0 +1,13 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = createSearchFromQuery;
+var _queryString = require("query-string");
+function createSearchFromQuery(query) {
+  const queryString = (0, _queryString.stringify)(query);
+  if (queryString) {
+    return `?${queryString}`;
+  }
+  return undefined;
+}
+module.exports = exports.default;

package/lib/cjs/environment/BrowserEnvironment.js

@@ -0,0 +1,111 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _getLocationUrl = _interopRequireDefault(require("../getLocationUrl"));
+var _parseQueryFromSearch = _interopRequireDefault(require("../parseQueryFromSearch"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+class BrowserEnvironment {
+  constructor() {
+    this._keyPrefix = Math.random().toString(36).slice(2, 8);
+    this._keyIndex = 0;
+    this._index = null;
+  }
+  init() {
+    const {
+      pathname,
+      search,
+      hash
+    } = window.location;
+    const {
+      key,
+      index = 0,
+      state
+    } = window.history.state || {};
+    const delta = this._index != null ? index - this._index : 0;
+    this._index = index;
+    return {
+      action: 'POP',
+      pathname,
+      search,
+      query: search && (0, _parseQueryFromSearch.default)(search),
+      hash,
+      key,
+      index,
+      delta,
+      state
+    };
+  }
+
+  // Subscribes to changes in location,
+  // excluding ones that happened as a result of calling `.navigate()`.
+  subscribe(listener) {
+    const onPopState = () => {
+      listener(this.init());
+    };
+    window.addEventListener('popstate', onPopState);
+    return () => {
+      window.removeEventListener('popstate', onPopState);
+    };
+  }
+  navigate(location) {
+    const {
+      action,
+      state
+    } = location;
+    const push = action === 'PUSH';
+    if (!push && action !== 'REPLACE') {
+      throw Error(`Unrecognized browser environment action: ${action}`);
+    }
+    const delta = push ? 1 : 0;
+    const extraState = this._createExtraState(delta);
+    const browserState = Object.assign({
+      state
+    }, extraState);
+    const url = (0, _getLocationUrl.default)(location);
+    if (push) {
+      window.history.pushState(browserState, null, url);
+    } else {
+      window.history.replaceState(browserState, null, url);
+    }
+    return Object.assign({}, location, extraState, {
+      delta
+    });
+  }
+  shift(delta) {
+    window.history.go(delta);
+  }
+  addBeforeDestroyListener(onBeforeDestroy) {
+    const onBeforeUnload = event => {
+      if (onBeforeDestroy()) {
+        event.preventDefault();
+      }
+    };
+    window.addEventListener('beforeunload', onBeforeUnload);
+    return () => {
+      window.removeEventListener('beforeunload', onBeforeUnload);
+    };
+  }
+  _createExtraState(delta) {
+    const keyIndex = this._keyIndex++;
+    this._index += delta;
+    return {
+      key: `${this._keyPrefix}:${keyIndex.toString(36)}`,
+      index: this._index
+    };
+  }
+
+  // Returns either a `string` value or `null` if the key doesn't exist.
+  getState(key) {
+    // FYI: `sessionStorage` persists across page reloads.
+    return window.sessionStorage.getItem(key);
+  }
+  removeState(key) {
+    window.sessionStorage.removeItem(key);
+  }
+  setState(key, value) {
+    window.sessionStorage.setItem(key, value);
+  }
+}
+exports.default = BrowserEnvironment;
+module.exports = exports.default;

package/lib/cjs/environment/MemoryEnvironment.js

@@ -0,0 +1,150 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _normalizeInputLocation = _interopRequireDefault(require("../normalizeInputLocation"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+class MemoryEnvironment {
+  constructor(initialLocation, {
+    save,
+    load
+  } = {}) {
+    this._save = save;
+    this._load = load;
+    const initialState = load ? this._loadState() : null;
+    if (initialState) {
+      this._stack = initialState.stack;
+      this._index = initialState.index;
+      this._state = initialState.state;
+    } else {
+      this._stack = [(0, _normalizeInputLocation.default)(initialLocation)];
+      this._index = 0;
+      this._state = {};
+    }
+    this._keyPrefix = Math.random().toString(36).slice(2, 8);
+    this._keyIndex = 0;
+    this._listener = null;
+  }
+  _loadState() {
+    try {
+      const {
+        stack,
+        index,
+        state
+      } = JSON.parse(this._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 (Array.isArray(stack) && typeof index === 'number' && stack[index] && typeof state === 'object' && state !== null) {
+        return {
+          stack,
+          index,
+          state
+        };
+      }
+    } catch (error) {} // eslint-disable-line no-empty
+
+    return null;
+  }
+  init(delta = 0) {
+    return Object.assign({}, this._stack[this._index], {
+      action: 'POP',
+      index: this._index,
+      delta
+    });
+  }
+  subscribe(listener) {
+    this._listener = listener;
+    return () => {
+      this._listener = null;
+    };
+  }
+  navigate(location) {
+    const {
+      action,
+      pathname,
+      search,
+      query,
+      hash,
+      state
+    } = location;
+    const push = action === 'PUSH';
+    if (!push && action !== 'REPLACE') throw Error(`Unrecognized browser environment action: ${action}`);
+    const delta = push ? 1 : 0;
+    this._index += delta;
+    const keyIndex = this._keyIndex++;
+    const key = `${this._keyPrefix}:${keyIndex.toString(36)}`;
+    this._stack[this._index] = {
+      pathname,
+      search,
+      query,
+      hash,
+      state,
+      key
+    };
+    if (push) {
+      this._stack.length = this._index + 1;
+    }
+    if (this._save) {
+      this._saveState();
+    }
+    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) {
+      this._saveState();
+    }
+    if (this._listener) {
+      this._listener(this.init(this._index - prevIndex));
+    }
+  }
+
+  // "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(listener) {
+    return () => {
+      this._removeBeforeDestroyListener(listener);
+    };
+  }
+
+  // This method is used in tests.
+  _removeBeforeDestroyListener() {}
+  _saveState() {
+    try {
+      this._save(JSON.stringify({
+        stack: this._stack,
+        index: this._index,
+        state: this._state
+      }));
+    } catch (error) {} // eslint-disable-line no-empty
+  }
+
+  // Returns either a `string` value or `null` if the key doesn't exist.
+  getState(key) {
+    if (key in this._state) {
+      return this._state[key];
+    }
+    return null;
+  }
+  removeState(key) {
+    if (key in this._state) {
+      delete this._state[key];
+    }
+  }
+  setState(key, value) {
+    this._state[key] = value;
+  }
+}
+exports.default = MemoryEnvironment;
+module.exports = exports.default;

package/lib/cjs/environment/ServerEnvironment.js

@@ -0,0 +1,53 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _normalizeInputLocation = _interopRequireDefault(require("../normalizeInputLocation"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+function noop() {}
+function serverSideNavigationNotPossible() {
+  throw new Error('Server-side navigation is not possible');
+}
+class ServerEnvironment {
+  constructor(initialLocation) {
+    this._location = (0, _normalizeInputLocation.default)(initialLocation);
+  }
+  init() {
+    return Object.assign({
+      action: 'POP'
+    }, this._location);
+  }
+  subscribe() {
+    // Server environment emits no location events.
+    return noop;
+  }
+
+  // Navigation methods are not implemented, because `ServerPEnvironment` instances
+  // cannot navigate.
+  navigate() {
+    serverSideNavigationNotPossible();
+  }
+
+  // Navigation methods are not implemented, because `ServerEnvironment` instances
+  // cannot navigate.
+  shift() {
+    serverSideNavigationNotPossible();
+  }
+
+  // "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 () => {};
+  }
+
+  // It doesn't seem to make any sense to store anything on server side.
+  // Hence, state management methods are "no op" stubs.
+  getState() {
+    return null;
+  }
+  removeState() {}
+  setState() {}
+}
+exports.default = ServerEnvironment;
+module.exports = exports.default;

package/lib/cjs/getLocationUrl.js

@@ -0,0 +1,20 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = getLocationUrl;
+var _queryString = require("query-string");
+function getLocationUrl({
+  pathname,
+  search,
+  query,
+  hash
+}) {
+  if (!search && query) {
+    const queryString = (0, _queryString.stringify)(query);
+    if (queryString) {
+      search = `?${queryString}`;
+    }
+  }
+  return `${pathname}${search || ''}${hash || ''}`;
+}
+module.exports = exports.default;

package/lib/cjs/index.js

@@ -0,0 +1,30 @@
+"use strict";
+
+exports.__esModule = true;
+exports.removeBasePath = exports.parseLocationUrl = exports.locationReducer = exports.getLocationUrl = exports.createMiddlewares = exports.addNavigationBlocker = exports.addBasePath = exports.ServerEnvironment = exports.MemoryEnvironment = exports.LocationStateStorage = exports.BrowserEnvironment = exports.Actions = exports.ActionTypes = void 0;
+var _Actions = _interopRequireDefault(require("./Actions"));
+exports.Actions = _Actions.default;
+var _ActionTypes = _interopRequireDefault(require("./ActionTypes"));
+exports.ActionTypes = _ActionTypes.default;
+var _basePath = require("./basePath");
+exports.addBasePath = _basePath.addBasePath;
+exports.removeBasePath = _basePath.removeBasePath;
+var _addNavigationBlocker = _interopRequireDefault(require("./addNavigationBlocker"));
+exports.addNavigationBlocker = _addNavigationBlocker.default;
+var _getLocationUrl = _interopRequireDefault(require("./getLocationUrl"));
+exports.getLocationUrl = _getLocationUrl.default;
+var _parseLocationUrl = _interopRequireDefault(require("./parseLocationUrl"));
+exports.parseLocationUrl = _parseLocationUrl.default;
+var _createMiddlewares = _interopRequireDefault(require("./createMiddlewares"));
+exports.createMiddlewares = _createMiddlewares.default;
+var _locationReducer = _interopRequireDefault(require("./locationReducer"));
+exports.locationReducer = _locationReducer.default;
+var _LocationStateStorage = _interopRequireDefault(require("./LocationStateStorage"));
+exports.LocationStateStorage = _LocationStateStorage.default;
+var _BrowserEnvironment = _interopRequireDefault(require("./environment/BrowserEnvironment"));
+exports.BrowserEnvironment = _BrowserEnvironment.default;
+var _MemoryEnvironment = _interopRequireDefault(require("./environment/MemoryEnvironment"));
+exports.MemoryEnvironment = _MemoryEnvironment.default;
+var _ServerEnvironment = _interopRequireDefault(require("./environment/ServerEnvironment"));
+exports.ServerEnvironment = _ServerEnvironment.default;
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }

package/lib/cjs/isPromise.js

@@ -0,0 +1,9 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = isPromise;
+function isPromise(anything) {
+  // Weirdly, `typeof null` is "object".
+  return typeof anything === 'object' && anything !== null && typeof anything.then === 'function';
+}
+module.exports = exports.default;

package/lib/cjs/locationReducer.js

@@ -0,0 +1,13 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = locationReducer;
+var _ActionTypes = _interopRequireDefault(require("./ActionTypes"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+function locationReducer(state, action) {
+  if (action.type === _ActionTypes.default.UPDATE) {
+    return action.payload;
+  }
+  return state;
+}
+module.exports = exports.default;

package/lib/cjs/middleware/createBasePathMiddleware.js

@@ -0,0 +1,24 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = createBasePathMiddleware;
+var _basePath = require("../basePath");
+var _createTransformLocationMiddleware = _interopRequireDefault(require("./createTransformLocationMiddleware"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+// 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.
+function createBasePathMiddleware(basePath) {
+  return (0, _createTransformLocationMiddleware.default)({
+    // Transforms input `Location`:
+    // prepends `basePath` to the URL.
+    transformInputLocation: location => {
+      return (0, _basePath.addBasePath)(location, basePath);
+    },
+    // Transforms environment `Location` object:
+    // removes `basePath` from the URL.
+    transformEnvironmentLocation: location => {
+      return (0, _basePath.removeBasePath)(location, basePath);
+    }
+  });
+}
+module.exports = exports.default;

package/lib/cjs/middleware/createEnvironmentMiddleware.js

@@ -0,0 +1,58 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = createEnvironmentMiddleware;
+var _ActionTypes = _interopRequireDefault(require("../ActionTypes"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+function updateLocation(location) {
+  return {
+    type: _ActionTypes.default.UPDATE,
+    payload: location
+  };
+}
+
+// Creates a "middleware" that performs the actual navigation according to the `environment` being used.
+// For example, when `BrowserProtocol` is used, it calls methods of the `history` object.
+// A better name for this function could be something like `createProtocolMiddleware(environment)`.
+// A better name for "environment" could be something like "environment".
+function createEnvironmentMiddleware(environment, {
+  shouldIgnoreEnvironmentLocationUpdates
+}) {
+  return function environmentMiddleware() {
+    return next => {
+      // Whenever browser location changes,
+      // perform the same changes with the internal `location` object.
+      const unsubscribe = environment.subscribe(location => {
+        if (!shouldIgnoreEnvironmentLocationUpdates()) {
+          next(updateLocation(location));
+        }
+      });
+      return action => {
+        const {
+          type,
+          payload
+        } = action;
+        switch (type) {
+          case _ActionTypes.default.INIT:
+            return next(updateLocation(environment.init()));
+          case _ActionTypes.default.NAVIGATE:
+            // `environment.navigate()` doesn't trigger the `subscribe()` listener.
+            return next(updateLocation(environment.navigate(payload)));
+          case _ActionTypes.default.SHIFT:
+            // `shift()` will trigger the `subscribe()` listener,
+            // which will call `updateLocation()`.
+            environment.shift(payload);
+            // eslint-disable-next-line consistent-return
+            return;
+          case _ActionTypes.default.DISPOSE:
+            unsubscribe();
+            // eslint-disable-next-line consistent-return
+            return;
+          default:
+            return next(action);
+        }
+      };
+    };
+  };
+}
+module.exports = exports.default;

package/lib/cjs/middleware/createNavigationBlockerMiddleware.js

@@ -0,0 +1,128 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = createNavigationBlockerMiddleware;
+var _ActionTypes = _interopRequireDefault(require("../ActionTypes"));
+var _isPromise = _interopRequireDefault(require("../isPromise"));
+var _navigationBlockers = require("../navigationBlockers");
+var _onlyAllowedOnClientSide = _interopRequireDefault(require("../onlyAllowedOnClientSide"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+// Creates a "middleware" that applies navigation blockers.
+function createNavigationBlockerMiddleware(environment, {
+  ignoreEnvironmentLocationUpdates
+}) {
+  // A "dummy" initial value that will be ignored.
+  let navigationBlockersEvaluationStatus = {
+    cancelled: false
+  };
+  function createNavigationBlockersEvaluationStatus() {
+    (0, _onlyAllowedOnClientSide.default)();
+    navigationBlockersEvaluationStatus.cancelled = true;
+    navigationBlockersEvaluationStatus = {
+      cancelled: false
+    };
+    return navigationBlockersEvaluationStatus;
+  }
+  return function navigationListenerMiddleware() {
+    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.
+        case _ActionTypes.default.NAVIGATE:
+          // `resultValue` variable name works around a stupid javascript error:
+          // "Cannot redeclare block-scoped variable 'result'".
+          result = (0, _navigationBlockers.runNavigationBlockers)((0, _navigationBlockers.getNavigationBlockers)(), payload);
+          if ((0, _isPromise.default)(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;
+
+        // Prevent or allow navigation that was initiated by the environment itself.
+        // For example, in a web browser, it could happen when the user clicks the "Back"/"Forward" buttons.
+        //
+        // In this scenario, the web browser is already at the new location, i.e. the navigation has already happened.
+        // It could be "prevented" by rewinding back to the previous location.
+        //
+        case _ActionTypes.default.UPDATE:
+          // If no navigation blockers to run, don't do anything.
+          if ((0, _navigationBlockers.getNavigationBlockers)().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 environment.
+          // So this case is not something that's supposed to happen in real life.
+          // Rather, it's a guard against an unsupported or incorrectly-implemented environment 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 = (0, _navigationBlockers.runNavigationBlockers)((0, _navigationBlockers.getNavigationBlockers)(), payload);
+          if ((0, _isPromise.default)(result)) {
+            const status = createNavigationBlockersEvaluationStatus();
+
+            // While location blockers are running, rewind to the previous location.
+            ignoreEnvironmentLocationUpdates(() => {
+              environment.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.
+                ignoreEnvironmentLocationUpdates(() => {
+                  environment.shift(payload.delta);
+                });
+                // Update the location.
+                next(action);
+              }
+            });
+          } else if (result) {
+            // Prevent the navigation: rewind to the previous location.
+            ignoreEnvironmentLocationUpdates(() => {
+              environment.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.default.DISPOSE:
+          (0, _navigationBlockers.removeAllNavigationBlockers)();
+          return next(action);
+        default:
+          return next(action);
+      }
+    };
+  };
+}
+module.exports = exports.default;