feat: deferred API updates (#9095)

* fix: keep loaderData as promises and track values internally

* chore: rename <Deferred> -> <Await>

* chore: rename useDeferredData -> useAwaitedData

* bundle bump

* Fix up example of raw promise

* clean up await error boundary

* fix: cancel fetcher deferred loads on revalidations

* Handle fetcher deferred rejections at error boundaries

* change Await prop from value -> promise

* Add changeset

* Add test for not proying settled values through

* Add tests for raw promises and <Await>

* Handle raw values with Await

* add useAsyncError, support raw objects, stop supporting arrays and single promises

* deferred() -> defer()

* change <Await promise> to <Await resolve>

* bump bundle

* Remove defer utility in favor of naked objects

* Clean up test

* Revert "Remove defer utility in favor of naked objects"

This reverts commit 3fd7850.

* disbale auto tracking on naked objects

* useRouteError => useAsyncError in changesets

* add rejection code path to raw Await example

Author: brophdawg11

.changeset/light-months-argue.md

@@ -3,46 +3,46 @@
 "@remix-run/router": patch
 ---
 
-Feat: adds `deferred` support to data routers
+Feat: adds `defer()` support to data routers
 
-Returning a `deferred` from a `loader` allows you to separate _critical_ loader data that you want to wait for prior to rendering the destination page from _non-critical_ data that you are OK to show a spinner for until it loads.
+Returning a `defer()` from a `loader` allows you to separate _critical_ loader data that you want to wait for prior to rendering the destination page from _non-critical_ data that you are OK to show a spinner for until it loads.
 
 ```jsx
-// In your route loader, return a deferred() and choose per-key whether to
+// In your route loader, return a defer() and choose per-key whether to
 // await the promise or not.  As soon as the awaited promises resolve, the
 // page will be rendered.
 function loader() {
-  return deferred({
+  return defer({
     critical: await getCriticalData(),
     lazy: getLazyData(),
   });
 };
 
 // In your route element, grab the values from useLoaderData and render them
-// with <Deferred> inside a <Suspense> boundary
-function DeferredPage() {
+// with <Await> inside a <React.Suspense> boundary
+function Page() {
   let data = useLoaderData();
   return (
     <>
       <p>Critical Data: {data.critical}</p>
-      <Suspense fallback={<p>Loading...</p>}>
-        <Deferred value={data.lazy} errorElement={<RenderDeferredError />}>
-          <RenderDeferredData />
-        </Deferred>
-      </Suspense>
+      <React.Suspense fallback={<p>Loading...</p>}>
+        <Await resolve={data.lazy} errorElement={<RenderError />}>
+          <RenderData />
+        </Await>
+      </React.Suspense>
     </>
   );
 }
 
 // Use separate components to render the data once it resolves, and access it
-// via the useDeferredData hook
-function RenderDeferredData() {
-  let data = useDeferredData();
+// via the useAsyncValue hook
+function RenderData() {
+  let data = useAsyncValue();
   return <p>Lazy: {data}</p>;
 }
 
-function RenderDeferredError() {
-  let data = useRouteError();
+function RenderError() {
+  let data = useAsyncError();
   return <p>Error! {data.message} {data.stack}</p>;
 }
 ```
@@ -51,16 +51,16 @@ If you want to skip the separate components, you can use the Render Props
 pattern and handle the rendering of the deferred data inline:
 
 ```jsx
-function DeferredPage() {
+function Page() {
   let data = useLoaderData();
   return (
     <>
       <p>Critical Data: {data.critical}</p>
-      <Suspense fallback={<p>Loading...</p>}>
-        <Deferred value={data.lazy} errorElement={<RenderDeferredError />}>
+      <React.Suspense fallback={<p>Loading...</p>}>
+        <Await resolve={data.lazy} errorElement={<RenderError />}>
           {(data) => <p>{data}</p>}
-        </Deferred>
-      </Suspense>
+        </Await>
+      </React.Suspense>
     </>
   );
 }

.changeset/new-kiwis-burn.md

@@ -8,7 +8,7 @@ Deferred API Updates
 - Removes `<Suspense>` from inside `<Deferred>`, requires users to render their own suspense boundaries
 - Updates `Deferred` to use a true error boundary to catch render errors as well as data errors
 - Support array and single promise usages
-  - `return deferred([ await critical(), lazy() ])`
-  - `return deferred(lazy())`
+  - `return defer([ await critical(), lazy() ])`
+  - `return defer(lazy())`
 - Remove `Deferrable`/`ResolvedDeferrable` in favor of raw `Promise`'s and `Awaited`
-- Remove generics from `useDeferredData` until `useLoaderData` generic is decided in 6.5
+- Remove generics from `useAsyncValue` until `useLoaderData` generic is decided in 6.5

.changeset/sweet-books-switch.md

@@ -0,0 +1,14 @@
+---
+"react-router": patch
+"@remix-run/router": patch
+---
+
+fix: Rename `<Deferred>` to `<Await>`
+
+- We are no longer replacing the `Promise` on `loaderData` with the value/error
+  when it settles so it's now always a `Promise`.
+- To that end, we changed from `<Deferred value={promise}>` to
+  `<Await resolve={promise}>` for clarity, and it also now supports using
+  `<Await>` with raw promises from anywhere, not only those on `loaderData`
+  from a defer() call.
+- The hook is also changed from `useDeferredData` -> `useAsyncValue`

examples/data-router/src/main.tsx

@@ -19,6 +19,7 @@ import {
   todoLoader,
   Todo,
   sleep,
+  AwaitPage,
 } from "./routes";
 import "./index.css";
 
@@ -39,6 +40,7 @@ ReactDOM.createRoot(document.getElementById("root")).render(
             element={<DeferredChild />}
           />
         </Route>
+        <Route id="await" path="await" element={<AwaitPage />} />
         <Route
           path="long-load"
           loader={() => sleep(3000)}

examples/data-router/src/routes.tsx

@@ -1,13 +1,12 @@
 import React from "react";
 import {
-  type ActionFunction,
-  type LoaderFunction,
-  Deferred,
+  Await,
   Form,
   Link,
   Outlet,
-  deferred,
-  useDeferredData,
+  defer,
+  useAsyncError,
+  useAsyncValue,
   useFetcher,
   useFetchers,
   useLoaderData,
@@ -17,12 +16,16 @@ import {
   useRouteError,
   json,
   useActionData,
+  ActionFunctionArgs,
+  LoaderFunctionArgs,
 } from "react-router-dom";
 
 import type { Todos } from "./todos";
 import { addTodo, deleteTodo, getTodos } from "./todos";
 
-export const sleep = (n: number = 500) => new Promise((r) => setTimeout(r, n));
+export function sleep(n: number = 500) {
+  return new Promise((r) => setTimeout(r, n));
+}
 
 export function Fallback() {
   return <p>Performing initial data "load"</p>;
@@ -47,6 +50,8 @@ export function Layout() {
         &nbsp;|&nbsp;
         <Link to="/deferred/child">Deferred Child</Link>
         &nbsp;|&nbsp;
+        <Link to="/await">Await</Link>
+        &nbsp;|&nbsp;
         <Link to="/long-load">Long Load</Link>
         &nbsp;|&nbsp;
         <Link to="/404">404 Link</Link>
@@ -79,12 +84,12 @@ interface HomeLoaderData {
   date: string;
 }
 
-export const homeLoader: LoaderFunction = async (): Promise<HomeLoaderData> => {
+export async function homeLoader(): Promise<HomeLoaderData> {
   await sleep();
   return {
     date: new Date().toISOString(),
   };
-};
+}
 
 export function Home() {
   let data = useLoaderData() as HomeLoaderData;
@@ -97,7 +102,7 @@ export function Home() {
 }
 
 // Todos
-export const todosAction: ActionFunction = async ({ request }) => {
+export async function todosAction({ request }: ActionFunctionArgs) {
   await sleep();
 
   let formData = await request.formData();
@@ -121,12 +126,12 @@ export const todosAction: ActionFunction = async ({ request }) => {
     status: 302,
     headers: { Location: "/todos" },
   });
-};
+}
 
-export const todosLoader: LoaderFunction = async (): Promise<Todos> => {
+export async function todosLoader(): Promise<Todos> {
   await sleep();
   return getTodos();
-};
+}
 
 export function TodosList() {
   let todos = useLoaderData() as Todos;
@@ -211,9 +216,9 @@ export function TodoItem({ id, todo }: TodoItemProps) {
 }
 
 // Todo
-export const todoLoader: LoaderFunction = async ({
+export async function todoLoader({
   params,
-}): Promise<string> => {
+}: LoaderFunctionArgs): Promise<string> {
   await sleep();
   let todos = getTodos();
   if (!params.id) {
@@ -224,7 +229,7 @@ export const todoLoader: LoaderFunction = async ({
     throw new Error(`Uh oh, I couldn't find a todo with id "${params.id}"`);
   }
   return todo;
-};
+}
 
 export function Todo() {
   let params = useParams();
@@ -251,57 +256,63 @@ interface DeferredRouteLoaderData {
 const rand = () => Math.round(Math.random() * 100);
 const resolve = (d: string, ms: number) =>
   new Promise((r) => setTimeout(() => r(`${d} - ${rand()}`), ms));
-const reject = (d: string, ms: number) =>
-  new Promise((_, r) => setTimeout(() => r(`${d} - ${rand()}`), ms));
+const reject = (d: Error | string, ms: number) =>
+  new Promise((_, r) =>
+    setTimeout(() => {
+      if (d instanceof Error) {
+        d.message += ` - ${rand()}`;
+      } else {
+        d += ` - ${rand()}`;
+      }
+      r(d);
+    }, ms)
+  );
 
-export const deferredLoader: LoaderFunction = async ({ request }) => {
-  return deferred({
+export async function deferredLoader() {
+  return defer({
     critical1: await resolve("Critical 1", 250),
     critical2: await resolve("Critical 2", 500),
     lazyResolved: Promise.resolve("Lazy Data immediately resolved - " + rand()),
     lazy1: resolve("Lazy 1", 1000),
     lazy2: resolve("Lazy 2", 1500),
     lazy3: resolve("Lazy 3", 2000),
-    lazyError: reject("Kaboom!", 2500),
+    lazyError: reject(new Error("Kaboom!"), 2500),
   });
-};
+}
 
 export function DeferredPage() {
   let data = useLoaderData() as DeferredRouteLoaderData;
-
   return (
     <div>
       <p>{data.critical1}</p>
       <p>{data.critical2}</p>
 
       <React.Suspense fallback={<p>should not see me!</p>}>
-        <Deferred value={data.lazyResolved}>
-          <RenderDeferredData />
-        </Deferred>
+        <Await resolve={data.lazyResolved}>
+          <RenderAwaitedData />
+        </Await>
       </React.Suspense>
 
       <React.Suspense fallback={<p>loading 1...</p>}>
-        <Deferred value={data.lazy1}>
-          <RenderDeferredData />
-        </Deferred>
+        <Await resolve={data.lazy1}>
+          <RenderAwaitedData />
+        </Await>
       </React.Suspense>
 
       <React.Suspense fallback={<p>loading 2...</p>}>
-        <Deferred value={data.lazy2}>
-          <RenderDeferredData />
-        </Deferred>
+        <Await resolve={data.lazy2}>
+          <RenderAwaitedData />
+        </Await>
       </React.Suspense>
 
       <React.Suspense fallback={<p>loading 3...</p>}>
-        <Deferred value={data.lazy3}>
-          {(data: string) => <p>{data}</p>}
-        </Deferred>
+        <Await resolve={data.lazy3}>{(data: string) => <p>{data}</p>}</Await>
       </React.Suspense>
 
       <React.Suspense fallback={<p>loading (error)...</p>}>
-        <Deferred value={data.lazyError} errorElement={<RenderDeferredError />}>
-          <RenderDeferredData />
-        </Deferred>
+        <Await resolve={data.lazyError} errorElement={<RenderAwaitedError />}>
+          <RenderAwaitedData />
+        </Await>
       </React.Suspense>
 
       <Outlet />
@@ -314,16 +325,16 @@ interface DeferredChildLoaderData {
   lazy: Promise<string>;
 }
 
-export const deferredChildLoader: LoaderFunction = async ({ request }) => {
-  return deferred({
+export async function deferredChildLoader() {
+  return defer({
     critical: await resolve("Critical Child Data", 500),
     lazy: resolve("Lazy Child Data", 1000),
   });
-};
+}
 
-export const deferredChildAction: ActionFunction = async ({ request }) => {
+export async function deferredChildAction() {
   return json({ ok: true });
-};
+}
 
 export function DeferredChild() {
   let data = useLoaderData() as DeferredChildLoaderData;
@@ -332,9 +343,9 @@ export function DeferredChild() {
     <div>
       <p>{data.critical}</p>
       <React.Suspense fallback={<p>loading child...</p>}>
-        <Deferred value={data.lazy}>
-          <RenderDeferredData />
-        </Deferred>
+        <Await resolve={data.lazy}>
+          <RenderAwaitedData />
+        </Await>
       </React.Suspense>
       <Form method="post">
         <button type="submit" name="key" value="value">
@@ -346,13 +357,39 @@ export function DeferredChild() {
   );
 }
 
-export function RenderDeferredData() {
-  let data = useDeferredData<string>();
+let shouldResolve = true;
+let rawPromiseResolver: ((value: unknown) => void) | null;
+let rawPromiseRejecter: ((value: unknown) => void) | null;
+let rawPromise: Promise<unknown> = new Promise((r, j) => {
+  rawPromiseResolver = r;
+  rawPromiseRejecter = j;
+});
+
+export function AwaitPage() {
+  React.useEffect(() => {
+    setTimeout(() => {
+      if (shouldResolve) {
+        rawPromiseResolver?.("Resolved raw promise!");
+      } else {
+        rawPromiseRejecter?.("Rejected raw promise!");
+      }
+    }, 1000);
+  }, []);
+
+  return (
+    <React.Suspense fallback={<p>Awaiting raw promise </p>}>
+      <Await resolve={rawPromise}>{(data: string) => <p>{data}</p>}</Await>
+    </React.Suspense>
+  );
+}
+
+function RenderAwaitedData() {
+  let data = useAsyncValue() as string;
   return <p>{data}</p>;
 }
 
-export function RenderDeferredError() {
-  let error = useRouteError() as Error;
+function RenderAwaitedError() {
+  let error = useAsyncError() as Error;
   return (
     <p style={{ color: "red" }}>
       Error (errorElement)!