@feng3d/reactivity 1.0.4 → 1.0.6

package/src/reactive.ts

@@ -1,130 +1,186 @@
-import { mutableHandlers } from './baseHandlers';
-import { mutableCollectionHandlers } from './collectionHandlers';
-import { Computed } from './computed';
-import { Ref } from './ref';
-import { ReactiveFlags, TargetType } from './shared/constants';
-import { getTargetType, isObject, Target } from './shared/general';
-
-/**
- * 创建或者获取响应式对象的代理对象。
- *
- * @param target 被响应式的对象。
- * @returns 响应式代理对象。
- *
- * 注意：
- *
- * 扩大被反应式的对象的类型范围，只有`Object.isExtensible`不通过的对象不被响应化。Float32Array等都允许被响应化。
- */
-export function reactive<T extends object>(target: T): Reactive<T>
-{
-    if (!isObject(target))
-    {
-        return target;
-    }
-
-    if (target[ReactiveFlags.RAW])
-    {
-        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
- */
-export function isReactive(value: unknown): boolean
-{
-    return !!(value && (value as Target)[ReactiveFlags.IS_REACTIVE]);
-}
-
-/**
- * 转换为响应式对象。
- *
- * @param value 对象。
- * @returns
- */
-export const toReactive = <T>(value: T): T =>
-{
-    if (isObject(value))
-    {
-        return reactive(value as any) as any;
-    }
-
-    return value;
-};
-
-/**
- * 判断一个对象是否为代理对象。
- *
- * @param value 对象。
- * @returns
- */
-export function isProxy(value: any): boolean
-{
-    return value ? !!value[ReactiveFlags.RAW] : false;
-}
-
-export type Reactive<T> = UnwrapRefSimple<T>;
-
-/**
- * 原始类型
- */
-type Primitive = string | number | boolean | bigint | symbol | undefined | null;
-/**
- * 内置类型
- */
-export type Builtin = Primitive | Function | Date | Error | RegExp;
-
-/**
- * 用于扩展不被 unwrap 的类型。
- *
- * ``` ts
- * declare module '@vue/reactivity' {
- *   export interface RefUnwrapBailTypes {
- *     runtimeDOMBailTypes: Node | Window
- *   }
- * }
- * ```
- */
-export interface RefUnwrapBailTypes { }
-
-/**
- * 解包类型。
- */
-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]>
-    } :
-    T;
+import { mutableHandlers } from './baseHandlers';
+import { mutableCollectionHandlers } from './collectionHandlers';
+import { Computed } from './computed';
+import { Ref } from './ref';
+import { ReactiveFlags, TargetType } from './shared/constants';
+import { getTargetType, isObject, Target } from './shared/general';
+
+/**
+ * 移除对象属性中的 readonly 关键字。
+ *
+ * 用于将只读类型转换为可写类型。
+ */
+export type UnReadonly<T> = {
+    -readonly [P in keyof T]: T[P];
+};
+
+/**
+ * 创建或者获取响应式对象的代理对象。
+ *
+ * 将普通对象转换为响应式对象，使其属性可以被追踪和更新。
+ *
+ * 特点：
+ * 1. 支持对象和集合类型的响应式转换
+ * 2. 自动处理嵌套对象的响应式转换
+ * 3. 缓存已创建的代理对象
+ * 4. 支持只读属性的响应式转换
+ *
+ * 注意：
+ * 1. 扩大被反应式的对象的类型范围，只有 `Object.isExtensible` 不通过的对象不被响应化。
+ *    Float32Array 等都允许被响应化。
+ * 2. 被反应式的对象的只读属性也会被标记为可编辑。希望被反应对象属性一般为只读属性，
+ *    通过反应式来改变属性值，同时又通过反应式系统来处理其更改后响应逻辑。
+ *
+ * @param target 要转换为响应式的对象
+ * @returns 响应式代理对象
+ */
+export function reactive<T extends object>(target: T): Reactive<T>
+{
+    if (!isObject(target))
+    {
+        return target;
+    }
+
+    if (target[ReactiveFlags.RAW])
+    {
+        return target as any;
+    }
+
+    // 只有特定类型的值可以被观察
+    const targetType = getTargetType(target);
+
+    if (targetType === TargetType.INVALID)
+    {
+        return target as any;
+    }
+
+    // 如果目标已经有对应的代理对象，直接返回
+    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>();
+
+/**
+ * 判断一个对象是否为响应式对象。
+ *
+ * 通过检查对象是否具有 IS_REACTIVE 标志来判断。
+ *
+ * @param value 要检查的对象
+ * @returns 如果是响应式对象则返回 true，否则返回 false
+ */
+export function isReactive(value: unknown): boolean
+{
+    return !!(value && (value as Target)[ReactiveFlags.IS_REACTIVE]);
+}
+
+/**
+ * 转换为响应式对象。
+ *
+ * 如果输入是对象，则将其转换为响应式对象。
+ * 如果输入不是对象，则直接返回。
+ *
+ * @param value 要转换的值
+ * @returns 转换后的响应式对象或原值
+ */
+export const toReactive = <T>(value: T): T =>
+{
+    if (isObject(value))
+    {
+        return reactive(value as any) as any;
+    }
+
+    return value;
+};
+
+/**
+ * 判断一个对象是否为代理对象。
+ *
+ * 通过检查对象是否具有 RAW 标志来判断。
+ *
+ * @param value 要检查的对象
+ * @returns 如果是代理对象则返回 true，否则返回 false
+ */
+export function isProxy(value: any): boolean
+{
+    return value ? !!value[ReactiveFlags.RAW] : false;
+}
+
+/**
+ * 响应式类型。
+ *
+ * 表示一个对象的所有属性都是响应式的。
+ */
+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;
+
+/**
+ * 用于扩展不被解包的类型。
+ *
+ * 可以通过声明合并来扩展此接口，添加不需要被解包的类型。
+ *
+ * 示例：
+ * ```ts
+ * declare module '@vue/reactivity' {
+ *   export interface RefUnwrapBailTypes {
+ *     runtimeDOMBailTypes: Node | Window
+ *   }
+ * }
+ * ```
+ */
+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]>
+    } :
+    T;

package/src/ref.ts

@@ -1,88 +1,150 @@
-import { batchRun } from './batch';
-import { Reactivity } from './Reactivity';
-import { toReactive } from './reactive';
-import { ReactiveFlags } from './shared/constants';
-import { hasChanged, toRaw } from './shared/general';
-
-/**
- * 创建一个引用，该引用的值可以被响应式系统追踪和更新。
- *
- * @param value 引用的值。
- * @returns 包含 value 属性的对象，用于获取和设置引用的值。
- */
-export function ref<T>(value?: T): Ref<T>
-{
-    if (isRef(value))
-    {
-        return value as any;
-    }
-
-    return new RefReactivity<T>(value) as any;
-}
-
-/**
- * 判断一个对象是否为引用。
- * @param r 引用。
- */
-export function isRef<T>(r: Ref<T> | unknown): r is Ref<T>;
-export function isRef(r: any): r is Ref
-{
-    return r ? r[ReactiveFlags.IS_REF] === true : false;
-}
-
-export interface RefReactivity<T = any> extends Ref<T> { }
-
-/**
- * 引用反应式节点。
- *
- * 当使用 ref 函数时，会创建一个 RefReactivity 对象。
- */
-export class RefReactivity<T = any> extends Reactivity<T> implements Ref<T>
-{
-    public readonly [ReactiveFlags.IS_REF] = true;
-
-    get value()
-    {
-        this.track();
-
-        return this._value;
-    }
-
-    set value(v: T)
-    {
-        const oldValue = this._rawValue;
-        const newValue = toRaw(v);
-
-        if (!hasChanged(oldValue, newValue)) return;
-
-        batchRun(() =>
-        {
-            this.trigger();
-
-            this._rawValue = newValue;
-            this._value = toReactive(newValue);
-        });
-    }
-
-    /**
-     * 原始值。
-     *
-     * 用于比较值是否发生变化。
-     */
-    private _rawValue: T;
-
-    constructor(value: T)
-    {
-        super();
-        this._rawValue = toRaw(value);
-        this._value = toReactive(value);
-    }
-}
-
-export interface Ref<T = any, S = T>
-{
-    get value(): T
-    set value(_: S)
-    [RefSymbol]: true
-}
-declare const RefSymbol: unique symbol;
+import { batchRun } from './batch';
+import { Reactivity } from './Reactivity';
+import { toReactive } from './reactive';
+import { ReactiveFlags } from './shared/constants';
+import { hasChanged, toRaw } from './shared/general';
+
+/**
+ * 创建一个引用，该引用的值可以被响应式系统追踪和更新。
+ *
+ * ref 是响应式系统中最基本的响应式对象。
+ * 它可以包装任何类型的值，使其成为响应式的。
+ *
+ * 特点：
+ * 1. 可以包装任何类型的值
+ * 2. 通过 .value 访问和修改值
+ * 3. 自动解包原始值
+ * 4. 支持嵌套的响应式对象
+ *
+ * @param value 要包装的值
+ * @returns 包含 value 属性的响应式引用对象
+ */
+export function ref<T>(value?: T): Ref<T>
+{
+    if (isRef(value))
+    {
+        return value as any;
+    }
+
+    return new RefReactivity<T>(value) as any;
+}
+
+/**
+ * 判断一个对象是否为引用。
+ *
+ * 通过检查对象是否具有 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
+{
+    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();
+
+        return this._value;
+    }
+
+    /**
+     * 设置引用的值。
+     *
+     * 设置值时会：
+     * 1. 比较新旧值是否发生变化
+     * 2. 如果值发生变化，则：
+     *    - 触发更新通知
+     *    - 更新原始值
+     *    - 更新响应式值
+     *
+     * @param v 要设置的新值
+     */
+    set value(v: T)
+    {
+        const oldValue = this._rawValue;
+        const newValue = toRaw(v);
+
+        if (!hasChanged(oldValue, newValue)) return;
+
+        batchRun(() =>
+        {
+            this.trigger();
+
+            this._rawValue = newValue;
+            this._value = toReactive(newValue);
+        });
+    }
+
+    /**
+     * 原始值。
+     *
+     * 存储未经响应式处理的原始值。
+     * 用于比较值是否发生变化。
+     *
+     * @private
+     */
+    private _rawValue: T;
+
+    /**
+     * 创建引用反应式节点。
+     *
+     * @param value 要包装的值
+     */
+    constructor(value: T)
+    {
+        super();
+        this._rawValue = toRaw(value);
+        this._value = toReactive(value);
+    }
+}
+
+/**
+ * 引用接口。
+ *
+ * 定义了引用的基本结构：
+ * 1. value: 引用的值，可读可写
+ * 2. RefSymbol: 用于标识这是一个引用
+ */
+export interface Ref<T = any, S = T>
+{
+    get value(): T
+    set value(_: S)
+    [RefSymbol]: true
+}
+declare const RefSymbol: unique symbol;

package/src/shared/constants.ts

@@ -1,41 +1,41 @@
-/**
- * 响应式标志枚举，用于标识响应式对象的特殊属性或状态
- */
-export enum ReactiveFlags
-{
-    IS_REACTIVE = '__v_isReactive', // 标识对象是否为响应式对象
-    RAW = '__v_raw', // 获取对象的原始非响应式版本
-    IS_REF = '__v_isRef', // 标识对象是否为 ref 对象
-}
-
-export enum TargetType
-{
-    INVALID = 0,
-    COMMON = 1,
-    COLLECTION = 2,
-}
-
-/**
- * 跟踪操作类型枚举，用于标识在响应式系统中对对象属性进行的操作类型
- */
-export enum TrackOpTypes
-{
-    GET = 'get', // 获取属性值
-    HAS = 'has', // 检查属性是否存在
-    ITERATE = 'iterate', // 遍历对象属性
-}
-
-/**
- * 触发操作类型枚举，用于标识在响应式系统中对对象属性进行的修改操作类型
- */
-export enum TriggerOpTypes
-{
-    SET = 'set', // 设置属性值
-    ADD = 'add', // 添加新属性
-    DELETE = 'delete', // 删除属性
-    CLEAR = 'clear', // 清空对象属性
-}
-
-export const ITERATE_KEY: unique symbol = Symbol(__DEV__ ? 'Object iterate' : '');
-export const MAP_KEY_ITERATE_KEY: unique symbol = Symbol(__DEV__ ? 'Map keys iterate' : '');
-export const ARRAY_ITERATE_KEY: unique symbol = Symbol(__DEV__ ? 'Array iterate' : '');
+/**
+ * 响应式标志枚举，用于标识响应式对象的特殊属性或状态
+ */
+export enum ReactiveFlags
+{
+    IS_REACTIVE = '__v_isReactive', // 标识对象是否为响应式对象
+    RAW = '__v_raw', // 获取对象的原始非响应式版本
+    IS_REF = '__v_isRef', // 标识对象是否为 ref 对象
+}
+
+export enum TargetType
+{
+    INVALID = 0,
+    COMMON = 1,
+    COLLECTION = 2,
+}
+
+/**
+ * 跟踪操作类型枚举，用于标识在响应式系统中对对象属性进行的操作类型
+ */
+export enum TrackOpTypes
+{
+    GET = 'get', // 获取属性值
+    HAS = 'has', // 检查属性是否存在
+    ITERATE = 'iterate', // 遍历对象属性
+}
+
+/**
+ * 触发操作类型枚举，用于标识在响应式系统中对对象属性进行的修改操作类型
+ */
+export enum TriggerOpTypes
+{
+    SET = 'set', // 设置属性值
+    ADD = 'add', // 添加新属性
+    DELETE = 'delete', // 删除属性
+    CLEAR = 'clear', // 清空对象属性
+}
+
+export const ITERATE_KEY: unique symbol = Symbol(__DEV__ ? 'Object iterate' : '');
+export const MAP_KEY_ITERATE_KEY: unique symbol = Symbol(__DEV__ ? 'Map keys iterate' : '');
+export const ARRAY_ITERATE_KEY: unique symbol = Symbol(__DEV__ ? 'Array iterate' : '');