@feng3d/reactivity 1.0.4 → 1.0.6

package/dist/index.umd.cjs

@@ -10,33 +10,42 @@
      * 获取当前节点值。
      *
      * 取值时将会建立与父节点的依赖关系。
+     * 当其他响应式节点访问此值时，会自动建立依赖关系。
      */
     get value() {
       this.track();
       return this._value;
     }
     /**
-     * 捕捉。
+     * 建立依赖关系。
      *
-     * 建立与父节点的依赖关系。
+     * 当其他节点访问当前节点的值时，会调用此方法。
+     * 将当前节点与访问者（父节点）建立依赖关系。
+     *
+     * 如果当前没有活动的响应式节点，或者不应该跟踪依赖，则不会建立依赖关系。
      */
     track() {
-      if (!Reactivity.activeReactivity || !_shouldTrack)
-        return;
+      if (!Reactivity.activeReactivity || !_shouldTrack) return;
       const parent = Reactivity.activeReactivity;
       if (parent) {
         this._parents.set(parent, parent._version);
       }
     }
     /**
-     * 触发。
+     * 触发更新。
+     *
+     * 当节点值发生变化时，会调用此方法。
+     * 通知所有依赖此节点的父节点进行更新。
      *
-     * 冒泡到所有父节点，设置失效子节点字典。
+     * 更新过程：
+     * 1. 遍历所有父节点
+     * 2. 检查父节点的版本号是否匹配
+     * 3. 触发父节点的更新
+     * 4. 将当前节点添加到父节点的失效子节点集合中
      */
     trigger() {
       this._parents.forEach((version, parent) => {
-        if (parent._version !== version)
-          return;
+        if (parent._version !== version) return;
         parent.trigger();
         parent._children.set(this, this._value);
       });
@@ -99,8 +108,9 @@
   }
   class ComputedReactivity extends Reactivity {
     /**
-     * 创建计算依赖。
-     * @param func 检测的可能包含响应式的函数。
+     * 创建计算反应式节点。
+     *
+     * @param func 计算函数，可以访问其他响应式数据，并返回计算结果
      */
     constructor(func) {
       super();
@@ -111,11 +121,12 @@
       this._func = func;
     }
     /**
-     * 获取值。
+     * 获取计算属性的值。
      *
-     * 取值时将会建立与父节点的依赖关系。
-     *
-     * 同时会检查子节点是否发生变化，如果发生变化，则重新计算。
+     * 取值时会：
+     * 1. 检查是否需要重新计算
+     * 2. 建立与父节点的依赖关系
+     * 3. 返回当前值
      */
     get value() {
       this.runIfDirty();
@@ -123,11 +134,11 @@
       return this._value;
     }
     /**
-     * 触发。
+     * 触发更新。
      *
-     * 冒泡到所有父节点，设置失效子节点字典。
-     *
-     * 把触发节点添加到失效子节点字典队列中。
+     * 当依赖发生变化时，会调用此方法。
+     * 如果当前正在执行计算，会将更新延迟到计算完成后。
+     * 否则，立即通知所有父节点进行更新。
      */
     trigger() {
       if (Reactivity.activeReactivity === this) {
@@ -136,7 +147,14 @@
       super.trigger();
     }
     /**
-     * 执行当前节点。
+     * 执行计算。
+     *
+     * 执行计算函数，更新当前值。
+     * 在计算过程中会：
+     * 1. 强制启用依赖跟踪
+     * 2. 保存并设置当前活动节点
+     * 3. 执行计算函数
+     * 4. 恢复活动节点
      */
     run() {
       forceTrack(() => {
@@ -148,9 +166,13 @@
       });
     }
     /**
-     * 检查当前节点是否脏。
+     * 检查并执行计算。
+     *
+     * 检查当前节点是否需要重新计算：
+     * 1. 如果脏标记为 true，需要重新计算
+     * 2. 如果子节点发生变化，需要重新计算
      *
-     * 如果脏，则执行计算。
+     * 重新计算后会清除脏标记。
      */
     runIfDirty() {
       this._isDirty = this._isDirty || this.isChildrenChanged();
@@ -160,17 +182,26 @@
       }
     }
     /**
-     * 判断子节点是否发生变化。
+     * 检查子节点是否发生变化。
+     *
+     * 遍历所有子节点，检查它们的值是否发生变化。
+     * 如果发生变化，返回 true，否则返回 false。
+     *
+     * 在检查过程中会：
+     * 1. 临时禁用依赖跟踪
+     * 2. 检查每个子节点的值
+     * 3. 如果子节点没有变化，重新建立依赖关系
+     * 4. 清空子节点集合
+     *
+     * @returns 是否有子节点发生变化
      */
     isChildrenChanged() {
-      if (this._children.size === 0)
-        return false;
+      if (this._children.size === 0) return false;
       let isChanged = false;
       const preReactiveNode = Reactivity.activeReactivity;
       Reactivity.activeReactivity = null;
       this._children.forEach((value, node) => {
-        if (isChanged)
-          return;
+        if (isChanged) return;
         if (node.value !== value) {
           isChanged = true;
           return;
@@ -186,52 +217,6 @@
       return isChanged;
     }
   }
-  function effect(fn) {
-    return new EffectReactivity(fn);
-  }
-  const _EffectReactivity = class _EffectReactivity2 extends ComputedReactivity {
-    constructor(func) {
-      super(func);
-      this._isEnable = true;
-      this.runIfDirty();
-    }
-    pause() {
-      this._isEnable = false;
-    }
-    resume() {
-      if (this._isEnable)
-        return;
-      this._isEnable = true;
-      if (_EffectReactivity2.pausedQueueEffects.has(this)) {
-        _EffectReactivity2.pausedQueueEffects.delete(this);
-        this.trigger();
-      }
-    }
-    trigger() {
-      batchRun(() => {
-        super.trigger();
-        if (this._isEnable) {
-          batch(this, Reactivity.activeReactivity === this);
-        } else {
-          _EffectReactivity2.pausedQueueEffects.add(this);
-        }
-      });
-    }
-    /**
-     * 执行当前节点。
-     *
-     * 当暂停时将会直接执行被包装的函数。
-     */
-    run() {
-      if (this._isEnable) {
-        super.run();
-      } else {
-        this._func(this._value);
-      }
-    }
-  };
-  _EffectReactivity.pausedQueueEffects = /* @__PURE__ */ new WeakSet();
-  let EffectReactivity = _EffectReactivity;
   var ReactiveFlags = /* @__PURE__ */ ((ReactiveFlags2) => {
     ReactiveFlags2["IS_REACTIVE"] = "__v_isReactive";
     ReactiveFlags2["RAW"] = "__v_raw";
@@ -284,8 +269,7 @@
     }
   }
   function getTargetType(value) {
-    if (!Object.isExtensible(value))
-      return TargetType.INVALID;
+    if (!Object.isExtensible(value)) return TargetType.INVALID;
     return targetTypeMap(toRawType(value));
   }
   const toTypeString = (value) => Object.prototype.toString.call(value);
@@ -300,10 +284,231 @@
   // @__NO_SIDE_EFFECTS__
   function makeMap(str) {
     const map = /* @__PURE__ */ Object.create(null);
-    for (const key of str.split(","))
-      map[key] = 1;
+    for (const key of str.split(",")) map[key] = 1;
     return (val) => val in map;
   }
+  let activeEffectScope;
+  class EffectScope {
+    /**
+     * 构造函数
+     * @param detached 是否创建分离的作用域
+     */
+    constructor(detached = false) {
+      this.detached = detached;
+      this._active = true;
+      this._on = 0;
+      this.effects = [];
+      this.cleanups = [];
+      this._isPaused = false;
+      this.parent = activeEffectScope;
+      if (!detached && activeEffectScope) {
+        this.index = (activeEffectScope.scopes || (activeEffectScope.scopes = [])).push(
+          this
+        ) - 1;
+      }
+    }
+    /**
+     * 获取作用域是否处于活动状态
+     */
+    get active() {
+      return this._active;
+    }
+    /**
+     * 暂停作用域
+     *
+     * 暂停当前作用域及其所有子作用域和效果
+     */
+    pause() {
+      if (this._active) {
+        this._isPaused = true;
+        let i, l;
+        if (this.scopes) {
+          for (i = 0, l = this.scopes.length; i < l; i++) {
+            this.scopes[i].pause();
+          }
+        }
+        for (i = 0, l = this.effects.length; i < l; i++) {
+          this.effects[i].pause();
+        }
+      }
+    }
+    /**
+     * 恢复作用域
+     *
+     * 恢复当前作用域及其所有子作用域和效果
+     */
+    resume() {
+      if (this._active) {
+        if (this._isPaused) {
+          this._isPaused = false;
+          let i, l;
+          if (this.scopes) {
+            for (i = 0, l = this.scopes.length; i < l; i++) {
+              this.scopes[i].resume();
+            }
+          }
+          for (i = 0, l = this.effects.length; i < l; i++) {
+            this.effects[i].resume();
+          }
+        }
+      }
+    }
+    /**
+     * 在作用域中运行函数
+     * @param fn 要运行的函数
+     * @returns 函数的返回值
+     */
+    run(fn) {
+      if (this._active) {
+        const currentEffectScope = activeEffectScope;
+        try {
+          activeEffectScope = this;
+          return fn();
+        } finally {
+          activeEffectScope = currentEffectScope;
+        }
+      }
+    }
+    /**
+     * 激活作用域
+     * 仅应在非分离的作用域上调用
+     * @internal
+     */
+    on() {
+      if (++this._on === 1) {
+        this.prevScope = activeEffectScope;
+        activeEffectScope = this;
+      }
+    }
+    /**
+     * 停用作用域
+     * 仅应在非分离的作用域上调用
+     * @internal
+     */
+    off() {
+      if (this._on > 0 && --this._on === 0) {
+        activeEffectScope = this.prevScope;
+        this.prevScope = void 0;
+      }
+    }
+    /**
+     * 停止作用域
+     *
+     * 停止当前作用域及其所有子作用域和效果，并执行清理函数
+     * @param fromParent 是否由父作用域调用
+     */
+    stop(fromParent) {
+      if (this._active) {
+        this._active = false;
+        let i, l;
+        for (i = 0, l = this.effects.length; i < l; i++) {
+          this.effects[i].stop();
+        }
+        this.effects.length = 0;
+        for (i = 0, l = this.cleanups.length; i < l; i++) {
+          this.cleanups[i]();
+        }
+        this.cleanups.length = 0;
+        if (this.scopes) {
+          for (i = 0, l = this.scopes.length; i < l; i++) {
+            this.scopes[i].stop(true);
+          }
+          this.scopes.length = 0;
+        }
+        if (!this.detached && this.parent && !fromParent) {
+          const last = this.parent.scopes.pop();
+          if (last && last !== this) {
+            this.parent.scopes[this.index] = last;
+            last.index = this.index;
+          }
+        }
+        this.parent = void 0;
+      }
+    }
+  }
+  function effectScope(detached) {
+    return new EffectScope(detached);
+  }
+  function getCurrentScope() {
+    return activeEffectScope;
+  }
+  function onScopeDispose(fn, failSilently = false) {
+    if (activeEffectScope) {
+      activeEffectScope.cleanups.push(fn);
+    }
+  }
+  function effect(fn) {
+    return new EffectReactivity(fn);
+  }
+  const _EffectReactivity = class _EffectReactivity extends ComputedReactivity {
+    constructor(func) {
+      super(func);
+      this._isEnable = true;
+      if (activeEffectScope && activeEffectScope.active) {
+        activeEffectScope.effects.push(this);
+      }
+      this.runIfDirty();
+    }
+    /**
+     * 暂停效果。
+     *
+     * 暂停后，当依赖发生变化时不会自动执行。
+     */
+    pause() {
+      this._isEnable = false;
+    }
+    /**
+     * 恢复效果。
+     *
+     * 恢复后，当依赖发生变化时会自动执行。
+     */
+    resume() {
+      if (this._isEnable) return;
+      this._isEnable = true;
+      if (_EffectReactivity.pausedQueueEffects.has(this)) {
+        _EffectReactivity.pausedQueueEffects.delete(this);
+        this.trigger();
+      }
+    }
+    /**
+     * 停止效果。
+     *
+     * 停止后，效果将不再响应依赖的变化。
+     */
+    stop() {
+      this._isEnable = false;
+      _EffectReactivity.pausedQueueEffects.delete(this);
+    }
+    /**
+     * 触发效果执行。
+     *
+     * 当依赖发生变化时，会调用此方法。
+     */
+    trigger() {
+      batchRun(() => {
+        super.trigger();
+        if (this._isEnable) {
+          batch(this, Reactivity.activeReactivity === this);
+        } else {
+          _EffectReactivity.pausedQueueEffects.add(this);
+        }
+      });
+    }
+    /**
+     * 执行当前节点。
+     *
+     * 当暂停时将会直接执行被包装的函数。
+     */
+    run() {
+      if (this._isEnable) {
+        super.run();
+      } else {
+        this._func(this._value);
+      }
+    }
+  };
+  _EffectReactivity.pausedQueueEffects = /* @__PURE__ */ new WeakSet();
+  let EffectReactivity = _EffectReactivity;
   function property(target, key) {
     let depsMap = PropertyReactivity._targetMap.get(target);
     if (!depsMap) {
@@ -317,19 +522,7 @@
     }
     return dep;
   }
-  class PropertyReactivity extends Reactivity {
-    constructor(target, key) {
-      super();
-      this._target = target;
-      this._key = key;
-      if (target instanceof Map || target instanceof WeakMap) {
-        this._value = target.get(key);
-      } else if (target instanceof Set || target instanceof WeakSet) {
-        this._value = target.has(key);
-      } else {
-        this._value = target[key];
-      }
-    }
+  const _PropertyReactivity = class _PropertyReactivity extends Reactivity {
     /**
      * 获取当前节点值。
      *
@@ -345,11 +538,22 @@
       } else if (isSymbol(this._key)) {
         v = ~~this._value + 1;
       }
-      if (v === this._value)
-        return;
+      if (v === this._value) return;
       this.trigger();
       this._value = v;
     }
+    constructor(target, key) {
+      super();
+      this._target = target;
+      this._key = key;
+      if (target instanceof Map || target instanceof WeakMap) {
+        this._value = target.get(key);
+      } else if (target instanceof Set || target instanceof WeakSet) {
+        this._value = target.has(key);
+      } else {
+        this._value = target[key];
+      }
+    }
     triggerIfChanged() {
     }
     /**
@@ -362,8 +566,7 @@
      * @returns
      */
     static track(target, type, key) {
-      if (!Reactivity.activeReactivity)
-        return;
+      if (!Reactivity.activeReactivity) return;
       const dep = property(target, key);
       dep.track();
     }
@@ -379,8 +582,7 @@
      */
     static trigger(target, type, key, newValue, oldValue) {
       const depsMap = this._targetMap.get(target);
-      if (!depsMap)
-        return;
+      if (!depsMap) return;
       const run = (dep) => {
         if (dep) {
           dep.value = newValue;
@@ -435,18 +637,34 @@
         }
       });
     }
-  }
-  PropertyReactivity._targetMap = /* @__PURE__ */ new WeakMap();
+  };
+  _PropertyReactivity._targetMap = /* @__PURE__ */ new WeakMap();
+  let PropertyReactivity = _PropertyReactivity;
   const arrayInstrumentations = {
     __proto__: null,
     /**
-     * 返回一个迭代器，用于遍历数组的响应式值
+     * 返回一个迭代器，用于遍历数组的响应式值。
+     *
+     * 实现了以下功能：
+     * 1. 创建数组的迭代器
+     * 2. 自动将迭代的值转换为响应式
+     * 3. 自动追踪数组的访问
+     *
+     * @returns 数组的迭代器
      */
     [Symbol.iterator]() {
       return iterator(this, Symbol.iterator, toReactive);
     },
     /**
-     * 连接数组并返回新数组，处理响应式数组
+     * 连接数组并返回新数组。
+     *
+     * 实现了以下功能：
+     * 1. 处理响应式数组的连接
+     * 2. 自动将参数中的数组转换为响应式
+     * 3. 保持原始值的引用
+     *
+     * @param args 要连接的数组或值
+     * @returns 连接后的新数组
      */
     concat(...args) {
       return reactiveReadArray(this).concat(
@@ -454,7 +672,14 @@
       );
     },
     /**
-     * 返回一个迭代器，用于遍历数组的键值对，并将值转换为响应式
+     * 返回一个迭代器，用于遍历数组的键值对。
+     *
+     * 实现了以下功能：
+     * 1. 创建数组的键值对迭代器
+     * 2. 自动将值转换为响应式
+     * 3. 自动追踪数组的访问
+     *
+     * @returns 数组的键值对迭代器
      */
     entries() {
       return iterator(this, "entries", (value) => {
@@ -463,148 +688,357 @@
       });
     },
     /**
-     * 测试数组中的所有元素是否都通过了指定函数的测试
+     * 测试数组中的所有元素是否都通过了指定函数的测试。
+     *
+     * 实现了以下功能：
+     * 1. 遍历数组元素
+     * 2. 对每个元素执行测试函数
+     * 3. 自动追踪数组的访问
+     * 4. 处理响应式值的测试
+     *
+     * @param fn 测试函数
+     * @param thisArg 测试函数的 this 值
+     * @returns 如果所有元素都通过测试则返回 true，否则返回 false
      */
     every(fn, thisArg) {
       return apply(this, "every", fn, thisArg, void 0, arguments);
     },
     /**
-     * 创建一个新数组，包含通过指定函数测试的所有元素
+     * 创建一个新数组，包含通过指定函数测试的所有元素。
+     *
+     * 实现了以下功能：
+     * 1. 遍历数组元素
+     * 2. 对每个元素执行测试函数
+     * 3. 自动追踪数组的访问
+     * 4. 自动将结果转换为响应式
+     *
+     * @param fn 测试函数
+     * @param thisArg 测试函数的 this 值
+     * @returns 包含通过测试的元素的新数组
      */
     filter(fn, thisArg) {
       return apply(this, "filter", fn, thisArg, (v) => v.map(toReactive), arguments);
     },
     /**
-     * 返回数组中满足指定测试函数的第一个元素
+     * 返回数组中满足指定测试函数的第一个元素。
+     *
+     * 实现了以下功能：
+     * 1. 遍历数组元素
+     * 2. 对每个元素执行测试函数
+     * 3. 自动追踪数组的访问
+     * 4. 自动将结果转换为响应式
+     *
+     * @param fn 测试函数
+     * @param thisArg 测试函数的 this 值
+     * @returns 第一个满足测试的元素，如果没有则返回 undefined
      */
     find(fn, thisArg) {
       return apply(this, "find", fn, thisArg, toReactive, arguments);
     },
     /**
-     * 返回数组中满足指定测试函数的第一个元素的索引
+     * 返回数组中满足指定测试函数的第一个元素的索引。
+     *
+     * 实现了以下功能：
+     * 1. 遍历数组元素
+     * 2. 对每个元素执行测试函数
+     * 3. 自动追踪数组的访问
+     * 4. 处理响应式值的查找
+     *
+     * @param fn 测试函数
+     * @param thisArg 测试函数的 this 值
+     * @returns 第一个满足测试的元素的索引，如果没有则返回 -1
      */
     findIndex(fn, thisArg) {
       return apply(this, "findIndex", fn, thisArg, void 0, arguments);
     },
     /**
-     * 返回数组中满足指定测试函数的最后一个元素
+     * 返回数组中满足指定测试函数的最后一个元素。
+     *
+     * 实现了以下功能：
+     * 1. 从后向前遍历数组元素
+     * 2. 对每个元素执行测试函数
+     * 3. 自动追踪数组的访问
+     * 4. 自动将结果转换为响应式
+     *
+     * @param fn 测试函数
+     * @param thisArg 测试函数的 this 值
+     * @returns 最后一个满足测试的元素，如果没有则返回 undefined
      */
     findLast(fn, thisArg) {
       return apply(this, "findLast", fn, thisArg, toReactive, arguments);
     },
     /**
-     * 返回数组中满足指定测试函数的最后一个元素的索引
+     * 返回数组中满足指定测试函数的最后一个元素的索引。
+     *
+     * 实现了以下功能：
+     * 1. 从后向前遍历数组元素
+     * 2. 对每个元素执行测试函数
+     * 3. 自动追踪数组的访问
+     * 4. 处理响应式值的查找
+     *
+     * @param fn 测试函数
+     * @param thisArg 测试函数的 this 值
+     * @returns 最后一个满足测试的元素的索引，如果没有则返回 -1
      */
     findLastIndex(fn, thisArg) {
       return apply(this, "findLastIndex", fn, thisArg, void 0, arguments);
     },
-    // flat, flatMap could benefit from ARRAY_ITERATE but are not straight-forward to implement
+    // flat, flatMap 可以从 ARRAY_ITERATE 中受益，但实现起来不太直接
     /**
-     * 对数组中的每个元素执行指定函数
+     * 对数组中的每个元素执行指定函数。
+     *
+     * 实现了以下功能：
+     * 1. 遍历数组元素
+     * 2. 对每个元素执行回调函数
+     * 3. 自动追踪数组的访问
+     * 4. 处理响应式值的遍历
+     *
+     * @param fn 回调函数
+     * @param thisArg 回调函数的 this 值
      */
     forEach(fn, thisArg) {
       return apply(this, "forEach", fn, thisArg, void 0, arguments);
     },
     /**
-     * 判断数组是否包含指定元素，处理响应式值
+     * 判断数组是否包含指定元素。
+     *
+     * 实现了以下功能：
+     * 1. 处理响应式值的查找
+     * 2. 自动追踪数组的访问
+     * 3. 处理代理对象的查找
+     *
+     * @param args 要查找的元素
+     * @returns 如果数组包含该元素则返回 true，否则返回 false
      */
     includes(...args) {
       return searchProxy(this, "includes", args);
     },
     /**
-     * 返回数组中指定元素第一次出现的索引，处理响应式值
+     * 返回数组中指定元素第一次出现的索引。
+     *
+     * 实现了以下功能：
+     * 1. 处理响应式值的查找
+     * 2. 自动追踪数组的访问
+     * 3. 处理代理对象的查找
+     *
+     * @param args 要查找的元素
+     * @returns 元素第一次出现的索引，如果没有则返回 -1
      */
     indexOf(...args) {
       return searchProxy(this, "indexOf", args);
     },
     /**
-     * 将数组的所有元素连接成一个字符串
+     * 将数组的所有元素连接成一个字符串。
+     *
+     * 实现了以下功能：
+     * 1. 处理响应式数组的连接
+     * 2. 自动追踪数组的访问
+     * 3. 保持原始值的引用
+     *
+     * @param separator 分隔符
+     * @returns 连接后的字符串
      */
     join(separator) {
       return reactiveReadArray(this).join(separator);
     },
-    // keys() iterator only reads `length`, no optimisation required
+    // keys() 迭代器只读取 length，不需要优化
     /**
-     * 返回数组中指定元素最后一次出现的索引，处理响应式值
+     * 返回数组中指定元素最后一次出现的索引。
+     *
+     * 实现了以下功能：
+     * 1. 处理响应式值的查找
+     * 2. 自动追踪数组的访问
+     * 3. 处理代理对象的查找
+     *
+     * @param args 要查找的元素
+     * @returns 元素最后一次出现的索引，如果没有则返回 -1
      */
     lastIndexOf(...args) {
       return searchProxy(this, "lastIndexOf", args);
     },
     /**
-     * 创建一个新数组，包含对原数组每个元素调用指定函数的结果
+     * 创建一个新数组，包含对原数组每个元素调用指定函数的结果。
+     *
+     * 实现了以下功能：
+     * 1. 遍历数组元素
+     * 2. 对每个元素执行映射函数
+     * 3. 自动追踪数组的访问
+     * 4. 处理响应式值的映射
+     *
+     * @param fn 映射函数
+     * @param thisArg 映射函数的 this 值
+     * @returns 包含映射结果的新数组
      */
     map(fn, thisArg) {
       return apply(this, "map", fn, thisArg, void 0, arguments);
     },
     /**
-     * 移除数组的最后一个元素并返回该元素，避免跟踪长度变化
+     * 移除数组的最后一个元素并返回该元素。
+     *
+     * 实现了以下功能：
+     * 1. 移除最后一个元素
+     * 2. 避免跟踪长度变化
+     * 3. 处理响应式值的移除
+     *
+     * @returns 被移除的元素
      */
     pop() {
       return noTracking(this, "pop");
     },
     /**
-     * 向数组末尾添加一个或多个元素，并返回新的长度，避免跟踪长度变化
+     * 向数组末尾添加一个或多个元素。
+     *
+     * 实现了以下功能：
+     * 1. 添加新元素
+     * 2. 避免跟踪长度变化
+     * 3. 处理响应式值的添加
+     *
+     * @param args 要添加的元素
+     * @returns 数组的新长度
      */
     push(...args) {
       return noTracking(this, "push", args);
     },
     /**
-     * 对数组中的每个元素执行累加器函数，并返回最终结果
+     * 对数组中的每个元素执行累加器函数。
+     *
+     * 实现了以下功能：
+     * 1. 从左到右遍历数组元素
+     * 2. 对每个元素执行累加器函数
+     * 3. 自动追踪数组的访问
+     * 4. 处理响应式值的累加
+     *
+     * @param fn 累加器函数
+     * @param args 初始值（可选）
+     * @returns 累加的结果
      */
     reduce(fn, ...args) {
       return reduce(this, "reduce", fn, args);
     },
     /**
-     * 从右到左对数组中的每个元素执行累加器函数，并返回最终结果
+     * 从右到左对数组中的每个元素执行累加器函数。
+     *
+     * 实现了以下功能：
+     * 1. 从右到左遍历数组元素
+     * 2. 对每个元素执行累加器函数
+     * 3. 自动追踪数组的访问
+     * 4. 处理响应式值的累加
+     *
+     * @param fn 累加器函数
+     * @param args 初始值（可选）
+     * @returns 累加的结果
      */
     reduceRight(fn, ...args) {
       return reduce(this, "reduceRight", fn, args);
     },
     /**
-     * 移除数组的第一个元素并返回该元素，避免跟踪长度变化
+     * 移除数组的第一个元素并返回该元素。
+     *
+     * 实现了以下功能：
+     * 1. 移除第一个元素
+     * 2. 避免跟踪长度变化
+     * 3. 处理响应式值的移除
+     *
+     * @returns 被移除的元素
      */
     shift() {
       return noTracking(this, "shift");
     },
-    // slice could use ARRAY_ITERATE but also seems to beg for range tracking
+    // slice 可以使用 ARRAY_ITERATE，但似乎也需要范围追踪
     /**
-     * 测试数组中的某些元素是否通过了指定函数的测试
+     * 测试数组中的某些元素是否通过了指定函数的测试。
+     *
+     * 实现了以下功能：
+     * 1. 遍历数组元素
+     * 2. 对每个元素执行测试函数
+     * 3. 自动追踪数组的访问
+     * 4. 处理响应式值的测试
+     *
+     * @param fn 测试函数
+     * @param thisArg 测试函数的 this 值
+     * @returns 如果有元素通过测试则返回 true，否则返回 false
      */
     some(fn, thisArg) {
       return apply(this, "some", fn, thisArg, void 0, arguments);
     },
     /**
-     * 通过删除或替换现有元素或添加新元素来修改数组，避免跟踪长度变化
+     * 通过删除或替换现有元素或添加新元素来修改数组。
+     *
+     * 实现了以下功能：
+     * 1. 修改数组内容
+     * 2. 避免跟踪长度变化
+     * 3. 处理响应式值的修改
+     *
+     * @param args 要删除的起始索引、要删除的元素数量和要添加的元素
+     * @returns 包含被删除元素的新数组
      */
     splice(...args) {
       return noTracking(this, "splice", args);
     },
     /**
-     * 返回一个新数组，包含原数组的反转副本
+     * 返回一个新数组，包含原数组的反转副本。
+     *
+     * 实现了以下功能：
+     * 1. 创建数组的反转副本
+     * 2. 自动将结果转换为响应式
+     * 3. 保持原始值的引用
+     *
+     * @returns 反转后的新数组
      */
     toReversed() {
       return reactiveReadArray(this).toReversed();
     },
     /**
-     * 返回一个新数组，包含原数组的排序副本
+     * 返回一个新数组，包含原数组的排序副本。
+     *
+     * 实现了以下功能：
+     * 1. 创建数组的排序副本
+     * 2. 自动将结果转换为响应式
+     * 3. 保持原始值的引用
+     *
+     * @param comparer 比较函数
+     * @returns 排序后的新数组
      */
     toSorted(comparer) {
       return reactiveReadArray(this).toSorted(comparer);
     },
     /**
-     * 返回一个新数组，包含原数组的切片副本
+     * 返回一个新数组，包含原数组的切片副本。
+     *
+     * 实现了以下功能：
+     * 1. 创建数组的切片副本
+     * 2. 自动将结果转换为响应式
+     * 3. 保持原始值的引用
+     *
+     * @param args 起始索引和结束索引
+     * @returns 切片后的新数组
      */
     toSpliced(...args) {
       return reactiveReadArray(this).toSpliced(...args);
     },
     /**
-     * 向数组开头添加一个或多个元素，并返回新的长度，避免跟踪长度变化
+     * 向数组开头添加一个或多个元素。
+     *
+     * 实现了以下功能：
+     * 1. 添加新元素
+     * 2. 避免跟踪长度变化
+     * 3. 处理响应式值的添加
+     *
+     * @param args 要添加的元素
+     * @returns 数组的新长度
      */
     unshift(...args) {
       return noTracking(this, "unshift", args);
     },
     /**
-     * 返回一个迭代器，用于遍历数组的响应式值
+     * 返回一个迭代器，用于遍历数组的值。
+     *
+     * 实现了以下功能：
+     * 1. 创建数组的值迭代器
+     * 2. 自动将迭代的值转换为响应式
+     * 3. 自动追踪数组的访问
+     *
+     * @returns 数组的值迭代器
      */
     values() {
       return iterator(this, "values", toReactive);
@@ -631,8 +1065,7 @@
   }
   function reactiveReadArray(array) {
     const raw = toRaw(array);
-    if (raw === array)
-      return raw;
+    if (raw === array) return raw;
     PropertyReactivity.track(raw, TrackOpTypes.ITERATE, ARRAY_ITERATE_KEY);
     return raw.map(toReactive);
   }
@@ -687,7 +1120,7 @@
     );
     return res;
   }
-  var _a;
+  var _a, _b;
   function ref(value) {
     if (isRef(value)) {
       return value;
@@ -697,22 +1130,45 @@
   function isRef(r) {
     return r ? r[ReactiveFlags.IS_REF] === true : false;
   }
-  class RefReactivity extends Reactivity {
+  class RefReactivity extends (_b = Reactivity, _a = ReactiveFlags.IS_REF, _b) {
+    /**
+     * 创建引用反应式节点。
+     *
+     * @param value 要包装的值
+     */
     constructor(value) {
       super();
       this[_a] = true;
       this._rawValue = toRaw(value);
       this._value = toReactive(value);
     }
+    /**
+     * 获取引用的值。
+     *
+     * 取值时会：
+     * 1. 建立依赖关系
+     * 2. 返回当前值
+     */
     get value() {
       this.track();
       return this._value;
     }
+    /**
+     * 设置引用的值。
+     *
+     * 设置值时会：
+     * 1. 比较新旧值是否发生变化
+     * 2. 如果值发生变化，则：
+     *    - 触发更新通知
+     *    - 更新原始值
+     *    - 更新响应式值
+     *
+     * @param v 要设置的新值
+     */
     set value(v) {
       const oldValue = this._rawValue;
       const newValue = toRaw(v);
-      if (!hasChanged(oldValue, newValue))
-        return;
+      if (!hasChanged(oldValue, newValue)) return;
       batchRun(() => {
         this.trigger();
         this._rawValue = newValue;
@@ -720,15 +1176,22 @@
       });
     }
   }
-  _a = ReactiveFlags.IS_REF;
   class BaseReactiveHandler {
     /**
      * 获取对象的属性值。
      *
-     * @param target 对象本身
-     * @param key 属性名
-     * @param receiver 代理对象
-     * @returns
+     * 实现了以下功能：
+     * 1. 响应式对象标识检查
+     * 2. 原始对象获取
+     * 3. 数组方法拦截
+     * 4. 属性依赖追踪
+     * 5. 值的自动解包
+     * 6. 对象的自动响应式转换
+     *
+     * @param target 被代理的原始对象
+     * @param key 要获取的属性名
+     * @param receiver 代理对象本身
+     * @returns 获取到的属性值
      */
     get(target, key, receiver) {
       if (key === ReactiveFlags.IS_REACTIVE) {
@@ -768,11 +1231,18 @@
   class MutableReactiveHandler extends BaseReactiveHandler {
     /**
      * 设置对象的属性值。
-     * @param target 被代理的对象。
-     * @param key 属性名。
-     * @param value 新值。
-     * @param receiver 代理对象。
-     * @returns 设置是否成功。
+     *
+     * 实现了以下功能：
+     * 1. 值的原始化处理
+     * 2. ref 值的特殊处理
+     * 3. 属性变更通知
+     * 4. 数组长度的特殊处理
+     *
+     * @param target 被代理的原始对象
+     * @param key 要设置的属性名
+     * @param value 要设置的新值
+     * @param receiver 代理对象本身
+     * @returns 设置是否成功
      */
     set(target, key, value, receiver) {
       let oldValue = target[key];
@@ -801,9 +1271,13 @@
     /**
      * 删除对象的属性。
      *
-     * @param target 被代理的对象。
-     * @param key 属性名。
-     * @returns 删除是否成功。
+     * 实现了以下功能：
+     * 1. 属性删除操作
+     * 2. 删除后的变更通知
+     *
+     * @param target 被代理的原始对象
+     * @param key 要删除的属性名
+     * @returns 删除是否成功
      */
     deleteProperty(target, key) {
       const hadKey = hasOwn(target, key);
@@ -814,6 +1288,17 @@
       }
       return result;
     }
+    /**
+     * 检查对象是否包含某个属性。
+     *
+     * 实现了以下功能：
+     * 1. 属性存在性检查
+     * 2. 属性访问依赖追踪
+     *
+     * @param target 被代理的原始对象
+     * @param key 要检查的属性名
+     * @returns 属性是否存在
+     */
     has(target, key) {
       const result = Reflect.has(target, key);
       if (!isSymbol(key) || !builtInSymbols.has(key)) {
@@ -821,6 +1306,16 @@
       }
       return result;
     }
+    /**
+     * 获取对象的所有属性名。
+     *
+     * 实现了以下功能：
+     * 1. 属性遍历
+     * 2. 遍历操作的依赖追踪
+     *
+     * @param target 被代理的原始对象
+     * @returns 对象的所有属性名数组
+     */
     ownKeys(target) {
       PropertyReactivity.track(
         target,
@@ -832,8 +1327,7 @@
   }
   const mutableHandlers = new MutableReactiveHandler();
   function hasOwnProperty(key) {
-    if (!isSymbol(key))
-      key = String(key);
+    if (!isSymbol(key)) key = String(key);
     const obj = toRaw(this);
     PropertyReactivity.track(obj, TrackOpTypes.HAS, key);
     return obj.hasOwnProperty(key);
@@ -862,6 +1356,17 @@
   }
   function createInstrumentations() {
     const instrumentations = {
+      /**
+       * 获取 Map 中的值。
+       *
+       * 实现了以下功能：
+       * 1. 支持原始键和响应式键的查找
+       * 2. 自动追踪键的访问
+       * 3. 自动将返回值转换为响应式
+       *
+       * @param key 要查找的键
+       * @returns 找到的值，如果不存在则返回 undefined
+       */
       get(key) {
         const target = this[ReactiveFlags.RAW];
         const rawTarget = toRaw(target);
@@ -880,11 +1385,28 @@
           target.get(key);
         }
       },
+      /**
+       * 获取集合的大小。
+       *
+       * 实现了以下功能：
+       * 1. 追踪集合大小的访问
+       * 2. 返回集合的实际大小
+       */
       get size() {
         const target = this[ReactiveFlags.RAW];
         PropertyReactivity.track(toRaw(target), TrackOpTypes.ITERATE, ITERATE_KEY);
         return Reflect.get(target, "size", target);
       },
+      /**
+       * 检查集合是否包含某个值。
+       *
+       * 实现了以下功能：
+       * 1. 支持原始键和响应式键的检查
+       * 2. 自动追踪键的检查
+       *
+       * @param key 要检查的键
+       * @returns 如果集合包含该键则返回 true，否则返回 false
+       */
       has(key) {
         const target = this[ReactiveFlags.RAW];
         const rawTarget = toRaw(target);
@@ -895,6 +1417,17 @@
         PropertyReactivity.track(rawTarget, TrackOpTypes.HAS, rawKey);
         return key === rawKey ? target.has(key) : target.has(key) || target.has(rawKey);
       },
+      /**
+       * 遍历集合中的所有元素。
+       *
+       * 实现了以下功能：
+       * 1. 追踪集合的遍历操作
+       * 2. 自动将遍历的值转换为响应式
+       * 3. 保持回调函数的 this 上下文
+       *
+       * @param callback 遍历回调函数
+       * @param thisArg 回调函数的 this 值
+       */
       forEach(callback, thisArg) {
         const observed = this;
         const target = observed[ReactiveFlags.RAW];
@@ -903,13 +1436,24 @@
         PropertyReactivity.track(rawTarget, TrackOpTypes.ITERATE, ITERATE_KEY);
         return target.forEach(
           (value, key) => (
-            // important: make sure the callback is
-            // 1. invoked with the reactive map as `this` and 3rd arg
-            // 2. the value received should be a corresponding reactive/readonly.
+            // 重要：确保回调函数
+            // 1. 使用响应式 map 作为 this 和第三个参数
+            // 2. 接收到的值应该是相应的响应式/只读版本
             callback.call(thisArg, wrap(value), wrap(key), observed)
           )
         );
       },
+      /**
+       * 向 Set 中添加值。
+       *
+       * 实现了以下功能：
+       * 1. 自动将值转换为原始值
+       * 2. 避免重复添加
+       * 3. 触发添加操作的通知
+       *
+       * @param value 要添加的值
+       * @returns 集合本身，支持链式调用
+       */
       add(value) {
         value = toRaw(value);
         const target = toRaw(this);
@@ -921,6 +1465,18 @@
         }
         return this;
       },
+      /**
+       * 设置 Map 中的值。
+       *
+       * 实现了以下功能：
+       * 1. 自动将值转换为原始值
+       * 2. 支持原始键和响应式键的设置
+       * 3. 触发添加或修改操作的通知
+       *
+       * @param key 要设置的键
+       * @param value 要设置的值
+       * @returns 集合本身，支持链式调用
+       */
       set(key, value) {
         value = toRaw(value);
         const target = toRaw(this);
@@ -939,6 +1495,16 @@
         }
         return this;
       },
+      /**
+       * 从集合中删除值。
+       *
+       * 实现了以下功能：
+       * 1. 支持原始键和响应式键的删除
+       * 2. 触发删除操作的通知
+       *
+       * @param key 要删除的键
+       * @returns 如果删除成功则返回 true，否则返回 false
+       */
       delete(key) {
         const target = toRaw(this);
         const { has, get } = getProto(target);
@@ -954,6 +1520,16 @@
         }
         return result;
       },
+      /**
+       * 清空集合。
+       *
+       * 实现了以下功能：
+       * 1. 清空集合中的所有元素
+       * 2. 触发清空操作的通知
+       * 3. 在开发模式下保存旧值用于调试
+       *
+       * @returns 如果清空成功则返回 true，否则返回 false
+       */
       clear() {
         const target = toRaw(this);
         const hadItems = target.size !== 0;
@@ -997,7 +1573,7 @@
         isKeyOnly ? MAP_KEY_ITERATE_KEY : ITERATE_KEY
       );
       return {
-        // iterator protocol
+        // 迭代器协议
         next() {
           const { value, done } = innerIterator.next();
           return done ? { value, done } : {
@@ -1005,7 +1581,7 @@
             done
           };
         },
-        // iterable protocol
+        // 可迭代协议
         [Symbol.iterator]() {
           return this;
         }
@@ -1048,18 +1624,21 @@
   function isProxy(value) {
     return value ? !!value[ReactiveFlags.RAW] : false;
   }
-  exports2.ComputedDep = ComputedReactivity;
-  exports2.Dep = Reactivity;
-  exports2.EffectDep = EffectReactivity;
+  exports2.EffectReactivity = EffectReactivity;
+  exports2.EffectScope = EffectScope;
+  exports2.Reactivity = Reactivity;
   exports2.RefReactivity = RefReactivity;
   exports2.batchRun = batchRun;
   exports2.computed = computed;
   exports2.effect = effect;
+  exports2.effectScope = effectScope;
   exports2.forceTrack = forceTrack;
+  exports2.getCurrentScope = getCurrentScope;
   exports2.isProxy = isProxy;
   exports2.isReactive = isReactive;
   exports2.isRef = isRef;
   exports2.noTrack = noTrack;
+  exports2.onScopeDispose = onScopeDispose;
   exports2.reactive = reactive;
   exports2.ref = ref;
   exports2.toRaw = toRaw;