navigation-stack 0.1.0

package/lib/cjs/middleware/createTransformLocationMiddleware.js

@@ -0,0 +1,38 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = createTransformLocationMiddleware;
+var _ActionTypes = _interopRequireDefault(require("../ActionTypes"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+// Creates a "middleware" that transforms action payload (location).
+function createTransformLocationMiddleware({
+  transformInputLocation,
+  transformEnvironmentLocation
+}) {
+  return function transformLocationMiddleware() {
+    return next => action => {
+      const {
+        type,
+        payload
+      } = action;
+      switch (type) {
+        // Transforms `NAVIGATE` action payload (`location`).
+        case _ActionTypes.default.NAVIGATE:
+          return next({
+            type,
+            payload: transformInputLocation(payload)
+          });
+
+        // Transforms `UPDATE` action payload (input `location`).
+        case _ActionTypes.default.UPDATE:
+          return next({
+            type,
+            payload: transformEnvironmentLocation(payload)
+          });
+        default:
+          return next(action);
+      }
+    };
+  };
+}
+module.exports = exports.default;

package/lib/cjs/middleware/navigationActionMiddleware.js

@@ -0,0 +1,37 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = navigationActionMiddleware;
+var _ActionTypes = _interopRequireDefault(require("../ActionTypes"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+// This "middleware" transforms a `PUSH` / `REPLACE` action into a `NAVIGATE` action.
+function navigationActionMiddleware() {
+  return next => action => {
+    const {
+      type,
+      payload
+    } = action;
+    switch (type) {
+      // Converts a `PUSH` action into a `NAVIGATE` action.
+      case _ActionTypes.default.PUSH:
+        return next({
+          type: _ActionTypes.default.NAVIGATE,
+          payload: Object.assign({}, payload, {
+            action: 'PUSH'
+          })
+        });
+
+      // Converts a `REPLACE` action into a `NAVIGATE` action.
+      case _ActionTypes.default.REPLACE:
+        return next({
+          type: _ActionTypes.default.NAVIGATE,
+          payload: Object.assign({}, payload, {
+            action: 'REPLACE'
+          })
+        });
+      default:
+        return next(action);
+    }
+  };
+}
+module.exports = exports.default;

package/lib/cjs/middleware/normalizeInputLocationMiddleware.js

@@ -0,0 +1,27 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = normalizeInputLocationMiddleware;
+var _ActionTypes = _interopRequireDefault(require("../ActionTypes"));
+var _normalizeInputLocation = _interopRequireDefault(require("../normalizeInputLocation"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+// This "middleware" transforms input location argument into a proper `NormalizedInputLocation`.
+function normalizeInputLocationMiddleware() {
+  return next => action => {
+    const {
+      type,
+      payload
+    } = action;
+    switch (type) {
+      case _ActionTypes.default.PUSH:
+      case _ActionTypes.default.REPLACE:
+        return next({
+          type,
+          payload: (0, _normalizeInputLocation.default)(payload)
+        });
+      default:
+        return next(action);
+    }
+  };
+}
+module.exports = exports.default;

package/lib/cjs/navigationBlockers.js

@@ -0,0 +1,146 @@
+"use strict";
+
+exports.__esModule = true;
+exports.addNavigationBlocker = addNavigationBlocker;
+exports.getNavigationBlockers = getNavigationBlockers;
+exports.removeAllNavigationBlockers = removeAllNavigationBlockers;
+exports.runNavigationBlockers = runNavigationBlockers;
+var _isPromise = _interopRequireDefault(require("./isPromise"));
+var _onlyAllowedOnClientSide = _interopRequireDefault(require("./onlyAllowedOnClientSide"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+let navigationBlockersList = [];
+let removeBeforeDestroyListener;
+function getNavigationBlockers() {
+  return navigationBlockersList;
+}
+function addNavigationBlockerToTheList(blocker) {
+  (0, _onlyAllowedOnClientSide.default)();
+  navigationBlockersList.push(blocker);
+}
+function removeNavigationBlockerFromTheList(blocker) {
+  (0, _onlyAllowedOnClientSide.default)();
+  navigationBlockersList = navigationBlockersList.filter(_ => _ !== blocker);
+}
+function removeAllNavigationBlockers() {
+  (0, _onlyAllowedOnClientSide.default)();
+  if (getNavigationBlockers().some(blocker => blocker.beforeDestroy)) {
+    removeBeforeDestroyListener();
+    removeBeforeDestroyListener = undefined;
+  }
+  navigationBlockersList = [];
+}
+
+// Runs the `listener` while ignoring any errors that might be thrown by it.
+function runNavigationBlocker({
+  listener
+}, location) {
+  let result;
+  try {
+    result = listener(location);
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.warn(`Ignoring navigation blocker \`${listener.name}\` that failed with \`${error}\`.`);
+    // eslint-disable-next-line no-console
+    console.error(error);
+  }
+
+  // If the listener returned a `Promise`, await for that `Promise`
+  // and then return the result.
+  if ((0, _isPromise.default)(result)) {
+    return result.catch(error => {
+      // eslint-disable-next-line no-console
+      console.warn(`Ignoring navigation blocker \`${listener.name}\` that failed with \`${error}\`.`);
+      // eslint-disable-next-line no-console
+      console.error(error);
+    });
+  }
+  // The listener didn't return a `Promise`.
+  // Return the "synchronous" result.
+  return result;
+}
+
+// Runs all listeners in order.
+// If any listener returns a non-`null` result, it stops and returns the result.
+// If there's no such listener, returns `true`.
+function runNavigationBlockers(navigationBlockers, toLocation) {
+  if (navigationBlockers.length === 0) {
+    return undefined;
+  }
+
+  // Call the first blocker in the list.
+  const result = runNavigationBlocker(navigationBlockers[0], toLocation);
+  const next = () => {
+    // Proceed to the next blocker.
+    return runNavigationBlockers(navigationBlockers.slice(1), toLocation);
+  };
+  if ((0, _isPromise.default)(result)) {
+    return result.then(resultValue => {
+      if (resultValue) {
+        return resultValue;
+      }
+      return next();
+    });
+  }
+  if (result) {
+    return result;
+  }
+  return next();
+}
+
+/* istanbul ignore next: not testable with Karma */
+function onBeforeDestroy() {
+  const result = runNavigationBlockers(getNavigationBlockers(), null);
+
+  // If no listener returned anything, don't prevent the "unload" event.
+  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" listeners should be ignored.
+  // https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event
+  if ((0, _isPromise.default)(result)) {
+    return undefined;
+  }
+
+  // Prevent the "unload" event.
+  return true;
+}
+function addNavigationBlocker(environment, listener) {
+  (0, _onlyAllowedOnClientSide.default)();
+
+  // All navigation blockers also run on `beforeDestroy` event.
+  // If required, this could be a parameter of this function.
+  // The rationale could be that adding `beforeunload` a listener
+  // disables web page caching in some browsers like Firefox.
+  const beforeDestroy = true;
+
+  // If it's the first "beforeDestroy" listener, add the global `onBeforeDestroy` listener.
+  //
+  // Sidenote: Add the "beforeunload" event listener only as needed, as its presence
+  // prevents the page from being added to the page navigation cache:
+  //
+  // "In Firefox, beforeunload is not compatible with the back/forward cache (bfcache):
+  //  that is, Firefox will not place pages in the bfcache if they have beforeunload listeners,
+  //  and this is bad for performance."
+  //
+  // https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event
+  if (beforeDestroy && !getNavigationBlockers().some(blocker => blocker.beforeDestroy)) {
+    removeBeforeDestroyListener = environment.addBeforeDestroyListener(onBeforeDestroy);
+  }
+  const blocker = {
+    listener,
+    beforeDestroy
+  };
+  addNavigationBlockerToTheList(blocker);
+  return () => {
+    removeNavigationBlockerFromTheList(blocker);
+
+    // If it was the last "beforeDestroy" listener, remove the global `onBeforeDestroy` listener.
+    if (beforeDestroy && !getNavigationBlockers().some(navigationBlocker => navigationBlocker.beforeDestroy)) {
+      removeBeforeDestroyListener();
+      removeBeforeDestroyListener = undefined;
+    }
+  };
+}

package/lib/cjs/normalizeInputLocation.js

@@ -0,0 +1,46 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = normalizeInputLocation;
+var _createSearchFromQuery = _interopRequireDefault(require("./createSearchFromQuery"));
+var _parseLocationUrl = _interopRequireDefault(require("./parseLocationUrl"));
+var _parseQueryFromSearch = _interopRequireDefault(require("./parseQueryFromSearch"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+// * If `location` is a string, it parses it into a `NormalizedInputLocation`.
+// * 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`.
+function normalizeInputLocation(location) {
+  if (typeof location === 'string') {
+    return (0, _parseLocationUrl.default)(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]);
+    }
+  }
+
+  // Create `query` from `search`.
+  if (location.search && !location.query) {
+    location = Object.assign({}, location, {
+      query: (0, _parseQueryFromSearch.default)(location.search)
+    });
+  }
+
+  // Convert `query` object into a `search` string
+  // if `query` is present but `search` is not.
+  if (location.query && !location.search) {
+    location = Object.assign({}, location, {
+      search: (0, _createSearchFromQuery.default)(location.query)
+    });
+  }
+
+  // Set default values on `search` and `hash`
+  // if those properties are not present.
+  return Object.assign({}, location, {
+    search: location.search || '',
+    hash: location.hash || ''
+  });
+}
+module.exports = exports.default;

package/lib/cjs/onlyAllowedOnClientSide.js

@@ -0,0 +1,10 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = onlyAllowedOnClientSide;
+function onlyAllowedOnClientSide() {
+  if (typeof window === 'undefined') {
+    throw new Error('This function can only be called on client side');
+  }
+}
+module.exports = exports.default;

package/lib/cjs/parseLocationUrl.js

@@ -0,0 +1,39 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = parseLocationUrl;
+var _parseQueryFromSearch = _interopRequireDefault(require("./parseQueryFromSearch"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+function parseLocationUrl(url) {
+  if (url[0] !== '/') {
+    throw new Error('Expected URL to start with a slash');
+  }
+  let remainingPath = url;
+  const hashIndex = remainingPath.indexOf('#');
+  let hash;
+  if (hashIndex !== -1) {
+    hash = remainingPath.slice(hashIndex);
+    remainingPath = remainingPath.slice(0, hashIndex);
+  } else {
+    hash = '';
+  }
+  const searchIndex = remainingPath.indexOf('?');
+  let search;
+  if (searchIndex !== -1) {
+    search = remainingPath.slice(searchIndex);
+    remainingPath = remainingPath.slice(0, searchIndex);
+  } else {
+    search = '';
+  }
+  const location = {
+    pathname: remainingPath,
+    search,
+    hash
+  };
+  const query = (0, _parseQueryFromSearch.default)(search);
+  if (query) {
+    location.query = query;
+  }
+  return location;
+}
+module.exports = exports.default;

package/lib/cjs/parseQueryFromSearch.js

@@ -0,0 +1,16 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = parseQueryFromSearch;
+var _queryString = require("query-string");
+function parseQueryFromSearch(search) {
+  if (search.length > '?'.length) {
+    try {
+      return (0, _queryString.parse)(search.slice(1));
+    } catch (error) {
+      // Ignore any query parsing errors.
+    }
+  }
+  return undefined;
+}
+module.exports = exports.default;

package/lib/esm/ActionTypes.js

@@ -0,0 +1,9 @@
+export default {
+  INIT: '@@navigation-stack/INIT',
+  PUSH: '@@navigation-stack/PUSH',
+  REPLACE: '@@navigation-stack/REPLACE',
+  NAVIGATE: '@@navigation-stack/NAVIGATE',
+  SHIFT: '@@navigation-stack/SHIFT',
+  UPDATE: '@@navigation-stack/UPDATE',
+  DISPOSE: '@@navigation-stack/DISPOSE'
+};

package/lib/esm/Actions.js

@@ -0,0 +1,21 @@
+import ActionTypes from './ActionTypes';
+export default {
+  init: () => ({
+    type: ActionTypes.INIT
+  }),
+  push: location => ({
+    type: ActionTypes.PUSH,
+    payload: location
+  }),
+  replace: location => ({
+    type: ActionTypes.REPLACE,
+    payload: location
+  }),
+  shift: delta => ({
+    type: ActionTypes.SHIFT,
+    payload: delta
+  }),
+  dispose: () => ({
+    type: ActionTypes.DISPOSE
+  })
+};

package/lib/esm/LocationStateStorage.js

@@ -0,0 +1,53 @@
+import getLocationUrl from './getLocationUrl';
+export default class LocationStateStorage {
+  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.getState(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.removeState(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.setState(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/addNavigationBlocker.js

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

package/lib/esm/basePath.js

@@ -0,0 +1,53 @@
+function normalizeBasePath(basePath) {
+  if (!basePath || basePath === '/') {
+    return undefined;
+  }
+
+  // Validate `basePath`.
+  if (basePath[0] !== '/') {
+    throw new Error('`basePath` must start with a slash');
+  }
+
+  // Remove trailing slash from `basePath`.
+  if (basePath.slice(-1) === '/') {
+    basePath = basePath.slice(0, -1);
+  }
+  return basePath;
+}
+function removeBasePathFromRelativeUrl(url, basePath) {
+  if (url.indexOf(basePath) === 0) {
+    // `farce` had a bug here:
+    // `location.pathname` is supposed to always be non-empty.
+    // If `basePath` is set to `/basePath` and the user navigates to `/basePath` URL,
+    // originally here it would simply strips the whole string from the URL
+    // and the result would be incorrect: `pathname: ""`.
+    // The fix below is adding `|| '/'` in the `return` statement.
+    // https://github.com/4Catalyzer/farce/issues/483
+    return url.slice(basePath.length) || '/';
+  }
+  return url;
+}
+export function addBasePath(location, basePath) {
+  basePath = normalizeBasePath(basePath);
+  if (!basePath) {
+    return location;
+  }
+  if (typeof location === 'string') {
+    return `${basePath}${location}`;
+  }
+  return Object.assign({}, location, {
+    pathname: `${basePath}${location.pathname}`
+  });
+}
+export function removeBasePath(location, basePath) {
+  basePath = normalizeBasePath(basePath);
+  if (!basePath) {
+    return location;
+  }
+  if (typeof location === 'string') {
+    return removeBasePathFromRelativeUrl(location, basePath);
+  }
+  return Object.assign({}, location, {
+    pathname: removeBasePathFromRelativeUrl(location.pathname, basePath)
+  });
+}

package/lib/esm/createMiddlewares.js

@@ -0,0 +1,37 @@
+import createBasePathMiddleware from './middleware/createBasePathMiddleware';
+import createEnvironmentMiddleware from './middleware/createEnvironmentMiddleware';
+import createNavigationBlockerMiddleware from './middleware/createNavigationBlockerMiddleware';
+import navigationActionMiddleware from './middleware/navigationActionMiddleware';
+import normalizeInputLocationMiddleware from './middleware/normalizeInputLocationMiddleware';
+export default 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,
+  // 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(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.
+  createEnvironmentMiddleware(environment, {
+    shouldIgnoreEnvironmentLocationUpdates: () => shouldIgnoreEnvironmentLocationUpdates
+  }),
+  // Allows blocking navigation.
+  // Handles location `UPDATE` actions dispatched by the environment.
+  createNavigationBlockerMiddleware(environment, {
+    ignoreEnvironmentLocationUpdates
+  })];
+}

package/lib/esm/createSearchFromQuery.js

@@ -0,0 +1,8 @@
+import { stringify as stringifyQuery } from 'query-string';
+export default function createSearchFromQuery(query) {
+  const queryString = stringifyQuery(query);
+  if (queryString) {
+    return `?${queryString}`;
+  }
+  return undefined;
+}

package/lib/esm/environment/BrowserEnvironment.js

@@ -0,0 +1,104 @@
+import getLocationUrl from '../getLocationUrl';
+import parseQueryFromSearch from '../parseQueryFromSearch';
+export default 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 && parseQueryFromSearch(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 = getLocationUrl(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);
+  }
+}