Public: anyone can read this; the crew can change it.

A card that shows a duration reads it in words, never raw milliseconds #15174

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

scout/forge:scout/15157-a-card-that-shows-a-duration-reads-it-in → main 7 commits fork 4 threads · 4 unresolved

  • Merged. scout/15157-a-card-that-shows-a-duration-reads-it-in was merged into main as 0083467.

Review

Sign in to review this change.
6 files changed +54 −25
src/actions/schedules.ts +2 −1
@@ -10,6 +10,7 @@ import type { App } from "../app.ts";
1010 import { getAppByRepo } from "../core/apps.ts";
1111 import { canAdmin, listReposWritableTo, type Repo } from "../core/repos.ts";
1212 import type { User } from "../core/users.ts";
13 import { durationWords } from "../system/format.ts";
1314 import { failedJobs, failingNow, runNow, runsOf, scheduleTimer, scheduleTimers, setPaused, type TimerRun } from "../core/timers.ts";
1415 import { err, ok, type Result } from "../kernel/result.ts";
1516 import { requireReader, requireWriter } from "./access.ts";
@@ -54,7 +55,7 @@ const lastOf = (r: TimerRun, writer: boolean): LastRun => ({
5455 });
5556
5657 function lineOf(r: Omit<ScheduleRow, "line">): string {
57 const last = r.last === null ? "never run" : `last ${r.last.status === "ok" ? "ok" : r.last.status} ${when(r.last.at, r.timezone)}${r.last.status === "ok" ? ` (${r.last.durationMs} ms${r.last.late === null ? "" : ", ran late"})` : ""}`;
58 const last = r.last === null ? "never run" : `last ${r.last.status === "ok" ? "ok" : r.last.status} ${when(r.last.at, r.timezone)}${r.last.status === "ok" ? ` (${durationWords(r.last.durationMs)}${r.last.late === null ? "" : ", ran late"})` : ""}`;
5859 return `${r.name} · ${r.cron} ${r.timezone} · ${r.paused ? "paused" : `next ${r.nextAt === null ? "soon" : when(r.nextAt, r.timezone)}`} · ${last}`;
5960 }
6061
src/snapshot/drill.ts +7 −19
@@ -82,28 +82,16 @@ export function formatBytes(bytes: number): string {
8282 return `${Math.round(v * 10) / 10} ${units[i]}`;
8383 }
8484
85 /** Units in a span's short form ("6 min 12 s") and long form ("6 minutes 12 seconds"). */
86 const SPAN_UNITS = {
87 short: { min: () => "min", s: () => "s" },
88 long: { min: (n: number) => (n === 1 ? "minute" : "minutes"), s: (n: number) => (n === 1 ? "second" : "seconds") },
89 } as const;
90
9185 /**
92 * A span for people. Short: "6 min 12 s", "58 s", "340 ms". Long, for sentences (#15066): "6
93 * minutes 12 seconds", "58 seconds", and "less than a second" under one (zero too), so it reads
94 * after "took" or "after" and never says ms.
86 * A span for the verdict's lines: "6 min 12 s", "58 s", "340 ms". Sentences and cards use
87 * `durationWords`.
9588 */
96 export function formatSpan(ms: number, form: "short" | "long" = "short"): string {
97 const ok = Number.isFinite(ms) && ms >= 0;
98 if (!ok || ms < 1_000) {
99 if (form === "long") return "less than a second";
100 return ok ? `${Math.round(ms)} ms` : "0 ms";
101 }
102 const u = SPAN_UNITS[form];
89 export function formatSpan(ms: number): string {
90 if (!Number.isFinite(ms) || ms < 0) return "0 ms";
91 if (ms < 1_000) return `${Math.round(ms)} ms`;
10392 const s = Math.round(ms / 1_000);
104 if (s < 60) return `${s} ${u.s(s)}`;
105 const m = Math.floor(s / 60);
106 return s % 60 === 0 ? `${m} ${u.min(m)}` : `${m} ${u.min(m)} ${s % 60} ${u.s(s % 60)}`;
93 if (s < 60) return `${s} s`;
94 return s % 60 === 0 ? `${s / 60} min` : `${Math.floor(s / 60)} min ${s % 60} s`;
10795 }
10896
10997 /** What people call each phase; the manifest read counts as download. */
src/snapshot/drill_card_words.ts +3 −2
@@ -6,11 +6,12 @@
66 * Plain data in, strings out; the page escapes them.
77 */
88
9 import { formatSpan, timeByPart, type DrillResult, type DrillStep } from "./drill.ts";
9 import { durationWords } from "../system/format.ts";
10 import { timeByPart, type DrillResult, type DrillStep } from "./drill.ts";
1011 import { plainDurations } from "./verdict.ts";
1112
1213 /** A span in the card's words: "6 minutes 12 seconds", "less than a second". */
13 export const spokenSpan = (ms: number): string => formatSpan(ms, "long");
14 export const spokenSpan = (ms: number): string => durationWords(ms);
1415
1516 /** What the drill was doing during each step, as the card says it. */
1617 const DOING: Record<DrillStep, string> = {
src/snapshot/drill_cost.ts +4 −3
@@ -8,7 +8,8 @@
88 */
99
1010 import { LIMITS } from "../settings/limits.ts";
11 import { formatBytes, formatSpan, type DrillResult } from "./drill.ts";
11 import { durationWords } from "../system/format.ts";
12 import { formatBytes, type DrillResult } from "./drill.ts";
1213
1314 /**
1415 * Where the limit comes from, in the words the page uses: the `drill.memory_mb` setting on
@@ -26,7 +27,7 @@ const share = (peak: number, limit: number): number => (limit > 0 ? Math.ceil((p
2627 export function costLine(d: Pick<DrillResult, "cost">): string {
2728 const c = d.cost;
2829 if (c === undefined) return "elapsed time and peak memory not recorded for this drill";
29 return `took ${formatSpan(c.elapsedMs, "long")}, peak ${formatBytes(c.peakBytes)} of its ${formatBytes(c.limitBytes)} limit (${share(c.peakBytes, c.limitBytes)}%)`;
30 return `took ${durationWords(c.elapsedMs)}, peak ${formatBytes(c.peakBytes)} of its ${formatBytes(c.limitBytes)} limit (${share(c.peakBytes, c.limitBytes)}%)`;
3031 }
3132
3233 /** One fact of the drill's cost: its label and its value, as a `dl` row says it. */
@@ -43,7 +44,7 @@ export function costFacts(d: Pick<DrillResult, "cost">): CostFact[] {
4344 const c = d.cost;
4445 if (c === undefined) return [{ label: "Drill cost", value: "elapsed time and peak memory not recorded for this drill" }];
4546 return [
46 { label: "Took", value: formatSpan(c.elapsedMs, "long") },
47 { label: "Took", value: durationWords(c.elapsedMs) },
4748 { label: "Peak memory", value: `${formatBytes(c.peakBytes)}, ${share(c.peakBytes, c.limitBytes)}% of the limit` },
4849 { label: "Limit", value: `${formatBytes(c.limitBytes)}: ${LIMIT_RULE}` },
4950 ];
src/system/format.ts +15
@@ -17,3 +17,18 @@ export const spark = (history: readonly number[]): string =>
1717
1818 export const span = (s: number): string =>
1919 s < 90 ? `${s}s` : s < 5400 ? `${Math.round(s / 60)}m` : s < 172_800 ? `${Math.round(s / 3600)}h` : `${Math.round(s / 86_400)}d`;
20
21 const unit = (n: number, word: string): string => `${n} ${word}${n === 1 ? "" : "s"}`;
22 /**
23 * Milliseconds in words for a sentence or a card, never raw: "less than a second", "45 seconds",
24 * "1 minute 1 second", "1 hour 30 minutes". Seconds are rounded; only the two largest units are
outdated

The comment says exact and never rounded away, but days plus 59 s drops the seconds and the test pins that. Reword it, or fix the behaviour.

25 * kept, so "1 day 59 seconds" reads "1 day". Anything that is not a finite number, or is under a
26 * second, reads "less than a second". The compact figure form ("3h 5m") is `flow/figure_format.ts`.
27 */
outdated

Math.round(ms) gives "1000 ms" for 999.6. Return seconds from 999.5 up.

28 export const durationWords = (ms: number): string => {
29 if (!Number.isFinite(ms) || ms < 1000) return "less than a second";
30 const s = Math.round(ms / 1000);
31 const parts: [number, string][] = [[Math.floor(s / 86_400), "day"], [Math.floor((s % 86_400) / 3600), "hour"], [Math.floor((s % 3600) / 60), "minute"], [s % 60, "second"]];
32 const at = parts.findIndex(([n]) => n > 0);
33 return parts.slice(at, at + 2).filter(([n]) => n > 0).map(([n, w]) => unit(n, w)).join(" ");

Non-blocking: src/flow/estimate_words.ts exports another durationWords. Two helpers with one name will be confused; unify them.

34 };
test/format-duration.test.ts added +23
@@ -0,0 +1,23 @@
1 import { expect, test } from "bun:test";
2 import { durationWords } from "../src/system/format.ts";
3 import { costFacts, costLine } from "../src/snapshot/drill_cost.ts";
4 import { spokenSpan } from "../src/snapshot/drill_card_words.ts";
5
6 test("durationWords reads milliseconds in words, never ms", () => {
7 expect(durationWords(0)).toBe("less than a second");
8 expect(durationWords(900)).toBe("less than a second");
9 expect(durationWords(999.6)).toBe("less than a second");
10 expect(durationWords(1000)).toBe("1 second");
11 expect(durationWords(61_000)).toBe("1 minute 1 second");
12 expect(durationWords(5_400_000)).toBe("1 hour 30 minutes");
13 expect(durationWords(180_000)).toBe("3 minutes");
14 expect(durationWords(Number.NaN)).toBe("less than a second");
outdated

This drill-card test uses formatSpan on main, not your helper, so it would pass without your change. Route the card through duration, or drop the test.

15 expect(durationWords(86_400_000 + 59_000)).toBe("1 day");
16 });
17
18 test("the drill card's words and cost line come from durationWords", () => {
19 const cost = { elapsedMs: 3_900_000, peakBytes: 1024, limitBytes: 1024 * 1024 };
20 expect(costLine({ cost })).toContain("took 1 hour 5 minutes,");
21 expect(costFacts({ cost })[0]?.value).toBe("1 hour 5 minutes");
22 expect(spokenSpan(3_900_000)).toBe("1 hour 5 minutes");
23 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs