navigation-stack 0.5.3 → 0.6.1

package/lib/index.d.ts

@@ -1,5 +1,3 @@
-// TypeScript Version: 3.0
-
 export {};
 
 export type Query = Record<string, string>;
@@ -97,11 +95,11 @@ export type NavigationBlockerResult =
  *
  * * The `location` argument is `null` when the web browser tab is about to be closed.
  * * The `location` argument is of type `LocationBase` when a `.push()` or `.replace()` navigation is blocked.
- * * The `location` argument is of type `Location` when blocking a navigation that was initiated outside of the application code.
+ * * The `location` argument is of type `LocationBase` 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 type NavigationBlocker = (
-  location: Location | LocationBase | null,
+  location: LocationBase | null,
 ) => NavigationBlockerResult;
 
 // I dunno why did they use an `interface` here.
@@ -123,20 +121,18 @@ export function parseLocationUrl(locationUrl: string): LocationBase;
 
 export function parseInputLocation(location: InputLocation): LocationBase;
 
-export function addNavigationBlocker(
-  session: Session,
-  blocker: NavigationBlocker,
-): () => void;
-
-export interface NavigationStackOptions {
+export interface NavigationStackOptions<ScrollableContainer, Anchor> {
   basePath?: string;
-  maintainScrollPosition?: boolean;
+  manageScrollPosition?: boolean;
+  scrollPositionSetter?: Constructor<
+    ScrollPositionSetter<ScrollableContainer, Anchor>
+  >;
 }
 
 export class NavigationStack<ScrollableContainer = any, Anchor = any> {
   constructor(
-    session: Session<ScrollableContainer, Anchor>,
-    options?: NavigationStackOptions,
+    environment: Constructor<Environment<ScrollableContainer, Anchor>>,
+    options?: NavigationStackOptions<ScrollableContainer, Anchor>,
   );
 
   addScrollableContainer(
@@ -144,6 +140,10 @@ export class NavigationStack<ScrollableContainer = any, Anchor = any> {
     scrollableContainer: ScrollableContainer,
   ): () => void;
 
+  addNavigationBlocker(blocker: NavigationBlocker): () => void;
+
+  dataStorage: LocationDataStorage;
+
   subscribe(listener: (location: Location) => void): () => void;
 
   current(): Location;
@@ -156,7 +156,7 @@ export class NavigationStack<ScrollableContainer = any, Anchor = any> {
 
   shift(delta: number): void;
 
-  locationRendered(): Promise<void>;
+  locationRendered(location: Location): Promise<void>;
 
   stop(): void;
 }
@@ -173,7 +173,7 @@ export type SessionExecutionStatusListener = (
 
 export type ScrollListener = () => void;
 
-export class ServerSideNavigationError extends Error {
+export class ServerSideRedirectError extends Error {
   constructor(location: LocationBase);
 
   location: LocationBase;
@@ -185,9 +185,11 @@ export class NavigationOutOfBoundsError extends Error {
   index: number;
 }
 
-export class Navigation {
-  // Subscribes to "location change" events.
-  subscribe(listener: (location: LocationInternal) => void): () => void;
+export class EnvironmentNavigation {
+  // Subscribes to "asynchronous" changes of the current location.
+  subscribeToAsyncrhonousLocationUpdates(
+    listener: (location: LocationInternal) => void,
+  ): () => void;
 
   init(
     initialLocation: LocationBase,
@@ -218,13 +220,19 @@ export interface EnvironmentDataStorage {
   set(key: string, value: string): void;
 }
 
-export interface SessionLifecycle {
+export interface EnvironmentLifecycle {
   addTerminationBlocker(blocker: SessionTerminationBlocker): () => void;
   addExecutionStatusListener(
     listener: SessionExecutionStatusListener,
   ): () => void;
 }
 
+export interface EnvironmentLog {
+  debug(...args: any[]): void;
+  warn(...args: any[]): void;
+  error(...args: any[]): void;
+}
+
 // Manages scroll position in an environment such as a web browser.
 export interface EnvironmentScrollPosition<ScrollableContainer, Anchor> {
   // Gets numeric scroll position of a page.
@@ -255,10 +263,13 @@ export interface EnvironmentScrollPosition<ScrollableContainer, Anchor> {
 
 export interface Environment<ScrollableContainer, Anchor> {
   dataStorage: EnvironmentDataStorage;
+  log: EnvironmentLog;
+  lifecycle: EnvironmentLifecycle;
+  navigation: EnvironmentNavigation;
   scrollPosition: EnvironmentScrollPosition<ScrollableContainer, Anchor>;
 }
 
-export interface Session<ScrollableContainer = any, Anchor = any> {
+interface Session<ScrollableContainer = any, Anchor = any> {
   // `key` should be unique within `environment.dataStorage`.
   // For example, `BrowserEnvironment` uses `window.sessionStorage`
   // that is shared across different sessions within a given web browser tab,
@@ -268,7 +279,7 @@ export interface Session<ScrollableContainer = any, Anchor = any> {
   // Private varibles. Not public API.
   environment: Environment<ScrollableContainer, Anchor>;
 
-  lifecycle: SessionLifecycle;
+  lifecycle: EnvironmentLifecycle;
 
   subscribe(listener: (location: LocationInternal) => void): () => void;
 
@@ -282,12 +293,12 @@ export interface Session<ScrollableContainer = any, Anchor = any> {
 }
 
 // This is just a copy-paste of the `session` interface above.
-declare abstract class SessionBaseClass<
-  ScrollableContainer = any,
-  Anchor = any,
-> implements Session<ScrollableContainer, Anchor>
+declare abstract class SessionClass<ScrollableContainer = any, Anchor = any>
+  implements Session<ScrollableContainer, Anchor>
 {
-  constructor(parameters: { navigation: Navigation });
+  constructor(
+    environmentClass: Constructor<Environment<ScrollableContainer, Anchor>>,
+  );
 
   // `key` should be unique within `environment.dataStorage`.
   // For example, `BrowserEnvironment` uses `window.sessionStorage`
@@ -295,10 +306,11 @@ declare abstract class SessionBaseClass<
   // hence the uniqueness requirement.
   key: string;
 
-  // Private varibles. Not public API.
+  // Private varible. Not public API.
   environment: Environment<ScrollableContainer, Anchor>;
 
-  lifecycle: SessionLifecycle;
+  // Private varible. Not public API.
+  lifecycle: EnvironmentLifecycle;
 
   subscribe(listener: (location: LocationInternal) => void): () => void;
 
@@ -311,14 +323,148 @@ declare abstract class SessionBaseClass<
   shift(delta: number): void;
 }
 
-export class WebBrowserSession extends SessionBaseClass<HTMLElement, string> {
-  constructor();
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface WebBrowserEnvironment
+  extends Environment<HTMLElement, string> {}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface ServerSideRenderEnvironment
+  extends Environment<string, string> {}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface InMemoryEnvironment extends Environment<string, string> {}
+
+// Theoretically, a developer could pass their own `ScrollPositionSetter` implementation
+// when calling `.addScrollableContainer()` or
+export interface ScrollPositionSetter<ScrollableContainer, Anchor> {
+  // Sets scroll position of a page or a scrollable element.
+  // Returns a `Promise` that resolves when it has finished setting the scroll position.
+  set(
+    // This is the scrollable container whose scroll position should be set.
+    // * When setting page scroll position, `scrollableContainer` is `undefined`.
+    // * When setting scrollable element scroll position, `scrollableContainer` is the scrollable element.
+    scrollableContainer: ScrollableContainer,
+    // This is the scroll position to set.
+    // * When setting page scroll position, it could be either an anchor or numeric coordinates.
+    // * When setting scrollable element scroll position, it could only be numeric coordinates.
+    scrollPositionOrAnchor: Anchor | [number, number],
+    // `scrollPosition` provides various "helper" methods for setting scroll position according to the environment.
+    // For example, in the context of a `WebBrowserEnvironment`, it provides the methods for setting scroll position in a web browser.
+    scrollPositionHelper: EnvironmentScrollPosition<
+      ScrollableContainer,
+      Anchor
+    >,
+  ): Promise<void>;
+
+  // Cancels any pending (or in-progress) setting of scroll position.
+  cancel(): void;
+}
+
+// https://stackoverflow.com/questions/39392853/is-there-a-type-for-class-in-typescript-and-does-any-include-it
+export type Constructor<T = any> = new (...args: any[]) => T;
+
+export type DataStorageValue =
+  | string
+  | number
+  | boolean
+  | Record<string, unknown>
+  | null
+  | undefined;
+
+declare class DataStorage<
+  Key extends string = string,
+  Value extends DataStorageValue = DataStorageValue,
+> {
+  constructor(session: Session, options: { namespace: string });
+
+  get(key: Key): Value | undefined;
+
+  set(key: Key, value: Value | undefined): void;
 }
 
-export class ServerSideRenderSession extends SessionBaseClass<string, string> {
-  constructor();
+declare class LocationDataStorage<
+  Key extends string = string,
+  Value extends DataStorageValue = DataStorageValue,
+> {
+  constructor(session: Session, options: { namespace: string });
+
+  get(location: Location, key: Key): Value;
+
+  set(location: Location, key: Key, value: Value): void;
 }
 
-export class InMemorySession extends SessionBaseClass<string, string> {
-  constructor();
+export class ScrollPositionRestoration<
+  ScrollableContainer = any,
+  Anchor = any,
+> {
+  constructor(
+    session: Session<ScrollableContainer, Anchor>,
+
+    options?: {
+      // Using this option, a developer could provide their own implementation of setting
+      // a scroll position. For example, it could use "smooth" (animated) scrolling, etc.
+      // When specified, it applies to both page and any scrollable containers.
+      scrollPositionSetter: ScrollPositionSetter<ScrollableContainer, Anchor>;
+
+      shouldChangePageScrollPositionOnLocationChange?: (
+        prevLocation: Location | undefined,
+        newLocation: Location,
+      ) => boolean;
+
+      // `options._getSavedPageScrollPositionOnLocationChange`
+      // isn't used in real life and is not part of the public API.
+      // It's only used in tests.
+      _getSavedPageScrollPositionOnLocationChange?: (
+        location: Location,
+        prevLocation: Location | undefined,
+      ) => [number, number] | undefined;
+
+      // Using this option, a developer could theoretically provide their own implementation
+      // of setting a scroll position. For example, it could use "smooth" (animated) scrolling, etc.
+      // This could be part of the public API if anyone provided a sensible real-world use case for it.
+      _pageScrollPositionSetter?: ScrollPositionSetter<
+        ScrollableContainer,
+        Anchor
+      >;
+    },
+  );
+
+  addScrollableContainer(
+    scrollableContainerKey: string,
+    scrollableContainer: ScrollableContainer,
+
+    options?: {
+      shouldChangeScrollPositionOnLocationChange?: (
+        prevLocation: Location | undefined,
+        newLocation: Location,
+      ) => boolean;
+
+      // `_options._getSavedScrollPositionOnLocationChange`
+      // isn't used in real life and is not part of the public API.
+      // It's only used in tests.
+      _getSavedScrollPositionOnLocationChange?: (
+        location: Location,
+        prevLocation: Location | undefined,
+      ) => [number, number] | undefined;
+
+      // Using this option, a developer could theoretically provide their own implementation
+      // of setting a scroll position. For example, it could use "smooth" (animated) scrolling, etc.
+      // This could be part of the public API if anyone provided a sensible real-world use case for it.
+      _scrollPositionSetter: ScrollPositionSetter<ScrollableContainer, Anchor>;
+    },
+  ): () => void;
+
+  locationRendered: (location: Location) => Promise<void>;
+
+  stop(): void;
+
+  // `_enableSavingScrollPosition()` and `_disableSavingScrollPosition()`
+  // aren't used in real life and are not part of the public API.
+  // They're only used in tests.
+  _enableSavingScrollPosition(): void;
+
+  // `_enableSavingScrollPosition()` and `_disableSavingScrollPosition()`
+  // aren't used in real life and are not part of the public API.
+  // They're only used in tests.
+  _disableSavingScrollPosition(): void;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "navigation-stack",
-  "version": "0.5.3",
-  "description": "Handles navigation in a web browser",
+  "version": "0.6.1",
+  "description": "Navigation in a Single-Page Application",
   "keywords": [
     "history",
     "browser",
@@ -25,7 +25,7 @@
   "scripts": {
     "build": "rimraf lib && 4c build --types false src && npm run build:pick && npm run build:types",
     "build:pick": "cherry-pick --cjs-dir cjs --esm-dir esm --cwd lib ../src",
-    "build:types": "cpy types/*.d.ts lib && cpy types/data-storage/*.d.ts lib/data-storage && cpy types/scroll-position/*.d.ts lib/scroll-position && cpy types/redux/*.d.ts lib/redux",
+    "build:types": "cpy types/*.d.ts lib",
     "format": "4c format --prettier-ignore .eslintignore .",
     "lint": "4c lint --prettier-ignore .eslintignore .",
     "prepublishOnly": "npm run build",
@@ -44,10 +44,7 @@
     "*": "yarn 4c lint --fix --prettier-ignore .eslintignore"
   },
   "prettier": "@4c/prettier-config",
-  "dependencies": {
-    "query-string": "^5.1.1",
-    "redux": "^5.0.1"
-  },
+  "dependencies": {},
   "devDependencies": {
     "@4c/babel-preset": "^9.1.0",
     "@4c/cli": "^3.0.1",

package/src/NavigationStack.js

@@ -1,40 +1,102 @@
-import { applyMiddleware, createStore } from 'redux';
-
-import Actions from './redux/Actions';
-import createMiddlewares from './redux/createMiddlewares';
-import locationReducer from './redux/locationReducer';
+import { addBasePath, removeBasePath } from './basePath';
+import LocationDataStorage from './data-storage/LocationDataStorage';
+import getLocationFromInternalLocation from './getLocationFromInternalLocation';
+import isPromise from './isPromise';
+import {
+  addNavigationBlocker,
+  removeAllNavigationBlockers,
+} from './navigationBlockers';
+import {
+  blockNonProgrammaticNavigationIfRequired,
+  blockProgrammaticNavigationIfRequired,
+} from './navigationBlockersEvaluation';
+import parseInputLocation from './parseInputLocation';
 import ScrollPositionRestoration from './scroll-position/ScrollPositionRestoration';
-
-function getCreateMiddlewaresOptions(navigationStackOptions) {
-  if (!navigationStackOptions) {
-    return undefined;
-  }
-  // eslint-disable-next-line no-unused-vars
-  const { maintainScrollPosition, ...restOptions } = navigationStackOptions;
-  return restOptions;
-}
+import Session from './session/Session';
 
 export default class NavigationStack {
-  constructor(session, options) {
-    this._session = session;
-
-    // Create a Redux store.
-    this._store = createStore(
-      locationReducer,
-      applyMiddleware(
-        ...createMiddlewares(session, getCreateMiddlewaresOptions(options)),
-      ),
-    );
+  constructor(
+    Environment,
+    { basePath, manageScrollPosition, scrollPositionSetter } = {},
+  ) {
+    // Create a session.
+    this._session = new Session(Environment);
+
+    // Base path, if used.
+    this._basePath = basePath;
+
+    // Create location data storage.
+    this.dataStorage = new LocationDataStorage(this._session, {
+      namespace: 'navigation-stack',
+    });
+
+    // Allows temporarily ignoring location update events when set to `true`.
+    this._ignoreLocationUpdates = false;
+
+    // Subscribe to location updates.
+    // * Ignores location updates if `_ignoreLocationUpdates` flag is temporarily set.
+    // * Runs navigation blockers to see if the location update should be reverted.
+    // * Updates `this._location` if the update wasn't ignored or blocked.
+    this._unsubscribe = this._session.subscribe((location) => {
+      // If this location update shouldn't be temporarily ignored.
+      if (!this._ignoreLocationUpdates) {
+        // Remove `basePath` from `location`.
+        location = removeBasePath(location, this._basePath);
+
+        // See if the location update should've been blocked.
+        // If it should've, it will automatically "rewind" it.
+        const result = blockNonProgrammaticNavigationIfRequired(
+          location,
+          this._session,
+          this._doAndIgnoreLocationUpdates,
+        );
+
+        const onResult = (blocked) => {
+          if (!blocked) {
+            // Update `this._location`.
+            // Since it's gonna be returned from the public `this.current()` method,
+            // convert it from `LocationInternal` to `Location`.
+            this._location = getLocationFromInternalLocation(location);
+          }
+        };
+
+        if (isPromise(result)) {
+          result.then(onResult);
+        } else {
+          onResult(result);
+        }
+      }
+    });
 
     // Create `ScrollPositionRestoration`.
-    if (options && options.maintainScrollPosition) {
-      this._scrollPositionRestoration = new ScrollPositionRestoration(session);
+    if (manageScrollPosition) {
+      this._scrollPositionRestoration = new ScrollPositionRestoration(
+        this._session,
+        // Custom `ScrollPositionSetter`.
+        { scrollPositionSetter },
+      );
     }
   }
 
+  // Subscribes to any changes of the current location.
+  // The first subscriber is always the `NavigationStack` itself
+  // because its listener is what drives the actual navigation.
+  // Any additional application-specific listeners could be added, if required.
+  subscribe(listener) {
+    // `NavigationStack.subscribe()` is simply a proxy to `Session.subscribe()`
+    // with the only convenience feature that it "normalizes" the `location` argument.
+    return this._session.subscribe((locationInternal) => {
+      listener(getLocationFromInternalLocation(locationInternal));
+    });
+  }
+
+  addNavigationBlocker(blocker) {
+    return addNavigationBlocker(this._session, blocker);
+  }
+
   addScrollableContainer(scrollableContainerKey, scrollableContainer) {
     if (!this._scrollPositionRestoration) {
-      throw new Error('`maintainScrollPosition: true` option not passed');
+      throw new Error('`manageScrollPosition: true` option not passed');
     }
     return this._scrollPositionRestoration.addScrollableContainer(
       scrollableContainerKey,
@@ -42,59 +104,107 @@ export default class NavigationStack {
     );
   }
 
-  subscribe(listener) {
-    // Subscribe to any potential Redux state changes.
-    return this._store.subscribe(() => {
-      // Initially, calls the listener when setting the initial location.
-      // After that, calls it on any location change.
-      const location = this.current();
-      if (!this._latestLocation || location !== this._latestLocation) {
-        this._latestLocation = location;
-        listener(location);
-      }
-    });
-  }
-
   init(initialLocation) {
-    if (this._latestLocation) {
+    if (this._location) {
       throw new Error('Already initialized');
     }
 
-    this._store.dispatch(Actions.init(initialLocation));
-    this._latestLocation = this.current();
+    this._session.start(
+      initialLocation && this._parseInputLocation(initialLocation),
+    );
+
+    if (this._scrollPositionRestoration) {
+      this._scrollPositionRestoration.start();
+    }
   }
 
   current() {
-    return this._store.getState();
+    // TypeScript definition of the `.current()` method tells that it always returns
+    // some non-`undefined` location.
+    // But `this._location` is `undefined` until `.init(initialLocation?)` is called.
+    // To work around that limitation, it simply throws if `.current()` is called before `.init()`.
+    if (!this._location) {
+      throw new Error('Not initialized');
+    }
+    return this._location;
   }
 
   push(location) {
-    this._store.dispatch(Actions.push(location));
+    this._navigate('push', location);
   }
 
   replace(location) {
-    this._store.dispatch(Actions.replace(location));
+    this._navigate('replace', location);
+  }
+
+  _navigate(operation, location) {
+    const toLocation = this._parseInputLocation(location);
+
+    const result = blockProgrammaticNavigationIfRequired(
+      toLocation,
+      this._session,
+    );
+
+    const onResult = (blocked) => {
+      if (!blocked) {
+        this._session.navigate(operation, toLocation);
+      }
+    };
+
+    if (isPromise(result)) {
+      result.then(onResult);
+    } else {
+      onResult(result);
+    }
   }
 
   shift(delta) {
-    this._store.dispatch(Actions.shift(delta));
+    this._session.shift(delta);
   }
 
   stop() {
+    if (!this._unsubscribe) {
+      throw new Error('Already stopped');
+    }
+
+    this._unsubscribe();
+    this._unsubscribe = undefined;
+
+    // Even if it calls `unsubscribe()` function above, any other subscriptions
+    // would still stay. We're not talking about `navigationStack.subscribe()`
+    // subscriptions because those don't really matter in terms of cleaning them up:
+    // those're just Redux store subscriptions that don't have any side effects.
+    // Subscriptions we're talking here are `Session`'s own subscription
+    // via `session.subscribe()` and any hypothetical manual `session.subscribe()`
+    // calls that could be made by the application code for whatever purpose.
+    // Both of those should be cleared.
+    // To work around that, `.stop()` function removes all subscriptions.
+    this._session.stop();
+
+    removeAllNavigationBlockers(this._session);
+
     if (this._scrollPositionRestoration) {
       this._scrollPositionRestoration.stop();
     }
-    this._store.dispatch(Actions.stop());
   }
 
-  locationRendered() {
-    if (this._scrollPositionRestoration) {
-      const location = this.current();
-      if (!location) {
-        throw new Error('Not initialized');
-      }
-      return this._scrollPositionRestoration.locationRendered(location);
+  locationRendered(location) {
+    if (!this._scrollPositionRestoration) {
+      throw new Error('`manageScrollPosition: true` option not passed');
     }
-    return Promise.resolve();
+    return this._scrollPositionRestoration.locationRendered(location);
   }
+
+  _parseInputLocation(inputLocation) {
+    // Parse input location (string or incomplete object) to a proper `location` object.
+    // Add `basePath` to `location`.
+    return addBasePath(parseInputLocation(inputLocation), this._basePath);
+  }
+
+  // Allows temporarily ignoring location update events.
+  _doAndIgnoreLocationUpdates = (func) => {
+    this._ignoreLocationUpdates = true;
+    func();
+    this._ignoreLocationUpdates = false;
+  };
 }

package/src/data-storage/DataStorage.js

@@ -4,6 +4,7 @@ export default class DataStorage {
       throw new Error('`DataStorage` requires a `session.key`');
     }
     this._sessionKey = session.key;
+    this._log = session.environment.log;
     this._dataStorage = session.environment.dataStorage;
     this._namespace = namespace;
   }
@@ -22,8 +23,8 @@ export default class DataStorage {
       // junk into sessionStorage under our namespace.
       return JSON.parse(value);
     } catch (error) {
-      // eslint-disable-next-line no-console
-      console.error('[navigation-stack] Could not read data from storage');
+      this._log.error('[navigation-stack] Could not read data from storage');
+      this._log.error(error);
 
       // Pretend that the entry doesn't exist.
       return undefined;
@@ -38,8 +39,10 @@ export default class DataStorage {
         this._dataStorage.remove(storageKey);
       } catch (error) {
         // No need to handle errors here.
-        // eslint-disable-next-line no-console
-        console.error('[navigation-stack] Could not delete data from storage');
+        this._log.error(
+          '[navigation-stack] Could not delete data from storage',
+        );
+        this._log.error(error);
       }
 
       return;
@@ -54,8 +57,8 @@ export default class DataStorage {
     } 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.
-      // eslint-disable-next-line no-console
-      console.error('[navigation-stack] Could not save data in storage');
+      this._log.error('[navigation-stack] Could not save data in storage');
+      this._log.error(error);
     }
   }
 

package/src/environment/InMemoryEnvironment.js

@@ -1,9 +1,15 @@
 import InMemoryDataStorage from './data-storage/InMemoryDataStorage';
+import InMemorySessionLifecycle from './lifecycle/InMemorySessionLifecycle';
+import InMemoryLog from './log/InMemoryLog';
+import InMemoryNavigation from './navigation/InMemoryNavigation';
 import InMemoryScrollPosition from './scroll-position/InMemoryScrollPosition';
 
 export default class InMemoryEnvironment {
   constructor() {
     this.dataStorage = new InMemoryDataStorage();
+    this.log = new InMemoryLog();
+    this.lifecycle = new InMemorySessionLifecycle();
+    this.navigation = new InMemoryNavigation();
     this.scrollPosition = new InMemoryScrollPosition();
   }
 }