@iann29/rastro 0.1.0-alpha.1 → 0.1.0-alpha.11

package/src/component/vitals.ts

@@ -0,0 +1,146 @@
+import { VITAL_HISTOGRAM_EDGES, MAX_VITAL_VALUE } from "./constants.js";
+
+/**
+ * Field-measured Web Vitals. Values are integers: milliseconds for the time
+ * metrics, and CLS scaled by 1000 so one shared histogram covers every metric.
+ */
+export const VITAL_METRICS = ["LCP", "CLS", "INP", "FCP", "TTFB"] as const;
+
+export type VitalMetric = (typeof VITAL_METRICS)[number];
+
+/**
+ * The Google-published rating thresholds. Every threshold is also a histogram
+ * edge, so good/needs-improvement/poor counts are exact, never interpolated.
+ */
+export const VITAL_THRESHOLDS: Record<
+  VitalMetric,
+  { good: number; poor: number }
+> = {
+  LCP: { good: 2_500, poor: 4_000 },
+  CLS: { good: 100, poor: 250 },
+  INP: { good: 200, poor: 500 },
+  FCP: { good: 1_800, poor: 3_000 },
+  TTFB: { good: 800, poor: 1_800 },
+};
+
+/** Sentinel row keys; sanitized paths always start with "/" so neither collides. */
+export const VITAL_ALL = "(all)";
+export const VITAL_OTHER_PAGES = "(other)";
+
+/** Bounded device classes; anything else folds into "unknown". */
+export const VITAL_DEVICES = ["desktop", "mobile", "tablet"] as const;
+
+export function vitalDevice(device: string | undefined): string {
+  return device && (VITAL_DEVICES as readonly string[]).includes(device)
+    ? device
+    : "unknown";
+}
+
+export const VITAL_HISTOGRAM_BUCKETS = VITAL_HISTOGRAM_EDGES.length + 1;
+
+export function isVitalMetric(value: string): value is VitalMetric {
+  return (VITAL_METRICS as readonly string[]).includes(value);
+}
+
+export function isValidVitalValue(value: number): boolean {
+  return Number.isFinite(value) && value >= 0 && value <= MAX_VITAL_VALUE;
+}
+
+export function emptyVitalHistogram(): number[] {
+  return Array.from({ length: VITAL_HISTOGRAM_BUCKETS }, () => 0);
+}
+
+/** Bucket i holds values in (edge[i-1], edge[i]]; the last bucket is open. */
+export function vitalHistogramBucket(value: number): number {
+  for (let index = 0; index < VITAL_HISTOGRAM_EDGES.length; index += 1) {
+    if (value <= VITAL_HISTOGRAM_EDGES[index]) return index;
+  }
+  return VITAL_HISTOGRAM_EDGES.length;
+}
+
+export function addToVitalHistogram(
+  histogram: number[],
+  value: number,
+): number[] {
+  const next = normalizedVitalHistogram(histogram);
+  next[vitalHistogramBucket(value)] += 1;
+  return next;
+}
+
+export function mergeVitalHistograms(
+  left: number[],
+  right: number[],
+): number[] {
+  const result = normalizedVitalHistogram(left);
+  const addition = normalizedVitalHistogram(right);
+  for (let index = 0; index < result.length; index += 1) {
+    result[index] += addition[index];
+  }
+  return result;
+}
+
+/**
+ * Percentile estimated by linear interpolation inside the winning bucket. The
+ * top bucket is open-ended, so estimates saturate at the highest edge; a
+ * reported p75 equal to that edge means "at least this much".
+ */
+export function vitalHistogramPercentile(
+  histogram: number[],
+  fraction: number,
+): number {
+  const buckets = normalizedVitalHistogram(histogram);
+  const total = buckets.reduce((sum, count) => sum + count, 0);
+  if (total === 0) return 0;
+  const target = Math.ceil(total * fraction);
+  let cumulative = 0;
+  for (let index = 0; index < buckets.length; index += 1) {
+    const count = buckets[index];
+    if (count === 0) continue;
+    if (cumulative + count >= target) {
+      const lower = index === 0 ? 0 : VITAL_HISTOGRAM_EDGES[index - 1];
+      const upper =
+        index < VITAL_HISTOGRAM_EDGES.length
+          ? VITAL_HISTOGRAM_EDGES[index]
+          : VITAL_HISTOGRAM_EDGES[VITAL_HISTOGRAM_EDGES.length - 1];
+      const position = (target - cumulative) / count;
+      return Math.round(Math.min(upper, lower + position * (upper - lower)));
+    }
+    cumulative += count;
+  }
+  return VITAL_HISTOGRAM_EDGES[VITAL_HISTOGRAM_EDGES.length - 1];
+}
+
+/** Exact rating counts; every threshold is a bucket edge by construction. */
+export function vitalRatingCounts(
+  histogram: number[],
+  metric: VitalMetric,
+): { good: number; needsImprovement: number; poor: number } {
+  const buckets = normalizedVitalHistogram(histogram);
+  const thresholds = VITAL_THRESHOLDS[metric];
+  let good = 0;
+  let needsImprovement = 0;
+  let poor = 0;
+  for (let index = 0; index < buckets.length; index += 1) {
+    const upper =
+      index < VITAL_HISTOGRAM_EDGES.length
+        ? VITAL_HISTOGRAM_EDGES[index]
+        : Number.POSITIVE_INFINITY;
+    if (upper <= thresholds.good) good += buckets[index];
+    else if (upper <= thresholds.poor) needsImprovement += buckets[index];
+    else poor += buckets[index];
+  }
+  return { good, needsImprovement, poor };
+}
+
+function normalizedVitalHistogram(histogram: number[]): number[] {
+  const result = Array.from({ length: VITAL_HISTOGRAM_BUCKETS }, () => 0);
+  for (
+    let index = 0;
+    index < Math.min(histogram.length, result.length);
+    index += 1
+  ) {
+    const count = histogram[index];
+    result[index] = Number.isSafeInteger(count) && count > 0 ? count : 0;
+  }
+  return result;
+}