@feng3d/reactivity 1.0.5 → 1.0.7

package/lib/index.d.ts

@@ -1,8 +1,9 @@
 export { batchRun } from './batch';
-export { ComputedReactivity as ComputedDep, computed, type Computed } from './computed';
-export { Reactivity as Dep, forceTrack, noTrack } from './Reactivity';
-export { EffectReactivity as EffectDep, effect, type Effect } from './effect';
-export { isProxy, isReactive, reactive, type Reactive } from './reactive';
-export { RefReactivity, isRef, ref, type Ref } from './ref';
+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 { forceTrack, noTrack } from './Reactivity';
+export { isRef, ref, type Ref } from './ref';
 export { toRaw } from './shared/general';
 //# sourceMappingURL=index.d.ts.map

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,kBAAkB,IAAI,WAAW,EAAE,QAAQ,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AACxF,OAAO,EAAE,UAAU,IAAI,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,gBAAgB,IAAI,SAAS,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAC9E,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5D,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,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/lib/property.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"property.d.ts","sourceRoot":"","sources":["../src/property.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAuD,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AA8BvH;;GAEG;AACH,qBAAa,kBAAkB,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,CAAE,SAAQ,UAAU,CAAC,CAAC,CAAC;IAEvE;;;;OAIG;IACH,IAAI,KAAK,IAAI,CAAC,CAKb;IACD,IAAI,KAAK,CAAC,CAAC,EANE,CAMF,EAeV;IAED,OAAO,CAAC,OAAO,CAAI;IACnB,OAAO,CAAC,IAAI,CAAI;gBAEJ,MAAM,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC;IAuB7B,gBAAgB;IAKhB;;;;;;;;OAQG;IACH,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,GAAG,EAAE,OAAO,GAAG,IAAI;IASpE;;OAEG;IACH,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,kBAAkB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAiB;IAExF;;;;;;;;;OASG;IACH,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI;CA+FpH"}
+{"version":3,"file":"property.d.ts","sourceRoot":"","sources":["../src/property.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAuD,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAgCvH;;GAEG;AACH,qBAAa,kBAAkB,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,CAAE,SAAQ,UAAU,CAAC,CAAC,CAAC;IAEvE;;;;OAIG;IACH,IAAI,KAAK,IAAI,CAAC,CAKb;IAED,IAAI,KAAK,CAAC,CAAC,EAPE,CAOF,EAeV;IAED,OAAO,CAAC,OAAO,CAAI;IACnB,OAAO,CAAC,IAAI,CAAI;gBAEJ,MAAM,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC;IAuB7B,gBAAgB;IAKhB;;;;;;;;OAQG;IACH,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,GAAG,EAAE,OAAO,GAAG,IAAI;IAUpE;;OAEG;IACH,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,kBAAkB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAiB;IAExF;;;;;;;;;OASG;IACH,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI;CAiGpH"}

package/lib/reactive.d.ts

@@ -3,58 +3,92 @@ import { Ref } from './ref';
 import { Target } from './shared/general';
 /**
  * 移除对象属性中的 readonly 关键字。
+ *
+ * 用于将只读类型转换为可写类型。
  */
-type UnReadonly<T> = {
+export type UnReadonly<T> = {
     -readonly [P in keyof T]: T[P];
 };
 /**
  * 创建或者获取响应式对象的代理对象。
  *
- * @param target 被响应式的对象。
- * @returns 响应式代理对象。
+ * 将普通对象转换为响应式对象，使其属性可以被追踪和更新。
+ *
+ * 特点：
+ * 1. 支持对象和集合类型的响应式转换
+ * 2. 自动处理嵌套对象的响应式转换
+ * 3. 缓存已创建的代理对象
+ * 4. 支持只读属性的响应式转换
  *
  * 注意：
+ * 1. 扩大被反应式的对象的类型范围，只有 `Object.isExtensible` 不通过的对象不被响应化。
+ *    Float32Array 等都允许被响应化。
+ * 2. 被反应式的对象的只读属性也会被标记为可编辑。希望被反应对象属性一般为只读属性，
+ *    通过反应式来改变属性值，同时又通过反应式系统来处理其更改后响应逻辑。
  *
- * 1. 扩大被反应式的对象的类型范围，只有`Object.isExtensible`不通过的对象不被响应化。Float32Array等都允许被响应化。
- * 2. 被反应式的对象的只读属性也会被标记为可编辑。希望被反应对象属性一般为只读属性，通过反应式来改变属性值，同时又通过反应式系统来处理其更改后响应逻辑。
+ * @param target 要转换为响应式的对象
+ * @returns 响应式代理对象
+ */
+export declare function reactive<T extends object>(target: T): Reactive<T>;
+/**
+ * 响应式对象缓存映射。
  *
+ * 用于缓存已创建的响应式代理对象，避免重复创建。
  */
-export declare function reactive<T extends object>(target: T): UnReadonly<Reactive<T>>;
 export declare const reactiveMap: WeakMap<Target, any>;
 /**
  * 判断一个对象是否为响应式对象。
  *
- * @param value 对象。
- * @returns
+ * 通过检查对象是否具有 IS_REACTIVE 标志来判断。
+ *
+ * @param value 要检查的对象
+ * @returns 如果是响应式对象则返回 true，否则返回 false
  */
 export declare function isReactive(value: unknown): boolean;
 /**
  * 转换为响应式对象。
  *
- * @param value 对象。
- * @returns
+ * 如果输入是对象，则将其转换为响应式对象。
+ * 如果输入不是对象，则直接返回。
+ *
+ * @param value 要转换的值
+ * @returns 转换后的响应式对象或原值
  */
 export declare const toReactive: <T>(value: T) => T;
 /**
  * 判断一个对象是否为代理对象。
  *
- * @param value 对象。
- * @returns
+ * 通过检查对象是否具有 RAW 标志来判断。
+ *
+ * @param value 要检查的对象
+ * @returns 如果是代理对象则返回 true，否则返回 false
  */
 export declare function isProxy(value: any): boolean;
-export type Reactive<T> = UnwrapRefSimple<T>;
 /**
- * 原始类型
+ * 响应式类型。
+ *
+ * 表示一个对象的所有属性都是响应式的。
+ */
+export type Reactive<T> = UnReadonly<UnwrapRefSimple<T>>;
+/**
+ * 原始类型。
+ *
+ * 包括：字符串、数字、布尔值、大整数、符号、undefined、null。
  */
 type Primitive = string | number | boolean | bigint | symbol | undefined | null;
 /**
- * 内置类型
+ * 内置类型。
+ *
+ * 包括：原始类型、函数、日期、错误、正则表达式。
  */
 export type Builtin = Primitive | Function | Date | Error | RegExp;
 /**
- * 用于扩展不被 unwrap 的类型。
+ * 用于扩展不被解包的类型。
+ *
+ * 可以通过声明合并来扩展此接口，添加不需要被解包的类型。
  *
- * ``` ts
+ * 示例：
+ * ```ts
  * declare module '@vue/reactivity' {
  *   export interface RefUnwrapBailTypes {
  *     runtimeDOMBailTypes: Node | Window
@@ -66,6 +100,13 @@ export interface RefUnwrapBailTypes {
 }
 /**
  * 解包类型。
+ *
+ * 递归地解包响应式对象的类型，包括：
+ * 1. 内置类型直接返回
+ * 2. Ref 类型解包为内部类型
+ * 3. Computed 类型解包为内部类型
+ * 4. 对象类型递归解包其属性
+ * 5. 其他类型直接返回
  */
 export type UnwrapRefSimple<T> = T extends Builtin | Ref | RefUnwrapBailTypes[keyof RefUnwrapBailTypes] ? T : T extends Ref<infer TT> ? TT : T extends Computed<infer TT> ? TT : T extends object ? {
     [K in keyof T]: UnwrapRefSimple<T[K]>;

package/lib/reactive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reactive.d.ts","sourceRoot":"","sources":["../src/reactive.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAE5B,OAAO,EAA2B,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAEnE;;GAEG;AACH,KAAK,UAAU,CAAC,CAAC,IAAI;IACjB,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACjC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAiC7E;AACD,eAAO,MAAM,WAAW,sBAA6B,CAAC;AAEtD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGlD;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,oBAQtB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAG3C;AAED,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,eAAe,CAAC,CAAC,CAAC,CAAC;AAE7C;;GAEG;AACH,KAAK,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;AAChF;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,IAAI,GAAG,KAAK,GAAG,MAAM,CAAC;AAEnE;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;CAAI;AAEvC;;GAEG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IACzB,CAAC,SACC,OAAO,GACP,GAAG,GACH,kBAAkB,CAAC,MAAM,kBAAkB,CAAC,GAC5C,CAAC,GACH,CAAC,SAAS,GAAG,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,GAC5B,CAAC,SAAS,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,GACjC,CAAC,SAAS,MAAM,GAAG;KACd,CAAC,IAAI,MAAM,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACxC,GACD,CAAC,CAAC"}
+{"version":3,"file":"reactive.d.ts","sourceRoot":"","sources":["../src/reactive.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAE5B,OAAO,EAA2B,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAEnE;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI;IACxB,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACjC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAqCjE;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,sBAA6B,CAAC;AAEtD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGlD;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG,CAQxC,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAG3C;AAED;;;;GAIG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,UAAU,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;AAEzD;;;;GAIG;AACH,KAAK,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;AAEhF;;;;GAIG;AACH,MAAM,MAAM,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,IAAI,GAAG,KAAK,GAAG,MAAM,CAAC;AAEnE;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,kBAAkB;CAAI;AAEvC;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IACzB,CAAC,SACC,OAAO,GACP,GAAG,GACH,kBAAkB,CAAC,MAAM,kBAAkB,CAAC,GAC5C,CAAC,GACH,CAAC,SAAS,GAAG,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,GAC5B,CAAC,SAAS,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,GACjC,CAAC,SAAS,MAAM,GAAG;KACd,CAAC,IAAI,MAAM,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACxC,GACD,CAAC,CAAC"}

package/lib/ref.d.ts

@@ -3,34 +3,96 @@ import { ReactiveFlags } from './shared/constants';
 /**
  * 创建一个引用，该引用的值可以被响应式系统追踪和更新。
  *
- * @param value 引用的值。
- * @returns 包含 value 属性的对象，用于获取和设置引用的值。
+ * ref 是响应式系统中最基本的响应式对象。
+ * 它可以包装任何类型的值，使其成为响应式的。
+ *
+ * 特点：
+ * 1. 可以包装任何类型的值
+ * 2. 通过 .value 访问和修改值
+ * 3. 自动解包原始值
+ * 4. 支持嵌套的响应式对象
+ *
+ * @param value 要包装的值
+ * @returns 包含 value 属性的响应式引用对象
  */
 export declare function ref<T>(value?: T): Ref<T>;
 /**
  * 判断一个对象是否为引用。
- * @param r 引用。
+ *
+ * 通过检查对象是否具有 IS_REF 标志来判断。
+ *
+ * @param r 要检查的对象
+ * @returns 如果是引用则返回 true，否则返回 false
  */
 export declare function isRef<T>(r: Ref<T> | unknown): r is Ref<T>;
+/**
+ * 引用反应式节点接口。
+ *
+ * 继承自 Ref 接口，表示这是一个引用反应式节点。
+ */
 export interface RefReactivity<T = any> extends Ref<T> {
 }
 /**
- * 引用反应式节点。
+ * 引用反应式节点类。
  *
  * 当使用 ref 函数时，会创建一个 RefReactivity 对象。
+ * 实现了引用的核心功能：
+ * 1. 值的存储和访问
+ * 2. 值的自动解包
+ * 3. 变更通知
+ * 4. 依赖追踪
  */
 export declare class RefReactivity<T = any> extends Reactivity<T> implements Ref<T> {
+    /**
+     * 标识这是一个 ref 对象。
+     *
+     * 用于 isRef 函数判断对象是否为引用。
+     */
     readonly [ReactiveFlags.IS_REF] = true;
+    /**
+     * 获取引用的值。
+     *
+     * 取值时会：
+     * 1. 建立依赖关系
+     * 2. 返回当前值
+     */
     get value(): T;
+    /**
+     * 设置引用的值。
+     *
+     * 设置值时会：
+     * 1. 比较新旧值是否发生变化
+     * 2. 如果值发生变化，则：
+     *    - 触发更新通知
+     *    - 更新原始值
+     *    - 更新响应式值
+     *
+     * @param v 要设置的新值
+     */
     set value(v: T);
     /**
      * 原始值。
      *
+     * 存储未经响应式处理的原始值。
      * 用于比较值是否发生变化。
+     *
+     * @private
      */
     private _rawValue;
+    /**
+     * 创建引用反应式节点。
+     *
+     * @param value 要包装的值
+     */
     constructor(value: T);
 }
+/**
+ * 引用接口。
+ *
+ * 定义了引用的基本结构：
+ * 1. value: 引用的值，可读可写
+ * 2. RefSymbol: 用于标识这是一个引用
+ */
 export interface Ref<T = any, S = T> {
     get value(): T;
     set value(_: S);

package/lib/ref.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ref.d.ts","sourceRoot":"","sources":["../src/ref.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGnD;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAQxC;AAED;;;GAGG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,OAAO,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC;AAM3D,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,GAAG,CAAE,SAAQ,GAAG,CAAC,CAAC,CAAC;CAAI;AAE1D;;;;GAIG;AACH,qBAAa,aAAa,CAAC,CAAC,GAAG,GAAG,CAAE,SAAQ,UAAU,CAAC,CAAC,CAAE,YAAW,GAAG,CAAC,CAAC,CAAC;IAEvE,SAAgB,CAAC,aAAa,CAAC,MAAM,CAAC,QAAQ;IAE9C,IAAI,KAAK,IAOI,CAAC,CAFb;IAED,IAAI,KAAK,CAAC,CAAC,EAAE,CAAC,EAcb;IAED;;;;OAIG;IACH,OAAO,CAAC,SAAS,CAAI;gBAET,KAAK,EAAE,CAAC;CAMvB;AAED,MAAM,WAAW,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC;IAE/B,IAAI,KAAK,IAAI,CAAC,CAAA;IACd,IAAI,KAAK,CAAC,CAAC,EAAE,CAAC,EAAC;IACf,CAAC,SAAS,CAAC,EAAE,IAAI,CAAA;CACpB;AACD,OAAO,CAAC,MAAM,SAAS,EAAE,OAAO,MAAM,CAAC"}
+{"version":3,"file":"ref.d.ts","sourceRoot":"","sources":["../src/ref.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGnD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAQxC;AAED;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,OAAO,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC;AAM3D;;;;GAIG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,GAAG,CAAE,SAAQ,GAAG,CAAC,CAAC,CAAC;CAAI;AAE1D;;;;;;;;;GASG;AACH,qBAAa,aAAa,CAAC,CAAC,GAAG,GAAG,CAAE,SAAQ,UAAU,CAAC,CAAC,CAAE,YAAW,GAAG,CAAC,CAAC,CAAC;IAEvE;;;;OAIG;IACH,SAAgB,CAAC,aAAa,CAAC,MAAM,CAAC,QAAQ;IAE9C;;;;;;OAMG;IACH,IAAI,KAAK,IAmBI,CAAC,CAdb;IAED;;;;;;;;;;;OAWG;IACH,IAAI,KAAK,CAAC,CAAC,EAAE,CAAC,EAcb;IAED;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS,CAAI;IAErB;;;;OAIG;gBACS,KAAK,EAAE,CAAC;CAMvB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC;IAE/B,IAAI,KAAK,IAAI,CAAC,CAAA;IACd,IAAI,KAAK,CAAC,CAAC,EAAE,CAAC,EAAC;IACf,CAAC,SAAS,CAAC,EAAE,IAAI,CAAA;CACpB;AACD,OAAO,CAAC,MAAM,SAAS,EAAE,OAAO,MAAM,CAAC"}

package/lib/shared/constants.d.ts

@@ -2,8 +2,8 @@
  * 响应式标志枚举，用于标识响应式对象的特殊属性或状态
  */
 export declare enum ReactiveFlags {
-    IS_REACTIVE = "__v_isReactive",
-    RAW = "__v_raw",
+    IS_REACTIVE = "__v_isReactive",// 标识对象是否为响应式对象
+    RAW = "__v_raw",// 获取对象的原始非响应式版本
     IS_REF = "__v_isRef"
 }
 export declare enum TargetType {
@@ -15,17 +15,17 @@ export declare enum TargetType {
  * 跟踪操作类型枚举，用于标识在响应式系统中对对象属性进行的操作类型
  */
 export declare enum TrackOpTypes {
-    GET = "get",
-    HAS = "has",
+    GET = "get",// 获取属性值
+    HAS = "has",// 检查属性是否存在
     ITERATE = "iterate"
 }
 /**
  * 触发操作类型枚举，用于标识在响应式系统中对对象属性进行的修改操作类型
  */
 export declare enum TriggerOpTypes {
-    SET = "set",
-    ADD = "add",
-    DELETE = "delete",
+    SET = "set",// 设置属性值
+    ADD = "add",// 添加新属性
+    DELETE = "delete",// 删除属性
     CLEAR = "clear"
 }
 export declare const ITERATE_KEY: unique symbol;

package/lib/shared/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/shared/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,oBAAY,aAAa;IAErB,WAAW,mBAAmB;IAC9B,GAAG,YAAY;IACf,MAAM,cAAc;CACvB;AAED,oBAAY,UAAU;IAElB,OAAO,IAAI;IACX,MAAM,IAAI;IACV,UAAU,IAAI;CACjB;AAED;;GAEG;AACH,oBAAY,YAAY;IAEpB,GAAG,QAAQ;IACX,GAAG,QAAQ;IACX,OAAO,YAAY;CACtB;AAED;;GAEG;AACH,oBAAY,cAAc;IAEtB,GAAG,QAAQ;IACX,GAAG,QAAQ;IACX,MAAM,WAAW;IACjB,KAAK,UAAU;CAClB;AAED,eAAO,MAAM,WAAW,EAAE,OAAO,MAAgD,CAAC;AAClF,eAAO,MAAM,mBAAmB,EAAE,OAAO,MAAkD,CAAC;AAC5F,eAAO,MAAM,iBAAiB,EAAE,OAAO,MAA+C,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/shared/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,oBAAY,aAAa;IAErB,WAAW,mBAAmB,CAAE,eAAe;IAC/C,GAAG,YAAY,CAAE,gBAAgB;IACjC,MAAM,cAAc;CACvB;AAED,oBAAY,UAAU;IAElB,OAAO,IAAI;IACX,MAAM,IAAI;IACV,UAAU,IAAI;CACjB;AAED;;GAEG;AACH,oBAAY,YAAY;IAEpB,GAAG,QAAQ,CAAE,QAAQ;IACrB,GAAG,QAAQ,CAAE,WAAW;IACxB,OAAO,YAAY;CACtB;AAED;;GAEG;AACH,oBAAY,cAAc;IAEtB,GAAG,QAAQ,CAAE,QAAQ;IACrB,GAAG,QAAQ,CAAE,QAAQ;IACrB,MAAM,WAAW,CAAE,OAAO;IAC1B,KAAK,UAAU;CAClB;AAED,eAAO,MAAM,WAAW,EAAE,OAAO,MAAgD,CAAC;AAClF,eAAO,MAAM,mBAAmB,EAAE,OAAO,MAAkD,CAAC;AAC5F,eAAO,MAAM,iBAAiB,EAAE,OAAO,MAA+C,CAAC"}

package/lib/shared/general.d.ts

@@ -12,7 +12,7 @@ export declare const isSymbol: (val: unknown) => val is symbol;
 export declare const isString: (val: unknown) => val is string;
 export declare const isIntegerKey: (key: unknown) => boolean;
 export declare const isMap: (val: unknown) => val is Map<any, any>;
-export declare const hasOwn: (val: object, key: string | symbol) => key is never;
+export declare const hasOwn: (val: object, key: string | symbol) => key is keyof typeof val;
 export declare const hasChanged: (value: any, oldValue: any) => boolean;
 export declare function getTargetType(value: Target): TargetType;
 export declare const toRawType: (value: unknown) => string;

package/lib/shared/general.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"general.d.ts","sourceRoot":"","sources":["../../src/shared/general.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAExD,OAAO,EAAG,CAAC;AACX,OAAO,CAAC,MAAM,CACd;IACI;;OAEG;IACH,IAAI,OAAO,EAAE,OAAO,CAAC;CACxB;AAGD,eAAO,MAAM,QAAQ,QAAS,OAAO,4BAAqE,CAAC;AAE3G,eAAO,MAAM,OAAO,EAAE,OAAO,KAAK,CAAC,OAAuB,CAAC;AAC3D,eAAO,MAAM,QAAQ,QAAS,OAAO,kBAA2C,CAAC;AACjF,eAAO,MAAM,QAAQ,QAAS,OAAO,kBAA2C,CAAC;AACjF,eAAO,MAAM,YAAY,QAAS,OAAO,KAAG,OAIA,CAAC;AAC7C,eAAO,MAAM,KAAK,QAAS,OAAO,yBACM,CAAC;AAGzC,eAAO,MAAM,MAAM,QACV,MAAM,OACN,MAAM,GAAG,MAAM,iBACoD,CAAC;AAG7E,eAAO,MAAM,UAAU,UAAW,GAAG,YAAY,GAAG,KAAG,OACxB,CAAC;AAmBhC,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,cAK1C;AAKD,eAAO,MAAM,SAAS,UAAW,OAAO,KAAG,MAGP,CAAC;AAErC,MAAM,WAAW,MAAM;IAEnB,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,EAAE,OAAO,CAAA;IACrC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAA;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAKvC;AAED,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAGtD;AAED;;;;GAIG;AAGH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAU7D"}
+{"version":3,"file":"general.d.ts","sourceRoot":"","sources":["../../src/shared/general.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAExD,OAAO,EAAG,CAAC;AACX,OAAO,CAAC,MAAM,CACd;IACI;;OAEG;IACH,IAAI,OAAO,EAAE,OAAO,CAAC;CACxB;AAGD,eAAO,MAAM,QAAQ,GAAI,KAAK,OAAO,KAAG,GAAG,IAAI,MAAM,CAAC,GAAG,EAAE,GAAG,CAA4C,CAAC;AAE3G,eAAO,MAAM,OAAO,EAAE,OAAO,KAAK,CAAC,OAAuB,CAAC;AAC3D,eAAO,MAAM,QAAQ,GAAI,KAAK,OAAO,KAAG,GAAG,IAAI,MAAiC,CAAC;AACjF,eAAO,MAAM,QAAQ,GAAI,KAAK,OAAO,KAAG,GAAG,IAAI,MAAiC,CAAC;AACjF,eAAO,MAAM,YAAY,GAAI,KAAK,OAAO,KAAG,OAIA,CAAC;AAC7C,eAAO,MAAM,KAAK,GAAI,KAAK,OAAO,KAAG,GAAG,IAAI,GAAG,CAAC,GAAG,EAAE,GAAG,CAChB,CAAC;AAGzC,eAAO,MAAM,MAAM,GACf,KAAK,MAAM,EACX,KAAK,MAAM,GAAG,MAAM,KACrB,GAAG,IAAI,MAAM,OAAO,GAAqD,CAAC;AAG7E,eAAO,MAAM,UAAU,GAAI,OAAO,GAAG,EAAE,UAAU,GAAG,KAAG,OACxB,CAAC;AAmBhC,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,cAK1C;AAKD,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,KAAG,MAGP,CAAC;AAErC,MAAM,WAAW,MAAM;IAEnB,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,EAAE,OAAO,CAAA;IACrC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAA;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAKvC;AAED,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAGtD;AAED;;;;GAIG;AAGH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAU7D"}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@feng3d/reactivity",
   "type": "module",
-  "version": "1.0.5",
-  "description": "反应式",
+  "version": "1.0.7",
+  "description": "反应式，主要用于feng3d中的数据驱动。",
   "homepage": "https://feng3d.com/reactivity",
   "main": "./dist/index.umd.cjs",
   "types": "./lib/index.d.ts",
@@ -11,9 +11,9 @@
   "license": "MIT",
   "exports": {
     ".": {
+      "types": "./lib/index.d.ts",
       "import": "./dist/index.js",
-      "require": "./dist/index.umd.cjs",
-      "types": "./lib/index.d.ts"
+      "require": "./dist/index.umd.cjs"
     }
   },
   "scripts": {
@@ -21,10 +21,9 @@
     "clean": "rimraf \"{lib,dist,public}\"",
     "build": "vite build",
     "test": "vitest",
-    "test:ui": "vitest --ui",
     "types": "tsc",
     "watch": "tsc -w",
-    "lint": "eslint --ext .js --ext .ts src test --ignore-path .gitignore --max-warnings 0",
+    "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",
@@ -51,17 +50,20 @@
     "tsconfig.json"
   ],
   "devDependencies": {
+    "@eslint/js": "^9.0.0",
     "@feng3d/cli": "^0.0.19",
-    "@typescript-eslint/eslint-plugin": "5.17.0",
-    "@typescript-eslint/parser": "5.17.0",
-    "@vitest/ui": "^0.32.2",
+    "@types/node": "^22.15.19",
+    "@typescript-eslint/eslint-plugin": "8.32.1",
+    "@typescript-eslint/parser": "8.32.1",
     "cross-env": "7.0.3",
-    "eslint": "8.12.0",
-    "rimraf": "3.0.2",
-    "tslib": "^2.4.0",
-    "typedoc": "^0.24.8",
-    "typescript": "5.1.3",
-    "vite": "^4.3.9",
-    "vitest": "^0.32.2"
+    "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/Reactivity.ts

@@ -1,11 +1,15 @@
 import { type ComputedReactivity } from './computed';
 
 /**
- * 反应式节点。
+ * 反应式节点基类。
  *
  * 拥有节点值以及被捕捉与触发的能力。
+ * 用于被 computed、effect 等构建的节点所继承。
  *
- * 用于被 computed effect 等构建的节点所继承。
+ * 实现了响应式系统的核心功能：
+ * 1. 值的存储和访问
+ * 2. 依赖关系的建立（track）
+ * 3. 变更通知的传播（trigger）
  */
 export class Reactivity<T = any>
 {
@@ -13,6 +17,7 @@ export class Reactivity<T = any>
      * 获取当前节点值。
      *
      * 取值时将会建立与父节点的依赖关系。
+     * 当其他响应式节点访问此值时，会自动建立依赖关系。
      */
     get value(): T
     {
@@ -20,26 +25,32 @@ export class Reactivity<T = any>
 
         return this._value;
     }
+
     /**
      * @private
      */
     _value: T;
 
     /**
-     * 父反应节点。
+     * 父反应节点集合。
      *
-     * 记录了哪些节点调用了当前节点。
+     * 记录了哪些节点依赖了当前节点。
+     * 当当前节点值发生变化时，会通知所有父节点。
      *
-     * 当前节点失效时，会通知并移除所有父节点。
+     * Map 的 key 是父节点，value 是父节点的版本号。
+     * 版本号用于判断依赖关系是否过期。
      *
      * @private
      */
     _parents = new Map<ComputedReactivity, number>();
 
     /**
-     * 捕捉。
+     * 建立依赖关系。
+     *
+     * 当其他节点访问当前节点的值时，会调用此方法。
+     * 将当前节点与访问者（父节点）建立依赖关系。
      *
-     * 建立与父节点的依赖关系。
+     * 如果当前没有活动的响应式节点，或者不应该跟踪依赖，则不会建立依赖关系。
      */
     track()
     {
@@ -47,6 +58,7 @@ export class Reactivity<T = any>
 
         // 连接父节点和子节点。
         const parent = Reactivity.activeReactivity;
+
         if (parent)
         {
             this._parents.set(parent, parent._version);
@@ -54,9 +66,16 @@ export class Reactivity<T = any>
     }
 
     /**
-     * 触发。
+     * 触发更新。
+     *
+     * 当节点值发生变化时，会调用此方法。
+     * 通知所有依赖此节点的父节点进行更新。
      *
-     * 冒泡到所有父节点，设置失效子节点字典。
+     * 更新过程：
+     * 1. 遍历所有父节点
+     * 2. 检查父节点的版本号是否匹配
+     * 3. 触发父节点的更新
+     * 4. 将当前节点添加到父节点的失效子节点集合中
      */
     trigger()
     {
@@ -77,6 +96,9 @@ export class Reactivity<T = any>
     /**
      * 当前正在执行的反应式节点。
      *
+     * 用于在依赖收集过程中标识当前正在执行的节点。
+     * 当其他节点访问此节点的值时，会将其作为父节点。
+     *
      * @internal
      */
     static activeReactivity: ComputedReactivity;
@@ -84,42 +106,62 @@ export class Reactivity<T = any>
 
 /**
  * 反应式节点链。
+ *
+ * 用于表示响应式节点之间的依赖关系链。
+ * 每个节点包含：
+ * 1. 节点本身
+ * 2. 节点的值
+ * 3. 下一个节点的引用
  */
 export type ReactivityLink = { node: Reactivity, value: any, next: ReactivityLink };
 
 /**
- * 强制跟踪。
+ * 强制跟踪依赖。
+ *
+ * 在函数执行期间强制启用依赖跟踪。
+ * 即使当前处于不跟踪状态，也会建立依赖关系。
  *
- * @param fn 强制跟踪的函数。
+ * @param fn 要执行的函数
+ * @returns 函数的执行结果
  */
 export function forceTrack<T>(fn: () => T): T
 {
     const preShouldTrack = _shouldTrack;
+
     _shouldTrack = true;
     const result = fn();
+
     _shouldTrack = preShouldTrack;
 
     return result;
 }
 
 /**
- * 不跟踪。
+ * 禁用依赖跟踪。
+ *
+ * 在函数执行期间禁用依赖跟踪。
+ * 即使当前处于跟踪状态，也不会建立依赖关系。
  *
- * @param fn 不跟踪的函数。
+ * @param fn 要执行的函数
+ * @returns 函数的执行结果
  */
 export function noTrack<T>(fn: () => T): T
 {
     const preShouldTrack = _shouldTrack;
+
     _shouldTrack = false;
     const result = fn();
+
     _shouldTrack = preShouldTrack;
 
     return result;
 }
 
 /**
- * 是否应该跟踪的标志
- * 控制是否进行依赖跟踪
+ * 是否应该跟踪依赖的标志。
+ *
+ * 控制是否进行依赖跟踪。
+ * 可以通过 forceTrack 和 noTrack 函数临时修改此值。
  *
  * @private
  */