tanstack-store

TanStack Store

当工作涉及 TanStack Store 时使用此技能，尤其是 @tanstack/react-store、与框架无关的 store、原子、派生状态，或从较早的 useStore 示例迁移时。

工作流

1. 修改代码前，检查本地状态结构：
   • @tanstack/store、@tanstack/react-store、框架适配器、React 和测试工具的包版本。
   • Store 生命周期：模块级单例、由上下文提供的组合对象、组件生命周期内的 store、请求作用域的 SSR 状态，或本地原子。
   • 使用中的读写 API：useSelector、已弃用的 useStore、_useStore、useAtom、setState、操作工厂、订阅或原子。
   • 更新预期：不可变对象更新、派生计算、批处理、持久化副作用，以及选择器触发重新渲染的行为。
2. 当行为或版本很重要时，刷新并查阅当前文档和包相关资料。从 source-map.md 开始。
3. 对于安装、包名、核心 createStore、Store、操作、订阅、不可变更新和批处理，使用 setup-core.md。
4. 对于 React 用法、useSelector、选择器 compare、useAtom、useCreateStore、useCreateAtom、上下文以及 useStore 迁移，使用 react-patterns.md。
5. 对于原子、异步原子、派生 store、先前值、相等性、shallow 和响应式图行为，使用 atoms-derived-batching.md。
6. 对于 SSR、测试、生命周期、持久化、框架适配器、不使用 devtools 进行调试以及生产环境检查，使用 production-testing.md。

实现判断

• 在 React 中优先使用 useSelector。将 useStore 视为已弃用的别名，将 _useStore 视为过渡方案，除非代码库有意采用它们。
• 保持 store 更新不可变。setState 会用更新函数的返回值替换 store 值，因此更新对象时应使用展开语法或构造完整的新状态。
• 使用精简的选择器进行 React 渲染。选择整个 store 会让组件与每次状态变化耦合。
• 仅当选择器返回组合值且会因此频繁变化时，才添加 compare 或 shallow；优先选择稳定的基本类型值。
• 当多次 store 或原子更新应只通知订阅者一次，并提供最终状态时，使用 batch。
• 当 store 管理领域操作时，使用操作工厂；避免 UI 组件手动重复编写更新逻辑。
• 在 SSR 中，除非状态确实是全局且公开的，否则避免使用模块作用域的用户／会话 store。对于每个用户的数据，应创建请求作用域或组件作用域的 store。
• 使用 subscribe 处理持久化或日志记录等副作用，并始终保留 unsubscribe 清理逻辑。自 0.11.2 起，订阅者内部对其他 store 的读取不会被跟踪；对于所有应触发该副作用的来源，都要分别订阅。
• 依赖适配器细节前，请查阅当前文档。Store 仍处于 alpha/v0 阶段，适配器 API 也仍在演进。

验证

优先使用仓库现有的检查。对有实质影响的 TanStack Store 改动，应包含相关的检查子集：

• 类型检查，覆盖 store 状态、操作工厂、选择器、原子值和上下文组合对象。
• 单元测试，覆盖 setState、操作方法、派生 store、原子、异步原子、批处理和订阅清理。
• 组件测试，覆盖选择器重新渲染边界、compare、useAtom setter、上下文错误以及已弃用 API 的迁移。
• 如果改动涉及 store 生命周期、模块作用域、上下文提供器或服务器创建的初始状态，则进行 SSR／请求测试。
• 对依赖派生状态、乐观本地状态、持久化或跨组件订阅的 UI 流程进行浏览器冒烟测试。