Compelte createTree documentation

Author: ngoczwolinski

src/backend/controllers/createTree.ts

@@ -62,7 +62,8 @@ export default function createTree(currentFiberNode: Fiber): Tree {
     } = currentFiberNode;
 
     // Obtain component name:
-    let componentName =
+    /** Name of the current component */
+    let componentName: string =
       elementType?._context?.displayName || //For ContextProvider
       elementType?._result?.name || //For lazy Component
       elementType?.render?.name ||
@@ -111,17 +112,19 @@ export default function createTree(currentFiberNode: Fiber): Tree {
     };
 
     // ---------------APPEND PROP DATA FROM REACT DEV TOOL----------------------
-    // Check to see if the parent component has any props
+    // Check to see if the currentFiberNode has any props
     if (memoizedProps) {
       switch (elementType.name) {
+        // If component comes from React Router, extract only pathname:
         case 'Router':
           componentData.props = { pathname: memoizedProps?.location?.pathname };
           break;
         case 'RenderedRoute':
           componentData.props = { pathname: memoizedProps?.match?.pathname };
           break;
+        // Else filter & format props data to ensure they are JSON stringify-able, before sending to front end
         default:
-          Object.assign(componentData.props, filterAndFormatData(memoizedProps));
+          componentData.props = filterAndFormatData(memoizedProps);
       }
     }
 
@@ -160,28 +163,23 @@ export default function createTree(currentFiberNode: Fiber): Tree {
     //   componentName = 'Context';
     // }
 
-    // // DEPRECATED: This code might have worked previously. However, with the update of React Dev Tool, context can no longer be pulled using this method.
-    // // Check to see if the component has any context:
-    // // if the component uses the useContext hook, we want to grab the context object and add it to the componentData object for that fiber
-    // // if (tag === FunctionComponent && _debugHookTypes && dependencies?.firstContext?.memoizedValue) {
-    // //   componentData.context = convertDataToString(dependencies.firstContext.memoizedValue);
-    // // }
-
     // ---------OBTAIN STATE & SET STATE METHODS FROM CLASS COMPONENT-----------
-    // Check if node is a stateful class component when user use setState.
+    // Check if currentFiberNode is a stateful class component when user use setState.
     // If user use setState to define/manage state, the state object will be stored in stateNode.state => grab the state object stored in the stateNode.state
     // Example: for tic-tac-toe demo-app: Board is a stateful component that use setState to store state data.
     if ((tag === ClassComponent || tag === IndeterminateComponent) && stateNode?.state) {
       // Save component's state and setState() function to our record for future time-travel state changing. Add record index to snapshot so we can retrieve.
       componentData.index = componentActionsRecord.saveNew(stateNode);
       // Save state information in componentData.
       componentData.state = stateNode.state;
-      // Passess to front end
+      // Pass to front end
       newState = componentData.state;
     }
 
     // --------OBTAIN STATE & DISPATCH METHODS FROM FUNCTIONAL COMPONENT--------
-    // Check if node is a hooks useState function
+    // Check if currentFiberNode is a stateful functional component when user use useState hook.
+    // If user use useState to define/manage state, the state object will be stored in memoizedState => grab the state object & its update method (dispatch) from memoizedState
+    // Example: for Stateful buttons demo-app: Increment is a stateful component that use useState hook to store state data.
     if (
       (tag === FunctionComponent ||
         tag === IndeterminateComponent ||
@@ -191,20 +189,21 @@ export default function createTree(currentFiberNode: Fiber): Tree {
     ) {
       if (memoizedState.queue) {
         try {
+          // Obtain all hooksStates & the corresponding udpate method from memoizedState
           const hooksStates = getHooksStateAndUpdateMethod(memoizedState);
+          // Obtain variable names by parsing the function definition stored in elementType.
           const hooksNames = getHooksNames(elementType.toString());
           // Intialize state & index:
-          // newState.hooksState = [];
           componentData.hooksState = {};
           componentData.hooksIndex = [];
+
           hooksStates.forEach(({ state, component }, i) => {
             // Save component's state and dispatch() function to our record for future time-travel state changing. Add record index to snapshot so we can retrieve.
             componentData.hooksIndex.push(componentActionsRecord.saveNew(component));
-            // Passess to front end
+            // Save state information in componentData.
             componentData.hooksState[hooksNames[i].varName] = state;
           });
-          // Passess to front end
-          // TODO: Refactor this, this is currently being used for Tree & Diff tabs
+          // Pass to front end
           newState = componentData.hooksState;
         } catch (err) {
           // COMMENT OUT TO AVOID PRINTTING ON THE CONSOLE OF USER - KEEP IT FOR DEBUGGING PURPOSE
@@ -223,11 +222,6 @@ export default function createTree(currentFiberNode: Fiber): Tree {
      * `rtid` - The `Root ID` is a unique identifier that is assigned to each React root instance in a React application.
      */
     let rtid: string | null = null;
-    /**
-     * The updated tree after adding the `componentData` obtained from `currentFiberNode`
-     */
-    let childNode: Tree = tree;
-    // We want to add this fiber node to the snapshot
 
     // Grab JSX Component & replace the 'fromLinkFiber' class value
     if (currentFiberNode.child?.stateNode?.setAttribute) {
@@ -246,10 +240,12 @@ export default function createTree(currentFiberNode: Fiber): Tree {
       }
       currentFiberNode.child.stateNode.classList.add(rtid);
     }
-    rtidCounter += 1; // I THINK THIS SHOULD BE UP IN THE IF STATEMENT. Still unsure the use of rtid
+    rtidCounter += 1;
 
-    // Append the childNode to the tree
-    childNode = tree.addChild(newState, componentName, componentData, rtid);
+    /**
+     * The updated tree after adding the `componentData` obtained from `currentFiberNode`
+     */
+    const childNode = tree.addChild(newState, componentName, componentData, rtid);
 
     // ---------------------TRAVERSE TO NEXT FIBERNODE--------------------------
     // If currentFiberNode has children, recurse on children

src/backend/controllers/statePropExtractors.ts

@@ -1,7 +1,7 @@
 const acorn = require('acorn');
 const jsx = require('acorn-jsx');
 const JSXParser = acorn.Parser.extend(jsx());
-import { HookStates, Fiber } from '../types/backendTypes';
+import { HookStates, HookStateItem, Fiber } from '../types/backendTypes';
 import { exclude } from '../models/filterConditions';
 
 type ReactimeData = {
@@ -10,6 +10,7 @@ type ReactimeData = {
 // ------------FILTER DATA FROM REACT DEV TOOL && CONVERT TO STRING-------------
 /**
  * This function receives raw Data from REACT DEV TOOL and filter the Data based on the exclude list. The filterd data is then converted to string (if applicable) before being sent to reacTime front end.
+ * NOTE: the formating is important since Chrome will only accept JSON.stringfiable object. Circular object & function are not JSON stringifiable.
  *
  * @param reactDevData - The data object obtained from React Devtool. Ex: memoizedProps, memoizedState
  * @param reactimeData - The cached data from the current component. This can be data about states, context and/or props of the component.
@@ -64,8 +65,10 @@ export function filterAndFormatData(
  * @return An array of array of HookStateItem objects
  *
  */
-export function getHooksStateAndUpdateMethod(memoizedState: Fiber['memoizedState']): HookStates {
-  const hooksStates: HookStates = [];
+export function getHooksStateAndUpdateMethod(
+  memoizedState: Fiber['memoizedState'],
+): Array<HookStateItem> {
+  const hooksStates: Array<HookStateItem> = [];
   while (memoizedState) {
     if (memoizedState.queue) {
       hooksStates.push({

src/backend/models/masterState.ts

@@ -3,8 +3,6 @@
 // For class components, there will be one "component" for each snapshot
 // For functional components that utilize Hooks, there will be one "component"
 
-import { index } from 'd3';
-
 // for each setter/getter every time we have a new snapshot
 let componentActionsRecord = [];
 
@@ -18,12 +16,11 @@ export default {
 
   /**
    * @function saveNew - Adds a new component to the componentActionsRecord array and returns its index.
-   * @param component
-   * @returns number
+   * @param component - An object that contains bound update method. For class component, the udpate method is `setState`. For functional component, the update method is `dispatch`.
+   * @returns - the index of the newly added component
    */
   saveNew: (component): number => {
-    componentActionsRecord.push(component);
-    return componentActionsRecord.length - 1;
+    return componentActionsRecord.push(component) - 1;
   },
   // ----------------------------CLASS COMPONENT--------------------------------
   /**

src/backend/types/backendTypes.ts

@@ -42,25 +42,38 @@ export interface MsgData {
 
 /**
  * @type ComponentData -
- * @member index -
- * @member hooksIndex -
- * @member actualDuration -
- * @member actualStartTime -
- * @member selfBaseDuration -
- * @member treeBaseDuration -
- * @member props -
+ * @member actualDuration - The time taken to render the current Fiber node and its descendants during the previous render cycle. This value is used to optimize the rendering of components and to provide performance metrics to developers.
+ * @member actualStartTime - The time at which the rendering of the current Fiber node started during the previous render cycle.
+ * @member context - {in experiment} - An object contains all context information of the current component
+ * @member index - {class component only} - The index of the bound setState method stored in `componentActionsRecord`
+ * @member hooksState - {functional component only} - An object contains all states of the current functional component
+ * @member hooksIndex - {functional component only} - An array of index of the bound dispatch method stored in `componentActionsRecord`
+ * @member props - An object contains all props of the current component
+ * @member selfBaseDuration - The base duration of the current Fiber node's render phase (excluding the time taken to render its children). This field is only set when the enableProfilerTimer flag is enabled.
+ * @member state - {class component only} - An object contains all states of the current class component
+ * @member treeBaseDuration - The total base duration of the current Fiber node's subtree. This field is only set when the enableProfilerTimer flag is enabled.
  */
 export interface ComponentData {
+  /** The time taken to render the current Fiber node and its descendants during the previous render cycle. */
   actualDuration?: number;
+  /** The time at which the rendering of the current Fiber node started during the previous render cycle. */
   actualStartTime?: number;
-  selfBaseDuration?: number;
-  treeBaseDuration?: number;
-  props: { [key: string]: any };
+  /** {in experiment} - An object contains all context information of the current component */
   context: {};
-  state: { [key: string]: any } | null;
+  /** {class component only} - The index of the bound setState method stored in `componentActionsRecord`  */
+  index: number | null;
+  /** {functional component only} - An object contains all states of the current functional component */
   hooksState: {} | null;
+  /** {functional component only} - An array of index of the bound dispatch method stored in `componentActionsRecord` */
   hooksIndex: number[] | null;
-  index: number | null;
+  /** An object contains all props of the current component */
+  props: { [key: string]: any };
+  /** The base duration of the current Fiber node's render phase (excluding the time taken to render its children). */
+  selfBaseDuration?: number;
+  /** An object contains all states of the current class component */
+  state: { [key: string]: any } | null;
+  /** The total base duration of the current Fiber node's subtree. */
+  treeBaseDuration?: number;
 }
 
 /**
@@ -108,9 +121,9 @@ export type WorkTag =
 export const FunctionComponent = 0;
 export const ClassComponent = 1;
 /** Before we know whether it is function or class */
-export const IndeterminateComponent = 2; 
+export const IndeterminateComponent = 2;
 /** Root of a host tree. Could be nested inside another node. */
-export const HostRoot = 3; 
+export const HostRoot = 3;
 /** A subtree. Could be an entry point to a different renderer. */
 export const HostPortal = 4;
 /**