@feng3d/reactivity 1.0.9 → 1.0.12

package/LICENSE

@@ -1,21 +1,15 @@
-MIT License
+MIT 许可证
 
-Copyright (c) 2019 feng
+版权所有 (c) 2026 feng
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+特此授予任何获得本软件及相关文档文件（"软件"）副本的人免费许可，
+可以不受限制地处理本软件，包括但不限于使用、复制、修改、合并、
+发布、分发、再许可和/或销售本软件的副本，并允许向其提供本软件的
+人这样做，但须符合以下条件：
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+上述版权声明和本许可声明应包含在本软件的所有副本或主要部分中。
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+本软件按"原样"提供，不提供任何明示或暗示的保证，包括但不限于对
+适销性、特定用途适用性和非侵权性的保证。在任何情况下，作者或版权
+持有人均不对因本软件或本软件的使用或其他交易而产生的任何索赔、
+损害或其他责任负责，无论是在合同诉讼、侵权诉讼还是其他诉讼中。

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;
@@ -84,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);
       });
@@ -116,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;
   }
   /**
@@ -244,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;
@@ -283,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);
@@ -296,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(
@@ -369,6 +478,8 @@ class EffectScope {
       } finally {
         activeEffectScope = currentEffectScope;
       }
+    } else if (__DEV__) {
+      warn(`无法运行已停用的 effect 作用域。`);
     }
   }
   /**
@@ -437,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) {
@@ -445,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);
     }
@@ -509,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);
@@ -524,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];
+    }
+  }
   /**
    * 获取当前节点值。
    *
@@ -544,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() {
   }
   /**
@@ -639,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,
   /**
@@ -1122,7 +1246,6 @@ function noTracking(self, method, args = []) {
   );
   return res;
 }
-var _a, _b;
 function ref(value) {
   if (isRef(value)) {
     return value;
@@ -1140,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);
   }
@@ -1261,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);
@@ -1487,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);
@@ -1514,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);
@@ -1535,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(
@@ -1590,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)) {
@@ -1628,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", []);
   }
   /**
    * 创建并运行副作用
@@ -1706,6 +1870,7 @@ class ReactiveObject {
     this._effectScope = null;
   }
 }
+console.log("@feng3d/reactivity v1.0.12");
 export {
   EffectScope,
   ReactiveObject,