Documenting linkFiber & tree files

Author: ngoczwolinski

src/backend/linkFiber.ts

@@ -391,6 +391,26 @@ function createTree(
   }
   return tree;
 }
+type version = undefined | { version: string };
+/**
+ * @interface DevTools - A global object provided by the React Developer Tools extension. It provides a set of methods that allow developers to inspect and manipulate React components in the browser.
+ */
+interface DevTools {
+  /**
+   * @property renderers - an Map object containing information about the React renders that are currently active on the page. The react version being used can be obtained at key = 1.
+   */
+  renderers: Map<1, undefined | { version: string }>;
+  /**
+   * @method getFiberRoots - a method that return a fiber root {set}
+   * @param renderID - the ID of the node???
+   * @return A set of fiber root.
+   */
+  getFiberRoots: (renderID: number) => Set<number>;
+
+  onCommitFiberRoot: any;
+}
+
+interface ReactInstance {}
 
 /**
  * @method linkFiber
@@ -400,31 +420,34 @@ function createTree(
  * linkFiber contains core module functionality, exported as an anonymous function.
  */
 export default (snap: Snapshot, mode: Mode): (() => void) => {
-  // checks for visiblity of document
-  function onVisibilityChange(): void {
-    // hidden property = background tab/minimized window
+  // Checks for visiblity of document
+  function onVisibilityChange() {
+    // Hidden property = background tab/minimized window
     doWork = !document.hidden;
   }
   return () => {
     // react devtools global hook is a global object that was injected by the React Devtools content script, allows access to fiber nodes and react version
-    const devTools = window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+    const devTools: undefined | DevTools = window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+    console.log('linkFiber.ts', { devTools });
     // check if reactDev Tools is installed
     if (!devTools) {
       return;
     }
+    // if reactDev Tools is installed, send a message to front end
     window.postMessage(
       {
         action: 'devToolsInstalled',
         payload: 'devToolsInstalled',
       },
       '*',
     );
-    // reactInstance returns an object of the react, 1st element in map
+    // Obtain reaction application information. If target application is not a React App, this will return null.
     const reactInstance = devTools.renderers.get(1);
     // if no React Instance found then target is not a compatible app
     if (!reactInstance) {
       return;
     }
+    // we may want to add try/catch
     window.postMessage(
       {
         action: 'aReactApp',
@@ -439,7 +462,9 @@ export default (snap: Snapshot, mode: Mode): (() => void) => {
     document.addEventListener('visibilitychange', onVisibilityChange);
 
     if (reactInstance && reactInstance.version) {
+      // Obtain the fiber
       fiberRoot = devTools.getFiberRoots(1).values().next().value;
+      console.log('LinkFiber', { fiberRoot });
       // React has inherent methods that are called with react fiber
       // we attach new functionality without compromising the original work that onCommitFiberRoot does
       const addOneMoreStep = function (original) {

src/backend/tree.ts

@@ -6,20 +6,23 @@
 /* eslint-disable no-console */
 /* eslint-disable no-param-reassign */
 
-let copyInstances = 0;
-const circularComponentTable = new Set<Tree>();
-let componentNames = {};
+// ~~ I dont like the fact that this are global variables ~~ - Zack
+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
 
-// Removes unserializable state data such as functions
+// Functions dont serialize properly so we need to scrub for that
 function scrubUnserializableMembers(tree: Tree): Tree {
   Object.entries(tree.state).forEach((keyValuePair) => {
     if (typeof keyValuePair[1] === 'function') tree.state[keyValuePair[0]] = 'function';
   });
   return tree;
 }
 
+// Making a deep clone of an object
 function serializeState(state) {
   try {
+    // makes a deep clone, but this way can be very slow
     return JSON.parse(JSON.stringify(state));
   } catch (e) {
     return 'circularState';
@@ -29,9 +32,11 @@ function serializeState(state) {
 /**
  * This is the current snapshot that is being sent to the snapshots array.
  * Creates a Tree
- * @param state : the tree's current state
- * @param name : the tree's name
- * @param componentData : Data in the component 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
  * @parent generates a new tree (recursive call)
  */
 class Tree {
@@ -77,37 +82,54 @@ class Tree {
     this.rtid = rtid;
   }
 
-  // Returns a unique name ready to be used
+  // Returns a unique name ready to be used for when new components gets added to the tree
   checkForDuplicates(name: string): string {
     // check for empty name
     if (name === '' && typeof this.rtid === 'string') {
       name = this.rtid.replace('fromLinkFiber', '');
     }
+    // if we are at root, then make sure componentNames is an empty
     if (this.state === 'root') componentNames = {};
     // check for duplicate
     else if (componentNames[name] !== undefined) {
-      const count = componentNames[name] + 1;
-      const newName = name + count;
+      // if name exists in componentNames object, grab count and add 1
+      const count: number = componentNames[name] + 1;
+      // declare a new name variable
+      const newName: string = name + count;
+      // update name count in object
       componentNames[name] = count;
+      // return newName
       return newName;
     }
+    // add name in componentsName with value of 0
     componentNames[name] = 0;
+    // return name
     return name;
   }
 
   addChild(state: string | {}, name: string, componentData: {}, rtid: any): Tree {
+    // gets unique name by calling checkForDuplicates method
     const uniqueName = this.checkForDuplicates(name);
+    // instantiates new child Tree with state, uniqueName, componentData and rtid
     const newChild: Tree = new Tree(state, uniqueName, componentData, rtid);
+    // updating newChild parent to "this"
     newChild.parent = this;
+    // adds newChild to children array
     this.children.push(newChild);
+    // return newChild
     return newChild;
   }
 
   addSibling(state: string | {}, name: string, componentData: {}, rtid: any): Tree {
+    // gets unique name by calling checkForDuplicates method
     const uniqueName = this.checkForDuplicates(name);
+    // instantiate new sibilng tree with state, uniqueName, componentName and rtid
     const newSibling: Tree = new Tree(state, uniqueName, componentData, rtid);
+    // updating newSibling parent to be the parent of "this" which refers to sibling node
     newSibling.parent = this.parent;
+    // adds newSibling to children array
     this.parent.children.push(newSibling);
+    // return newSibling
     return newSibling;
   }
 
@@ -119,14 +141,18 @@ class Tree {
      * @object circularComponentTable : Clears circular component table only on first call, not recursive ones
      *
      */
+    // if we havent made a copy of the tree, increment copyInstances and clear cicularComponentTable set
     if (copyInstances === 0) {
       copyInstances++;
       circularComponentTable.clear();
     }
     // creates copy of present node
     let copy: Tree = new Tree(this.state, this.name, this.componentData, this.rtid);
+    // you want to get rid of the parentNode
     delete copy.parent;
+    // add to circulareComponentTable
     circularComponentTable.add(this);
+    // 
     copy = scrubUnserializableMembers(copy);
 
     // creates copy of each child of the present node

src/backend/types/backendTypes.ts

@@ -3,31 +3,56 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import Tree from '../tree';
 
+/**
+ * The snapshot of the current tree
+ * @param tree - {Tree} - The tree structure to send to front end
+ * @param unfilteredTree - {null} - The current mode (i.e. jumping, time-traveling, or paused)
+ */
 export interface Snapshot {
   tree: Tree;
   unfilteredTree: null;
 }
 
+/**
+ * Where we
+ * @param jumping - whether we are jumping steps by
+ * @param paused - true/false for whether pausing to see the state
+ */
 export interface Mode {
   jumping: boolean;
   paused: boolean;
 }
 
+/**
+ *
+ */
 export interface SnapshotNode {
   name: string;
   state: {
     location?: any;
   };
   children: any[];
 }
-
+/**
+ * @param data - an object with action & payload properties
+ */
 export interface MsgData {
   data: {
     action: string;
     payload: any;
   };
 }
 
+/**
+ *
+ * @param index -
+ * @param hooksIndex -
+ * @param actualDuration -
+ * @param actualStartTime -
+ * @param selfBaseDuration -
+ * @param treeBaseDuration -
+ * @param props -
+ */
 export interface ComponentData {
   index?: number;
   hooksIndex?: number;
@@ -38,11 +63,19 @@ export interface ComponentData {
   props?: any;
 }
 
+/**
+ * @param state -
+ * @param component -
+ */
 export interface HookStateItem {
   state: any;
   component: any;
 }
 
+/**
+ * HookeStates is an array of HookeStateItem
+ * Each HookStateItem is an object with state & component properties
+ */
 export type HookStates = Array<HookStateItem>;
 
 export interface State {