@lytjs/reactivity 5.0.1 → 6.4.0

package/dist/index.d.cts

@@ -0,0 +1,226 @@
+import { U as UnwrapNestedRefs, b as DeepReadonly, C as ComputedGetter, l as WritableComputedOptions, m as WritableComputedRef, k as WatchSource, g as WatchCallbackWithImmediate, j as WatchOptions, i as WatchHandle, O as OnCleanup, h as WatchEffectOptions } from './scope-BC3djHz7.cjs';
+export { a as ComputedSetter, D as DebuggerEvent, E as EffectScope, c as EffectScopeOptions, R as ReactiveEffectOptions, d as ReactiveEffectRunner, e as ReactiveObject, T as ToRefs, f as UnwrapRef, W as WatchCallback, n as batch, o as batchAsync, p as effect, q as effectScope, r as enableTracking, s as getCurrentScope, t as getSkippedTrackingCount, u as onEffectCleanup, v as onScopeDispose, w as pauseTracking, x as resetSkippedTrackingCount, y as resetTracking, z as shouldSkipTracking, A as stop, B as untrack, F as withFirstRenderOptimization } from './scope-BC3djHz7.cjs';
+import { C as ComputedRef } from './ref-CwOCKoy2.cjs';
+export { R as Ref, S as ShallowRef, c as customRef, i as isComputedRef, a as isShallowRef, r as ref, s as shallowRef, t as toRef, b as toRefs, d as toValue, e as triggerRef, u as unref } from './ref-CwOCKoy2.cjs';
+export { C as ComputedRefSymbol, a as ComputedSignal, R as ReactiveSymbol, b as ReadonlySignal, c as ReadonlySymbol, d as RefSymbol, S as ShallowRefSymbol, e as Signal, f as Subscriber, W as WritableComputedSignal, g as WritableSignal, m as computedSignal, r as readonlySignal, s as set, n as signal, o as signalBatch, l as signalComputed, p as signalUntrack, u as update, v as valueOf, w as writableComputedSignal } from './signal-DWrUYmvd.cjs';
+import { RefLike } from '@lytjs/shared-types';
+
+/**
+ * 获取响应式对象的原始值
+ */
+declare function toRaw<T>(observed: T): T;
+/**
+ * 判断一个值是否为 ref
+ */
+declare function isRef<T = unknown>(r: unknown): r is RefLike<T>;
+
+declare function reactive<T extends object>(target: T): UnwrapNestedRefs<T>;
+declare function shallowReactive<T extends object>(target: T): T;
+declare function readonly<T extends object>(target: T): DeepReadonly<UnwrapNestedRefs<T>>;
+declare function shallowReadonly<T extends object>(target: T): Readonly<T>;
+declare function isReactive(value: unknown): boolean;
+declare function isReadonly(value: unknown): boolean;
+declare function isProxy(value: unknown): boolean;
+
+declare function markRaw<T extends object>(value: T): T;
+
+/**
+ * 设置 SSR 模式。
+ * 在 SSR 环境中调用 setSSRMode(true) 可让 computed 在创建时立即求值，
+ * 避免在服务端渲染时因懒求值导致的不一致问题。
+ *
+ * 注意：此设置为模块级全局状态，多实例/测试场景下可能产生状态泄漏。
+ * 如需隔离，请确保不同环境使用独立的模块加载上下文。
+ */
+declare function setSSRMode(isSSR: boolean): void;
+declare function computed<T>(getterOrOptions: ComputedGetter<T> | WritableComputedOptions<T>): ComputedRef<T> | WritableComputedRef<T>;
+
+/**
+ * 侦听一个或多个响应式数据源，并在数据变化时执行回调。
+ *
+ * @param source - 要侦听的数据源，可以是 ref、reactive 对象、getter 函数，或它们的数组
+ * @param cb - 数据变化时的回调函数
+ * @param options - 侦听选项
+ * @returns 停止侦听的句柄函数
+ *
+ * @remarks
+ * 关于 scheduler 参数签名：
+ * watch 的 scheduler 与 ReactiveEffect 的 scheduler 参数签名不同。
+ * - ReactiveEffect.scheduler: () => void（无参数，由 effect 系统内部调用）
+ * - watch scheduler: (job: () => void, ...args: unknown[]) => unknown
+ *   其中 job 是 watch 内部封装的变更检测+回调执行函数。
+ *   当用户提供 scheduler 时，watch 会将 job 作为第一个参数传入，
+ *   用户可以在 scheduler 中决定何时执行 job（如节流、防抖等）。
+ */
+declare function watch<T, Immediate extends Readonly<boolean> = false>(source: WatchSource<T> | WatchSource<T>[], cb: WatchCallbackWithImmediate<T, Immediate>, options?: WatchOptions<Immediate>): WatchHandle;
+declare function watchEffect(effectFn: (onCleanup: OnCleanup) => void, options?: WatchEffectOptions): WatchHandle;
+declare function watchPostEffect(effectFn: (onCleanup: OnCleanup) => void, options?: WatchEffectOptions): WatchHandle;
+declare function watchSyncEffect(effectFn: (onCleanup: OnCleanup) => void, options?: WatchEffectOptions): WatchHandle;
+
+/**
+ * @lytjs/reactivity - batch.ts
+ * FIX: P2-4 REACTIVITY-NEW-05 - 批量操作 API
+ *
+ * 提供 batchScope 函数，支持嵌套批量操作和自动提交。
+ * 允许在批量作用域内执行多个响应式操作，只在作用域结束时统一触发更新。
+ */
+/** 批量作用域配置选项 */
+interface BatchScopeOptions {
+    /** 是否异步提交（默认 false） */
+    async?: boolean;
+    /** 作用域名称（用于调试） */
+    name?: string;
+    /** 错误处理回调 */
+    onError?: (error: unknown) => void;
+}
+/** 批量作用域上下文 */
+interface BatchScopeContext {
+    /** 当前嵌套深度 */
+    depth: number;
+    /** 作用域名称 */
+    name: string;
+    /** 是否已提交 */
+    committed: boolean;
+    /** 是否已取消 */
+    cancelled: boolean;
+}
+/** 批量操作回调 */
+type BatchScopeCallback<T> = (ctx: BatchScopeContext) => T;
+/**
+ * 创建批量作用域并执行回调函数。
+ * 在作用域内所有响应式操作会被批量收集，只在作用域结束时统一触发更新。
+ *
+ * 支持嵌套调用：嵌套的 batchScope 会继承外层的批量状态，
+ * 只有最外层作用域结束时才会真正提交所有更新。
+ *
+ * @example
+ * ```typescript
+ * batchScope((ctx) => {
+ *   signal1.set(1);
+ *   signal2.set(2);
+ *   // 此时不会触发更新
+ *
+ *   batchScope((innerCtx) => {
+ *     signal3.set(3);
+ *     // 嵌套作用域，仍然不会触发更新
+ *   });
+ * });
+ * // 所有更新在这里统一触发
+ * ```
+ *
+ * @param callback - 在批量作用域内执行的回调函数
+ * @param options - 批量作用域配置选项
+ * @returns 回调函数的返回值
+ */
+declare function batchScope<T>(callback: BatchScopeCallback<T>, options?: BatchScopeOptions): T;
+/**
+ * 创建异步批量作用域。
+ * 与 batchScope 类似，但支持 async/await。
+ *
+ * @example
+ * ```typescript
+ * await batchScopeAsync(async (ctx) => {
+ *   signal1.set(1);
+ *   await someAsyncOperation();
+ *   signal2.set(2);
+ * });
+ * ```
+ *
+ * @param callback - 异步回调函数
+ * @param options - 批量作用域配置选项
+ * @returns Promise，在批量作用域完成时 resolve
+ */
+declare function batchScopeAsync<T>(callback: BatchScopeCallback<Promise<T> | T>, options?: BatchScopeOptions): Promise<T>;
+/**
+ * 在批量作用域内执行无追踪操作。
+ * 函数内读取 signal 不会建立依赖关系。
+ *
+ * @param fn - 要执行的函数
+ * @returns 函数的返回值
+ */
+declare function batchScopeUntrack<T>(fn: () => T): T;
+/**
+ * 获取当前批量作用域深度。
+ * 0 表示不在任何批量作用域内。
+ */
+declare function getBatchScopeDepth(): number;
+/**
+ * 获取当前活跃的批量作用域信息。
+ * 返回当前作用域栈的只读副本。
+ */
+declare function getCurrentBatchScopeStack(): ReadonlyArray<BatchScopeContext>;
+/**
+ * 检查当前是否在批量作用域内。
+ */
+declare function isInBatchScope(): boolean;
+/**
+ * 等待所有待处理的批量操作完成（异步模式）。
+ * 返回一个 Promise，在所有异步批量操作完成后 resolve。
+ *
+ * FIX: P2-2 flushBatchScopes 中 pendingCallbacks 始终为空（死代码）。
+ * 原因：batchScope 的异步模式使用 batchAsync 而非 pendingCallbacks 注册回调，
+ * 导致 pendingCallbacks 永远不会被填充。移除死代码，避免误导维护者。
+ * 如需等待异步 batchScope 完成，应直接 await batchScopeAsync()。
+ *
+ * FIX: P2-batch1-7 保留原因：
+ * 1. API 兼容性：此函数是公共 API 的一部分，直接删除会导致破坏性变更
+ * 2. 未来扩展：可用于实现等待所有异步 batchScope 完成的功能
+ * 3. 测试用途：提供一种同步刷新所有批量操作的方式（即使当前为空操作）
+ * 4. 类型安全：返回 Promise<void> 与异步 API 签名保持一致
+ *
+ * @deprecated 当前实现为空操作，如需等待异步 batchScope 完成，请直接使用 await batchScopeAsync()
+ */
+declare function flushBatchScopes(): Promise<void>;
+
+/** DevTools 信号依赖信息 */
+interface DevToolsSignalInfo {
+    id: string;
+    name: string;
+    value: unknown;
+    dependencies: string[];
+    dependents: string[];
+}
+/** DevTools effect 信息 */
+interface DevToolsEffectInfo {
+    id: string;
+    name: string;
+    active: boolean;
+    dependencies: string[];
+}
+/** LytJS DevTools 全局对象接口 */
+interface LytJSDevTools {
+    /** 版本号 */
+    version: string;
+    /** 获取所有信号信息 */
+    getSignals: () => DevToolsSignalInfo[];
+    /** 获取所有 effect 信息 */
+    getEffects: () => DevToolsEffectInfo[];
+    /** 监听信号变化 */
+    onSignalChange: (callback: (signalId: string, value: unknown) => void) => () => void;
+    /** 监听 effect 执行 */
+    onEffectRun: (callback: (effectId: string) => void) => () => void;
+    /** 启用/禁用调试 */
+    setEnabled: (enabled: boolean) => void;
+    /** 当前是否启用 */
+    isEnabled: () => boolean;
+}
+/** 调试工具全局对象 */
+declare global {
+    interface Window {
+        __LYTJS_DEVTOOLS__?: LytJSDevTools;
+    }
+}
+/**
+ * 通知 DevTools 信号变化
+ * @internal
+ * FIX: P2-4 使用批处理合并高频通知，减少监听器调用次数
+ */
+declare function _notifyDevToolsSignalChange(signalId: string, value: unknown): void;
+/**
+ * 通知 DevTools effect 执行
+ * @internal
+ * FIX: P2-4 使用批处理合并高频通知，减少监听器调用次数
+ */
+declare function _notifyDevToolsEffectRun(effectId: string): void;
+
+export { type BatchScopeCallback, type BatchScopeContext, type BatchScopeOptions, ComputedGetter, ComputedRef, DeepReadonly, type DevToolsEffectInfo, type DevToolsSignalInfo, type LytJSDevTools, UnwrapNestedRefs, WatchEffectOptions, WatchHandle, WatchOptions, WatchSource, WritableComputedOptions, WritableComputedRef, _notifyDevToolsEffectRun, _notifyDevToolsSignalChange, batchScope, batchScopeAsync, batchScopeUntrack, computed, flushBatchScopes, getBatchScopeDepth, getCurrentBatchScopeStack, isInBatchScope, isProxy, isReactive, isReadonly, isRef, markRaw, reactive, readonly, setSSRMode, shallowReactive, shallowReadonly, toRaw, watch, watchEffect, watchPostEffect, watchSyncEffect };

package/dist/index.d.ts

@@ -0,0 +1,226 @@
+import { U as UnwrapNestedRefs, b as DeepReadonly, C as ComputedGetter, l as WritableComputedOptions, m as WritableComputedRef, k as WatchSource, g as WatchCallbackWithImmediate, j as WatchOptions, i as WatchHandle, O as OnCleanup, h as WatchEffectOptions } from './scope-CTxSo201.js';
+export { a as ComputedSetter, D as DebuggerEvent, E as EffectScope, c as EffectScopeOptions, R as ReactiveEffectOptions, d as ReactiveEffectRunner, e as ReactiveObject, T as ToRefs, f as UnwrapRef, W as WatchCallback, n as batch, o as batchAsync, p as effect, q as effectScope, r as enableTracking, s as getCurrentScope, t as getSkippedTrackingCount, u as onEffectCleanup, v as onScopeDispose, w as pauseTracking, x as resetSkippedTrackingCount, y as resetTracking, z as shouldSkipTracking, A as stop, B as untrack, F as withFirstRenderOptimization } from './scope-CTxSo201.js';
+import { C as ComputedRef } from './ref-CwOCKoy2.js';
+export { R as Ref, S as ShallowRef, c as customRef, i as isComputedRef, a as isShallowRef, r as ref, s as shallowRef, t as toRef, b as toRefs, d as toValue, e as triggerRef, u as unref } from './ref-CwOCKoy2.js';
+export { C as ComputedRefSymbol, a as ComputedSignal, R as ReactiveSymbol, b as ReadonlySignal, c as ReadonlySymbol, d as RefSymbol, S as ShallowRefSymbol, e as Signal, f as Subscriber, W as WritableComputedSignal, g as WritableSignal, m as computedSignal, r as readonlySignal, s as set, n as signal, o as signalBatch, l as signalComputed, p as signalUntrack, u as update, v as valueOf, w as writableComputedSignal } from './signal-DWrUYmvd.js';
+import { RefLike } from '@lytjs/shared-types';
+
+/**
+ * 获取响应式对象的原始值
+ */
+declare function toRaw<T>(observed: T): T;
+/**
+ * 判断一个值是否为 ref
+ */
+declare function isRef<T = unknown>(r: unknown): r is RefLike<T>;
+
+declare function reactive<T extends object>(target: T): UnwrapNestedRefs<T>;
+declare function shallowReactive<T extends object>(target: T): T;
+declare function readonly<T extends object>(target: T): DeepReadonly<UnwrapNestedRefs<T>>;
+declare function shallowReadonly<T extends object>(target: T): Readonly<T>;
+declare function isReactive(value: unknown): boolean;
+declare function isReadonly(value: unknown): boolean;
+declare function isProxy(value: unknown): boolean;
+
+declare function markRaw<T extends object>(value: T): T;
+
+/**
+ * 设置 SSR 模式。
+ * 在 SSR 环境中调用 setSSRMode(true) 可让 computed 在创建时立即求值，
+ * 避免在服务端渲染时因懒求值导致的不一致问题。
+ *
+ * 注意：此设置为模块级全局状态，多实例/测试场景下可能产生状态泄漏。
+ * 如需隔离，请确保不同环境使用独立的模块加载上下文。
+ */
+declare function setSSRMode(isSSR: boolean): void;
+declare function computed<T>(getterOrOptions: ComputedGetter<T> | WritableComputedOptions<T>): ComputedRef<T> | WritableComputedRef<T>;
+
+/**
+ * 侦听一个或多个响应式数据源，并在数据变化时执行回调。
+ *
+ * @param source - 要侦听的数据源，可以是 ref、reactive 对象、getter 函数，或它们的数组
+ * @param cb - 数据变化时的回调函数
+ * @param options - 侦听选项
+ * @returns 停止侦听的句柄函数
+ *
+ * @remarks
+ * 关于 scheduler 参数签名：
+ * watch 的 scheduler 与 ReactiveEffect 的 scheduler 参数签名不同。
+ * - ReactiveEffect.scheduler: () => void（无参数，由 effect 系统内部调用）
+ * - watch scheduler: (job: () => void, ...args: unknown[]) => unknown
+ *   其中 job 是 watch 内部封装的变更检测+回调执行函数。
+ *   当用户提供 scheduler 时，watch 会将 job 作为第一个参数传入，
+ *   用户可以在 scheduler 中决定何时执行 job（如节流、防抖等）。
+ */
+declare function watch<T, Immediate extends Readonly<boolean> = false>(source: WatchSource<T> | WatchSource<T>[], cb: WatchCallbackWithImmediate<T, Immediate>, options?: WatchOptions<Immediate>): WatchHandle;
+declare function watchEffect(effectFn: (onCleanup: OnCleanup) => void, options?: WatchEffectOptions): WatchHandle;
+declare function watchPostEffect(effectFn: (onCleanup: OnCleanup) => void, options?: WatchEffectOptions): WatchHandle;
+declare function watchSyncEffect(effectFn: (onCleanup: OnCleanup) => void, options?: WatchEffectOptions): WatchHandle;
+
+/**
+ * @lytjs/reactivity - batch.ts
+ * FIX: P2-4 REACTIVITY-NEW-05 - 批量操作 API
+ *
+ * 提供 batchScope 函数，支持嵌套批量操作和自动提交。
+ * 允许在批量作用域内执行多个响应式操作，只在作用域结束时统一触发更新。
+ */
+/** 批量作用域配置选项 */
+interface BatchScopeOptions {
+    /** 是否异步提交（默认 false） */
+    async?: boolean;
+    /** 作用域名称（用于调试） */
+    name?: string;
+    /** 错误处理回调 */
+    onError?: (error: unknown) => void;
+}
+/** 批量作用域上下文 */
+interface BatchScopeContext {
+    /** 当前嵌套深度 */
+    depth: number;
+    /** 作用域名称 */
+    name: string;
+    /** 是否已提交 */
+    committed: boolean;
+    /** 是否已取消 */
+    cancelled: boolean;
+}
+/** 批量操作回调 */
+type BatchScopeCallback<T> = (ctx: BatchScopeContext) => T;
+/**
+ * 创建批量作用域并执行回调函数。
+ * 在作用域内所有响应式操作会被批量收集，只在作用域结束时统一触发更新。
+ *
+ * 支持嵌套调用：嵌套的 batchScope 会继承外层的批量状态，
+ * 只有最外层作用域结束时才会真正提交所有更新。
+ *
+ * @example
+ * ```typescript
+ * batchScope((ctx) => {
+ *   signal1.set(1);
+ *   signal2.set(2);
+ *   // 此时不会触发更新
+ *
+ *   batchScope((innerCtx) => {
+ *     signal3.set(3);
+ *     // 嵌套作用域，仍然不会触发更新
+ *   });
+ * });
+ * // 所有更新在这里统一触发
+ * ```
+ *
+ * @param callback - 在批量作用域内执行的回调函数
+ * @param options - 批量作用域配置选项
+ * @returns 回调函数的返回值
+ */
+declare function batchScope<T>(callback: BatchScopeCallback<T>, options?: BatchScopeOptions): T;
+/**
+ * 创建异步批量作用域。
+ * 与 batchScope 类似，但支持 async/await。
+ *
+ * @example
+ * ```typescript
+ * await batchScopeAsync(async (ctx) => {
+ *   signal1.set(1);
+ *   await someAsyncOperation();
+ *   signal2.set(2);
+ * });
+ * ```
+ *
+ * @param callback - 异步回调函数
+ * @param options - 批量作用域配置选项
+ * @returns Promise，在批量作用域完成时 resolve
+ */
+declare function batchScopeAsync<T>(callback: BatchScopeCallback<Promise<T> | T>, options?: BatchScopeOptions): Promise<T>;
+/**
+ * 在批量作用域内执行无追踪操作。
+ * 函数内读取 signal 不会建立依赖关系。
+ *
+ * @param fn - 要执行的函数
+ * @returns 函数的返回值
+ */
+declare function batchScopeUntrack<T>(fn: () => T): T;
+/**
+ * 获取当前批量作用域深度。
+ * 0 表示不在任何批量作用域内。
+ */
+declare function getBatchScopeDepth(): number;
+/**
+ * 获取当前活跃的批量作用域信息。
+ * 返回当前作用域栈的只读副本。
+ */
+declare function getCurrentBatchScopeStack(): ReadonlyArray<BatchScopeContext>;
+/**
+ * 检查当前是否在批量作用域内。
+ */
+declare function isInBatchScope(): boolean;
+/**
+ * 等待所有待处理的批量操作完成（异步模式）。
+ * 返回一个 Promise，在所有异步批量操作完成后 resolve。
+ *
+ * FIX: P2-2 flushBatchScopes 中 pendingCallbacks 始终为空（死代码）。
+ * 原因：batchScope 的异步模式使用 batchAsync 而非 pendingCallbacks 注册回调，
+ * 导致 pendingCallbacks 永远不会被填充。移除死代码，避免误导维护者。
+ * 如需等待异步 batchScope 完成，应直接 await batchScopeAsync()。
+ *
+ * FIX: P2-batch1-7 保留原因：
+ * 1. API 兼容性：此函数是公共 API 的一部分，直接删除会导致破坏性变更
+ * 2. 未来扩展：可用于实现等待所有异步 batchScope 完成的功能
+ * 3. 测试用途：提供一种同步刷新所有批量操作的方式（即使当前为空操作）
+ * 4. 类型安全：返回 Promise<void> 与异步 API 签名保持一致
+ *
+ * @deprecated 当前实现为空操作，如需等待异步 batchScope 完成，请直接使用 await batchScopeAsync()
+ */
+declare function flushBatchScopes(): Promise<void>;
+
+/** DevTools 信号依赖信息 */
+interface DevToolsSignalInfo {
+    id: string;
+    name: string;
+    value: unknown;
+    dependencies: string[];
+    dependents: string[];
+}
+/** DevTools effect 信息 */
+interface DevToolsEffectInfo {
+    id: string;
+    name: string;
+    active: boolean;
+    dependencies: string[];
+}
+/** LytJS DevTools 全局对象接口 */
+interface LytJSDevTools {
+    /** 版本号 */
+    version: string;
+    /** 获取所有信号信息 */
+    getSignals: () => DevToolsSignalInfo[];
+    /** 获取所有 effect 信息 */
+    getEffects: () => DevToolsEffectInfo[];
+    /** 监听信号变化 */
+    onSignalChange: (callback: (signalId: string, value: unknown) => void) => () => void;
+    /** 监听 effect 执行 */
+    onEffectRun: (callback: (effectId: string) => void) => () => void;
+    /** 启用/禁用调试 */
+    setEnabled: (enabled: boolean) => void;
+    /** 当前是否启用 */
+    isEnabled: () => boolean;
+}
+/** 调试工具全局对象 */
+declare global {
+    interface Window {
+        __LYTJS_DEVTOOLS__?: LytJSDevTools;
+    }
+}
+/**
+ * 通知 DevTools 信号变化
+ * @internal
+ * FIX: P2-4 使用批处理合并高频通知，减少监听器调用次数
+ */
+declare function _notifyDevToolsSignalChange(signalId: string, value: unknown): void;
+/**
+ * 通知 DevTools effect 执行
+ * @internal
+ * FIX: P2-4 使用批处理合并高频通知，减少监听器调用次数
+ */
+declare function _notifyDevToolsEffectRun(effectId: string): void;
+
+export { type BatchScopeCallback, type BatchScopeContext, type BatchScopeOptions, ComputedGetter, ComputedRef, DeepReadonly, type DevToolsEffectInfo, type DevToolsSignalInfo, type LytJSDevTools, UnwrapNestedRefs, WatchEffectOptions, WatchHandle, WatchOptions, WatchSource, WritableComputedOptions, WritableComputedRef, _notifyDevToolsEffectRun, _notifyDevToolsSignalChange, batchScope, batchScopeAsync, batchScopeUntrack, computed, flushBatchScopes, getBatchScopeDepth, getCurrentBatchScopeStack, isInBatchScope, isProxy, isReactive, isReadonly, isRef, markRaw, reactive, readonly, setSSRMode, shallowReactive, shallowReadonly, toRaw, watch, watchEffect, watchPostEffect, watchSyncEffect };