fix(react): Hold fetch results until DataProvider mounts with CommitGateManager

.changeset/precommit-fetch.md

@@ -0,0 +1,15 @@
+---
+'@data-client/react': patch
+---
+
+Add `CommitGateManager` for DataProvider inside a lazy layout, such as Expo Router's root layout
+
+[useSuspense](/docs/api/useSuspense) and `use(useFetch())` could stay on the fallback, or refetch in a loop, when their fetch finished before [DataProvider](/docs/api/DataProvider) had mounted. Expo Router wraps routes, including the root `_layout.tsx`, in `React.lazy` when async routes are on (the default on web), so React can throw away the provider's first render. Any DataProvider inside `React.lazy`, or next to something that suspends outside it, is affected. This is not specific to React Native.
+
+Add `CommitGateManager` before the other managers. It holds those results until the provider mounts:
+
+```tsx
+<DataProvider managers={[new CommitGateManager(), ...getDefaultManagers()]}>
+```
+
+On React Native, DataProvider adds it automatically.

docs/core/api/CommitGateManager.md

@@ -0,0 +1,70 @@
+---
+title: CommitGateManager - Keep fetches that resolve before DataProvider mounts
+sidebar_label: CommitGateManager
+frameworks: [react]
+---
+
+import ProviderManagers from '../shared/_provider_managers.mdx';
+
+# CommitGateManager
+
+Holds fetch results that arrive before [<DataProvider />](./DataProvider.md) mounts, then
+applies them once it does.
+
+React can render a `DataProvider` and then throw that render away. This happens when the provider
+sits inside a lazy-loaded layout, or when something outside the provider suspends during its first
+render. A fetch that resolves in between has no store to land in, so [useSuspense()](./useSuspense.md)
+would stay on its fallback. `CommitGateManager` keeps those results and replays them into the store
+that mounts, so the endpoint is called only once.
+
+:::info implements
+
+`CommitGateManager` implements [Manager](./Manager.md)
+
+:::
+
+## Usage
+
+Add it first when `DataProvider` renders inside a [lazy](https://react.dev/reference/react/lazy)
+layout or route, or next to a component that can suspend outside it. The most common case is
+[Expo Router](https://docs.expo.dev/router/introduction/): with async routes on, which is the default
+on web, it wraps the root `_layout.tsx` in `React.lazy`. This isn't specific to React Native.
+
+On React Native, [DataProvider](./DataProvider.md#managers) adds it first to its `managers` for you.
+
+<ProviderManagers imports={['CommitGateManager', 'getDefaultManagers']}>
+
+```ts
+// highlight-next-line
+const managers = [new CommitGateManager(), ...getDefaultManagers()];
+```
+
+</ProviderManagers>
+
+:::note
+
+Put it first, in the same `managers` list as the [NetworkManager](./NetworkManager.md) it protects,
+and give each `DataProvider` its own `CommitGateManager`.
+
+:::
+
+:::tip
+
+Placing `DataProvider` at the root, with every [Suspense](https://react.dev/reference/react/Suspense)
+boundary inside it, avoids the race without this manager.
+
+:::
+
+## Members
+
+### middleware
+
+#### Processed Actions
+
+- [setResponse](./Controller.md#setResponse) is held until the provider mounts.
+- [resetEntireStore](./Controller.md#resetEntireStore) drops held results, and results fetched before it that settle later.
+- During server rendering, nothing is held, since a server render never mounts.
+
+#### Dispatched Actions
+
+- [setResponse](./Controller.md#setResponse) replays each held result into the mounted store.

docs/core/api/DataProvider.md

@@ -51,6 +51,8 @@ List of [Manager](./Manager.md)s use. This is the main extensibility point of th
 
 [getDefaultManagers()](./getDefaultManagers.md) can be used to extend the default managers.
 
+On React Native, [CommitGateManager](./CommitGateManager.md) is added first unless `managers` already includes it.
+
 Default Production:
 
 ```typescript

packages/react/src/components/DataProvider.tsx

@@ -14,6 +14,7 @@ import type { JSX } from 'react';
 import DataStore from './DataStore.js';
 import type { DevToolsPosition } from './DevToolsButton.js';
 import { getDefaultManagers } from './getDefaultManagers.js';
+import platformManagers from './platformManagers.js';
 import { SSR } from './LegacyReact.js';
 import { renderDevButton } from './renderDevButton.js';
 import { ControllerContext } from '../context.js';
@@ -50,8 +51,9 @@ export default function DataProvider({
     controllerRef.current = new Controller({ gcPolicy: gcRef.current });
   //TODO: bind all methods so destructuring works
 
-  const managersRef: React.RefObject<Manager[]> = useRef<any>(managers);
-  if (!managersRef.current) managersRef.current = getDefaultManagers();
+  const managersRef: React.RefObject<Manager[]> = useRef<any>(undefined);
+  if (!managersRef.current)
+    managersRef.current = platformManagers(managers ?? getDefaultManagers());
 
   // run in a useEffect in DataStore
   // eslint-disable-next-line react-hooks/exhaustive-deps

packages/react/src/components/__tests__/precommit-race.native.tsx

@@ -0,0 +1,28 @@
+import type { ReactNode } from 'react';
+import { Text } from 'react-native';
+import TestRenderer from 'react-test-renderer';
+
+import { registerPrecommitRaceTests } from './precommit-race.node-suite';
+import type { RaceHost } from './precommit-race.node-suite';
+
+const host: RaceHost = {
+  addsGate: true,
+  Text: ({ children }: { children?: ReactNode }) => <Text>{children}</Text>,
+  createRenderer() {
+    let renderer: TestRenderer.ReactTestRenderer | undefined;
+    return {
+      render(node) {
+        if (!renderer) renderer = TestRenderer.create(node);
+        else renderer.update(node);
+      },
+      read() {
+        return JSON.stringify(renderer?.toJSON() ?? '');
+      },
+      unmount() {
+        renderer?.unmount();
+      },
+    };
+  },
+};
+
+registerPrecommitRaceTests(host);