030b5801d3
新增纯 TS 轮询基线组件 task-polling-baseline:累计轮询请求数、每次 批量响应的总字节与单次最大响应、按条目数/字节双上限的有界内存缓存 (超限驱逐最旧条目),失败路径零状态变更。useTaskProgressLoop 新增 可选 onBaseline 选项接入基线(默认零行为变化)。测试用 Node 24 原生 type-stripping + node:test 运行(npm test),8 个用例覆盖默认路径、 批量、幂等、空输入、单元素、限流溢出、非法输入与失败恢复。
146 lines
4.7 KiB
TypeScript
146 lines
4.7 KiB
TypeScript
/**
|
|
* 前端任务轮询基线(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<number, CacheEntry>()
|
|
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<T>(
|
|
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<typeof createTaskPollingBaseline>
|