@feng3d/reactivity 1.0.8 → 1.0.11

package/dist/index.umd.cjs

@@ -1,10 +1,29 @@
 (function(global, factory) {
   typeof exports === "object" && typeof module !== "undefined" ? factory(exports) : typeof define === "function" && define.amd ? define(["exports"], factory) : (global = typeof globalThis !== "undefined" ? globalThis : global || self, factory(global.feng3d = {}));
 })(this, (function(exports2) {
-  "use strict";
-  class Reactivity {
+  "use strict";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());
     }
     /**
      * 获取当前节点值。
@@ -25,8 +44,8 @@
      * 如果当前没有活动的响应式节点，或者不应该跟踪依赖，则不会建立依赖关系。
      */
     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);
       }
@@ -51,7 +70,17 @@
       });
       this._parents.clear();
     }
-  }
+  };
+  /**
+   * 当前正在执行的反应式节点。
+   *
+   * 用于在依赖收集过程中标识当前正在执行的节点。
+   * 当其他节点访问此节点的值时，会将其作为父节点。
+   *
+   * @internal
+   */
+  __publicField(_Reactivity, "activeReactivity");
+  let Reactivity = _Reactivity;
   function forceTrack(fn) {
     const preShouldTrack = _shouldTrack;
     _shouldTrack = true;
@@ -69,15 +98,13 @@
   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);
     }
@@ -90,6 +117,7 @@
     }
     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);
         });
@@ -122,10 +150,48 @@
      */
     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;
     }
     /**
@@ -250,9 +316,9 @@
     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;
@@ -289,6 +355,9 @@
     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);
@@ -302,12 +371,50 @@
      * @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(
@@ -375,6 +482,8 @@
         } finally {
           activeEffectScope = currentEffectScope;
         }
+      } else if (__DEV__) {
+        warn(`无法运行已停用的 effect 作用域。`);
       }
     }
     /**
@@ -443,6 +552,10 @@
   function onScopeDispose(fn, failSilently = false) {
     if (activeEffectScope) {
       activeEffectScope.cleanups.push(fn);
+    } else if (__DEV__ && !failSilently) {
+      warn(
+        `onScopeDispose() 在没有活动的 effect 作用域时被调用，无法关联。`
+      );
     }
   }
   function effect(fn) {
@@ -451,7 +564,12 @@
   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);
       }
@@ -515,7 +633,7 @@
       }
     }
   };
-  _EffectReactivity.pausedQueueEffects = /* @__PURE__ */ new WeakSet();
+  __publicField(_EffectReactivity, "pausedQueueEffects", /* @__PURE__ */ new WeakSet());
   let EffectReactivity = _EffectReactivity;
   function property(target, key) {
     let depsMap = PropertyReactivity._targetMap.get(target);
@@ -530,7 +648,21 @@
     }
     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];
+      }
+    }
     /**
      * 获取当前节点值。
      *
@@ -550,18 +682,6 @@
       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() {
     }
     /**
@@ -645,9 +765,11 @@
         }
       });
     }
-  };
-  _PropertyReactivity._targetMap = /* @__PURE__ */ new WeakMap();
-  let PropertyReactivity = _PropertyReactivity;
+  }
+  /**
+   * @private
+   */
+  __publicField(PropertyReactivity, "_targetMap", /* @__PURE__ */ new WeakMap());
   const arrayInstrumentations = {
     __proto__: null,
     /**
@@ -1128,7 +1250,6 @@
     );
     return res;
   }
-  var _a, _b;
   function ref(value) {
     if (isRef(value)) {
       return value;
@@ -1146,7 +1267,21 @@
      */
     constructor(value) {
       super();
-      this[_a] = true;
+      /**
+       * 标识这是一个 ref 对象。
+       *
+       * 用于 isRef 函数判断对象是否为引用。
+       */
+      __publicField(this, _a, true);
+      /**
+       * 原始值。
+       *
+       * 存储未经响应式处理的原始值。
+       * 用于比较值是否发生变化。
+       *
+       * @private
+       */
+      __publicField(this, "_rawValue");
       this._rawValue = toRaw(value);
       this._value = toReactive(value);
     }
@@ -1267,6 +1402,7 @@
         value,
         isRef(target) ? target : receiver
       );
+      __DEV__ && console.assert(target === toRaw(receiver));
       if (target === toRaw(receiver)) {
         if (!hadKey) {
           PropertyReactivity.trigger(target, TriggerOpTypes.ADD, key, value);
@@ -1493,6 +1629,8 @@
         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);
@@ -1520,6 +1658,8 @@
         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);
@@ -1541,7 +1681,7 @@
       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(
@@ -1596,6 +1736,15 @@
       };
     };
   }
+  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)) {
@@ -1634,8 +1783,21 @@
   }
   class ReactiveObject {
     constructor() {
-      this._effectScope = new EffectScope();
-      this._destroyCallbacks = [];
+      /**
+       * 副作用作用域
+       *
+       * 用于管理所有副作用的生命周期：
+       * - 收集所有通过 effect() 方法创建的副作用
+       * - 在类销毁时自动停止所有副作用
+       * - 防止副作用在类销毁后继续执行，避免内存泄漏
+       *
+       * 私有属性，外部无法直接访问，只能通过 effect() 方法使用
+       */
+      __publicField(this, "_effectScope", new EffectScope());
+      /**
+       * 销毁时需要执行的函数
+       */
+      __publicField(this, "_destroyCallbacks", []);
     }
     /**
      * 创建并运行副作用