新增：

• Claude Code 插件 - claude plugin install react@data-client 安装适用于你所用框架的 skill
• Vue skill - Vue 项目得到的是 Vue 组合式函数和测试，而不是 React hook
• llms.txt - 任何智能体都可以把文档作为 markdown 读取，而且每个页面都会告诉它该去哪里找

同样可用：

• Agent Skills - 定义 REST API、设计 schema、编写 Manager 以及测试；/data-client-setup 现在只安装你需要的那些，并且它们由这些文档生成
• Chrome DevTools MCP - 智能体可以检查正在运行的应用的 store，React Native 则使用 Expo MCP
• 升级 skill - 迁移 skill 会升级你的代码，包括 codemod 做不到的部分

快速上手​

安装 /data-client-setup skill 并运行它。它会检测 React 或 Vue 以及你的 API 风格（REST、GraphQL 或自定义），安装你的项目所需的 skill，并配置好 Data Client。对于 REST，它会交给 data-client-rest-setup，由后者把现有的 fetch 或 axios 调用迁移到 endpoint（#4153）。

npx skills add reactive/data-client --skill data-client-setup

npx openskills install reactive/data-client/.agents/skills/data-client-setup

claude plugin marketplace add reactive/data-client
claude plugin install core@data-client

Agent Skills 列出了每个 skill，以及如何预先一次安装全部 skill。

Claude Code 插件​

Data Client 仓库是一个 Claude Code 插件市场。core 插件包含 setup、REST、GraphQL、schema 和 Manager skill；react 和 vue 插件添加各自框架的 skill 并引入 core；migrations 插件添加升级 skill（#4153）。 Agent Skills 页面展示了用 skills CLI 和 OpenSkills 完成同样安装的方法。

claude plugin marketplace add reactive/data-client
claude plugin install react@data-client

Vue 请使用 vue@data-client，两者都不用则使用 core@data-client，并在升级前添加 migrations@data-client。

Vue skill​

Vue 项目之前得到的是 React hook 的 skill，因此智能体会套用 React 的模式。 data-client-vue skill 编写 DataClientPlugin 和组合式函数代码，并能调试正在运行的应用（#4126）。 data-client-vue-testing 编写 renderDataCompose() 和 mountDataClient() 测试（#4126），这些测试遵循 Vue 测试指南（#4181）。

llms.txt​

没有 skill 的智能体可以按照 llms.txt 约定把文档作为 markdown 读取（#4171、#4236）：

• React 的 llms.txt 和 Vue 的 vue/llms.txt 索引了每个页面，旁边的 llms-full.txt 则把它们全部收在一个文件里
• rest/llms.txt 和 graphql/llms.txt 只覆盖对应包的 API
• 任何文档页面在 URL 后加上 .md 就是 markdown，比如 /docs/api/useSuspense.md

每个页面都在 <head> 中链接了它的 llms.txt，每个文档页面都链接了它的 markdown，因此拿到任意页面 URL 的智能体都能自行找到它们。

skill 与文档保持一致​

skill 的参考页面现在按框架从这些文档生成，因此它们带有安装命令等共享片段，并且只给 Vue 项目提供 Vue 代码。当 skill 与文档出现偏差时，CI 检查会失败，因此 skill 会随每次发布保持最新（#4170）。

同样可用​

针对每项任务的 skill​

除了 setup 之外，Data Client 应用的每个部分都有对应的 skill。/data-client-setup 会安装你的项目用到的那些：

• data-client-rest-setup 把 fetch、axios、ky、got 或 superagent 客户端迁移到 RestEndpoint，配合 axios 迁移指南及其 codemod（#3867）
• data-client-graphql-setup 和 data-client-endpoint-setup 覆盖 GraphQL 和自定义异步函数
• data-client-rest 用 resource() 和 RestEndpoint 定义 API
• data-client-schema 设计 Entity、Collection、Union 和 Query schema
• data-client-manager 为 websocket、SSE、轮询和日志编写 Manager
• data-client-react 和 data-client-react-testing 使用并测试 React hook

在 skills.sh/reactive/data-client 浏览全部 skill。

调试正在运行的应用​

问你的智能体"为什么这里没有重新获取？"或"缓存里现在有什么？"，它可以直接检查正在运行的应用，而不是从代码里猜。在开发模式下，DevToolsManager 把每个 store 的 Controller 放在 globalThis.__DC_CONTROLLERS__ 上，因此通过 Chrome DevTools MCP，或在 React Native 中通过 Expo MCP 连接的智能体，可以读取 store、跟踪派发的 action，并把它们与网络请求对应起来。这个映射在浏览器、React Native 和 Node 中都存在（#3753）。

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

React 和 Vue 的 skill 通过 Chrome DevTools MCP 驱动这一流程；它们能检查哪些内容请参阅使用智能体调试。

升级 skill​

skill 也负责升级。v0.18 skill 会运行 codemod，然后处理 codemod 做不到的部分，比如为输出依赖 endpoint 参数的 schema 注册 argsKey （v0.18 迁移）。path-to-regexp v8 skill 会重写你 endpoint 中的路径语法。

npx skills add reactive/data-client \
  --skill data-client-v0.18-migration \
  --skill path-to-regexp-v8-migration

npx openskills install reactive/data-client/.agents/skills/data-client-v0.18-migration
npx openskills install reactive/data-client/.agents/skills/path-to-regexp-v8-migration

claude plugin marketplace add reactive/data-client
claude plugin install migrations@data-client

v0.19 让 Manager 可以在一次 store 更新中写入一整批流式到达的行，把 endpoint 代码的类型检查速度提高约 2 倍，并修复了一批 TypeScript 和 Vue 问题。编码智能体还获得了 Claude Code 插件、Vue skill 和 llms.txt；请参阅面向编码智能体的 Data Client。

新 API：

• 支持 Array schema 的 Controller.set() - 用 ctrl.set([Entity], rows) 在一次 store 更新中写入多个 entity，比每行调用一次 set() 最多快 95 倍

性能：

• 更快的 TypeScript - 编辑器和 tsc 检查 RestEndpoint 与 resource() 代码的速度提高约 2 倍，内存减少 40%，并且之前能捕获的错误一个都不少

其他改进：

• 修复 TypeScript 7 对包 exports 的模块解析；导入现在会解析到声明文件（#4019）
• renderDataHook() 在首次渲染挂起时也会运行 provider 的挂载副作用（#4099）
• Controller.set() 的值按 schema 推导类型，因此 ctrl.set(new schema.All(Todo), 42) 会是 TypeScript 错误（#4133）
• Controller.set() 可用 Invalidate schema 删除单个 entity，不再需要包成单行批量的变通写法（#4230）
• 在 new RestEndpoint()、.extend() 和 resource().extend() 中，process() 获得带类型的 params，因此写错路径参数会是 TypeScript 错误，而不是运行时的 undefined（#4183、#4184）
• getOptimisticResponse() 的返回值按 schema 推导类型，因此字段类型写错会是 TypeScript 错误，而不是闪现一下错误数据（#4198）
• Vue 的 useSuspense() 和 useLive() 在新参数加载期间保留之前的数据，而不是返回 undefined（#4131）
• Vue 的 useSuspense() 和 useLive() 把参数变化后的获取错误发送给 onErrorCaptured()，而不是产生未处理的 promise rejection（#4135）
• Vue 的 useSuspense()、useDLE() 和 useFetch() 不再在每次 store 更新时重新获取过时数据，因此 controller.set() 不会被覆盖（#4134）
• Vue 的 useSuspense() 在挂载时显示过时数据并在后台重新获取，与 React 一致，而不是在重新获取完成前一直显示 <Suspense> 的 fallback（#4169）
• Vue 的 useDLE() 和 useCache() 在无关的 store 更新中保留已过期的 invalidIfStale 数据，而不是卡在加载状态（#4142）
• Vue 的 DataClientPlugin 可以安装在 3.5 之前的 Vue 版本上，而不是抛出 app.onUnmount is not a function（#4146）
• Vue 的 DataClientPlugin 默认进行垃圾回收，与 React 的 DataProvider 一致，因此你不再需要传入 gcPolicy；它如何决定移除什么（#4148）
• Vue 组合式函数接受像 () => ({ id: props.id }) 这样的 getter 参数；之前类型上允许，但却把函数本身传给了 endpoint（#4115）
• 修复在关闭 skipLibCheck 的 TypeScript 4.x 上出现的 Cannot find name 'NoInfer' 和 export type 错误（#4138）
• 修复在关闭 skipLibCheck 的 TypeScript 4.0–4.5 上 Entity、Endpoint、Union 和 RestEndpoint 的类型错误（#4140）
• 修复在 TypeScript 4.0–4.4 上导入 @data-client/react/redux、@data-client/react/nextjs 或 @data-client/test 时的 ',' expected 错误（#4232）
• 修复在 TypeScript 4.0–4.4 上 @data-client/test 的 act 和 renderHook 被推导为 any 的问题（#4251）
• Entity 类可以用在期望 EntityInterface 的地方（#4149）；为未来版本准备好 pk() 重写
• useCache() 和 useDLE() 对已删除且重新获取失败的 entity 返回 undefined，而不是一个能绕过 if (!data) 检查的真值 Symbol；移除所有变通代码（#4150）
• Vue 的 useFetch() 在挂载期间保护其数据不被垃圾回收，与 useSuspense() 一致，因此配置的 gcPolicy 不再会清除组件稍后要读取的预取数据（#4152）
• 打开 Redux DevTools 的应用在开发模式下遇到大型 store 或频繁更新时不再卡顿；每次更新的序列化快 40-60 倍（#4163）
• 传入 endpoint 覆盖对象的 resource().extend() 会在类型中保留之前用 .extend('name', options) 添加的 endpoint，因此使用它们不再是 TypeScript 错误（#4184）
• 当 Query 或 Lazy 包装 Collection 时，RestEndpoint.push、unshift 和 remove 接受 Entity 的字段作为 body，而不是只接受 FormData（#4226）
• Vue 的 useFetch() 的类型现在是它返回的只读 Ref，因此 promise.resolved（始终为 undefined）现在是 TypeScript 错误；请改为读取 promise.value.resolved（#4114）
• 传给 DataProvider 或 DataClientPlugin 的 Controller 子类不再需要类型断言就能通过类型检查（#4228）
• prepareStore() 的 store 可以不加类型断言直接传给 react-redux 的 <Provider>，并且其类型中包含 dispatch()（#4238）
• resource().create 接受 FormData，无需类型断言，与 update、partialUpdate 和 getList.push 一致（#4235）
• RestEndpoint.push、unshift 和 remove 以 JSON 形式发送数组 body，因此一次创建或移除多个条目不再向服务器发送 "[object Object]"；resource().create 也接受数组（#4262）
• Vue 的 createDataClient() 已弃用，因为它是 DataClientPlugin 的内部实现；请用 app.use(DataClientPlugin, options) 安装插件，而不是直接调用它（#4193）
• Vue 的 renderDataCompose() 的 waitForNextUpdate() 已弃用，因为它会在 1 秒后静默放弃，让仍处于挂起状态的测试通过；请改为 await result，或在变化之后 await allSettled()，后者现在也会等待由 prop 变化触发的获取（组合式函数的单元测试、#4221）

破坏性变更：

• 需要 TypeScript 4.0 或更高版本 - 移除了 TypeScript 3.x 的声明文件（#4151）

为未来版本做好准备：

• 在 Entity.pk() 重写中把 args 标注为 readonly
• 用 DataClientPlugin 代替 Vue 的 createDataClient()
• 替换 Vue 测试中的 waitForNextUpdate()

批量 Controller.set()​

接收一连串行数据（比如通过 websocket 传来的价格行情）的 Manager，现在可以通过传入 Array schema，用一次 Controller.set() 把它们全部写入。在 v0.19 之前，[Ticker] 会是 TypeScript 错误，所以常见的变通做法是每行调用一次 set()：

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);
};

每一行都会与已存储的 entity 合并，列表中没有的 entity 则保持不变。Array schema 不接受 args，也不接受更新函数。要批量处理混合的 Entity 类型、删除操作或按 id 作为键的行，请传入 Union、 Invalidate 或 Values schema；示例请参阅 Controller.set()。 #4103

试试下面的两个按钮。这个浏览器测试从空的 store 开始，分别计时 500 次 set() 调用的 Promise.all 与一次批量 set()。两种方式都只产生一次 React 提交，并且各自写入 500 个新价格。

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 />);

性能​

每次 set() 都是一次独立的 store 更新，而每次 store 更新都会复制该 entity 类型的整张表。逐行写入会为每一行重复这次复制，因此开销随批量大小和 store 大小一起增长。批量写入只需付出一次复制的代价。

下图是 examples/benchmark/core.js 中的 node setMany 基准测试：一个已持有 500 个 entity 的 store，对比每行同步调用一次 set() 与一次 set([Ticker], rows)。它测量的是 store 更新：50 行时快 20 倍，500 行时快 95 倍。 #4103

在 Manager 中，缓冲到达的消息并用一次 set() 刷出每一批，具体做法见批量处理高频更新。coin 应用的 StreamManager 现在就是这样刷出 Coinbase 的行情消息。

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]));
  }
};

更多演示

更快的 TypeScript​

TypeScript 会在编辑器里的每次按键和每次 CI 构建时重新检查你的代码。在拥有大量 endpoint 的应用中，沉重的库类型表现为迟缓的自动补全、要等几秒才出现的红色波浪线，以及更慢的构建。 v0.19 让 RestEndpoint、resource() 和 .extend() 的检查开销大幅降低，你无需改动任何代码。TypeScript 仍然会报告之前报告过的每一个错误（#4173）。

结果​

我们最重的压力测试，一个包含 150 个带长路径、.extend() 和 .paginated() 的 RestEndpoint 的文件，现在在 TypeScript 6 上检查快 2 倍，在 TypeScript 7 上快 2.2 倍，内存用量减少约 40%。所有数字都是已发布的 v0.18.1 包与 v0.19 的对比；检查时间取 10 次运行中的最佳值。

endpoint 密集的代码所做的类型工作少了很多。类型实例化是 TypeScript 的工作单位：它们是确定性的，因此可以在不同机器间干净地比较。Union 比 v0.18 做了更多工作，因为 v0.19 现在会对 set() 的值做类型检查（见下文）。

悬停或点击单元格可查看精确数字。

set() 各行测量的是带类型的 set() 值，v0.18 完全不检查这些值。普通值的检查仍比之前更快，而大型 Union 上的更新函数检查耗时大致相同，尽管 TypeScript 现在会检查每个更新函数的返回值（#4179）。

小文件的开销主要来自 TypeScript 固定的启动成本（仅加载 lib.dom.d.ts 就要约 100MB），所以它们的时间和内存几乎不变。随着代码库增长，节省的开销会逐渐累积。

改了什么​

• .extend() 和 .paginated() 在所有 endpoint 之间共享，而不是为每种 endpoint 类型重新创建。
• endpoint 选项被推导为普通对象类型，因此 TypeScript 不再在每次使用时重新构建它们。
• 像 /users/:id 这样的路径参数只需一遍即可读取完毕。

发布之前，我们在 TypeScript 4.0 到 7 上关闭了测试套件中的每一个 @ts-expect-error，并确认每个错误仍然出现在同一位置。

在 TypeScript 5.x 及更早版本上，传给 .extend() 的 process(value, params) 方法在 strict 下也不再报 "implicitly has an 'any' type" 错误。

其他改进​

带类型的 set() 值​

Controller.set() 之前对任何 schema 都接受任意值，所以拼写错误或字段类型写错只会在运行时表现为错误数据。现在值按 schema 推导类型： Entity 接受它的字段，而 Collection、All 或 Array 接受一个行列表。每个字段都是可选的，因为 set() 会合并到已存储的数据中；并且数字和字符串可以互换，就像在 API 响应中一样。 #4133

悬停在红色下划线上可查看每个错误。

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 }));
}

Query 接受它所包装 schema 的输入，因为 set() 规范化的是那个 schema，而不是反转 process()。当每个成员都把判别字段声明为字面量（如 readonly type = 'post'）时， Union 的行会按它所选中的成员进行检查，因此不能混用不同成员的字段；请参阅 Unions。

如果之前能编译的代码现在在这里报错，说明它写入的数据与其 schema 的描述不符。请修正该值，或者在数据确实可能是那种形状时放宽 Entity 的字段类型。

用 set() 删除单个 entity​

向 Controller.set() 传入 Invalidate schema 会删除其行所标识的 entity，但单个形式曾是 TypeScript 错误，所以代码只能把它包成单行批量。现在它可以通过类型检查，且行按 Entity 的字段推导类型（#4230）：

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

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

与批量 set() 一样，它不接受 args，也不接受更新函数。

带类型的 process() params​

传给 new RestEndpoint()、.extend() 或 resource().extend() 的 process() 方法，其 params 之前被推导为 any，因此读取 endpoint 并不具备的参数也能编译通过，并在运行时返回 undefined。params 和 body 现在从 endpoint 推导类型，包括在同一个 .extend() 调用中设置的 path （#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 };
  },
});

当每个参数都是可选的时，params 可能为 undefined，因此要用 params?.page 读取。

这可能会在现有的 process() 方法中暴露出新的 TypeScript 错误。每一个错误都标记了一处可能为 undefined 或在运行时抛出异常的读取，因此请修正参数名或补上缺失的检查。

带类型的乐观响应​

除非 endpoint 有带类型的 process()，否则 getOptimisticResponse() 可以返回任何东西，因此字段类型写错只会在服务器响应之前表现为 UI 里的错误数据。返回值现在会按 endpoint 的 schema 检查，就像带类型的 set() 值一样：Entity 接受它的任意字段，而 Collection 接受它们的列表（#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' };
  },
});

这可能会在现有的 getOptimisticResponse() 方法中暴露出新的 TypeScript 错误。每一个错误都标记了一个在服务器响应之前会以错误类型存储的值，因此请返回字段的真实类型（这里是 !todo.completed）。

排序后的 Collection 上带类型的 push()​

把 Collection 包在 Query 中进行排序或过滤，会让 push、unshift 和 remove 拒绝除 FormData 以外的所有 body，尽管它们在运行时会向列表添加数据。body 现在从 Collection 的 Entity 推导类型，因此可以去掉类型断言，而字段写错会是 TypeScript 错误。被 Lazy 包装的 Collection 也同样适用（#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 });
}

其中 getPosts 用 Query 对其 Collection 排序：

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,
  ),
});

resource().create 中的 FormData​

resource() 的 create 会原样发送 FormData body，与 update、partialUpdate 和 getList.push 一致，但它的类型只允许对象，所以提交表单需要类型断言（#4235）。去掉断言即可：

<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 已弃用；getList.push 是它的替代品，同样接受 FormData。

Vue getter 参数​

像 useSuspense() 和 useLive() 这样的 Vue 组合式函数在类型上接受 getter 函数作为参数，但它们把函数本身传给了 endpoint，而没有调用它。getter 现在与 ref 和 computed 的行为一致，并且当 getter 读取的任何内容发生变化时，组合式函数会重新获取（#4115）。如果你只是为了让参数具有响应性才用 computed() 包装，现在可以去掉它：

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,
}));

这适用于每个接受 endpoint 参数的组合式函数：useSuspense()、 useLive()、useCache()、useDLE()、 useFetch()、useQuery() 和 useSubscription()。

Vue 默认进行垃圾回收​

Vue 的 DataClientPlugin 之前只有在你自己传入 gcPolicy 时才会移除未使用的数据。它现在默认使用 new GCPolicy()，与 React 的 DataProvider 相同，因此除非你要自定义它，否则可以去掉这个选项（#4148）。

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

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

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

app.use(DataClientPlugin);

数据只有在没有任何已挂载组件读取它，_并且_自获取以来已经过了两倍新鲜期（至少两分钟）时才会被移除。清扫每五分钟检查一次。在此之前被组件再次读取的任何数据都会重新回到使用中。

在移除之后挂载的组件会把该数据视为从未获取过：useSuspense() 会重新获取它，而 useCache() 会返回 undefined。要让未使用的数据保留更久或减少清扫频率，请传入你自己的 gcPolicy。

Vue stale-while-revalidate​

当组件挂载时的数据已过时但仍然有效，Vue 的 useSuspense() 现在会立即渲染它并在后台重新获取，与 React 一致。之前，它会在重新获取完成前一直显示 <Suspense> 的 fallback（#4169）。

Entity 类可作为 EntityInterface 通过类型检查​

用 EntityInterface 标注为接受任意 Entity 的辅助函数曾经拒绝 Entity 类，因为 Entity.pk() 把它的 args 标注为可变数组。它现在是 readonly any[]，因此下面的代码可以通过类型检查（#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);

如果你重写了 static pk() 并把 args 标注为可变数组，它目前仍能编译，但未来的破坏性版本将要求 readonly；现在就更新它。

已删除的 entity 读取为 undefined​

当一个 entity 被删除且重新获取失败时，useCache() 和 useDLE() （React 和 Vue）会把一个内部 Symbol 作为数据返回。Symbol 是真值，所以常见的"尚未加载"守卫会放它通过，组件就当作自己拿到了 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>;
}

现在 data 是 undefined，与它的类型和 Controller.get() 一致。 Controller.getResponse() 和 Controller.fetchIfStale() 也同样如此，例如在自定义 Manager 中。

如果你为此做过变通处理，现在可以去掉了。普通的真值检查就足够了：

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>;
}

要在重新获取失败时显示特定内容（例如删除后的 404），请从 useDLE() 读取 error，而不是检查 data。

更快的 Redux DevTools​

打开 Redux DevTools 扩展后，开发模式下的每次 store 更新都会为扩展序列化整个 store，而其中每个时间戳都是用慢速方式格式化的。大型 store 或频繁更新，比如轮询、实时数据或大量 controller.set() 调用，会让页面卡顿。现在每次更新的序列化快 40-60 倍，而时间戳仍然显示为 10:42:07.123 AM 这样的形式（#4163）。生产构建不包含 DevTools，因此不受影响。

迁移指南​

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

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 或更高版本​

如果你已经在使用 TypeScript 4.0 或更高版本，请跳过本节。

TypeScript 3.x 的声明文件已被移除，因为它们在任何 TypeScript 3.x 版本上都已无法通过类型检查。请把 devDependencies 中的 typescript 升级到 ^4.0.0 或更高版本。#4151

为未来版本做好准备​

升级到 0.19 并不需要做这里的任何事情；你的代码可以原样继续工作。每一项都会在未来版本中失效，所以现在更新能让那次升级不费任何功夫。

Entity.pk() 的 args 是 readonly​

如果你没有用带类型的 args 参数重写 static pk()，请跳过这一项。

Entity.pk() 现在把 args 标注为 readonly any[]。把它标注为可变数组的重写目前仍能编译，但未来版本将要求 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()​

如果你用 app.use(DataClientPlugin) 安装 store，请跳过这一项。

createDataClient() 和 ProvidedDataClient 是 DataClientPlugin 的内部实现，将不再导出。请改为安装插件，并通过 useController() 读取 controller。#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()​

如果你的 Vue 测试没有调用 waitForNextUpdate()，请跳过这一项。

renderDataCompose() 的 waitForNextUpdate() 会在 1 秒后静默放弃，因此组合式函数仍处于挂起状态时测试也能通过。它将被移除。请改为 await 结果，并在修改 props 或调用 controller 之后调用 allSettled()；它现在也会等待由 prop 变化触发的获取。#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();

升级支持​

一如既往，如果你遇到任何问题或有任何疑问，欢迎加入我们的 或提交 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

claude plugin marketplace add reactive/data-client
claude plugin install migrations@data-client

否则，直接运行 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

claude plugin marketplace add reactive/data-client
claude plugin install migrations@data-client

没有智能体的话，先运行 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' },
);

同时适用于路径参数和搜索参数，并支持 Array 和 Values collection。

Collection.moveWith()​

Collection.moveWith() 用于构造自定义的移动 schema，类似于 addWith()。merge 函数控制实体如何被添加到目标 collection（例如前置插入而非追加），而移除行为则会自动推导。为方便使用，还提供了 unshift 合并函数。

import { Collection, unshift } from '@data-client/rest';

class MyCollection extends Collection {
  constructor(schema, options) {
    super(schema, options);
    this.move = this.moveWith(unshift);
  }
}

并行加载数据​

useFetch() 现在返回一个 UsablePromise thenable，使 use(useFetch(endpoint, args)) 成为 useSuspense() 的即插即用等价物—— 数据加载时挂起，已缓存时返回反规范化后的数据，出错时抛出，并在失效时重新挂起。

由于 useFetch() 和 use() 是两次独立的调用，多个获取会并行开始。所有 useFetch() 调用都会在任何 use() 挂起之前执行，因此即使第一个 use() 挂起了组件，每个获取也都已经在进行中。这避免了多次调用 useSuspense() 时出现的串行瀑布流，即第二个获取必须等第一个完成后才能开始。 #3755

import { use } from 'react';
import { useFetch } from '@data-client/react';
import { PostResource, CommentResource } from './Resources';

function PostWithComments({ id }: { id: number }) {
  // Both fetches start in parallel
  const postPromise = useFetch(PostResource.get, { id });
  const commentsPromise = useFetch(CommentResource.getList, { postId: id });

  // use() reads the results — if the first suspends,
  // the second fetch is already in-flight
  const post = use(postPromise);
  const comments = use(commentsPromise);

  return (
    <article>
      <h3>{post.title}</h3>
      <p>{post.body}</p>
      <h4>Comments</h4>
      {comments.map(comment => (
        <div key={comment.id} className="listItem">
          <strong>{comment.author}</strong>: {comment.text}
        </div>
      ))}
    </article>
  );
}
render(<PostWithComments id={1} />);

反规范化深度限制与 Lazy​

当 schema 在不同实体类型之间存在双向关系时（例如 Department → Building → Department → ...），反规范化会遍历连通图中的每一个唯一实体。数据集较小时这并不明显，但在大规模下——成千上万个相互关联的实体——递归会超出 JS 调用栈并抛出 RangeError: Maximum call stack size exceeded。 #3822

两个互补的特性解决了这个问题：作为安全网的深度限制，以及 Lazy，用于按字段精确控制哪些关系被急切解析。

反规范化深度限制​

反规范化现在默认强制执行 64 层实体跳转的深度限制。超出限制的实体会以未解析的 id 返回，而不是完全反规范化后的对象。在开发模式下达到该限制时会输出一条 console.error。

可以通过 static maxEntityDepth 为每个 Entity 单独配置该限制：

class Department extends Entity {
  static maxEntityDepth = 16;
}