@sdeverywhere/check-core 0.1.10 → 0.1.11

package/dist/index.d.cts

@@ -1377,15 +1377,50 @@ interface ComparisonViewGroup {
     views: (ComparisonView | ComparisonUnresolvedView)[];
 }
 
+/**
+ * A summary of timing samples collected during a performance run.
+ */
 interface PerfReport {
+    /** Minimum sample time, in milliseconds. */
     readonly minTime: number;
+    /** Maximum sample time, in milliseconds. */
     readonly maxTime: number;
+    /**
+     * Trimmed mean (interquartile mean) computed from the middle 50% of samples,
+     * in milliseconds.  This is more robust against outliers than a simple mean.
+     */
     readonly avgTime: number;
+    /** Median (50th percentile) sample time, in milliseconds. */
+    readonly medianTime: number;
+    /** 95th percentile sample time, in milliseconds. */
+    readonly p95Time: number;
+    /** Population standard deviation across all samples, in milliseconds. */
+    readonly stdDev: number;
+    /** All recorded sample times, sorted ascending, in milliseconds. */
     readonly allTimes: number[];
 }
+/**
+ * Collect performance timing samples and produce a robust statistical summary.
+ */
 declare class PerfStats {
     private readonly times;
+    /**
+     * Record a single run time sample.
+     *
+     * @param timeInMillis The run time in milliseconds.
+     */
     addRun(timeInMillis: number): void;
+    /**
+     * Get the raw run time samples that have been recorded.
+     *
+     * @returns A copy of the recorded run times, in insertion order.
+     */
+    getTimes(): number[];
+    /**
+     * Produce a `PerfReport` summarizing the recorded samples.
+     *
+     * @returns The summary report.
+     */
     toReport(): PerfReport;
 }
 

package/dist/index.d.ts

@@ -1377,15 +1377,50 @@ interface ComparisonViewGroup {
     views: (ComparisonView | ComparisonUnresolvedView)[];
 }
 
+/**
+ * A summary of timing samples collected during a performance run.
+ */
 interface PerfReport {
+    /** Minimum sample time, in milliseconds. */
     readonly minTime: number;
+    /** Maximum sample time, in milliseconds. */
     readonly maxTime: number;
+    /**
+     * Trimmed mean (interquartile mean) computed from the middle 50% of samples,
+     * in milliseconds.  This is more robust against outliers than a simple mean.
+     */
     readonly avgTime: number;
+    /** Median (50th percentile) sample time, in milliseconds. */
+    readonly medianTime: number;
+    /** 95th percentile sample time, in milliseconds. */
+    readonly p95Time: number;
+    /** Population standard deviation across all samples, in milliseconds. */
+    readonly stdDev: number;
+    /** All recorded sample times, sorted ascending, in milliseconds. */
     readonly allTimes: number[];
 }
+/**
+ * Collect performance timing samples and produce a robust statistical summary.
+ */
 declare class PerfStats {
     private readonly times;
+    /**
+     * Record a single run time sample.
+     *
+     * @param timeInMillis The run time in milliseconds.
+     */
     addRun(timeInMillis: number): void;
+    /**
+     * Get the raw run time samples that have been recorded.
+     *
+     * @returns A copy of the recorded run times, in insertion order.
+     */
+    getTimes(): number[];
+    /**
+     * Produce a `PerfReport` summarizing the recorded samples.
+     *
+     * @returns The summary report.
+     */
     toReport(): PerfReport;
 }
 

package/dist/index.js

@@ -4576,34 +4576,76 @@ function handleRenames(origCurrentBundle, renamedDatasetKeys) {
 import { assertNever as assertNever11 } from "assert-never";
 
 // src/perf/perf-stats.ts
+function percentile(sorted, p) {
+  if (sorted.length === 1) {
+    return sorted[0];
+  }
+  const rank = p * (sorted.length - 1);
+  const lo = Math.floor(rank);
+  const hi = Math.ceil(rank);
+  if (lo === hi) {
+    return sorted[lo];
+  }
+  const frac = rank - lo;
+  return sorted[lo] + (sorted[hi] - sorted[lo]) * frac;
+}
 var PerfStats = class {
   constructor() {
     this.times = [];
   }
+  /**
+   * Record a single run time sample.
+   *
+   * @param timeInMillis The run time in milliseconds.
+   */
   addRun(timeInMillis) {
     this.times.push(timeInMillis);
   }
+  /**
+   * Get the raw run time samples that have been recorded.
+   *
+   * @returns A copy of the recorded run times, in insertion order.
+   */
+  getTimes() {
+    return this.times.slice();
+  }
+  /**
+   * Produce a `PerfReport` summarizing the recorded samples.
+   *
+   * @returns The summary report.
+   */
   toReport() {
     if (this.times.length === 0) {
       return {
         minTime: 0,
         maxTime: 0,
         avgTime: 0,
+        medianTime: 0,
+        p95Time: 0,
+        stdDev: 0,
         allTimes: []
       };
     }
-    const minTime = Math.min(...this.times);
-    const maxTime = Math.max(...this.times);
-    const sortedTimes = this.times.sort();
-    const minIndex = Math.floor(sortedTimes.length / 4);
-    const maxIndex = minIndex + Math.ceil(sortedTimes.length / 2);
+    const sortedTimes = this.times.slice().sort((a, b) => a - b);
+    const n = sortedTimes.length;
+    const minTime = sortedTimes[0];
+    const maxTime = sortedTimes[n - 1];
+    const minIndex = Math.floor(n / 4);
+    const maxIndex = minIndex + Math.max(1, Math.ceil(n / 2));
     const middleTimes = sortedTimes.slice(minIndex, maxIndex);
-    const totalTime = middleTimes.reduce((a, b) => a + b, 0);
-    const avgTime = totalTime / middleTimes.length;
+    const avgTime = middleTimes.reduce((a, b) => a + b, 0) / middleTimes.length;
+    const medianTime = percentile(sortedTimes, 0.5);
+    const p95Time = percentile(sortedTimes, 0.95);
+    const mean = sortedTimes.reduce((a, b) => a + b, 0) / n;
+    const variance = sortedTimes.reduce((acc, t) => acc + (t - mean) * (t - mean), 0) / n;
+    const stdDev = Math.sqrt(variance);
     return {
       minTime,
       maxTime,
       avgTime,
+      medianTime,
+      p95Time,
+      stdDev,
       allTimes: sortedTimes
     };
   }