@warp-ts/reactivity 0.1.2 → 0.1.3

package/README.md

@@ -0,0 +1,67 @@
+# `@warp-ts/reactivity`
+
+Warp 的细粒度响应式内核：`signal` / `computed` / `effect` / `batch` / owner 树 / `reactive`。
+零依赖、可脱离 DOM 单独使用；Warp 的模板绑定、组件、store 都建在它之上。
+
+## 安装
+
+```bash
+pnpm add @warp-ts/reactivity
+```
+
+用 Warp 写应用时直接从 `@warp-ts/warp` 导入即可（它再导出本包全部公开 API）。
+
+## 用法
+
+```ts
+import { batch, computed, effect, onCleanup, signal, untrack } from '@warp-ts/reactivity'
+
+const first = signal('张')
+const last = signal('三')
+const full = computed(() => first() + last())
+
+const stop = effect(() => {
+  console.log(full())                       // 依赖 first / last（经由 full）
+  onCleanup(() => console.log('上一轮清理'))
+})
+
+batch(() => { first.set('李'); last.set('四') })   // 只触发 1 次 effect
+untrack(() => full())                              // 读但不订阅
+stop()
+```
+
+列表更新用 `set` 的函数形态（读旧值不建立依赖）：
+
+```ts
+const items = signal<number[]>([])
+items.set(l => l.concat(1))
+```
+
+## API 一览
+
+| API | 说明 |
+|---|---|
+| `signal(v, opts?)` | 读 `s()`、写 `s.set(v \| prev => v)`、不追踪读 `s.peek()`；`opts.equals: false` 每次写都通知 |
+| `computed(fn, opts?)` | 惰性 + 缓存，必须纯函数 |
+| `effect(fn)` / `renderEffect(fn)` | 副作用；返回 `stop`。`renderEffect` 创建即同步执行 |
+| `batch(fn)` / `untrack(fn)` / `flushSync()` | 合并写入 / 不追踪读取 / 同步刷完待处理 effect |
+| `reactive(obj)` / `shallowReactive` / `isReactive` / `toRaw` | Proxy 深响应，支持数组 / Map / Set |
+| `createRoot(fn)` / `getOwner()` / `runWithOwner(owner, fn)` / `onCleanup(fn)` | 所有权与释放 |
+| `createSelector(source)` | 选中态优化：只通知旧 / 新两个 key |
+
+```ts
+import { createRoot, onCleanup } from '@warp-ts/reactivity'
+
+const dispose = createRoot(d => {
+  const t = setInterval(() => {}, 1000)
+  onCleanup(() => clearInterval(t))   // 归当前 owner，dispose 时一并释放
+  return d
+})
+dispose()
+```
+
+## 说明
+
+- `signal` 适合整体替换的值；就地改字段的深层对象用 `reactive`。
+- `effect` / `onCleanup` 建在无 owner 处（模块顶层、`setTimeout` 回调）会永不释放，dev 下报 `WARP-R101`。
+- 属于 Warp 框架，通常通过 `@warp-ts/warp` 聚合入口使用。

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "@warp-ts/reactivity",
-  "version": "0.1.2",
-  "description": "Signal / Computed / Effect / batch / owner 树 / reactive",
+  "version": "0.1.3",
+  "description": "Warp 的细粒度响应式内核：signal / computed / effect / batch / owner 树 / reactive，零依赖",
+  "keywords": [
+    "warp",
+    "signals",
+    "reactive",
+    "reactivity",
+    "fine-grained",
+    "state"
+  ],
   "type": "module",
   "sideEffects": false,
   "license": "MIT",