/** * 前端任务轮询基线(Task 81)。 * * 为浏览器端的任务轮询建立三条可观测、有界的基线: * - 请求量:recordRequest() 记录发起的轮询请求次数; * - 响应体大小:recordResponseItems() 累计每次批量进度响应(整个 items 数组)的字节数,并记录单次最大响应; * - 页面内存:最近一次响应按条目保留在内存缓存中(条目数 / 缓存字节双上限), * 超限时驱逐最旧条目,保证缓存有界、不随任务数量无界增长。 * * 该组件是纯 TS、无副作用模块,供 useTaskProgressLoop 及其测试复用; * 所有统计在 reset() 前单调累加,key 提取或序列化失败时整个调用失败且不产生任何状态变更。 */ export interface TaskPollingBaselineOptions { /** 缓存最大条目数,默认 500 */ maxEntries?: number /** 缓存最大字节数,默认 1 MiB */ maxCacheBytes?: number } export interface TaskPollingBaselineStats { /** 累计轮询请求次数 */ requestCount: number /** 累计响应体总字节数 */ totalResponseBytes: number /** 单次最大响应体字节数 */ largestResponseBytes: number /** 缓存中的条目数 */ entryCount: number /** 缓存占用字节数 */ cachedBytes: number /** 被驱逐或拒绝的条目数 */ droppedCount: number /** 缓存条目 key(按首次到达顺序) */ entryKeys: number[] } /** 每条缓存条目的固定估算开销:key + 记录结构 + 文本编码余量 */ const ENTRY_OVERHEAD = 64 const DEFAULT_MAX_ENTRIES = 500 const DEFAULT_MAX_CACHE_BYTES = 1024 * 1024 interface CacheEntry { bytes: number } export function createTaskPollingBaseline(options: TaskPollingBaselineOptions = {}) { const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES const maxCacheBytes = options.maxCacheBytes ?? DEFAULT_MAX_CACHE_BYTES if (!(maxEntries > 0) || !(maxCacheBytes > 0)) { throw new Error('上限配置必须为正数: maxEntries=' + maxEntries + ', maxCacheBytes=' + maxCacheBytes) } const cache = new Map() let requestCount = 0 let totalResponseBytes = 0 let largestResponseBytes = 0 let cachedBytes = 0 let droppedCount = 0 function evictIfNeeded() { while (cache.size > maxEntries || cachedBytes > maxCacheBytes) { const oldest = cache.keys().next().value as number | undefined if (oldest == null) break const entry = cache.get(oldest) cache.delete(oldest) cachedBytes -= entry ? entry.bytes : 0 droppedCount += 1 } } function recordRequest() { requestCount += 1 } /** * 记录一次批量进度响应,返回成功写入缓存的条目数。 * items 非数组、extractKey 非函数或 key 提取抛错时整个调用失败,不产生任何状态变更。 */ function recordResponseItems( items: T[], extractKey: (item: T) => number | null | undefined, ): number { if (!Array.isArray(items)) throw new Error('items 必须是数组') if (typeof extractKey !== 'function') throw new Error('extractKey 必须是函数') const encoder = new TextEncoder() const prepared: Array<{ key: number; bytes: number }> = [] let arrayBytes = 0 if (items.length > 0) { arrayBytes = encoder.encode(JSON.stringify(items)).byteLength } for (const item of items) { const serialized = JSON.stringify(item) const bytes = encoder.encode(serialized).byteLength + ENTRY_OVERHEAD const key = extractKey(item) if (typeof key === 'number' && Number.isFinite(key) && key > 0) { prepared.push({ key, bytes }) } } // 全部校验与序列化通过后才提交统计,保证失败路径零状态变更 totalResponseBytes += arrayBytes if (arrayBytes > largestResponseBytes) largestResponseBytes = arrayBytes let inserted = 0 for (const { key, bytes } of prepared) { if (bytes > maxCacheBytes) { droppedCount += 1 continue } const existing = cache.get(key) if (existing) cachedBytes -= existing.bytes cache.set(key, { bytes }) cachedBytes += bytes inserted += 1 evictIfNeeded() } return inserted } function reset() { cache.clear() requestCount = 0 totalResponseBytes = 0 largestResponseBytes = 0 cachedBytes = 0 droppedCount = 0 } function stats(): TaskPollingBaselineStats { return { requestCount, totalResponseBytes, largestResponseBytes, entryCount: cache.size, cachedBytes, droppedCount, entryKeys: [...cache.keys()], } } return { recordRequest, recordResponseItems, reset, stats } } export type TaskPollingBaseline = ReturnType