navigation-stack 0.3.0 → 0.4.0

package/lib/esm/session/navigation/InMemoryNavigation.js

@@ -0,0 +1,97 @@
+import parseInputLocation from '../../parseInputLocation';
+export default class InMemoryNavigation {
+  constructor() {
+    // A stack of `LocationBase` objects.
+    this._stack = [];
+  }
+
+  // eslint-disable-next-line no-unused-vars
+  subscribe(listener) {
+    // `InMemoryNavigation` doesn't have any "asynchronycity" about it
+    // and performs any navigation immediately at the time of the call.
+    // Hence, no asynchronous listener would ever be called
+    // due to no asynchronous events being dispatched.
+    return () => {};
+  }
+  init(initialLocation, {
+    operation,
+    key,
+    index,
+    delta
+  }) {
+    this._stack.push({
+      location: parseInputLocation(initialLocation),
+      key
+    });
+    return this._createLocationObject({
+      operation,
+      index,
+      delta
+    });
+  }
+  navigate(location, {
+    operation,
+    key,
+    index,
+    delta
+  }) {
+    const {
+      pathname,
+      search,
+      query,
+      hash
+    } = location;
+    this._stack[index] = {
+      location: {
+        pathname,
+        search,
+        query,
+        hash
+      },
+      key
+    };
+
+    // A `PUSH` navigation sets a new terminal (rightmost) location.
+    if (delta === 1) {
+      // Trim the location stack by removing any previous location history
+      // that might've existed after the current index.
+      this._stack.length = index + 1;
+    }
+    return Object.assign({}, location, {
+      key,
+      operation,
+      index,
+      delta
+    });
+  }
+  shift({
+    operation,
+    index,
+    delta
+  }) {
+    return this._createLocationObject({
+      operation,
+      index,
+      delta
+    });
+  }
+  getInitialLocation() {
+    return undefined;
+  }
+  _createLocationObject({
+    operation,
+    index,
+    delta
+  }) {
+    const {
+      location,
+      key
+    } = this._stack[index];
+    return Object.assign({}, location, {
+      key,
+      operation,
+      index,
+      delta
+    });
+  }
+}

package/lib/esm/session/navigation/ServerSideNavigation.js

@@ -0,0 +1,54 @@
+/* eslint-disable no-underscore-dangle, max-classes-per-file */
+
+import ServerSideNavigationError from './error/ServerSideNavigationError';
+export default class ServerSideNavigation {
+  init(initialLocation, {
+    operation,
+    key,
+    index,
+    delta
+  }) {
+    return Object.assign({}, initialLocation, {
+      operation,
+      key,
+      index,
+      delta
+    });
+  }
+
+  // eslint-disable-next-line no-unused-vars
+  subscribe(listener) {
+    // `ServerSideNavigation` doesn't have any "asynchronycity" about it
+    // and any navigation is prohibited and would result in an error.
+    // So no asynchronous listener would ever be called
+    // due to no asynchronous events being dispatched.
+    return () => {};
+  }
+
+  // eslint-disable-next-line no-unused-vars
+  navigate(location, {
+    operation,
+    key,
+    index,
+    delta
+  }) {
+    throw new ServerSideNavigationError(location);
+  }
+
+  // eslint-disable-next-line no-unused-vars
+  shift({
+    operation,
+    index,
+    delta
+  }) {
+    // It's not supposed to ever get to this code.
+    // * If `delta` is `0` then it's a "do nothing" scenario and `Session` won't even call this code.
+    // * If `delta` is not `0` and is out of bounds then a `NavigationOutOfBoundsError` will be thrown.
+    // * If `delta` is not `0` and is not out of bounds then it implies that a valid navigation has happened before
+    //   which can't be the case because no navigation is possible on server side without throwing an error.
+    throw new Error('Server side has no navigation history');
+  }
+  getInitialLocation() {
+    return undefined;
+  }
+}

package/lib/esm/session/navigation/WebBrowserNavigation.js

@@ -0,0 +1,213 @@
+import getLocationUrl from '../../getLocationUrl';
+// import parseInputLocation from '../../parseInputLocation';
+import parseQueryFromSearch from '../../parseQueryFromSearch';
+import Operations from './operation/operations';
+const NO_LOCATION_INDEX = -1;
+
+// 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.
+//
+export default class WebBrowserNavigation {
+  constructor() {
+    // `_currentLocationIndex` is used when receiving a "popstate" event
+    // that wasn't initiated by the application code but rather by the user
+    // clicking "Back" or "Forward" button in their web browser.
+    this._currentLocationIndex = NO_LOCATION_INDEX;
+  }
+
+  // Subscribes to changes in the current location.
+  // Returns an `unsubscribe()` function which is "idempotent", i.e. it can be called multiple times.
+  subscribe(listener) {
+    const onPopState = () => {
+      // If "popstate" event is received before navigation is initialized,
+      // ignore such "popstate" event. This behavior is logical from the application code's view.
+      // And besides, `this._currentLocationIndex` is not defined in such conditions.
+      if (this._currentLocationIndex === NO_LOCATION_INDEX) {
+        throw new Error('Received a "popstate" event before initialized');
+      }
+      const prevIndex = this._currentLocationIndex;
+      const {
+        index
+      } = this._getCurrentLocationState();
+      this._currentLocationIndex = index;
+      listener(this._createEntryFromCurrentLocation({
+        operation: Operations.SHIFT,
+        delta: index - prevIndex
+      }));
+    };
+
+    // Due to how `popstate` event listener works, there should only be one listener at a time,
+    // otherwise two different `Session`s would react to the same `popstate` event,
+    // each interpreting it as its own, while in reality it only belongs to one of them
+    // and the other one should completely ignore it.
+    // In other words, there can't exist two navigation sessions simultaneously by design.
+    // There can only be one active navigation session at a given time.
+    // Another one could only start after the previous one ends,
+    // not both of them being active simultaneously.
+    if (this._subscribed) {
+      throw new Error('There already is an active subscription. Only one subscription is allowed at a time.');
+    }
+    window.addEventListener('popstate', onPopState);
+    this._subscribed = true;
+    return () => {
+      window.removeEventListener('popstate', onPopState);
+      this._subscribed = false;
+    };
+  }
+  init(initialLocation, {
+    operation,
+    key,
+    index,
+    delta
+  }) {
+    // Validate that `initialLocation` is same as `window.location`.
+    const isCurrentLocation = initialLocation === this._getCurrentLocation() || this._isSameAsCurrentLocation(initialLocation);
+    if (!isCurrentLocation) {
+      throw new Error('`initialLocation` argument should be same as `window.location`');
+    }
+
+    // Set `window.history.state` of the initial location
+    // by calling `window.history.replaceState()` on page load.
+    // Otherwise, `window.history.state` would be `null` for the initial location
+    // and there'd be no place to store the additional properties of the initial location
+    // such as `location.key`.
+    // https://github.com/taion/scroll-behavior/issues/215
+    //
+    // If the user opens the initial page for the first time, `window.history.state` will be `null`.
+    // If the user refreshes the initial page, `window.history.state` will not be cleared
+    // and therefore will not be `null` and will instead have the previously-set value.
+    //
+    if (!this._getCurrentLocationState()) {
+      // Create additional properties for the initial locaiton.
+      const additionalProperties = {
+        key,
+        index
+      };
+      // Call `history.replaceState()`.
+      this._storeAdditionalPropertiesForLocation(initialLocation, additionalProperties, delta);
+    }
+    this._currentLocationIndex = index;
+
+    // Call the listeners.
+    return this._createEntryFromCurrentLocation({
+      operation,
+      delta
+    });
+  }
+  navigate(location, {
+    operation,
+    key,
+    index,
+    delta
+  }) {
+    const additionalProperties = {
+      key,
+      index
+    };
+    this._storeAdditionalPropertiesForLocation(location, additionalProperties, delta);
+    this._currentLocationIndex = index;
+
+    // Call the listeners.
+    return Object.assign({
+      operation,
+      delta
+    }, location, additionalProperties);
+  }
+
+  // shift({ operation, index, delta }) {
+  shift({
+    delta
+  }) {
+    // Web browser `history` is extremely non-strict when it comes to `history.go(delta)` navigation.
+    // It will allow any number as `delta`, regardless of whether such history entry exists or not.
+    // To introduce strict validation of the `delta` argument, `Session` class code explicitly checks
+    // the new `index` on whether it's out of bounds of the navigation history stack, and after it verifies
+    // that the new `index` is valid, it calls the `.shift(delta)` method of `WebBrowserNavigation` class.
+    //
+    // Calling `window.history.go()` will trigger a "popstate" event which will trigger the listeners.
+    //
+    window.history.go(delta);
+  }
+  getInitialLocation() {
+    // Web browser environment already knows the initial location
+    // by the time javascript code starts execution.
+    return this._getCurrentLocation();
+  }
+  _getCurrentLocation() {
+    return window.location;
+  }
+  _getCurrentLocationState() {
+    return window.history.state;
+  }
+  _isSameAsCurrentLocation(inputLocation) {
+    return typeof inputLocation === 'string' ? inputLocation === getLocationUrl(this._getCurrentLocation()) : inputLocation === this._getCurrentLocation() || getLocationUrl(inputLocation) === getLocationUrl(this._getCurrentLocation());
+  }
+  _createEntryFromCurrentLocation({
+    operation,
+    delta
+  }) {
+    const {
+      pathname,
+      search,
+      hash
+    } = this._getCurrentLocation();
+    const {
+      key,
+      index
+    } = this._getCurrentLocationState();
+    return {
+      operation,
+      pathname,
+      search,
+      query: parseQueryFromSearch(search),
+      hash,
+      key,
+      index,
+      delta
+    };
+  }
+  _storeAdditionalPropertiesForLocation(location, additionalProperties, delta) {
+    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`.
+    if (delta === 1) {
+      window.history.pushState(additionalProperties, null, url);
+    } else if (delta === 0) {
+      window.history.replaceState(additionalProperties, null, url);
+    } else {
+      throw new Error(`Unsupported \`delta\`: ${delta}`);
+    }
+  }
+}

package/lib/esm/session/navigation/error/NavigationOutOfBoundsError.js

@@ -0,0 +1,6 @@
+export default class NavigationOutOfBoundsError extends Error {
+  constructor(index) {
+    super(`Location index ${index} is out of navigation history bounds`);
+    this.index = index;
+  }
+}

package/lib/esm/session/navigation/error/ServerSideNavigationError.js

@@ -0,0 +1,14 @@
+const _excluded = ["operation"];
+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; }
+import getLocationUrl from '../../../getLocationUrl';
+export default class ServerSideNavigationError extends Error {
+  constructor(location) {
+    super(location ? `Navigate to ${getLocationUrl(location)}` : 'Navigate to previous or next location');
+    if (location) {
+      // Remove `operation` property from `location`.
+      // eslint-disable-next-line no-unused-vars
+      const locationBase = _objectWithoutPropertiesLoose(location, _excluded);
+      this.location = locationBase;
+    }
+  }
+}

package/lib/esm/session/navigation/operation/operations.js

@@ -0,0 +1,6 @@
+export default {
+  INIT: 'INIT',
+  PUSH: 'PUSH',
+  REPLACE: 'REPLACE',
+  SHIFT: 'SHIFT'
+};

package/lib/esm/session/subscription/Subscription.js

@@ -0,0 +1,75 @@
+export default class Subscription {
+  constructor({
+    activateSubscription
+  } = {}) {
+    this.notifySubscribers = argument => {
+      // `._latest` is only used in tests.
+      this._latest = argument;
+      for (const {
+        listener
+      } of this._listeners) {
+        listener(argument);
+      }
+    };
+    this._activateSubscription = activateSubscription;
+
+    // This property is accessed in tests.
+    this._listeners = [];
+  }
+  subscribe(listener) {
+    // If subscriptions are stopped, i.e. no new subscriptions are to be added,
+    // then don't add any listeners and return a "do nothing" function.
+    if (this._stopped) {
+      return () => {};
+    }
+
+    // Creating a `listenerEntry` object ensures that the `.filter()` function
+    // during "unsubscribe" step doesn't accidentally remove another listeners
+    // having the same `listener` function.
+    // I.e. it's not illegal to call `.subscribe(listener)` multiple times
+    // with the same argument, and those would be considered different subscriptions.
+    const listenerEntry = {
+      listener
+    };
+
+    // If it's the first listener, activate subscription.
+    if (this._listeners.length === 0) {
+      this._deactivateSubscription = this._activateSubscription(this.notifySubscribers);
+    }
+
+    // Add the `listener` to the list.
+    this._listeners.push(listenerEntry);
+
+    // The returned `unsubscribe()` function is "idempotent", i.e. it can be called multiple times.
+    return () => {
+      // Remove the listener, if not already removed.
+      this._removeListener(listenerEntry);
+    };
+  }
+  stop() {
+    if (this._stopped) {
+      throw new Error('Already stopped');
+    }
+    this._stopped = true;
+
+    // Clear any remaining listeners.
+    for (const listener of this._listeners.slice()) {
+      this._removeListener(listener);
+    }
+  }
+  _removeListener(listenerEntry) {
+    // If no listeners are left, no need to do anything.
+    if (this._listeners.length === 0) {
+      return;
+    }
+
+    // Remove the `listener` from the list.
+    this._listeners = this._listeners.filter(_ => _ !== listenerEntry);
+
+    // If it was the last listener, deactivate subscription.
+    if (this._listeners.length === 0) {
+      this._deactivateSubscription();
+      this._deactivateSubscription = undefined;
+    }
+  }
+}