use(promise)

Adds experimental support to Fiber for unwrapping the value of a promise
inside a component. It is not yet implemented for Server Components, 
but that is planned.

If promise has already resolved, the value can be unwrapped
"immediately" without showing a fallback. The trick we use to implement
this is to yield to the main thread (literally suspending the work
loop), wait for the microtask queue to drain, then check if the promise
resolved in the meantime. If so, we can resume the last attempted fiber
without unwinding the stack. This functionality was implemented in 
previous commits.

Another feature is that the promises do not need to be cached between
attempts. Because we assume idempotent execution of components, React
will track the promises that were used during the previous attempt and
reuse the result. You shouldn't rely on this property, but during
initial render it mostly just works. Updates are trickier, though,
because if you used an uncached promise, we have no way of knowing 
whether the underlying data has changed, so we have to unwrap the
promise every time. It will still work, but it's inefficient and can
lead to unnecessary fallbacks if it happens during a discrete update.

When we implement this for Server Components, this will be less of an
issue because there are no updates in that environment. However, it's
still better for performance to cache data requests, so the same
principles largely apply.

The intention is that this will eventually be the only supported way to
suspend on arbitrary promises. Throwing a promise directly will
be deprecated.

packages/react-reconciler/src/ReactFiberHooks.new.js

@@ -14,6 +14,7 @@ import type {
   ReactContext,
   StartTransitionOptions,
   Usable,
+  Thenable,
 } from 'shared/ReactTypes';
 import type {Fiber, Dispatcher, HookType} from './ReactInternalTypes';
 import type {Lanes, Lane} from './ReactFiberLane.new';
@@ -121,6 +122,10 @@ import {
 } from './ReactFiberConcurrentUpdates.new';
 import {getTreeId} from './ReactFiberTreeContext.new';
 import {now} from './Scheduler';
+import {
+  trackUsedThenable,
+  getPreviouslyUsedThenableAtIndex,
+} from './ReactFiberWakeable.new';
 
 const {ReactCurrentDispatcher, ReactCurrentBatchConfig} = ReactSharedInternals;
 
@@ -206,6 +211,9 @@ let didScheduleRenderPhaseUpdate: boolean = false;
 let didScheduleRenderPhaseUpdateDuringThisPass: boolean = false;
 // Counts the number of useId hooks in this component.
 let localIdCounter: number = 0;
+// Counts number of `use`-d thenables
+let thenableIndexCounter: number = 0;
+
 // Used for ids that are generated completely client-side (i.e. not during
 // hydration). This counter is global, so client ids are not stable across
 // render attempts.
@@ -404,6 +412,7 @@ export function renderWithHooks<Props, SecondArg>(
 
   // didScheduleRenderPhaseUpdate = false;
   // localIdCounter = 0;
+  // thenableIndexCounter = 0;
 
   // TODO Warn if no hooks are used at all during mount, then some are used during update.
   // Currently we will identify the update render as a mount because memoizedState === null.
@@ -442,6 +451,7 @@ export function renderWithHooks<Props, SecondArg>(
     do {
       didScheduleRenderPhaseUpdateDuringThisPass = false;
       localIdCounter = 0;
+      thenableIndexCounter = 0;
 
       if (numberOfReRenders >= RE_RENDER_LIMIT) {
         throw new Error(
@@ -525,6 +535,7 @@ export function renderWithHooks<Props, SecondArg>(
   didScheduleRenderPhaseUpdate = false;
   // This is reset by checkDidRenderIdHook
   // localIdCounter = 0;
+  thenableIndexCounter = 0;
 
   if (didRenderTooFewHooks) {
     throw new Error(
@@ -632,6 +643,7 @@ export function resetHooksAfterThrow(): void {
 
   didScheduleRenderPhaseUpdateDuringThisPass = false;
   localIdCounter = 0;
+  thenableIndexCounter = 0;
 }
 
 function mountWorkInProgressHook(): Hook {
@@ -724,7 +736,70 @@ function createFunctionComponentUpdateQueue(): FunctionComponentUpdateQueue {
 }
 
 function use<T>(usable: Usable<T>): T {
-  throw new Error('Not implemented.');
+  if (
+    usable !== null &&
+    typeof usable === 'object' &&
+    typeof usable.then === 'function'
+  ) {
+    // This is a thenable.
+    const thenable: Thenable<T> = (usable: any);
+
+    // Track the position of the thenable within this fiber.
+    const index = thenableIndexCounter;
+    thenableIndexCounter += 1;
+
+    switch (thenable.status) {
+      case 'fulfilled': {
+        const fulfilledValue: T = thenable.value;
+        return fulfilledValue;
+      }
+      case 'rejected': {
+        const rejectedError = thenable.reason;
+        throw rejectedError;
+      }
+      default: {
+        const prevThenableAtIndex: Thenable<T> | null = getPreviouslyUsedThenableAtIndex(
+          index,
+        );
+        if (prevThenableAtIndex !== null) {
+          switch (prevThenableAtIndex.status) {
+            case 'fulfilled': {
+              const fulfilledValue: T = prevThenableAtIndex.value;
+              return fulfilledValue;
+            }
+            case 'rejected': {
+              const rejectedError: mixed = prevThenableAtIndex.reason;
+              throw rejectedError;
+            }
+            default: {
+              // The thenable still hasn't resolved. Suspend with the same
+              // thenable as last time to avoid redundant listeners.
+              throw prevThenableAtIndex;
+            }
+          }
+        } else {
+          // This is the first time something has been used at this index.
+          // Stash the thenable at the current index so we can reuse it during
+          // the next attempt.
+          trackUsedThenable(thenable, index);
+
+          // Suspend.
+          // TODO: Throwing here is an implementation detail that allows us to
+          // unwind the call stack. But we shouldn't allow it to leak into
+          // userspace. Throw an opaque placeholder value instead of the
+          // actual thenable. If it doesn't get captured by the work loop, log
+          // a warning, because that means something in userspace must have
+          // caught it.
+          throw thenable;
+        }
+      }
+    }
+  }
+
+  // TODO: Add support for Context
+
+  // eslint-disable-next-line react-internal/safe-string-coercion
+  throw new Error('An unsupported type was passed to use(): ' + String(usable));
 }
 
 function basicStateReducer<S>(state: S, action: BasicStateAction<S>): S {

packages/react-reconciler/src/ReactFiberHooks.old.js

@@ -14,6 +14,7 @@ import type {
   ReactContext,
   StartTransitionOptions,
   Usable,
+  Thenable,
 } from 'shared/ReactTypes';
 import type {Fiber, Dispatcher, HookType} from './ReactInternalTypes';
 import type {Lanes, Lane} from './ReactFiberLane.old';
@@ -121,6 +122,10 @@ import {
 } from './ReactFiberConcurrentUpdates.old';
 import {getTreeId} from './ReactFiberTreeContext.old';
 import {now} from './Scheduler';
+import {
+  trackUsedThenable,
+  getPreviouslyUsedThenableAtIndex,
+} from './ReactFiberWakeable.old';
 
 const {ReactCurrentDispatcher, ReactCurrentBatchConfig} = ReactSharedInternals;
 
@@ -206,6 +211,9 @@ let didScheduleRenderPhaseUpdate: boolean = false;
 let didScheduleRenderPhaseUpdateDuringThisPass: boolean = false;
 // Counts the number of useId hooks in this component.
 let localIdCounter: number = 0;
+// Counts number of `use`-d thenables
+let thenableIndexCounter: number = 0;
+
 // Used for ids that are generated completely client-side (i.e. not during
 // hydration). This counter is global, so client ids are not stable across
 // render attempts.
@@ -404,6 +412,7 @@ export function renderWithHooks<Props, SecondArg>(
 
   // didScheduleRenderPhaseUpdate = false;
   // localIdCounter = 0;
+  // thenableIndexCounter = 0;
 
   // TODO Warn if no hooks are used at all during mount, then some are used during update.
   // Currently we will identify the update render as a mount because memoizedState === null.
@@ -442,6 +451,7 @@ export function renderWithHooks<Props, SecondArg>(
     do {
       didScheduleRenderPhaseUpdateDuringThisPass = false;
       localIdCounter = 0;
+      thenableIndexCounter = 0;
 
       if (numberOfReRenders >= RE_RENDER_LIMIT) {
         throw new Error(
@@ -525,6 +535,7 @@ export function renderWithHooks<Props, SecondArg>(
   didScheduleRenderPhaseUpdate = false;
   // This is reset by checkDidRenderIdHook
   // localIdCounter = 0;
+  thenableIndexCounter = 0;
 
   if (didRenderTooFewHooks) {
     throw new Error(
@@ -632,6 +643,7 @@ export function resetHooksAfterThrow(): void {
 
   didScheduleRenderPhaseUpdateDuringThisPass = false;
   localIdCounter = 0;
+  thenableIndexCounter = 0;
 }
 
 function mountWorkInProgressHook(): Hook {
@@ -724,7 +736,70 @@ function createFunctionComponentUpdateQueue(): FunctionComponentUpdateQueue {
 }
 
 function use<T>(usable: Usable<T>): T {
-  throw new Error('Not implemented.');
+  if (
+    usable !== null &&
+    typeof usable === 'object' &&
+    typeof usable.then === 'function'
+  ) {
+    // This is a thenable.
+    const thenable: Thenable<T> = (usable: any);
+
+    // Track the position of the thenable within this fiber.
+    const index = thenableIndexCounter;
+    thenableIndexCounter += 1;
+
+    switch (thenable.status) {
+      case 'fulfilled': {
+        const fulfilledValue: T = thenable.value;
+        return fulfilledValue;
+      }
+      case 'rejected': {
+        const rejectedError = thenable.reason;
+        throw rejectedError;
+      }
+      default: {
+        const prevThenableAtIndex: Thenable<T> | null = getPreviouslyUsedThenableAtIndex(
+          index,
+        );
+        if (prevThenableAtIndex !== null) {
+          switch (prevThenableAtIndex.status) {
+            case 'fulfilled': {
+              const fulfilledValue: T = prevThenableAtIndex.value;
+              return fulfilledValue;
+            }
+            case 'rejected': {
+              const rejectedError: mixed = prevThenableAtIndex.reason;
+              throw rejectedError;
+            }
+            default: {
+              // The thenable still hasn't resolved. Suspend with the same
+              // thenable as last time to avoid redundant listeners.
+              throw prevThenableAtIndex;
+            }
+          }
+        } else {
+          // This is the first time something has been used at this index.
+          // Stash the thenable at the current index so we can reuse it during
+          // the next attempt.
+          trackUsedThenable(thenable, index);
+
+          // Suspend.
+          // TODO: Throwing here is an implementation detail that allows us to
+          // unwind the call stack. But we shouldn't allow it to leak into
+          // userspace. Throw an opaque placeholder value instead of the
+          // actual thenable. If it doesn't get captured by the work loop, log
+          // a warning, because that means something in userspace must have
+          // caught it.
+          throw thenable;
+        }
+      }
+    }
+  }
+
+  // TODO: Add support for Context
+
+  // eslint-disable-next-line react-internal/safe-string-coercion
+  throw new Error('An unsupported type was passed to use(): ' + String(usable));
 }
 
 function basicStateReducer<S>(state: S, action: BasicStateAction<S>): S {

packages/react-reconciler/src/ReactFiberLane.new.js

@@ -403,7 +403,11 @@ export function markStarvedLanesAsExpired(
   // Iterate through the pending lanes and check if we've reached their
   // expiration time. If so, we'll assume the update is being starved and mark
   // it as expired to force it to finish.
-  let lanes = pendingLanes;
+  //
+  // We exclude retry lanes because those must always be time sliced, in order
+  // to unwrap uncached promises.
+  // TODO: Write a test for this
+  let lanes = pendingLanes & ~RetryLanes;
   while (lanes > 0) {
     const index = pickArbitraryLaneIndex(lanes);
     const lane = 1 << index;
@@ -435,7 +439,15 @@ export function getHighestPriorityPendingLanes(root: FiberRoot) {
   return getHighestPriorityLanes(root.pendingLanes);
 }
 
-export function getLanesToRetrySynchronouslyOnError(root: FiberRoot): Lanes {
+export function getLanesToRetrySynchronouslyOnError(
+  root: FiberRoot,
+  originallyAttemptedLanes: Lanes,
+): Lanes {
+  if (root.errorRecoveryDisabledLanes & originallyAttemptedLanes) {
+    // The error recovery mechanism is disabled until these lanes are cleared.
+    return NoLanes;
+  }
+
   const everythingButOffscreen = root.pendingLanes & ~OffscreenLane;
   if (everythingButOffscreen !== NoLanes) {
     return everythingButOffscreen;
@@ -646,6 +658,8 @@ export function markRootFinished(root: FiberRoot, remainingLanes: Lanes) {
 
   root.entangledLanes &= remainingLanes;
 
+  root.errorRecoveryDisabledLanes &= remainingLanes;
+
   const entanglements = root.entanglements;
   const eventTimes = root.eventTimes;
   const expirationTimes = root.expirationTimes;

packages/react-reconciler/src/ReactFiberLane.old.js

@@ -403,7 +403,11 @@ export function markStarvedLanesAsExpired(
   // Iterate through the pending lanes and check if we've reached their
   // expiration time. If so, we'll assume the update is being starved and mark
   // it as expired to force it to finish.
-  let lanes = pendingLanes;
+  //
+  // We exclude retry lanes because those must always be time sliced, in order
+  // to unwrap uncached promises.
+  // TODO: Write a test for this
+  let lanes = pendingLanes & ~RetryLanes;
   while (lanes > 0) {
     const index = pickArbitraryLaneIndex(lanes);
     const lane = 1 << index;
@@ -436,11 +440,22 @@ export function getHighestPriorityPendingLanes(root: FiberRoot) {
 }
 
 export function getLanesToRetrySynchronouslyOnError(root: FiberRoot): Lanes {
-  const everythingButOffscreen = root.pendingLanes & ~OffscreenLane;
-  if (everythingButOffscreen !== NoLanes) {
-    return everythingButOffscreen;
+  const pendingLanes = root.pendingLanes;
+
+  // Only includes lanes that include actual updates, not Suspense retries.
+  // We omit Suspense retries because they must be allowed to yield to
+  // microtasks, so that they can unwrap the value of an unmemoized promise.
+  // (Unmemoized promises can only be unwrapped by yielding to the main thread.)
+  //
+  // We also omit OffscreenLane in this step because we only want to perform
+  // prerendering work after all the normal rendering work has finished.
+  const updateLanes = pendingLanes & ~(OffscreenLane | RetryLanes);
+  if (updateLanes !== NoLanes) {
+    return updateLanes;
   }
-  if (everythingButOffscreen & OffscreenLane) {
+
+  // Prerendered lanes
+  if (pendingLanes & OffscreenLane) {
     return OffscreenLane;
   }
   return NoLanes;

packages/react-reconciler/src/ReactFiberRoot.new.js

@@ -70,6 +70,7 @@ function FiberRootNode(
   this.expiredLanes = NoLanes;
   this.mutableReadLanes = NoLanes;
   this.finishedLanes = NoLanes;
+  this.errorRecoveryDisabledLanes = NoLanes;
 
   this.entangledLanes = NoLanes;
   this.entanglements = createLaneMap(NoLanes);