[RFC] Type ReactComponentTreeHook

For this one, I wanted to type a non-trivial piece of the codebase and ran into the fact that we do not have types for ReactElement nor ReactInstance, so I had to create them.

I'll add comments inline

Author: vjeux

src/isomorphic/classic/element/ReactElementType.js

@@ -0,0 +1,37 @@
+/**
+ * Copyright 2016-present, Facebook, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree. An additional grant
+ * of patent rights can be found in the PATENTS file in the same directory.
+ *
+ * @flow
+ * @providesModule ReactElementType
+ */
+
+'use strict';
+
+import type { ReactInstance } from 'ReactInstanceType';
+
+export type Source = {
+  fileName: string,
+  lineNumber: number,
+};
+
+export type ReactElement = {
+  $$typeof: any,
+  type: any,
+  key: any,
+  ref: any,
+  props: any,
+  _owner: ReactInstance,
+
+  // __DEV__
+  _store: {
+    validated: bool,
+  },
+  _self: ReactElement,
+  _shadowChildren: any,
+  _source: Source,
+};

src/isomorphic/hooks/ReactComponentTreeHook.js

@@ -6,6 +6,7 @@
  * LICENSE file in the root directory of this source tree. An additional grant
  * of patent rights can be found in the PATENTS file in the same directory.
  *
+ * @flow
  * @providesModule ReactComponentTreeHook
  */
 
@@ -16,6 +17,9 @@ var ReactCurrentOwner = require('ReactCurrentOwner');
 var invariant = require('invariant');
 var warning = require('warning');
 
+import type { ReactElement, Source } from 'ReactElementType';
+import type { DebugID } from 'ReactInstanceType';
+
 function isNative(fn) {
   // Based on isNative() from Lodash
   var funcToString = Function.prototype.toString;
@@ -39,8 +43,19 @@ function isNative(fn) {
   }
 }
 
-var itemMap;
-var itemByKey;
+type Item = {
+  element: ReactElement,
+  parentID: DebugID,
+  text: ?string,
+  childIDs: Array<DebugID>,
+  isMounted: bool,
+  updateCount: number,
+};
+
+declare function get(id: DebugID): ?Item;
+declare function remove(id: DebugID): void;
+declare function set(id: DebugID, item: Item): void;
+declare function keys(): Array<DebugID>;
 
 var canUseMap = (
   typeof Array.from === 'function' &&
@@ -49,57 +64,52 @@ var canUseMap = (
 );
 
 if (canUseMap) {
-  itemMap = new Map();
-} else {
-  itemByKey = {};
-}
-
-var unmountedIDs = [];
-var rootIDs = [];
-
-// Use non-numeric keys to prevent V8 performance issues:
-// https://github.com/facebook/react/pull/7232
-function getKeyFromID(id) {
-  return '.' + id;
-}
-function getIDFromKey(key) {
-  return parseInt(key.substr(1), 10);
-}
+  var itemMap = new Map();
 
-function get(id) {
-  if (canUseMap) {
+  var get = function(id) {
     return itemMap.get(id);
-  }
-  var key = getKeyFromID(id);
-  return itemByKey[key];
-}
-
-function remove(id) {
-  if (canUseMap) {
+  };
+  var remove = function(id) {
     itemMap.delete(id);
-    return;
-  }
-  var key = getKeyFromID(id);
-  delete itemByKey[key];
-}
-
-function create(id, element, parentID) {
-  var item = {
-    element,
-    parentID,
-    text: null,
-    childIDs: [],
-    isMounted: false,
-    updateCount: 0,
   };
-  if (canUseMap) {
+  var set = function(id, item) {
     itemMap.set(id, item);
-    return;
+  };
+  var keys = function() {
+    return Array.from(itemMap.keys());
+  };
+} else {
+  var itemByKey = {};
+
+  // Use non-numeric keys to prevent V8 performance issues:
+  // https://github.com/facebook/react/pull/7232
+  function getKeyFromID(id: DebugID): string {
+    return '.' + id;
+  }
+  function getIDFromKey(key: string): DebugID {
+    return parseInt(key.substr(1), 10);
   }
-  var key = getKeyFromID(id);
-  itemByKey[key] = item;
+
+  var get = function(id) {
+    var key = getKeyFromID(id);
+    return itemByKey[key];
+  };
+  var remove = function(id) {
+    var key = getKeyFromID(id);
+    delete itemByKey[key];
+  };
+  var set = function(id, item) {
+    var key = getKeyFromID(id);
+    itemByKey[key] = item;
+  };
+  var keys = function() {
+    return Object.keys(itemByKey).map(getIDFromKey);
+  };
 }
 
+var unmountedIDs: Array<DebugID> = [];
+var rootIDs: Array<DebugID> = [];
+
 function purgeDeep(id) {
   var item = get(id);
   if (item) {
@@ -110,7 +120,7 @@ function purgeDeep(id) {
 }
 
 function describeComponentFrame(name, source, ownerName) {
-  return '\n    in ' + name + (
+  return '\n    in ' + (name || 'Unknown') + (
     source ?
       ' (at ' + source.fileName.replace(/^.*[\\\/]/, '') + ':' +
       source.lineNumber + ')' :
@@ -120,7 +130,7 @@ function describeComponentFrame(name, source, ownerName) {
   );
 }
 
-function getDisplayName(element) {
+function getDisplayName(element: ?ReactElement): string {
   if (element == null) {
     return '#empty';
   } else if (typeof element === 'string' || typeof element === 'number') {
@@ -132,7 +142,7 @@ function getDisplayName(element) {
   }
 }
 
-function describeID(id) {
+function describeID(id: DebugID): string {
   var name = ReactComponentTreeHook.getDisplayName(id);
   var element = ReactComponentTreeHook.getElement(id);
   var ownerID = ReactComponentTreeHook.getOwnerID(id);
@@ -150,8 +160,9 @@ function describeID(id) {
 }
 
 var ReactComponentTreeHook = {
-  onSetChildren(id, nextChildIDs) {
+  onSetChildren(id: DebugID, nextChildIDs: Array<DebugID>): void {
     var item = get(id);
+    invariant(item, 'Item must have been set');
     item.childIDs = nextChildIDs;
 
     for (var i = 0; i < nextChildIDs.length; i++) {
@@ -178,7 +189,7 @@ var ReactComponentTreeHook = {
         nextChild.parentID = id;
         // TODO: This shouldn't be necessary but mounting a new root during in
         // componentWillMount currently causes not-yet-mounted components to
-        // be purged from our tree data so their parent ID is missing.
+        // be purged from our tree data so their parent DebugID is missing.
       }
       invariant(
         nextChild.parentID === id,
@@ -191,11 +202,19 @@ var ReactComponentTreeHook = {
     }
   },
 
-  onBeforeMountComponent(id, element, parentID) {
-    create(id, element, parentID);
+  onBeforeMountComponent(id: DebugID, element: ReactElement, parentID: DebugID): void {
+    var item = {
+      element,
+      parentID,
+      text: null,
+      childIDs: [],
+      isMounted: false,
+      updateCount: 0,
+    };
+    set(id, item);
   },
 
-  onBeforeUpdateComponent(id, element) {
+  onBeforeUpdateComponent(id: DebugID, element: ReactElement): void {
     var item = get(id);
     if (!item || !item.isMounted) {
       // We may end up here as a result of setState() in componentWillUnmount().
@@ -205,15 +224,16 @@ var ReactComponentTreeHook = {
     item.element = element;
   },
 
-  onMountComponent(id) {
+  onMountComponent(id: DebugID): void {
     var item = get(id);
+    invariant(item, 'Item must have been set');
     item.isMounted = true;
     if (item.parentID === 0) {
       rootIDs.push(id);
     }
   },
 
-  onUpdateComponent(id) {
+  onUpdateComponent(id: DebugID): void {
     var item = get(id);
     if (!item || !item.isMounted) {
       // We may end up here as a result of setState() in componentWillUnmount().
@@ -223,7 +243,7 @@ var ReactComponentTreeHook = {
     item.updateCount++;
   },
 
-  onUnmountComponent(id) {
+  onUnmountComponent(id: DebugID): void {
     var item = get(id);
     if (item) {
       // We need to check if it exists.
@@ -242,7 +262,7 @@ var ReactComponentTreeHook = {
     unmountedIDs.push(id);
   },
 
-  purgeUnmountedComponents() {
+  purgeUnmountedComponents(): void {
     if (ReactComponentTreeHook._preventPurging) {
       // Should only be used for testing.
       return;
@@ -255,21 +275,18 @@ var ReactComponentTreeHook = {
     unmountedIDs.length = 0;
   },
 
-  isMounted(id) {
+  isMounted(id: DebugID): bool {
     var item = get(id);
     return item ? item.isMounted : false;
   },
 
-  getCurrentStackAddendum(topElement) {
+  getCurrentStackAddendum(topElement: ?ReactElement): string {
     var info = '';
     if (topElement) {
-      var type = topElement.type;
-      var name = typeof type === 'function' ?
-        type.displayName || type.name :
-        type;
+      var name = getDisplayName(topElement);
       var owner = topElement._owner;
       info += describeComponentFrame(
-        name || 'Unknown',
+        name,
         topElement._source,
         owner && owner.getName()
       );
@@ -282,7 +299,7 @@ var ReactComponentTreeHook = {
     return info;
   },
 
-  getStackAddendumByID(id) {
+  getStackAddendumByID(id: ?DebugID): string {
     var info = '';
     while (id) {
       info += describeID(id);
@@ -291,45 +308,45 @@ var ReactComponentTreeHook = {
     return info;
   },
 
-  getChildIDs(id) {
+  getChildIDs(id: DebugID): Array<DebugID> {
     var item = get(id);
     return item ? item.childIDs : [];
   },
 
-  getDisplayName(id) {
+  getDisplayName(id: DebugID): ?string {
     var element = ReactComponentTreeHook.getElement(id);
     if (!element) {
       return null;
     }
     return getDisplayName(element);
   },
 
-  getElement(id) {
+  getElement(id: DebugID): ?ReactElement {
     var item = get(id);
     return item ? item.element : null;
   },
 
-  getOwnerID(id) {
+  getOwnerID(id: DebugID): ?DebugID {
     var element = ReactComponentTreeHook.getElement(id);
     if (!element || !element._owner) {
       return null;
     }
     return element._owner._debugID;
   },
 
-  getParentID(id) {
+  getParentID(id: DebugID): ?DebugID {
     var item = get(id);
     return item ? item.parentID : null;
   },
 
-  getSource(id) {
+  getSource(id: DebugID): ?Source {
     var item = get(id);
     var element = item ? item.element : null;
     var source = element != null ? element._source : null;
     return source;
   },
 
-  getText(id) {
+  getText(id: DebugID): ?string {
     var element = ReactComponentTreeHook.getElement(id);
     if (typeof element === 'string') {
       return element;
@@ -340,20 +357,17 @@ var ReactComponentTreeHook = {
     }
   },
 
-  getUpdateCount(id) {
+  getUpdateCount(id: DebugID): number {
     var item = get(id);
     return item ? item.updateCount : 0;
   },
 
-  getRootIDs() {
+  getRootIDs(): Array<DebugID> {
     return rootIDs;
   },
 
-  getRegisteredIDs() {
-    if (canUseMap) {
-      return Array.from(itemMap.keys());
-    }
-    return Object.keys(itemByKey).map(getIDFromKey);
+  getRegisteredIDs(): Array<DebugID> {
+    return keys();
   },
 };