A local-first multi-agent app development platform, built on PenguinHarness
/**
* Pure helpers behind the cost center's global controls (date-range presets +
* time-series precision) and the series shaping the charts draw — the
* per-entity counts the requests charts stack, the rate values their lines
* follow, and the empty-bucket compaction the cost and Token charts apply.
* No React, unit-tested in test/usage-controls.test.ts.
*
* The range picks the precision; there is no separate control for it. The
* trailing "last hour" window is the only thing that reaches minute buckets (a
* calendar range cannot — a single day by minute is already 1440 points),
* "last 24 hours" serves hours, and every calendar range is drawn per day,
* week or month by its length.
*/
import type { UsageGranularity, UsageSeriesPoint } from "@adelie/server/api";
import { cacheHitRate } from "../../lib/format";
import { SERIES_COLORS } from "../../lib/category-colors";
/** Quick range choices; `1h`/`1d` are trailing timestamp windows, the rest calendar ranges (`custom` reveals the two date inputs). */
export type RangePreset = "1h" | "1d" | "7d" | "30d" | "90d" | "custom";
/** Calendar-preset day counts (today inclusive). */
const PRESET_DAYS: Record<"7d" | "30d" | "90d", number> = {
"7d": 7,
"30d": 30,
"90d": 90,
};
/** Format a Date as a local `yyyy-mm-dd`. */
export function isoDate(d: Date): string {
const pad = (n: number) => (n < 10 ? `0${n}` : `${n}`);
return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
}
/** The from/to range a calendar preset stands for (today inclusive). */
export function presetRange(
preset: "7d" | "30d" | "90d",
today: Date,
): { from: string; to: string } {
const from = new Date(today);
from.setDate(from.getDate() - (PRESET_DAYS[preset] - 1));
return { from: isoDate(from), to: isoDate(today) };
}
/**
* The trailing timestamp window a `1h`/`1d` preset stands for, computed at
* load time so a reload keeps trailing "now": the instant bounds plus the
* local dates they span (the date pair keeps the server's date-column filter
* effective; the instants refine it).
*/
export function presetTsWindow(
preset: "1h" | "1d",
now: Date,
): { fromTs: string; toTs: string; from: string; to: string } {
const fromDate = new Date(now.getTime() - (preset === "1h" ? 3_600_000 : 86_400_000));
return {
fromTs: fromDate.toISOString(),
toTs: now.toISOString(),
from: isoDate(fromDate),
to: isoDate(now),
};
}
/** Inclusive day count of a `yyyy-mm-dd` range (UTC arithmetic — plain calendar distance, no DST wobble); invalid or reversed ranges count as 1. */
export function rangeDays(from: string, to: string): number {
const ms = Date.parse(`${to}T00:00:00Z`) - Date.parse(`${from}T00:00:00Z`);
if (!Number.isFinite(ms) || ms < 0) return 1;
return Math.round(ms / 86_400_000) + 1;
}
/** The precision a custom range is drawn at: daily up to a quarter, weekly up to half a year, monthly beyond. */
export function defaultGranularity(days: number): UsageGranularity {
if (days <= 92) return "day";
if (days <= 190) return "week";
return "month";
}
/**
* The precision a range is drawn at. There is no precision control — the range
* picks it, because only one precision reads well per range and every other
* choice either fuses into a wall of hairlines or hides the shape.
*
* Each result must also be a combination the server accepts: it caps a
* response at 500 buckets, so the trailing hour goes to minute (61 buckets)
* and the trailing day to hour (25), while every calendar preset stays on day
* (90 at the widest). `minute` and window-bounded `hour` additionally require
* the `fromTs`/`toTs` pair, which is exactly what the two trailing presets send.
*/
export function presetDefaultGranularity(preset: RangePreset, days: number): UsageGranularity {
if (preset === "1h") return "minute";
if (preset === "1d") return "hour";
if (preset === "custom") return defaultGranularity(days);
return "day";
}
/** Short x-axis form of a bucket key: minute/hour `hh:mm`, day/week `mm-dd`, month `yyyy-mm`. */
export function bucketAxisLabel(g: UsageGranularity, key: string): string {
if (g === "minute" || g === "hour") return key.slice(11);
if (g === "month") return key;
return key.slice(5);
}
/** Full bubble form of a bucket key: the key itself, with a minute/hour key's `T` opened up to a space. */
export function bucketFullLabel(g: UsageGranularity, key: string): string {
return g === "minute" || g === "hour" ? key.replace("T", " ") : key;
}
/** One entity's per-bucket request and success counts, index-aligned with the chart's buckets. */
export interface EntityCounts {
label: string;
requests: number[];
completed: number[];
denominator: number[];
}
/** A drawable series of a requests chart: one entity's counts, or the folded tail. */
export interface EntitySeries extends EntityCounts {
/** The folded tail (drawn in neutral gray, after the named ones). */
other?: boolean;
}
/**
* How many entities keep a hue of their own. The palette holds exactly this
* many distinct, CVD-checked line colors, and past it the stack and the lines
* would repeat a color — so this is the cap, not a taste setting.
*/
export const MAX_NAMED_SERIES = SERIES_COLORS.length;
/**
* Shape entity series for stacking: the top `max` entities keep their own
* color, the rest fold into one neutral tail whose label is built from the
* number folded — the chart says how many entities it stopped naming instead
* of quietly presenting the head as the whole picture. Input is already
* sorted by total requests descending (the server's contract).
*/
export function foldEntitySeries(
entities: readonly EntityCounts[],
otherLabel: (folded: number) => string,
max = MAX_NAMED_SERIES,
): EntitySeries[] {
const named: EntitySeries[] = entities.slice(0, max).map((s) => ({ ...s }));
const rest = entities.slice(max);
if (rest.length === 0) return named;
// A tail of one is not "other": name it (the color is still the neutral one — a label beats a mystery bucket).
if (rest.length === 1) return [...named, { ...rest[0]!, other: true }];
return [...named, { ...sumCounts(rest), label: otherLabel(rest.length), other: true }];
}
/** Column sums over a set of series: the stack's height per bucket, and the counts its combined rate comes from. */
export function sumCounts(series: readonly EntityCounts[]): Omit<EntityCounts, "label"> {
const buckets = series[0]?.requests.length ?? 0;
const column = (pick: (e: EntityCounts) => number[]) =>
Array.from({ length: buckets }, (_, i) => series.reduce((s, e) => s + (pick(e)[i] ?? 0), 0));
return {
requests: column((e) => e.requests),
completed: column((e) => e.completed),
denominator: column((e) => e.denominator),
};
}
/**
* Per-bucket success rate in percent, or **null where there is nothing to
* rate** (denominator 0 — the entity was idle, or every request it made was
* aborted). Null is not a number the reader may be shown: the hover table
* prints a dash for it, and plotRates below turns it into a drawing height so
* the line still crosses the interval.
*/
export function rateSeries(
counts: Pick<EntityCounts, "completed" | "denominator">,
): (number | null)[] {
return counts.denominator.map((d, i) => (d > 0 ? ((counts.completed[i] ?? 0) / d) * 100 : null));
}
/** Per-bucket cache hit rate in percent, null where the bucket had no cache traffic at all — the same "no rate here" as a success rate with an empty denominator. */
export function hitRateValues(series: readonly UsageSeriesPoint[]): (number | null)[] {
return series.map((p) => {
const rate = cacheHitRate(p.cacheRead, p.cacheWrite);
return rate === null ? null : rate * 100;
});
}
/**
* The height a rate line is drawn at across a bucket that has no rate. The
* stroke has to cross the interval at *some* height — a hole reads as a claim
* of its own, and so does dropping to the floor, which is where "made
* requests and failed every one" lives. The top of the axis is the one height
* that invents no failure.
*
* It is a drawing choice and nothing more: the hover table prints a dash for
* the same bucket, so the number the reader takes away is never this 100.
*/
export const NO_RATE_PLOT = 100;
/** Drawing values for a rate line: every bucket gets a height, the ones with no rate at NO_RATE_PLOT. */
export function plotRates(values: readonly (number | null)[]): number[] {
return values.map((v) => v ?? NO_RATE_PLOT);
}
/** A time series with its empty buckets dropped: the buckets that survived, where they sat, and where the axis now jumps. */
export interface CompactSeries {
/** The buckets that recorded something, in order. */
points: UsageSeriesPoint[];
/**
* Where each surviving bucket sat in the original series. The per-entity
* counts arrive aligned index-for-index with that array, so they have to be
* re-indexed through this to stay aligned with `points` — see compactCounts.
*/
kept: number[];
/** Indices in `points` after which at least one bucket was dropped — where the axis jumps in time. */
breaks: number[];
}
/**
* Drop the buckets that recorded nothing. The survivors are handed to
* makeGeom as the entire series, so the coordinate system spreads them evenly
* over the plot area on its own: one point sits in the middle of the card,
* two at a quarter and three quarters, and the divisions subdivide as points
* are added. Left to right, only what happened — the shape the charts had
* before the range control existed.
*
* Emptiness is a property of the **bucket**, never of one entity in it: an
* interval where anything at all ran stays, and the entities that did not run
* in it show their zeros and dashes there. That is what lets every chart on
* the page compact through this one call and keep one shared axis.
*
* `breaks` is what the axis is drawn with, since an axis that skips intervals
* must not read as a continuous one.
*/
export function compactSeries(series: readonly UsageSeriesPoint[]): CompactSeries {
const points: UsageSeriesPoint[] = [];
const kept: number[] = [];
const breaks: number[] = [];
let dropping = false;
series.forEach((p, i) => {
// Nothing was recorded in this bucket: no request, and no tokens either
// (a request that spent nothing is still a request, and keeps its bucket).
if (p.requests === 0 && p.total === 0) {
dropping = true;
return;
}
// A break belongs *between* two drawn points; buckets dropped before the
// first one (or after the last) shorten the axis without breaking it.
if (dropping && points.length > 0) breaks.push(points.length - 1);
dropping = false;
kept.push(i);
points.push(p);
});
return { points, kept, breaks };
}
/**
* Re-index one entity's per-bucket counts onto the compacted bucket list.
* The server aligns these arrays index-for-index with `series`; dropping
* buckets from the series without dropping the same positions here would
* shift every entity's history sideways and silently attribute its counts to
* the wrong intervals. One `kept` list for the series and for every entity is
* what makes that impossible.
*/
export function compactCounts(
counts: Omit<EntityCounts, "label">,
kept: readonly number[],
): Omit<EntityCounts, "label"> {
const pick = (values: readonly number[]) => kept.map((i) => values[i] ?? 0);
return {
requests: pick(counts.requests),
completed: pick(counts.completed),
denominator: pick(counts.denominator),
};
}