navigation-stack 0.1.0

package/lib/esm/environment/MemoryEnvironment.js

@@ -0,0 +1,143 @@
+import normalizeInputLocation from '../normalizeInputLocation';
+export default 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 = [normalizeInputLocation(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;
+  }
+}

package/lib/esm/environment/ServerEnvironment.js

@@ -0,0 +1,46 @@
+import normalizeInputLocation from '../normalizeInputLocation';
+function noop() {}
+function serverSideNavigationNotPossible() {
+  throw new Error('Server-side navigation is not possible');
+}
+export default class ServerEnvironment {
+  constructor(initialLocation) {
+    this._location = normalizeInputLocation(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() {}
+}

package/lib/esm/getLocationUrl.js

@@ -0,0 +1,15 @@
+import { stringify as stringifyQuery } from 'query-string';
+export default function getLocationUrl({
+  pathname,
+  search,
+  query,
+  hash
+}) {
+  if (!search && query) {
+    const queryString = stringifyQuery(query);
+    if (queryString) {
+      search = `?${queryString}`;
+    }
+  }
+  return `${pathname}${search || ''}${hash || ''}`;
+}

package/lib/esm/index.js

@@ -0,0 +1,12 @@
+export { default as Actions } from './Actions';
+export { default as ActionTypes } from './ActionTypes';
+export { addBasePath, removeBasePath } from './basePath';
+export { default as addNavigationBlocker } from './addNavigationBlocker';
+export { default as getLocationUrl } from './getLocationUrl';
+export { default as parseLocationUrl } from './parseLocationUrl';
+export { default as createMiddlewares } from './createMiddlewares';
+export { default as locationReducer } from './locationReducer';
+export { default as LocationStateStorage } from './LocationStateStorage';
+export { default as BrowserEnvironment } from './environment/BrowserEnvironment';
+export { default as MemoryEnvironment } from './environment/MemoryEnvironment';
+export { default as ServerEnvironment } from './environment/ServerEnvironment';

package/lib/esm/isPromise.js

@@ -0,0 +1,4 @@
+export default function isPromise(anything) {
+  // Weirdly, `typeof null` is "object".
+  return typeof anything === 'object' && anything !== null && typeof anything.then === 'function';
+}

package/lib/esm/locationReducer.js

@@ -0,0 +1,7 @@
+import ActionTypes from './ActionTypes';
+export default function locationReducer(state, action) {
+  if (action.type === ActionTypes.UPDATE) {
+    return action.payload;
+  }
+  return state;
+}

package/lib/esm/middleware/createBasePathMiddleware.js

@@ -0,0 +1,19 @@
+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 environment `Location` object:
+    // removes `basePath` from the URL.
+    transformEnvironmentLocation: location => {
+      return removeBasePath(location, basePath);
+    }
+  });
+}

package/lib/esm/middleware/createEnvironmentMiddleware.js

@@ -0,0 +1,52 @@
+import ActionTypes from '../ActionTypes';
+function updateLocation(location) {
+  return {
+    type: ActionTypes.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".
+export default 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.INIT:
+            return next(updateLocation(environment.init()));
+          case ActionTypes.NAVIGATE:
+            // `environment.navigate()` doesn't trigger the `subscribe()` listener.
+            return next(updateLocation(environment.navigate(payload)));
+          case ActionTypes.SHIFT:
+            // `shift()` will trigger the `subscribe()` listener,
+            // which will call `updateLocation()`.
+            environment.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

@@ -0,0 +1,123 @@
+import ActionTypes from '../ActionTypes';
+import isPromise from '../isPromise';
+import { getNavigationBlockers, removeAllNavigationBlockers, runNavigationBlockers } from '../navigationBlockers';
+import onlyAllowedOnClientSide from '../onlyAllowedOnClientSide';
+
+// Creates a "middleware" that applies navigation blockers.
+export default function createNavigationBlockerMiddleware(environment, {
+  ignoreEnvironmentLocationUpdates
+}) {
+  // A "dummy" initial value that will be ignored.
+  let navigationBlockersEvaluationStatus = {
+    cancelled: false
+  };
+  function createNavigationBlockersEvaluationStatus() {
+    onlyAllowedOnClientSide();
+    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.NAVIGATE:
+          // `resultValue` variable name works around a stupid javascript error:
+          // "Cannot redeclare block-scoped variable 'result'".
+          result = runNavigationBlockers(getNavigationBlockers(), 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;
+
+        // 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.UPDATE:
+          // If no navigation blockers to run, don't do anything.
+          if (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 = runNavigationBlockers(getNavigationBlockers(), payload);
+          if (isPromise(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.DISPOSE:
+          removeAllNavigationBlockers();
+          return next(action);
+        default:
+          return next(action);
+      }
+    };
+  };
+}

package/lib/esm/middleware/createTransformLocationMiddleware.js

@@ -0,0 +1,33 @@
+import ActionTypes from '../ActionTypes';
+
+// Creates a "middleware" that transforms action payload (location).
+export default function createTransformLocationMiddleware({
+  transformInputLocation,
+  transformEnvironmentLocation
+}) {
+  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: transformEnvironmentLocation(payload)
+          });
+        default:
+          return next(action);
+      }
+    };
+  };
+}

package/lib/esm/middleware/navigationActionMiddleware.js

@@ -0,0 +1,32 @@
+import ActionTypes from '../ActionTypes';
+
+// This "middleware" transforms a `PUSH` / `REPLACE` action into a `NAVIGATE` action.
+export default function navigationActionMiddleware() {
+  return next => action => {
+    const {
+      type,
+      payload
+    } = action;
+    switch (type) {
+      // Converts a `PUSH` action into a `NAVIGATE` action.
+      case ActionTypes.PUSH:
+        return next({
+          type: ActionTypes.NAVIGATE,
+          payload: Object.assign({}, payload, {
+            action: 'PUSH'
+          })
+        });
+
+      // Converts a `REPLACE` action into a `NAVIGATE` action.
+      case ActionTypes.REPLACE:
+        return next({
+          type: ActionTypes.NAVIGATE,
+          payload: Object.assign({}, payload, {
+            action: 'REPLACE'
+          })
+        });
+      default:
+        return next(action);
+    }
+  };
+}

package/lib/esm/middleware/normalizeInputLocationMiddleware.js

@@ -0,0 +1,22 @@
+import ActionTypes from '../ActionTypes';
+import normalizeInputLocation from '../normalizeInputLocation';
+
+// This "middleware" transforms input location argument into a proper `NormalizedInputLocation`.
+export default function normalizeInputLocationMiddleware() {
+  return next => action => {
+    const {
+      type,
+      payload
+    } = action;
+    switch (type) {
+      case ActionTypes.PUSH:
+      case ActionTypes.REPLACE:
+        return next({
+          type,
+          payload: normalizeInputLocation(payload)
+        });
+      default:
+        return next(action);
+    }
+  };
+}

package/lib/esm/navigationBlockers.js

@@ -0,0 +1,138 @@
+import isPromise from './isPromise';
+import onlyAllowedOnClientSide from './onlyAllowedOnClientSide';
+let navigationBlockersList = [];
+let removeBeforeDestroyListener;
+export function getNavigationBlockers() {
+  return navigationBlockersList;
+}
+function addNavigationBlockerToTheList(blocker) {
+  onlyAllowedOnClientSide();
+  navigationBlockersList.push(blocker);
+}
+function removeNavigationBlockerFromTheList(blocker) {
+  onlyAllowedOnClientSide();
+  navigationBlockersList = navigationBlockersList.filter(_ => _ !== blocker);
+}
+export function removeAllNavigationBlockers() {
+  onlyAllowedOnClientSide();
+  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 (isPromise(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`.
+export 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 (isPromise(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 (isPromise(result)) {
+    return undefined;
+  }
+
+  // Prevent the "unload" event.
+  return true;
+}
+export function addNavigationBlocker(environment, listener) {
+  onlyAllowedOnClientSide();
+
+  // 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;
+    }
+  };
+}