@graphty/graph-io 0.3.24 → 0.3.26

package/src/common/options.ts

@@ -1,5 +1,5 @@
 /**
- * Option normalisation for importers and exporters (design sections 8.4 and 8.5): every common
+ * Option normalization for importers and exporters (design sections 8.4 and 8.5): every common
  * option resolved to its documented default, enum values checked (E_UNSUPPORTED, the core's
  * convention for an option outside its set), and the per-format defaults (`ids`, `defaultDirected`,
  * `weightFrom`, `addMissingNodes`) supplied by the importer that calls resolveImportOptions().
@@ -16,9 +16,13 @@ import {
     SINK_OPTION_CODE,
 } from "./codes.js";
 import { canonicalEncoding } from "./input.js";
+import { plural } from "./plural.js";
 import { type ImportReportBuilder } from "./report.js";
 
-/** The defaults an importer supplies for the options whose default is per format (design section 8.4). */
+/**
+ * The defaults an importer supplies for the options whose default is per format.
+ * @category Plugin helpers
+ */
 export interface ImportFormatDefaults {
     /** "canonical" for text-cell formats, "keep" for JSON. */
     readonly ids: IdCoercion;
@@ -31,9 +35,9 @@ export interface ImportFormatDefaults {
 }
 
 /**
- * CommonImportOptions with every field present (design section 8.4 defaults applied).
- * Consumed by the per-format importers and exporters under src/formats.
+ * CommonImportOptions with every field present.
  * @public
+ * @category Plugin helpers
  */
 export interface ResolvedImportOptions {
     /** The id coercion rule. */
@@ -70,7 +74,10 @@ export interface ResolvedImportOptions {
     readonly encoding: string | null;
 }
 
-/** CommonExportOptions with every field present (design section 8.5 defaults applied). */
+/**
+ * CommonExportOptions with every field present.
+ * @category Plugin helpers
+ */
 export interface ResolvedExportOptions {
     /** "error" never renames a node; "mangle" rewrites and keeps the original. */
     readonly sanitizeIds: "error" | "mangle";
@@ -89,7 +96,10 @@ const LONG_MODES: ReadonlySet<string> = new Set(["f64", "string"]);
 const HYPEREDGE_POLICIES: ReadonlySet<string> = new Set(["error", "skip", "star", "clique"]);
 const SANITIZE_MODES: ReadonlySet<string> = new Set(["error", "mangle"]);
 
-/** The default error limit of design section 8.4. */
+/**
+ * The default error limit: errors tolerated before an import aborts.
+ * @category Reports and errors
+ */
 export const DEFAULT_ERROR_LIMIT = 100;
 
 export { SINK_OPTION_CODE };
@@ -98,17 +108,18 @@ export { SINK_OPTION_CODE };
 const SINK_OPTION_NAMES = ["addMissingNodes", "duplicateEdges", "selfLoops", "weightDtype"] as const;
 
 /**
- * Report every builder-policy option the caller explicitly requested that the sink does not use
- * (design section 8.4 precedence), one `W_SINK_OPTION` warning per option with the option name as
+ * Report every builder-policy option the caller explicitly requested that the sink does not use,
+ * one `W_SINK_OPTION` warning per option with the option name as
  * the element. Options left undefined are never reported: they are defaults, not requests. On the
  * registry's builder, which is seeded from the same options, nothing is ever reported.
  * @param sink - the sink the importer pushes into
  * @param options - the caller's raw options, possibly undefined
  * @param report - the report to record into
  * @param enforcesMissingNodes - true when the importer applies `addMissingNodes: false` itself (it
- * refuses unknown endpoints before the sink sees them), so that request is honoured on any sink and
+ * refuses unknown endpoints before the sink sees them), so that request is honored on any sink and
  * only `addMissingNodes: true` against a refusing sink is reported
  * @returns the number of warnings recorded
+ * @category Writing a format
  */
 export function reportSinkOptions(
     sink: GraphSink,
@@ -156,15 +167,28 @@ const IGNORABLE_OPTION_NAMES = [
     "hyperedges",
 ] as const;
 
+/** The defaults that are the same in every format (the others, such as `defaultDirected`, differ by format). */
+const FIXED_DEFAULTS: Readonly<Partial<Record<(typeof IGNORABLE_OPTION_NAMES)[number], unknown>>> = {
+    nodeIdFrom: "id",
+    duplicateEdges: "keep",
+    selfLoops: "keep",
+    onMixedDirection: "expand",
+    weightDtype: "f64",
+    long: "f64",
+    restoreMangledIds: true,
+    hyperedges: "skip",
+};
+
 /**
  * Report every common option the caller set to a non-default value that the format has no use
- * for (design section 8.4: "the importer reports every option it could not honour"): one
+ * for: one
  * `W_OPTION_IGNORED` warning (category `unsupported`) per option, the option name as the element.
  * The builder-policy options are reportSinkOptions()'s and are skipped here.
  * @param options - the caller's raw options, possibly undefined
  * @param report - the report to record into
  * @param used - the common option names the importer reads
  * @returns the number of warnings recorded
+ * @category Writing a format
  */
 export function reportUnusedOptions(
     options: CommonImportOptions | undefined,
@@ -180,7 +204,8 @@ export function reportUnusedOptions(
             continue;
         }
         const value: unknown = options[name];
-        if (value === undefined) {
+        if (value === undefined || value === FIXED_DEFAULTS[name]) {
+            // an option spelled out at its default changes nothing, whether or not the format reads it
             continue;
         }
         report.warning(
@@ -194,6 +219,29 @@ export function reportUnusedOptions(
     return recorded;
 }
 
+/**
+ * Whether the caller chose a graph with `graphIndex` or `graphName`. An importer warns
+ * W_MULTIPLE_GRAPHS about the graphs it skipped only when it read the first by default.
+ * @param options - the caller's graphIndex / graphName
+ * @returns true when either option is set
+ * @category Writing a format
+ */
+export function graphChosen(options: GraphChoiceOptions | undefined): boolean {
+    return options?.graphIndex !== undefined || options?.graphName !== undefined;
+}
+
+/**
+ * The graphs of an input as an E_GRAPH_NOT_FOUND message lists them: their indexes and names, so the
+ * caller can choose without a second call.
+ * @param names - each graph's name, null for an unnamed graph
+ * @returns the text to append, starting with "; "
+ */
+function graphNamesText(names: readonly (string | null)[]): string {
+    const shown = names.slice(0, 10).map((n, i) => `${i} ${n === null ? "(unnamed)" : JSON.stringify(n)}`);
+    const more = names.length > shown.length ? `, and ${names.length - shown.length} more` : "";
+    return `; the file holds ${shown.join(", ")}${more}`;
+}
+
 /**
  * The graph an importer reads from an input that holds several: the one `graphIndex` or
  * `graphName` names, else the first. A choice that names no graph is E_GRAPH_NOT_FOUND, a name two
@@ -203,6 +251,7 @@ export function reportUnusedOptions(
  * @param options - the caller's graphIndex / graphName
  * @param report - the report a failure is recorded in
  * @returns the index of the graph to read; E_UNSUPPORTED for an option of the wrong type, or both
+ * @category Writing a format
  */
 export function chooseGraph(
     names: readonly (string | null)[],
@@ -250,7 +299,7 @@ export function chooseGraph(
         if (matches.length === 0) {
             return report.fail(
                 GRAPH_NOT_FOUND_CODE,
-                `graphName ${JSON.stringify(graphName)} names none of the ${names.length} graph(s)`,
+                `graphName ${JSON.stringify(graphName)} names none of the ${names.length} graph${plural(names.length)}${graphNamesText(names)}`,
                 { element: graphName },
                 { names: [...names] },
             );
@@ -259,17 +308,21 @@ export function chooseGraph(
     }
     const index = graphIndex ?? 0;
     if (index >= names.length) {
-        return report.fail(GRAPH_NOT_FOUND_CODE, `graphIndex ${index} is beyond the ${names.length} graph(s)`);
+        return report.fail(
+            GRAPH_NOT_FOUND_CODE,
+            `graphIndex ${index} is beyond the ${names.length} graph${plural(names.length)}${graphNamesText(names)}`,
+        );
     }
     return index;
 }
 
 /**
- * Apply the design section 8.4 defaults to an importer's common options and check every enum
+ * Apply the documented defaults to an importer's common options and check every enum
  * value. Format-specific options in the same object are ignored here.
  * @param options - the caller's options, possibly undefined
  * @param defaults - the importer's per-format defaults
  * @returns the resolved options; E_UNSUPPORTED for a value outside its set
+ * @category Writing a format
  */
 export function resolveImportOptions(
     options: CommonImportOptions | undefined,
@@ -297,9 +350,10 @@ export function resolveImportOptions(
 }
 
 /**
- * Apply the design section 8.5 defaults to an exporter's common options and check the enum values.
+ * Apply the documented defaults to an exporter's common options and check the enum values.
  * @param options - the caller's options, possibly undefined
  * @returns the resolved options; E_UNSUPPORTED for a value outside its set
+ * @category Writing a format
  */
 export function resolveExportOptions(options: CommonExportOptions | undefined): ResolvedExportOptions {
     const o: CommonExportOptions = options ?? {};
@@ -450,10 +504,51 @@ function encodingOption(value: unknown): string | null {
     return canonical;
 }
 
+/**
+ * The options to pass to another importer that you hand text you already decoded with readText():
+ * the caller's options without `encoding` and `onProgress`, which that text no longer needs. Without
+ * this, the other importer would warn that `encoding` has no effect on text, and report progress a
+ * second time.
+ * @example
+ * ```ts
+ * const text = await readText(input, report, opts);
+ * report.include(await csvImporter.import(text, sink, forDecodedText(options)));
+ * ```
+ * @param options - the caller's import options
+ * @returns a copy without `encoding` and `onProgress`
+ * @category Writing a format
+ */
+export function forDecodedText<O extends CommonImportOptions>(options: O | undefined): O {
+    return { ...options, encoding: undefined, onProgress: undefined } as O;
+}
+
+/**
+ * The dialect names of the built-in formats with a `dialect` save option. One options object shared between formats
+ * can hold one format's dialect, and the other formats ignore it, as they ignore any option they do not have.
+ */
+export const FORMAT_DIALECTS: Readonly<Record<string, readonly string[]>> = Object.freeze({
+    csv: Object.freeze(["gephi", "generic"]),
+    json: Object.freeze(["node-link", "d3", "jgf", "cytoscape", "graphology", "vis", "obographs"]),
+});
+
+/**
+ * Whether a `dialect` value names another format's dialect, which this format ignores rather than refuses.
+ * @param format - this format
+ * @param value - the caller's `dialect` option
+ * @returns true for another built-in format's dialect name
+ */
+export function otherFormatDialect(format: string, value: unknown): boolean {
+    return (
+        typeof value === "string" &&
+        Object.entries(FORMAT_DIALECTS).some(([f, names]) => f !== format && names.includes(value))
+    );
+}
+
 /**
  * A short description of an option value for an error message.
  * @param value - the value
  * @returns the JSON text of a primitive, or the type name otherwise
+ * @category Plugin helpers
  */
 export function describe(value: unknown): string {
     switch (typeof value) {

package/src/common/plural.ts

@@ -0,0 +1,49 @@
+/**
+ * Count agreement for messages, so a report says "1 node is" and "3 nodes are", never "1 node(s) are".
+ */
+
+/**
+ * The plural ending of a regular noun after a count.
+ * @param n - the count
+ * @returns "" for 1, "s" otherwise
+ */
+export function plural(n: number): string {
+    return n === 1 ? "" : "s";
+}
+
+/**
+ * The form of a verb that agrees with a count.
+ * @param n - the count
+ * @param one - the form for 1 ("is", "was", "holds")
+ * @param many - the form for any other count ("are", "were", "hold")
+ * @returns `one` or `many`
+ */
+export function agree(n: number, one: string, many: string): string {
+    return n === 1 ? one : many;
+}
+
+/**
+ * A count of nodes and edges, leaving out a zero: "2 nodes and 1 edge", "1 edge".
+ * @param nodes - the node count
+ * @param edges - the edge count
+ * @returns the text
+ */
+export function elementCount(nodes: number, edges: number): string {
+    const parts = [];
+    if (nodes > 0 || edges === 0) {
+        parts.push(`${nodes} node${plural(nodes)}`);
+    }
+    if (edges > 0) {
+        parts.push(`${edges} edge${plural(edges)}`);
+    }
+    return parts.join(" and ");
+}
+
+/**
+ * A word with its indefinite article, chosen by its first letter: "an integer", "a double".
+ * @param word - the word
+ * @returns "a word" or "an word"
+ */
+export function withArticle(word: string): string {
+    return `${/^[aeiou]/i.test(word) ? "an" : "a"} ${word}`;
+}

package/src/common/report.ts

@@ -13,11 +13,20 @@
 import { GraphFormatError, type GraphFormatErrorCode } from "@graphty/graph-format";
 
 import { ImportError, type ImportIssue, type ImportReport, type IssueCategory, type LossNote } from "../types.js";
+import { ISSUES_SUPPRESSED_CODE } from "./codes.js";
+import { agree, plural } from "./plural.js";
+
+/**
+ * The most warnings of one code a report keeps; later ones are counted in one W_ISSUES_SUPPRESSED
+ * warning, so a per-row warning on a large file cannot grow the report without bound.
+ * @category Issue and loss codes
+ */
+export const MAX_WARNINGS_PER_CODE = 1000;
 
 /**
  * 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
+ * @category Writing a format
  */
 export interface IssueLocation {
     /** The 1-based source line, when known. */
@@ -28,8 +37,8 @@ export interface IssueLocation {
 
 /**
  * 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
+ * @category Plugin helpers
  */
 export interface MutableCounts {
     /** Nodes pushed. */
@@ -40,7 +49,7 @@ export interface MutableCounts {
     skippedNodes: number;
     /** Edges skipped after an error. */
     skippedEdges: number;
-    /** Source edges expanded into two logical edges (design section 3.6). */
+    /** Source edges expanded into two logical edges. */
     expandedMixed: number;
 }
 
@@ -60,18 +69,30 @@ const CATEGORY_BY_CODE: Readonly<Partial<Record<GraphFormatErrorCode, IssueCateg
 };
 
 /**
- * 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.
+ * No longer recorded; kept so code that switches on older reports still compiles.
+ * @category Issue and loss codes
  */
 export const PARSE_ERROR_CODE = "E_PARSE";
 
+/**
+ * An issue message as the ImportError shows it: prefixed with its line when the issue has one and the
+ * message does not already name it.
+ * @param message - the issue message
+ * @param where - the issue location
+ * @returns the message for the error
+ */
+function withLine(message: string, where: IssueLocation | undefined): string {
+    const line = where?.line;
+    return line === undefined || line === null || message.includes(`line ${line}`)
+        ? message
+        : `line ${line}: ${message}`;
+}
+
 /**
  * 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.
+ * ImportError carrying the report so far is thrown. Warnings never abort.
+ * @category Writing a format
  */
 export class ImportReportBuilder {
     /** The importer's format name. */
@@ -89,6 +110,9 @@ export class ImportReportBuilder {
 
     private readonly onceCodes = new Set<string>();
 
+    /** Warnings recorded per code, kept or not. */
+    private readonly warningsByCode = new Map<string, number>();
+
     private errors = 0;
 
     private warnings = 0;
@@ -163,7 +187,7 @@ export class ImportReportBuilder {
         this.errors++;
         if (this.errors > this.errorLimit) {
             this.truncatedFlag = true;
-            throw this.abort(`error limit of ${this.errorLimit} exceeded: ${message}`, {
+            throw this.abort(`error limit of ${this.errorLimit} exceeded: ${withLine(message, where)}`, {
                 code,
                 limit: this.errorLimit,
             });
@@ -172,7 +196,9 @@ export class ImportReportBuilder {
     }
 
     /**
-     * Record a warning; warnings never count toward the limit.
+     * Record a warning; warnings never count toward the limit. Beyond MAX_WARNINGS_PER_CODE
+     * warnings of one code the warning is counted, not kept: finish() adds one W_ISSUES_SUPPRESSED
+     * warning per such code with the number dropped.
      * @param category - the issue category
      * @param code - a stable code such as "W_WIDENED"
      * @param message - a plain-ASCII message
@@ -181,8 +207,12 @@ export class ImportReportBuilder {
      */
     warning(category: IssueCategory, code: string, message: string, where?: IssueLocation): ImportIssue {
         const issue = makeIssue(category, "warning", code, message, where);
-        this.issueList.push(issue);
-        this.warnings++;
+        const seen = (this.warningsByCode.get(code) ?? 0) + 1;
+        this.warningsByCode.set(code, seen);
+        if (seen <= MAX_WARNINGS_PER_CODE) {
+            this.issueList.push(issue);
+            this.warnings++;
+        }
         return issue;
     }
 
@@ -226,7 +256,7 @@ export class ImportReportBuilder {
     }
 
     /**
-     * The per-element catch of design section 8.6: record a thrown GraphFormatError as an error
+     * The per-element catch: 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
@@ -238,11 +268,38 @@ export class ImportReportBuilder {
     recordError(err: unknown, where?: IssueLocation): ImportIssue {
         if (err instanceof GraphFormatError && !(err instanceof ImportError)) {
             const category = CATEGORY_BY_CODE[err.code] ?? "validation-error";
+            if (err.code === "E_TOO_LARGE") {
+                // the sink is full: every later element would fail the same way, so the import stops
+                return this.failWith(category, err.code, err.message, where);
+            }
             return this.error(category, err.code, err.message, where);
         }
         throw err;
     }
 
+    /**
+     * A builder that starts from everything this one recorded so far: issues, counts, loss notes,
+     * the warnOnce keys, the error and warning counts and the truncation flag. For an importer that
+     * reads its input once and emits several graphs, each with its own report.
+     * @returns the copy; later records to either builder do not reach the other
+     */
+    fork(): ImportReportBuilder {
+        const copy = new ImportReportBuilder(this.format, this.errorLimit);
+        Object.assign(copy.counts, this.counts);
+        copy.issueList.push(...this.issueList);
+        copy.lossList.push(...this.lossList);
+        for (const key of this.onceCodes) {
+            copy.onceCodes.add(key);
+        }
+        for (const [code, count] of this.warningsByCode) {
+            copy.warningsByCode.set(code, count);
+        }
+        copy.errors = this.errors;
+        copy.warnings = this.warnings;
+        copy.truncatedFlag = this.truncatedFlag;
+        return copy;
+    }
+
     /**
      * 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.
@@ -263,13 +320,65 @@ export class ImportReportBuilder {
      * @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.failWith("parse-error", code, message, where, details);
+    }
+
+    /**
+     * Record a fatal error of any category and abort, as fail() does for a parse error: a size
+     * limit (E_TOO_LARGE, category "unsupported") stops an import without being a defect of the
+     * syntax. A fatal error is not the error limit: `truncated` stays as it was.
+     * @param category - the issue category
+     * @param code - a stable code
+     * @param message - a plain-ASCII message
+     * @param where - the line and element, when known
+     * @param details - optional machine-readable context for the ImportError
+     */
+    failWith(
+        category: IssueCategory,
+        code: string,
+        message: string,
+        where?: IssueLocation,
+        details?: Readonly<Record<string, unknown>>,
+    ): never {
+        this.issueList.push(makeIssue(category, "error", code, message, where));
         this.errors++;
-        if (this.errors > this.errorLimit) {
-            this.truncatedFlag = true;
+        throw this.abort(withLine(message, where), { code, ...details });
+    }
+
+    /**
+     * Add a finished report to this one: its issues after the ones recorded so far, its counts, its
+     * loss notes and its truncated flag. Use it when an importer hands part of the work to another
+     * importer (for example, a wrapper around the CSV importer) and returns one report for both. The issues
+     * keep their codes; errors added this way do not count toward this report's error limit, since
+     * the other importer applied its own.
+     * @param report - the report the other importer returned
+     * @returns this builder
+     * @example
+     * ```ts
+     * const report = new ImportReportBuilder("netscope", opts.errorLimit);
+     * const text = await readText(input, report, opts);
+     * report.include(await csvImporter.import(text, sink, options));
+     * return report.finish();
+     * ```
+     */
+    include(report: ImportReport): this {
+        for (const issue of report.issues) {
+            this.issueList.push(issue);
+            if (issue.severity === "error") {
+                this.errors++;
+            } else {
+                this.warnings++;
+            }
         }
-        throw this.abort(message, { code, ...details });
+        const { counts } = report;
+        this.counts.nodes += counts.nodes;
+        this.counts.edges += counts.edges;
+        this.counts.skippedNodes += counts.skippedNodes;
+        this.counts.skippedEdges += counts.skippedEdges;
+        this.counts.expandedMixed += counts.expandedMixed;
+        this.lossList.push(...report.lossy);
+        this.truncatedFlag ||= report.truncated;
+        return this;
     }
 
     /**
@@ -279,12 +388,27 @@ export class ImportReportBuilder {
      */
     finish(): ImportReport {
         const { nodes, edges, skippedNodes, skippedEdges, expandedMixed } = this.counts;
+        const suppressed: ImportIssue[] = [];
+        for (const [code, seen] of this.warningsByCode) {
+            if (seen > MAX_WARNINGS_PER_CODE) {
+                const more = seen - MAX_WARNINGS_PER_CODE;
+                suppressed.push(
+                    makeIssue(
+                        "unsupported",
+                        "warning",
+                        ISSUES_SUPPRESSED_CODE,
+                        `${more} more ${code} warning${plural(more)} ${agree(more, "was", "were")} not kept (the report keeps the first ${MAX_WARNINGS_PER_CODE})`,
+                        { element: code },
+                    ),
+                );
+            }
+        }
         return Object.freeze({
             format: this.format,
             counts: Object.freeze({ nodes, edges, skippedNodes, skippedEdges, expandedMixed }),
-            issues: Object.freeze([...this.issueList]),
+            issues: Object.freeze([...this.issueList, ...suppressed]),
             errorCount: this.errors,
-            warningCount: this.warnings,
+            warningCount: this.warnings + suppressed.length,
             truncated: this.truncatedFlag,
             lossy: Object.freeze([...this.lossList]),
             durationMs: now() - this.startedAt,
@@ -319,19 +443,38 @@ function makeIssue(
 }
 
 /**
- * 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.
+ * Whether a thrown value means the load was cancelled rather than failed: the DOMException or Error
+ * named "AbortError" that an aborted signal throws, or the "TimeoutError" of AbortSignal.timeout().
+ * Use it in a `catch` block to say nothing to the user when they cancelled. A custom reason passed
+ * to `abort(reason)` is not recognized: compare it with `signal.reason`. A format plugin uses it to
+ * let a cancellation through untouched.
  * @param err - the thrown value
- * @returns true for an AbortError
+ * @returns true for an AbortError or a TimeoutError
+ * @example
+ * ```ts
+ * try {
+ *     await loadFromUrl(url, { signal });
+ * } catch (err) {
+ *     if (!isAbortError(err)) {
+ *         showError(err);
+ *     }
+ * }
+ * ```
+ * @category Reports and errors
  */
 export function isAbortError(err: unknown): boolean {
-    return typeof err === "object" && err !== null && (err as { name?: unknown }).name === "AbortError";
+    if (typeof err !== "object" || err === null) {
+        return false;
+    }
+    const { name } = err as { name?: unknown };
+    return name === "AbortError" || name === "TimeoutError";
 }
 
 /**
  * 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
+ * @category Plugin helpers
  */
 export function messageOf(err: unknown): string {
     if (err instanceof Error) {