navigation-stack 0.1.3 → 0.2.0

package/lib/esm/session/MemorySession.js

@@ -0,0 +1,217 @@
+/* eslint-disable max-classes-per-file */
+
+import normalizeInputLocation from '../normalizeInputLocation';
+
+// eslint-disable-next-line no-underscore-dangle
+function _loadState(load, isValidLoadedData) {
+  try {
+    const data = JSON.parse(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 (isValidLoadedData(data)) {
+      return data;
+    }
+  } catch (error) {} // eslint-disable-line no-empty
+
+  return null;
+}
+
+// eslint-disable-next-line no-underscore-dangle
+function _saveState(save, data) {
+  try {
+    save(JSON.stringify(data));
+  } catch (error) {} // eslint-disable-line no-empty
+}
+class MemoryNavigation {
+  constructor(initialLocation, {
+    save,
+    load
+  } = {}) {
+    this._save = save;
+    this._keyPrefix = Date.now().toString(36);
+    this._keyIndex = 0;
+    this._subscriptionListener = null;
+    const initialState = load ? _loadState(load, this._isValidLoadedData) : null;
+    if (initialState) {
+      this._stack = initialState.stack;
+      this._index = initialState.index;
+    } else {
+      this._stack = [Object.assign({}, normalizeInputLocation(initialLocation), {
+        key: this._getNextKey()
+      })];
+      this._index = 0;
+    }
+  }
+  _isValidLoadedData({
+    stack,
+    index
+  }) {
+    // Check that the `stack` and `index` at least seem reasonable before using them.
+    // This isn't foolproof, but it might prevent mistakes.
+    return Array.isArray(stack) && typeof index === 'number' && stack[index];
+  }
+  init() {
+    return this._createLocationObject({
+      action: 'INIT',
+      delta: 0
+    });
+  }
+  subscribe(listener) {
+    this._subscriptionListener = listener;
+    return () => {
+      this._subscriptionListener = null;
+    };
+  }
+  navigate(location) {
+    const {
+      action,
+      pathname,
+      search,
+      query,
+      hash,
+      state
+    } = location;
+    if (action !== 'PUSH' && action !== 'REPLACE') {
+      throw Error(`Unrecognized browser session action: ${action}`);
+    }
+    const delta = action === 'PUSH' ? 1 : 0;
+    this._index += delta;
+    const key = this._getNextKey();
+    this._stack[this._index] = {
+      pathname,
+      search,
+      query,
+      hash,
+      state,
+      key
+    };
+    if (action === 'PUSH') {
+      this._stack.length = this._index + 1;
+    }
+    if (this._save) {
+      _saveState(this._save, {
+        stack: this._stack,
+        index: this._index
+      });
+    }
+    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) {
+      _saveState(this._save, {
+        stack: this._stack,
+        index: this._index
+      });
+    }
+    if (this._subscriptionListener) {
+      this._subscriptionListener(this._createLocationObject({
+        action: 'POP',
+        delta: this._index - prevIndex
+      }));
+    }
+  }
+  _getNextKey() {
+    const key = `${this._keyPrefix}.${this._keyIndex.toString(36)}`;
+    this._keyIndex++;
+    return key;
+  }
+  _createLocationObject({
+    action,
+    delta
+  }) {
+    return Object.assign({}, this._stack[this._index], {
+      action,
+      index: this._index,
+      delta
+    });
+  }
+}
+class MemoryDataStorage {
+  constructor({
+    load,
+    save
+  } = {}) {
+    this._save = save;
+    const initialState = load ? _loadState(load, this._isValidLoadedData) : null;
+    if (initialState) {
+      this._state = initialState.state;
+    } else {
+      this._state = {};
+    }
+  }
+
+  // Returns either a `string` value or `null` if the key doesn't exist.
+  get(key) {
+    if (key in this._state) {
+      return this._state[key];
+    }
+    return null;
+  }
+  remove(key) {
+    if (key in this._state) {
+      delete this._state[key];
+    }
+    if (this._save) {
+      _saveState(this._save, {
+        state: this._state
+      });
+    }
+  }
+  set(key, value) {
+    this._state[key] = value;
+    if (this._save) {
+      _saveState(this._save, {
+        state: this._state
+      });
+    }
+  }
+  _isValidLoadedData({
+    state
+  }) {
+    // Perform a basic validation of `state`.
+    return typeof state === 'object' && state !== null;
+  }
+}
+function createNestedStateSaveLoadFunctions({
+  save,
+  load
+}, key) {
+  return {
+    save: save ? data => save(key, data) : undefined,
+    load: load ? () => load(key) : undefined
+  };
+}
+export default class MemorySession {
+  constructor(initialLocation, {
+    save,
+    load
+  } = {}) {
+    this.navigation = new MemoryNavigation(initialLocation, createNestedStateSaveLoadFunctions({
+      save,
+      load
+    }, 'navigation'));
+    this.dataStorage = new MemoryDataStorage(createNestedStateSaveLoadFunctions({
+      save,
+      load
+    }, 'dataStorage'));
+  }
+
+  // "Before destroy" listeners are currently ignored.
+  // If required, one could implement a `_destroy()` method
+  // and there check that the listeners actually do get called.
+  // eslint-disable-next-line no-unused-vars
+  addBeforeDestroyListener(listener) {
+    return () => {};
+  }
+}

package/lib/esm/{environment/ServerEnvironment.js → session/ServerSession.js}

@@ -1,46 +1,58 @@
+/* eslint-disable max-classes-per-file */
+
 import normalizeInputLocation from '../normalizeInputLocation';
 function noop() {}
 function serverSideNavigationNotPossible() {
   throw new Error('Server-side navigation is not possible');
 }
-export default class ServerEnvironment {
+class ServerNavigation {
   constructor(initialLocation) {
     this._location = normalizeInputLocation(initialLocation);
   }
   init() {
     return Object.assign({
-      action: 'POP'
-    }, this._location);
+      action: 'INIT'
+    }, this._location, {
+      index: 0,
+      key: '0'
+    });
   }
   subscribe() {
-    // Server environment emits no location events.
+    // Server-side environment emits no location subscription events.
     return noop;
   }
 
-  // Navigation methods are not implemented, because `ServerPEnvironment` instances
+  // Navigation methods are not implemented, because `ServerSession` instances
   // cannot navigate.
   navigate() {
     serverSideNavigationNotPossible();
   }
 
-  // Navigation methods are not implemented, because `ServerEnvironment` instances
+  // Navigation methods are not implemented, because `ServerSession` instances
   // cannot navigate.
   shift() {
     serverSideNavigationNotPossible();
   }
+}
+class ServerDataStorage {
+  // It doesn't seem to make any sense to store anything on server side.
+  // Hence, state management methods are "no op" stubs.
+  get() {
+    return null;
+  }
+  remove() {}
+  set() {}
+}
+export default class ServerSession {
+  constructor(initialLocation) {
+    this.navigation = new ServerNavigation(initialLocation);
+    this.dataStorage = new ServerDataStorage();
+  }
 
   // "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;
+    return noop;
   }
-  removeState() {}
-  setState() {}
 }

package/lib/index.d.ts

@@ -13,12 +13,9 @@ export type InputLocationQuery = Record<
 
 export interface Location<TState = any> {
   /**
-   * 'PUSH' or 'REPLACE' if the location was reached via FarceActions.push or
-   * FarceActions.replace respectively; 'POP' on the initial location, or if
-   * the location was reached via the browser back or forward buttons or
-   * via FarceActions.shift
+   * See the README on the `action` property of `location`.
    */
-  action: 'PUSH' | 'REPLACE' | 'POP';
+  action: 'PUSH' | 'REPLACE' | 'POP' | 'INIT';
   /**
    * the path name; as on window.location e.g. '/foo'
    */
@@ -36,9 +33,9 @@ export interface Location<TState = any> {
    */
   hash: string;
   /**
-   * if present, a unique key identifying the current history entry
+   * a unique key identifying the current history entry
    */
-  key?: string;
+  key: string;
   /**
    * the current index of the history entry, starting at 0 for the initial
    * entry; this increments on FarceActions.push but not on
@@ -46,12 +43,11 @@ export interface Location<TState = any> {
    */
   index: number;
   /**
-   * the difference between the current index and the index of the previous
-   * location
+   * the difference between the current index and the index of the previous location
    */
   delta: number;
   /**
-   * additional location state that is not part of the URL
+   * any additional location state that the application might explicitly define and store
    */
   state: TState;
 }
@@ -70,11 +66,15 @@ export interface InputLocationObject {
 export interface LocationBase {
   pathname: Location['pathname'];
   search: Location['search'];
-  query?: Query;
+  query: Query;
   hash: Location['hash'];
   state?: Location['state'];
 }
 
+export interface NavigationLocation extends LocationBase {
+  action: 'PUSH' | 'REPLACE';
+}
+
 /**
  * Location descriptor string:
  *  store.dispatch(FarceActions.push('/foo?bar=baz#qux'));
@@ -109,13 +109,20 @@ export type NavigationBlockerResult =
   | Promise<NavigationBlockerSyncResult>;
 
 /**
- * The navigation listener function receives the `location` to which the user
- * is attempting to navigate.
+ * Navigation blocker function receives a `location` to which the application (or the user) is attempting to navigate.
  *
- * The `location` argument is `null` when the web browser tab is about to be closed.
+ * * The `location` argument is `null` when the web browser tab is about to be closed.
+ * * The `location` argument is of type `NavigationLocation` when a `.push()` or `.replace()` action is blocked.
+ * * The `location` argument is of type `Location` when blocking a navigation that was initiated outside of the application code.
+ *   For example, when the user clicks "Back" or "Forward" button in a web browser.
  */
 export interface NavigationBlocker {
-  (location: Location | LocationBase | null): NavigationBlockerResult;
+  (location: Location | NavigationLocation | null): NavigationBlockerResult;
+}
+
+// I dunno why did they use an `interface` here.
+export interface BeforeLocationChangeListener {
+  (location: Location): void;
 }
 
 export function addBasePath<L extends InputLocation>(
@@ -131,15 +138,20 @@ export function getLocationUrl(location: InputLocationObject): string;
 export function parseLocationUrl(locationUrl: string): LocationBase;
 
 export function createMiddlewares(
-  environment: Environment,
+  session: SessionBase,
   options?: CreateMiddlewaresOptions,
 ): Middleware[];
 
 export function addNavigationBlocker(
-  environment: EnvironmentBase,
+  session: SessionBase,
   blocker: NavigationBlocker,
 ): () => void;
 
+export function addBeforeLocationChangeListener(
+  session: SessionBase,
+  listener: BeforeLocationChangeListener,
+): () => void;
+
 export const ActionTypes: {
   INIT: '@@navigation-stack/INIT';
   PUSH: '@@navigation-stack/PUSH';
@@ -190,78 +202,71 @@ export const Actions: {
 
 type BeforeDestroyListener = () => boolean | undefined;
 
-export interface Environment {
+interface SessionNavigation {
   init(): void;
 
   // Subscribes to changes in location,
   // excluding ones that happened as a result of calling `.navigate()`.
   subscribe(listener: (location: Location) => void): () => void;
 
-  navigate(location: LocationBase): Location;
+  navigate(location: NavigationLocation): Location;
 
   shift(delta: number): void;
-
-  addBeforeDestroyListener(listener: BeforeDestroyListener): void;
-
-  getState(key: string): string | null;
-  removeState(key: string): void;
-  setState(key: string, value: string): void;
 }
 
-// This is just a copy-paste of the `Environment` interface above.
-declare abstract class EnvironmentBase implements Environment {
-  init(): void;
-
-  // Subscribes to changes in location,
-  // excluding ones that happened as a result of calling `.navigate()`.
-  subscribe(listener: (location: Location) => void): () => void;
+interface SessionDataStorage {
+  get(key: string): string | null;
+  remove(key: string): void;
+  set(key: string, value: string): void;
+}
 
-  navigate(location: LocationBase): Location;
+export interface Session {
+  navigation: SessionNavigation;
+  dataStorage: SessionDataStorage;
+  addBeforeDestroyListener(listener: BeforeDestroyListener): void;
 
-  shift(delta: number): void;
+  // These're internal variables that're manually set under the hood.
+  // _beforeLocationChangeListenersList?: Array<BeforeLocationChangeListener>;
+  // _navigationBlockersList?: Array<NavigationBlocker>;
+  // _removeBeforeDestroyListener?: () => void;
+  // _navigationBlockersEvaluationStatus?: { cancelled?: boolean };
+}
 
+// This is just a copy-paste of the `session` interface above.
+declare abstract class SessionBase implements Session {
+  navigation: SessionNavigation;
+  dataStorage: SessionDataStorage;
   addBeforeDestroyListener(listener: BeforeDestroyListener): void;
 
-  getState(key: string): string | null;
-  removeState(key: string): void;
-  setState(key: string, value: string): void;
+  // These're internal variables that're manually set under the hood.
+  // _beforeLocationChangeListenersList?: Array<BeforeLocationChangeListener>;
+  // _navigationBlockersList?: Array<NavigationBlocker>;
+  // _removeBeforeDestroyListener?: () => void;
+  // _navigationBlockersEvaluationStatus?: { cancelled?: boolean };
 }
 
-export class BrowserEnvironment extends EnvironmentBase {}
+export class BrowserSession extends SessionBase {}
 
-export interface MemoryEnvironmentOptions<MemoryEnvironmentState = any> {
-  save?: (state: MemoryEnvironmentState) => void;
-  load?: () => MemoryEnvironmentState | undefined | null;
+export interface MemorySessionOptions {
+  save?: (data: string) => void;
+  load?: () => string | undefined | null;
 }
 
-export class ServerEnvironment extends EnvironmentBase {
+export class ServerSession extends SessionBase {
   constructor(initialLocation: InputLocation);
 }
 
-export class MemoryEnvironment extends EnvironmentBase {
+export class MemorySession extends SessionBase {
   constructor(
     initialLocation: InputLocation,
-    options?: MemoryEnvironmentOptions,
+    options?: MemorySessionOptions,
   );
 }
 
-export interface QueryMiddlewareOptions {
-  stringify(query: InputLocationQuery): string;
-  parse(str: string): Query;
-}
-
-export function createQueryMiddleware(
-  options: QueryMiddlewareOptions,
-): Middleware;
-
-export const queryMiddleware: Middleware;
-
-export function createBasePathMiddleware(basePath?: string): Middleware;
-
 export const locationReducer: Reducer<Location, Action>;
 
-export class LocationStateStorage {
-  constructor(environment: Environment, options?: { namespace?: string });
+export class LocationDataStorage {
+  constructor(session: Session, options?: { namespace?: string });
 
   get(location: Location, key: string): any;
   set(location: Location, key: string, value: any): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "navigation-stack",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Handles navigation in a web browser",
   "keywords": [
     "history",
@@ -92,8 +92,8 @@
     "webpack": "^5.72.1"
   },
   "resolutions": {
-    "dtslint/@definitelytyped/header-parser": "^0.0.41",
-    "dtslint/@definitelytyped/typescript-versions": "^0.0.41",
-    "dtslint/@definitelytyped/utils": "^0.0.41"
+    "@definitelytyped/header-parser": "^0.0.41",
+    "@definitelytyped/typescript-versions": "^0.0.41",
+    "@definitelytyped/utils": "^0.0.41"
   }
 }

package/src/{LocationStateStorage.js → LocationDataStorage.js}

@@ -1,6 +1,6 @@
 import getLocationUrl from './getLocationUrl';
 
-export default class LocationStateStorage {
+export default class LocationDataStorage {
   constructor(environment, { namespace } = {}) {
     this._environment = environment;
     this._getFallbackLocationKey = getLocationUrl;
@@ -11,7 +11,7 @@ export default class LocationStateStorage {
     const stateKey = this._getStateKey(location, key);
 
     try {
-      const value = this._environment.getState(stateKey);
+      const value = this._environment.dataStorage.get(stateKey);
       // === null is probably sufficient.
       if (value === null) {
         return undefined;
@@ -31,7 +31,7 @@ export default class LocationStateStorage {
 
     if (value === undefined) {
       try {
-        this._environment.removeState(stateKey);
+        this._environment.dataStorage.remove(stateKey);
       } catch (error) {
         // No need to handle errors here.
       }
@@ -44,7 +44,7 @@ export default class LocationStateStorage {
     const valueString = JSON.stringify(value);
 
     try {
-      this._environment.setState(stateKey, valueString);
+      this._environment.dataStorage.set(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.

package/src/addBeforeLocationChangeListener.js

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

package/src/beforeLocationChangeListeners.js

@@ -0,0 +1,54 @@
+/* eslint-disable no-underscore-dangle */
+
+export function getBeforeLocationChangeListeners(session) {
+  return session._beforeLocationChangeListenersList || [];
+}
+
+function addBeforeLocationChangeListenerToTheList(listener, session) {
+  if (!session._beforeLocationChangeListenersList) {
+    session._beforeLocationChangeListenersList = [];
+  }
+  session._beforeLocationChangeListenersList.push(listener);
+}
+
+function removeBeforeLocationChangeListenerFromTheList(listener, session) {
+  if (session._beforeLocationChangeListenersList) {
+    session._beforeLocationChangeListenersList =
+      session._beforeLocationChangeListenersList.filter((_) => _ !== listener);
+  }
+}
+
+export function removeAllBeforeLocationChangeListeners(session) {
+  session._beforeLocationChangeListenersList = [];
+}
+
+// Runs the `listener` while ignoring any errors that might be thrown by it.
+function runBeforeLocationChangeListener(listener, location) {
+  try {
+    listener(location);
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `Ignoring before location change listener \`${listener.name}\` that failed with \`${error}\`.`,
+    );
+    // eslint-disable-next-line no-console
+    console.error(error);
+  }
+}
+
+// Runs all listeners in order.
+export function runBeforeLocationChangeListeners(
+  navigationListeners,
+  toLocation,
+) {
+  for (const listener of navigationListeners) {
+    runBeforeLocationChangeListener(listener, toLocation);
+  }
+}
+
+export function addBeforeLocationChangeListener(session, listener) {
+  addBeforeLocationChangeListenerToTheList(listener, session);
+  return () => {
+    removeBeforeLocationChangeListenerFromTheList(listener, session);
+  };
+}

package/src/createMiddlewares.js

@@ -1,16 +1,17 @@
 import createBasePathMiddleware from './middleware/createBasePathMiddleware';
-import createEnvironmentMiddleware from './middleware/createEnvironmentMiddleware';
+import createBeforeLocationChangeListenerMiddleware from './middleware/createBeforeLocationChangeListenerMiddleware';
+import createLocationMiddleware from './middleware/createLocationMiddleware';
 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;
+export default function createMiddlewares(session, options) {
+  // Allows temporarily ignoring location update events.
+  let shouldIgnoreLocationSubscriptionEvents = false;
+  const ignoreLocationSubscriptionEvents = (func) => {
+    shouldIgnoreLocationSubscriptionEvents = true;
     func();
-    shouldIgnoreEnvironmentLocationUpdates = false;
+    shouldIgnoreLocationSubscriptionEvents = false;
   };
 
   return [
@@ -23,19 +24,22 @@ export default function createMiddlewares(environment, options) {
     createBasePathMiddleware(options && options.basePath),
     // Allows blocking navigation.
     // Handles `NAVIGATE` actions dispatched by the application itself.
-    createNavigationBlockerMiddleware(environment, {
-      ignoreEnvironmentLocationUpdates,
+    createNavigationBlockerMiddleware(session, {
+      ignoreLocationSubscriptionEvents,
     }),
-    // 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,
+    // This "middleware" performs the actual navigation according to the `session` being used.
+    // For example, when `BrowserSession` is used, it calls methods of the `history` object.
+    createLocationMiddleware(session, {
+      shouldIgnoreLocationSubscriptionEvents: () =>
+        shouldIgnoreLocationSubscriptionEvents,
     }),
     // Allows blocking navigation.
-    // Handles location `UPDATE` actions dispatched by the environment.
-    createNavigationBlockerMiddleware(environment, {
-      ignoreEnvironmentLocationUpdates,
+    // Handles location `UPDATE` actions dispatched in response to location update events.
+    createNavigationBlockerMiddleware(session, {
+      ignoreLocationSubscriptionEvents,
     }),
+    // Allows subscribing to upcoming location changes
+    // before those changes are applied in the `location` object in the state.
+    createBeforeLocationChangeListenerMiddleware(session),
   ];
 }