@graphty/graph-io 0.0.0 → 0.2.1

package/src/common/report.ts

@@ -0,0 +1,352 @@
+/**
+ * The ImportReport builder shared by every importer (design section 8.6): issues by category and
+ * severity, the element counts, loss notes, the error limit with truncation, and the ImportError
+ * that carries the partial report when the importer aborts.
+ *
+ * Layering (design section 8.6): the builder throws on the first hard error; the importer catches
+ * per element, records an ImportIssue through this class, skips the element and continues until the
+ * error limit, then aborts with E_IMPORT. `recordError()` is that catch: it turns a thrown
+ * GraphFormatError into an issue with the category its code implies and re-throws everything else
+ * (an ImportError, an abort reason, a programming error) unchanged.
+ */
+
+import { GraphFormatError, type GraphFormatErrorCode } from "@graphty/graph-format";
+
+import { ImportError, type ImportIssue, type ImportReport, type IssueCategory, type LossNote } from "../types.js";
+
+/**
+ * Where an issue was found: the 1-based line and the element (id or attribute name) when known.
+ * Consumed by the per-format importers and exporters under src/formats.
+ * @public
+ */
+export interface IssueLocation {
+    /** The 1-based source line, when known. */
+    readonly line?: number | null | undefined;
+    /** The element the issue is about, when known. */
+    readonly element?: string | null | undefined;
+}
+
+/**
+ * The mutable element counters of a report in progress; importers increment them directly in hot loops.
+ * Consumed by the per-format importers and exporters under src/formats.
+ * @public
+ */
+export interface MutableCounts {
+    /** Nodes pushed. */
+    nodes: number;
+    /** Logical edges pushed (both halves of an expanded edge count). */
+    edges: number;
+    /** Nodes skipped after an error. */
+    skippedNodes: number;
+    /** Edges skipped after an error. */
+    skippedEdges: number;
+    /** Source edges expanded into two logical edges (design section 3.6). */
+    expandedMixed: number;
+}
+
+/**
+ * The category a thrown GraphFormatError maps to when an importer catches it per element: the codes
+ * that mean "the file referenced something it never declared" are missing values, a refused
+ * direction change is a coercion, size and feature limits are unsupported, everything else is a
+ * validation error of the element.
+ */
+const CATEGORY_BY_CODE: Readonly<Partial<Record<GraphFormatErrorCode, IssueCategory>>> = {
+    E_UNKNOWN_NODE: "missing-value",
+    E_UNKNOWN_COLUMN: "missing-value",
+    E_DIRECTED: "coercion",
+    E_TOO_LARGE: "unsupported",
+    E_UNSUPPORTED: "unsupported",
+    E_GPU_INELIGIBLE: "unsupported",
+};
+
+/**
+ * The code a report used to give a thrown value that was not a GraphFormatError. Since audit round
+ * 1 such a value (a TypeError, a RangeError: a bug in an importer or a sink, never a defect of the
+ * input) propagates out of import() untouched, so no importer records this code any more; the
+ * constant stays for consumers that switch on the codes of earlier reports.
+ */
+export const PARSE_ERROR_CODE = "E_PARSE";
+
+/**
+ * Accumulates an ImportReport while an importer runs. Errors count toward the error limit; the
+ * error that takes the count beyond the limit is still recorded, `truncated` is set, and an
+ * ImportError carrying the report so far is thrown (design section 8.4: "beyond it the importer
+ * aborts with E_IMPORT"). Warnings never abort.
+ */
+export class ImportReportBuilder {
+    /** The importer's format name. */
+    readonly format: string;
+
+    /** The error limit the report was created with. */
+    readonly errorLimit: number;
+
+    /** The element counters; importers increment them directly. */
+    readonly counts: MutableCounts = { nodes: 0, edges: 0, skippedNodes: 0, skippedEdges: 0, expandedMixed: 0 };
+
+    private readonly issueList: ImportIssue[] = [];
+
+    private readonly lossList: LossNote[] = [];
+
+    private readonly onceCodes = new Set<string>();
+
+    private errors = 0;
+
+    private warnings = 0;
+
+    private truncatedFlag = false;
+
+    private readonly startedAt: number;
+
+    /**
+     * Create a builder for one import call.
+     * @param format - the importer's format name
+     * @param errorLimit - errors tolerated before the import aborts; Infinity for no limit
+     */
+    constructor(format: string, errorLimit: number) {
+        this.format = format;
+        this.errorLimit = errorLimit;
+        this.startedAt = now();
+    }
+
+    /**
+     * Issues recorded so far, in order.
+     * @returns the live list (not copied; finish() copies)
+     */
+    get issues(): readonly ImportIssue[] {
+        return this.issueList;
+    }
+
+    /**
+     * Issues with severity "error".
+     * @returns the count
+     */
+    get errorCount(): number {
+        return this.errors;
+    }
+
+    /**
+     * Issues with severity "warning".
+     * @returns the count
+     */
+    get warningCount(): number {
+        return this.warnings;
+    }
+
+    /**
+     * Whether the error limit was exceeded.
+     * @returns true once an error beyond the limit was recorded
+     */
+    get truncated(): boolean {
+        return this.truncatedFlag;
+    }
+
+    /**
+     * Loss notes recorded so far.
+     * @returns the live list
+     */
+    get lossy(): readonly LossNote[] {
+        return this.lossList;
+    }
+
+    /**
+     * Record an error. When the count goes beyond the error limit the report is marked truncated
+     * and an ImportError carrying it is thrown; the importer does not catch that.
+     * @param category - the issue category
+     * @param code - a stable code such as "E_UNKNOWN_NODE"
+     * @param message - a plain-ASCII message
+     * @param where - the line and element, when known
+     * @returns the recorded issue
+     */
+    error(category: IssueCategory, code: string, message: string, where?: IssueLocation): ImportIssue {
+        const issue = makeIssue(category, "error", code, message, where);
+        this.issueList.push(issue);
+        this.errors++;
+        if (this.errors > this.errorLimit) {
+            this.truncatedFlag = true;
+            throw this.abort(`error limit of ${this.errorLimit} exceeded: ${message}`, {
+                code,
+                limit: this.errorLimit,
+            });
+        }
+        return issue;
+    }
+
+    /**
+     * Record a warning; warnings never count toward the limit.
+     * @param category - the issue category
+     * @param code - a stable code such as "W_WIDENED"
+     * @param message - a plain-ASCII message
+     * @param where - the line and element, when known
+     * @returns the recorded issue
+     */
+    warning(category: IssueCategory, code: string, message: string, where?: IssueLocation): ImportIssue {
+        const issue = makeIssue(category, "warning", code, message, where);
+        this.issueList.push(issue);
+        this.warnings++;
+        return issue;
+    }
+
+    /**
+     * Record a warning the first time its key is seen and ignore later repeats, for conditions
+     * that would otherwise produce one warning per row.
+     * @param category - the issue category
+     * @param code - the stable code
+     * @param message - a plain-ASCII message
+     * @param where - the line and element, when known
+     * @param key - what repeats are deduplicated on; the code itself by default (pass `code:column`
+     * to warn once per column)
+     * @returns the recorded issue, or null when the key was already recorded
+     */
+    warnOnce(
+        category: IssueCategory,
+        code: string,
+        message: string,
+        where?: IssueLocation,
+        key: string = code,
+    ): ImportIssue | null {
+        if (this.onceCodes.has(key)) {
+            return null;
+        }
+        this.onceCodes.add(key);
+        return this.warning(category, code, message, where);
+    }
+
+    /**
+     * Record something the importer could not represent.
+     * @param code - a stable code
+     * @param message - a plain-ASCII message
+     * @param column - the affected column, or null
+     * @param count - the affected count, or null
+     * @returns the recorded note
+     */
+    loss(code: string, message: string, column: string | null = null, count: number | null = null): LossNote {
+        const note: LossNote = Object.freeze({ code, message, column, count });
+        this.lossList.push(note);
+        return note;
+    }
+
+    /**
+     * The per-element catch of design section 8.6: record a thrown GraphFormatError as an error
+     * issue with its code and the category the code implies. Anything else is re-thrown unchanged:
+     * an ImportError (the import already aborted), an abort reason, and any other thrown value (a
+     * TypeError or RangeError is a programming error in the importer or the sink, never a defect of
+     * the input, so it must surface as an exception rather than as an issue blamed on the file).
+     * @param err - the thrown value
+     * @param where - the line and element, when known
+     * @returns the recorded issue
+     */
+    recordError(err: unknown, where?: IssueLocation): ImportIssue {
+        if (err instanceof GraphFormatError && !(err instanceof ImportError)) {
+            const category = CATEGORY_BY_CODE[err.code] ?? "validation-error";
+            return this.error(category, err.code, err.message, where);
+        }
+        throw err;
+    }
+
+    /**
+     * Build the ImportError that aborts the import, carrying the report so far. The caller throws
+     * it; this method only constructs it so it can be used in expression position.
+     * @param message - a plain-ASCII message
+     * @param details - optional machine-readable context
+     * @returns the error to throw
+     */
+    abort(message: string, details?: Readonly<Record<string, unknown>>): ImportError {
+        return new ImportError(message, this.finish(), details);
+    }
+
+    /**
+     * Record a fatal parse error and abort: the issue is recorded (even beyond the error limit)
+     * and an ImportError carrying the report is thrown.
+     * @param code - a stable code such as "E_INVALID_UTF8"
+     * @param message - a plain-ASCII message
+     * @param where - the line and element, when known
+     * @param details - optional machine-readable context for the ImportError
+     */
+    fail(code: string, message: string, where?: IssueLocation, details?: Readonly<Record<string, unknown>>): never {
+        const issue = makeIssue("parse-error", "error", code, message, where);
+        this.issueList.push(issue);
+        this.errors++;
+        if (this.errors > this.errorLimit) {
+            this.truncatedFlag = true;
+        }
+        throw this.abort(message, { code, ...details });
+    }
+
+    /**
+     * The report as it stands: a frozen snapshot with the parse duration so far. Can be called more
+     * than once; each call reflects everything recorded up to that point.
+     * @returns the report
+     */
+    finish(): ImportReport {
+        const { nodes, edges, skippedNodes, skippedEdges, expandedMixed } = this.counts;
+        return Object.freeze({
+            format: this.format,
+            counts: Object.freeze({ nodes, edges, skippedNodes, skippedEdges, expandedMixed }),
+            issues: Object.freeze([...this.issueList]),
+            errorCount: this.errors,
+            warningCount: this.warnings,
+            truncated: this.truncatedFlag,
+            lossy: Object.freeze([...this.lossList]),
+            durationMs: now() - this.startedAt,
+        });
+    }
+}
+
+/**
+ * Build a frozen ImportIssue.
+ * @param category - the category
+ * @param severity - error or warning
+ * @param code - the stable code
+ * @param message - the message
+ * @param where - the location, when known
+ * @returns the issue
+ */
+function makeIssue(
+    category: IssueCategory,
+    severity: "error" | "warning",
+    code: string,
+    message: string,
+    where: IssueLocation | undefined,
+): ImportIssue {
+    return Object.freeze({
+        category,
+        severity,
+        code,
+        message,
+        line: where?.line ?? null,
+        element: where?.element ?? null,
+    });
+}
+
+/**
+ * Whether a thrown value is an abort reason (the DOMException or Error named "AbortError" that
+ * AbortSignal.reason holds), which an importer must let through untouched.
+ * @param err - the thrown value
+ * @returns true for an AbortError
+ */
+export function isAbortError(err: unknown): boolean {
+    return typeof err === "object" && err !== null && (err as { name?: unknown }).name === "AbortError";
+}
+
+/**
+ * The message of a thrown value: an Error's message, a string as is, anything else described by type.
+ * @param err - the thrown value
+ * @returns a plain message
+ */
+export function messageOf(err: unknown): string {
+    if (err instanceof Error) {
+        return err.message;
+    }
+    if (typeof err === "string") {
+        return err;
+    }
+    return `non-error thrown (${typeof err})`;
+}
+
+/**
+ * A monotonic millisecond clock: performance.now() where it exists, Date.now() otherwise.
+ * @returns milliseconds
+ */
+function now(): number {
+    return typeof performance === "object" ? performance.now() : Date.now();
+}

package/src/common/temporal.ts

@@ -0,0 +1,302 @@
+/**
+ * Temporal values (design section 5.1): `date` / `dateTime` attributes, GEXF time bounds and Neo4j
+ * temporal types become f64 epoch milliseconds (or the raw numeric time when the file's timeformat
+ * is integer / double). When a value's canonical re-formatting would differ from the source text (a
+ * UTC offset, fractional seconds beyond milliseconds, a date without a time in a dateTime column)
+ * the importer also keeps the lexical form in a companion `<column>.text` column with role
+ * `timeText`; the exporter emits the text when present and formats the number otherwise.
+ *
+ * Only ISO-8601 forms are parsed (XSD date / dateTime / time and Neo4j's literals), by a fixed
+ * grammar rather than Date.parse, so two hosts agree on every value.
+ */
+
+import { type ColumnDecl, type ColumnRole, GraphFormatError } from "@graphty/graph-format";
+
+/** The temporal kinds a declared type can map to; each fixes the parse grammar and the canonical text. */
+export type TemporalKind = "date" | "dateTime" | "localDateTime" | "time" | "localTime";
+
+/**
+ * The GEXF `timeformat` values (design section 5.9).
+ * Consumed by the per-format importers and exporters under src/formats.
+ * @public
+ */
+export type TimeFormat = "integer" | "double" | "date" | "dateTime";
+
+/** A parsed temporal value: the number stored in the column and the source text when it must be kept. */
+export interface TemporalValue {
+    /** Epoch milliseconds (date, dateTime, localDateTime), milliseconds since midnight (time, localTime), or the raw number. */
+    readonly value: number;
+    /** The source text when formatTemporal(value) would not reproduce it; null otherwise. */
+    readonly text: string | null;
+}
+
+/** The role of a companion text column. */
+export const TIME_TEXT_ROLE: ColumnRole = "timeText";
+
+/** The suffix of a companion text column's name. */
+export const TIME_TEXT_SUFFIX = ".text";
+
+const DATE_TIME =
+    /^(-?[0-9]{4,})-([0-9]{2})-([0-9]{2})(?:[T ]([0-9]{2}):([0-9]{2})(?::([0-9]{2})(?:\.([0-9]{1,9}))?)?)?(Z|z|[+-][0-9]{2}(?::?[0-9]{2})?)?$/;
+const TIME = /^([0-9]{2}):([0-9]{2})(?::([0-9]{2})(?:\.([0-9]{1,9}))?)?(Z|z|[+-][0-9]{2}(?::?[0-9]{2})?)?$/;
+const NUMERIC = /^[+-]?([0-9]+(\.[0-9]*)?|\.[0-9]+)([eE][+-]?[0-9]+)?$/;
+
+const MS_PER_MINUTE = 60_000;
+const MS_PER_DAY = 86_400_000;
+
+/**
+ * Parse an ISO-8601 temporal text of one kind.
+ * @param text - the source text (already trimmed)
+ * @param kind - the temporal kind
+ * @returns the value and, when the canonical form differs, the source text; E_COLUMN_TYPE when the text is not of the kind
+ */
+export function parseTemporal(text: string, kind: TemporalKind): TemporalValue {
+    let value: number;
+    switch (kind) {
+        case "date":
+        case "dateTime":
+        case "localDateTime":
+            value = parseDateTime(text, kind);
+            break;
+        case "time":
+        case "localTime":
+            value = parseTime(text, kind);
+            break;
+        default: {
+            const name: string = kind;
+            throw new GraphFormatError("E_COLUMN_TYPE", `unknown temporal kind ${name}`, { kind: name });
+        }
+    }
+    const canonical = formatTemporal(value, kind);
+    return { value, text: canonical === text ? null : text };
+}
+
+/**
+ * Parse a GEXF time bound (`start`, `end`, `timestamp`, a spell or an attvalue time) under the
+ * graph's timeformat: integer / double values are numbers as written; date / dateTime values are
+ * ISO text; when the format is unknown (absent header) numeric text is a number and anything else
+ * is tried as dateTime.
+ * @param text - the source text
+ * @param timeFormat - the graph's timeformat, or null when the file declares none
+ * @returns the value and the source text when it must be kept
+ */
+export function parseTimeText(text: string, timeFormat: TimeFormat | null): TemporalValue {
+    const trimmed = text.trim();
+    switch (timeFormat) {
+        case "integer":
+        case "double":
+            return parseNumericTime(trimmed);
+        case "date":
+            return parseTemporal(trimmed, "date");
+        case "dateTime":
+            return parseTemporal(trimmed, "dateTime");
+        case null:
+            return NUMERIC.test(trimmed) ? parseNumericTime(trimmed) : parseTemporal(trimmed, "dateTime");
+        default: {
+            const name: string = timeFormat;
+            throw new GraphFormatError("E_COLUMN_TYPE", `unknown timeformat ${name}`, { timeFormat: name });
+        }
+    }
+}
+
+/**
+ * Format a temporal value in its canonical ISO-8601 form.
+ * @param value - the number as stored
+ * @param kind - the temporal kind
+ * @returns the canonical text: `YYYY-MM-DD`, `YYYY-MM-DDTHH:MM:SS[.mmm]Z`, `YYYY-MM-DDTHH:MM:SS[.mmm]`,
+ * `HH:MM:SS[.mmm]Z` or `HH:MM:SS[.mmm]`
+ */
+export function formatTemporal(value: number, kind: TemporalKind): string {
+    switch (kind) {
+        case "date": {
+            const d = new Date(value);
+            return `${year(d)}-${pad2(d.getUTCMonth() + 1)}-${pad2(d.getUTCDate())}`;
+        }
+        case "dateTime":
+        case "localDateTime": {
+            const d = new Date(value);
+            const date = `${year(d)}-${pad2(d.getUTCMonth() + 1)}-${pad2(d.getUTCDate())}`;
+            const time = clock(d.getUTCHours(), d.getUTCMinutes(), d.getUTCSeconds(), d.getUTCMilliseconds());
+            return kind === "dateTime" ? `${date}T${time}Z` : `${date}T${time}`;
+        }
+        case "time":
+        case "localTime": {
+            const ms = ((value % MS_PER_DAY) + MS_PER_DAY) % MS_PER_DAY;
+            const h = Math.floor(ms / 3_600_000);
+            const m = Math.floor((ms % 3_600_000) / MS_PER_MINUTE);
+            const s = Math.floor((ms % MS_PER_MINUTE) / 1000);
+            const text = clock(h, m, s, ms % 1000);
+            return kind === "time" ? `${text}Z` : text;
+        }
+        default: {
+            const name: string = kind;
+            throw new GraphFormatError("E_COLUMN_TYPE", `unknown temporal kind ${name}`, { kind: name });
+        }
+    }
+}
+
+/**
+ * Format a GEXF time bound under the graph's timeformat: the number's shortest text for integer /
+ * double, the canonical ISO form otherwise.
+ * @param value - the value as stored
+ * @param timeFormat - the graph's timeformat, or null for a file that declares none (double)
+ * @returns the text
+ */
+export function formatTimeValue(value: number, timeFormat: TimeFormat | null): string {
+    switch (timeFormat) {
+        case "date":
+            return formatTemporal(value, "date");
+        case "dateTime":
+            return formatTemporal(value, "dateTime");
+        case "integer":
+        case "double":
+        case null:
+            return String(value);
+        default: {
+            const name: string = timeFormat;
+            throw new GraphFormatError("E_COLUMN_TYPE", `unknown timeformat ${name}`, { timeFormat: name });
+        }
+    }
+}
+
+/**
+ * The declaration of the companion text column of a temporal column (design section 5.1).
+ * @param column - the temporal column's name
+ * @returns a string column named `<column>.text` with role timeText and `extra.for` naming the column
+ */
+export function timeTextCompanion(column: string): ColumnDecl {
+    return {
+        name: column + TIME_TEXT_SUFFIX,
+        dtype: "string",
+        role: TIME_TEXT_ROLE,
+        nullable: true,
+        extra: { for: column },
+    };
+}
+
+/**
+ * Parse a numeric time bound.
+ * @param text - the trimmed source text
+ * @returns the number; the text is kept when String(value) differs from it
+ */
+function parseNumericTime(text: string): TemporalValue {
+    if (!NUMERIC.test(text)) {
+        throw new GraphFormatError("E_COLUMN_TYPE", `"${text}" is not a numeric time`, { value: text });
+    }
+    const value = Number(text);
+    return { value, text: String(value) === text ? null : text };
+}
+
+/**
+ * Parse a date or date-time text into epoch milliseconds.
+ * @param text - the source text
+ * @param kind - date (a time part is accepted and kept in the companion), dateTime or localDateTime
+ * @returns epoch milliseconds
+ */
+function parseDateTime(text: string, kind: "date" | "dateTime" | "localDateTime"): number {
+    const m = DATE_TIME.exec(text);
+    if (m === null) {
+        throw new GraphFormatError("E_COLUMN_TYPE", `"${text}" is not an ISO-8601 ${kind}`, { value: text, kind });
+    }
+    const y = Number(m[1]);
+    const month = Number(m[2]);
+    const day = Number(m[3]);
+    const hour = m[4] === undefined ? 0 : Number(m[4]);
+    const minute = m[5] === undefined ? 0 : Number(m[5]);
+    const second = m[6] === undefined ? 0 : Number(m[6]);
+    const ms = m[7] === undefined ? 0 : fractionMs(m[7]);
+    if (month < 1 || month > 12 || day < 1 || day > 31 || hour > 24 || minute > 59 || second > 60) {
+        throw new GraphFormatError("E_COLUMN_TYPE", `"${text}" is out of range for a ${kind}`, { value: text, kind });
+    }
+    // Date.UTC maps years 0..99 to 1900..1999; the setters do not
+    const d = new Date(0);
+    d.setUTCFullYear(y, month - 1, day);
+    d.setUTCHours(hour, minute, second, ms);
+    if (d.getUTCDate() !== day && hour !== 24) {
+        throw new GraphFormatError("E_COLUMN_TYPE", `"${text}" is not a calendar date`, { value: text, kind });
+    }
+    const offset = m[8] === undefined ? 0 : offsetMinutes(m[8]);
+    return d.getTime() - offset * MS_PER_MINUTE;
+}
+
+/**
+ * Parse a time-of-day text into milliseconds since midnight (UTC for `time` with a zone).
+ * @param text - the source text
+ * @param kind - time or localTime
+ * @returns milliseconds since midnight in 0..86400000
+ */
+function parseTime(text: string, kind: "time" | "localTime"): number {
+    const m = TIME.exec(text);
+    if (m === null) {
+        throw new GraphFormatError("E_COLUMN_TYPE", `"${text}" is not an ISO-8601 ${kind}`, { value: text, kind });
+    }
+    const hour = Number(m[1]);
+    const minute = Number(m[2]);
+    const second = m[3] === undefined ? 0 : Number(m[3]);
+    const ms = m[4] === undefined ? 0 : fractionMs(m[4]);
+    if (hour > 24 || minute > 59 || second > 60) {
+        throw new GraphFormatError("E_COLUMN_TYPE", `"${text}" is out of range for a ${kind}`, { value: text, kind });
+    }
+    const local = ((hour * 60 + minute) * 60 + second) * 1000 + ms;
+    const offset = m[5] === undefined ? 0 : offsetMinutes(m[5]);
+    const utc = local - offset * MS_PER_MINUTE;
+    return ((utc % MS_PER_DAY) + MS_PER_DAY) % MS_PER_DAY;
+}
+
+/**
+ * Milliseconds of a fractional-second text (1 to 9 digits), truncated to whole milliseconds.
+ * @param digits - the digits after the decimal point
+ * @returns 0..999
+ */
+function fractionMs(digits: string): number {
+    return Math.floor(Number(`0.${digits}`) * 1000);
+}
+
+/**
+ * The minutes of a zone designator.
+ * @param zone - "Z", "+HH:MM", "+HHMM" or "+HH"
+ * @returns signed minutes east of UTC
+ */
+function offsetMinutes(zone: string): number {
+    if (zone === "Z" || zone === "z") {
+        return 0;
+    }
+    const sign = zone.startsWith("-") ? -1 : 1;
+    const digits = zone.slice(1).replace(":", "");
+    const hours = Number(digits.slice(0, 2));
+    const minutes = digits.length > 2 ? Number(digits.slice(2, 4)) : 0;
+    return sign * (hours * 60 + minutes);
+}
+
+/**
+ * Two-digit zero-padded text.
+ * @param n - 0..99
+ * @returns the text
+ */
+function pad2(n: number): string {
+    return n < 10 ? `0${n}` : String(n);
+}
+
+/**
+ * The year of a UTC date as at least four digits (negative years keep their sign).
+ * @param d - the date
+ * @returns the text
+ */
+function year(d: Date): string {
+    const y = d.getUTCFullYear();
+    const abs = String(Math.abs(y)).padStart(4, "0");
+    return y < 0 ? `-${abs}` : abs;
+}
+
+/**
+ * `HH:MM:SS` with `.mmm` appended when the milliseconds are not zero.
+ * @param h - hours
+ * @param m - minutes
+ * @param s - seconds
+ * @param ms - milliseconds
+ * @returns the text
+ */
+function clock(h: number, m: number, s: number, ms: number): string {
+    const base = `${pad2(h)}:${pad2(m)}:${pad2(s)}`;
+    return ms === 0 ? base : `${base}.${String(ms).padStart(3, "0")}`;
+}