src/primitives/uptime-strip.ts

Functions

Imports

It imports src/html.ts, src/primitives/companion.ts, src/primitives/tick-gap.ts. Imported by src/index.ts.

Source

1import { element, escapeHtml } from "../html.js";
2import { type PrimitiveTable, type PrimitiveTableOptions, primitiveTable } from "./companion.js";
3import { tickGap } from "./tick-gap.js";
4
5/** The state of one period in an {@link uptimeStrip}. */
6export type UptimeStatus = "up" | "degraded" | "down" | "unknown";
7
8/** One period: a status, or a status with its own hover label (e.g. "Mon 14:00, 2 failed probes"). */
9export type UptimeSlot = UptimeStatus | { readonly status: UptimeStatus; readonly label?: string };
10
11/** Options for {@link uptimeStrip}. */
12export interface UptimeStripOptions {
13  /** The periods, oldest first. */
14  readonly slots: readonly UptimeSlot[];
15  /**
16   * What is monitored and over what window, e.g. "API, last 7 days"; it starts the generated
17   * text alternative. Required unless `alt` is given.
18   */
19  readonly label?: string;
20  /** The text alternative, instead of the one generated from `label` and the counts (F18). */
21  readonly alt?: string;
22  /** The strip's width in CSS pixels (default 240). */
23  readonly width?: number;
24  /** The strip's height in CSS pixels (default 24). */
25  readonly height?: number;
26}
27
28const STATUS: Readonly<Record<UptimeStatus, { color: string; height: number; word: string }>> = {
29  // Height encodes status as well as color, so the strip reads without hue: a shorter tick is worse.
30  up: { color: "var(--enarratio-status-good)", height: 1, word: "up" },
31  degraded: { color: "var(--enarratio-status-warning)", height: 0.66, word: "degraded" },
32  down: { color: "var(--enarratio-status-bad)", height: 0.33, word: "down" },
33  unknown: { color: "var(--enarratio-status-unknown)", height: 1, word: "no data" },
34};
35
36const round = (n: number): number => Math.round(n * 100) / 100;
37
38/** One period, checked, with the name it carries in hover details and the companion table. */
39interface PreparedSlot {
40  readonly status: UptimeStatus;
41  /** The slot's own label, or "Period 3". */
42  readonly name: string;
43  readonly word: string;
44}
45
46/** Everything the strip, its text alternative and its companion table are computed from. */
47interface UptimeStripValues {
48  readonly slots: readonly PreparedSlot[];
49  readonly counts: Readonly<Record<UptimeStatus, number>>;
50  readonly width: number;
51  readonly height: number;
52  /** The sentence generated from the counts, or "" when only `alt` names the strip. */
53  readonly summary: string;
54  readonly alt: string;
55  readonly subject: string;
56}
57
58/** Validates the options and computes the numbers every part of an uptime strip is made from. */
59function prepareUptimeStrip(options: UptimeStripOptions): UptimeStripValues {
60  const { slots } = options;
61  if (slots.length === 0) throw new Error("uptimeStrip: needs at least one slot");
62  const subject = options.label?.trim() ?? "";
63  const given = options.alt?.trim() ?? "";
64  if (subject === "" && given === "") throw new Error("uptimeStrip: label or alt is required");
65  const width = options.width ?? 240;
66  const height = options.height ?? 24;
67  for (const [name, n] of [
68    ["width", width],
69    ["height", height],
70  ] as const) {
71    if (!(Number.isFinite(n) && n > 0)) {
72      throw new Error(`uptimeStrip: ${name} must be a positive number, is ${n}`);
73    }
74  }
75  const counts: Record<UptimeStatus, number> = { up: 0, degraded: 0, down: 0, unknown: 0 };
76  const prepared = slots.map((slot, i): PreparedSlot => {
77    const status = typeof slot === "string" ? slot : slot.status;
78    // Own properties only: "constructor" or "toString" from JSON is not a status (F15).
79    if (typeof status !== "string" || !Object.hasOwn(STATUS, status)) {
80      throw new Error(`uptimeStrip: slot ${i + 1} has unknown status "${String(status)}"`);
81    }
82    counts[status] += 1;
83    const own = typeof slot === "string" ? undefined : slot.label;
84    return { status, name: own ? own : `Period ${i + 1}`, word: STATUS[status].word };
85  });
86  const measured = counts.up + counts.degraded + counts.down;
87  const availability =
88    measured === 0
89      ? "no measurements"
90      : `${round(((counts.up + counts.degraded) / measured) * 100)}% available`;
91  const parts = (Object.keys(counts) as UptimeStatus[])
92    .filter((s) => counts[s] > 0)
93    .map((s) => `${counts[s]} ${STATUS[s].word}`);
94  const summary =
95    subject === ""
96      ? ""
97      : `${subject}: ${slots.length} periods, ${parts.join(", ")}; ${availability}.`;
98  return {
99    slots: prepared,
100    counts,
101    width,
102    height,
103    summary,
104    alt: given || summary,
105    subject,
106  };
107}
108
109/**
110 * A row of ticks, one per period, showing whether a service was up, degraded, down or unmeasured.
111 * Status is carried by tick height and outline as well as color, and the text alternative
112 * summarizes the counts and availability.
113 *
114 * @example
115 * uptimeStrip({ slots: ["up", "up", "degraded", "down", "up"], label: "Site, last 5 hours" });
116 */
117export function uptimeStrip(options: UptimeStripOptions): string {
118  const { slots, width, height, alt } = prepareUptimeStrip(options);
119  const step = width / slots.length;
120  const gap = tickGap(step);
121
122  const ticks = slots.map((slot, i) => {
123    const spec = STATUS[slot.status];
124    const { status } = slot;
125    const h = height * spec.height;
126    const title = `${slot.name}: ${spec.word}`;
127    const common = {
128      x: round(i * step),
129      y: round(height - h),
130      width: round(step - gap),
131      height: round(h),
132    };
133    return element(
134      "rect",
135      status === "unknown"
136        ? {
137            ...common,
138            x: round(i * step + 0.5),
139            width: round(step - gap - 1),
140            y: 0.5,
141            height: height - 1,
142            fill: "none",
143            stroke: spec.color,
144            "stroke-dasharray": "2,2",
145          }
146        : { ...common, fill: spec.color, "data-status": status },
147      element("title", {}, escapeHtml(title)),
148    );
149  });
150
151  return element(
152    "svg",
153    {
154      class: "enarratio enarratio-uptime-strip",
155      "data-enarratio": "uptime-strip",
156      xmlns: "http://www.w3.org/2000/svg",
157      viewBox: `0 0 ${width} ${height}`,
158      width,
159      height,
160      role: "img",
161      "aria-label": alt,
162    },
163    ticks.join(""),
164  );
165}
166
167/**
168 * An uptime strip's periods as a table (period and status) and a summary sentence with the counts
169 * and availability, computed from the same slots as the drawing so the two cannot disagree. Takes
170 * the same options as {@link uptimeStrip}. Without `label` the summary is the given `alt`.
171 *
172 * @example
173 * const { summary, table } = uptimeStripTable({ slots: ["up", "down"], label: "Site, last 2 hours" });
174 */
175export function uptimeStripTable(
176  options: UptimeStripOptions,
177  display?: PrimitiveTableOptions,
178): PrimitiveTable {
179  const p = prepareUptimeStrip(options);
180  return primitiveTable(
181    p.summary || p.alt,
182    { columns: ["Period", "Status"], rows: p.slots.map((s) => [s.name, s.word]) },
183    p.subject || p.alt,
184    display,
185  );
186}