src/render/data.ts

Functions

Imports

It imports no other module of this repo. Imported by src/lite/bar.ts, src/plot/heatmap.ts, src/plot/scatter.ts, src/primitives/heat-strip.ts, src/primitives/sparkline.ts, src/primitives/timeline.ts, src/render/bar-model.ts, src/render/line-model.ts, src/science/genome.ts, src/science/network.ts, src/science/titer.ts.

Source

1/** Helpers for reading caller data by key, with errors that name the chart, row and field. */
2
3/** The keys of `T` whose values are assignable to `V`. */
4export type KeysOfType<T, V> = {
5  [K in keyof T]-?: T[K] extends V ? K : never;
6}[keyof T] &
7  string;
8
9/** Formats a number for tooltips and tables when the caller gives no formatter. */
10export function defaultFormat(value: number): string {
11  return value.toLocaleString("en-US", { maximumFractionDigits: 6 });
12}
13
14/** Reads a finite number, or throws naming where it was expected. */
15export function readNumber(kind: string, row: object, key: string, index: number): number {
16  const value: unknown = (row as Record<string, unknown>)[key];
17  if (typeof value !== "number" || !Number.isFinite(value)) {
18    throw new Error(
19      `${kind}: row ${index + 1} field "${key}" is ${String(value)}, not a finite number`,
20    );
21  }
22  return value;
23}
24
25/** Reads a number or null (a gap), or throws. */
26export function readNumberOrNull(
27  kind: string,
28  row: object,
29  key: string,
30  index: number,
31): number | null {
32  const value: unknown = (row as Record<string, unknown>)[key];
33  if (value === null || value === undefined) return null;
34  return readNumber(kind, row, key, index);
35}
36
37/** Reads a category: a non-empty string or a finite number (a year, a dose), or throws. */
38export function readCategory(
39  kind: string,
40  row: object,
41  key: string,
42  index: number,
43): string | number {
44  const value: unknown = (row as Record<string, unknown>)[key];
45  if (typeof value === "number" && Number.isFinite(value)) return value;
46  if (typeof value === "string" && value !== "") return value;
47  throw new Error(
48    `${kind}: row ${index + 1} field "${key}" is ${JSON.stringify(value)}, not a label`,
49  );
50}
51
52/** Reads a category as text. */
53export function readLabel(kind: string, row: object, key: string, index: number): string {
54  return String(readCategory(kind, row, key, index));
55}
56
57/** A Date, an ISO 8601 string or a timestamp as a Date; undefined for anything else or an invalid date. */
58export function toDate(value: unknown): Date | undefined {
59  const date =
60    value instanceof Date
61      ? value
62      : typeof value === "string" || typeof value === "number"
63        ? new Date(value)
64        : undefined;
65  return date && !Number.isNaN(date.getTime()) ? date : undefined;
66}
67
68/** Reads a Date, an ISO 8601 string or a timestamp as a Date, or throws. */
69export function readDate(kind: string, row: object, key: string, index: number): Date {
70  const value: unknown = (row as Record<string, unknown>)[key];
71  const date = toDate(value);
72  if (!date) {
73    throw new Error(
74      `${kind}: row ${index + 1} field "${key}" is ${JSON.stringify(value)}, not a date`,
75    );
76  }
77  return date;
78}
79
80/**
81 * The distinct values of a label field in first-seen order, or ascending when every value is a
82 * number (years, doses), or `explicit` when the caller fixed the order. Values are compared as
83 * text, so 2022 and "2022" are one category (A8). Throws if data holds a value `explicit` leaves
84 * out.
85 */
86export function domainOf(
87  kind: string,
88  field: string,
89  values: readonly (string | number)[],
90  explicit: readonly (string | number)[] | undefined,
91): string[] {
92  if (explicit) {
93    const allowed = new Set(explicit.map(String));
94    for (const v of values) {
95      if (!allowed.has(String(v))) {
96        throw new Error(`${kind}: ${field} value "${v}" is missing from the ${field} domain given`);
97      }
98    }
99    return [...new Set(explicit.map(String))];
100  }
101  const seen = new Map<string, string | number>();
102  for (const v of values) if (!seen.has(String(v))) seen.set(String(v), v);
103  const distinct = [...seen.values()];
104  if (distinct.every((v) => typeof v === "number")) {
105    return (distinct as number[]).sort((a, b) => a - b).map(String);
106  }
107  return [...seen.keys()];
108}
109
110/**
111 * A mark's key from its parts. JSON, so no part can contain the separator and collide with
112 * another mark's key (A9, F14). Keys are opaque: compare them, never parse them.
113 */
114export function markKey(...parts: readonly (string | number)[]): string {
115  return JSON.stringify(parts);
116}
117
118/** The smallest of many numbers, without spreading them onto the stack (F15). */
119export function minOf(values: Iterable<number>): number {
120  let min = Number.POSITIVE_INFINITY;
121  for (const v of values) if (v < min) min = v;
122  return min;
123}
124
125/** The largest of many numbers, without spreading them onto the stack (F15). */
126export function maxOf(values: Iterable<number>): number {
127  let max = Number.NEGATIVE_INFINITY;
128  for (const v of values) if (v > max) max = v;
129  return max;
130}
131
132/** Throws unless a size option is a positive finite number (A7, F15). */
133export function requireSize(kind: string, name: string, value: number | undefined): void {
134  if (value !== undefined && !(Number.isFinite(value) && value > 0)) {
135    throw new Error(`${kind}: ${name} must be a positive number, is ${value}`);
136  }
137}
138
139/** Milliseconds in a UTC day. */
140export const DAY = 86_400_000;
141
142/**
143 * Dates made at local midnight (`new Date(2025, 0, 6)`) mean a calendar date, but east of UTC
144 * that instant falls on the previous UTC day. When every Date is at local midnight and not at
145 * UTC midnight, each is moved to UTC midnight of its local date (A3).
146 */
147export function calendarDates(dates: Date[]): Date[] {
148  const localMidnight = dates.every(
149    (d) =>
150      d.getHours() === 0 &&
151      d.getMinutes() === 0 &&
152      d.getSeconds() === 0 &&
153      d.getMilliseconds() === 0,
154  );
155  const utcMidnight = dates.every((d) => d.getTime() % DAY === 0);
156  if (!localMidnight || utcMidnight) return dates;
157  return dates.map((d) => new Date(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate())));
158}
159
160/** The step (1 to 5) of the sequential ramp a value falls in, given four ascending thresholds. */
161export function rampStep(value: number, thresholds: readonly number[]): number {
162  let step = 1;
163  for (const t of thresholds) if (value >= t) step += 1;
164  return step;
165}
166
167/**
168 * Four ascending thresholds splitting `min` to `max` into the ramp's five steps: the caller's, or
169 * equal intervals. Flat data still gets ascending thresholds, so every value lands in step 1.
170 */
171export function rampThresholds(
172  kind: string,
173  min: number,
174  max: number,
175  given: readonly number[] | undefined,
176): readonly number[] {
177  const span = max - min || 1;
178  const thresholds = given ?? [1, 2, 3, 4].map((k) => min + (span * k) / 5);
179  for (let i = 1; i < thresholds.length; i += 1) {
180    if ((thresholds[i] as number) <= (thresholds[i - 1] as number)) {
181      throw new Error(`${kind}: thresholds must ascend`);
182    }
183  }
184  return thresholds;
185}
186
187/** An instant as `2026-01-05 14:30 UTC` (seconds only when not zero). */
188export function formatInstant(date: Date): string {
189  const pad = (n: number): string => String(n).padStart(2, "0");
190  const seconds = date.getUTCSeconds() ? `:${pad(date.getUTCSeconds())}` : "";
191  return `${date.toISOString().slice(0, 10)} ${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}${seconds} UTC`;
192}