|
| 1 | +/** |
| 2 | + * `costs()` — the cost tables: scopes ranked by the self-time they burn, |
| 3 | + * root writes ranked by the downstream re-run time they cause. Folded from |
| 4 | + * every `RerunEvent` as the engine records it. |
| 5 | + * |
| 6 | + * Its own module on purpose: the tables register with the engine's fold seam |
| 7 | + * when this module is evaluated, so an observe-tier consumer that only |
| 8 | + * subscribes to records (an APM adapter) never ships the accumulation or the |
| 9 | + * tables; a consumer that imports `costs` gets both. Reset with the engine on |
| 10 | + * `enable()`/`disable()`. |
| 11 | + */ |
| 12 | +import { registerFold, rootsOf, type RerunEvent } from "./attribution.js"; |
| 13 | +import type { Computed } from "./types.js"; |
| 14 | + |
| 15 | +export interface ScopeCost { |
| 16 | + name: string; |
| 17 | + kind: "effect" | "memo"; |
| 18 | + runs: number; |
| 19 | + selfMs: number; |
| 20 | + /** |
| 21 | + * Self-time of PLAIN, non-held runs that produced an unchanged value — |
| 22 | + * the recoverable number. Overlay runs (optimistic/transition) are never |
| 23 | + * counted here: an optimistic recompute landing back on the committed |
| 24 | + * value is the mechanism working, not waste. |
| 25 | + */ |
| 26 | + wastedMs: number; |
| 27 | + /** Self-time spent in optimistic/transition (overlay) runs. */ |
| 28 | + overlayMs: number; |
| 29 | +} |
| 30 | +export interface WriteCost { |
| 31 | + /** Root cause name (a signal write, async landing, or refresh target). */ |
| 32 | + name: string; |
| 33 | + /** Number of downstream re-runs this root triggered. */ |
| 34 | + runs: number; |
| 35 | + /** Summed self-time of every downstream re-run it caused. */ |
| 36 | + downstreamMs: number; |
| 37 | +} |
| 38 | +export interface AttributionCostTables { |
| 39 | + /** Ranked by self-time. */ |
| 40 | + scopes: ScopeCost[]; |
| 41 | + /** Ranked by the total downstream re-run time each root write caused. */ |
| 42 | + writes: WriteCost[]; |
| 43 | +} |
| 44 | + |
| 45 | +const scopeCosts = new Map<Computed<any>, ScopeCost>(); |
| 46 | +const writeCosts = new Map<string, WriteCost>(); |
| 47 | + |
| 48 | +function recordCosts(el: Computed<any>, event: RerunEvent): void { |
| 49 | + let scope = scopeCosts.get(el); |
| 50 | + if (scope === undefined) { |
| 51 | + scope = { |
| 52 | + name: event.nodeName, |
| 53 | + kind: event.nodeKind, |
| 54 | + runs: 0, |
| 55 | + selfMs: 0, |
| 56 | + wastedMs: 0, |
| 57 | + overlayMs: 0 |
| 58 | + }; |
| 59 | + scopeCosts.set(el, scope); |
| 60 | + } |
| 61 | + scope.runs++; |
| 62 | + scope.selfMs += event.selfMs; |
| 63 | + if (event.phase !== "plain") scope.overlayMs += event.selfMs; |
| 64 | + else if (!event.changed && !event.held) scope.wastedMs += event.selfMs; |
| 65 | + const roots = new Set<string>(); |
| 66 | + rootsOf(event.causes, roots); |
| 67 | + for (const name of roots) { |
| 68 | + let write = writeCosts.get(name); |
| 69 | + if (write === undefined) writeCosts.set(name, (write = { name, runs: 0, downstreamMs: 0 })); |
| 70 | + write.runs++; |
| 71 | + write.downstreamMs += event.selfMs; |
| 72 | + } |
| 73 | +} |
| 74 | + |
| 75 | +registerFold({ |
| 76 | + rerun: recordCosts, |
| 77 | + reset() { |
| 78 | + scopeCosts.clear(); |
| 79 | + writeCosts.clear(); |
| 80 | + } |
| 81 | +}); |
| 82 | + |
| 83 | +/** |
| 84 | + * Aggregated cost tables since `enable()`: `scopes` ranked by self-time |
| 85 | + * (with `wastedMs` = time spent on unchanged-value runs), `writes` ranked by |
| 86 | + * total downstream re-run time each root write caused. |
| 87 | + */ |
| 88 | +export function costs(): AttributionCostTables { |
| 89 | + return { |
| 90 | + scopes: [...scopeCosts.values()].sort((a, b) => b.selfMs - a.selfMs), |
| 91 | + writes: [...writeCosts.values()].sort((a, b) => b.downstreamMs - a.downstreamMs) |
| 92 | + }; |
| 93 | +} |
0 commit comments