@feng3d/reactivity 1.0.7 → 1.0.9

package/lib/ReactiveObject.d.ts

@@ -0,0 +1,101 @@
+import { Effect } from '@feng3d/reactivity';
+/**
+ * 响应式类基类
+ *
+ * 提供响应式编程的基础功能，包括：
+ * 1. 提供副作用管理机制，自动管理副作用的生命周期
+ * 2. 在类销毁时自动清理所有副作用，防止内存泄漏
+ *
+ * 使用方式：
+ * ```typescript
+ * class MyClass extends ReactiveObject {
+ *   constructor() {
+ *     super();
+ *
+ *     // 创建副作用，会自动管理生命周期
+ *     this.effect(() => {
+ *       ...
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export declare class ReactiveObject {
+    constructor();
+    /**
+     * 副作用作用域
+     *
+     * 用于管理所有副作用的生命周期：
+     * - 收集所有通过 effect() 方法创建的副作用
+     * - 在类销毁时自动停止所有副作用
+     * - 防止副作用在类销毁后继续执行，避免内存泄漏
+     *
+     * 私有属性，外部无法直接访问，只能通过 effect() 方法使用
+     */
+    private _effectScope;
+    /**
+     * 销毁时需要执行的函数
+     */
+    private _destroyCallbacks;
+    /**
+     * 创建并运行副作用
+     *
+     * 功能：
+     * 1. 将传入的函数包装为副作用
+     * 2. 自动收集副作用中访问的响应式属性作为依赖
+     * 3. 当依赖变化时自动重新执行副作用
+     * 4. 在类销毁时自动停止副作用
+     *
+     * 使用场景：
+     * - 监听属性变化并执行相应操作
+     * - 自动更新UI或重新计算派生状态
+     * - 执行清理或初始化逻辑
+     *
+     * @param fn 副作用函数，会在依赖变化时自动执行
+     *
+     * 使用示例：
+     * ```typescript
+     * this.effect(() => {
+     *   // 访问响应式属性，建立依赖关系
+     *   const value = reactive(this).someProperty;
+     *
+     *   // 执行相应的逻辑
+     *   this.updateUI(value);
+     * });
+     * ```
+     */
+    effect(fn: () => void): Effect;
+    /**
+     * 销毁时执行的函数
+     * @param callback 销毁时执行的函数
+     */
+    destroyCall(callback: () => void): void;
+    /**
+     * 销毁响应式类实例
+     *
+     * 执行清理操作：
+     * 1. 执行所有注册的清理函数
+     * 2. 停止所有副作用作用域，防止副作用继续执行
+     * 3. 清理引用，帮助垃圾回收，防止内存泄漏
+     *
+     * 重要：
+     * - 子类重写此方法时必须调用 super.destroy()
+     * - 确保在类实例不再使用时调用此方法
+     * - 调用后实例将无法再使用 effect() 方法
+     *
+     * 使用示例：
+     * ```typescript
+     * class MyClass extends ReactiveObject {
+     *   destroy() {
+     *     // 执行子类特定的清理逻辑
+     *     this.cleanup();
+     *
+     *     // 必须调用父类的destroy方法
+     *     super.destroy();
+     *   }
+     * }
+     * ```
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=ReactiveObject.d.ts.map

package/lib/ReactiveObject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReactiveObject.d.ts","sourceRoot":"","sources":["../src/ReactiveObject.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAuB,MAAM,oBAAoB,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,cAAc;;IAMvB;;;;;;;;;OASG;IACH,OAAO,CAAC,YAAY,CAAqB;IAEzC;;OAEG;IACH,OAAO,CAAC,iBAAiB,CAAsB;IAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,IAAI;IAYrB;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,IAAI;IAKhC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,OAAO;CAUV"}

package/lib/batch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../src/batch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGhD;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,kBAAkB,EAAE,SAAS,EAAE,OAAO,GAAG,IAAI,CAUvE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CA+C1C"}
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../src/batch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGhD;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,kBAAkB,EAAE,SAAS,EAAE,OAAO,GAAG,IAAI,CAsBvE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CA+C1C"}

package/lib/effectScope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"effectScope.d.ts","sourceRoot":"","sources":["../src/effectScope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,cAAc,EAAE,MAAM,UAAU,CAAC;AAGzD;;GAEG;AACH,eAAO,IAAI,iBAAiB,EAAE,WAAW,GAAG,SAAS,CAAC;AAEtD;;;;GAIG;AACH,qBAAa,WAAW;IAgDD,QAAQ;IA9C3B;;;OAGG;IACH,OAAO,CAAC,OAAO,CAAQ;IACvB;;;OAGG;IACH,OAAO,CAAC,GAAG,CAAK;IAChB;;;OAGG;IACH,OAAO,EAAE,cAAc,EAAE,CAAM;IAC/B;;;OAGG;IACH,QAAQ,EAAE,CAAC,MAAM,IAAI,CAAC,EAAE,CAAM;IAE9B;;OAEG;IACH,OAAO,CAAC,SAAS,CAAS;IAE1B;;;OAGG;IACH,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC;;;OAGG;IACH,MAAM,EAAE,WAAW,EAAE,GAAG,SAAS,CAAC;IAClC;;;OAGG;IACH,OAAO,CAAC,KAAK,CAAqB;IAElC;;;OAGG;gBACgB,QAAQ,UAAQ;IAYnC;;OAEG;IACH,IAAI,MAAM,IAAI,OAAO,CAGpB;IAED;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAqBb;;;;OAIG;IACH,MAAM,IAAI,IAAI;IAwBd;;;;OAIG;IACH,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,SAAS;IAuBlC;;OAEG;IACH,SAAS,EAAE,WAAW,GAAG,SAAS,CAAC;IACnC;;;;OAIG;IACH,EAAE,IAAI,IAAI;IASV;;;;OAIG;IACH,GAAG,IAAI,IAAI;IASX;;;;;OAKG;IACH,IAAI,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,IAAI;CA2CnC;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,WAAW,CAG3D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,WAAW,GAAG,SAAS,CAGzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,YAAY,UAAQ,GAAG,IAAI,CAazE"}
+{"version":3,"file":"effectScope.d.ts","sourceRoot":"","sources":["../src/effectScope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,cAAc,EAAE,MAAM,UAAU,CAAC;AAGzD;;GAEG;AACH,eAAO,IAAI,iBAAiB,EAAE,WAAW,GAAG,SAAS,CAAC;AAEtD;;;;GAIG;AACH,qBAAa,WAAW;IAgDD,QAAQ;IA9C3B;;;OAGG;IACH,OAAO,CAAC,OAAO,CAAQ;IACvB;;;OAGG;IACH,OAAO,CAAC,GAAG,CAAK;IAChB;;;OAGG;IACH,OAAO,EAAE,cAAc,EAAE,CAAM;IAC/B;;;OAGG;IACH,QAAQ,EAAE,CAAC,MAAM,IAAI,CAAC,EAAE,CAAM;IAE9B;;OAEG;IACH,OAAO,CAAC,SAAS,CAAS;IAE1B;;;OAGG;IACH,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC;;;OAGG;IACH,MAAM,EAAE,WAAW,EAAE,GAAG,SAAS,CAAC;IAClC;;;OAGG;IACH,OAAO,CAAC,KAAK,CAAqB;IAElC;;;OAGG;gBACgB,QAAQ,UAAQ;IAYnC;;OAEG;IACH,IAAI,MAAM,IAAI,OAAO,CAGpB;IAED;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAqBb;;;;OAIG;IACH,MAAM,IAAI,IAAI;IAwBd;;;;OAIG;IACH,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,SAAS;IAuBlC;;OAEG;IACH,SAAS,EAAE,WAAW,GAAG,SAAS,CAAC;IACnC;;;;OAIG;IACH,EAAE,IAAI,IAAI;IASV;;;;OAIG;IACH,GAAG,IAAI,IAAI;IASX;;;;;OAKG;IACH,IAAI,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,IAAI;CA2CnC;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,WAAW,CAG3D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,WAAW,GAAG,SAAS,CAGzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,YAAY,UAAQ,GAAG,IAAI,CAYzE"}

package/lib/index.d.ts

@@ -3,6 +3,7 @@ export { computed, type Computed } from './computed';
 export { effect, type Effect } from './effect';
 export { effectScope, EffectScope, getCurrentScope, onScopeDispose } from './effectScope';
 export { isProxy, isReactive, reactive, type Reactive, type UnReadonly } from './reactive';
+export { ReactiveObject } from './ReactiveObject';
 export { forceTrack, noTrack } from './Reactivity';
 export { isRef, ref, type Ref } from './ref';
 export { toRaw } from './shared/general';

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC1F,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,QAAQ,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC3F,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,GAAG,EAAE,MAAM,OAAO,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC1F,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,QAAQ,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC3F,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,GAAG,EAAE,MAAM,OAAO,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC"}

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@feng3d/reactivity",
-  "type": "module",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "反应式，主要用于feng3d中的数据驱动。",
   "homepage": "https://feng3d.com/reactivity",
+  "author": "feng",
+  "license": "MIT",
+  "type": "module",
   "main": "./dist/index.umd.cjs",
   "types": "./lib/index.d.ts",
   "module": "./dist/index.js",
-  "author": "feng",
-  "license": "MIT",
   "exports": {
     ".": {
       "types": "./lib/index.d.ts",
@@ -17,28 +17,24 @@
     }
   },
   "scripts": {
-    "dev": "cd examples && npm run dev",
-    "clean": "rimraf \"{lib,dist,public}\"",
-    "build": "vite build",
-    "test": "vitest",
-    "types": "tsc",
-    "watch": "tsc -w",
+    "examples:dev": "cd examples && npm run dev",
+    "postdocs": "node scripts/postdocs.js && cd examples && vite build --outDir ../public",
+    "clean": "rimraf lib dist public",
+    "build": "vite build && tsc",
+    "watch": "concurrently \"vite build --watch\" \"tsc -w\" \"vitest\"",
+    "test": "vitest run",
     "lint": "eslint . --ext .js,.ts --max-warnings 0",
     "lintfix": "npm run lint -- --fix",
-    "docs": "typedoc && cd examples && vite build --outDir ../public",
-    "upload_oss": "npm run docs && feng3d-cli oss_upload_dir",
-    "release": "npm run clean && npm run lint && npm run build && npm run docs && npm run types && npm publish",
+    "docs": "typedoc",
     "prepublishOnly": "node scripts/prepublish.js",
-    "postpublish": "node scripts/postpublish.js"
+    "release": "npm run clean && npm run lint && npm test && npm run build && npm run docs && npm publish",
+    "postpublish": "node scripts/postpublish.js",
+    "prepare": "husky"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/feng3d-labs/reactivity.git"
   },
-  "workspaces": [
-    ".",
-    "./examples"
-  ],
   "publishConfig": {
     "access": "public"
   },
@@ -64,6 +60,18 @@
     "typescript": "5.8.3",
     "typescript-eslint": "^8.32.1",
     "vite": "^6.3.5",
-    "vitest": "^3.1.3"
-  }
+    "vitest": "^3.1.3",
+    "concurrently": "^9.1.2",
+    "husky": "^9.1.7",
+    "lint-staged": "^15.2.10"
+  },
+  "lint-staged": {
+    "*.{js,ts}": [
+      "eslint --fix --max-warnings 0"
+    ]
+  },
+  "workspaces": [
+    ".",
+    "./examples"
+  ]
 }

package/src/ReactiveObject.ts

@@ -0,0 +1,131 @@
+import { Effect, effect, EffectScope } from '@feng3d/reactivity';
+
+/**
+ * 响应式类基类
+ *
+ * 提供响应式编程的基础功能，包括：
+ * 1. 提供副作用管理机制，自动管理副作用的生命周期
+ * 2. 在类销毁时自动清理所有副作用，防止内存泄漏
+ *
+ * 使用方式：
+ * ```typescript
+ * class MyClass extends ReactiveObject {
+ *   constructor() {
+ *     super();
+ *
+ *     // 创建副作用，会自动管理生命周期
+ *     this.effect(() => {
+ *       ...
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export class ReactiveObject
+{
+    constructor()
+    {
+    }
+
+    /**
+     * 副作用作用域
+     *
+     * 用于管理所有副作用的生命周期：
+     * - 收集所有通过 effect() 方法创建的副作用
+     * - 在类销毁时自动停止所有副作用
+     * - 防止副作用在类销毁后继续执行，避免内存泄漏
+     *
+     * 私有属性，外部无法直接访问，只能通过 effect() 方法使用
+     */
+    private _effectScope = new EffectScope();
+
+    /**
+     * 销毁时需要执行的函数
+     */
+    private _destroyCallbacks: (() => void)[] = [];
+
+    /**
+     * 创建并运行副作用
+     *
+     * 功能：
+     * 1. 将传入的函数包装为副作用
+     * 2. 自动收集副作用中访问的响应式属性作为依赖
+     * 3. 当依赖变化时自动重新执行副作用
+     * 4. 在类销毁时自动停止副作用
+     *
+     * 使用场景：
+     * - 监听属性变化并执行相应操作
+     * - 自动更新UI或重新计算派生状态
+     * - 执行清理或初始化逻辑
+     *
+     * @param fn 副作用函数，会在依赖变化时自动执行
+     *
+     * 使用示例：
+     * ```typescript
+     * this.effect(() => {
+     *   // 访问响应式属性，建立依赖关系
+     *   const value = reactive(this).someProperty;
+     *
+     *   // 执行相应的逻辑
+     *   this.updateUI(value);
+     * });
+     * ```
+     */
+    effect(fn: () => void)
+    {
+        let eff: Effect;
+
+        this._effectScope.run(() =>
+        {
+            eff = effect(fn);
+        });
+
+        return eff;
+    }
+
+    /**
+     * 销毁时执行的函数
+     * @param callback 销毁时执行的函数
+     */
+    destroyCall(callback: () => void)
+    {
+        this._destroyCallbacks.push(callback);
+    }
+
+    /**
+     * 销毁响应式类实例
+     *
+     * 执行清理操作：
+     * 1. 执行所有注册的清理函数
+     * 2. 停止所有副作用作用域，防止副作用继续执行
+     * 3. 清理引用，帮助垃圾回收，防止内存泄漏
+     *
+     * 重要：
+     * - 子类重写此方法时必须调用 super.destroy()
+     * - 确保在类实例不再使用时调用此方法
+     * - 调用后实例将无法再使用 effect() 方法
+     *
+     * 使用示例：
+     * ```typescript
+     * class MyClass extends ReactiveObject {
+     *   destroy() {
+     *     // 执行子类特定的清理逻辑
+     *     this.cleanup();
+     *
+     *     // 必须调用父类的destroy方法
+     *     super.destroy();
+     *   }
+     * }
+     * ```
+     */
+    destroy()
+    {
+        // 执行所有注册的清理函数
+        this._destroyCallbacks?.forEach((item) => item());
+        this._destroyCallbacks = null;
+
+        // 停止副作用作用域，这会自动停止所有通过 effect() 创建的副作用
+        this._effectScope?.stop();
+        this._effectScope = null;
+    }
+}

package/src/batch.ts

@@ -15,10 +15,22 @@ export function batch(dep: ComputedReactivity, isRunning: boolean): void
 {
     if (isRunning)
     {
+        // 如果依赖已经在队列中，直接返回，避免重复添加
+        if (_isRunedDeps.indexOf(dep) !== -1)
+        {
+            return;
+        }
+
         _isRunedDeps.push(dep);
     }
     else
     {
+        // 如果依赖已经在队列中，直接返回，避免重复添加
+        if (_needEffectDeps.indexOf(dep) !== -1)
+        {
+            return;
+        }
+
         _needEffectDeps.push(dep);
     }
 }

package/src/collectionHandlers.ts

@@ -434,10 +434,10 @@ function checkIdentityKeys(
         const type = toRawType(target);
 
         warn(
-            `Reactive ${type} contains both the raw and reactive ` +
-            `versions of the same object${type === `Map` ? ` as keys` : ``}, ` +
-            `which can lead to inconsistencies. ` +
-            `It is recommended to use only the reactive version.`,
+            `响应式 ${type} 同时包含同一对象的原始版本和响应式版本` +
+            `${type === `Map` ? `作为键` : ``}，` +
+            `这可能导致不一致。` +
+            `建议仅使用响应式版本。`,
         );
     }
 }

package/src/effectScope.ts

@@ -158,7 +158,7 @@ export class EffectScope
         }
         else if (__DEV__)
         {
-            warn(`cannot run an inactive effect scope.`);
+            warn(`无法运行已停用的 effect 作用域。`);
         }
     }
 
@@ -287,8 +287,7 @@ export function onScopeDispose(fn: () => void, failSilently = false): void
     else if (__DEV__ && !failSilently)
     {
         warn(
-            `onScopeDispose() is called when there is no active effect scope` +
-            ` to be associated with.`,
+            `onScopeDispose() 在没有活动的 effect 作用域时被调用，无法关联。`,
         );
     }
 }

package/src/index.ts

@@ -3,6 +3,7 @@ export { computed, type Computed } from './computed';
 export { effect, type Effect } from './effect';
 export { effectScope, EffectScope, getCurrentScope, onScopeDispose } from './effectScope';
 export { isProxy, isReactive, reactive, type Reactive, type UnReadonly } from './reactive';
+export { ReactiveObject } from './ReactiveObject';
 export { forceTrack, noTrack } from './Reactivity';
 export { isRef, ref, type Ref } from './ref';
 export { toRaw } from './shared/general';

package/src/shared/general.ts

@@ -86,7 +86,7 @@ export function toRaw<T>(observed: T): T
 
 export function warn(msg: string, ...args: any[]): void
 {
-    console.warn(`[Vue warn] ${msg}`, ...args);
+    console.warn(`[警告] ${msg}`, ...args);
 }
 
 /**