benchforge 0.1.9 → 0.2.4

package/dist/StatisticalUtils-BD92crgM.mjs

@@ -0,0 +1,255 @@
+//#region src/stats/StatisticalUtils.ts
+const defaultConfidence = .95;
+const bootstrapSamples = 1e4;
+const maxBootstrapInput = 1e4;
+/** Swap direction labels for higher-is-better metrics (positive = faster) */
+function swapDirection(ci) {
+	const swap = {
+		faster: "slower",
+		slower: "faster",
+		uncertain: "uncertain",
+		equivalent: "equivalent"
+	};
+	return {
+		...ci,
+		direction: swap[ci.direction]
+	};
+}
+/** Negate percent and CI for "higher is better" metrics (e.g., throughput) */
+function flipCI(ci) {
+	return {
+		...ci,
+		percent: -ci.percent,
+		ci: [-ci.ci[1], -ci.ci[0]],
+		histogram: ci.histogram?.map((bin) => ({
+			x: -bin.x,
+			count: bin.count
+		}))
+	};
+}
+/** Compute a statistic from samples by kind */
+function computeStat(samples, kind) {
+	if (kind === "mean") return average(samples);
+	if (kind === "min") return minOf(samples);
+	if (kind === "max") return maxOf(samples);
+	return percentile(samples, kind.percentile);
+}
+/** @return true if the stat kind supports bootstrap CI (min/max don't) */
+function isBootstrappable(kind) {
+	return kind !== "min" && kind !== "max";
+}
+/** @return smallest value in samples (loop to avoid spread-arg limits) */
+function minOf(samples) {
+	let min = samples[0];
+	for (let i = 1; i < samples.length; i++) if (samples[i] < min) min = samples[i];
+	return min;
+}
+/** @return largest value in samples (loop to avoid spread-arg limits) */
+function maxOf(samples) {
+	let max = samples[0];
+	for (let i = 1; i < samples.length; i++) if (samples[i] > max) max = samples[i];
+	return max;
+}
+/** @return relative standard deviation (coefficient of variation) */
+function coefficientOfVariation(samples) {
+	const mean = average(samples);
+	if (mean === 0) return 0;
+	return standardDeviation(samples) / mean;
+}
+/** @return median absolute deviation for robust variability measure */
+function medianAbsoluteDeviation(samples) {
+	const med = median(samples);
+	return median(samples.map((x) => Math.abs(x - med)));
+}
+/** Shared-resample bootstrap: one resample per iteration, all stats computed on it.
+*  Mean is computed first (non-destructive), then percentiles via in-place quickSelect. */
+function multiSampleBootstrap(samples, stats, options = {}) {
+	const { resamples = bootstrapSamples, confidence: conf = defaultConfidence } = options;
+	const sub = subsample(samples, maxBootstrapInput);
+	const n = sub.length;
+	const buf = new Array(n);
+	const ops = buildStatOps(stats, n);
+	const allStats = ops.map(() => new Array(resamples));
+	for (let i = 0; i < resamples; i++) {
+		resampleInto(sub, buf);
+		for (let j = 0; j < ops.length; j++) allStats[j][i] = ops[j].compute(buf);
+	}
+	const capped = sub !== samples;
+	const results = new Array(stats.length);
+	for (let j = 0; j < ops.length; j++) results[ops[j].origIndex] = {
+		estimate: ops[j].pointEstimate(samples),
+		ci: computeInterval(allStats[j], conf),
+		samples: allStats[j],
+		ciLevel: "sample",
+		...capped && { subsampled: samples.length }
+	};
+	return results;
+}
+/** Bootstrap CIs for multiple stats, dispatching block vs sample automatically.
+*  Returns undefined for non-bootstrappable stats (min/max). */
+function bootstrapCIs(samples, batchOffsets, stats, options) {
+	const bsStats = stats.filter(isBootstrappable);
+	if (bsStats.length === 0) return stats.map(() => void 0);
+	const bsResults = (batchOffsets?.length ?? 0) >= 2 ? bsStats.map((s) => blockBootstrap(samples, batchOffsets, statKindToFn(s), options)) : multiSampleBootstrap(samples, bsStats, options);
+	const results = new Array(stats.length);
+	let bi = 0;
+	for (let i = 0; i < stats.length; i++) results[i] = isBootstrappable(stats[i]) ? bsResults[bi++] : void 0;
+	return results;
+}
+/** Convert StatKind to a stat function */
+function statKindToFn(kind) {
+	if (kind === "mean") return average;
+	if (kind === "min") return minOf;
+	if (kind === "max") return maxOf;
+	const p = kind.percentile;
+	return (s) => percentile(s, p);
+}
+/** Block bootstrap CI: Tukey-trim outlier batches, then resample per-block
+*  statFn values as independent observations. Requires 2+ blocks. */
+function blockBootstrap(samples, blocks, statFn, options = {}) {
+	const { resamples = bootstrapSamples, confidence: conf = defaultConfidence } = options;
+	const side = prepareBlocks(samples, blocks, statFn);
+	const stats = Array.from({ length: resamples }, () => average(createResample(side.blockVals)));
+	return {
+		estimate: statFn(side.filtered),
+		ci: computeInterval(stats, conf),
+		samples: stats,
+		ciLevel: "block"
+	};
+}
+/** @return mean of values */
+function average(values) {
+	return values.reduce((a, b) => a + b, 0) / values.length;
+}
+/** @return median (50th percentile) of values */
+function median(values) {
+	return percentile(values, .5);
+}
+/** @return standard deviation with Bessel's correction */
+function standardDeviation(samples) {
+	if (samples.length <= 1) return 0;
+	const mean = average(samples);
+	const variance = samples.reduce((sum, x) => sum + (x - mean) ** 2, 0) / (samples.length - 1);
+	return Math.sqrt(variance);
+}
+/** @return value at percentile p (0-1), using O(N) quickselect */
+function percentile(values, p) {
+	const copy = values.slice();
+	return quickSelect(copy, Math.max(0, Math.ceil(copy.length * p) - 1));
+}
+/** Hoare's selection: O(N) average k-th smallest element. Mutates arr. */
+function quickSelect(arr, k) {
+	let lo = 0;
+	let hi = arr.length - 1;
+	while (lo < hi) {
+		const [i, j] = partition(arr, lo, hi);
+		if (k <= j) hi = j;
+		else if (k >= i) lo = i;
+		else break;
+	}
+	return arr[k];
+}
+/** Fill buf in-place with bootstrap resample (with replacement) from source */
+function resampleInto(source, buf) {
+	const n = source.length;
+	for (let i = 0; i < n; i++) buf[i] = source[Math.floor(Math.random() * n)];
+}
+/** @return bootstrap resample with replacement */
+function createResample(samples) {
+	const n = samples.length;
+	return Array.from({ length: n }, () => samples[Math.floor(Math.random() * n)]);
+}
+/** @return Tukey fence bounds [lo, hi] for the given IQR multiplier.
+*  minIqr prevents degenerate fences when values are tightly clustered. */
+function tukeyFences(values, multiplier = 3, minIqr = 0) {
+	const q1 = percentile(values, .25);
+	const q3 = percentile(values, .75);
+	const iqr = Math.max(q3 - q1, minIqr);
+	return [q1 - multiplier * iqr, q3 + multiplier * iqr];
+}
+/** @return indices of values below the upper 3x IQR Tukey fence.
+*  Only trims slow outliers — fast batches reflect less environmental noise, not errors.
+*  Floors IQR at 2% of median to avoid over-trimming tightly clustered batch means. */
+function tukeyKeep(values) {
+	if (values.length < 4) return values.map((_, i) => i);
+	const [, hi] = tukeyFences(values, 3, median(values) * .02);
+	return values.flatMap((v, i) => v <= hi ? [i] : []);
+}
+/** @return samples split into blocks by offset boundaries */
+function splitByOffsets(samples, offsets) {
+	return offsets.map((start, i) => {
+		const end = i + 1 < offsets.length ? offsets[i + 1] : samples.length;
+		return samples.slice(start, end);
+	});
+}
+/** Tukey-trim outlier blocks and compute per-block statistic for one side */
+function prepareBlocks(samples, offsets, fn, noTrim) {
+	const splits = splitByOffsets(samples, offsets);
+	const means = splits.map(average);
+	const keep = noTrim ? means.map((_, i) => i) : tukeyKeep(means);
+	return {
+		blockVals: keep.map((i) => fn(splits[i])),
+		filtered: keep.flatMap((i) => splits[i]),
+		trimCount: means.length - keep.length
+	};
+}
+/** Random subsample without replacement via partial Fisher-Yates. Returns original if n <= max. */
+function subsample(samples, max) {
+	if (samples.length <= max) return samples;
+	const copy = samples.slice();
+	for (let i = 0; i < max; i++) {
+		const j = i + Math.floor(Math.random() * (copy.length - i));
+		[copy[i], copy[j]] = [copy[j], copy[i]];
+	}
+	return copy.slice(0, max);
+}
+/** @return confidence interval [lower, upper] */
+function computeInterval(values, conf) {
+	const alpha = (1 - conf) / 2;
+	return [percentile(values, alpha), percentile(values, 1 - alpha)];
+}
+/** Build stat operations in safe order: mean/min/max first (non-destructive),
+*  then percentiles ascending (use quickSelect which mutates buf) */
+function buildStatOps(stats, n) {
+	const simple = (order, i, fn) => ({
+		order,
+		compute: fn,
+		pointEstimate: fn,
+		origIndex: i
+	});
+	const ops = stats.map((s, i) => {
+		if (s === "mean") return simple(-3, i, average);
+		if (s === "min") return simple(-2, i, minOf);
+		if (s === "max") return simple(-1, i, maxOf);
+		const p = s.percentile;
+		const k = Math.max(0, Math.ceil(n * p) - 1);
+		return {
+			order: p,
+			origIndex: i,
+			compute: (buf) => quickSelect(buf, k),
+			pointEstimate: (v) => percentile(v, p)
+		};
+	});
+	ops.sort((a, b) => a.order - b.order);
+	return ops;
+}
+/** Hoare partition around the midpoint pivot. @return [i, j] boundary indices. */
+function partition(arr, lo, hi) {
+	const pivot = arr[lo + (hi - lo >> 1)];
+	let i = lo;
+	let j = hi;
+	while (i <= j) {
+		while (arr[i] < pivot) i++;
+		while (arr[j] > pivot) j--;
+		if (i <= j) {
+			[arr[i], arr[j]] = [arr[j], arr[i]];
+			i++;
+			j--;
+		}
+	}
+	return [i, j];
+}
+//#endregion
+export { swapDirection as C, subsample as S, prepareBlocks as _, computeInterval as a, splitByOffsets as b, defaultConfidence as c, maxBootstrapInput as d, maxOf as f, percentile as g, minOf as h, coefficientOfVariation as i, flipCI as l, medianAbsoluteDeviation as m, bootstrapCIs as n, computeStat as o, median as p, bootstrapSamples as r, createResample as s, average as t, isBootstrappable as u, quickSelect as v, tukeyFences as w, statKindToFn as x, resampleInto as y };
+
+//# sourceMappingURL=StatisticalUtils-BD92crgM.mjs.map

package/dist/StatisticalUtils-BD92crgM.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"StatisticalUtils-BD92crgM.mjs","names":[],"sources":["../src/stats/StatisticalUtils.ts"],"sourcesContent":["/** Whether CI was computed from block-level or sample-level resampling */\nexport type CILevel = \"block\" | \"sample\";\n\n/** Stat descriptor for multi-bootstrap: known stat kinds enable zero-alloc inner loops */\nexport type StatKind = \"mean\" | \"min\" | \"max\" | { percentile: number };\n\n/** Bootstrap estimate with confidence interval and raw resample distribution */\nexport interface BootstrapResult {\n  /** Point estimate from the original sample */\n  estimate: number;\n  /** Confidence interval [lower, upper] from bootstrap resampling */\n  ci: [number, number];\n  /** Bootstrap resample distribution (for visualization) */\n  samples: number[];\n  /** Block-level (between-run) or sample-level (within-run) resampling */\n  ciLevel: CILevel;\n  /** Original sample count before subsampling (set only when cap applied) */\n  subsampled?: number;\n}\n\nexport type CIDirection = \"faster\" | \"slower\" | \"uncertain\" | \"equivalent\";\n\n/** Binned histogram for efficient transfer to browser */\nexport interface HistogramBin {\n  /** Bin center value */\n  x: number;\n  count: number;\n}\n\n/**\n * Bootstrap confidence interval for percentage difference between two sample medians.\n * Used for baseline comparisons: negative percent means current is faster.\n */\nexport interface DifferenceCI {\n  /** Observed percentage difference (current - baseline) / baseline */\n  percent: number;\n  /** Confidence interval [lower, upper] in percent */\n  ci: [number, number];\n  /** Whether the CI excludes zero: \"faster\", \"slower\", or \"uncertain\" */\n  direction: CIDirection;\n  /** Bootstrap distribution histogram for visualization */\n  histogram?: HistogramBin[];\n  /** Label for the CI plot title (e.g. \"mean Δ%\") */\n  label?: string;\n  /** Blocks trimmed per side [baseline, current] via Tukey fences */\n  trimmed?: [number, number];\n  /** Block-level (between-run) or sample-level (within-run) resampling */\n  ciLevel?: CILevel;\n  /** false when batch count is too low for reliable CI */\n  ciReliable?: boolean;\n  /** Original sample count before subsampling (set only when cap applied) */\n  subsampled?: number;\n}\n\n/** Options for bootstrap resampling */\ntype BootstrapOptions = {\n  /** Number of bootstrap resamples (default: 10000) */\n  resamples?: number;\n  /** Confidence level 0-1 (default: 0.95) */\n  confidence?: number;\n};\n\ninterface StatOp {\n  origIndex: number;\n  compute: (buf: number[]) => number;\n  pointEstimate: (s: number[]) => number;\n}\n\nexport const defaultConfidence = 0.95;\nexport const bootstrapSamples = 10000;\nexport const maxBootstrapInput = 10_000;\nconst outlierMultiplier = 1.5;\n\n/** Swap direction labels for higher-is-better metrics (positive = faster) */\nexport function swapDirection(ci: DifferenceCI): DifferenceCI {\n  const swap: Record<CIDirection, CIDirection> = {\n    faster: \"slower\",\n    slower: \"faster\",\n    uncertain: \"uncertain\",\n    equivalent: \"equivalent\",\n  };\n  return { ...ci, direction: swap[ci.direction] };\n}\n\n/** Negate percent and CI for \"higher is better\" metrics (e.g., throughput) */\nexport function flipCI(ci: DifferenceCI): DifferenceCI {\n  return {\n    ...ci,\n    percent: -ci.percent,\n    ci: [-ci.ci[1], -ci.ci[0]],\n    histogram: ci.histogram?.map(bin => ({ x: -bin.x, count: bin.count })),\n  };\n}\n\n/** Compute a statistic from samples by kind */\nexport function computeStat(samples: number[], kind: StatKind): number {\n  if (kind === \"mean\") return average(samples);\n  if (kind === \"min\") return minOf(samples);\n  if (kind === \"max\") return maxOf(samples);\n  return percentile(samples, kind.percentile);\n}\n\n/** @return true if the stat kind supports bootstrap CI (min/max don't) */\nexport function isBootstrappable(kind: StatKind): boolean {\n  return kind !== \"min\" && kind !== \"max\";\n}\n\n/** @return smallest value in samples (loop to avoid spread-arg limits) */\nexport function minOf(samples: number[]): number {\n  let min = samples[0];\n  for (let i = 1; i < samples.length; i++) {\n    if (samples[i] < min) min = samples[i];\n  }\n  return min;\n}\n\n/** @return largest value in samples (loop to avoid spread-arg limits) */\nexport function maxOf(samples: number[]): number {\n  let max = samples[0];\n  for (let i = 1; i < samples.length; i++) {\n    if (samples[i] > max) max = samples[i];\n  }\n  return max;\n}\n\n/** @return relative standard deviation (coefficient of variation) */\nexport function coefficientOfVariation(samples: number[]): number {\n  const mean = average(samples);\n  if (mean === 0) return 0;\n  const stdDev = standardDeviation(samples);\n  return stdDev / mean;\n}\n\n/** @return median absolute deviation for robust variability measure */\nexport function medianAbsoluteDeviation(samples: number[]): number {\n  const med = median(samples);\n  const deviations = samples.map(x => Math.abs(x - med));\n  return median(deviations);\n}\n\n/** @return outliers detected via Tukey's interquartile range method */\nexport function findOutliers(samples: number[]): {\n  rate: number;\n  indices: number[];\n} {\n  const [lo, hi] = tukeyFences(samples, outlierMultiplier);\n  const indices = samples.flatMap((v, i) => (v < lo || v > hi ? [i] : []));\n  return { rate: indices.length / samples.length, indices };\n}\n\n/** Sample-level bootstrap CI: resample individual samples with replacement. */\nexport function sampleBootstrap(\n  samples: number[],\n  statFn: (s: number[]) => number,\n  options: BootstrapOptions = {},\n): BootstrapResult {\n  const { resamples = bootstrapSamples, confidence: conf = defaultConfidence } =\n    options;\n  const sub = subsample(samples, maxBootstrapInput);\n  const buf = new Array(sub.length);\n  const stats = Array.from({ length: resamples }, () => {\n    resampleInto(sub, buf);\n    return statFn(buf);\n  });\n  return {\n    estimate: statFn(samples),\n    ci: computeInterval(stats, conf),\n    samples: stats,\n    ciLevel: \"sample\",\n    ...(sub !== samples && { subsampled: samples.length }),\n  };\n}\n\n/** Shared-resample bootstrap: one resample per iteration, all stats computed on it.\n *  Mean is computed first (non-destructive), then percentiles via in-place quickSelect. */\nexport function multiSampleBootstrap(\n  samples: number[],\n  stats: StatKind[],\n  options: BootstrapOptions = {},\n): BootstrapResult[] {\n  const { resamples = bootstrapSamples, confidence: conf = defaultConfidence } =\n    options;\n  const sub = subsample(samples, maxBootstrapInput);\n  const n = sub.length;\n  const buf = new Array(n);\n  const ops = buildStatOps(stats, n);\n  const allStats = ops.map(() => new Array<number>(resamples));\n\n  for (let i = 0; i < resamples; i++) {\n    resampleInto(sub, buf);\n    for (let j = 0; j < ops.length; j++) {\n      allStats[j][i] = ops[j].compute(buf);\n    }\n  }\n\n  const capped = sub !== samples;\n  const results = new Array<BootstrapResult>(stats.length);\n  for (let j = 0; j < ops.length; j++) {\n    results[ops[j].origIndex] = {\n      estimate: ops[j].pointEstimate(samples),\n      ci: computeInterval(allStats[j], conf),\n      samples: allStats[j],\n      ciLevel: \"sample\",\n      ...(capped && { subsampled: samples.length }),\n    };\n  }\n  return results;\n}\n\n/** Bootstrap CIs for multiple stats, dispatching block vs sample automatically.\n *  Returns undefined for non-bootstrappable stats (min/max). */\nexport function bootstrapCIs(\n  samples: number[],\n  batchOffsets: number[] | undefined,\n  stats: StatKind[],\n  options?: BootstrapOptions,\n): (BootstrapResult | undefined)[] {\n  const bsStats = stats.filter(isBootstrappable);\n  if (bsStats.length === 0) return stats.map(() => undefined);\n\n  const hasBlocks = (batchOffsets?.length ?? 0) >= 2;\n  const bsResults = hasBlocks\n    ? bsStats.map(s =>\n        blockBootstrap(samples, batchOffsets!, statKindToFn(s), options),\n      )\n    : multiSampleBootstrap(samples, bsStats, options);\n\n  const results: (BootstrapResult | undefined)[] = new Array(stats.length);\n  let bi = 0;\n  for (let i = 0; i < stats.length; i++) {\n    results[i] = isBootstrappable(stats[i]) ? bsResults[bi++] : undefined;\n  }\n  return results;\n}\n\n/** Convert StatKind to a stat function */\nexport function statKindToFn(kind: StatKind): (s: number[]) => number {\n  if (kind === \"mean\") return average;\n  if (kind === \"min\") return minOf;\n  if (kind === \"max\") return maxOf;\n  const p = kind.percentile;\n  return (s: number[]) => percentile(s, p);\n}\n\n/** Block bootstrap CI: Tukey-trim outlier batches, then resample per-block\n *  statFn values as independent observations. Requires 2+ blocks. */\nexport function blockBootstrap(\n  samples: number[],\n  blocks: number[],\n  statFn: (s: number[]) => number,\n  options: BootstrapOptions = {},\n): BootstrapResult {\n  const { resamples = bootstrapSamples, confidence: conf = defaultConfidence } =\n    options;\n  const side = prepareBlocks(samples, blocks, statFn);\n  const stats = Array.from({ length: resamples }, () =>\n    average(createResample(side.blockVals)),\n  );\n  return {\n    estimate: statFn(side.filtered),\n    ci: computeInterval(stats, conf),\n    samples: stats,\n    ciLevel: \"block\",\n  };\n}\n\n/** @return mean of values */\nexport function average(values: number[]): number {\n  const sum = values.reduce((a, b) => a + b, 0);\n  return sum / values.length;\n}\n\n/** @return median (50th percentile) of values */\nexport function median(values: number[]): number {\n  return percentile(values, 0.5);\n}\n\n/** @return standard deviation with Bessel's correction */\nexport function standardDeviation(samples: number[]): number {\n  if (samples.length <= 1) return 0;\n  const mean = average(samples);\n  const variance =\n    samples.reduce((sum, x) => sum + (x - mean) ** 2, 0) / (samples.length - 1);\n  return Math.sqrt(variance);\n}\n\n/** @return value at percentile p (0-1), using O(N) quickselect */\nexport function percentile(values: number[], p: number): number {\n  const copy = values.slice();\n  const k = Math.max(0, Math.ceil(copy.length * p) - 1);\n  return quickSelect(copy, k);\n}\n\n/** Hoare's selection: O(N) average k-th smallest element. Mutates arr. */\nexport function quickSelect(arr: number[], k: number): number {\n  let lo = 0;\n  let hi = arr.length - 1;\n  while (lo < hi) {\n    const [i, j] = partition(arr, lo, hi);\n    if (k <= j) hi = j;\n    else if (k >= i) lo = i;\n    else break;\n  }\n  return arr[k];\n}\n\n/** Fill buf in-place with bootstrap resample (with replacement) from source */\nexport function resampleInto(source: number[], buf: number[]): void {\n  const n = source.length;\n  for (let i = 0; i < n; i++) {\n    buf[i] = source[Math.floor(Math.random() * n)];\n  }\n}\n\n/** @return bootstrap resample with replacement */\nexport function createResample(samples: number[]): number[] {\n  const n = samples.length;\n  return Array.from(\n    { length: n },\n    () => samples[Math.floor(Math.random() * n)],\n  );\n}\n\n/** @return Tukey fence bounds [lo, hi] for the given IQR multiplier.\n *  minIqr prevents degenerate fences when values are tightly clustered. */\nexport function tukeyFences(\n  values: number[],\n  multiplier = 3,\n  minIqr = 0,\n): [lo: number, hi: number] {\n  const q1 = percentile(values, 0.25);\n  const q3 = percentile(values, 0.75);\n  const iqr = Math.max(q3 - q1, minIqr);\n  return [q1 - multiplier * iqr, q3 + multiplier * iqr];\n}\n\n/** @return indices of values below the upper 3x IQR Tukey fence.\n *  Only trims slow outliers — fast batches reflect less environmental noise, not errors.\n *  Floors IQR at 2% of median to avoid over-trimming tightly clustered batch means. */\nexport function tukeyKeep(values: number[]): number[] {\n  if (values.length < 4) return values.map((_, i) => i);\n  const minIqr = median(values) * 0.02;\n  const [, hi] = tukeyFences(values, 3, minIqr);\n  return values.flatMap((v, i) => (v <= hi ? [i] : []));\n}\n\n/** @return samples split into blocks by offset boundaries */\nexport function splitByOffsets(\n  samples: number[],\n  offsets: number[],\n): number[][] {\n  return offsets.map((start, i) => {\n    const end = i + 1 < offsets.length ? offsets[i + 1] : samples.length;\n    return samples.slice(start, end);\n  });\n}\n\n/** @return per-block statistic values from sample data split by offsets */\nexport function blockValues(\n  samples: number[],\n  offsets: number[],\n  fn: (s: number[]) => number,\n): number[] {\n  return splitByOffsets(samples, offsets).map(fn);\n}\n\n/** Tukey-trim outlier blocks and compute per-block statistic for one side */\nexport function prepareBlocks(\n  samples: number[],\n  offsets: number[],\n  fn: (s: number[]) => number,\n  noTrim?: boolean,\n): { blockVals: number[]; filtered: number[]; trimCount: number } {\n  const splits = splitByOffsets(samples, offsets);\n  const means = splits.map(average);\n  const keep = noTrim ? means.map((_, i) => i) : tukeyKeep(means);\n  return {\n    blockVals: keep.map(i => fn(splits[i])),\n    filtered: keep.flatMap(i => splits[i]),\n    trimCount: means.length - keep.length,\n  };\n}\n\n/** Random subsample without replacement via partial Fisher-Yates. Returns original if n <= max. */\nexport function subsample(samples: number[], max: number): number[] {\n  if (samples.length <= max) return samples;\n  const copy = samples.slice();\n  for (let i = 0; i < max; i++) {\n    const j = i + Math.floor(Math.random() * (copy.length - i));\n    [copy[i], copy[j]] = [copy[j], copy[i]];\n  }\n  return copy.slice(0, max);\n}\n\n/** @return confidence interval [lower, upper] */\nexport function computeInterval(\n  values: number[],\n  conf: number,\n): [number, number] {\n  const alpha = (1 - conf) / 2;\n  return [percentile(values, alpha), percentile(values, 1 - alpha)];\n}\n\n/** Build stat operations in safe order: mean/min/max first (non-destructive),\n *  then percentiles ascending (use quickSelect which mutates buf) */\nfunction buildStatOps(stats: StatKind[], n: number): StatOp[] {\n  const simple = (order: number, i: number, fn: (s: number[]) => number) => ({\n    order,\n    compute: fn,\n    pointEstimate: fn,\n    origIndex: i,\n  });\n  const ops = stats.map((s, i): StatOp & { order: number } => {\n    if (s === \"mean\") return simple(-3, i, average);\n    if (s === \"min\") return simple(-2, i, minOf);\n    if (s === \"max\") return simple(-1, i, maxOf);\n    const p = s.percentile;\n    const k = Math.max(0, Math.ceil(n * p) - 1);\n    return {\n      order: p,\n      origIndex: i,\n      compute: (buf: number[]) => quickSelect(buf, k),\n      pointEstimate: (v: number[]) => percentile(v, p),\n    };\n  });\n  ops.sort((a, b) => a.order - b.order);\n  return ops;\n}\n\n/** Hoare partition around the midpoint pivot. @return [i, j] boundary indices. */\nfunction partition(arr: number[], lo: number, hi: number): [number, number] {\n  const pivot = arr[lo + ((hi - lo) >> 1)];\n  let i = lo;\n  let j = hi;\n  while (i <= j) {\n    while (arr[i] < pivot) i++;\n    while (arr[j] > pivot) j--;\n    if (i <= j) {\n      [arr[i], arr[j]] = [arr[j], arr[i]];\n      i++;\n      j--;\n    }\n  }\n  return [i, j];\n}\n"],"mappings":"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"}

package/dist/TimeSampler-Ds8n7l2B.mjs

@@ -0,0 +1,29 @@
+import { Session } from "node:inspector/promises";
+//#region src/profiling/node/TimeSampler.ts
+/** Run a function while sampling CPU time, return profile */
+async function withTimeProfiling(options, fn) {
+	const { interval } = options;
+	const ownSession = !options.session;
+	const session = options.session ?? new Session();
+	if (ownSession) session.connect();
+	try {
+		if (ownSession) await session.post("Profiler.enable");
+		if (interval) await session.post("Profiler.setSamplingInterval", { interval });
+		await session.post("Profiler.start");
+		const result = await fn();
+		const { profile } = await session.post("Profiler.stop");
+		return {
+			result,
+			profile
+		};
+	} finally {
+		if (ownSession) {
+			await session.post("Profiler.disable");
+			session.disconnect();
+		}
+	}
+}
+//#endregion
+export { withTimeProfiling };
+
+//# sourceMappingURL=TimeSampler-Ds8n7l2B.mjs.map

package/dist/TimeSampler-Ds8n7l2B.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"TimeSampler-Ds8n7l2B.mjs","names":[],"sources":["../src/profiling/node/TimeSampler.ts"],"sourcesContent":["import { Session } from \"node:inspector/promises\";\nimport type { CallFrame } from \"./HeapSampler.ts\";\n\n/** V8 CPU profile node (flat array element, not tree) */\nexport interface TimeProfileNode {\n  id: number;\n  callFrame: CallFrame;\n  hitCount?: number;\n  /** Child node IDs */\n  children?: number[];\n}\n\n/** V8 CPU profile returned by Profiler.stop */\nexport interface TimeProfile {\n  nodes: TimeProfileNode[];\n  /** Microseconds */\n  startTime: number;\n  /** Microseconds */\n  endTime: number;\n  /** Node IDs sampled at each tick */\n  samples?: number[];\n  /** Microseconds between samples */\n  timeDeltas?: number[];\n}\n\nexport interface TimeProfileOptions {\n  /** Sampling interval in microseconds (default 1000 = 1ms) */\n  interval?: number;\n  /** External session to use (shares Profiler domain, caller manages enable/disable) */\n  session?: Session;\n}\n\n/** Run a function while sampling CPU time, return profile */\nexport async function withTimeProfiling<T>(\n  options: TimeProfileOptions,\n  fn: () => Promise<T> | T,\n): Promise<{ result: T; profile: TimeProfile }> {\n  const { interval } = options;\n  const ownSession = !options.session;\n  const session = options.session ?? new Session();\n  if (ownSession) session.connect();\n\n  try {\n    if (ownSession) await session.post(\"Profiler.enable\");\n    if (interval)\n      await session.post(\"Profiler.setSamplingInterval\", { interval });\n    await session.post(\"Profiler.start\");\n    const result = await fn();\n    const { profile } = await session.post(\"Profiler.stop\");\n    return { result, profile: profile as unknown as TimeProfile };\n  } finally {\n    if (ownSession) {\n      await session.post(\"Profiler.disable\");\n      session.disconnect();\n    }\n  }\n}\n"],"mappings":";;;AAiCA,eAAsB,kBACpB,SACA,IAC8C;CAC9C,MAAM,EAAE,aAAa;CACrB,MAAM,aAAa,CAAC,QAAQ;CAC5B,MAAM,UAAU,QAAQ,WAAW,IAAI,SAAS;AAChD,KAAI,WAAY,SAAQ,SAAS;AAEjC,KAAI;AACF,MAAI,WAAY,OAAM,QAAQ,KAAK,kBAAkB;AACrD,MAAI,SACF,OAAM,QAAQ,KAAK,gCAAgC,EAAE,UAAU,CAAC;AAClE,QAAM,QAAQ,KAAK,iBAAiB;EACpC,MAAM,SAAS,MAAM,IAAI;EACzB,MAAM,EAAE,YAAY,MAAM,QAAQ,KAAK,gBAAgB;AACvD,SAAO;GAAE;GAAiB;GAAmC;WACrD;AACR,MAAI,YAAY;AACd,SAAM,QAAQ,KAAK,mBAAmB;AACtC,WAAQ,YAAY"}