useMutableSource hook (facebook#18000)

useMutableSource hook

useMutableSource() enables React components to safely and efficiently read from a mutable external source in Concurrent Mode. The API will detect mutations that occur during a render to avoid tearing and it will automatically schedule updates when the source is mutated.

RFC: reactjs/rfcs#147

Author: Brian Vaughn

packages/react-debug-tools/src/ReactDebugHooks.js

@@ -8,6 +8,9 @@
  */
 
 import type {
+  MutableSource,
+  MutableSourceGetSnapshotFn,
+  MutableSourceSubscribeFn,
   ReactContext,
   ReactProviderType,
   ReactEventResponder,
@@ -72,6 +75,16 @@ function getPrimitiveStackCache(): Map<string, Array<any>> {
       Dispatcher.useDebugValue(null);
       Dispatcher.useCallback(() => {});
       Dispatcher.useMemo(() => null);
+      Dispatcher.useMutableSource(
+        {
+          _source: {},
+          _getVersion: () => 1,
+          _workInProgressVersionPrimary: null,
+          _workInProgressVersionSecondary: null,
+        },
+        () => null,
+        () => () => {},
+      );
     } finally {
       readHookLog = hookLog;
       hookLog = [];
@@ -229,6 +242,23 @@ function useMemo<T>(
   return value;
 }
 
+function useMutableSource<Source, Snapshot>(
+  source: MutableSource<Source>,
+  getSnapshot: MutableSourceGetSnapshotFn<Source, Snapshot>,
+  subscribe: MutableSourceSubscribeFn<Source, Snapshot>,
+): Snapshot {
+  // useMutableSource() composes multiple hooks internally.
+  // Advance the current hook index the same number of times
+  // so that subsequent hooks have the right memoized state.
+  nextHook(); // MutableSource
+  nextHook(); // State
+  nextHook(); // Effect
+  nextHook(); // Effect
+  const value = getSnapshot(source._source);
+  hookLog.push({primitive: 'MutableSource', stackError: new Error(), value});
+  return value;
+}
+
 function useResponder(
   responder: ReactEventResponder<any, any>,
   listenerProps: Object,
@@ -299,6 +329,7 @@ const Dispatcher: DispatcherType = {
   useState,
   useResponder,
   useTransition,
+  useMutableSource,
   useDeferredValue,
   useEvent,
 };

packages/react-debug-tools/src/__tests__/ReactHooksInspectionIntegration-test.js

@@ -785,4 +785,38 @@ describe('ReactHooksInspectionIntegration', () => {
       },
     ]);
   });
+
+  if (__EXPERIMENTAL__) {
+    it('should support composite useMutableSource hook', () => {
+      const mutableSource = React.createMutableSource({}, () => 1);
+      function Foo(props) {
+        React.useMutableSource(
+          mutableSource,
+          () => 'snapshot',
+          () => {},
+        );
+        React.useMemo(() => 'memo', []);
+        return <div />;
+      }
+      let renderer = ReactTestRenderer.create(<Foo />);
+      let childFiber = renderer.root.findByType(Foo)._currentFiber();
+      let tree = ReactDebugTools.inspectHooksOfFiber(childFiber);
+      expect(tree).toEqual([
+        {
+          id: 0,
+          isStateEditable: false,
+          name: 'MutableSource',
+          value: 'snapshot',
+          subHooks: [],
+        },
+        {
+          id: 1,
+          isStateEditable: false,
+          name: 'Memo',
+          value: 'memo',
+          subHooks: [],
+        },
+      ]);
+    });
+  }
 });

packages/react-dom/src/server/ReactPartialRendererHooks.js

@@ -13,6 +13,9 @@ import type {
 } from 'react-reconciler/src/ReactFiberHooks';
 import type {ThreadID} from './ReactThreadIDAllocator';
 import type {
+  MutableSource,
+  MutableSourceGetSnapshotFn,
+  MutableSourceSubscribeFn,
   ReactContext,
   ReactEventResponderListener,
 } from 'shared/ReactTypes';
@@ -461,6 +464,18 @@ function useResponder(responder, props): ReactEventResponderListener<any, any> {
   };
 }
 
+// TODO Decide on how to implement this hook for server rendering.
+// If a mutation occurs during render, consider triggering a Suspense boundary
+// and falling back to client rendering.
+function useMutableSource<Source, Snapshot>(
+  source: MutableSource<Source>,
+  getSnapshot: MutableSourceGetSnapshotFn<Source, Snapshot>,
+  subscribe: MutableSourceSubscribeFn<Source, Snapshot>,
+): Snapshot {
+  resolveCurrentlyRenderingComponent();
+  return getSnapshot(source._source);
+}
+
 function useDeferredValue<T>(value: T, config: TimeoutConfig | null | void): T {
   resolveCurrentlyRenderingComponent();
   return value;
@@ -510,4 +525,6 @@ export const Dispatcher: DispatcherType = {
   useDeferredValue,
   useTransition,
   useEvent,
+  // Subscriptions are not setup in a server environment.
+  useMutableSource,
 };

packages/react-reconciler/src/ReactFiberBeginWork.js

@@ -180,7 +180,7 @@ import {
   markSpawnedWork,
   requestCurrentTimeForUpdate,
   retryDehydratedSuspenseBoundary,
-  scheduleWork,
+  scheduleUpdateOnFiber,
   renderDidSuspendDelayIfPossible,
   markUnprocessedUpdateTime,
 } from './ReactFiberWorkLoop';
@@ -2121,7 +2121,7 @@ function updateDehydratedSuspenseComponent(
         // at even higher pri.
         let attemptHydrationAtExpirationTime = renderExpirationTime + 1;
         suspenseState.retryTime = attemptHydrationAtExpirationTime;
-        scheduleWork(current, attemptHydrationAtExpirationTime);
+        scheduleUpdateOnFiber(current, attemptHydrationAtExpirationTime);
         // TODO: Early abort this render.
       } else {
         // We have already tried to ping at a higher priority than we're rendering with

packages/react-reconciler/src/ReactFiberClassComponent.js

@@ -53,7 +53,7 @@ import {readContext} from './ReactFiberNewContext';
 import {
   requestCurrentTimeForUpdate,
   computeExpirationForFiber,
-  scheduleWork,
+  scheduleUpdateOnFiber,
 } from './ReactFiberWorkLoop';
 import {requestCurrentSuspenseConfig} from './ReactFiberSuspenseConfig';
 
@@ -200,7 +200,7 @@ const classComponentUpdater = {
     }
 
     enqueueUpdate(fiber, update);
-    scheduleWork(fiber, expirationTime);
+    scheduleUpdateOnFiber(fiber, expirationTime);
   },
   enqueueReplaceState(inst, payload, callback) {
     const fiber = getInstance(inst);
@@ -224,7 +224,7 @@ const classComponentUpdater = {
     }
 
     enqueueUpdate(fiber, update);
-    scheduleWork(fiber, expirationTime);
+    scheduleUpdateOnFiber(fiber, expirationTime);
   },
   enqueueForceUpdate(inst, callback) {
     const fiber = getInstance(inst);
@@ -247,7 +247,7 @@ const classComponentUpdater = {
     }
 
     enqueueUpdate(fiber, update);
-    scheduleWork(fiber, expirationTime);
+    scheduleUpdateOnFiber(fiber, expirationTime);
   },
 };
 

packages/react-reconciler/src/ReactFiberCompleteWork.js

@@ -26,6 +26,7 @@ import type {
   SuspenseListRenderState,
 } from './ReactFiberSuspenseComponent';
 import type {SuspenseContext} from './ReactFiberSuspenseContext';
+import {resetWorkInProgressVersions as resetMutableSourceWorkInProgressVersions} from './ReactMutableSource';
 
 import {now} from './SchedulerWithReactIntegration';
 
@@ -662,6 +663,7 @@ function completeWork(
     case HostRoot: {
       popHostContainer(workInProgress);
       popTopLevelLegacyContextObject(workInProgress);
+      resetMutableSourceWorkInProgressVersions();
       const fiberRoot = (workInProgress.stateNode: FiberRoot);
       if (fiberRoot.pendingContext) {
         fiberRoot.context = fiberRoot.pendingContext;