app/kb/procedures/run.mjs

Functions

Imports

It imports app/lib/site-origin.mjs. Imported by app/enhance/run.ts.

Source

1// The pure half of run mode (docs/PROCEDURES.md "Run mode"): what a bench run is, how its timers count, and what
2// the saved record says. A run is a person working through one procedure once: which steps are done, a note on
3// each, the timers they started, the scale they chose. It lives in the browser (localStorage), is downloadable and
4// printable, and never reaches the server: nothing here touches the DOM, a clock or storage, so the same functions
5// run in a test. The browser module (app/enhance/run.ts) passes `now` in.
6//
7// A timer's remaining time is computed from the moment it ends, not counted down, so a phone that sleeps or a page
8// that reloads mid-incubation still knows how long is left.
9
10import { SITE_ORIGIN } from "../../lib/site-origin.mjs";
11
12export const RUN_VERSION = 1;
13
14/** Seconds in each unit a timer mark can use (validate.mjs TIME_UNITS). */
15const UNIT_SECONDS = Object.freeze(
16  /** @type {Record<string, number>} */ ({
17    second: 1, seconds: 1, sec: 1, s: 1,
18    minute: 60, minutes: 60, min: 60,
19    hour: 3600, hours: 3600, h: 3600,
20    day: 86400, days: 86400,
21  }),
22);
23
24/**
25 * @typedef {{ label: string, text: string, min: number | null, max: number | null, unit: string }} StepTimer
26 * @typedef {{ state: "running" | "paused" | "done", endsAt: number | null, remainingMs: number, totalMs: number }} TimerState
27 * @typedef {{ done: boolean, doneAt: number | null, note: string }} StepState
28 * @typedef {{
29 *   v: number, path: string, version: string, title: string, scale: number | null,
30 *   startedAt: number, finishedAt: number | null, note: string,
31 *   steps: Record<string, StepState>, timers: Record<string, TimerState>,
32 * }} Run
33 */
34
35/**
36 * A timer's length in milliseconds: the longer end of a range ("5 to 10 minutes" runs 10), because a timer that
37 * rings early is the mistake that costs a prep. Null when the mark carries no usable number.
38 *
39 * @param {StepTimer} timer
40 */
41export function timerMs(timer) {
42  const seconds = UNIT_SECONDS[String(timer.unit).toLowerCase()];
43  const amount = timer.max ?? timer.min;
44  if (seconds === undefined || amount === null || !Number.isFinite(amount) || amount <= 0) return null;
45  return Math.round(amount * seconds * 1000);
46}
47
48/** The key a step's nth timer is stored under. */
49export const timerKey = (/** @type {number | string} */ step, /** @type {number} */ index) => `${step}.${index}`;
50
51/**
52 * @param {{ path: string, version: string, title: string, scale: number | null }} procedure
53 * @param {number} now
54 * @returns {Run}
55 */
56export function newRun(procedure, now) {
57  return { v: RUN_VERSION, path: procedure.path, version: procedure.version, title: procedure.title, scale: procedure.scale, startedAt: now, finishedAt: null, note: "", steps: {}, timers: {} };
58}
59
60const stepOf = (/** @type {Run} */ run, /** @type {number | string} */ step) => run.steps[String(step)] ?? { done: false, doneAt: null, note: "" };
61
62/** @param {Run} run @param {number | string} step @param {number} now */
63export function toggleDone(run, step, now) {
64  const current = stepOf(run, step);
65  return { ...run, steps: { ...run.steps, [String(step)]: { ...current, done: !current.done, doneAt: current.done ? null : now } } };
66}
67
68/** @param {Run} run @param {number | string} step @param {string} note */
69export function setNote(run, step, note) {
70  return { ...run, steps: { ...run.steps, [String(step)]: { ...stepOf(run, step), note: note.slice(0, 2000) } } };
71}
72
73/** @param {Run} run @param {string} note */
74export function setRunNote(run, note) {
75  return { ...run, note: note.slice(0, 4000) };
76}
77
78/** @param {Run} run @param {number | null} scale */
79export function setScale(run, scale) {
80  return { ...run, scale };
81}
82
83/** @param {Run} run @param {number} now */
84export function finishRun(run, now) {
85  return { ...run, finishedAt: run.finishedAt ?? now };
86}
87
88/** Starts a timer, or resumes a paused one from where it stopped. @param {Run} run @param {string} key @param {number} ms @param {number} now */
89export function startTimer(run, key, ms, now) {
90  const current = run.timers[key];
91  const remainingMs = current && current.state === "paused" ? current.remainingMs : ms;
92  return { ...run, timers: { ...run.timers, [key]: { state: /** @type {const} */ ("running"), endsAt: now + remainingMs, remainingMs, totalMs: ms } } };
93}
94
95/** @param {Run} run @param {string} key @param {number} now */
96export function pauseTimer(run, key, now) {
97  const current = run.timers[key];
98  if (!current || current.state !== "running" || current.endsAt === null) return run;
99  return { ...run, timers: { ...run.timers, [key]: { ...current, state: /** @type {const} */ ("paused"), endsAt: null, remainingMs: Math.max(0, current.endsAt - now) } } };
100}
101
102/** @param {Run} run @param {string} key */
103export function resetTimer(run, key) {
104  const { [key]: _gone, ...rest } = run.timers;
105  return { ...run, timers: rest };
106}
107
108/** Milliseconds left on a timer, or null when it has not been started. @param {Run} run @param {string} key @param {number} now */
109export function timerRemaining(run, key, now) {
110  const t = run.timers[key];
111  if (!t) return null;
112  if (t.state === "paused" || t.state === "done") return t.state === "done" ? 0 : t.remainingMs;
113  return Math.max(0, (t.endsAt ?? now) - now);
114}
115
116/**
117 * Marks every running timer whose time has come as done, and returns which rang so the page can alert once.
118 *
119 * @param {Run} run @param {number} now
120 * @returns {{ run: Run, rang: string[] }}
121 */
122export function tickTimers(run, now) {
123  /** @type {string[]} */
124  const rang = [];
125  /** @type {Record<string, TimerState>} */
126  const timers = { ...run.timers };
127  for (const [key, t] of Object.entries(run.timers)) {
128    if (t.state === "running" && t.endsAt !== null && t.endsAt <= now) {
129      timers[key] = { ...t, state: /** @type {const} */ ("done"), endsAt: null, remainingMs: 0 };
130      rang.push(key);
131    }
132  }
133  return rang.length === 0 ? { run, rang } : { run: { ...run, timers }, rang };
134}
135
136/** "2:05", "1:30:00": a countdown in the form a person reads at the bench. @param {number} ms */
137export function clock(ms) {
138  const total = Math.ceil(Math.max(0, ms) / 1000);
139  const h = Math.floor(total / 3600);
140  const m = Math.floor((total % 3600) / 60);
141  const s = total % 60;
142  return h > 0 ? `${h}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}` : `${m}:${String(s).padStart(2, "0")}`;
143}
144
145/** How far along a run is, over the steps the procedure has. @param {Run} run @param {Array<number | string>} steps */
146export function runProgress(run, steps) {
147  const done = steps.filter((n) => run.steps[String(n)]?.done).length;
148  return { done, total: steps.length };
149}
150
151/**
152 * The step one-at-a-time view shows (docs/KNOWLEDGE-BASE.md, R4, the cook view): the one the person chose, while it is still a
153 * step of the procedure; else the first not yet done; else the last, so a finished run still shows a step.
154 *
155 * @param {Run} run
156 * @param {string[]} keys every step's key, in the page's order
157 * @param {string | null} chosen
158 */
159export function shownStep(run, keys, chosen) {
160  if (chosen && keys.includes(chosen)) return chosen;
161  return keys.find((key) => !run.steps[key]?.done) ?? keys[keys.length - 1] ?? null;
162}
163
164/**
165 * The step before or after `key`, or null at either end.
166 *
167 * @param {string[]} keys
168 * @param {string} key
169 * @param {-1 | 1} by
170 */
171export function stepBeside(keys, key, by) {
172  const at = keys.indexOf(key);
173  return at === -1 ? null : (keys[at + by] ?? null);
174}
175
176const when = (/** @type {number | null} */ ms) => (ms === null ? "" : new Date(ms).toISOString());
177
178/** The Bioschemas profile a run's download follows (docs/KNOWLEDGE-BASE.md, P4). */
179const LAB_PROCESS_PROFILE = "https://bioschemas.org/profiles/LabProcess/0.1-DRAFT";
180
181/**
182 * The saved record as a plain object: what a download is, and what survives the browser. Only what the person
183 * entered or did, with the procedure's own identity so the record says which version it followed.
184 *
185 * It is also a Bioschemas LabProcess (P4): runs are private, so this download is the only place one is written. The
186 * protocol it executes is named by the `@id` the procedure's page gives its LabProtocol, and its version.
187 *
188 * A step's `key` is unique in the procedure (its section and its number: numbering restarts in a section that starts
189 * its own list), `number` is the one the page prints.
190 *
191 * @param {Run} run
192 * @param {Array<{ key?: string, number: number | string, section?: string, text: string }>} steps
193 * @param {string} [origin] the site the run was made on
194 */
195export function runRecord(run, steps, origin = SITE_ORIGIN) {
196  // A run made on a frozen version's page carries its /v/ address; the protocol's identity is its plain page.
197  const page = run.path.replace(/\/v\/[^/]+$/, "");
198  return {
199    "@context": "https://schema.org",
200    "@type": "LabProcess",
201    "http://purl.org/dc/terms/conformsTo": { "@id": LAB_PROCESS_PROFILE },
202    name: `Run of ${run.title}`,
203    executesLabProtocol: { "@type": "LabProtocol", "@id": `${origin}${page}#procedure`, name: run.title, url: `${origin}${run.path}`, ...(run.version ? { version: run.version } : {}) },
204    startTime: when(run.startedAt),
205    ...(run.finishedAt !== null ? { endTime: when(run.finishedAt) } : {}),
206    ...(run.note.trim() ? { description: run.note.trim() } : {}),
207    ...(run.scale !== null ? { parameterValue: [{ "@type": "PropertyValue", name: "Scale", value: run.scale }] } : {}),
208    record: "dustinedwards.info run",
209    format: RUN_VERSION,
210    procedure: { path: run.path, title: run.title, version: run.version },
211    scale: run.scale,
212    startedAt: when(run.startedAt),
213    finishedAt: when(run.finishedAt),
214    note: run.note,
215    steps: steps.map((s) => {
216      const st = stepOf(run, s.key ?? s.number);
217      return { step: s.number, section: s.section ?? "", text: s.text, done: st.done, doneAt: when(st.doneAt), note: st.note };
218    }),
219  };
220}
221
222/**
223 * The same record as plain Markdown, for a notebook or an email: a heading, the run's facts, and each step as a
224 * checked or unchecked line with its note under it.
225 *
226 * @param {Run} run
227 * @param {Array<{ key?: string, number: number | string, section?: string, text: string }>} steps
228 */
229export function runMarkdown(run, steps) {
230  const lines = [`# Run: ${run.title}`, ""];
231  lines.push(`Protocol: ${run.path}${run.version ? `, version ${run.version}` : ""}`);
232  if (run.scale !== null) lines.push(`Scale: ${run.scale}`);
233  lines.push(`Started: ${when(run.startedAt)}`);
234  if (run.finishedAt !== null) lines.push(`Finished: ${when(run.finishedAt)}`);
235  if (run.note.trim()) lines.push("", run.note.trim());
236  lines.push("", "## Steps", "");
237  let section = "";
238  for (const s of steps) {
239    if ((s.section ?? "") !== section) {
240      section = s.section ?? "";
241      if (section) lines.push("", `### ${section}`, "");
242    }
243    const st = stepOf(run, s.key ?? s.number);
244    lines.push(`- [${st.done ? "x" : " "}] ${s.number}. ${s.text.replace(/\s+/g, " ").trim()}${st.done && st.doneAt ? ` (${when(st.doneAt)})` : ""}`);
245    if (st.note.trim()) lines.push(`  - Note: ${st.note.trim().replace(/\n+/g, " ")}`);
246  }
247  return `${lines.join("\n")}\n`;
248}
249
250/**
251 * Parses a stored run, or returns null: a stored value from another format or one that is not a run is ignored, never
252 * trusted. Only the shapes this module writes are accepted.
253 *
254 * @param {unknown} raw
255 * @returns {Run | null}
256 */
257export function parseRun(raw) {
258  if (typeof raw !== "string") return null;
259  let value;
260  try {
261    value = JSON.parse(raw);
262  } catch {
263    return null;
264  }
265  if (!value || typeof value !== "object" || value.v !== RUN_VERSION) return null;
266  // typeof null is "object", so a null `steps` must be refused by name.
267  const plainObject = (/** @type {unknown} */ x) => x !== null && typeof x === "object" && !Array.isArray(x);
268  if (typeof value.path !== "string" || typeof value.startedAt !== "number" || !plainObject(value.steps) || !plainObject(value.timers)) return null;
269  return /** @type {Run} */ ({
270    v: RUN_VERSION,
271    path: value.path,
272    version: typeof value.version === "string" ? value.version : "",
273    title: typeof value.title === "string" ? value.title : "",
274    scale: typeof value.scale === "number" ? value.scale : null,
275    startedAt: value.startedAt,
276    finishedAt: typeof value.finishedAt === "number" ? value.finishedAt : null,
277    note: typeof value.note === "string" ? value.note : "",
278    steps: value.steps,
279    timers: value.timers,
280  });
281}