navigation-stack 0.1.0

package/src/createMiddlewares.js

@@ -0,0 +1,41 @@
+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/src/createSearchFromQuery.js

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

package/src/environment/BrowserEnvironment.js

@@ -0,0 +1,109 @@
+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 = { state, ...extraState };
+    const url = getLocationUrl(location);
+
+    if (push) {
+      window.history.pushState(browserState, null, url);
+    } else {
+      window.history.replaceState(browserState, null, url);
+    }
+
+    return { ...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);
+  }
+}

package/src/environment/MemoryEnvironment.js

@@ -0,0 +1,151 @@
+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 {
+      ...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 { ...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/src/environment/ServerEnvironment.js

@@ -0,0 +1,54 @@
+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 {
+      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/src/getLocationUrl.js

@@ -0,0 +1,12 @@
+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/src/index.js

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

package/src/isPromise.js

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

package/src/locationReducer.js

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

package/src/middleware/createBasePathMiddleware.js

@@ -0,0 +1,20 @@
+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/src/middleware/createEnvironmentMiddleware.js

@@ -0,0 +1,57 @@
+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/src/middleware/createNavigationBlockerMiddleware.js

@@ -0,0 +1,128 @@
+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/src/middleware/createTransformLocationMiddleware.js

@@ -0,0 +1,29 @@
+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/src/middleware/navigationActionMiddleware.js

@@ -0,0 +1,27 @@
+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: { ...payload, action: 'PUSH' },
+        });
+
+      // Converts a `REPLACE` action into a `NAVIGATE` action.
+      case ActionTypes.REPLACE:
+        return next({
+          type: ActionTypes.NAVIGATE,
+          payload: { ...payload, action: 'REPLACE' },
+        });
+
+      default:
+        return next(action);
+    }
+  };
+}