parse | (iso: string): number | |
|---|
toMs | (at: string | number | Date | null | undefined): number | A time as a number of milliseconds: a number, a Date, or a server timestamp (a zoneless one is UTC). NaN for nothing, an empty string or a value that is not a time. |
|---|
toMsOrNull | (at: string | number | Date | null | undefined): number | null | The same, null where toMs gives NaN, for a caller that tests for "no time" with == null. |
|---|
calendarDays | (t: number, now: number, zone?: string | undefined): number | Whole calendar days from t to now in the zone: 1 is yesterday, -1 tomorrow. |
|---|
day | (t: number, now?: number, zone?: string | undefined): string | "September 12", or "September 12, 2025" when the year is not this one: American English, the family's (Dustin, 2026-10-25). |
|---|
relative | (t: number, now?: number, zone?: string | undefined, options?: RelativeOptions): string | Relative, spelled out: "just now", "less than a minute ago", "5 minutes ago", "3 hours ago", "yesterday", "4 days ago", "September 12"; and ahead, "in 3 hours", "tomorrow". Minutes and hours are whole and round down, so "1 hour ago" means at least an hour. The unit words are Intl.RelativeTimeFormat's. |
|---|
utc | (t: number): string | The Portal's compact UTC form, for logs and ids: "2026-09-30 13:02Z". |
|---|
formatDate | (at: string | number | Date | null | undefined, options?: FormatDateOptions): string | null | A date, American English (the family's), from a number, a Date or a timestamp string. Null for a value that is not a time ("Invalid Date" is never shown; the caller says what goes in its place). Intl.DateTimeFormat does the words: dateStyle and timeStyle (MDN: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat). |
|---|
dateRange | (start: string | number | Date | null | undefined, end: string | number | Date | null | undefined, options?: Pick<FormatDateOptions, "style" | "zone">): string | null | A meeting's dates: "May 1, 2026", "May 1, 2026 to May 2, 2026", or null with no dates. One date when both are the same moment. |
|---|
timecode | (ms: number | null | undefined, options?: { hours?: "auto" | "always" | undefined; }): string | A duration as a player's timecode writes it: "4:05", "1:02:03". With hours: "always", the form a feed wants for <itunes:duration>: "00:04:05", "01:02:03". Negative, missing or NaN is zero. |
|---|
duration | (ms: number | null | undefined, options?: DurationOptions): string | A duration in words, for a screen reader or a sentence: "3 minutes, 12 seconds", "1 hour, 2 minutes, 3 seconds", "0 seconds". Units that are zero are left out. |
|---|
span | (ms: number | null | undefined): string | A rough duration to the largest unit, rounded down, for "waiting 3 hours" and "oldest 2 days": "less than a minute", "5 minutes", "3 hours", "2 days". The spelled-out form of a compact "3.2h". |
|---|
until | (t: number, now?: number): string | How soon something scheduled fires, spelled out: "due now" once the moment has passed, then "in 5 minutes", "in 3 hours, 20 minutes" (the hour form carries the minutes, since "in 3 hours" hides up to 59 of them), and "in 2 days" (a day or more drops the hours, which would be noise). |
|---|
zoneName | (t: number, zone?: string | undefined): string | The zone's short name as an American reader knows it: "CST", "CDT", "EST", "PDT". en-US has names only for the American zones and writes "GMT+1" for the rest, so a zone it has no name for takes the British one when there is one ("BST", "CEST"), else the offset. |
|---|
exactParts | (t: number, zone?: string | undefined): { local: string; utc: string | null; } | Exact, in the viewer's zone with UTC beside it, in two parts so the UTC part can be kept whole on a line (the Portal's .when .faint { white-space: nowrap }): the local time, and "(1:02 PM UTC)". UTC's date is added when it differs from the local one; a viewer in UTC sees one time and no second part. |
|---|
exact | (t: number, zone?: string | undefined): string | "November 3, 2026, 8:00 AM CST (2:00 PM UTC)". |
|---|
text | (t: number, format: TimeFormat, now?: number, zone?: string | undefined): string | The text a <time class="cap-time"> shows. |
|---|
serverNow | (clientNow: number, skew: number, newestServerRead: number): number | The page's "now" for relative times when the browser's clock and the server's disagree: the browser's clock moved onto the server's by the skew measured when the data arrived, and never earlier than the newest time a server read reported. Otherwise a row written after the page's last tick, or on a server whose clock runs ahead of the browser's, reads "in less than a minute" for something that has just happened. From the Portal's lib/format.ts (portalNow). Pass it as a React now, or give setClock a function that returns it. |
|---|
setClock | (fn: (() => number) | null): void | Replaces the clock the plain behavior module reads (the default is Date.now), and redraws. setClock(null) puts it back. |
|---|
nowFor | (el: Element): { now: number; frozen: boolean; } | "now" for an element: a frozen data-cap-now on it or an ancestor (specimens, tests, printed reports), else the clock. |
|---|
draw | (el: HTMLElement): void | |
|---|
enhance | (root?: ParentNode): () => void | Attaches to every [data-cap="time"] under root not yet attached: writes its text, and keeps relative times fresh every 30 seconds with one shared timer. Returns a function that detaches. |
|---|
knownZone | (zone: string | null | undefined): string | A zone name the browser's Intl knows, else "UTC": a zone from a form or from Cloudflare's request.cf.timezone can be missing or unknown, and Intl throws on an unknown one. From Carrel (lib/writing/progress.ts). |
|---|
laterUntil | (now: number | Date, zone: string | null | undefined, hour?: number): string | When Later brings something back: hour (8 am) on the next calendar day in the person's zone (UTC when the zone is unknown), as an ISO instant. The wall-clock time is found by correcting a first guess by the zone's offset, twice, so a change to or from summer time overnight still lands on 8 am. From Carrel's Home (lib/desk.server.ts, laterUntil). |
|---|
two | (n: number): string | A number as two digits, "07". |
|---|