valtio store
npm install @empjs/valtioValtio 的增强版状态库 —— 更少样板代码,更高生产力。基于 Valtio 的细粒度响应式机制,提供开箱即用的高级功能:历史回溯、自动派生、持久化、嵌套更新、克隆、重置等。
``bash`
pnpm add @empjs/valtionpm install @empjs/valtio
yarn add @empjs/valtio
bun add @empjs/valtio
依赖:React 18+(作为 peerDependency)。
`tsx
import { createStore } from '@empjs/valtio'
const store = createStore({ count: 0, name: '' })
function Counter() {
const snap = store.useSnapshot()
return (
无需手动
proxy + useSnapshot,store 自带 set、update、reset、persist 等方法。$3
适合表单、编辑器等组件内状态,每个组件实例拥有独立 store:
`tsx
import { useStore } from '@empjs/valtio'function Form() {
const [snap, store] = useStore({ name: '', age: 0 })
return (
)
}
`$3
- 不做限制:传
{ history: {} } 或不传 limit,历史节点不裁剪,可撤销步数无上限。
- 做限制:传 { history: { limit: 50 } } 表示最多保留 50 步可撤销;超出后由本库自动丢弃最旧节点(valtio-history 原生不支持 limit)。全局:
`tsx
// 不限制步数
const store = createStore({ text: '' }, { history: {} })// 或限制最多 50 步
const store = createStore({ text: '' }, { history: { limit: 50 } })
// store.useSnapshot() 返回 { value, history, undo, redo, isUndoEnabled, isRedoEnabled }
`局部:
`tsx
// 不限制步数
const [snap, store] = useStore(initialState, { history: {} })// 或限制最多 50 步
const [snap, store] = useStore(initialState, { history: { limit: 50 } })
// snap 上直接有 undo、redo、isUndoEnabled、isRedoEnabled
`$3
全局:
`tsx
const { base, derived } = createStore(
{ firstName: '', lastName: '' },
{
derive: (get, proxy) => ({
fullName: ${get(proxy).firstName} ${get(proxy).lastName}.trim(),
}),
}
)
// base.useSnapshot() → 原始状态;derived.useSnapshot() → { fullName }
`局部:
`tsx
const [baseSnap, baseStore, derivedSnap] = useStore(
{ a: 1, b: 2 },
{ derive: (get, p) => ({ sum: get(p).a + get(p).b }) }
)
// derivedSnap.sum 自动更新
`$3
`tsx
const store = createStore({ theme: 'light' })
store.persist('app-settings') // 自动与 localStorage 双向同步,返回取消订阅函数
`$3
`tsx
import { createMap, createSet } from '@empjs/valtio'const map = createMap([['a', 1]])
const set = createSet([1, 2, 3])
// 可放入 createStore 初始状态或 useStore,响应式更新
`API 概览
| 能力 | 说明 |
|------|------|
|
createStore(initialState, options?) | 创建全局增强 store;options 支持 devtools、name、history、derive |
| useStore(initialState, options?) | 组件内局部 store;options 支持 history、derive |
| createMap / createSet | 可代理的 Map/Set |
| Store 方法 | getSnapshot、useSnapshot、subscribe、subscribeKey、subscribeKeys、update、set、setNested、delete、reset、ref、batch、clone、toJSON、fromJSON、persist、debug |同时从本库可再导出 Valtio 原生:
proxy、snapshot、subscribe、subscribeKey、ref、useSnapshot、proxyWithHistory、proxyMap、proxySet、derive、devtools。文档与示例
- 在线文档与 Demo:运行本仓库根目录
pnpm dev,访问 apps/valtio-offical 提供的文档站。
- 对比与设计:见仓库根目录 docs/improvements.md、docs/compare.md。测试与覆盖率
`bash
bun test # 运行测试
bun test --coverage # 运行测试并生成覆盖率(或 pnpm tc)
`测试用例位于
test/ 目录,按功能分文件:enhanceStore.test.ts、createStore.test.ts、createStore.history.test.ts、createStore.derive.test.ts、collections.test.ts、subscribe.test.ts、persist.test.ts、useStore.test.tsx`。MIT