Coding Agents:

• One-prompt setup - Add the data-client plugin to Claude Code, Cursor or Codex and ask it to set up Data Client; it installs the packages, adds the provider and links the skills your app needs
• Skills ship in the packages - npx --no data-client-skills links the skills your installed @data-client/* packages carry, so your agent follows the version you have instead of an older release
• Agents keep using Data Client - Setup adds a note to AGENTS.md, and each skill names the everyday tasks it covers, so later sessions reach for Data Client instead of fetch in useEffect
• Debug the running app - In development, globalThis.__DC__ gives your agent the store's Controller and recent actions from Cursor's browser, Chrome DevTools MCP, Playwright MCP or Claude in Chrome
• Vue skills, llms.txt, and skills generated from these docs

New APIs:

• Controller.set() with Array schemas - Write many entities in one store update with ctrl.set([Entity], rows), up to 95x faster than one set() per row

Performance:

• Faster TypeScript - Editors and tsc check RestEndpoint and resource() code about 2x faster with 40% less memory, catching every error they caught before

Other Improvements:

• Fix TypeScript 7 module resolution for package exports; imports now resolve to declaration files (#4019)
• renderDataHook() runs provider mount effects when the first render suspends (#4099)
• Controller.set() values are typed by the schema, so ctrl.set(new schema.All(Todo), 42) is a TypeScript error (#4133)
• Controller.set() deletes one entity with an Invalidate schema without the one-row batch workaround (#4230)
• process() gets typed params in new RestEndpoint(), .extend() and resource().extend(), so a wrong path parameter is a TypeScript error instead of undefined at runtime (#4183, #4184)
• getOptimisticResponse() returns are typed by the schema, so a wrong field type is a TypeScript error instead of a flash of bad data (#4198)
• Vue useSuspense() and useLive() keep the previous data while new arguments load, instead of returning undefined (#4131)
• Vue useSuspense() and useLive() send fetch errors after arguments change to onErrorCaptured() instead of an unhandled promise rejection (#4135)
• Vue useSuspense(), useDLE() and useFetch() no longer refetch stale data on every store update, so a controller.set() is not overwritten (#4134)
• Vue useSuspense() shows stale data on mount and refetches in the background, like React, instead of showing the <Suspense> fallback until the refetch finishes (#4169)
• Vue useDLE() and useCache() keep expired invalidIfStale data through unrelated store updates instead of getting stuck loading (#4142)
• Vue DataClientPlugin installs on Vue versions before 3.5 instead of throwing app.onUnmount is not a function (#4146)
• Vue DataClientPlugin garbage collects by default, matching React's DataProvider, so you no longer need to pass gcPolicy; how it decides what to remove (#4148)
• Vue composables accept getter arguments like () => ({ id: props.id }); they were typed to allow them but passed the function itself to the endpoint (#4115)
• Fix Cannot find name 'NoInfer' and export type errors on TypeScript 4.x with skipLibCheck off (#4138)
• Fix Entity, Endpoint, Union and RestEndpoint type errors on TypeScript 4.0–4.5 with skipLibCheck off (#4140)
• Fix ',' expected errors importing @data-client/react/redux, @data-client/react/nextjs or @data-client/test on TypeScript 4.0–4.4 (#4232)
• Fix act and renderHook from @data-client/test typed as any on TypeScript 4.0–4.4 (#4251)
• React Native useSuspense(), useFetch() and useDLE() refetch on screen focus only when the current data is stale or invalid, instead of refetching fresh data on every refocus (#4378)
• renderDataHook() works with React Native Testing Library 14 and stays synchronous, so renderDataHook() calls need no await (#4374)
• Entity classes can be used where an EntityInterface is expected (#4149); prepare pk() overrides for a future release
• useCache() and useDLE() return undefined for a deleted entity whose refetch failed, instead of a truthy Symbol that slipped past if (!data) checks; remove any workarounds (#4150)
• Vue useFetch() keeps its data from being garbage collected while mounted, like useSuspense(), so a configured gcPolicy no longer evicts prefetched data that components read later (#4152)
• Apps with Redux DevTools open no longer stutter in development on large stores or frequent updates; each update serializes 40-60x faster (#4163)
• resource().extend() with an object of endpoint overrides keeps endpoints added earlier with .extend('name', options) in its type, so using them is no longer a TypeScript error (#4184)
• RestEndpoint.push, unshift and remove accept the Entity's fields as the body when a Query or Lazy wraps the Collection, instead of only FormData (#4226)
• Vue useFetch() is typed as the read-only Ref it returns, so promise.resolved (always undefined) is now a TypeScript error; read promise.value.resolved instead (#4114)
• A Controller subclass passed to DataProvider or DataClientPlugin no longer needs a cast to type-check (#4228)
• prepareStore()'s store can be passed to react-redux's <Provider> without a cast, and has dispatch() in its type (#4238)
• resource().create accepts FormData without a cast, like update, partialUpdate and getList.push (#4235)
• RestEndpoint.push, unshift and remove send an array body as JSON, so creating or removing several items at once no longer sends "[object Object]" to your server; resource().create takes an array too (#4262)
• Polling keeps the schema of endpoints given pollFrequency with .extend(), so a polled useLive() list updates right away from mutations and optimistic updates instead of waiting for the next poll (#4437)
• DataProvider only warns that it doesn't update during SSR when something fetches while the server renders, instead of on every server render, so pages that load data after mount (like Expo Router's static web output) stay quiet (#4449)
• Server rendering with React 19 no longer logs "Uncaught suspense" when nothing suspended; React renders and discards fallbacks of large boundaries, and the warning now waits for a fallback that actually shows (#4450)
• Vue createDataClient() is deprecated, since it's internal to DataClientPlugin; install the plugin with app.use(DataClientPlugin, options) instead of calling it directly (#4193)
• Vue renderDataCompose()'s waitForNextUpdate() is deprecated, since it gives up silently after 1 second and lets a test pass while still suspended; await result instead, or await allSettled() after a change, which now also waits for fetches a prop change starts (unit testing composables, #4221)

Breaking Changes:

• TypeScript 4.0 or later is required - the TypeScript 3.x declarations are removed (#4151)
• Managers must define middleware - getMiddleware() is removed (#4378, #4382)
• @data-client/test requires @data-client/react 0.15.3 or later (#4414)
• globalThis.__DC__ replaces __DC_CONTROLLERS__ in development (#4435)

Get ready for future releases:

• Type args as readonly in Entity.pk() overrides
• Use DataClientPlugin instead of Vue createDataClient()
• Replace waitForNextUpdate() in Vue tests

Coding agents​

Coding agents write a lot of Data Client code, and they write it well when they have the current APIs instead of guessing from older releases they were trained on. v0.19 gets your agent those APIs in one step, keeps them matched to the version you install, and lets it check the running app.

Set up with one prompt​

Add the data-client plugin to your agent, then ask it to set up Data Client:

claude plugin marketplace add reactive/data-client --scope project \
  --sparse .claude-plugin .agents/skills
claude plugin install data-client@data-client --scope project

codex plugin marketplace add reactive/data-client \
  --sparse .claude-plugin --sparse .agents/skills
codex plugin add data-client@data-client

The setup skill detects React or Vue and your API style (REST, GraphQL or custom async functions), installs the packages, adds the provider, and links the skills those packages ship. For REST it also moves your existing fetch or axios calls to endpoints (#4153). Claude Code installs the plugin for the project, so teammates who open it get the plugin too. The package READMEs on npm open with the same setup (#4454).

The plugin only sets apps up, so it carries just the setup skill and the data-client skill below. Every other skill comes from your packages, below. Agents without a plugin take the Other agents prompt, which installs the setup skill with the skills CLI first. #4410, #4425, #4427, #4439, #4440

Skills ship in the packages​

Each @data-client/* package now carries the skills for its own APIs, so your agent follows the version you have installed and gets new guidance with each upgrade. data-client-skills (in @data-client/react, vue, rest, graphql and endpoint) links them into .agents/skills, with .claude/skills linking to it, where Claude Code, Cursor and Codex load them as their own skills.

npx skills add reactive/data-client \
  --skill data-client-react --skill data-client-rest --skill data-client-schema

npx --no data-client-skills

Commit the links, and run the command again after adding, removing or upgrading @data-client packages (Agent Skills has the details). If you installed skills with npx skills add before, remove those copies first (npx skills remove data-client-react -y); the command keeps folders it didn't create and says so. #4407, #4410

Upgrade skills ship in the packages too. data-client-v0.18-migration runs the codemod, then handles what it can't (v0.18 migration), and path-to-regexp-v8-migration rewrites path syntax in your endpoints.

Agents keep using Data Client​

An agent in a later session doesn't know the setup happened, so it can fall back to fetch in useEffect or app-wide context. Setup now adds a note to your project's AGENTS.md, which Cursor, Codex and Claude Code read at the start of every session (setup adds @AGENTS.md to your CLAUDE.md if you have one):

This app manages server state (fetching, caching, mutations and real-time updates) with Reactive Data Client. Use it
for all server data, and read the matching `data-client-*` skill before writing, changing or debugging code that loads
or changes data. After adding, removing or upgrading `@data-client/*` packages, run `npx --no data-client-skills` and
commit the skill links.

Each skill's description now names the work it covers in everyday terms, like loading and error states, forms, or data that looks stale on screen, instead of listing hook names, so agents load it for those tasks even when you never mention Data Client. Adding or changing an endpoint that returns data loads data-client-schema, so the endpoint's responses are normalized into the shared cache with Entities. The data-client skill starts any Data Client task and points your agent at the skill for it. #4408, #4428, #4453

Debug the running app​

Ask your agent "why didn't this refetch?" or "what's in the cache right now?" and it can check the running app instead of guessing from code. In development, DevToolsManager puts the store on globalThis.__DC__: __DC__.controller is its Controller, and __DC__.actions its recent actions, recorded from the moment the app starts, with or without the Redux DevTools extension. Production builds don't include it.

__DC__.controller.getState();
__DC__.actions.slice(-10);

The React and Vue skills read it from any browser tool that runs JavaScript in the page: Cursor's built-in browser, Chrome DevTools MCP, Playwright MCP or Claude in Chrome, and match dispatched actions to network requests; see debugging with agents. If your own scripts read __DC_CONTROLLERS__, switch them to __DC__. #4435, #4428, #4447

Vue skills​

Vue projects used to get the React hooks skill, so agents reached for React patterns. The data-client-vue skill writes DataClientPlugin and composable code and debugs a running app, and data-client-vue-testing writes renderDataCompose() and mountDataClient() tests that follow the Vue testing guides. #4126, #4181

llms.txt​

Agents without skills can read the docs as markdown, following the llms.txt convention:

• llms.txt for React and vue/llms.txt for Vue index every page, and llms-full.txt beside each holds them all in one file
• rest/llms.txt and graphql/llms.txt cover just that package's API
• Any docs page is markdown when you add .md to its URL, like /docs/api/useSuspense.md

Every page links its llms.txt in <head>, and every docs page links its markdown, so an agent given any page URL finds them on its own. The setup pages' markdown gives agents the setup steps directly. #4171, #4236, #4427

Skills match the docs​

Skill reference pages are generated per framework from these docs, so they carry shared snippets like install commands and give Vue projects only Vue code. A CI check fails when a skill drifts from the docs, so skills stay current with each release. #4170

Batch Controller.set()​

A Manager that receives a stream of rows (like price tickers over a websocket) can now write them all with one Controller.set() by passing an Array schema. Before v0.19, [Ticker] was a TypeScript error, so the usual workaround was a set() per row:

ws.onmessage = event => {
  const rows = JSON.parse(event.data);
  for (const row of rows) {
    ctrl.set(Ticker, { product_id: row.product_id }, row);
  }
};

ws.onmessage = event => {
  const rows = JSON.parse(event.data);
  ctrl.set([Ticker], rows);
};

Each row merges with its stored entity, and entities not in the list are untouched. Array schemas take no args and no updater function. To batch mixed Entity types, deletes, or rows keyed by id, pass a Union, Invalidate, or Values schema; see Controller.set() for examples. #4103

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.

import React from 'react';
import { useController, useQuery } from '@data-client/react';
import { Ticker, newPrices } from './Ticker';

function PriceStream() {
  const ctrl = useController();
  const [timing, setTiming] = React.useState('');
  const first = useQuery(Ticker, { product_id: 'COIN-0' });

  const time = async (
    label: string,
    write: (rows: ReturnType<typeof newPrices>) => Promise<unknown>,
  ) => {
    const rows = newPrices();
    const start = performance.now();
    await write(rows);
    setTiming(`${label}: ${(performance.now() - start).toFixed(1)} ms`);
  };
  const perRow = () =>
    time('500 set() calls', rows =>
      Promise.all(
        rows.map(row => ctrl.set(Ticker, { product_id: row.product_id }, row)),
      ),
    );
  // highlight-next-line
  const batch = () => time('1 batch set()', rows => ctrl.set([Ticker], rows));

  return (
    <div>
      <button onClick={perRow}>set() per row</button>{' '}
      <button onClick={batch}>batch set()</button>
      <p>COIN-0: {first ? `$${first.price}` : 'no data yet'}</p>
      <p>{timing}</p>
    </div>
  );
}
render(<PriceStream />);

Performance​

Each set() is a separate store update, and every store update copies that entity type's table. Writing rows one at a time repeats that copy for every row, so the cost grows with both the batch size and the store size. A batch pays that copy once.

The chart is the node setMany benchmark in examples/benchmark/core.js: a store that already holds 500 entities, then a synchronous set() per row against one set([Ticker], rows). It measures the store update: 20x faster for 50 rows and 95x faster for 500 rows. #4103

In a Manager, buffer incoming messages and flush each batch with one set(), as described in Batching high-frequency updates. The coin app's StreamManager now flushes Coinbase ticker messages this way.

handleMessage(msg: any) {
  if (msg.type in this.entities) {
    (this.buffer[msg.type] ??= {})[msg.product_id] = msg;
    this.flushTimeout ??= setTimeout(this.flush, 50);
  }
}

flush = () => {
  const buffer = this.buffer;
  this.buffer = {};
  this.flushTimeout = undefined;
  for (const type in buffer) {
    this.controller.set([this.entities[type]], Object.values(buffer[type]));
  }
};

更多演示

Faster TypeScript​

TypeScript re-checks your code on every keystroke in the editor and on every CI build. In apps with many endpoints, heavy library types show up as laggy autocomplete, red squiggles that take seconds to appear, and slower builds. v0.19 makes RestEndpoint, resource() and .extend() much cheaper to check, with no code changes on your side. TypeScript still reports every error it reported before (#4173).

Results​

Our heaviest stress test, a file of 150 RestEndpoints with long paths, .extend() and .paginated(), now checks 2x faster on TypeScript 6 and 2.2x faster on TypeScript 7, using about 40% less memory. All numbers compare the published v0.18.1 packages with v0.19; check times are the best of 10 runs.

Endpoint-heavy code does much less type work. Type instantiations are TypeScript's unit of work: they're deterministic, so they compare cleanly across machines. Union does more work than in v0.18, because v0.19 now type-checks set() values (see below).

Hover or tap a cell for exact numbers.

The set() rows measure typed set() values, which v0.18 didn't check at all. Plain values still check faster than before, and updater functions on large Unions check in about the same time even though TypeScript now checks each updater's return value (#4179).

Small files are dominated by TypeScript's fixed startup cost (loading lib.dom.d.ts alone takes about 100MB), so their time and memory barely move. The savings add up as a codebase grows.

What changed​

• .extend() and .paginated() are shared across all endpoints instead of re-created for each endpoint type.
• Endpoint options infer as plain object types, so TypeScript stops rebuilding them at every use.
• Path parameters like /users/:id are read in a single pass.

Before shipping, we turned off every @ts-expect-error in the test suite on TypeScript 4.0 through 7 and confirmed every error still appears in the same place.

On TypeScript 5.x and earlier, a process(value, params) method passed to .extend() also no longer fails with "implicitly has an 'any' type" under strict.

Other improvements​

Typed set() values​

Controller.set() previously accepted any value for a schema, so a typo or a wrong field type only surfaced as bad data at runtime. Values are now typed by the schema: an Entity takes its fields, while a Collection, All or Array takes a list of rows. Every field is optional, since set() merges into what is already stored, and numbers and strings are interchangeable just like in API responses. #4133

Hover the red underlines to see each error.

import type { Controller } from '@data-client/react';
import { schema } from '@data-client/rest';
import { Todo, TodoResource } from './Todo';

export function updateTodos(ctrl: Controller) {
  // ✅ rows are partial Todos; ids may be strings or numbers
  ctrl.set(TodoResource.getList.schema, [{ id: '5', completed: true }]);
  ctrl.set(Todo, { id: 5 }, todo => ({ completed: !todo.completed }));
  ctrl.set([Todo], [{ id: 1, title: 'first' }, { id: 2 }]);

  // ❌ All takes a list of rows
  ctrl.set(new schema.All(Todo), 42);
  // ❌ completed is a boolean
  ctrl.set(Todo, { id: 5 }, { id: 5, completed: 'yes' });
  // ❌ Todo has no done field
  ctrl.set(TodoResource.getList.schema, [{ id: 5, done: true }]);
  // ❌ updaters must return Todo fields
  ctrl.set(Todo, { id: 5 }, todo => ({ title: todo.completed }));
}

A Query takes the input of the schema it wraps, since set() normalizes that schema rather than reversing process(). When each member declares its discriminator as a literal (like readonly type = 'post'), a Union row is checked against the member it selects, so it can't mix fields from different members; see Unions.

If code that previously compiled now fails here, it was writing data its schema doesn't describe. Fix the value, or widen the Entity's field types if the data really can take that shape.

Delete one entity with set()​

Passing an Invalidate schema to Controller.set() deletes the entity its row identifies, but the single form was a TypeScript error, so code wrapped it in a one-row batch. It now type-checks, with the row typed by the Entity's fields (#4230):

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

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

Like batch set(), it takes no args and no updater function.

Typed process() params​

A process() method passed to new RestEndpoint(), .extend() or resource().extend() got params typed as any, so reading a parameter the endpoint doesn't have compiled and returned undefined at runtime. params and body are now typed from the endpoint, including a path set in the same .extend() call (#4183, #4184):

import { RestEndpoint } from '@data-client/rest';

const getUser = new RestEndpoint({ path: '/users/:id' });

export const getUserById = getUser.extend({
  path: '/users/by-id/:userId',
  process(value, params) {
    const userId: string | number = params.userId;
    // @ts-expect-error 'id' is not a param of '/users/by-id/:userId'
    params.id;
    return { ...value, userId };
  },
});

When every param is optional, params may be undefined, so read it with params?.page.

This can surface new TypeScript errors in existing process() methods. Each one marks a read that could be undefined or throw at runtime, so fix the param name or add the missing check.

Typed optimistic responses​

getOptimisticResponse() could return anything unless the endpoint had a typed process(), so a wrong field type only showed up as bad data in the UI until the server responded. The return value is now checked against the endpoint's schema, like a typed set() value: an Entity takes any of its fields, and a Collection takes a list of them (#4198):

import { Entity, RestEndpoint } from '@data-client/rest';

class Todo extends Entity {
  id = 0;
  title = '';
  completed = false;
}

export const toggleTodo = new RestEndpoint({
  path: '/todos/:id',
  method: 'PATCH',
  schema: Todo,
  // @ts-expect-error completed is a boolean; 'false' is truthy, so the checkbox would stay checked
  getOptimisticResponse(snap, { id }) {
    const todo = snap.get(Todo, { id });
    if (!todo) throw snap.abort;
    return { id, completed: todo.completed ? 'false' : 'true' };
  },
});

This can surface new TypeScript errors in existing getOptimisticResponse() methods. Each one marks a value that would be stored with the wrong type until the server responds, so return the field's real type (here !todo.completed).

Typed push() on sorted Collections​

Wrapping a Collection in a Query to sort or filter it made push, unshift and remove reject every body except FormData, though they add to the list at runtime. The body is now typed from the Collection's Entity, so the cast can go and a wrong field is a TypeScript error. The same applies to a Collection wrapped in Lazy (#4226).

import { useController } from '@data-client/react';
import { getPosts } from './getPosts';

export function useAddPost() {
  const ctrl = useController();
  return (title: string, author: string) =>
    ctrl.fetch(getPosts.push, { group: 'react' }, { title, author } as any);
}

import { useController } from '@data-client/react';
import { getPosts } from './getPosts';

export function useAddPost() {
  const ctrl = useController();
  return (title: string, author: string) =>
    ctrl.fetch(getPosts.push, { group: 'react' }, { title, author });
}

where getPosts sorts its Collection with a Query:

import { Collection, Entity, Query, RestEndpoint } from '@data-client/rest';

export class Post extends Entity {
  id = '';
  title = '';
  group = '';
  author = '';
}

export const getPosts = new RestEndpoint({
  path: '/:group/posts',
  searchParams: {} as { orderBy?: 'title' | 'author' },
  schema: new Query(
    new Collection([Post], { nonFilterArgumentKeys: /orderBy/ }),
    (posts, { orderBy }: { orderBy?: 'title' | 'author' } = {}) =>
      orderBy ?
        [...posts].sort((a, b) => a[orderBy].localeCompare(b[orderBy]))
      : posts,
  ),
});

FormData in resource().create​

resource()'s create sends a FormData body as-is, like update, partialUpdate and getList.push, but its type only allowed an object, so submitting a form needed a cast (#4235). Drop the cast:

<form
  onSubmit={e => {
    e.preventDefault();
    ctrl.fetch(PostResource.create, new FormData(e.currentTarget) as any);
  }}
>

<form
  onSubmit={e => {
    e.preventDefault();
    ctrl.fetch(PostResource.create, new FormData(e.currentTarget));
  }}
>

create is deprecated; getList.push is its replacement and takes FormData too.

Vue getter arguments​

Vue composables like useSuspense() and useLive() were typed to accept a getter function as an argument, but they passed the function itself to the endpoint instead of calling it. Getters now work the same as refs and computed, and the composable refetches when anything the getter reads changes (#4115). Drop the computed() wrapper if you only used it to make arguments reactive:

import { computed } from 'vue';

const props = defineProps<{ id: number }>();
const article = await useSuspense(
  ArticleResource.get,
  computed(() => ({ id: props.id })),
);

const props = defineProps<{ id: number }>();
const article = await useSuspense(ArticleResource.get, () => ({
  id: props.id,
}));

This applies to every composable that takes endpoint arguments: useSuspense(), useLive(), useCache(), useDLE(), useFetch(), useQuery() and useSubscription().

Vue garbage collects by default​

Vue's DataClientPlugin only removed unused data if you passed a gcPolicy yourself. It now defaults to new GCPolicy(), the same as React's DataProvider, so you can drop the option unless you customize it (#4148).

import { DataClientPlugin, GCPolicy } from '@data-client/vue';

app.use(DataClientPlugin, { gcPolicy: new GCPolicy() });

import { DataClientPlugin } from '@data-client/vue';

app.use(DataClientPlugin);

Data is removed only when no mounted component reads it and twice its freshness lifetime has passed since it was fetched (at least two minutes). A sweep checks every five minutes. Anything a component reads again before then is back in use.

A component that mounts after removal treats the data as never fetched: useSuspense() fetches it again, while useCache() returns undefined. To keep unused data longer or sweep less often, pass your own gcPolicy.

Vue stale-while-revalidate​

When a component mounts with data that is stale but still valid, Vue useSuspense() now renders it right away and refetches in the background, like React. Before, it showed the <Suspense> fallback until the refetch finished (#4169).

Entity classes typecheck as EntityInterface​

Helpers typed to accept any Entity with EntityInterface rejected Entity classes, because Entity.pk() typed its args as a mutable array. It is now readonly any[], so this typechecks (#4149):

import { Entity } from '@data-client/rest';
import type { EntityInterface } from '@data-client/react';

class User extends Entity {
  id = '';
  name = '';
}

function entityName(schema: EntityInterface) {
  return schema.key;
}

entityName(User);

If you override static pk() and type args as a mutable array, it still compiles, but a future breaking release will require readonly; update it now.

Deleted entities read as undefined​

When an entity was deleted and its refetch failed, useCache() and useDLE() (React and Vue) returned an internal Symbol as data. A Symbol is truthy, so the usual "not loaded yet" guard let it through and the component rendered as if it had an entity (#4150):

function TodoDetail({ id }: { id: number }) {
  const todo = useCache(TodoResource.get, { id });
  // a deleted todo used to get past this guard, so todo.title.trim() threw
  if (!todo) return <TodoPlaceholder />;
  return <h3>{todo.title.trim()}</h3>;
}

Now data is undefined, matching its type and Controller.get(). The same applies to Controller.getResponse() and Controller.fetchIfStale(), for example in custom Managers.

If you worked around this, the workaround can go. A plain truthiness check is enough:

function TodoDetail({ id }: { id: number }) {
  const todo = useCache(TodoResource.get, { id });
  if (!todo || typeof todo === 'symbol') return <TodoPlaceholder />;
  return <h3>{todo.title.trim()}</h3>;
}

function TodoDetail({ id }: { id: number }) {
  const todo = useCache(TodoResource.get, { id });
  if (!todo) return <TodoPlaceholder />;
  return <h3>{todo.title.trim()}</h3>;
}

To show something specific when the refetch failed (for example a 404 after deletion), read error from useDLE() rather than inspecting data.

Faster Redux DevTools​

With the Redux DevTools extension open, every store update in development serializes the whole store for the extension, and each timestamp in it was formatted the slow way. Large stores or frequent updates, like polling, live data or many controller.set() calls, made the page stutter. Each update now serializes 40-60x faster, and timestamps still read like 10:42:07.123 AM (#4163). Production builds don't include DevTools, so they are unaffected.

Migration guide​

This upgrade requires updating all package versions simultaneously.

npm install --save @data-client/react@^0.19.0 @data-client/rest@^0.19.0 @data-client/endpoint@^0.19.0 @data-client/core@^0.19.0 @data-client/vue@^0.19.0 @data-client/test@^0.19.0 @data-client/img@^0.19.0

yarn add @data-client/react@^0.19.0 @data-client/rest@^0.19.0 @data-client/endpoint@^0.19.0 @data-client/core@^0.19.0 @data-client/vue@^0.19.0 @data-client/test@^0.19.0 @data-client/img@^0.19.0

pnpm add @data-client/react@^0.19.0 @data-client/rest@^0.19.0 @data-client/endpoint@^0.19.0 @data-client/core@^0.19.0 @data-client/vue@^0.19.0 @data-client/test@^0.19.0 @data-client/img@^0.19.0

<script type="importmap">
{
  "imports": {
    "@data-client/react": "https://esm.sh/@data-client/react@^0.19.0",
    "@data-client/rest": "https://esm.sh/@data-client/rest@^0.19.0",
    "@data-client/endpoint": "https://esm.sh/@data-client/endpoint@^0.19.0",
    "@data-client/core": "https://esm.sh/@data-client/core@^0.19.0",
    "@data-client/vue": "https://esm.sh/@data-client/vue@^0.19.0",
    "@data-client/test": "https://esm.sh/@data-client/test@^0.19.0",
    "@data-client/img": "https://esm.sh/@data-client/img@^0.19.0"
  }
}
</script>

TypeScript 4.0 or later​

Skip this section if you already use TypeScript 4.0 or later.

The TypeScript 3.x declarations are removed, since they no longer typechecked on any TypeScript 3.x version. Bump typescript to ^4.0.0 or later in your devDependencies. #4151

Manager.middleware is required​

Skip this section if your Managers already define middleware.

getMiddleware() was replaced by the middleware property in v0.14; it's now removed. A Manager that still defines it, or has no middleware at all, is a TypeScript error, and throws when DataProvider or DataClientPlugin mounts in development. Rename getMiddleware() to a middleware property:

class LoggingManager implements Manager {
  getMiddleware = (): Middleware => controller => next => async action => {
    console.log('before', action, controller.getState());
    await next(action);
    console.log('after', action, controller.getState());
  };

  cleanup() {}
}

class LoggingManager implements Manager {
  middleware: Middleware = controller => next => async action => {
    console.log('before', action, controller.getState());
    await next(action);
    console.log('after', action, controller.getState());
  };

  cleanup() {}
}

#4382

@data-client/test requires @data-client/react 0.15.3​

Skip this section if you don't use @data-client/test.

@data-client/test now builds on @data-client/react/mock, which first loads in Jest and other CommonJS tests in @data-client/react 0.15.3, so support for 0.12 through 0.15.2 is dropped. Upgrade @data-client/react to the same version as @data-client/test, as the install command above does. Fixture types imported from @data-client/test and from @data-client/react/mock are now the same types. #4414

__DC_CONTROLLERS__ is now __DC__​

Skip this section if no debugging script or tool of yours reads globalThis.__DC_CONTROLLERS__.

In development, DevToolsManager now puts the store on globalThis.__DC__, whose controller and actions read the page's store, instead of the __DC_CONTROLLERS__ Map. With several stores, __DC__.stores lists their keys and setting __DC__.store picks one.

__DC_CONTROLLERS__.get('Data Client: My App').getState();

__DC__.store = 'Data Client: My App'; // only needed with several stores
__DC__.controller.getState();

#4435

Get ready for future releases​

Nothing here is needed to upgrade to 0.19; your code keeps working as is. Each item will break in a future release, so updating now makes that upgrade a no-op.

Entity.pk() args are readonly​

Skip this if you don't override static pk() with a typed args parameter.

Entity.pk() now types args as readonly any[]. Overrides that annotate it as a mutable array still compile for now, but a future release will require readonly.

class User extends Entity {
  static pk(value: any, parent?: any, key?: string, args?: any[]) {
    return `${value.id}-${args?.[0]?.org}`;
  }
}

class User extends Entity {
  static pk(value: any, parent?: any, key?: string, args?: readonly any[]) {
    return `${value.id}-${args?.[0]?.org}`;
  }
}

Vue createDataClient()​

Skip this if you install the store with app.use(DataClientPlugin).

createDataClient() and ProvidedDataClient are internal to DataClientPlugin and will stop being exported. Install the plugin instead, and read the controller with useController(). #4193

import { createDataClient } from '@data-client/vue';

const { controller } = createDataClient({ managers, initialState });

import { DataClientPlugin, useController } from '@data-client/vue';

app.use(DataClientPlugin, { managers, initialState });
// in a component's setup()
const controller = useController();

Vue renderDataCompose() waitForNextUpdate()​

Skip this if your Vue tests don't call waitForNextUpdate().

waitForNextUpdate() from renderDataCompose() gives up silently after 1 second, so a test can pass while the composable is still suspended. It will be removed. await the result instead, and call allSettled() after changing props or calling the controller; it now also waits for the fetch a prop change starts. #4221

const { result, waitForNextUpdate } = await renderDataCompose(
  (props: { id: number }) =>
    useSuspense(ArticleResource.get, () => ({ id: props.id })),
  { props, resolverFixtures },
);
await waitForNextUpdate();
const article = await result;

props.id = 6;
await waitForNextUpdate();

const { result, allSettled } = await renderDataCompose(
  (props: { id: number }) =>
    useSuspense(ArticleResource.get, () => ({ id: props.id })),
  { props, resolverFixtures },
);
const article = await result;

props.id = 6;
await allSettled();

Upgrade support​

As usual, if you have any troubles or questions, feel free to join our or file a bug

新特性：

• Scalar schema - 随视角（lens）变化的实体字段（例如特定投资组合的数值），且永不修改底层实体
• RestEndpoint content 属性 - 只用一个属性即可实现类型化文件下载、文本响应和流式传输
• resource() nonFilterArgumentKeys - 排序/分页参数不再把你的 Collection 拆散

其他改进：

• 二进制 Content-Type 自动检测 - 图片、PDF 及其他二进制响应无需任何配置即可自动处理（#3868）
• Collection 扩展方法的 body 类型与 HTTP 方法语义一致 - PATCH 扩展方法（.move、.remove）接受部分 body；独立的 RestEndpoint 会从 Collection 的实体 schema 推导出类型化的 body（#3910）
• 从 @data-client/endpoint 和 @data-client/rest 导出 CollectionOptions，用于类型化地构造 Collection（#3904）

import { Collection, Entity, RestEndpoint, Scalar } from '@data-client/rest';

export class Company extends Entity {
  id = '';
  name = '';
  price = 0;
  pct_equity = 0;
  shares = 0;
}

const PortfolioScalar = new Scalar({
  lens: args => args[0]?.portfolio,
  key: 'portfolio',
  entity: Company,
});
Company.schema = {
  pct_equity: PortfolioScalar,
  shares: PortfolioScalar,
};

export const getCompanies = new RestEndpoint({
  path: '/companies',
  searchParams: {} as { portfolio: string },
  // `portfolio` is a lens, not a filter — the returned Company list is the same
  // regardless of lens. Dropping it from `argsKey` collapses every portfolio to
  // one Collection pk, so `Collection.queryKey()` finds the list on every
  // switch and `useSuspense` reuses it without refetching.
  schema: new Collection([Company], { argsKey: () => ({}) }),
});

export const getPortfolioColumns = new RestEndpoint({
  path: '/companies/columns',
  searchParams: {} as { portfolio: string },
  schema: new Collection([PortfolioScalar], {
    argsKey: ({ portfolio }: { portfolio: string }) => ({ portfolio }),
  }),
});

这个示例展示了同一批 Company 实体通过不同的投资组合视角进行渲染。稳定的 Entity 字段会被复用，而随视角变化的值则从独立的 Scalar 单元格中选取。

破坏性变更：

• Schema.denormalize() 接收 delegate - denormalize(input, args, unvisit) → denormalize(input, delegate)。仅影响自定义 Schema 实现。
• Schema.normalize() 接收 delegate - normalize(input, parent, key, args, visit, delegate) → normalize(input, parent, key, delegate)。仅影响自定义 Schema 实现。

**在使用 AI 智能体？**安装迁移 skill——它会运行 codemod，为依赖参数的 schema 注册 argsKey，并处理 codemod 无法覆盖的情况（类字段、动态方法赋值、SFC <script> 块、自定义辅助函数）：

npx skills add reactive/data-client --skill data-client-v0.18-migration

npx openskills install reactive/data-client/.agents/skills/data-client-v0.18-migration

否则，直接运行 codemod——它覆盖了常见情况：

npx jscodeshift -t https://dataclient.io/codemods/v0.18.js --extensions=ts,tsx,js,jsx src/

Scalar​

Scalar 用于处理那些取值依赖运行时“视角”（lens）的 Entity 字段——比如当前选中的投资组合、货币或区域设置。多个组件可以同时通过不同视角渲染同一个实体，各自看到正确的值，而实体本身始终不变。随视角变化的值存放在单独的单元格表中，并在反规范化时根据 endpoint 参数进行关联。

切换投资组合时 name 和 price 的引用保持稳定，因为 Company 实体本身从未改变——改变的只是当前视角所选中的 Scalar 单元格。同一个 Scalar 实例既可以作为 Entity.schema 字段使用（父实体从访问过程中推断），也可以独立用在 Values、[Scalar] 或 Collection([Scalar]) 中，以实现低成本的仅刷新列操作（通过 entity 显式绑定实体）。单元格的 pk 由映射键派生，或通过 Scalar.entityPk() 得到，后者默认使用 Entity.pk()，因此自定义主键和复合主键无需重写即可正常工作。

规范化后的 store 保持实体稳定，并把视角单元格分开存放：

entities['Company']['1'] = {
  id: '1',
  price: 145.20,
  pct_equity: ['1', 'pct_equity', 'Company'],
  shares: ['1', 'shares', 'Company'],
}

entities['Scalar(portfolio)']['Company|1|A'] = { pct_equity: 0.50, shares: 10000 }
entities['Scalar(portfolio)']['Company|1|B'] = { pct_equity: 0.30, shares: 6000 }

示例将 getCompanies 与一个低成本的、仅刷新视角数据的 getPortfolioColumns 配对，二者写入同一个单元格表——完整的缓存行为讲解请参阅 Scalar 文档。

Scalar 还实现了 queryKey，因此可以直接参与 useQuery、Controller.get 和 schema.Query—— 即完整的 Queryable 能力——枚举当前视角下的所有单元格。

#3887 - Scalar 文档

RestEndpoint content 属性​

RestEndpoint 现在接受一个 content 属性，用于控制响应体的解析方式。返回类型会根据该值自动推断，并且对于非 JSON 的内容类型，schema 在类型层面被约束为 undefined。

import { RestEndpoint } from '@data-client/rest';

const downloadFile = new RestEndpoint({
  path: '/files/:id/download',
  content: 'blob',
  dataExpiryLength: 0,
});

// Return type is Blob — inferred from content, no explicit generics needed
const blob: Blob = await ctrl.fetch(downloadFile, { id: '123' });

以前，文件下载需要冗长地重写 parseResponse。现在只需一个属性。

将 content 设为非 JSON 的值会在类型层面强制要求 schema: undefined，因为二进制数据无法被规范化。如果不小心使用了可规范化的 schema，运行时检查会给出清晰的错误信息。

可与 extend() 和子类配合使用：

// Extend a JSON endpoint into a blob downloader
const download = jsonEndpoint.extend({
  content: 'blob',
  schema: undefined,
});

// Subclass for a reusable blob endpoint type
class BlobEndpoint<O extends RestGenerics = any> extends RestEndpoint<O> {
  content = 'blob' as const;
}

#3868 - content 文档

resource() nonFilterArgumentKeys​

nonFilterArgumentKeys 让 resource() 可以声明哪些参数键不用于过滤集合结果——通常是排序、分页或显示选项。没有它的话，每一组不同的排序或分页参数都会创建一个独立的 Collection 分桶，新创建的条目也不会出现在使用了不同排序参数的列表中，即便底层数据本应匹配。

import { Entity, resource } from '@data-client/rest';

class Post extends Entity {
  id = '';
  title = '';
  group = '';
  author = '';
}

const PostResource = resource({
  path: '/:group/posts/:id',
  searchParams: {} as { orderBy?: string; author?: string },
  schema: Post,
  nonFilterArgumentKeys: ['orderBy'],
});

现在 group 和 author 是过滤键（它们划分出各自独立的 Collection），而 orderBy 是共享的——PostResource.getList.push() 会把新帖子添加到给定 { group, author } 分桶的所有 orderBy 变体中。

接受 string[]、RegExp 或谓词函数：

nonFilterArgumentKeys: /^(orderBy|page|cursor)$/,

#3914 - nonFilterArgumentKeys 文档

二进制 Content-Type 自动检测​

当未设置 content 时，parseResponse 现在会自动检测二进制 Content-Type 并返回 response.blob()，而不是通过 .text() 损坏数据。

诸如 image/*、audio/*、video/*、font/*、application/octet-stream、application/pdf 等二进制类型现在都会自动处理。类文本类型（text/*、XML、HTML、JavaScript、CSS 等）继续使用原有的文本 fallback，并附带感知 schema 的错误信息。

这意味着带有正确 Content-Type 头并提供二进制数据的 endpoint 无需任何配置即可工作：

const ep = new RestEndpoint({
  path: '/avatars/:id',
});
// Server responds with Content-Type: image/png
// → automatically returns a Blob (previously corrupted via .text())

#3868

迁移指南​

本次升级需要同时更新所有包的版本。

npm install --save @data-client/react@^0.18.0 @data-client/rest@^0.18.0 @data-client/endpoint@^0.18.0 @data-client/core@^0.18.0 @data-client/vue@^0.18.0 @data-client/test@^0.18.0 @data-client/img@^0.18.0

yarn add @data-client/react@^0.18.0 @data-client/rest@^0.18.0 @data-client/endpoint@^0.18.0 @data-client/core@^0.18.0 @data-client/vue@^0.18.0 @data-client/test@^0.18.0 @data-client/img@^0.18.0

pnpm add @data-client/react@^0.18.0 @data-client/rest@^0.18.0 @data-client/endpoint@^0.18.0 @data-client/core@^0.18.0 @data-client/vue@^0.18.0 @data-client/test@^0.18.0 @data-client/img@^0.18.0

<script type="importmap">
{
  "imports": {
    "@data-client/react": "https://esm.sh/@data-client/react@^0.18.0",
    "@data-client/rest": "https://esm.sh/@data-client/rest@^0.18.0",
    "@data-client/endpoint": "https://esm.sh/@data-client/endpoint@^0.18.0",
    "@data-client/core": "https://esm.sh/@data-client/core@^0.18.0",
    "@data-client/vue": "https://esm.sh/@data-client/vue@^0.18.0",
    "@data-client/test": "https://esm.sh/@data-client/test@^0.18.0",
    "@data-client/img": "https://esm.sh/@data-client/img@^0.18.0"
  }
}
</script>

本次发布中的破坏性变更仅影响自定义 Schema 实现。如果你只使用 resource() 和内置 schema（Entity、 Collection、Union、Values、 Array、Object、Query、 Invalidate、Lazy、Scalar），升级可以直接替换完成。

**有自定义 Schema？**如果你使用 AI 智能体，安装迁移 skill 并让它驱动整个流程——codemod、argsKey 注册以及手动清理：

npx skills add reactive/data-client --skill data-client-v0.18-migration

npx openskills install reactive/data-client/.agents/skills/data-client-v0.18-migration

没有智能体的话，先运行 codemod，再阅读下面各节了解它无法处理的情况（尤其是依赖参数的 schema 所需的 argsKey）：

npx jscodeshift -t https://dataclient.io/codemods/v0.18.js --extensions=ts,tsx,js,jsx src/

Schema.denormalize() 接收 delegate​

如果你没有实现自定义 Schema 类，可以跳过本节。

Schema.denormalize() 现在的签名是 (input, delegate)，取代了以前的 3 参数签名 (input, args, unvisit)。新的 IDenormalizeDelegate 暴露了 unvisit、args 以及新的 argsKey(fn) 辅助方法。 #3887

import { Entity } from '@data-client/rest';

class Wrapper {
  denormalize(
    input: {},
    args: readonly any[],
    unvisit: (s: any, v: any) => any,
  ) {
    const value = unvisit(this.schema, input);
    return this.process(value, ...args);
  }
}

import { Entity, type IDenormalizeDelegate } from '@data-client/rest';

class Wrapper {
  denormalize(input: {}, delegate: IDenormalizeDelegate) {
    const value = delegate.unvisit(this.schema, input);
    return this.process(value, ...delegate.args);
  }
}

codemod 能处理类方法、对象方法、函数声明、TypeScript 接口签名，以及透传式的 someSchema.denormalize(input, args, unvisit) 调用。它还会把 IDenormalizeDelegate 以内联 type 说明符的形式添加到你现有的 @data-client/* 导入中（找不到时则新建一行 import type）。

依赖参数的输出​

直接读取 delegate.args 不会参与记忆化。如果你的 schema 的输出依赖这些参数（例如一个视角），请通过 delegate.argsKey(fn) 声明这一依赖，以便缓存正确分桶。

class LensSchema {
  denormalize(input, args, unvisit) {
    const lens = args[0]?.portfolio;
    return this.lookup(input, lens);
  }
}

class LensSchema {
  constructor({ lens }) {
    this.lensSelector = lens;  // ①
  }
  denormalize(input, delegate) {
    const lens = delegate.argsKey(this.lensSelector);  // ②
    return this.lookup(input, lens);
  }
}

完整示例请参阅 Scalar。

Schema.normalize() 接收 delegate​

如果你没有实现自定义 Schema 类，可以跳过本节。

Schema.normalize() 现在从 INormalizeDelegate 读取 endpoint 参数和递归访问器，与新的 denormalize delegate 的形式保持一致。以前的签名是 (input, parent, key, args, visit, delegate, parentEntity?)；新的签名是 (input, parent, key, delegate, parentEntity?)。 #3934

import type { INormalizeDelegate, Visit } from '@data-client/rest';

class Wrapper {
  normalize(
    input: any,
    parent: any,
    key: string,
    args: readonly any[],
    visit: Visit,
    delegate: INormalizeDelegate,
  ) {
    const normalized = visit(this.schema, input.value, input, 'value', args);
    delegate.mergeEntity(this, this.pk(input, parent, key, args), normalized);
    return normalized;
  }
}

import type { INormalizeDelegate } from '@data-client/rest';

class Wrapper {
  normalize(
    input: any,
    parent: any,
    key: string,
    delegate: INormalizeDelegate,
  ) {
    const { args, visit } = delegate;
    const normalized = visit(this.schema, input.value, input, 'value');
    delegate.mergeEntity(this, this.pk(input, parent, key, args), normalized);
    return normalized;
  }
}

如果你的 schema 接受可选的 parentEntity 参数，请把它保留为最后一个参数：

normalize(input, parent, key, delegate, parentEntity) {
  // ...
}

delegate.visit() 在递归规范化时已经携带了同样的参数，因此嵌套的 schema 不需要显式传入参数。

新增：normalize 的 parentEntity​

normalize delegate 的 visit() 回调会在内部跟踪最近的外层类实体 schema，并将其作为可选的末尾参数 parentEntity 转发给 Schema.normalize()。新的 schema 可以选择利用它，在规范化时发现自己所属的实体（Scalar 在内部就是这样使用的）。

可选：合并 Collection 定义​

Collection 现在可以在同一个实例上同时使用 argsKey 和 nestKey。作为一项可选的清理，你可以把成对的顶层和嵌套 Collection 替换为一个共享定义：

export const getTodos = new RestEndpoint({
  path: '/todos',
  searchParams: {} as { userId?: string },
  schema: new Collection([Todo]),
});

class User extends Entity {
  static schema = {
    todos: new Collection([Todo], {
      nestKey: parent => ({ userId: parent.id }),
    }),
  };
}

export const userTodos = new Collection([Todo], {
  //argsKey: params => ({ ...params }), - this is default, so it's not needed
  nestKey: parent => ({ userId: parent.id }),
});

export const getTodos = new RestEndpoint({
  path: '/todos',
  searchParams: {} as { userId?: string },
  schema: userTodos,
});

class User extends Entity {
  static schema = {
    todos: userTodos,
  };
}

升级支持​

一如既往，如果你遇到任何问题或有任何疑问，欢迎加入我们的 或提交 bug

• 使用 useFetch() 并行加载数据——通过 use(useFetch()) 并发获取多个 endpoint，避免串行瀑布流
• Collection.move——用一次操作在多个 Collection 之间移动实体
• Collection.moveWith()——自定义移动行为（例如前置插入而非追加）
• Lazy——延迟关系的反规范化，以提升性能并隔离记忆化

其他改进：

• 直接导入 schema——无需 schema 命名空间即可直接导入 schema 类
• 反规范化深度限制——防止大型双向实体图导致栈溢出；可通过 Entity.maxEntityDepth 配置（#3822）
• DevToolsManager 在开发模式下暴露 globalThis.__DC_CONTROLLERS__，便于从 Chrome DevTools MCP 和 Expo MCP 以编程方式访问 store。使用 data-client-react skill 来启用 AI 辅助调试。
• 移除 Next.js SSR 期间具有误导性的 'Uncaught Suspense' 警告
• 修复 RestEndpoint 中 method: 'POST' 导致 sideEffect: false 类型丢失的问题
• renderDataHook() 在每个测试之后自动清理——无需手动调用 cleanup()
• renderDataHook() 返回每次渲染的 cleanup() 和 allSettled()，让测试的收尾更可靠

Collection.move 让你能够用一次操作轻松地在多个 Collection 之间移动实体：

import { useController } from '@data-client/react';
import { TaskResource, type Task } from './TaskResource';

export default function TaskCard({ task }: { task: Task }) {
  const handleMove = () => ctrl.fetch(
    TaskResource.getList.move,
    { id: task.id },
    { id: task.id, status: task.status === 'backlog' ? 'in-progress' : 'backlog' },
  );
  const ctrl = useController();
  return (
    <div className="listItem">
      <span style={{ flex: 1 }}>{task.title}</span>
      <button onClick={handleMove}>
        {task.status === 'backlog' ? '\u25bc' : '\u25b2'}
      </button>
    </div>
  );
}

破坏性变更：

• path-to-regexp v8——RestEndpoint.path 语法更新：/:optional? → {/:optional}，/:repeat+ → /*repeat（类型为 string[]）
• useFetch() 返回 UsablePromise——返回可供 React.use() 使用的 thenable；请检查 .resolved 而不是真值性

使用自动化 codemod 升级，它涵盖所有破坏性变更：

npx jscodeshift -t https://dataclient.io/codemods/v0.16.js --extensions=ts,tsx,js,jsx src/

Collection.move​

Collection.move 和 RestEndpoint.move 让你能够用一次 PATCH 请求轻松地在多个 collection 之间移动实体。实体会自动从与其旧状态匹配的 collection 中移除，并添加到与请求体中新值匹配的 collection 中。

这对看板、分组重新分配、状态变更，或任何条目需要在筛选列表之间移动的工作流都很有用。

const TaskResource = resource({
  path: '/tasks/:id',
  searchParams: {} as { status: string },
  schema: Task,
});

// PATCH /tasks/3 - moves task from 'backlog' to 'in-progress'
await ctrl.fetch(
  TaskResource.getList.move,
  { id: '3' },
  { id: '3', status: 'in-progress' },
);