components/usage-meter/usage-meter.ts

Functions

Imports

It imports components/meter/meter.ts, components/time/time.ts. Imported by components/usage-meter/usage-meter.react.tsx.

Source

1// The usage meter's behaviour: a pure assessment of one usage figure against its free
2// limit (tone, projection by the reset, when it runs out, and the sentence that says so),
3// and `enhance`, which draws each row's bar through the shared meter (components/meter) from
4// its ARIA values through the CSSOM. No framework; the React wrapper uses the same functions.
5//
6import { enhance as enhanceMeter, update as drawBar } from "../meter/meter.ts";
7import { DAY, HOUR } from "../time/time.ts";
8
9// The rules (approved for 0.1): warning at 75% used, or when the projection runs out before
10// the reset; critical at 90%; no projection until 7 days of history.
11
12export const MIN_HISTORY = 7;
13export const WARN_AT = 0.75;
14export const CRIT_AT = 0.9;
15
16export type UsageTone = "ok" | "warn" | "crit";
17
18export interface UsageInput {
19  used: number;
20  limit: number;
21  // Totals of past whole periods (days), oldest first. Fewer than 7: no projection.
22  history: number[];
23  // When the count resets, or null for a total that does not reset (storage).
24  resetsAt: number | Date | null;
25  now: number | Date;
26  // The length of one period; a day unless said otherwise.
27  periodMs?: number;
28  // A plural noun for what is counted, for "38 writes left". Optional.
29  unit?: string;
30  // What happens at the limit, completing "At the limit, ... until 00:00 UTC.":
31  // "reads fail", "the watcher cannot save its pass". Optional.
32  atLimit?: string;
33}
34
35export interface UsageAssessment {
36  tone: UsageTone;
37  // Used as a whole percentage of the limit.
38  percent: number;
39  // The projected total at the reset, or null with no projection.
40  projectedAtReset: number | null;
41  // When the limit is reached at the current rate (ms since the epoch), or null.
42  fullAt: number | null;
43  // A short status word for a warning or critical row: "Runs out before the reset".
44  label: string;
45  // The "why" line. It starts with `lead`, the part shown in the tone's colour.
46  text: string;
47  lead: string;
48  // The projection in words for aria-valuetext: "projected 87 percent by the reset".
49  projection: string;
50}
51
52const ms = (t: number | Date): number => (typeof t === "number" ? t : t.getTime());
53const plural = (n: number, word: string): string => `${n} ${word}${n === 1 ? "" : "s"}`;
54
55// A duration in plain words, rounded to the unit a person would say: "40 minutes",
56// "3 hours", "2 days".
57export function duration(span: number): string {
58  const m = Math.max(0, Math.round(span / 60_000));
59  if (m < 1) return "less than a minute";
60  if (m < 60) return plural(m, "minute");
61  const h = Math.round(span / HOUR);
62  if (h < 48) return plural(h, "hour");
63  return plural(Math.round(span / DAY), "day");
64}
65
66// "00:00 UTC". A reset is a UTC time in every provider this family uses.
67export function utcClock(t: number | Date): string {
68  return `${new Date(ms(t)).toISOString().slice(11, 16)} UTC`;
69}
70
71export function assess(input: UsageInput): UsageAssessment {
72  const { used, limit, history, unit, atLimit } = input;
73  const now = ms(input.now);
74  const resetsAt = input.resetsAt == null ? null : ms(input.resetsAt);
75  const periodMs = input.periodMs ?? DAY;
76  const frac = limit > 0 ? used / limit : 1;
77  const percent = Math.round(frac * 100);
78  const left = Math.max(0, limit - used);
79  const leftWords = `${left.toLocaleString("en-US")}${unit ? ` ${unit}` : ""} left.`;
80  const until = resetsAt != null ? ` until ${utcClock(resetsAt)}` : "";
81  const atLimitSentence = atLimit ? ` At the limit, ${atLimit}${until}.` : "";
82
83  // The projection: today's rate so far, or the typical rate from history for the first
84  // hour of a period, when today's rate is mostly noise.
85  let projectedAtReset: number | null = null;
86  let fullAt: number | null = null;
87  const enoughHistory = history.length >= MIN_HISTORY;
88  if (resetsAt != null && enoughHistory && resetsAt > now) {
89    const elapsed = now - (resetsAt - periodMs);
90    const recent = history.slice(-MIN_HISTORY);
91    const typical = recent.reduce((a, b) => a + b, 0) / recent.length / periodMs;
92    const rate = elapsed >= HOUR ? used / elapsed : typical;
93    projectedAtReset = used + rate * (resetsAt - now);
94    if (projectedAtReset >= limit && rate > 0 && used < limit) fullAt = now + (limit - used) / rate;
95  }
96  const projectedPct = projectedAtReset == null ? null : Math.round((projectedAtReset / limit) * 100);
97  const noProjection =
98    resetsAt == null
99      ? enoughHistory
100        ? "This total does not reset."
101        : `No projection: ${plural(history.length, "day")} of history, ${MIN_HISTORY} needed. This total does not reset.`
102      : `No projection: ${plural(history.length, "day")} of history, ${MIN_HISTORY} needed.`;
103
104  const projection =
105    used >= limit
106      ? "at the limit"
107      : fullAt != null
108        ? `projected to run out in about ${duration(fullAt - now)}${resetsAt != null && fullAt < resetsAt ? ", before the reset" : ""}`
109        : projectedPct != null
110          ? `projected ${projectedPct} percent by the reset`
111          : "no projection yet";
112
113  const out = (tone: UsageTone, label: string, lead: string, text: string): UsageAssessment => ({
114    tone,
115    percent,
116    projectedAtReset,
117    fullAt,
118    label,
119    lead,
120    text,
121    projection,
122  });
123
124  if (used >= limit) {
125    const lead = "At the limit";
126    return out("crit", "At the limit", lead, `${lead}${atLimit ? `: ${atLimit}${until}` : ""}.`);
127  }
128  if (frac >= CRIT_AT) {
129    const runOut = fullAt != null ? ` Full in about ${duration(fullAt - now)}.` : "";
130    const why = projectedAtReset == null && resetsAt != null ? ` ${noProjection}` : "";
131    return out("crit", "Nearly out", leftWords, `${leftWords}${runOut}${atLimitSentence}${why}`);
132  }
133  if (fullAt != null && resetsAt != null && fullAt < resetsAt) {
134    const lead = `Full in about ${duration(fullAt - now)}`;
135    return out("warn", "Runs out before the reset", lead, `${lead}, ${duration(resetsAt - fullAt)} before the reset.${atLimitSentence}`);
136  }
137  if (projectedAtReset == null || resetsAt == null) {
138    const lead = resetsAt == null && enoughHistory ? "Does not reset" : "No projection";
139    return out(frac >= WARN_AT ? "warn" : "ok", frac >= WARN_AT ? "Over 75% used" : "No projection yet", lead, noProjection);
140  }
141  const by = `about ${projectedPct}% by the reset at ${utcClock(resetsAt)}, in ${duration(resetsAt - now)}.`;
142  if (frac >= WARN_AT) {
143    const lead = `${percent}% used`;
144    return out("warn", "Over 75% used", lead, `${lead}: ${by}`);
145  }
146  return out("ok", "On track", "On track", `On track: ${by}`);
147}
148
149// The bar's widths, as percentages of the limit, clamped to the bar. The meter draws the
150// same shares as 0 to 1 ratios; these stay for apps that size their own marks.
151export function widths(used: number, limit: number, projected: number | null): { used: number; projected: number } {
152  const pct = (v: number) => (limit > 0 ? Math.min(100, Math.max(0, (v * 100) / limit)) : 100);
153  const u = pct(used);
154  return { used: u, projected: projected == null ? u : Math.max(u, pct(projected)) };
155}
156
157// Draws one row's bar from its aria-valuenow and aria-valuemax and its data-projected (the
158// projected total at the reset, in the same unit; absent with no projection).
159export const sizeBar: (bar: HTMLElement) => void = drawBar;
160
161// Attaches to every [data-cap="usage-meter"] under root that is not attached yet, and draws
162// its rows' bars (each row is a [data-cap="meter"]). Returns a function that detaches them.
163export function enhance(root: ParentNode = document): () => void {
164  const undo: Array<() => void> = [];
165  for (const meter of root.querySelectorAll<HTMLElement>("[data-cap='usage-meter']:not([data-cap-ready])")) {
166    meter.dataset.capReady = "";
167    undo.push(enhanceMeter(meter));
168    undo.push(() => {
169      delete meter.dataset.capReady;
170    });
171  }
172  return () => undo.forEach((f) => f());
173}