Skip to content

reactive/data-client / .agents/skills/data-client-manager

data-client-manager

Verified

Write @data-client Managers, the runtime layer that bridges the store to the world outside the view framework: global side effects and real-time data such as websockets, SSE and polling. A Manager reacts to every request or to events from outside the app, and moves data into or out of the store. Use one instead of useEffect for behavior that belongs to the whole app, such as error toasts and reporting, logging and analytics, auth failures, refetching on focus or reconnect, and cross-tab sync. Not for the shape of data: data built from responses (joined, derived, or accumulated) is defined in a schema, so use data-client-schema.

references/Controller.md

View on GitHub
<!-- Generated by `yarn build:skills` from docs/core/api/Controller.md (react). Edit the source doc, not this file. -->

# Controller

`Controller` gives type-safe access to the Reactive Data Client [store and its lifecycle](./Manager.md#control-flow).
Each store has one `Controller`.

`Controller` memoizes denormalization for global referential equality: unchanged store data gives the same object
wherever it is read. This keeps rendering and lookups fast.

`Controller` is provided:

- [Managers](./Manager.md) as the first argument in [Manager.middleware](./Manager.md#middleware)
- React with [useController()](https://dataclient.io/docs/api/useController)
- [Unit testing hooks](https://dataclient.io/docs/guides/unit-testing-hooks) with [renderDataHook()](https://dataclient.io/docs/api/renderDataHook#controller)

```ts
class Controller {
  /*************** Action Dispatchers ***************/
  fetch(endpoint, ...args): ReturnType<E>;
  fetchIfStale(endpoint, ...args): Promise<Denormalize<E['schema']>>;
  expireAll({ testKey }): Promise<void>;
  invalidate(endpoint, ...args): Promise<void>;
  invalidateAll({ testKey }): Promise<void>;
  resetEntireStore(): Promise<void>;
  set(queryable, ...args, value): Promise<void>;
  set([Entity], rows): Promise<void>;
  setResponse(endpoint, ...args, response): Promise<void>;
  setError(endpoint, ...args, error): Promise<void>;
  resolve(endpoint, { args, response, fetchedAt, error }): Promise<void>;
  subscribe(endpoint, ...args): Promise<void>;
  unsubscribe(endpoint, ...args): Promise<void>;
  /*************** Data Access ***************/
  get(queryable, ...args, state): DenormalizeNullable<typeof queryable> | undefined;
  getResponse(endpoint, ...args, state): { data; expiryStatus; expiresAt };
  getError(endpoint, ...args, state): ErrorTypes | undefined;
  snapshot(state: State<unknown>, fetchedAt?: number): SnapshotInterface;
  getState(): State<unknown>;
}
```

## Action Dispatchers

### fetch(endpoint, ...args) {#fetch}

Fetches the endpoint with the given args. When the fetch completes, the response or error goes into the cache.

**Create**

```tsx
import { useController } from '@data-client/react';
import { PostResource } from './PostResource';

function CreatePost() {
  const ctrl = useController();

  return (
    <form
      onSubmit={e =>
        ctrl.fetch(PostResource.getList.push, new FormData(e.currentTarget))
      }
    >
      {/* ... */}
    </form>
  );
}
```

**Update**

```tsx
import { useController } from '@data-client/react';
import { PostResource } from './PostResource';

function UpdatePost({ id }: { id: string }) {
  const ctrl = useController();

  return (
    <form
      onSubmit={e =>
        ctrl.fetch(PostResource.update, { id }, new FormData(e.currentTarget))
      }
    >
      {/* ... */}
    </form>
  );
}
```

**Delete**

```tsx
import { useController } from '@data-client/react';
import { useCallback } from 'react';
import { useNavigate } from 'react-router';
import { Post, PostResource } from './PostResource';

function PostListItem({ post }: { post: Post }) {
  const ctrl = useController();
  const navigate = useNavigate();

  const handleDelete = useCallback(
    async e => {
      await ctrl.fetch(PostResource.delete, { id: post.id });
      navigate('/');
    },
    [ctrl, post.id],
  );

  return (
    <div>
      <h3>{post.title}</h3>
      <button onClick={handleDelete}>X</button>
    </div>
  );
}
```

> **Tip**
>
> `fetch` has the same return value as the [Endpoint](https://dataclient.io/rest/api/Endpoint) passed to it.
> With a schema, it returns the denormalized value.
>
> ```ts
> const controller = useController();
>
> const post = await controller.fetch(
>   PostResource.getList.push,
>   createPayload,
> );
> post.title;
> post.pk();
> ```

#### Endpoint.sideEffect

[sideEffect](https://dataclient.io/rest/api/Endpoint#sideeffect) changes how `fetch()` behaves:

##### true

- Resolves _before_ the cache update is [committed](https://react.dev/learn/render-and-commit#step-3-react-commits-changes-to-the-dom).
- Every call starts a new fetch.
- Unawaited, it rejects unhandled, since no component reads its error. Await it, or use
  [useLoading()](https://dataclient.io/docs/api/useLoading) to show the error.

##### false | undefined

- Resolves _after_ the cache update is [committed](https://react.dev/learn/render-and-commit#step-3-react-commits-changes-to-the-dom).
- Identical requests are deduplicated, so only one is in flight at a time.
  - To start a _new_ request, abort the one in flight first.
- Safe unawaited: the error is stored for components reading that endpoint, so it never reaches global
  unhandled-rejection handlers ([report it](./managers.md#error-reporting) instead). `await` still rejects.

### fetchIfStale(endpoint, ...args) {#fetchIfStale}

Fetches only when the data is missing, [stale](https://dataclient.io/docs/concepts/expiry-policy#stale) or [invalid](https://dataclient.io/docs/concepts/expiry-policy#invalid),
and always returns a Promise of the latest fetch's outcome. This avoids overfetching fresh data when prefetching.

| Cache                                                                                                         | Fetches                     | `await` gives                                                                                       | Not awaited                                 |
| ------------------------------------------------------------------------------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| Missing, stale or invalid                                                                                     | Yes, like [fetch()](#fetch) | The fetched data, or rejects with its error                                                         | The error is stored; no unhandled rejection |
| Fresh                                                                                                         | No                          | The cached data                                                                                     | Nothing happens                             |
| The latest fetch failed within [errorExpiryLength](https://dataclient.io/rest/api/Endpoint#errorexpirylength) | No                          | Rejects with that error, like [useSuspense()](https://dataclient.io/docs/api/useSuspense) throws it | Nothing happens                             |

So prefetches don't need to be awaited or caught: components reading that endpoint show a stored error as usual.
Unawaited failures don't reach global unhandled-rejection handlers, so report fetch errors with an
[error reporting Manager](./managers.md#error-reporting). A `.then()` chained onto the result makes a new
Promise, so end that chain with `.catch()`.

```ts
// start a secondary request without waiting for it
controller.fetchIfStale(CommentResource.getList, { issueId });
// wait for the data; rejects if that fetch fails
const issue = await controller.fetchIfStale(IssueResource.get, { id: issueId });
```

To check whether data is cached and fresh without fetching, read [getResponse()](#getResponse) synchronously.

#### In route loaders {#fetchIfStale-loaders}

A loader starts the next page's fetches before it renders. Like [useSuspense()](https://dataclient.io/docs/api/useSuspense), navigation should wait
only when the cached data can't render: when it's missing, invalidated, or stale from an
[invalidIfStale](https://dataclient.io/docs/concepts/expiry-policy#endpointinvalidifstale) endpoint. Stale data renders at once and
refetches. How to get that depends on what the router waits for:

| Router                                                                                                                                                                                                                 | In the loader                                                                           | Nothing cached                                                                                                                                                                                                                                                                                          |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Changes the route in a [transition](https://react.dev/reference/react/startTransition), like the Next.js App Router, React Router 7, TanStack Router or [@anansi/router](https://www.npmjs.com/package/@anansi/router) | Start every `fetchIfStale()` without awaiting it, so the router has nothing to wait for | The current page stays until the new one is ready, unless the new page has its own Suspense boundary (like an [AsyncBoundary](https://dataclient.io/docs/api/AsyncBoundary) or a TanStack Router `pendingComponent`), which shows its fallback. @anansi/router skips the transition on back and forward |
| Renders the loader's return value, or doesn't change the route in a transition (React Router 6 without its `v7_startTransition` flag)                                                                                  | Return the cached data when it can render; otherwise return `fetchIfStale()`            | The router waits for the fetch                                                                                                                                                                                                                                                                          |

The Next.js App Router has no loaders: `useSuspense()` fetches as the page renders.

```ts title="Router with transitions"
import type { Controller } from '@data-client/react';
import { CommentResource } from './resources/Comment';
import { IssueResource } from './resources/Issue';

export const issueLoader =
  (ctrl: Controller) =>
  ({ params }: { params: { id: string } }) => {
    // not awaited: the route changes at once, and useSuspense() waits inside the transition
    ctrl.fetchIfStale(IssueResource.get, { id: params.id });
    ctrl.fetchIfStale(CommentResource.getList, { issueId: params.id });
    // React Router 6 requires a return value
    return null;
  };
```

When server rendering waits for the loader, as @anansi/core's `prefetchSpout` does for @anansi/router's `resolveData`,
also await the first view's fetch so the first HTML includes its data. Add `.catch(() => {})` (or use
`Promise.allSettled()` for several), so a failure never rejects unhandled on the client; `useSuspense()` still shows the
error.

```ts
resolveData: async (controller: Controller, { id }: { id: string }) => {
  controller.fetchIfStale(CommentResource.getList, { issueId: id });
  await controller.fetchIfStale(IssueResource.get, { id }).catch(() => {});
},
```

```ts title="Router that renders loader data"
import { ExpiryStatus, type Controller } from '@data-client/react';
import { IssueResource } from './resources/Issue';

export const issueLoader =
  (ctrl: Controller) =>
  ({ params }: { params: { id: string } }) => {
    const args = { id: params.id };
    const { data, expiryStatus } = ctrl.getResponse(
      IssueResource.get,
      args,
      ctrl.getState(),
    );
    const fetched = ctrl.fetchIfStale(IssueResource.get, args);
    // stale data is still Valid, so it returns at once
    return expiryStatus === ExpiryStatus.Valid ? data : fetched;
  };
```

A loader that returns a pending fetch lets the router show its own pending and error UI, but it holds navigation while
the request runs. That tradeoff comes with waiting for loader data, whatever fetches it.

Example app: [github-app](https://github.com/reactive/data-client/tree/master/examples/github-app) ([`src/routing/routes.tsx`](https://github.com/reactive/data-client/blob/master/examples/github-app/src/routing/routes.tsx))

### expireAll({ testKey }) {#expireAll}

Sets all responses' [expiry status](https://dataclient.io/docs/concepts/expiry-policy) matching `testKey` to [Stale](https://dataclient.io/docs/concepts/expiry-policy#stale).

Use it to refresh only the data on screen when the cache holds many sets of args.

```tsx
import { type Controller, useController } from '@data-client/react';
import { AccountResource, TradeResource, type Trade } from './resources';
import { Form, FormField } from './Form';

const createTradeHandler =
  (ctrl: Controller, userId: string) => async (trade: Trade) => {
    await ctrl.fetch(TradeResource.getList.push, { user: userId }, trade);
    ctrl.expireAll(AccountResource.get);
    ctrl.expireAll(AccountResource.getList);
  };

function CreateTrade({ userId }: { userId: string }) {
  const handleTrade = createTradeHandler(useController(), userId);

  return (
    <Form onSubmit={handleTrade}>
      <FormField name="ticker" />
      <FormField name="amount" type="number" />
      <FormField name="price" type="number" />
    </Form>
  );
}
```

> **Tip**
>
> Often it is better to [include mutation side effects in the mutation response](https://dataclient.io/rest/guides/side-effects). This
> reduces load, improves performance and keeps state consistent.

### invalidate(endpoint, ...args) {#invalidate}

Forces refetching and suspenseon [useSuspense](https://dataclient.io/docs/api/useSuspense) with the same Endpoint
and parameters.

```tsx
import { useController, useSuspense } from '@data-client/react';
import { ArticleResource } from './ArticleResource';

function ArticleName({ id }: { id: string }) {
  const article = useSuspense(ArticleResource.get, { id });
  const ctrl = useController();

  return (
    <div>
      <h1>{article.title}</h1>
      <button onClick={() => ctrl.invalidate(ArticleResource.get, { id })}>
        Fetch &amp; suspend
      </button>
    </div>
  );
}
```

> **Tip**
>
> To refresh while still showing stale data, use [Controller.fetch](#fetch).

> **Tip: Invalidate many endpoints at once**
>
> Use [schema.Invalidate](https://dataclient.io/rest/api/Invalidate) to invalidate every endpoint that contains a given entity.
>
> For REST, try [Resource.delete](https://dataclient.io/rest/api/resource#delete).
>
> ```ts
> // deletes MyResource(5)
> // this will refetch MyResource.get({id: '5'})
> // and remove it from MyResource.getList
> controller.setResponse(MyResource.delete, { id: '5' }, { id: '5' });
> ```

### invalidateAll({ testKey }) {#invalidateAll}

[Invalidates](https://dataclient.io/docs/concepts/expiry-policy#invalid) all [endpoint keys](https://dataclient.io/rest/api/RestEndpoint#key) matching `testKey`.

```tsx
import { useController, useSuspense } from '@data-client/react';
import { ArticleResource } from './ArticleResource';

function ArticleName({ id }: { id: string }) {
  const article = useSuspense(ArticleResource.get, { id });
  const ctrl = useController();

  return (
    <div>
      <h1>{article.title}</h1>
      <button onClick={() => ctrl.invalidateAll(ArticleResource.get)}>
        Fetch &amp; suspend
      </button>
    </div>
  );
}
```

> **Tip**
>
> To refresh while still showing stale data, use [Controller.expireAll](#expireAll) instead.

The code below invalidates only GET endpoints on the test.com domain. Other domains stay in the cache.

```ts
const myDomain = 'http://test.com';
const testKey = (key: string) => key.startsWith(`GET ${myDomain}`);

function useLogout() {
  const ctrl = useController();
  return () => ctrl.invalidateAll({ testKey });
}
```

Also clear the cache on 401 (unauthorized) with [LogoutManager](./LogoutManager.md).

**Web**

```tsx title="index.tsx"
import {
  DataProvider,
  LogoutManager,
  getDefaultManagers,
} from '@data-client/react';
import { createRoot } from 'react-dom/client';
import App from './App';
import { unAuth } from '../authentication';

const myDomain = 'http://test.com';
const testKey = (key: string) => key.startsWith(`GET ${myDomain}`);

const managers = () => [
  new LogoutManager({
    handleLogout(controller) {
      // call custom unAuth function we defined
      unAuth();
      // still reset the store
      controller.invalidateAll({ testKey });
    },
  }),
  ...getDefaultManagers(),
];

createRoot(document.body).render(
  <DataProvider managers={managers}>
    <App />
  </DataProvider>,
);
```

**React Native**

```tsx title="index.tsx"
import {
  DataProvider,
  LogoutManager,
  getDefaultManagers,
} from '@data-client/react';
import { AppRegistry } from 'react-native';
import App from './App';
import { unAuth } from '../authentication';

const myDomain = 'http://test.com';
const testKey = (key: string) => key.startsWith(`GET ${myDomain}`);

const managers = () => [
  new LogoutManager({
    handleLogout(controller) {
      // call custom unAuth function we defined
      unAuth();
      // still reset the store
      controller.invalidateAll({ testKey });
    },
  }),
  ...getDefaultManagers(),
];

const Root = () => (
  <DataProvider managers={managers}>
    <App />
  </DataProvider>
);
AppRegistry.registerComponent('MyApp', () => Root);
```

**NextJS**

```tsx title="app/Provider.tsx"
'use client';
import { LogoutManager, getDefaultManagers } from '@data-client/react';
import { DataProvider } from '@data-client/react/nextjs';
import { unAuth } from '../authentication';

const myDomain = 'http://test.com';
const testKey = (key: string) => key.startsWith(`GET ${myDomain}`);

const managers = () => [
  new LogoutManager({
    handleLogout(controller) {
      // call custom unAuth function we defined
      unAuth();
      // still reset the store
      controller.invalidateAll({ testKey });
    },
  }),
  ...getDefaultManagers(),
];

export default function Provider({
  children,
}: {
  children: React.ReactNode;
}) {
  return <DataProvider managers={managers}>{children}</DataProvider>;
}
```

```tsx title="app/layout.tsx"
import Provider from './Provider';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Provider>{children}</Provider>
      </body>
    </html>
  );
}
```

**Expo**

```tsx title="app/_layout.tsx"
import { Stack } from 'expo-router';
import {
  DataProvider,
  LogoutManager,
  getDefaultManagers,
} from '@data-client/react';
import { unAuth } from '../authentication';

const myDomain = 'http://test.com';
const testKey = (key: string) => key.startsWith(`GET ${myDomain}`);

const managers = () => [
  new LogoutManager({
    handleLogout(controller) {
      // call custom unAuth function we defined
      unAuth();
      // still reset the store
      controller.invalidateAll({ testKey });
    },
  }),
  ...getDefaultManagers(),
];

export default function RootLayout() {
  return (
    <DataProvider managers={managers}>
      <Stack>
        <Stack.Screen name="index" />
      </Stack>
    </DataProvider>
  );
}
```

### resetEntireStore() {#resetEntireStore}

Clears the entire Reactive Data Client cache. Responses to fetches in flight are not stored. Those fetches reject with a `ResetError` (`error.name === 'ResetError'`), except `sideEffect` fetches, which still settle with their own result or error.

Use it when a user logs out or the authenticated user changes.

```tsx
import { useController, useSuspense } from '@data-client/react';
import { useCallback } from 'react';
import { CurrentUserResource } from './CurrentUserResource';
import { impersonateUser } from './auth';

const USER_NUMBER_ONE: string = '1111';

function UserName() {
  const user = useSuspense(CurrentUserResource.get);
  const ctrl = useController();

  const becomeAdmin = useCallback(() => {
    // Changes the current user
    impersonateUser(USER_NUMBER_ONE);
    ctrl.resetEntireStore();
  }, [ctrl]);
  return (
    <div>
      <h1>{user.name}</h1>
      <button onClick={becomeAdmin}>Be Number One</button>
    </div>
  );
}
```

### set(queryable, ...args, value) {#set}

Updates any [Queryable](https://dataclient.io/rest/api/schema#queryable) [Schema](https://dataclient.io/rest/api/schema#schema-overview), or many entities at once with an [Array](https://dataclient.io/rest/api/Array) or [Values](https://dataclient.io/rest/api/Values) schema.

```ts
ctrl.set(
  Todo,
  // which Todo to update
  { id: '5' },
  // merge this data into the Todo in the store
  { id: '5', title: 'tell me friends how great Data Client is' },
);
```

The value is typed by the schema: an [Entity](https://dataclient.io/rest/api/Entity) takes its fields (numbers and strings may be either),
while a [Collection](https://dataclient.io/rest/api/Collection) or [All](https://dataclient.io/rest/api/All) takes a list of rows. A [Query](https://dataclient.io/rest/api/Query)
takes the input of the schema it wraps, since `set()` normalizes that schema rather than reversing `process()`.

```ts
ctrl.set(TodoResource.getList.schema, [{ id: '5', completed: true }]);
```

[Collection.push](https://dataclient.io/rest/api/Collection#push) and [unshift](https://dataclient.io/rest/api/Collection#unshift) take the Collection's args,
which pick the lists to add to, and one row or a list of rows.

```ts
ctrl.set(TodoResource.getList.schema.push, { userId: '1' }, [
  { id: '6', title: 'Buy milk' },
  { id: '7', title: 'Walk dog' },
]);
```

> **Note: Unions**
>
> When each member declares its discriminator as a literal (like `readonly type = 'first'`), a
> [Union](https://dataclient.io/rest/api/Union) row is checked against the member it selects, so `{ type: 'first', secondField: 1 }` is an
> error. Only declared fields are accepted, so a key read by a
> `schemaAttribute` function must be declared on each member.

Pass a function to derive the value from the stored one. This [prevents race conditions](https://react.dev/reference/react/useState#updating-state-based-on-the-previous-state).

```ts
const id = '2';
ctrl.set(Article, { id }, article => ({ id, votes: article.votes + 1 }));
```

#### set(\[Entity], rows) {#set-array}

Pass an [Array](https://dataclient.io/rest/api/Array) schema (`[Todo]` or `new schema.Array(Todo)`) and a list of rows to update
many entities in one store update. Each row merges with its stored entity; entities not in the list are untouched.

```ts
ctrl.set(
  [Todo],
  [
    { id: '5', completed: true },
    { id: '6', completed: false },
  ],
);
```

Rows are typed by the Entity's fields; numbers and strings may be either, and object, array and Date values are not
checked since rows are raw input.

For lists that mix Entity types, use a [Union](https://dataclient.io/rest/api/Union); each row is stored by its `type`:

```ts
const Feed = new schema.Union({ post: Post, comment: Comment }, 'type');

ctrl.set(
  [Feed],
  [
    { id: '1', type: 'post', title: 'Hello' },
    { id: '7', type: 'comment', body: 'Nice!' },
  ],
);
```

To delete many entities at once, use [Invalidate](https://dataclient.io/rest/api/Invalidate#batch-invalidation); rows only need their pk
fields:

```ts
ctrl.set([new schema.Invalidate(Todo)], [{ id: '5' }, { id: '6' }]);
```

To delete one, pass the Invalidate schema and its row:

```ts
ctrl.set(new schema.Invalidate(Todo), { id: '5' });
```

[Values](https://dataclient.io/rest/api/Values) schemas take an object of rows instead:

```ts
ctrl.set(new schema.Values(Todo), {
  '5': { id: '5', completed: true },
  '6': { id: '6', completed: false },
});
```

Array, Values and Invalidate schemas take no `args` (so [Entity.pk()](https://dataclient.io/rest/api/Entity#pk) and [Entity.process()](https://dataclient.io/rest/api/Entity#process)
receive `[]`) and no updater function. Rows that share a pk merge in list order, without
[Entity.shouldReorder()](https://dataclient.io/rest/api/Entity#shouldreorder). Use this instead of calling `set()` once per row, such as when
[batching high-frequency stream updates](./managers.md#batching).

Try both buttons below. This browser check starts from an empty store and times `Promise.all` of 500 `set()`
calls against one batch `set()`. Both paths are one React commit, and each writes 500 new prices.

```ts title="Ticker"
import { Entity } from '@data-client/rest';

export class Ticker extends Entity {
  product_id = '';
  price = 0;

  pk() {
    return this.product_id;
  }
  static key = 'Ticker';
}

export const newPrices = () =>
  Array.from({ length: 500 }, (_, i) => ({
    product_id: `COIN-${i}`,
    price: Math.round(Math.random() * 10000) / 100,
  }));
```

```tsx title="Timing"
import React from 'react';
import NumberFlow from '@number-flow/react';

// Times write(), leaving makeInput() out of the measurement
export function useTimed<T>(
  makeInput: () => T,
  write: (input: T) => Promise<unknown>,
) {
  const [ms, setMs] = React.useState<number>();
  const run = async () => {
    const input = makeInput();
    const start = performance.now();
    await write(input);
    setMs(performance.now() - start);
  };
  return [ms, run] as const;
}

export function Timing({
  label,
  ms,
}: {
  label: string;
  ms: number | undefined;
}) {
  return (
    <div>
      <dt>{label}</dt>
      <dd>
        {ms !== undefined && (
          <NumberFlow
            value={ms}
            format={{ maximumFractionDigits: 1 }}
            suffix=" ms"
          />
        )}
      </dd>
    </div>
  );
}
```

```tsx title="PriceHeader"
import { useQuery } from '@data-client/react';
import NumberFlow from '@number-flow/react';
import { Ticker } from './Ticker';

export default function PriceHeader() {
  const first = useQuery(Ticker, { product_id: 'COIN-0' });
  return (
    <header className="appHeader">
      <h1 className="appTitle">Prices</h1>
      {first && (
        <span className="meta">
          COIN-0{' '}
          <NumberFlow
            value={first.price}
            format={{ style: 'currency', currency: 'USD' }}
          />
        </span>
      )}
    </header>
  );
}
```

```tsx title="PriceStream" {10,14}
import { useController } from '@data-client/react';
import { Ticker, newPrices } from './Ticker';
import { useTimed, Timing } from './Timing';
import PriceHeader from './PriceHeader';

function PriceStream() {
  const ctrl = useController();
  const [perRowMs, perRow] = useTimed(newPrices, rows =>
    Promise.all(
      rows.map(row => ctrl.set(Ticker, { product_id: row.product_id }, row)),
    ),
  );
  const [batchMs, batch] = useTimed(newPrices, rows =>
    ctrl.set([Ticker], rows),
  );

  return (
    <>
      <PriceHeader />
      <dl className="stats">
        <Timing label="500 set() calls" ms={perRowMs} />
        <Timing label="1 batch set()" ms={batchMs} />
      </dl>
      <div className="buttonGroup">
        <button onClick={perRow}>set() per row</button>
        <button onClick={batch}>batch set()</button>
      </div>
    </>
  );
}
render(<PriceStream />);
```

### setResponse(endpoint, ...args, response) {#setResponse}

Stores `response` in cache for given [Endpoint](https://dataclient.io/rest/api/Endpoint) and args.

Components suspending on this [Endpoint](https://dataclient.io/rest/api/Endpoint) and args resolve. Existing data for that Endpoint and args is updated; entities merge with their stored fields.

```tsx
import { useController } from '@data-client/react';
import { useEffect } from 'react';
import { EndpointLookup } from './EndpointLookup';

function useWebsocketUpdates(url: string) {
  const ctrl = useController();

  useEffect(() => {
    const websocket = new WebSocket(url);

    websocket.onmessage = event => {
      const { endpoint, args, data } = JSON.parse(event.data);
      ctrl.setResponse(EndpointLookup[endpoint], ...args, data);
    };

    return () => websocket.close();
  }, [ctrl, url]);
}
```

This is a proof of concept in React. A [Manager websockets implementation](./managers.md#data-stream)
is more robust.

### setError(endpoint, ...args, error) {#setError}

Stores `error` as the result of the [Endpoint](https://dataclient.io/rest/api/Endpoint) and args.

### resolve(endpoint, { args, response, fetchedAt, error }) {#resolve}

Resolves a specific fetch, storing the `response` in cache.

Like [setResponse](#setResponse), but `fetchedAt` ties the response to one fetch, so that fetch's optimistic update is
removed.

[NetworkManager](https://dataclient.io/docs/api/NetworkManager) uses it. Use it when a Manager processes fetch requests.

Pass the fetch action's `action.meta.fetchedAt` as `fetchedAt`. Then the store drops responses to fetches started before
[resetEntireStore()](#resetEntireStore), and an old response doesn't settle a newer fetch of the same key.

### subscribe(endpoint, ...args) {#subscribe}

Adds a subscription to the [Endpoint](https://dataclient.io/rest/api/Endpoint) and args. Each call increments its subscriber count.

[useSubscription](https://dataclient.io/docs/api/useSubscription) and [useLive](https://dataclient.io/docs/api/useLive) call this on mount.

Custom hooks can call it to subscribe based on other conditions.

```tsx
import {
  useController,
  type EndpointInterface,
  type FetchFunction,
  type Schema,
} from '@data-client/react';
import { useEffect } from 'react';

function useSubscribe<
  E extends EndpointInterface<FetchFunction, Schema | undefined, false | undefined>,
>(endpoint: E, ...args: readonly [...Parameters<E>]) {
  const controller = useController();
  const key = endpoint.key(...args);

  useEffect(() => {
    controller.subscribe(endpoint, ...args);
    return () => {
      controller.unsubscribe(endpoint, ...args);
    };
  }, [controller, key]);
}
```

### unsubscribe(endpoint, ...args) {#unsubscribe}

Removes a subscription to the [Endpoint](https://dataclient.io/rest/api/Endpoint) and args. Each call decrements its subscriber count; at
0, automatic updates stop.

[useSubscription](https://dataclient.io/docs/api/useSubscription) and [useLive](https://dataclient.io/docs/api/useLive) call this on unmount.

## Data Access

### get(schema, ...args, state) {#get}

Looks up any [Queryable](https://dataclient.io/rest/api/schema#queryable) [Schema](https://dataclient.io/rest/api/schema#schema-overview) in `state`.

#### Example

[useQuery](https://dataclient.io/docs/api/useQuery) builds on it, and [Managers](./Manager.md) can use it to read the store safely.

```tsx title="useQuery.ts"
import {
  useController,
  StateContext,
  type Queryable,
  type SchemaArgs,
  type DenormalizeNullable,
} from '@data-client/react';
import { useContext } from 'react';

/** Oversimplified useQuery */
function useQuery<S extends Queryable>(
  schema: S,
  ...args: SchemaArgs<S>
): DenormalizeNullable<S> | undefined {
  const state = useContext(StateContext);
  const controller = useController();

  return controller.get(schema, ...args, state);
}
```

### getResponse(endpoint, ...args, state) {#getResponse}

```ts title="returns"
{
  data: DenormalizeNullable<E['schema']>;
  expiryStatus: ExpiryStatus;
  expiresAt: number;
}
```

Gets the response for an endpoint and args from the given `state`.

#### data

The denormalized response. Every member keeps the same reference while its data is unchanged.

#### [expiryStatus](https://dataclient.io/docs/concepts/expiry-policy#expiry-status)

```ts
export enum ExpiryStatus {
  Invalid = 1,
  InvalidIfStale,
  Valid,
}
```

##### Valid

- Will never suspend.
- Might fetch if data is stale

##### InvalidIfStale

- Will suspend if data is stale.
- Might fetch if data is stale

##### Invalid

- Will always suspend
- Will always fetch

#### expiresAt

When the data expires, as a timestamp. Compare it to `Date.now()`.

#### Example

[useCache](https://dataclient.io/docs/api/useCache) and [useSuspense](https://dataclient.io/docs/api/useSuspense) build on it. [Managers](./Manager.md) can use it to look up a
response in the given state.

```tsx title="useCache.ts"
import {
  useController,
  StateContext,
  type EndpointInterface,
} from '@data-client/react';
import { useContext } from 'react';

/** Oversimplified useCache */
function useCache<E extends EndpointInterface>(
  endpoint: E,
  ...args: readonly [...Parameters<E>]
) {
  const state = useContext(StateContext);
  const controller = useController();
  return controller.getResponse(endpoint, ...args, state).data;
}
```

```tsx title="MyManager.ts"
import {
  type Manager,
  type Middleware,
  actionTypes,
} from '@data-client/react';

export default class MyManager implements Manager {
  declare protected websocket: WebSocket;

  middleware: Middleware = controller => {
    return next => async action => {
      if (action.type === actionTypes.FETCH) {
        console.log('The existing response of the requested fetch');
        console.log(
          controller.getResponse(
            action.endpoint,
            ...action.args,
            controller.getState(),
          ).data,
        );
      }
      next(action);
    };
  };

  cleanup() {
    this.websocket.close();
  }
}
```

### getError(endpoint, ...args, state) {#getError}

Gets the error for an endpoint and args, or `undefined` if there is none.

### snapshot(state, fetchedAt) {#snapshot}

Returns a [Snapshot](https://dataclient.io/docs/api/Snapshot).

### getState() {#getState}

Gets the internal state of Reactive Data Client that has _already been [committed](https://react.dev/learn/render-and-commit#step-3-react-commits-changes-to-the-dom)_.

> **Warning**
>
> Use it only outside components: in [Managers](./Manager.md), or in code like router loaders.
>
> Calling getState() during render can cause data tearing.

To act on a mutation's result, use the value `fetch()` resolves with instead of `getState()`. A
[mutation](#endpointsideeffect) resolves _before_ the store is updated, so `getState()` doesn't have its response yet.
The resolved value is the denormalized response.

```tsx
import { useController } from '@data-client/react';
import { useNavigate } from 'react-router';
import { PostResource } from './PostResource';

function UpdatePost({ id }: { id: string }) {
  const ctrl = useController();
  const navigate = useNavigate();

  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const post = await ctrl.fetch(
      PostResource.update,
      { id },
      new FormData(e.currentTarget),
    );
    navigate(`/posts/${post.id}`);
  };

  return <form onSubmit={handleSubmit}>{/* ... */}</form>;
}
```
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 117kUpdated Claude CodeCodexVerifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 117kUpdated Claude CodeCodexVerifiedInstall