@lytjs/devtools 4.2.0 → 6.0.0

package/dist/index.d.ts

@@ -0,0 +1,743 @@
+/**
+ * @lytjs/devtools - 类型定义
+ */
+
+/**
+ * DevTools 配置选项
+ */
+interface DevToolsOptions {
+    /** 是否启用 */
+    enabled?: boolean;
+    /** 面板位置 */
+    position?: 'right' | 'bottom' | 'left';
+    /** 面板宽度/高度 */
+    size?: number;
+}
+/**
+ * 组件树节点
+ */
+interface ComponentTreeNode {
+    id: string;
+    name: string;
+    props?: Record<string, any>;
+    children?: ComponentTreeNode[];
+    parent?: string;
+}
+/**
+ * Store 状态信息
+ */
+interface StoreStateInfo {
+    id: string;
+    state: Record<string, any>;
+    getters?: Record<string, any>;
+}
+/**
+ * 路由信息
+ */
+interface RouteInfo {
+    path: string;
+    name?: string | null;
+    params?: Record<string, string>;
+    query?: Record<string, string>;
+    matched: Array<{
+        path: string;
+        name?: string | null;
+    }>;
+}
+/**
+ * 信号节点信息
+ */
+interface SignalNode$1 {
+    id: string;
+    name: string;
+    type: 'signal' | 'computed' | 'effect';
+    value?: unknown;
+    previousValue?: unknown;
+    dependencies: string[];
+    dependents: string[];
+    updateCount: number;
+    lastUpdateTime: number;
+    averageUpdateTime: number;
+}
+/**
+ * 快照记录
+ */
+interface Snapshot$1 {
+    id: string;
+    timestamp: number;
+    label?: string;
+    signals: Record<string, SignalSnapshot$1>;
+}
+/**
+ * 单个信号的快照
+ */
+interface SignalSnapshot$1 {
+    value: unknown;
+    dependencies: string[];
+}
+/**
+ * 时间旅行状态
+ */
+interface TimeTravelState$1 {
+    snapshots: Snapshot$1[];
+    currentIndex: number;
+    canUndo: boolean;
+    canRedo: boolean;
+}
+/**
+ * 性能记录
+ */
+interface PerformanceRecord$1 {
+    id: string;
+    name: string;
+    type: 'signal' | 'computed' | 'effect';
+    duration: number;
+    timestamp: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 依赖图节点
+ */
+interface DependencyGraphNode$1 {
+    id: string;
+    name: string;
+    type: 'signal' | 'computed' | 'effect';
+    x?: number;
+    y?: number;
+}
+/**
+ * 依赖图边
+ */
+interface DependencyGraphEdge$1 {
+    source: string;
+    target: string;
+    type: 'dependency' | 'dependent';
+}
+/**
+ * 依赖图
+ */
+interface DependencyGraph$1 {
+    nodes: DependencyGraphNode$1[];
+    edges: DependencyGraphEdge$1[];
+}
+/**
+ * 性能统计
+ */
+interface PerformanceStats$1 {
+    totalRecords: number;
+    averageDuration: number;
+    maxDuration: number;
+    minDuration: number;
+    byType: Record<string, {
+        count: number;
+        average: number;
+        max: number;
+    }>;
+}
+/**
+ * DevTools API
+ */
+interface DevToolsAPI {
+    /** 获取组件树 */
+    getComponentTree(): ComponentTreeNode[];
+    /** 获取 Store 状态 */
+    getStoreStates(): StoreStateInfo[];
+    /** 获取当前路由 */
+    getCurrentRoute(): RouteInfo | null;
+    /** 刷新 */
+    refresh(): void;
+}
+
+/**
+ * @lytjs/devtools - 组件树查看器
+ */
+
+/**
+ * 获取组件树
+ */
+declare function getComponentTree(rootComponent?: any): ComponentTreeNode[];
+/**
+ * 序列化组件树为字符串
+ */
+declare function serializeComponentTree(nodes: ComponentTreeNode[], indent?: number): string;
+/**
+ * 注册根组件（供开发时使用）
+ */
+declare function registerRootComponent(component: any): void;
+/**
+ * 清除注册的根组件
+ */
+declare function unregisterRootComponent(): void;
+
+/**
+ * @lytjs/devtools - Store 状态检查器
+ */
+
+/**
+ * Store 变更回调类型
+ */
+type StoreChangeCallback = (storeId: string, state: Record<string, any>) => void;
+/**
+ * 注册 Store
+ */
+declare function registerStore(id: string, store: any): void;
+/**
+ * 注销 Store
+ */
+declare function unregisterStore(id: string): void;
+/**
+ * 获取所有 Store 状态
+ */
+declare function getStoreStates(): StoreStateInfo[];
+/**
+ * 获取特定 Store 的状态
+ */
+declare function getStoreState(storeId: string): StoreStateInfo | null;
+/**
+ * 修改 Store 状态（用于开发时调试）
+ */
+declare function setStoreState(storeId: string, path: string, value: any): boolean;
+/**
+ * 触发 Store Action
+ */
+declare function dispatchStoreAction(storeId: string, actionName: string, ...args: any[]): any;
+/**
+ * 序列化 Store 状态为字符串
+ */
+declare function serializeStoreStates(states: StoreStateInfo[]): string;
+/**
+ * 订阅 Store 变更
+ *
+ * @description
+ * 当 Store 的 $subscribe 方法可用时自动监听变更，
+ * 变更时会触发所有通过 onStoreChange 注册的全局回调
+ *
+ * @param storeId - 要订阅的 Store ID
+ * @returns 是否订阅成功
+ */
+declare function subscribeStore(storeId: string): boolean;
+/**
+ * 取消订阅 Store 变更
+ *
+ * @param storeId - 要取消订阅的 Store ID
+ */
+declare function unsubscribeStore(storeId: string): void;
+/**
+ * 注册全局 Store 变更回调
+ *
+ * @description
+ * 当任何已订阅的 Store 发生变更时，会调用此回调
+ *
+ * @param callback - 变更回调函数，接收 storeId 和当前 state
+ * @returns 取消注册的函数
+ */
+declare function onStoreChange(callback: StoreChangeCallback): () => void;
+/**
+ * 清空所有注册的 Store（用于测试）
+ */
+declare function clearStoreRegistry(): void;
+/**
+ * 获取已注册的 Store ID 列表
+ */
+declare function getRegisteredStoreIds(): string[];
+
+/**
+ * @lytjs/devtools - 路由查看器
+ */
+
+/**
+ * 注册路由器
+ */
+declare function registerRouter(router: any): void;
+/**
+ * 注销路由器
+ */
+declare function unregisterRouter(): void;
+/**
+ * 获取当前路由信息
+ */
+declare function getCurrentRoute(): RouteInfo | null;
+/**
+ * 获取路由历史
+ *
+ * @description
+ * 返回自监听开始以来的所有路由变更记录
+ *
+ * @returns 路由变更历史数组
+ */
+declare function getRouteHistory(): RouteInfo[];
+/**
+ * 监听路由变化
+ *
+ * @description
+ * 利用 router.afterEach 钩子监听路由导航，
+ * 每次导航后将路由信息记录到 routeHistory 中
+ *
+ * @returns 是否成功开始监听
+ */
+declare function watchRouteChanges(): boolean;
+/**
+ * 停止监听路由变化
+ *
+ * @description
+ * 停止路由变更监听，但已记录的历史不会被清除
+ */
+declare function unwatchRouteChanges(): void;
+/**
+ * 导航到指定路径
+ */
+declare function navigateTo(path: string): Promise<void>;
+/**
+ * 导航到指定路由名称
+ */
+declare function navigateToName(name: string, params?: Record<string, string>): Promise<void>;
+/**
+ * 返回上一页
+ */
+declare function goBack(): Promise<void>;
+/**
+ * 序列化路由信息为字符串
+ */
+declare function serializeRouteInfo(route: RouteInfo | null): string;
+/**
+ * 获取所有路由配置
+ */
+declare function getRoutes(): Array<{
+    path: string;
+    name?: string | null;
+}>;
+/**
+ * 检查路由器是否已注册
+ */
+declare function isRouterRegistered(): boolean;
+/**
+ * 清空路由变更历史（用于测试）
+ */
+declare function clearRouteHistory(): void;
+
+/**
+ * @lytjs/devtools - 信号依赖追踪和快照
+ *
+ * 提供时间旅行调试、信号依赖图可视化和性能分析功能
+ */
+interface SignalNode {
+    id: string;
+    name: string;
+    type: 'signal' | 'computed' | 'effect';
+    value?: unknown;
+    previousValue?: unknown;
+    dependencies: string[];
+    dependents: string[];
+    updateCount: number;
+    lastUpdateTime: number;
+    averageUpdateTime: number;
+}
+/** 快照记录 */
+interface Snapshot {
+    id: string;
+    timestamp: number;
+    label?: string;
+    signals: Record<string, SignalSnapshot>;
+}
+/** 单个信号的快照 */
+interface SignalSnapshot {
+    value: unknown;
+    dependencies: string[];
+}
+/** 时间旅行状态 */
+interface TimeTravelState {
+    snapshots: Snapshot[];
+    currentIndex: number;
+    canUndo: boolean;
+    canRedo: boolean;
+}
+/** 性能记录 */
+interface PerformanceRecord {
+    id: string;
+    name: string;
+    type: 'signal' | 'computed' | 'effect';
+    duration: number;
+    timestamp: number;
+    metadata?: Record<string, unknown>;
+}
+/** 依赖图节点 */
+interface DependencyGraphNode {
+    id: string;
+    name: string;
+    type: 'signal' | 'computed' | 'effect';
+    x?: number;
+    y?: number;
+}
+/** 依赖图边 */
+interface DependencyGraphEdge {
+    source: string;
+    target: string;
+    type: 'dependency' | 'dependent';
+}
+/** 依赖图 */
+interface DependencyGraph {
+    nodes: DependencyGraphNode[];
+    edges: DependencyGraphEdge[];
+}
+/**
+ * 注册一个信号
+ */
+declare function registerSignal(id: string, name: string, type: 'signal' | 'computed' | 'effect', initialValue?: unknown): void;
+/**
+ * 注销一个信号
+ */
+declare function unregisterSignal(id: string): void;
+/**
+ * 记录信号更新
+ */
+declare function recordSignalUpdate(id: string, newValue: unknown, duration?: number): void;
+/**
+ * 记录依赖关系
+ */
+declare function recordDependency(sourceId: string, targetId: string): void;
+/**
+ * 获取所有信号节点
+ */
+declare function getSignalNodes(): SignalNode[];
+/**
+ * 获取单个信号节点
+ */
+declare function getSignalNode(id: string): SignalNode | undefined;
+/**
+ * 获取依赖图
+ */
+declare function getDependencyGraph(): DependencyGraph;
+/**
+ * 创建快照
+ */
+declare function createSnapshot(label?: string): Snapshot;
+/**
+ * 获取所有快照
+ */
+declare function getSnapshots(): Snapshot[];
+/**
+ * 获取时间旅行状态
+ */
+declare function getTimeTravelState(): TimeTravelState;
+/**
+ * 恢复到指定快照
+ */
+declare function restoreSnapshot(index: number): Snapshot | undefined;
+/**
+ * 清除所有快照
+ */
+declare function clearSnapshots(): void;
+/**
+ * 获取性能记录
+ */
+declare function getPerformanceRecords(limit?: number): PerformanceRecord[];
+/**
+ * 获取性能统计
+ */
+declare function getPerformanceStats(): {
+    totalRecords: number;
+    averageDuration: number;
+    maxDuration: number;
+    minDuration: number;
+    byType: Record<string, {
+        count: number;
+        average: number;
+        max: number;
+    }>;
+};
+/**
+ * 清除性能记录
+ */
+declare function clearPerformanceRecords(): void;
+/**
+ * 清除所有注册信号
+ */
+declare function clearSignalRegistry(): void;
+/**
+ * 序列化信号节点用于显示
+ */
+declare function serializeSignalNode(node: SignalNode): string;
+/**
+ * 序列化依赖图用于显示
+ */
+declare function serializeDependencyGraph(): string;
+/**
+ * 序列化性能统计
+ */
+declare function serializePerformanceStats(): string;
+
+/**
+ * @lytjs/devtools - 性能监控系统
+ *
+ * 提供性能埋点、性能指标收集、性能告警等功能
+ */
+/** 性能指标类型 */
+type MetricType = 'render' | 'update' | 'effect' | 'computed' | 'reaction' | 'custom';
+/** 性能指标 */
+interface PerformanceMetric {
+    id: string;
+    name: string;
+    type: MetricType;
+    duration: number;
+    timestamp: number;
+    metadata?: Record<string, unknown>;
+}
+/** 告警级别 */
+type AlertLevel = 'info' | 'warning' | 'error' | 'critical';
+/** 告警规则 */
+interface AlertRule {
+    id: string;
+    name: string;
+    level: AlertLevel;
+    condition: (metric: PerformanceMetric, stats: PerformanceStats) => boolean;
+    message: string;
+    enabled: boolean;
+    cooldown: number;
+}
+/** 告警 */
+interface Alert {
+    id: string;
+    ruleId: string;
+    ruleName: string;
+    level: AlertLevel;
+    message: string;
+    metric?: PerformanceMetric;
+    timestamp: number;
+    acknowledged: boolean;
+}
+/** 性能统计 */
+interface PerformanceStats {
+    count: number;
+    total: number;
+    average: number;
+    min: number;
+    max: number;
+    p50: number;
+    p90: number;
+    p99: number;
+}
+/** 监控配置 */
+interface MonitorOptions {
+    /** 是否启用监控 */
+    enabled?: boolean;
+    /** 最大记录数 */
+    maxRecords?: number;
+    /** 默认采样率 (0-1) */
+    sampleRate?: number;
+    /** 是否自动记录页面指标 */
+    autoRecordPageMetrics?: boolean;
+    /** 是否自动记录长任务 */
+    autoRecordLongTasks?: boolean;
+    /** 长任务阈值 (ms) */
+    longTaskThreshold?: number;
+}
+type ObserverCallback = (metric: PerformanceMetric) => void;
+/**
+ * 初始化性能监控
+ */
+declare function initPerformanceMonitor(opts?: MonitorOptions): void;
+/**
+ * 记录性能指标
+ */
+declare function recordMetric(metric: Omit<PerformanceMetric, 'id' | 'timestamp'>): PerformanceMetric;
+/**
+ * 获取所有性能指标
+ */
+declare function getMetrics(limit?: number): PerformanceMetric[];
+/**
+ * 获取性能统计
+ */
+declare function getStats(type?: MetricType): PerformanceStats;
+/**
+ * 注册告警规则
+ */
+declare function registerAlertRule(rule: AlertRule): void;
+/**
+ * 注销告警规则
+ */
+declare function unregisterAlertRule(ruleId: string): void;
+/**
+ * 启用/禁用告警规则
+ */
+declare function setAlertRuleEnabled(ruleId: string, enabled: boolean): void;
+/**
+ * 获取所有告警规则
+ */
+declare function getAlertRules(): AlertRule[];
+/**
+ * 获取当前告警
+ */
+declare function getAlerts(includeAcknowledged?: boolean): Alert[];
+/**
+ * 确认告警
+ */
+declare function acknowledgeAlert(alertId: string): void;
+/**
+ * 确认所有告警
+ */
+declare function acknowledgeAllAlerts(): void;
+/**
+ * 清除告警记录
+ */
+declare function clearAlerts(): void;
+/**
+ * 添加观察者
+ */
+declare function addObserver(callback: ObserverCallback): void;
+/**
+ * 移除观察者
+ */
+declare function removeObserver(callback: ObserverCallback): void;
+/**
+ * 清除所有性能记录
+ */
+declare function clearMetrics(): void;
+/**
+ * 重置性能监控
+ */
+declare function resetPerformanceMonitor(): void;
+/**
+ * 获取性能报告
+ */
+declare function getPerformanceReport(): {
+    metrics: PerformanceMetric[];
+    stats: Record<MetricType, PerformanceStats>;
+    alerts: Alert[];
+    summary: {
+        totalMetrics: number;
+        totalAlerts: number;
+        unacknowledgedAlerts: number;
+        averageDuration: number;
+    };
+};
+/**
+ * 序列化性能报告（用于显示）
+ */
+declare function serializePerformanceReport(): string;
+/**
+ * 创建计时器
+ */
+declare function startTimer(name: string, type?: MetricType): () => void;
+
+/**
+ * @lytjs/devtools - 大规模性能压测基准测试
+ *
+ * 提供虚拟列表、组件渲染等大规模场景的性能基准测试
+ */
+/** 基准测试结果 */
+interface BenchmarkResult {
+    name: string;
+    iterations: number;
+    totalDuration: number;
+    averageDuration: number;
+    minDuration: number;
+    maxDuration: number;
+    opsPerSecond: number;
+    timestamp: number;
+}
+/** 基准测试配置 */
+interface BenchmarkConfig {
+    /** 测试名称 */
+    name: string;
+    /** 迭代次数 */
+    iterations: number;
+    /** 预热次数 */
+    warmup?: number;
+    /** 异步测试回调 */
+    fn: () => void | Promise<void>;
+    /** 异步回调 */
+    asyncFn?: () => Promise<void>;
+}
+/** 大规模场景配置 */
+interface LargeScaleScenario {
+    name: string;
+    nodeCount: number;
+    description: string;
+}
+/** 预定义的大规模场景 */
+declare const LARGE_SCALE_SCENARIOS: LargeScaleScenario[];
+/**
+ * 运行同步基准测试
+ */
+declare function runBenchmark(config: BenchmarkConfig): BenchmarkResult;
+/**
+ * 运行异步基准测试
+ */
+declare function runAsyncBenchmark(config: BenchmarkConfig): Promise<BenchmarkResult>;
+/**
+ * 获取基准测试结果
+ */
+declare function getBenchmarkResults(name?: string): BenchmarkResult[];
+/**
+ * 获取最新基准测试结果
+ */
+declare function getLatestBenchmarkResult(name: string): BenchmarkResult | undefined;
+/**
+ * 清除基准测试结果
+ */
+declare function clearBenchmarkResults(name?: string): void;
+/**
+ * 序列化基准测试结果
+ */
+declare function serializeBenchmarkResult(result: BenchmarkResult): string;
+/**
+ * 序列化所有基准测试结果
+ */
+declare function serializeAllBenchmarkResults(): string;
+/**
+ * 比较两次基准测试
+ */
+declare function compareBenchmarkResults(oldResult: BenchmarkResult, newResult: BenchmarkResult): {
+    durationDiff: number;
+    durationDiffPercent: number;
+    opsDiff: number;
+    opsDiffPercent: number;
+    improved: boolean;
+};
+/**
+ * 生成大规模测试场景的基准测试
+ */
+declare function createLargeScaleBenchmark(scenario: LargeScaleScenario, testFn: (nodeCount: number) => void | Promise<void>): BenchmarkConfig;
+/**
+ * 内存使用情况
+ */
+interface MemoryUsage {
+    usedJSHeapSize: number;
+    totalJSHeapSize: number;
+    jsHeapSizeLimit: number;
+}
+/**
+ * 获取当前内存使用情况
+ */
+declare function getMemoryUsage(): MemoryUsage | null;
+/**
+ * 序列化内存使用情况
+ */
+declare function serializeMemoryUsage(usage: MemoryUsage): string;
+/**
+ * 创建性能回归检测
+ */
+declare function createRegressionDetector(threshold?: number): {
+    addResult(result: BenchmarkResult): boolean;
+    getHistory(name: string): BenchmarkResult[];
+    clear(): void;
+};
+
+/**
+ * @lytjs/devtools - 开发者工具主入口
+ */
+
+/**
+ * 安装 DevTools
+ */
+declare function installDevTools(options?: DevToolsOptions): DevToolsAPI;
+/**
+ * 获取 DevTools 实例
+ */
+declare function getDevTools(): DevToolsAPI | null;
+/**
+ * 卸载 DevTools
+ */
+declare function uninstallDevTools(): void;
+
+export { type Alert, type AlertLevel, type AlertRule, type BenchmarkConfig, type BenchmarkResult, type ComponentTreeNode, type DependencyGraph$1 as DependencyGraph, type PerformanceStats$1 as DevPerformanceStats, type DevToolsAPI, type DevToolsOptions, LARGE_SCALE_SCENARIOS, type LargeScaleScenario, type MemoryUsage, type MetricType, type MonitorOptions, type PerformanceMetric, type PerformanceRecord$1 as PerformanceRecord, type RouteInfo, type SignalNode$1 as SignalNode, type Snapshot$1 as Snapshot, type StoreStateInfo, type TimeTravelState$1 as TimeTravelState, acknowledgeAlert, acknowledgeAllAlerts, addObserver, clearAlerts, clearBenchmarkResults, clearMetrics, clearPerformanceRecords, clearRouteHistory, clearSignalRegistry, clearSnapshots, clearStoreRegistry, compareBenchmarkResults, createLargeScaleBenchmark, createRegressionDetector, createSnapshot, installDevTools as default, dispatchStoreAction, getAlertRules, getAlerts, getBenchmarkResults, getComponentTree, getCurrentRoute, getDependencyGraph, getDevTools, getLatestBenchmarkResult, getMemoryUsage, getMetrics, getPerformanceRecords, getPerformanceReport, getPerformanceStats, getRegisteredStoreIds, getRouteHistory, getRoutes, getSignalNode, getSignalNodes, getSnapshots, getStats, getStoreState, getStoreStates, getTimeTravelState, goBack, initPerformanceMonitor, installDevTools, isRouterRegistered, navigateTo, navigateToName, onStoreChange, recordDependency, recordMetric, recordSignalUpdate, registerAlertRule, registerRootComponent, registerRouter, registerSignal, registerStore, removeObserver, resetPerformanceMonitor, restoreSnapshot, runAsyncBenchmark, runBenchmark, serializeAllBenchmarkResults, serializeBenchmarkResult, serializeComponentTree, serializeDependencyGraph, serializeMemoryUsage, serializePerformanceReport, serializePerformanceStats, serializeRouteInfo, serializeSignalNode, serializeStoreStates, setAlertRuleEnabled, setStoreState, startTimer, subscribeStore, uninstallDevTools, unregisterAlertRule, unregisterRootComponent, unregisterRouter, unregisterSignal, unregisterStore, unsubscribeStore, unwatchRouteChanges, watchRouteChanges };