Merge pull request #11 from oslabs-beta/backend

Backend

Author: ngoczwolinski

demo-app/src/client/Components/Nav.tsx

@@ -13,9 +13,9 @@ function Nav() {
       <Link className='link' to='/buttons'>
         Counter
       </Link>
-      <Link className='link' to='/test'>
+      {/* <Link className='link' to='/test'>
         Test
-      </Link>
+      </Link> */}
     </div>
   );
 }

src/backend/controllers/timeJump.ts

@@ -19,30 +19,40 @@ const circularComponentTable = new Set();
  *
  */
 export default function timeJump(mode: Status) {
-  // payload from index.ts is assigned to target
   /**
-   * @param target - The target snapshot to re-render
+   * The target snapshot to re-render
+   */
+  let target;
+  /**
+   * This function is to aid the removeListener for 'popstate'
+   */
+  // IMPORTANT: DO NOT move this function into return function. This function is out here so that it will not be redefined any time the return function is invoked. This is importatnt for removeEventListener for popstate to work.
+  const popStateHandler = () => {
+    initiateJump(target, mode);
+  };
+
+  /**
+   * @param inputTarget - The target snapshot to re-render. The payload from index.ts is assigned to inputTarget
    * @param firstCall - A boolean flag checking for `firstCall`
    */
-  return (target: Tree, firstCall = false): void => {
+  return (inputTarget: Tree, firstCall = false): void => {
     // Setting mode disables setState from posting messages to window
     mode.jumping = true;
+    // Set target for popStateHandler usage:
+    target = inputTarget;
     // Clearn the circularComponentTable
     if (firstCall) circularComponentTable.clear();
-    // Determine if user is navigating to another site
-    const navigating: boolean = routes.navigate(target.route);
-
+    // Determine if user is navigating to another route
+    // NOTE: Inside routes.navigate, if user is navigating, we will invoke history.go, which will go back/forth based on # of delta steps. This will trigger a popstate event. Since history.go is an async method, the event listener is the only way to invoke timeJump after we have arrived at the desirable route.
+    const navigating: boolean = routes.navigate(inputTarget.route);
     if (navigating) {
-      // Initiate popStateHandler to aid the removeListener for 'popstate'
-      const popStateHandler = () => {
-        initiateJump(target, mode);
-      };
-      // removeEventListener('popstate', popStateHandler);
-      // Background will "perform" popstate till get to the correct history location?
+      // Remove 'popstate' listener to avoid duplicate listeners
+      removeEventListener('popstate', popStateHandler);
+      // To invoke initateJump after history.go is complete
       addEventListener('popstate', popStateHandler);
     } else {
-      // Intiate the jump
-      initiateJump(target, mode);
+      // Intiate the jump immideately if not navigating
+      initiateJump(inputTarget, mode);
     }
   };
 }
@@ -53,10 +63,10 @@ export default function timeJump(mode: Status) {
  * @param mode - The current mode (i.e. jumping, time-traveling, or paused)
  */
 async function initiateJump(target, mode): Promise<void> {
-  console.log('JUMP');
   updateTreeState(target).then(() => {
     document.body.onmouseover = () => {
       mode.jumping = false;
+      console.log('mouseover');
     };
   });
 }
@@ -84,48 +94,34 @@ async function updateTreeState(target): Promise<void> {
   // Destructure component data:
   const { index, state, hooksIndex, hooksState } = target.componentData;
   // ------------------------STATEFUL CLASS COMPONENT-------------------------
-  // for stateful class components
-  // check if it is a stateful class component
-  // if yes, find the component by its index and assign it to a variable
-  // call that components setState method to reset state to the state at the time of the jump snapshot
-  //index can be zero => falsy value => DO NOT REMOVE UNDEFINED
+  // Check if it is a stateful class component
+  // Index can be zero => falsy value => DO NOT REMOVE UNDEFINED
   if (index !== undefined) {
-    // Obtain component data & its update method at the given index
+    // Obtain the BOUND update method at the given index
     const classComponent = componentActionsRecord.getComponentByIndex(index);
-    // If the user navigate to another page during jumps, Routes methods will popState until find a match => this cause changes in componentActionRecord => keep the if statement, otherwise will run into Uncaught Promise type error.
-    if (classComponent?.setState) {
-      // Update component state
-      await classComponent.setState(
-        // prevState contains the states of the snapshots we are jumping FROM, not jumping TO
-        (prevState) => state,
-      );
-    }
-    // Else statement is to ensure if a mismatch, this popstate is not the correct componentActionRecord. Return immediately to avoid traverse the entire tree
-    else return;
-
+    // Update component state
+    await classComponent.setState(
+      // prevState contains the states of the snapshots we are jumping FROM, not jumping TO
+      (prevState) => state,
+    );
     // Iterate through new children after state has been set
     target.children.forEach((child) => updateTreeState(child));
     return;
   }
 
   // ----------------------STATEFUL FUNCTIONAL COMPONENT----------------------
-  // check if component states are set with hooks
+  // Check if it is a stateful functional component
   // if yes, grab all relevant components for this snapshot by its index
   // call dispatch on each component passing in the corresponding currState value
   //index can be zero => falsy value => DO NOT REMOVE UNDEFINED
   if (hooksIndex !== undefined) {
-    // Obtain component data & its update method at the given index
+    // Obtain the array of BOUND update methods at the given indexes.
+    // NOTE: each useState will be a separate update method. So if a component have 3 useState, we will obtain an array of 3 update methods.
     const functionalComponent = componentActionsRecord.getComponentByIndexHooks(hooksIndex);
-    // If the user navigate to another page during jumps, Routes methods will popState until find a match => this cause changes in componentActionRecord => keep the if statement, otherwise will run into Uncaught Promise type error.
-    if (functionalComponent[0]?.dispatch) {
-      // Update component state
-      for (let i in functionalComponent) {
-        await functionalComponent[i].dispatch(Object.values(hooksState)[i]);
-      }
+    // Update component state
+    for (let i in functionalComponent) {
+      await functionalComponent[i].dispatch(Object.values(hooksState)[i]);
     }
-    // Else statement is to ensure if a mismatch, this popstate is not the correct componentActionRecord. Return immediately to avoid traverse the entire tree
-    else return;
-
     // Iterate through new children after state has been set
     target.children.forEach((child) => updateTreeState(child));
     return;

src/backend/models/masterState.ts

@@ -4,24 +4,35 @@
 /* eslint-disable guard-for-in */
 /* eslint-disable no-restricted-syntax */
 
+/**
+ * @type ComponentAction - an array of actions that can be performed on a component
+ */
 type ComponentAction = any[];
 
-// HookState is an array that contains a "component" for
-// every single state change that occurs in the app
+// The HookState data structure is an array that holds the current value of a hook's state, as well as a dispatch function that is used to update that state.
 // Information on these components include ComponentData as well as state
 // For class components, there will be one "component" for each snapshot
 // For functional components that utilize Hooks, there will be one "component"
 // for each setter/getter every time we have a new snapshot
 let componentActionsRecord: ComponentAction = [];
+// index keeps track of the current position in the array
 let index: number;
 index = 0;
 
 export default {
+  /**
+   * @function clear - Clears componentActionsRecord
+   */
   clear: () => {
     componentActionsRecord = [];
     index = 0;
   },
-  // Adds new component to ComponentActionsRecord
+
+  /**
+   * @function saveNew - Adds a new component to the componentActionsRecord array and returns its index.
+   * @param component
+   * @returns number
+   */
   saveNew: (component): number => {
     componentActionsRecord[index] = component;
     index++;
@@ -30,18 +41,24 @@ export default {
   },
   // ----------------------------CLASS COMPONENT--------------------------------
   /**
-   * This function is used for stateful Class Component to retrieve an object that has the bound setState method
+   * @function getComponentByIndex - This function is used for stateful Class Component to retrieve an object that has the bound setState method
    * @param inputIndex - index of component inside `componentActionsRecord` coming from `timeJump.ts`
    * @returns - an object containing the bound setState method
    */
   getComponentByIndex: (inputIndex: number): any | undefined => componentActionsRecord[inputIndex],
 
   //---------------------------FUNCTIONAL COMPONENT-----------------------------
   /**
-   * This function is used for Functional Component to retrieve an array of objects that have the bound dispatch methods.
+   * @function getComponentByIndexHooks - This function is used for Functional Component to retrieve an array of objects that have the bound dispatch methods.
    * @param inputIndex - index of component inside `componentActionsRecord` coming from `timeJump.ts`
    * @returns - an array of objects containing the bound dispatch methods
    */
   getComponentByIndexHooks: (inputIndex: Array<number> = []): any[] | undefined =>
     inputIndex.map((index) => componentActionsRecord[index]),
+  // ----------------------------------DEBUGGING--------------------------------
+  /**
+   * @function getAllComponents - This method is used for debugging purpose to access the array of setState/dispatch methods
+   * @returns - an array of objects containing the bound methods for updating state
+   */
+  getAllComponents: (): any[] => componentActionsRecord,
 };

src/backend/models/routes.ts

@@ -1,6 +1,6 @@
 /* eslint-disable max-classes-per-file */
 /* eslint-disable max-len */
-
+import componentActionsRecord from './masterState';
 /**
  * @class Route instances are created by the addRoute method on Routes. A Route instance has two properties: the url of the route and a unique id.
  */
@@ -93,7 +93,6 @@ class Routes {
    */
   navigate(route: Route): boolean {
     let targetIndex: number | undefined;
-
     // Loop through the routeHistory stack
     for (let i = 0; i < this.routeHistory.length; i += 1) {
       // If within the route history, found a match of url & id from the passed in route, update `targetIndex`
@@ -116,7 +115,6 @@ class Routes {
     // if delta != 0 => need to navigate to another page
     if (delta !== 0) {
       // Navigate to that page based on delta steps
-      console.log({ delta });
       window.history.go(delta);
       return true;
     }

src/backend/models/tree.ts

@@ -7,9 +7,12 @@
 /* eslint-disable no-param-reassign */
 import { Route } from './routes';
 
-let copyInstances = 0; // Tells you if we have already made a copy of current tree??
-const circularComponentTable = new Set<Tree>(); // Keeps track of the nodes added to the tree
-let componentNames = {}; // {componentName: frequency of use} => component name as a key and it's frequency of use as its value
+// The circularComponentTable is used to handle circular references in the state object. It keeps tracks of the components that have already been serialized. When a component is encountered for the first time, it is added to the table along with a unique identifier. If the same component is encountered again, the identifier is used to reference the previously serialized component in the output instead of serializing it again, thus avoiding the infinite loop.
+const circularComponentTable = new Set<Tree>();
+// Used to keep track of which objects have already been copied during the serialization process. This is necessary to handle circular references correctly. When an object is serialized, all its properties are copied to the serialized object. If an object property is an object itself, it needs to be serialized recursively. However, if the object being serialized has already been serialized before, it should not be serialized again to prevent an infinite loop.
+let copyInstances = 0;
+// ComponentNames is used to store a mapping between a component's unique identifier and its name. This mapping is used to reconstruct the component instances during deserialization.
+let componentNames = {};
 
 // Functions dont serialize properly so we need to scrub for that
 export function scrubUnserializableMembers(tree: Tree): Tree {
@@ -20,6 +23,11 @@ export function scrubUnserializableMembers(tree: Tree): Tree {
 }
 
 // Making a deep clone of state becuase we want to make a copy
+/**
+ * @function serializeState - In the context of React, state is often used to store data that determines the behavior and appearance of a component. By serializing the state, we can preserve the component's data across page refreshes, server-side rendering, and other transitions. Additionally, by serializing the state and passing it to a child component, we can create a deep clone of the state, which allows the child component to manipulate the state without affecting the original component. This is useful in situations where we want to keep the state of the parent component immutable, but still allow child components to modify a copy of the state.
+ * @param state - Object that contains the current state of the application or system that needs to be serialized.
+ * @returns
+ */
 export function serializeState(state) {
   try {
     // makes a deep clone
@@ -33,15 +41,14 @@ export function serializeState(state) {
 /**
  * This is the current snapshot that is being sent to the snapshots array.
  * Creates a Tree
- * @param state - {string| {}} - the tree's current state
- * @param name - {string} - the tree's name
- * @param componentData - {props: {}} - Data in the component tree
- * @param chilren - {(Tree | string)[]} - An array of children nodes
- * @param parent - {Tree} - the parent node
- * @param isExpanded - {boolean}
- * @param rtid - {any}
- * @param route -
- * @parent generates a new tree (recursive call)
+ * @param state - the current state of the component represented by this node.
+ * @param name - the name of the component represented by this node.
+ * @param componentData - an object containing the props of the component represented by this node.
+ * @param chilren - an array of child nodes.
+ * @param parent -  a reference to the parent node.
+ * @param isExpanded - a boolean value indicating whether the node is expanded in the UI.
+ * @param rtid - a unique identifier for the node.
+ * @param route - an object representing the route associated with the node.
  */
 class Tree {
   state: string | {};
@@ -87,6 +94,11 @@ class Tree {
   }
 
   // Returns a unique name ready to be used for when new components gets added to the tree
+  /**
+   * @function checkForDuplicates - Generates a unique name for a component that is being added to the component tree
+   * @param name
+   * @returns
+   */
   checkForDuplicates(name: string): string {
     // check for empty name
     if (name === '' && typeof this.rtid === 'string') {