@feng3d/reactivity 1.0.5 → 1.0.7

package/src/property.ts

@@ -13,6 +13,7 @@ import { isArray, isIntegerKey, isMap, isSymbol } from './shared/general';
 function property<T, K extends keyof T>(target: T, key: K)
 {
     let depsMap = PropertyReactivity._targetMap.get(target);
+
     if (!depsMap)
     {
         depsMap = new Map();
@@ -21,6 +22,7 @@ function property<T, K extends keyof T>(target: T, key: K)
 
     //
     let dep = depsMap.get(key);
+
     if (!dep)
     {
         dep = new PropertyReactivity(target, key);
@@ -46,6 +48,7 @@ export class PropertyReactivity<T, K extends keyof T> extends Reactivity<T>
 
         return this._value;
     }
+
     set value(v)
     {
         // 处理特殊字段，这些字段
@@ -112,6 +115,7 @@ export class PropertyReactivity<T, K extends keyof T> extends Reactivity<T>
         // 取值，建立依赖关系。
         dep.track();
     }
+
     /**
      * @private
      */
@@ -130,6 +134,7 @@ export class PropertyReactivity<T, K extends keyof T> extends Reactivity<T>
     static trigger(target: object, type: TriggerOpTypes, key?: unknown, newValue?: unknown, oldValue?: unknown): void
     {
         const depsMap = this._targetMap.get(target);
+
         if (!depsMap) return;
 
         const run = (dep: PropertyReactivity<any, any> | undefined) =>
@@ -157,6 +162,7 @@ export class PropertyReactivity<T, K extends keyof T> extends Reactivity<T>
                 if (targetIsArray && key === 'length')
                 {
                     const newLength = Number(newValue);
+
                     depsMap.forEach((dep, key) =>
                     {
                         if (

package/src/reactive.ts

@@ -7,24 +7,34 @@ import { getTargetType, isObject, 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 function reactive<T extends object>(target: T): UnReadonly<Reactive<T>>
+export function reactive<T extends object>(target: T): Reactive<T>
 {
     if (!isObject(target))
     {
@@ -36,35 +46,47 @@ export function reactive<T extends object>(target: T): UnReadonly<Reactive<T>>
         return target as any;
     }
 
-    // only specific value types can be observed.
+    // 只有特定类型的值可以被观察
     const targetType = getTargetType(target);
+
     if (targetType === TargetType.INVALID)
     {
         return target as any;
     }
 
-    // target already has corresponding Proxy
+    // 如果目标已经有对应的代理对象，直接返回
     const existingProxy = reactiveMap.get(target);
+
     if (existingProxy)
     {
         return existingProxy;
     }
 
+    // 创建新的代理对象
     const proxy = new Proxy<T>(
         target,
         targetType === TargetType.COLLECTION ? mutableCollectionHandlers : mutableHandlers as any,
     ) as T;
+
     reactiveMap.set(target, proxy);
 
     return proxy as any;
 }
+
+/**
+ * 响应式对象缓存映射。
+ *
+ * 用于缓存已创建的响应式代理对象，避免重复创建。
+ */
 export const reactiveMap = new WeakMap<Target, any>();
 
 /**
  * 判断一个对象是否为响应式对象。
  *
- * @param value 对象。
- * @returns
+ * 通过检查对象是否具有 IS_REACTIVE 标志来判断。
+ *
+ * @param value 要检查的对象
+ * @returns 如果是响应式对象则返回 true，否则返回 false
  */
 export function isReactive(value: unknown): boolean
 {
@@ -74,8 +96,11 @@ export function isReactive(value: unknown): boolean
 /**
  * 转换为响应式对象。
  *
- * @param value 对象。
- * @returns
+ * 如果输入是对象，则将其转换为响应式对象。
+ * 如果输入不是对象，则直接返回。
+ *
+ * @param value 要转换的值
+ * @returns 转换后的响应式对象或原值
  */
 export const toReactive = <T>(value: T): T =>
 {
@@ -90,29 +115,44 @@ export const toReactive = <T>(value: T): T =>
 /**
  * 判断一个对象是否为代理对象。
  *
- * @param value 对象。
- * @returns
+ * 通过检查对象是否具有 RAW 标志来判断。
+ *
+ * @param value 要检查的对象
+ * @returns 如果是代理对象则返回 true，否则返回 false
  */
 export function isProxy(value: any): boolean
 {
     return value ? !!value[ReactiveFlags.RAW] : false;
 }
 
-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
@@ -124,6 +164,13 @@ export interface RefUnwrapBailTypes { }
 
 /**
  * 解包类型。
+ *
+ * 递归地解包响应式对象的类型，包括：
+ * 1. 内置类型直接返回
+ * 2. Ref 类型解包为内部类型
+ * 3. Computed 类型解包为内部类型
+ * 4. 对象类型递归解包其属性
+ * 5. 其他类型直接返回
  */
 export type UnwrapRefSimple<T> =
     T extends

package/src/ref.ts

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