How does history.js work?

export type Pathname = string;
export type Search = string;
export type Hash = string;
export type State = unknown;
export type Key = string;

/** 
 * The pathname, search, and hash values of a URL.
 */
export interface Path {
  pathname: Pathname;
  search: Search;
  hash: Hash;
}

/** 
 * An entry in a history stack. A location contains information about the
 * URL path, as well as possibly some arbitrary state and a key.
 */
export interface Location extends Path {
  state: unknown;
  key: Key;
}

/** 
 * Actions represent the type of change to a location value.
 */
export enum Action {
  Pop = 'POP',
  Push = 'PUSH',
  Replace = 'REPLACE'
}

/**
 * A change to the current location.
 */
export interface Update {
  action: Action;
  location: Location;
}

/**
 * A change to the current location that was blocked. May be retried
 * after obtaining user confirmation.
 */
export interface Transition extends Update {
  retry(): void;
}

/**
 * A function that receives notifications about location changes.
 */
export interface Listener {
  (update: Update): void;
}

/**
 * A function that receives transitions when navigation is blocked.
 */
export interface Blocker {
  (tx: Transition): void;
}

type Events<F> = {
  length: number;
  push: (fn: F) => () => void;
  call: (arg: any) => void;
};
function createEvents<F extends Function>(): Events<F> {
  // event handlers list
  let handlers: F[] = [];

  return {
    get length() {
      return handlers.length;
    },
    // Register a handler and return a function that can be used to remove it
    push(fn: F) {
      handlers.push(fn);
      return function () {
        handlers = handlers.filter((handler) => handler !== fn);
      };
    },
    // When the event is triggered, execute all handlers.
    call(arg) {
      handlers.forEach((fn) => fn && fn(arg));
    }
  };
}

// BROWSER
export function createBrowserHistory(
  options: BrowserHistoryOptions = {}
): BrowserHistory {}
// HASH
export function createHashHistory(
  options: HashHistoryOptions = {}
): HashHistory {...}
// MEMORY
export function createMemoryHistory(
  options: MemoryHistoryOptions = {}
): MemoryHistory {...}

// BROWSER
export type BrowserHistoryOptions = { window?: Window };
function createBrowserHistory(options) {
  // use document.defaultView as a defaultValue 
  // BTW , in ts 'defaultView!' indicates that you are asserting it is not empty
    let { window = document.defaultView! } = options;
    let globalHistory = window.history;

  // ...
} 
// HASH is same with BROWSER

export type InitialEntry = string | Partial<Location>;
export type MemoryHistoryOptions = {
  initialEntries?: InitialEntry[];
  initialIndex?: number;
};

function createMemeryHistory(options) {
  let { initialEntries = ['/'], initialIndex } = options;
  // using a map to generate entries    
    let entries: Location[] = initialEntries.map((entry) => {
    let location = readOnly<Location>({
      pathname: '/',
      search: '',
      hash: '',
      state: null,
      key: createKey(),
      ...(typeof entry === 'string' ? parsePath(entry) : entry)
    });
    return location;
  });
  // limit the initialIndex within 0 to entries.length - 1
  let index = clamp(
    initialIndex == null ? entries.length - 1 : initialIndex,
    0,
    entries.length - 1
  );
}

// BROWSER
export interface BrowserHistory extends History {}
// HASH
export interface HashHistory extends History {}
// MEMORY
export interface MemoryHistory extends History {
  readonly index: number;
}

/**
 * A history is an interface to the navigation stack. The history serves as the
 * source of truth for the current location, as well as provides a set of
 * methods that may be used to change it.
 *
 * It is similar to the DOM's `window.history` object, but with a smaller, more
 * focused API.
 */
export interface History {
  readonly action: Action;
  readonly location: Location;
  createHref(to: To): string;
  push(to: To, state?: any): void;
  replace(to: To, state?: any): void;
  go(delta: number): void;
  back(): void;
  forward(): void;
  listen(listener: Listener): () => void;
  block(blocker: Blocker): () => void;
}

/**
  * An internal object utilized to store the 'key' and 'state' properties of 
  * a Location in window.history.state, while maintaining a count of 'index'
  * for going back in block events .
*/
type HistoryState = {
  // Location's state that stores the real user's state value
  usr: any;
  // Location's key
  key?: string;
  // index used for blocking purposes init value is 0.
  idx: number;
};

function getIndexAndLocation(): [number, Location] {
    /**
      * get Path properties from window.loaction or window.location.hash
      *
        * << Code in createHashHistory >>
        * let {
      *   pathname = '/',
      *     search = '',
      *     hash = ''
      * } = parsePath(window.location.hash.substr(1));
    */
    let { pathname, search, hash } = window.location;

        /**
            * The state declared here is either a HistoryState or an empty object.
            * When a user opens a new window,window.state is null. By default the 
            * state here is set to empty object
            * Upon window refresh, it will retrieve state from window.state.
            * So it can persist state even when the user refreshes the page.
        */
    let state = globalHistory.state || {};

    // return the index and the created Location 
    return [
      state.idx,
      readOnly<Location>({
        pathname,
        search,
        hash,
        state: state.usr || null,
        key: state.key || 'default'
      })
    ];
  }

// generate the parameters for history.pushState or history.replaceState
function getHistoryStateAndUrl(
    nextLocation: Location,
    index: number
  ): [HistoryState, string] {
    return [
      {
        usr: nextLocation.state,
        key: nextLocation.key,
        idx: index
      },
      createHref(nextLocation)
    ];
  }

// generate a new Location object
function getNextLocation(to: To, state: any = null): Location {
    return readOnly<Location>({
      pathname: location.pathname,
      hash: '',
      search: '',
      ...(typeof to === 'string' ? parsePath(to) : to),
      state,
      key: createKey()
    });
  }

// check if the transcation can be applied
function allowTx(action: Action, location: Location, retry: () => void) {
    // if these is no blocker, just return true
    // else exec all blockers and return false
    return (
      !blockers.length || (blockers.call({ action, location, retry }), false)
    );
  }

// upadate action,location and index that is maintanined in the history,
// and exec all listeners.
function applyTx(nextAction: Action) {
    action = nextAction;
    [index, location] = getIndexAndLocation();
    listeners.call({ action, location });
  }
// in createMemeryHistory
function applyTx(nextAction: Action, nextLocation: Location) {
    action = nextAction;
    location = nextLocation;
    listeners.call({ action, location });
 }

// use getter function for real-time data
let history: MemoryHistory = {
    // only in createMemoryHistory
    get index() {
      return index;
    },
    get action() {
      return action;
    },
    get location() {
      return location;
    },
    ...
  };

// in createBrowserHistory and createMemeryHistory 
function createHref(to: To) {
   return typeof to === 'string' ? to : createPath(to);
}

// in createHashHistory 
function getBaseHref() {
    let base = document.querySelector('base');
    let href = '';
        // Check base value here but actually use 'window.location.href' to ensure the href created by 'creatHref' is an absolute path. Because linking to a relative path erases the hash part of a URL 
    if (base && base.getAttribute('href')) {
      let url = window.location.href;
      let hashIndex = url.indexOf('#');
      href = hashIndex === -1 ? url : url.slice(0, hashIndex);
    }

    return href;
}

function createHref(to: To) {
   return getBaseHref() + '#' + (typeof to === 'string' ? to : createPath(to));
}

    // in createBrowserHistory and createMemeryHistory 
    function push(to: To, state?: any) {
    let nextAction = Action.Push;
    let nextLocation = getNextLocation(to, state);    
    // set retry for resuming the push operation after the execution of blockers
    function retry() {
      push(to, state);
    }



    if (allowTx(nextAction, nextLocation, retry)) {
      let [historyState, url] = getHistoryStateAndUrl(nextLocation, index + 1);

      // try...catch because iOS limits us to 100 pushState calls :/
      try {
        globalHistory.pushState(historyState, '', url);
      } catch (error) {
        // They are going to lose state here, but there is no real
        // way to warn them about it since the page will refresh...
        window.location.assign(url);
      }

      applyTx(nextAction);
    }
  }

  function replace(to: To, state?: any) {
        ...
    if (allowTx(nextAction, nextLocation, retry)) {
      ...
      globalHistory.replaceState(historyState, '', url);

      applyTx(nextAction);
    }
  }

  // in createMemeryHistory
    function push(to: To, state?: any) {
    ...
    if (allowTx(nextAction, nextLocation, retry)) {
      index += 1;
      entries.splice(index, entries.length, nextLocation);
      applyTx(nextAction, nextLocation);
    }
  }

  function replace(to: To, state?: any) {
    ...
    if (allowTx(nextAction, nextLocation, retry)) {
      entries[index] = nextLocation;
      applyTx(nextAction, nextLocation);
    }
  }

// in createBrowserHistory and createMemeryHistory 
function go(delta: number) {
    globalHistory.go(delta);
}

// in createMemoryHistory
function go(delta: number) {
    // prevent the array from exceeding its limits.
    let nextIndex = clamp(index + delta, 0, entries.length - 1);

    let nextAction = Action.Pop;
    let nextLocation = entries[nextIndex];
    function retry() {
      go(delta);
    }
        // like push and repalce
    if (allowTx(nextAction, nextLocation, retry)) {
      index = nextIndex;
      applyTx(nextAction, nextLocation);
    }
  }

const BeforeUnloadEventType = 'beforeunload';

// init the events
let listeners = createEvents<Listener>();
let blockers = createEvents<Blocker>();

function promptBeforeUnload(event: BeforeUnloadEvent) {
  // Cancel the event.
  event.preventDefault();
  // Chrome (and legacy IE) requires returnValue to be set.
  event.returnValue = '';
}

let history = {
        // ...
    // add a listener and return a dismiss function
    // just like 'useEffect' 👀
    listen(listener) {
      return listeners.push(listener);
    },
    // add blocker and return a dismiss function
    block(blocker) {
      let unblock = blockers.push(blocker);

         // In browser and hash mode, it handles the beforeunload event to
     //  provide a warning before the user leaves the page.
      if (blockers.length === 1) {
        window.addEventListener(BeforeUnloadEventType, promptBeforeUnload);
      }

      return function () {
        unblock();

        // Remove the beforeunload listener so the document may
        // still be salvageable in the pagehide event.
        // See https://html.spec.whatwg.org/#unloading-documents
        if (!blockers.length) {
          window.removeEventListener(BeforeUnloadEventType, promptBeforeUnload);
        }
      };
    }
  };

// in createMemoryHistory
let history = {
    //  ... 
  block(blocker) {
     let unblock = blockers.push(blocker);
  }
}

const HashChangeEventType = 'hashchange';
const PopStateEventType = 'popstate';

// store the last transcation using a closure
let blockedPopTx: Transition | null = null;

function handlePop() {
    // if blockedPopTx exsit, use it to execute all blokcers and set blockedPopTx to null
    if (blockedPopTx) {
      blockers.call(blockedPopTx);
      blockedPopTx = null;
    } else {
      // When the code reaches this point, the browser's location has changed, allowing us to retrieve the next index and Location.
            // To be explicit, 'next' has no relation to the direction; going back can also be  treated as 'next'.

      let nextAction = Action.Pop;
      let [nextIndex, nextLocation] = getIndexAndLocation();

      // if there is blockers
      if (blockers.length) {
        // Usually, we can obtain a valid index and location here because all history entries are produced from history.js unless you invoke the HTML5 APIs directly.
        if (nextIndex != null) {
          // calculate the steps of change
          let delta = index - nextIndex;
          if (delta) {
            // create and save the transaction to 'blockedPopTx'
            blockedPopTx = {
              action: nextAction,
              location: nextLocation,
              retry() {
                go(delta * -1);
              }
            };
                        // Go back to the former page, and this action will trigger the 'handlePop' function again. This allows it to execute blockers saved in 'blockedPopTx'.
            go(delta);
          }
        } else {
          // Trying to POP to a location with no index. We did not create
          // this location, so we can't effectively block the navigation.
          warning(
            false,
            // TODO: Write up a doc that explains our blocking strategy in
            // detail and link to it here so people can understand better
            // what is going on and how to avoid it.
            `You are trying to block a POP navigation to a location that was not ` +
              `created by the history library. The block will fail silently in ` +
              `production, but in general you should do all navigation with the ` +
              `history library (instead of using window.history.pushState directly) ` +
              `to avoid this situation.`
          );
        }
      } else {
        // no blocker 
        applyTx(nextAction);
      }
    }
  }

  window.addEventListener(PopStateEventType, handlePop);

  // popstate does not fire on hashchange in IE 11 and old (trident) Edge
  // https://developer.mozilla.org/de/docs/Web/API/Window/popstate_event
  window.addEventListener(HashChangeEventType, () => {
    let [, nextLocation] = getIndexAndLocation();

    // Ignore extraneous hashchange events.
    if (createPath(nextLocation) !== createPath(location)) {
      handlePop();
    }
  });