Feat: Add deferred support

[brophdawg11]

• Add's deferred() support to loader's in data routers
• Unit tests cover main usages
• Can be manually tested via the examples/data-router app using the /deferred and /deferred/child routes
  • probably need to run via USE_SOURCE=true npm run dev

[changeset-bot]

🦋 Changeset detected

Latest commit: 57e1fe7

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 5 packages

Name	Type
react-router	Patch
@remix-run/router	Patch
react-router-dom	Patch
react-router-dom-v5-compat	Patch
react-router-native	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[brophdawg11]

This class gets instantiated by a deferred() call and handles tracking data and pending keys, and calling a registered subscriber function when individual promises resolve so the router can update state.

[brophdawg11]

This is so we know if the data on loaderData was from a promise rejection and we should render it in the <Deferred> errorBoundary component

[brophdawg11]

This was no longer necessary since all gets are now state:loading

[ryanflorence]

let's use errorElement so we don't have both errorElement on Route and errorBoundary on Deferred

[brophdawg11]

👍 7504d99

[ryanflorence]

Can you access the deferred error somewhere?

[brophdawg11]

Can you access the deferred error somewhere?

I didn't create a specific hook for it yet - both success and error come through useDeferred and we provide the isDeferredError utility to differentiate. We can add one if we want the clarity. There's a few ways to consume the error currently:

// 1 - Consume success/error states in different components
<Deferred data="data" errorElement={<MyErrorBoundary/>}>
  <MyData />
</Deferred>

function MyData() {
  let data = useDeferred(); // Guaranteed to be success data
  return <p>{data}<p>;
}

function MyErrorBoundary() {
  let error = useDeferred();  // Guaranteed to be a DeferredError
  return <p>{error.message}<p>;
}

//////////

// 2 - Consume success/error states in the same component
<Deferred data="data">
  <MyData />
</Deferred>

function MyData() {
  // This might be success or error - you need to handle
  let dataOrError = useDeferred();

  if (isDeferredError(dataOrError)) {
    return <p>{dataOrError.message}<p>;
  }

  return <p>{dataOrError}<p>;
}

//////////

// 3 - Consume via render props
<Deferred data="data">
  {({ data }) => isDeferredError(data) ? 
    <p>{data.message}<p> :
    <p>{data}<p>}
</Deferred>

If we want to fork useDeferred into useDeferredData/useDeferredError it would look like:

// 1 - Consume success/error states in different components
<Deferred data="data" errorElement={<MyErrorBoundary/>}>
  <MyData />
</Deferred>

function MyData() {
  let data = useDeferredData();
  return <p>{data}<p>;
}

function MyErrorBoundary() {
  let error = useDeferredError();
  return <p>{error.message}<p>;
}

//////////

// 2 - Consume success/error states in the same component
<Deferred data="data">
  <MyData />
</Deferred>

function MyData() {
  let data = useDeferredData();
  let error = useDeferredError();

  if (error) {
    return <p>{error.message}<p>;
  }

  return <p>{data}<p>;
}

//////////

// 3 - Consume via render props
<Deferred data="data">
  {({ data, error }) => error ? 
    <p>{error.message}<p> :
    <p>{data}<p>}
</Deferred>

It's really no more verbose in either case - so I think I agree an explicit hooks would be nice. useDeferredData/useDeferredError aligns more closely to useLoaderData/useRouteError too. I can go ahead and make that change.

[ryanflorence]

I imagined we'd be able to use the same ErrorBoundary for route errorElement or deferred errorElement.

<>
  <Route errorElement={<ErrorBoundary />} />
  <Deferred errorElement={<ErrorBoundary />} />
</>

function ErrorBoundary() {
  let error = useRouteError();
  // ...
}

wdyt?

[brophdawg11]

Hm - yeah that could work - so the children of Deferred behave like a <Route element> and are always happy path?

[ryanflorence]

are always happy path?

Yeah, that's the goal. Keep happy paths happy! Also, if a deferred value throws an error and does not have an errorElement it needs to bubble up to the nearest route anyway.

[ryanflorence]

value={data.lazy}

[brophdawg11]

🙌

[ryanflorence]

should we call this useDeferredValue?

[brophdawg11]

Stale changeset again :/. It's useDeferredData now - aligning with useLoaderData as its happy path. We didn't want to use useDeferredValue since <Deferred value="..."> accepts a Promise/DeferredError or the resolved "data". useDeferredData will only ever give you the resolved data.

[ryanflorence]

There's nothing else for us to pass in here, so let's not put it on a named key and then force them to rename or double-destructure it:

// 😕
<Deferred>
  {({ data: whatever }) => ()}
</Deferred>

// 😕
<Deferred>
  {({ data: { stuff } }) => ()}
</Deferred>

Instead just pass the value into the child function:

<Deferred>
  {value => ()}
</Deferred>

[brophdawg11]

oops - that's a stale changeset 😬 We do just pass the resolved data now, will get that updated

I don't know how to use github reviews and this is annoying.