@lytjs/reactivity 5.0.1 → 6.4.0

package/README.md

@@ -1,202 +1,327 @@
-# @lytjs/reactivity
-
-Lyt.js 响应式系统 - 提供响应式数据、计算属性、侦听器等核心响应式能力。
-
-## 安装
-
-```bash
-npm install @lytjs/reactivity
-
-# 或使用 pnpm
-pnpm add @lytjs/reactivity
-```
-
-## 特性
-
-- 🚀 Proxy 代理实现，性能优异
-- 🔄 Signal 细粒度响应式 API
-- 📦 完全兼容 Vue 3 响应式 API
-- 🎯 零运行时依赖，体积仅 2.86KB (gzip)
-
-## 快速开始
-
-### ref - 响应式引用
-
-```javascript
-import { ref } from '@lytjs/reactivity';
-
-const count = ref(0);
-console.log(count.value); // 0
-
-count.value++;
-console.log(count.value); // 1
-```
-
-### reactive - 响应式对象
-
-```javascript
-import { reactive } from '@lytjs/reactivity';
-
-const state = reactive({
-  count: 0,
-  name: 'Lyt.js'
-});
-
-console.log(state.count); // 0
-state.count++;
-console.log(state.count); // 1
-```
-
-### computed - 计算属性
-
-```javascript
-import { ref, computed } from '@lytjs/reactivity';
-
-const count = ref(0);
-const doubled = computed(() => count.value * 2);
-
-console.log(doubled.value); // 0
-
-count.value++;
-console.log(doubled.value); // 2
-```
-
-### watch - 数据侦听
-
-```javascript
-import { ref, watch } from '@lytjs/reactivity';
-
-const count = ref(0);
-
-watch(count, (newValue, oldValue) => {
-  console.log(`count 变化: ${oldValue} -> ${newValue}`);
-});
-
-count.value++; // count 变化: 0 -> 1
-```
-
-### effect - 副作用
-
-```javascript
-import { ref, effect } from '@lytjs/reactivity';
-
-const count = ref(0);
-
-effect(() => {
-  console.log(`count 当前值: ${count.value}`);
-});
-// count 当前值: 0
-
-count.value++; // count 当前值: 1
-```
-
-## Signal API
-
-Signal 提供细粒度响应式能力，性能更优：
-
-```javascript
-import { signal, computed } from '@lytjs/reactivity/signal';
-
-const count = signal(0);
-const doubled = computed(() => count() * 2);
-
-console.log(count()); // 0
-console.log(doubled()); // 0
-
-count.set(1);
-console.log(count()); // 1
-console.log(doubled()); // 2
-```
-
-## API 参考
-
-### 响应式 API
-
-| API | 说明 |
-|------|------|
-| `ref(value)` | 创建响应式引用 |
-| `reactive(obj)` | 创建响应式对象 |
-| `shallowRef(value)` | 创建浅层响应式引用 |
-| `readonly(obj)` | 创建只读响应式对象 |
-| `toRef(obj, key)` | 将对象属性转为 ref |
-| `toRefs(obj)` | 将对象所有属性转为 ref |
-
-### 计算与侦听
-
-| API | 说明 |
-|------|------|
-| `computed(fn)` | 创建计算属性 |
-| `watch(source, fn, options)` | 数据变化时执行回调 |
-| `watchEffect(fn)` | 立即执行并追踪响应式依赖 |
-| `effect(fn, options)` | 创建副作用 |
-| `stop(effect)` | 停止副作用 |
-
-### 工具函数
-
-| API | 说明 |
-|------|------|
-| `isRef(v)` | 判断是否为 ref |
-| `isReactive(v)` | 判断是否为 reactive |
-| `isReadonly(v)` | 判断是否为 readonly |
-| `unref(v)` | 解包 ref |
-| `nextTick(fn)` | 在下一次 DOM 更新后执行 |
-
-## 示例
-
-### 表单验证
-
-```javascript
-import { reactive, computed } from '@lytjs/reactivity';
-
-const form = reactive({
-  email: '',
-  password: ''
-});
-
-const isValidEmail = computed(() => {
-  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(form.email);
-});
-
-const isValidPassword = computed(() => {
-  return form.password.length >= 6;
-});
-
-const isFormValid = computed(() => {
-  return isValidEmail.value && isValidPassword.value;
-});
-```
-
-### 计数器
-
-```javascript
-import { ref, computed } from '@lytjs/reactivity';
-
-const count = ref(0);
-const doubled = computed(() => count.value * 2);
-
-function increment() {
-  count.value++;
-}
-
-function decrement() {
-  count.value--;
-}
-```
-
-## 性能
-
-- 体积：2.86 KB (ESM gzip)
-- 零运行时依赖
-- 原生 Proxy 实现，性能优异
-
-## 兼容性
-
-- Node.js >= 18.0.0
-- Chrome 64+
-- Firefox 63+
-- Safari 12+
-- Edge 79+
-
-## License
-
-MIT
+# @lytjs/reactivity
+
+> LytJS 响应式系统，提供 ref、reactive、computed、watch、Signal 等核心响应式原语
+
+## 安装
+
+```bash
+npm install @lytjs/reactivity
+```
+
+## 核心 API
+
+### reactive / shallowReactive / readonly / shallowReadonly
+
+创建响应式对象，支持深层/浅层响应和只读模式
+
+```typescript
+import { reactive, shallowReactive, readonly, shallowReadonly } from '@lytjs/reactivity';
+
+const state = reactive({ count: 0 });
+state.count++; // 自动追踪
+
+const shallow = shallowReactive({ nested: { value: 1 } });
+shallow.nested.value = 2; // 不会触发更新（浅层响应）
+```
+
+### ref / shallowRef
+
+创建响应式引用，适用于基本类型值
+
+```typescript
+import { ref, shallowRef, isShallowRef } from '@lytjs/reactivity';
+
+const count = ref(0);
+count.value++;
+
+const shallow = shallowRef({ nested: { value: 1 } });
+// isShallowRef 类型守卫
+if (isShallowRef(shallow)) {
+  console.log('这是一个 ShallowRef');
+}
+```
+
+### isShallowRef / isComputedRef
+
+类型守卫函数，用于在运行时判断 Ref 类型
+
+```typescript
+import { ref, shallowRef, computed, isShallowRef, isComputedRef } from '@lytjs/reactivity';
+
+const r = ref(0);
+const sr = shallowRef({ a: 1 });
+const c = computed(() => r.value * 2);
+
+isShallowRef(r); // false
+isShallowRef(sr); // true
+isComputedRef(r); // false
+isComputedRef(c); // true
+```
+
+### computed
+
+创建计算属性，自动追踪依赖并缓存结果
+
+```typescript
+import { computed, ref } from '@lytjs/reactivity';
+
+const count = ref(1);
+const doubled = computed(() => count.value * 2);
+console.log(doubled.value); // 2
+```
+
+### watch / watchEffect
+
+侦听响应式数据变化并执行副作用
+
+```typescript
+import { watch, watchEffect, ref } from '@lytjs/reactivity';
+
+const count = ref(0);
+
+// 侦听特定源
+watch(count, (newVal, oldVal) => {
+  console.log(`count changed from ${oldVal} to ${newVal}`);
+});
+
+// 自动追踪依赖
+watchEffect(() => {
+  console.log(`count is ${count.value}`);
+});
+```
+
+### effect
+
+创建自定义响应式副作用
+
+```typescript
+import { effect, stop } from '@lytjs/reactivity';
+
+const runner = effect(() => {
+  // 副作用逻辑
+});
+
+// 停止副作用
+stop(runner);
+```
+
+### toRef / toRefs / unref
+
+响应式引用工具函数
+
+```typescript
+import { toRef, toRefs, unref } from '@lytjs/reactivity';
+
+const state = reactive({ foo: 1, bar: 2 });
+const { foo, bar } = toRefs(state);
+
+const refFoo = toRef(state, 'foo');
+const value = unref(refFoo); // 1
+```
+
+## Signal API
+
+Signal 是一种独立的响应式原语，拥有独立的订阅/通知机制，同时桥接 effect 系统保持互操作性。
+
+### signal
+
+创建可写 Signal
+
+```typescript
+import { signal, computed } from '@lytjs/reactivity';
+
+const count = signal(0);
+
+// 读取值
+console.log(count()); // 0
+
+// 设置值
+count.set(1);
+
+// 通过 updater 更新
+count.update((prev) => prev + 1);
+
+// 停止所有订阅通知，释放资源
+count.dispose();
+```
+
+### computed (Signal 版本)
+
+创建计算 Signal，惰性求值、自动依赖追踪
+
+```typescript
+import { signal, computed } from '@lytjs/reactivity';
+
+const count = signal(1);
+const doubled = computed(() => count() * 2);
+
+console.log(doubled()); // 2
+
+// 停止计算信号的依赖追踪
+doubled.dispose();
+```
+
+### writableComputedSignal
+
+创建可写计算 Signal
+
+```typescript
+import { signal, writableComputedSignal } from '@lytjs/reactivity';
+
+const firstName = signal('John');
+const lastName = signal('Doe');
+
+const fullName = writableComputedSignal(
+  () => `${firstName()} ${lastName()}`,
+  (val) => {
+    const [first, last] = val.split(' ');
+    firstName.set(first);
+    lastName.set(last);
+  },
+);
+
+fullName.set('Jane Smith');
+```
+
+### signalBatch / signalUntrack
+
+Signal 批处理和取消追踪
+
+```typescript
+import { signal, signalBatch, signalUntrack } from '@lytjs/reactivity';
+
+const a = signal(1);
+const b = signal(2);
+
+// 批量更新：多次 set 只触发一次通知
+signalBatch(() => {
+  a.set(10);
+  b.set(20);
+});
+
+// 取消追踪：读取 signal 不建立依赖
+const value = signalUntrack(() => a());
+```
+
+## Effect 批处理
+
+### batch / batchAsync
+
+批量执行多个响应式更新，减少不必要的重复计算
+
+```typescript
+import { batch, batchAsync, ref, effect } from '@lytjs/reactivity';
+
+const a = ref(1);
+const b = ref(2);
+
+// 同步批处理
+batch(() => {
+  a.value = 10;
+  b.value = 20;
+  // 在 batch 结束前，effect 不会触发
+});
+
+// 异步批处理
+await batchAsync(async () => {
+  a.value = await fetchValue();
+  b.value = await fetchOtherValue();
+});
+```
+
+### batchScope
+
+更细粒度的批处理控制
+
+```typescript
+import { batchScope, batchScopeAsync, batchScopeUntrack, isInBatchScope } from '@lytjs/reactivity';
+
+// 带选项的批处理
+batchScope(
+  () => {
+    // 检查是否在批处理作用域内
+    if (isInBatchScope()) {
+      console.log('当前在批处理作用域内');
+    }
+  },
+  { flush: 'sync' },
+);
+
+// 异步批处理作用域
+await batchScopeAsync(async () => {
+  // 异步操作
+});
+
+// 取消追踪的批处理
+batchScopeUntrack(() => {
+  // 内部的响应式读取不会建立依赖
+});
+```
+
+### 嵌套批处理行为
+
+`batch()` 支持嵌套调用，使用栈追踪状态
+
+```typescript
+import { batch, effect } from '@lytjs/reactivity';
+
+batch(() => {
+  // 追踪已暂停
+  batch(() => {
+    // 追踪仍处于暂停状态
+  });
+  // 内层 batch 结束后，追踪仍处于暂停状态（由外层 batch 控制）
+});
+// 外层 batch 结束后，追踪恢复正常
+```
+
+## 边界行为与已知限制
+
+### `signal()` 的 undefined 参数歧义
+
+`signal()` 通过 `arguments.length` 来区分读取操作和写入操作。当传入 `undefined` 作为参数时，由于 `arguments.length > 0` 为 `true`，它会被视为**写入操作**。
+
+```typescript
+import { signal } from '@lytjs/reactivity';
+
+const sig = signal<number | undefined>(42);
+sig(undefined); // 写入操作：将值设为 undefined
+sig(); // 读取操作：返回 undefined
+```
+
+### `computedSignal.dispose()` 方法
+
+调用 `dispose()` 后：
+
+- 计算信号不再自动追踪依赖变化
+- 后续访问将返回最后一次缓存的值
+- 依赖该计算信号的其他 effect 不会再因依赖变化而被触发
+
+## DevTools 集成
+
+在开发环境下，响应式系统会自动初始化 DevTools 全局对象：
+
+```typescript
+// 浏览器控制台
+window.__LYTJS_DEVTOOLS__.getSignals();
+window.__LYTJS_DEVTOOLS__.getEffects();
+window.__LYTJS_DEVTOOLS__.onSignalChange((id, value) => {
+  console.log('Signal changed:', id, value);
+});
+```
+
+## 子路径入口
+
+```typescript
+// Effect Scope
+import { effectScope, getCurrentScope, onScopeDispose } from '@lytjs/reactivity/scope';
+
+// 异步计算
+import { asyncComputed, useAsyncState } from '@lytjs/reactivity/async';
+```
+
+## 相关包
+
+- [@lytjs/core](../core) - 框架核心入口，整合所有子包
+- [@lytjs/component](../component) - 组件系统，依赖响应式系统
+- [@lytjs/common](../common) - 公共工具库