@feng3d/reactivity 1.0.8 → 1.0.11

package/dist/index.js

@@ -1,6 +1,25 @@
-class Reactivity {
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+var _a, _b;
+const _Reactivity = class _Reactivity {
   constructor() {
-    this._parents = /* @__PURE__ */ new Map();
+    /**
+     * @private
+     */
+    __publicField(this, "_value");
+    /**
+     * 父反应节点集合。
+     *
+     * 记录了哪些节点依赖了当前节点。
+     * 当当前节点值发生变化时，会通知所有父节点。
+     *
+     * Map 的 key 是父节点，value 是父节点的版本号。
+     * 版本号用于判断依赖关系是否过期。
+     *
+     * @private
+     */
+    __publicField(this, "_parents", /* @__PURE__ */ new Map());
   }
   /**
    * 获取当前节点值。
@@ -21,8 +40,8 @@ class Reactivity {
    * 如果当前没有活动的响应式节点，或者不应该跟踪依赖，则不会建立依赖关系。
    */
   track() {
-    if (!Reactivity.activeReactivity || !_shouldTrack) return;
-    const parent = Reactivity.activeReactivity;
+    if (!_Reactivity.activeReactivity || !_shouldTrack) return;
+    const parent = _Reactivity.activeReactivity;
     if (parent) {
       this._parents.set(parent, parent._version);
     }
@@ -47,7 +66,17 @@ class Reactivity {
     });
     this._parents.clear();
   }
-}
+};
+/**
+ * 当前正在执行的反应式节点。
+ *
+ * 用于在依赖收集过程中标识当前正在执行的节点。
+ * 当其他节点访问此节点的值时，会将其作为父节点。
+ *
+ * @internal
+ */
+__publicField(_Reactivity, "activeReactivity");
+let Reactivity = _Reactivity;
 function forceTrack(fn) {
   const preShouldTrack = _shouldTrack;
   _shouldTrack = true;
@@ -65,15 +94,13 @@ function noTrack(fn) {
 let _shouldTrack = true;
 function batch(dep, isRunning) {
   if (isRunning) {
-    const index = _isRunedDeps.indexOf(dep);
-    if (index !== -1) {
-      console.warn("dep already in _isRunedDeps");
+    if (_isRunedDeps.indexOf(dep) !== -1) {
+      return;
     }
     _isRunedDeps.push(dep);
   } else {
-    const index = _needEffectDeps.indexOf(dep);
-    if (index !== -1) {
-      console.warn("dep already in _needEffectDeps，存在多重依赖问题。可能是由于副作用中多次修改了同一个响应式对象。");
+    if (_needEffectDeps.indexOf(dep) !== -1) {
+      return;
     }
     _needEffectDeps.push(dep);
   }
@@ -86,6 +113,7 @@ function batchRun(fn) {
   }
   if (_isRunedDeps.length > 0) {
     _isRunedDeps.forEach((dep) => {
+      __DEV__ && console.assert(dep._isDirty === false, "dep.dirty === false");
       dep._children.forEach((version, node) => {
         node._parents.set(dep, dep._version);
       });
@@ -118,10 +146,48 @@ class ComputedReactivity extends Reactivity {
    */
   constructor(func) {
     super();
-    this.__v_isRef = true;
-    this._children = /* @__PURE__ */ new Map();
-    this._isDirty = true;
-    this._version = -1;
+    /**
+     * 标识这是一个 ref 对象。
+     *
+     * @internal
+     */
+    __publicField(this, "__v_isRef", true);
+    /**
+     * 计算函数。
+     *
+     * 用于计算属性值的函数，可以访问其他响应式数据。
+     * 当依赖发生变化时，会重新执行此函数。
+     */
+    __publicField(this, "_func");
+    /**
+     * 失效子节点集合。
+     *
+     * 记录所有依赖此计算属性的子节点。
+     * 当计算属性重新计算时，会通知这些子节点。
+     *
+     * @private
+     */
+    __publicField(this, "_children", /* @__PURE__ */ new Map());
+    /**
+     * 脏标记。
+     *
+     * 表示计算属性是否需要重新计算。
+     * 当依赖发生变化时，会设置此标记。
+     * 重新计算后会清除此标记。
+     *
+     * @private
+     */
+    __publicField(this, "_isDirty", true);
+    /**
+     * 版本号。
+     *
+     * 每次重新计算后自动递增。
+     * 用于判断子节点中的父节点引用是否过期。
+     * 当子节点发现父节点的版本号不匹配时，会重新建立依赖关系。
+     *
+     * @private
+     */
+    __publicField(this, "_version", -1);
     this._func = func;
   }
   /**
@@ -246,9 +312,9 @@ var TriggerOpTypes = /* @__PURE__ */ ((TriggerOpTypes2) => {
   TriggerOpTypes2["CLEAR"] = "clear";
   return TriggerOpTypes2;
 })(TriggerOpTypes || {});
-const ITERATE_KEY = Symbol("");
-const MAP_KEY_ITERATE_KEY = Symbol("");
-const ARRAY_ITERATE_KEY = Symbol("");
+const ITERATE_KEY = Symbol(__DEV__ ? "Object iterate" : "");
+const MAP_KEY_ITERATE_KEY = Symbol(__DEV__ ? "Map keys iterate" : "");
+const ARRAY_ITERATE_KEY = Symbol(__DEV__ ? "Array iterate" : "");
 globalThis.__DEV__ ?? (globalThis.__DEV__ = true);
 const isObject = (val) => val !== null && typeof val === "object";
 const isArray = Array.isArray;
@@ -285,6 +351,9 @@ function toRaw(observed) {
   const raw = observed && observed[ReactiveFlags.RAW];
   return raw ? toRaw(raw) : observed;
 }
+function warn(msg, ...args) {
+  console.warn(`[警告] ${msg}`, ...args);
+}
 // @__NO_SIDE_EFFECTS__
 function makeMap(str) {
   const map = /* @__PURE__ */ Object.create(null);
@@ -298,12 +367,50 @@ class EffectScope {
    * @param detached 是否创建分离的作用域
    */
   constructor(detached = false) {
+    /**
+     * 作用域是否处于活动状态
+     * @internal
+     */
+    __publicField(this, "_active", true);
+    /**
+     * 跟踪 on 方法的调用次数，允许多次调用 on 方法
+     * @internal
+     */
+    __publicField(this, "_on", 0);
+    /**
+     * 存储当前作用域中的所有效果
+     * @internal
+     */
+    __publicField(this, "effects", []);
+    /**
+     * 存储清理函数
+     * @internal
+     */
+    __publicField(this, "cleanups", []);
+    /**
+     * 作用域是否被暂停
+     */
+    __publicField(this, "_isPaused", false);
+    /**
+     * 父作用域，仅由非分离的作用域分配
+     * @internal
+     */
+    __publicField(this, "parent");
+    /**
+     * 记录未分离的子作用域
+     * @internal
+     */
+    __publicField(this, "scopes");
+    /**
+     * 在父作用域的 scopes 数组中记录子作用域的索引，用于优化移除操作
+     * @internal
+     */
+    __publicField(this, "index");
+    /**
+     * 前一个作用域
+     */
+    __publicField(this, "prevScope");
     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(
@@ -371,6 +478,8 @@ class EffectScope {
       } finally {
         activeEffectScope = currentEffectScope;
       }
+    } else if (__DEV__) {
+      warn(`无法运行已停用的 effect 作用域。`);
     }
   }
   /**
@@ -439,6 +548,10 @@ function getCurrentScope() {
 function onScopeDispose(fn, failSilently = false) {
   if (activeEffectScope) {
     activeEffectScope.cleanups.push(fn);
+  } else if (__DEV__ && !failSilently) {
+    warn(
+      `onScopeDispose() 在没有活动的 effect 作用域时被调用，无法关联。`
+    );
   }
 }
 function effect(fn) {
@@ -447,7 +560,12 @@ function effect(fn) {
 const _EffectReactivity = class _EffectReactivity extends ComputedReactivity {
   constructor(func) {
     super(func);
-    this._isEnable = true;
+    /**
+     * 是否为启用, 默认为 true。
+     *
+     * 启用时，会立即执行函数。
+     */
+    __publicField(this, "_isEnable", true);
     if (activeEffectScope && activeEffectScope.active) {
       activeEffectScope.effects.push(this);
     }
@@ -511,7 +629,7 @@ const _EffectReactivity = class _EffectReactivity extends ComputedReactivity {
     }
   }
 };
-_EffectReactivity.pausedQueueEffects = /* @__PURE__ */ new WeakSet();
+__publicField(_EffectReactivity, "pausedQueueEffects", /* @__PURE__ */ new WeakSet());
 let EffectReactivity = _EffectReactivity;
 function property(target, key) {
   let depsMap = PropertyReactivity._targetMap.get(target);
@@ -526,7 +644,21 @@ function property(target, key) {
   }
   return dep;
 }
-const _PropertyReactivity = class _PropertyReactivity extends Reactivity {
+class PropertyReactivity extends Reactivity {
+  constructor(target, key) {
+    super();
+    __publicField(this, "_target");
+    __publicField(this, "_key");
+    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];
+    }
+  }
   /**
    * 获取当前节点值。
    *
@@ -546,18 +678,6 @@ const _PropertyReactivity = class _PropertyReactivity extends Reactivity {
     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() {
   }
   /**
@@ -641,9 +761,11 @@ const _PropertyReactivity = class _PropertyReactivity extends Reactivity {
       }
     });
   }
-};
-_PropertyReactivity._targetMap = /* @__PURE__ */ new WeakMap();
-let PropertyReactivity = _PropertyReactivity;
+}
+/**
+ * @private
+ */
+__publicField(PropertyReactivity, "_targetMap", /* @__PURE__ */ new WeakMap());
 const arrayInstrumentations = {
   __proto__: null,
   /**
@@ -1124,7 +1246,6 @@ function noTracking(self, method, args = []) {
   );
   return res;
 }
-var _a, _b;
 function ref(value) {
   if (isRef(value)) {
     return value;
@@ -1142,7 +1263,21 @@ class RefReactivity extends (_b = Reactivity, _a = ReactiveFlags.IS_REF, _b) {
    */
   constructor(value) {
     super();
-    this[_a] = true;
+    /**
+     * 标识这是一个 ref 对象。
+     *
+     * 用于 isRef 函数判断对象是否为引用。
+     */
+    __publicField(this, _a, true);
+    /**
+     * 原始值。
+     *
+     * 存储未经响应式处理的原始值。
+     * 用于比较值是否发生变化。
+     *
+     * @private
+     */
+    __publicField(this, "_rawValue");
     this._rawValue = toRaw(value);
     this._value = toReactive(value);
   }
@@ -1263,6 +1398,7 @@ class MutableReactiveHandler extends BaseReactiveHandler {
       value,
       isRef(target) ? target : receiver
     );
+    __DEV__ && console.assert(target === toRaw(receiver));
     if (target === toRaw(receiver)) {
       if (!hadKey) {
         PropertyReactivity.trigger(target, TriggerOpTypes.ADD, key, value);
@@ -1489,6 +1625,8 @@ function createInstrumentations() {
       if (!hadKey) {
         key = toRaw(key);
         hadKey = has.call(target, key);
+      } else if (__DEV__) {
+        checkIdentityKeys(target, has, key);
       }
       const oldValue = get.call(target, key);
       target.set(key, value);
@@ -1516,6 +1654,8 @@ function createInstrumentations() {
       if (!hadKey) {
         key = toRaw(key);
         hadKey = has.call(target, key);
+      } else if (__DEV__) {
+        checkIdentityKeys(target, has, key);
       }
       const oldValue = get ? get.call(target, key) : void 0;
       const result = target.delete(key);
@@ -1537,7 +1677,7 @@ function createInstrumentations() {
     clear() {
       const target = toRaw(this);
       const hadItems = target.size !== 0;
-      const oldTarget = void 0;
+      const oldTarget = __DEV__ ? isMap(target) ? new Map(target) : new Set(target) : void 0;
       const result = target.clear();
       if (hadItems) {
         PropertyReactivity.trigger(
@@ -1592,6 +1732,15 @@ function createIterableMethod(method) {
     };
   };
 }
+function checkIdentityKeys(target, has, key) {
+  const rawKey = toRaw(key);
+  if (rawKey !== key && has.call(target, rawKey)) {
+    const type = toRawType(target);
+    warn(
+      `响应式 ${type} 同时包含同一对象的原始版本和响应式版本${type === `Map` ? `作为键` : ``}，这可能导致不一致。建议仅使用响应式版本。`
+    );
+  }
+}
 const getProto = (v) => Reflect.getPrototypeOf(v);
 function reactive(target) {
   if (!isObject(target)) {
@@ -1630,8 +1779,21 @@ function isProxy(value) {
 }
 class ReactiveObject {
   constructor() {
-    this._effectScope = new EffectScope();
-    this._destroyCallbacks = [];
+    /**
+     * 副作用作用域
+     *
+     * 用于管理所有副作用的生命周期：
+     * - 收集所有通过 effect() 方法创建的副作用
+     * - 在类销毁时自动停止所有副作用
+     * - 防止副作用在类销毁后继续执行，避免内存泄漏
+     *
+     * 私有属性，外部无法直接访问，只能通过 effect() 方法使用
+     */
+    __publicField(this, "_effectScope", new EffectScope());
+    /**
+     * 销毁时需要执行的函数
+     */
+    __publicField(this, "_destroyCallbacks", []);
   }
   /**
    * 创建并运行副作用