navigation-stack 0.5.3 → 0.6.0

package/lib/esm/scroll-position/ScrollPositionSaver.js

@@ -2,21 +2,23 @@
 
 import ScrollPositionAutoSaver from './ScrollPositionAutoSaver';
 import { PAGE_SCROLLABLE_CONTAINER_KEY } from './constants';
-import debug from '../debug';
 export default class ScrollPositionSaver {
   constructor({
+    log,
     scrollPosition,
     getLocation,
     saveScrollPositionForLocation,
     getScrollableContainers,
     shouldSaveScrollPosition
   }) {
+    this._log = log;
     this._scrollPosition = scrollPosition;
     this._getLocation = getLocation;
     this._saveScrollPositionForLocation = saveScrollPositionForLocation;
     this._getScrollableContainers = getScrollableContainers;
     this._shouldSaveScrollPosition = shouldSaveScrollPosition;
     this._scrollPositionAutoSaver = new ScrollPositionAutoSaver({
+      log: this._log,
       scrollPosition: this._scrollPosition,
       scrollPositionSaver: this,
       getScrollableContainers,
@@ -37,7 +39,7 @@ export default class ScrollPositionSaver {
     if (!this._shouldSaveScrollPosition()) {
       return;
     }
-    debug('save scroll position', this._getLocation().pathname);
+    this._log.debug('save scroll position', this._getLocation().pathname);
 
     // Get scrollable containers.
     const scrollableContainers = this._getScrollableContainers();
@@ -52,7 +54,7 @@ export default class ScrollPositionSaver {
     }
   }
   savePageScrollPosition() {
-    debug('save scroll position', this._getLocation().pathname, PAGE_SCROLLABLE_CONTAINER_KEY, this._scrollPosition.getPageScrollPosition());
+    this._log.debug('save scroll position', this._getLocation().pathname, PAGE_SCROLLABLE_CONTAINER_KEY, this._scrollPosition.getPageScrollPosition());
 
     // * If this is not a scheduled "auto-save" of scroll position
     //   and there already exists any scheduled "auto-save" of scroll position,
@@ -65,7 +67,7 @@ export default class ScrollPositionSaver {
     this._saveScrollPositionForLocation(this._getLocation(), undefined, this._scrollPosition.getPageScrollPosition());
   }
   saveScrollableContainerScrollPosition(scrollableContainerKey, scrollableContainer) {
-    debug('save scroll position', this._getLocation().pathname, scrollableContainerKey, this._scrollPosition.getScrollableContainerScrollPosition(scrollableContainer));
+    this._log.debug('save scroll position', this._getLocation().pathname, scrollableContainerKey, this._scrollPosition.getScrollableContainerScrollPosition(scrollableContainer));
 
     // * If this is not a scheduled "auto-save" of scroll position
     //   and there already exists any scheduled "auto-save" of scroll position,

package/lib/esm/session/Session.js

@@ -1,16 +1,13 @@
-import debug from '../debug';
 import parseInputLocation from '../parseInputLocation';
 import createSessionKey from './key/createSessionKey';
-import NavigationOutOfBoundsError from './navigation/error/NavigationOutOfBoundsError';
-import NavigationOperations from './navigation/operation/operations';
 import Subscription from './subscription/Subscription';
+import NavigationOutOfBoundsError from '../environment/navigation/error/NavigationOutOfBoundsError';
+import NavigationOperations from '../environment/navigation/operation/operations';
 const INITIAL_KEY_INDEX = -1;
 const INITIAL_INDEX = -1;
 const INIT_LOCATION_DELTA = 0;
 export default class Session {
-  constructor({
-    navigation
-  }) {
+  constructor(EnvironmentClass) {
     // This function is used by navigation.
     this._getCurrentLocationIndex = () => {
       return this._currentLocationIndex;
@@ -20,6 +17,9 @@ export default class Session {
     // under the hood, and `window.sessionStorage` is shared between different sessions.
     this.key = createSessionKey();
 
+    // Create an environment instance.
+    this.environment = new EnvironmentClass();
+
     // `this._locationKeyIndex` is incremented every time the current location changes.
     this._locationKeyIndex = INITIAL_KEY_INDEX;
 
@@ -31,18 +31,34 @@ export default class Session {
     // In other words, this is the last location index that it can `.shift()` to.
     this._terminalLocationIndex = this._currentLocationIndex;
 
-    // Create `navigation`.
-    this._navigation = navigation;
+    // Allows subscribing to location updates.
+    this._subscription = new Subscription();
 
-    // Manages subscriptions.
-    this._subscription = new Subscription({
-      activateSubscription: listener => {
-        return this._navigation.subscribe(listener);
-      }
+    // Subscribing to location changes means subscribing to both "synchronous"
+    // and "asynchronous" location changes. "synchronous" location changes
+    // happen immediately when the code triggers them."asynchronous" location changes
+    // either happen after an arbitrary delay or are even triggered from outside the code.
+    //
+    // Subscribing to "asynchronous" location changes is not necessary when
+    // there're no actual subscribers, in order to not unnecessarily "waste" any resources.
+    // Of course, this statement is rather far-fetched and in reality no one would ever tell any difference.
+    // Still, I felt like randomly introducing this seemingly unnecessary minor optimization.
+    //
+    // So it only subscribes to "asynchronous" location changes if there's at least one active subscriber.
+    // And in case all subscribers get unsubscribed, it will unsubscribe from "asynchronous" location changes too.
+    // One might think of it as some form of "mental masturbation", but what can I do — I already wrote the code.
+    //
+    this._subscription.onFirstSubscriber(() => {
+      return this.environment.navigation.subscribeToAsyncrhonousLocationUpdates(location => {
+        // Notify all subscribers about this "asynchronous" location change.
+        this._subscription.notifySubscribers(location);
+      });
     });
 
-    // Update current location index when a location change was not initiated
-    // by this session but rather by the user clicking "Back" or "Forward" button.
+    // This subscription is triggered in two cases:
+    // * Set initial current location index at initial page load.
+    // * Update current location index whenever a location change is not initiated
+    //   by this session but rather by the user clicking "Back" or "Forward" button.
     this._unsubscribe = this.subscribe(location => {
       // Update `this._currentLocationIndex` when the location change was not initiated
       // by this session but rather by the user clicking "Back" or "Forward" button.
@@ -52,16 +68,20 @@ export default class Session {
       // but if it was possible, this call would be required. It would also be required
       // by `navigation` to call `session.getNextKey()` function to increment `locationKeyIndex`.
       this._updateTerminalLocationIndex(location);
-      debug('current location', location.pathname, 'index', this._currentLocationIndex);
+      this.environment.log.debug('current location', location.pathname, 'index', this._currentLocationIndex);
     });
   }
 
   // Subscribes to changes in location.
+  // The first subscriber is always the `Session` itself:
+  // its listener keeps the current location index up-to-date.
+  // Any additional application-specific listeners could be added, if required.
+  // Applications should prefer adding any such listeners by calling `NavigationStack.subscribe()`
+  // method instead of calling this method directly, in order to "normalize" the `location` argument.
   subscribe(listener) {
     return this._subscription.subscribe(location => {
       if (!this._isStarted() && location.operation !== NavigationOperations.INIT) {
-        // eslint-disable-next-line no-console
-        console.error('Unexpected location change', location);
+        this.environment.log.error('Unexpected location change', location);
         throw new Error('Not started');
       } else {
         // Call the listener.
@@ -69,6 +89,18 @@ export default class Session {
       }
     });
   }
+
+  // Starts a navigation session.
+  //
+  // When run in a web browser, it could not only "start" a new session
+  // but also "resume" a previously-started session. That could happen
+  // when the user refreshes a page in a web browser which still retains
+  // the previous session's data but at the same time restarts the javascript code
+  // from scratch.
+  //
+  // So this `start()` method handles both cases: when there's previous session's data
+  // that should be restored and when there's no previous session's data.
+  //
   start(initialLocation) {
     if (this._stopped) {
       throw new Error('Can not be restarted');
@@ -81,7 +113,7 @@ export default class Session {
     // the initial location by the time javascript code starts execution.
     //
     if (!initialLocation) {
-      initialLocation = this._navigation.getInitialLocation();
+      initialLocation = this.environment.navigation.getInitialLocation();
       if (initialLocation) {
         initialLocation = parseInputLocation(initialLocation);
       }
@@ -92,18 +124,19 @@ export default class Session {
     if (this._currentLocationIndex !== INITIAL_INDEX) {
       throw new Error('Already started');
     }
-    debug('▶ start session', initialLocation.pathname);
+    this.environment.log.debug('▶ start session', initialLocation.pathname);
     this._started = true;
     const key = this._getNextLocationKey();
     const index = INITIAL_INDEX + 1;
     const delta = INIT_LOCATION_DELTA;
-    const locationResult = this._navigation.init(initialLocation, {
+    const locationResult = this.environment.navigation.init(initialLocation, {
       operation: NavigationOperations.INIT,
       key,
       index,
       delta
     });
     if (locationResult) {
+      // Notify all subscribers about this "synchronous" location change.
       this._subscription.notifySubscribers(locationResult);
     }
   }
@@ -111,7 +144,7 @@ export default class Session {
     if (this._stopped) {
       throw Error('Already stopped');
     }
-    debug('⏹ stop session');
+    this.environment.log.debug('⏹ stop session');
 
     // Once stopped, it won't be able to be restarted.
     this._stopped = true;
@@ -137,16 +170,17 @@ export default class Session {
     });
     const key = this._getNextLocationKey();
     const index = this._currentLocationIndex + delta;
-    debug(operation === NavigationOperations.PUSH ? '↓' : '⇅', operation, location.pathname, 'index', index);
+    this.environment.log.debug(operation === NavigationOperations.PUSH ? '↓' : '⇅', operation, location.pathname, 'index', index);
 
     // Navigate to the location.
-    const locationResult = this._navigation.navigate(location, {
+    const locationResult = this.environment.navigation.navigate(location, {
       operation,
       key,
       index,
       delta
     });
     if (locationResult) {
+      // Notify all subscribers about this "synchronous" location change.
       this._subscription.notifySubscribers(locationResult);
     }
   }
@@ -160,7 +194,7 @@ export default class Session {
       return;
     }
     const index = this._currentLocationIndex + delta;
-    debug(delta > 0 ? '→' : '←', 'shift', delta, 'index', index);
+    this.environment.log.debug(delta > 0 ? '→' : '←', 'shift', delta, 'index', index);
 
     // Validate that the new `index` is not out of bounds.
     if (index < 0 || index > this._terminalLocationIndex) {
@@ -168,12 +202,13 @@ export default class Session {
     }
 
     // Navigate to the location.
-    const locationResult = this._navigation.shift({
+    const locationResult = this.environment.navigation.shift({
       operation: NavigationOperations.SHIFT,
       index,
       delta
     });
     if (locationResult) {
+      // Notify all subscribers about this "synchronous" location change.
       this._subscription.notifySubscribers(locationResult);
     }
   }

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

@@ -1,20 +1,32 @@
 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;
-
+  constructor() {
     // This property is accessed in tests.
     this._listeners = [];
+
+    // These listeners will be called when the subscription enters "active" or "inactive" state.
+    // A subscription enters "active" state when it has at least one listener rather than zero.
+    // A subscription enters "inactive" state when it has no more listeners.
+    this._subscriptionActiveStateListeners = [];
+    this._subscriptionInactiveStateListeners = [];
+  }
+
+  // Adds a subscription active state listener.
+  // Returns a function that removes the subscription active state listener.
+  onFirstSubscriber(activeStateListener) {
+    this._subscriptionActiveStateListeners.push(activeStateListener);
+    // Return a function that removes the subscription active state listener.
+    return () => {
+      this._subscriptionActiveStateListeners = this._subscriptionActiveStateListeners.filter(_ => _ !== activeStateListener);
+    };
+  }
+  notifySubscribers(argument) {
+    // `._latest` is only used in tests.
+    this._latest = argument;
+    for (const {
+      listener
+    } of this._listeners) {
+      listener(argument);
+    }
   }
   subscribe(listener) {
     // If subscriptions are stopped, i.e. no new subscriptions are to be added,
@@ -34,7 +46,9 @@ export default class Subscription {
 
     // If it's the first listener, activate subscription.
     if (this._listeners.length === 0) {
-      this._deactivateSubscription = this._activateSubscription(this.notifySubscribers);
+      // Run all subscription active state listeners.
+      // The functions returned from those will become subscription inactive state listeners.
+      this._subscriptionInactiveStateListeners = this._subscriptionActiveStateListeners.map(activeStateListener => activeStateListener());
     }
 
     // Add the `listener` to the list.
@@ -66,10 +80,14 @@ export default class Subscription {
     // Remove the `listener` from the list.
     this._listeners = this._listeners.filter(_ => _ !== listenerEntry);
 
-    // If it was the last listener, deactivate subscription.
+    // If it was the last listener.
     if (this._listeners.length === 0) {
-      this._deactivateSubscription();
-      this._deactivateSubscription = undefined;
+      // Run any subscription inactive state listeners,
+      // after which clear the list of such listeners.
+      for (const inactiveStateListener of this._subscriptionInactiveStateListeners) {
+        inactiveStateListener();
+      }
+      this._subscriptionInactiveStateListeners = [];
     }
   }
 }

package/lib/esm/stringifyQuery.js

@@ -0,0 +1,61 @@
+// "The more recent RFC3986 reserves !, ', (, ), and *,
+// even though these characters have no formalized URI delimiting uses.
+//
+// https://datatracker.ietf.org/doc/html/rfc3986
+//
+// The following function encodes a string for RFC3986-compliant URL component format.
+// It also encodes [ and ], which are part of the IPv6 URI syntax.
+//
+// An RFC3986-compliant encodeURI implementation should not escape them,
+// which is demonstrated in the encodeURI() example.
+//
+// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent#encoding_for_rfc3986
+//
+// Can throw a `URIError` if the `string` contains a "lone surrogate".
+// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#utf-16_characters_unicode_code_points_and_grapheme_clusters
+// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/URIError
+// Example: "URIError: malformed URI sequence"
+//
+function encode(string) {
+  return encodeURIComponent(string).replace(/[!'()*]/g, character => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+export default function stringifyQuery(query) {
+  let queryString = '';
+  if (!query) {
+    return queryString;
+  }
+  for (const key of Object.keys(query)) {
+    let value = query[key];
+    if (Array.isArray(value)) {
+      throw new Error('Array values are not supported');
+    }
+
+    // Ignore `value: undefined`.
+    if (value === undefined) {
+      continue;
+    }
+
+    // Stringify `value`.
+    if (value === null) {
+      value = '';
+    } else {
+      value = String(value);
+    }
+
+    // Can throw a `URIError` if the `string` contains a "lone surrogate".
+    // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#utf-16_characters_unicode_code_points_and_grapheme_clusters
+    // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/URIError
+    // Example: "URIError: malformed URI sequence"
+    try {
+      const keyValuePair = `${encode(key)}${value ? '=' : ''}${encode(value)}`;
+      if (queryString.length > 1) {
+        queryString += '&';
+      }
+      queryString += keyValuePair;
+    } catch (error) {
+      // Simply ignore an invalid query parameter.
+      continue;
+    }
+  }
+  return queryString;
+}

package/lib/esm/stringifyQueryAsSearch.js

@@ -0,0 +1,8 @@
+import stringifyQuery from './stringifyQuery';
+export default function stringifyQueryAsSearch(query) {
+  const queryString = stringifyQuery(query);
+  if (queryString) {
+    return `?${queryString}`;
+  }
+  return '';
+}