components/time/time.ts

Functions

Imports

It imports no other module of this repo. Imported by components/draft-compare/draft-compare-render.ts, components/flag-list/flag-list.ts, components/history-list/history-list-model.ts, components/history-list/history-list-rows.ts, components/history-list/history-list.react.tsx, components/history-list/history-list.ts, components/moderation-queue/moderation-queue.ts, components/people-roles/people-roles.ts, components/posts-list/posts-list.ts, components/publish-gate/publish-gate.ts, components/time/time.react.tsx, components/usage-meter/usage-meter.ts.

Source

1// Times in words. Relative in rows ("5 minutes ago", never "5m"), exact in the viewer's
2// zone with UTC beside it. The pure functions take the zone so they can be checked anywhere; in a page
3// the zone is the viewer's.
4
5export const SEC = 1000;
6export const MIN = 60 * SEC;
7export const HOUR = 60 * MIN;
8export const DAY = 24 * HOUR;
9
10// How often enhance() and the React wrapper redraw relative times.
11export const REFRESH_MS = 30 * SEC;
12
13// A server timestamp with no zone (D1's datetime('now'), "YYYY-MM-DD HH:MM:SS", or the
14// same with a T) is UTC, because every timestamp the Worker writes is; Date.parse would
15// read it as local time. An ISO string with a zone passes through.
16const ZONELESS = /^\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}(:\d{2}(\.\d+)?)?$/;
17
18export function parse(iso: string): number {
19  const s = iso.trim();
20  return Date.parse(ZONELESS.test(s) ? `${s.replace(" ", "T")}Z` : s);
21}
22
23function plural(n: number, unit: string): string {
24  return `${n} ${unit}${n === 1 ? "" : "s"}`;
25}
26
27const dayKey = (zone?: string) => new Intl.DateTimeFormat("en-CA", { timeZone: zone, year: "numeric", month: "2-digit", day: "2-digit" });
28
29// Whole calendar days from `t` to `now` in the zone: 1 is yesterday, -1 tomorrow.
30export function calendarDays(t: number, now: number, zone?: string): number {
31  const f = dayKey(zone);
32  const at = (x: number) => {
33    const [y = 0, m = 1, d = 1] = f.format(x).split("-").map(Number);
34    return Date.UTC(y, m - 1, d);
35  };
36  return Math.round((at(now) - at(t)) / DAY);
37}
38
39// "12 September", or "12 September 2025" when the year is not this one.
40export function day(t: number, now: number = Date.now(), zone?: string): string {
41  const year = (x: number) => new Intl.DateTimeFormat("en-GB", { timeZone: zone, year: "numeric" }).format(x);
42  return new Intl.DateTimeFormat("en-GB", { timeZone: zone, day: "numeric", month: "long", year: year(t) === year(now) ? undefined : "numeric" }).format(t);
43}
44
45// Relative, spelled out: "just now", "less than a minute ago", "5 minutes ago",
46// "3 hours ago", "yesterday", "4 days ago", "12 September"; and ahead, "in 3 hours",
47// "tomorrow". Minutes and hours are whole and round down, so "1 hour ago" means at least
48// an hour.
49export function relative(t: number, now: number = Date.now(), zone?: string): string {
50  const d = now - t;
51  const a = Math.abs(d);
52  const ahead = d < 0;
53  const say = (s: string) => (ahead ? `in ${s}` : `${s} ago`);
54  if (!Number.isFinite(d)) return "";
55  if (a < 10 * SEC) return "just now";
56  if (a < MIN) return say("less than a minute");
57  if (a < HOUR) return say(plural(Math.floor(a / MIN), "minute"));
58  if (a < DAY) return say(plural(Math.floor(a / HOUR), "hour"));
59  const days = calendarDays(t, now, zone);
60  if (days === 0) return say(plural(Math.floor(a / HOUR), "hour"));
61  if (days === 1) return "yesterday";
62  if (days === -1) return "tomorrow";
63  if (Math.abs(days) < 7) return say(plural(Math.abs(days), "day"));
64  return day(t, now, zone);
65}
66
67// The Portal's compact UTC form, for logs and ids: "2026-09-30 13:02Z".
68export function utc(t: number): string {
69  return `${new Date(t).toISOString().replace("T", " ").slice(0, 16)}Z`;
70}
71
72function parts(t: number, zone: string | undefined, withZone: boolean): Record<string, string> {
73  const f = new Intl.DateTimeFormat("en-GB", {
74    timeZone: zone,
75    day: "numeric",
76    month: "long",
77    year: "numeric",
78    hour: "2-digit",
79    minute: "2-digit",
80    hourCycle: "h23",
81    timeZoneName: withZone ? "short" : undefined,
82  });
83  const out: Record<string, string> = {};
84  for (const p of f.formatToParts(t)) out[p.type] = p.value;
85  return out;
86}
87
88function isUtc(zone?: string): boolean {
89  const z = new Intl.DateTimeFormat("en-GB", { timeZone: zone }).resolvedOptions().timeZone;
90  return z === "UTC" || z === "Etc/UTC" || z === "Etc/GMT" || z === "GMT";
91}
92
93// What a time that cannot be read says, in place of a blank or "NaN" (the Portal's
94// exactTime does the same): a row never shows nothing where a time belongs.
95export const UNREADABLE = "an unreadable time";
96
97// Exact, in the viewer's zone with UTC beside it, in two parts so the UTC part can be kept
98// whole on a line (the Portal's `.when .faint { white-space: nowrap }`): the local time, and
99// "(13:02 UTC)". UTC's date is added when it differs from the local one; a viewer in UTC sees
100// one time and no second part.
101export function exactParts(t: number, zone?: string): { local: string; utc: string | null } {
102  if (!Number.isFinite(t)) return { local: UNREADABLE, utc: null };
103  const u = parts(t, "UTC", false);
104  const uDate = `${u.day} ${u.month} ${u.year}`;
105  const uTime = `${u.hour}:${u.minute} UTC`;
106  if (isUtc(zone)) return { local: `${uDate}, ${uTime}`, utc: null };
107  const l = parts(t, zone, true);
108  const lDate = `${l.day} ${l.month} ${l.year}`;
109  return { local: `${lDate}, ${l.hour}:${l.minute} ${l.timeZoneName}`, utc: `(${lDate === uDate ? uTime : `${uDate}, ${uTime}`})` };
110}
111
112// "30 September 2026, 14:02 BST (13:02 UTC)".
113export function exact(t: number, zone?: string): string {
114  const p = exactParts(t, zone);
115  return p.utc ? `${p.local} ${p.utc}` : p.local;
116}
117
118export type TimeFormat = "relative" | "exact";
119
120// The text a <time class="cap-time"> shows.
121export function text(t: number, format: TimeFormat, now: number = Date.now(), zone?: string): string {
122  if (!Number.isFinite(t)) return UNREADABLE;
123  return format === "exact" ? exact(t, zone) : relative(t, now, zone);
124}
125
126// The page's "now" for relative times when the browser's clock and the server's disagree:
127// the browser's clock moved onto the server's by the skew measured when the data arrived,
128// and never earlier than the newest time a server read reported. Otherwise a row written
129// after the page's last tick, or on a server whose clock runs ahead of the browser's, reads
130// "in less than a minute" for something that has just happened. From the Portal's
131// lib/format.ts (portalNow). Pass it as a React `now`, or give setClock a function that
132// returns it.
133export function serverNow(clientNow: number, skew: number, newestServerRead: number): number {
134  return Math.max(clientNow + skew, newestServerRead);
135}
136
137let clock: () => number = () => Date.now();
138
139// Replaces the clock the plain behaviour module reads (the default is Date.now), and
140// redraws. setClock(null) puts it back.
141export function setClock(fn: (() => number) | null): void {
142  clock = fn ?? (() => Date.now());
143  for (const el of live) if (el.isConnected) draw(el);
144}
145
146// "now" for an element: a frozen data-cap-now on it or an ancestor (specimens, tests,
147// printed reports), else the clock.
148function nowFor(el: Element): { now: number; frozen: boolean } {
149  const fixed = el.closest<HTMLElement>("[data-cap-now]")?.dataset.capNow;
150  return fixed ? { now: parse(fixed), frozen: true } : { now: clock(), frozen: false };
151}
152
153// Writes an exact time as its local part, then its UTC part in a span of its own.
154function drawExact(el: HTMLElement, t: number): void {
155  const p = exactParts(t);
156  const whole = p.utc ? `${p.local} ${p.utc}` : p.local;
157  const hasSpan = el.querySelector(".cap-time-utc") !== null;
158  if (el.textContent === whole && hasSpan === (p.utc !== null)) return;
159  el.textContent = p.utc ? `${p.local} ` : p.local;
160  if (!p.utc) return;
161  const span = document.createElement("span");
162  span.className = "cap-time-utc";
163  span.textContent = p.utc;
164  el.append(span);
165}
166
167export function draw(el: HTMLElement): void {
168  const iso = el.getAttribute("datetime");
169  if (!iso) return;
170  const { now } = nowFor(el);
171  const t = parse(iso);
172  if (el.dataset.format === "exact") return drawExact(el, t);
173  const next = text(t, "relative", now);
174  if (el.textContent !== next) el.textContent = next;
175}
176
177const live = new Set<HTMLElement>();
178let timer: number | undefined;
179
180function tick(): void {
181  for (const el of live) {
182    if (el.isConnected) draw(el);
183    else live.delete(el);
184  }
185  if (live.size === 0) {
186    window.clearInterval(timer);
187    timer = undefined;
188  }
189}
190
191// Attaches to every [data-cap="time"] under root not yet attached: writes its text, and
192// keeps relative times fresh every 30 seconds with one shared timer. Returns a function
193// that detaches.
194export function enhance(root: ParentNode = document): () => void {
195  const mine: HTMLElement[] = [];
196  for (const el of root.querySelectorAll<HTMLElement>("[data-cap='time']:not([data-cap-ready])")) {
197    el.dataset.capReady = "";
198    draw(el);
199    if (el.dataset.format !== "exact" && !nowFor(el).frozen) {
200      live.add(el);
201      mine.push(el);
202    }
203  }
204  if (live.size > 0 && timer === undefined) timer = window.setInterval(tick, REFRESH_MS);
205  return () => {
206    for (const el of mine) {
207      live.delete(el);
208      delete el.dataset.capReady;
209    }
210    if (live.size === 0 && timer !== undefined) {
211      window.clearInterval(timer);
212      timer = undefined;
213    }
214  };
215}