@feng3d/reactivity 1.0.7 → 1.0.8

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,CA0BvE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CA+C1C"}

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,69 +1,69 @@
-{
-  "name": "@feng3d/reactivity",
-  "type": "module",
-  "version": "1.0.7",
-  "description": "反应式，主要用于feng3d中的数据驱动。",
-  "homepage": "https://feng3d.com/reactivity",
-  "main": "./dist/index.umd.cjs",
-  "types": "./lib/index.d.ts",
-  "module": "./dist/index.js",
-  "author": "feng",
-  "license": "MIT",
-  "exports": {
-    ".": {
-      "types": "./lib/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.umd.cjs"
-    }
-  },
-  "scripts": {
-    "dev": "cd examples && npm run dev",
-    "clean": "rimraf \"{lib,dist,public}\"",
-    "build": "vite build",
-    "test": "vitest",
-    "types": "tsc",
-    "watch": "tsc -w",
-    "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",
-    "prepublishOnly": "node scripts/prepublish.js",
-    "postpublish": "node scripts/postpublish.js"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/feng3d-labs/reactivity.git"
-  },
-  "workspaces": [
-    ".",
-    "./examples"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "files": [
-    "dist/",
-    "lib",
-    "src",
-    "readme",
-    "tsconfig.json"
-  ],
-  "devDependencies": {
-    "@eslint/js": "^9.0.0",
-    "@feng3d/cli": "^0.0.19",
-    "@types/node": "^22.15.19",
-    "@typescript-eslint/eslint-plugin": "8.32.1",
-    "@typescript-eslint/parser": "8.32.1",
-    "cross-env": "7.0.3",
-    "eslint": "9.26.0",
-    "globals": "^14.0.0",
-    "rimraf": "6.0.1",
-    "tslib": "^2.8.1",
-    "typedoc": "^0.28.4",
-    "typescript": "5.8.3",
-    "typescript-eslint": "^8.32.1",
-    "vite": "^6.3.5",
-    "vitest": "^3.1.3"
-  }
-}
+{
+  "name": "@feng3d/reactivity",
+  "type": "module",
+  "version": "1.0.8",
+  "description": "反应式，主要用于feng3d中的数据驱动。",
+  "homepage": "https://feng3d.com/reactivity",
+  "main": "./dist/index.umd.cjs",
+  "types": "./lib/index.d.ts",
+  "module": "./dist/index.js",
+  "author": "feng",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.umd.cjs"
+    }
+  },
+  "scripts": {
+    "dev": "cd examples && npm run dev",
+    "clean": "rimraf \"{lib,dist,public}\"",
+    "build": "vite build",
+    "test": "vitest",
+    "types": "tsc",
+    "watch": "tsc -w",
+    "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 version patch && npm run clean && npm run lint && npm run build && npm run docs && npm run types && npm publish",
+    "prepublishOnly": "node scripts/prepublish.js",
+    "postpublish": "node scripts/postpublish.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/feng3d-labs/reactivity.git"
+  },
+  "workspaces": [
+    ".",
+    "./examples"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/",
+    "lib",
+    "src",
+    "readme",
+    "tsconfig.json"
+  ],
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@feng3d/cli": "^0.0.19",
+    "@types/node": "^22.15.19",
+    "@typescript-eslint/eslint-plugin": "8.32.1",
+    "@typescript-eslint/parser": "8.32.1",
+    "cross-env": "7.0.3",
+    "eslint": "9.26.0",
+    "globals": "^14.0.0",
+    "rimraf": "6.0.1",
+    "tslib": "^2.8.1",
+    "typedoc": "^0.28.4",
+    "typescript": "5.8.3",
+    "typescript-eslint": "^8.32.1",
+    "vite": "^6.3.5",
+    "vitest": "^3.1.3"
+  }
+}

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;
+    }
+}