10 篇博文 含有标签「版本发布」

v0.19 makes coding agents a first-class way to build with Data Client: one prompt sets up your app, and your agent follows skills that ship with the packages you installed. It also lets a Manager write a whole batch of streamed rows in one store update, type-checks endpoint code about 2x faster, and fixes a round of TypeScript and Vue issues.

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

v0.18 聚焦于三件事：对随请求上下文变化的值进行更丰富的数据建模、更简单的类型化下载，以及更贴近真实 API 过滤条件的集合匹配。

新特性：

• 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/

新特性：

• 使用 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/

新平台：

• Vue 3，提供完整的组合式函数：useSuspense、useCache、useDLE、useController、useQuery

新特性：

• Collection.remove，用于从集合中移除条目
• RestEndpoint.remove，将 PATCH 与集合移除合二为一
• Union 无需类型判别字段即可 query()
• Invalidate 支持 Union，用于多态删除操作
• mockInitialState()，让测试搭建更简单

性能：

• get/denormalize 操作提升 10-20%

破坏性变更：

• useDebounce() 返回 [val, isPending]
• ImmutableJS 支持移至 /imm 导出
• Schema delegate 接口整合

使用自动化 codemod 完成常见破坏性变更的升级：

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

Manager：

Manager API 得到了精简——更扁平的 action 结构降低了代码复杂度，并通过减少不同的内联缓存条目来提升性能；同时更简单的配置 API 让自定义更加愉快。

• 简化的 action 结构
• Manager.middleware 属性
• getDefaultManagers() 配置

性能：

• 立即发起 fetch 调用——不再等待空闲
• 通过移除不必要的 polyfill，包体积缩小 30%
• 规范化快 10%，反规范化快 32%

Schema/数据建模：

• 使用 Object Schema 进行 Query 连接
• 用于组合 Entity 行为的 EntityMixin
• Entity.pk() 默认值使用 id
• 通过 Entity.process() 实现动态失效

测试：

• renderDataHook() 让测试更简单

垃圾回收：

• GCPolicy——自动回收过时数据

破坏性变更：

• NetworkManager 立即发起获取
• action.payload -> action.response
• action.meta.args -> action.args

平台：

• NextJS App Router
• Expo
• React 19

测试：

• MockResolver 已标记为 'client' 代码，以适配 NextJS App Router
• 导出 renderDataHook() - 兼容 React 17 和 18

以下包已并入 @data-client/react：

• Redux
• Hooks

其他改进

• 新增 controller.set(Todo, { id }, { id, completed: false })
• RestEndpoint.path 支持 +、* 和 {}
• 修复 Union 在 controller.fetch() 中的返回值

破坏性变更：

• actionTypes.SET_TYPE -> actionTypes.SET_RESPONSE_TYPE
• SetAction -> SetResponseAction
• 最低 React 版本 16.8.4 -> 16.14

除了规范化状态带来的性能和数据完整性收益之外，我们还获得了一项额外的好处：能够安全地直接访问并查询 store。

在本次发布中，我们围绕 Queryable Schema 的概念统一并简化了这一功能。它们包括 Entity、All、Collection、Query 和 Union

这一变化最大的影响是引入了新的 hook useQuery()，它允许使用 Queryable Schema 直接查找 store。

class User extends Entity {
  username = '';
  id = '';
  groupId = '';
  pk() {
    return this.id;
  }
  static index = ['username' as const];
}

const bob = useQuery(User, { username: 'bob' });
const bob = useQuery(User, { id: '5' });

同样地，我们可以通过 controller.get 在 controller 和 snapshot 中查找 Queryable

const bob = snapshot.get(User, { username: 'bob' });

此外，我们还投入了更多的性能改进，使大多数操作的性能提升了约 2 倍，而 Query 则快了 16 倍。

破坏性变更：

• useCache(new Index(MyEntity)) -> useQuery(MyEntity)
• new Query -> new schema.Query
  • useCache(myQuery) -> useQuery(myQuery)
• new AbortOptimistic() -> snapshot.abort
• Entity.useIncoming → Entity.shouldUpdate

其他亮点：

• useCache() 接受带有 sideEffects 的 Endpoint（例如 Resource.update）
• 允许 Entity.pk() 返回数字。
• 2 到 16 倍的性能改进

本次发布聚焦于一致性和可扩展性。null 处理现在在所有 schema 类型中保持统一，使数据转换更可预测。新的 URL 工具函数支持自定义 URL 构造和搜索参数编码。

class MyEndpoint<O extends RestGenerics = any> extends RestEndpoint<O> {
  searchToString(searchParams) {
    // Use qs library for complex nested object encoding
    return qs.stringify(searchParams);
  }
}

破坏性变更：

• Array/Object schema 中保留 null 值

其他改进：

• RestEndpoint.searchToString() 用于自定义搜索参数编码
• 导出 getUrlBase、getUrlTokens 用于自定义 URL 构造
• 修复 DevToolsManager 内存泄漏

本次发布聚焦于开发者体验：在开发模式下显示的 devtools 按钮、更好的 DevTools 历史记录，以及 controller.expireAll() 和 controller.fetchIfStale() 等新的 controller 方法。

Resource.extend() 提供了三种强大的方式来自定义 resource——添加新的 endpoint、覆盖已有的 endpoint，或从基础 endpoint 派生。

const UserResource = createResource({
  path: '/users/:id',
  schema: User,
}).extend('current', {
  path: '/users/current',
});

破坏性变更：

• 移除所有 /next 导出
• 移除 makeCacheProvider
• DELETE -> INVALIDATE action 类型
• 不再支持遗留 schema
• Schema 序列化器必须支持函数调用
• Action 类型加上 'rdc' 前缀

Collection 让数组和对象可以通过 push 或 unshift 新成员来轻松扩展。它的名字来自 Backbone Collections。

Collection 现在是 Resource.getList 的默认 schema。

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

export default function CreateTodo({ userId }: { userId: number }) {
  const ctrl = useController();
  const handleKeyDown = async e => {
    if (e.key === 'Enter') {
      ctrl.fetch(TodoResource.getList.push, {
        userId,
        title: e.currentTarget.value,
        id: Math.random(),
      });
      e.currentTarget.value = '';
    }
  };
  return (
    <div className="listItem nogap">
      <label>
        <input type="checkbox" name="new" checked={false} disabled />
        <input type="text" onKeyDown={handleKeyDown} />
      </label>
    </div>
  );
}

升级相当简单，因为我们引入了 @data-client/rest/next 和 @data-client/react/next，以便渐进式地采用本版本中变更的新 API。这使得实际的升级只是简单地重命名一下导入路径。

其他亮点包括

• @data-client/rest
  • 异步 RestEndpoint.getHeaders
• @data-client/react
  • Controller.fetch() 的返回值按 schema 反规范化
  • Manager action 类型更新

完整细节请继续阅读：