@graphty/graph-io 0.3.25 → 0.3.26

package/src/types.ts

@@ -1,10 +1,10 @@
 /**
- * The io contract types of @graphty/graph-io (design section 12.4, normative): what every importer
+ * The io contract types of @graphty/graph-io: what every importer
  * and exporter implements and what every caller of one programs against. They are declared here
  * rather than in the core because ImportInput and CommonImportOptions reference ReadableStream and
  * AbortSignal, which need the DOM lib (or @types/node >= 18); the core's public types reference only
  * ES2020 globals (decision D-IO-TYPES). Every declaration is transcribed verbatim from the design;
- * the behaviour behind each option is specified in sections 8.4 (import), 8.5 (export) and 8.6
+ * the behavior behind each option is specified in sections 8.4 (import), 8.5 (export) and 8.6
  * (report and error aggregation).
  */
 
@@ -18,76 +18,188 @@ import {
 } from "@graphty/graph-format";
 
 /**
- * What an importer reads (design section 8.4): whole text, whole bytes, a byte stream (a browser
+ * What an importer reads: whole text, whole bytes, a byte stream (a browser
  * `File.stream()`, a fetch body) or an async iterable of text or byte chunks. Bytes are decoded
  * strictly in the encoding the `encoding` option, a byte order mark or the file's own declaration
  * names, else as UTF-8 (undeclared bytes that are not UTF-8 are read as windows-1252 with a
  * warning), so an invalid sequence is a parse-error and never a silent U+FFFD that could alias two ids.
+ * @category Loading
  */
 export type ImportInput = string | Uint8Array | ReadableStream<Uint8Array> | AsyncIterable<string | Uint8Array>;
 
 /**
- * The options every importer accepts next to its format-specific ones (design section 8.4). The
+ * The options every importer accepts next to its format-specific ones. The
  * builder-policy fields (`addMissingNodes`, `duplicateEdges`, `selfLoops`, `weightDtype`) seed the
  * registry's builder; on a caller's sink they are read back from `sink.options` and every option the
- * sink cannot honour is reported.
+ * sink cannot honor is reported.
+ * @category Loading
  */
 export interface CommonImportOptions {
     /**
-     * Id coercion rule applied before an id reaches the sink (design section 4.1): "canonical" by default for
-     * text-cell formats, "keep" for JSON.
+     * How id text becomes a node id. "canonical": integer text such as "42" becomes the number 42
+     * and everything else ("042", "4.2", "a") stays text. "string": every id stays text. "number":
+     * every id is read as a number, so "042" and "42" become one node (with a warning) and text that
+     * is not a number is an error. "keep": ids keep the type the file gives them. The default is
+     * "keep" for JSON, OBO, XGMML, CX, CX2 and Cytoscape sessions, and "canonical" for the other
+     * formats.
+     * @defaultValue per format
      */
     ids?: IdCoercion | undefined;
-    /** Which field becomes the node id; "id" by default; "label" / "index" resolve the GML / Pajek / d3 ambiguity. */
+    /**
+     * Which value becomes the node id: the file's own id ("id"), the node's label ("label"), or its
+     * position among the nodes, counting from 0 ("index"). Use it when a file's ids are meaningless
+     * numbers and the labels are the real names. In d3 JSON, "index" also reads edges whose ends are
+     * node positions. In GML and Pajek it only renames: every node still needs its id key or vertex
+     * number, because edges refer to nodes by it, and a GML node without an `id` key is skipped
+     * with E_MISSING_ID. CSV reads this option only when there is a node table, and it does not
+     * just rename: with "label" the node table's label column (`label`, or the `labelColumn`
+     * option) gives the ids, so the edge table must name its nodes by those labels.
+     * @defaultValue "id"
+     */
     nodeIdFrom?: "id" | "label" | "index" | undefined;
-    /** Whether an edge may reference an undeclared node (default true; the GEXF importer defaults false for edges). */
+    /**
+     * Whether an edge may name a node the file never declares; that node is then created. When
+     * false, such an edge is skipped as an error. The default is false for GEXF, XGMML, CX, CX2 and
+     * Cytoscape sessions, whose files must declare every node, and true for the other formats.
+     * @defaultValue per format
+     */
     addMissingNodes?: boolean | undefined;
-    /** The builder's duplicate-edge policy seed; default "keep". */
+    /**
+     * What to do with a second edge between the same two nodes: "keep" keeps both, "first" / "last"
+     * keep one, "sum" / "min" / "max" keep one with the weights combined, and "error" stops the
+     * import. Merged edges are reported once as W_EDGES_MERGED.
+     * @defaultValue "keep"
+     */
     duplicateEdges?: DuplicatePolicy | undefined;
-    /** The builder's self-loop policy seed; default "keep". */
+    /**
+     * What to do with an edge from a node to itself: "keep", "drop" (reported once as
+     * W_SELF_LOOPS_DROPPED with the number removed), or "error" to stop the import.
+     * @defaultValue "keep"
+     */
     selfLoops?: "keep" | "drop" | "error" | undefined;
-    /** What to do with a file whose edges disagree on direction (design section 3.6); default "expand". */
+    /**
+     * How edge direction is read. "expand" (the default) keeps the file's direction, and for a file
+     * that has both directed and undirected edges makes a directed graph in which each undirected
+     * edge is two edges, marked so an export can write them back as one. "directed" / "undirected"
+     * read every edge of any file that way, including a file whose edges all have the other
+     * direction, with a W_DIRECTION_FORCED warning. "error" stops the import at the first edge whose
+     * direction differs from the file's.
+     * @defaultValue "expand"
+     */
     onMixedDirection?: "expand" | "directed" | "undirected" | "error" | undefined;
-    /** The direction assumed for a file that declares none (GEXF: undirected per spec). */
+    /**
+     * Whether the graph is directed when the file does not say. The default is undirected for
+     * GraphML, GEXF, GML, JSON and XGMML, and directed for CSV, Pajek and Cytoscape sessions. DOT,
+     * Neo4j, CX, CX2 and OBO files always settle the direction themselves (DOT by `graph` or
+     * `digraph`; the others are always directed), so those formats do not read this option and
+     * report it as W_OPTION_IGNORED.
+     * @defaultValue per format
+     */
     defaultDirected?: boolean | undefined;
-    /** The attribute that becomes THE weight (per-format default: "weight", GML "value"); null = unweighted. */
+    /**
+     * The edge attribute read as the edge weight. The default is "weight", except "value" for GML
+     * and Pajek and none for OBO. Pass null to read every attribute as a plain attribute and leave
+     * the graph unweighted. A name no edge has leaves the graph unweighted, with a W_WEIGHT_NOT_FOUND
+     * warning: one options object with `weightFrom: "weight"` shared across formats reads GML and
+     * Pajek files, which keep their weights in `value`, without weights. An edge whose weight cell is
+     * empty or missing gets the default weight 1, and an export writes no weight for it.
+     * @defaultValue per format
+     */
     weightFrom?: string | null | undefined;
-    /** Weight staging precision; "f64" for every importer by default so 0.1 and 16777217 survive. */
+    /**
+     * Whether weights a 32-bit float cannot hold exactly are also kept exactly. "f64" keeps them in
+     * an edge column that `snapshot.edges.byRole("weight")` finds, so 0.1 and 16777217
+     * stay exact. "f32" keeps no such column and uses less memory: the 32-bit weight arrays
+     * `snapshot.weights` and `snapshot.edgeList().weights`, which every import fills, are then the
+     * only weights.
+     * @defaultValue "f64"
+     */
     weightDtype?: "f32" | "f64" | undefined;
-    /** How a declared `long` column is stored: "f64" (default) or "string" (design section 5.1). */
+    /**
+     * How a column the file declares as a 64-bit integer is stored: "f64" (a number, exact up to
+     * 2^53) or "string" (every digit kept, as text). GML declares no types, so there it applies to a
+     * key whose integer values go beyond 2^53.
+     * @defaultValue "f64"
+     */
     long?: "f64" | "string" | undefined;
-    /** Restore ids mangled by sanitizeIds "mangle" from the graphty:originalId attribute (default true). */
+    /**
+     * Whether to give back the original ids that an export with `sanitizeIds: "mangle"` had to
+     * rewrite. The export writes them to the file in an attribute whose name each format page
+     * gives. When false, the rewritten ids stay the ids and the originals are an ordinary node
+     * attribute, named after the format's spelling: `graphty.originalId` in GraphML,
+     * `graphty_originalId` in GML and Pajek, `graphty:originalId` in CX, CX2 and Cytoscape sessions,
+     * and a `graphty:originalId` entry of the `property_value` attribute in OBO.
+     * @defaultValue true
+     */
     restoreMangledIds?: boolean | undefined;
-    /** GraphML / JGF hyperedges: refuse, skip with a report entry (default), or expand to a star / clique. */
+    /**
+     * What to do with a GraphML or JGF hyperedge (an edge with more than two ends): "skip" leaves it
+     * out with a warning, "error" stops the import, and "star" and "clique" turn it into ordinary
+     * edges. "clique" joins every pair of ends. "star" works differently per format: GraphML adds a
+     * new hub node joined to every end, while JGF makes the hyperedge's first node the hub, so no
+     * node is added. A directed JGF hyperedge (`source` and `target` arrays) becomes one edge from
+     * every source to every target under both. In JGF every edge made from a hyperedge carries the
+     * hyperedge's id, label, relation and metadata; GraphML drops a hyperedge's `<data>` and its
+     * `<desc>`, with a warning.
+     * @defaultValue "skip"
+     */
     hyperedges?: "error" | "skip" | "star" | "clique" | undefined;
-    /** Errors tolerated before the importer aborts with E_IMPORT (default 100). */
+    /**
+     * How many errors an import tolerates. Each error skips one node, edge or value and is listed in
+     * the report; one error more than this stops the import with an ImportError. Pass 0 to stop at
+     * the first error.
+     * @defaultValue 100
+     */
     errorLimit?: number | undefined;
-    /** Cancellation; the importer stops between chunks and rejects with the signal's reason. */
+    /**
+     * Cancels the import. When it aborts, the import stops and rejects with the signal's reason
+     * (an AbortError, or a TimeoutError from `AbortSignal.timeout()`).
+     */
     signal?: AbortSignal | undefined;
-    /** Progress in bytes; `bytesTotal` is known for in-memory input only. */
+    /**
+     * Called as the input is read, with the bytes read so far and the total. For a string or a
+     * Uint8Array the total is known from the first call. For a stream (which includes loadFromUrl()
+     * and loadFromFile()) it is undefined until the last call, which always has
+     * `bytesDone === bytesTotal`. Text counts its UTF-8 length.
+     */
     onProgress?: ((bytesDone: number, bytesTotal?: number) => void) | undefined;
     /**
-     * The character encoding of byte input (a WHATWG label such as "utf-8", "windows-1252",
-     * "iso-8859-1", "utf-16le"); overrides the byte order mark and any encoding the file declares.
-     * Absent: a BOM decides, else the declaration (XML prolog, DOT `charset`), else UTF-8, and
-     * bytes that are not valid UTF-8 are read as windows-1252 with a warning. Ignored for text input.
+     * The character encoding of byte input, as a label such as "utf-8", "windows-1252" or
+     * "utf-16le". Without it graph-io uses a byte order mark, then the encoding the file declares
+     * (an XML declaration, DOT's `charset`), then UTF-8, and reads bytes that are not UTF-8 as
+     * windows-1252 with a warning. A byte order mark wins over this option. A string input is
+     * already text: setting this option for one adds a W_OPTION_IGNORED warning, once per input (a
+     * CSV import with a `nodes` table has two inputs).
      */
     encoding?: string | undefined;
 }
 
 /**
- * Which graph of an input that holds several to read: by position or by name, never both. An
- * importer of a format that can hold several graphs (a Cytoscape session, a CX collection, a JGF
- * or OBO Graphs `graphs` array) accepts these next to its own options; absent, it reads the first.
+ * Which graph to read from a file that holds several: by position or by name, never both. Without
+ * either, the first graph is read.
+ * @category Loading
  */
 export interface GraphChoiceOptions {
-    /** The 0-based position of the graph, as `GraphListing.index` gives it. */
+    /**
+     * The 0-based position of the graph to read from a file that holds several (`listGraphs()`
+     * gives each graph's `index`). A position past the last graph stops the import with an
+     * ImportError whose `issue.code` is E_GRAPH_NOT_FOUND; its message lists the file's graphs.
+     * @defaultValue 0
+     */
     graphIndex?: number | undefined;
-    /** The name of the graph, as `GraphListing.name` gives it; a name two graphs share is refused. */
+    /**
+     * The name of the graph to read from a file that holds several (`listGraphs()` gives each
+     * graph's `name`). A name no graph has stops the import with an ImportError whose `issue.code`
+     * is E_GRAPH_NOT_FOUND, and a name two graphs share with one whose `issue.code` is
+     * E_AMBIGUOUS_GRAPH_NAME.
+     */
     graphName?: string | undefined;
 }
 
-/** One graph of an input that can hold several, as an importer's listGraphs() describes it. */
+/**
+ * One graph of an input that can hold several, as an importer's listGraphs() describes it.
+ * @category Loading
+ */
 export interface GraphListing {
     /** The value graphIndex takes to read it. */
     readonly index: number;
@@ -100,37 +212,49 @@ export interface GraphListing {
 }
 
 /**
- * An importer plugin (design section 8.4): pushes scalars into the caller's sink in one pass and
- * never freezes. `Opts` is its format-specific option set; the default `unknown` lets a caller pass
- * the common options to an importer typed without one.
+ * A format's reader. It reads the input once, from start to end, and adds each node, edge and
+ * attribute to a graph builder (`GraphSink`, which `GraphBuilder` from @graphty/graph-format
+ * implements); importGraph() then builds the snapshot. Register one with
+ * `registry.registerImporter()` to teach graph-io a new format. `Opts` is the type of the format's
+ * own options.
+ * @category Writing a format
  */
 export interface GraphImporter<Opts = unknown> {
-    /** The format name: "gexf", "graphml", "gml", "dot", "pajek", "csv", "json", "neo4j". */
+    /** The name callers pass as `format`, such as "graphml" or "csv"; lowercase, unique in a registry. */
     readonly format: string;
-    /** File extensions with the leading dot. */
+    /** File extensions with the leading dot, most common first; used to detect the format from a file name. */
     readonly extensions: readonly string[];
-    /** MIME types the format is served as. */
+    /** MIME types the format is served as, most specific first; used to detect the format from a Content-Type. */
     readonly mimeTypes: readonly string[];
     /**
-     * Confidence that `head` is this format, for the registry's sniff().
+     * The names of this format's own options (`["separator"]`), when you want misspelled options
+     * reported. While every registered importer lists its options, a load warns `W_UNKNOWN_OPTION` for
+     * a name that no format and no load function takes. Leave it out to report nothing.
+     */
+    readonly options?: readonly string[] | undefined;
+    /**
+     * How sure you are that `head`, the first bytes of a file (up to SNIFF_HEAD_BYTES), is this
+     * format: 0 for no, up to 1 for certain. Below 0.5 counts as a weak guess, which loses to a
+     * file extension another format claims. Without this method the format is detected only by
+     * file name and MIME type.
      * @param head - the first bytes of the input
      * @returns a confidence in 0..1
      */
     sniff?(head: Uint8Array): number;
     /**
-     * Read `input` into `sink`; per-element errors are aggregated into the report until the error
-     * limit, then the importer throws ImportError with the partial report.
+     * Read `input` into `sink`. Record each problem in an ImportReportBuilder and skip the element;
+     * the builder throws ImportError once there are more errors than `errorLimit`.
      * @param input - the text, bytes or stream to read
-     * @param sink - the builder (or a recording sink) to push into
-     * @param options - format-specific and common options
-     * @returns the import report
+     * @param sink - the graph builder to add nodes, edges and attributes to
+     * @param options - the format's own options and the options every importer takes
+     * @returns the import report (`report.finish()`)
      */
     import(input: ImportInput, sink: GraphSink, options?: Opts & CommonImportOptions): Promise<ImportReport>;
     /**
-     * Read every graph of an input that can hold several (a DOT file with several graphs, a
-     * Pajek project with several networks, a JGF `graphs` array), each into its own sink. An
-     * importer without this method reads one graph per input. `import()` reads the first graph
-     * and warns how many it skipped.
+     * Optional, for a format whose files can hold several graphs: read every graph, each into its
+     * own sink. importAllGraphs() calls it; with it, importGraph() also honors `graphIndex` and
+     * `graphName` by reading every graph and returning the chosen one. `import()` should read the
+     * first graph and warn W_MULTIPLE_GRAPHS with the number skipped.
      * @param input - the text, bytes or stream to read
      * @param sinkFor - called once per graph, in document order, before that graph's first push
      * @param options - format-specific and common options
@@ -142,9 +266,10 @@ export interface GraphImporter<Opts = unknown> {
         options?: Opts & CommonImportOptions,
     ): Promise<ImportReport[]>;
     /**
-     * List the graphs of an input that can hold several without importing them, so a caller can
-     * offer a choice before reading one with `graphIndex` or `graphName`. An importer without this
-     * method does not list its graphs; `import()` reads the first.
+     * Optional: list the graphs of a file without importing them, so a caller can offer a choice.
+     * listGraphs() calls it. An importer that has it must also honor `graphIndex` and `graphName`
+     * in `import()` itself (`chooseGraph()` resolves them); one without it lists nothing and the
+     * registry makes the choice through `importAll()`.
      * @param input - the text, bytes or stream to read
      * @param options - format-specific and common options
      * @returns one listing per graph, in document order
@@ -153,98 +278,185 @@ export interface GraphImporter<Opts = unknown> {
 }
 
 /**
- * What a format can express without loss (design section 8.5): the fidelity matrix of research
- * note 07 section 9 as a table, and the acceptance test list for check().
+ * What a format can store exactly. checkCapabilities() compares a graph against it and returns a
+ * loss note for everything the graph has that the format cannot store.
+ * @category Saving
  */
 export interface ExportCapabilities {
-    /** Directed and undirected edges in one file. */
+    /**
+     * Whether one file can hold directed and undirected edges together. When false, a graph with both
+     * needs `onMixedDirection` ("directed" or "undirected") to be saved.
+     */
     readonly mixedDirection: boolean;
-    /** Parallel edges. */
+    /**
+     * Whether the file can hold two edges between the same pair of nodes. When false, the extra
+     * edges are not kept as separate edges.
+     */
     readonly multiEdges: boolean;
-    /** Self-loops. */
+    /** Whether the file can hold an edge from a node to itself. When false, such edges are lost. */
     readonly selfLoops: boolean;
-    /** Whether edge ids are required (generated when absent), optional or unsupported. */
+    /**
+     * Whether edges carry ids. "required": every edge has one, and ids are made up (e0, e1, ...)
+     * for a graph without them. "optional": edge ids are written when the graph has them. "none":
+     * edge ids are lost.
+     */
     readonly edgeIds: "required" | "optional" | "none";
-    /** Which node ids can be written unchanged. */
+    /**
+     * Which node ids the format can write as they are: "any"; "nmtoken" (XML name tokens: letters,
+     * digits and `. - _ :`, no spaces); "integer"; or "dense-1-based" (the nodes are always numbered
+     * 1 to N). Other ids need `sanitizeIds: "mangle"`, which writes the original ids too.
+     */
     readonly idCharset: "any" | "nmtoken" | "integer" | "dense-1-based";
-    /** The column dtypes the format keeps as declared. */
+    /**
+     * The attribute types the format keeps exactly: "bool", "i32" (32-bit integer), "u32" (unsigned
+     * 32-bit integer), "u8" (byte), "f32" (32-bit float), "f64" (64-bit float, a JavaScript number),
+     * "string" (text), "dict" (text stored as a dictionary of repeated values), "list" and "json".
+     * An attribute of another type is written as the nearest one the format has, with a
+     * W_DTYPE_UNSUPPORTED note.
+     */
     readonly dtypes: readonly Dtype[];
-    /** Multi-component (stride) columns. */
+    /**
+     * Whether an attribute other than the node position can hold several numbers per node or edge
+     * (a vector). When false, such an attribute does not read back as one attribute. Positions
+     * are covered by `positions`.
+     */
     readonly components: boolean;
-    /** List columns. */
+    /** Whether an attribute can hold a list per node or edge. When false, list attributes are lost or flattened. */
     readonly lists: boolean;
-    /** Nested json columns. */
+    /**
+     * Whether an attribute can hold nested JSON objects and arrays. When false, such attributes are
+     * written as text or lost.
+     */
     readonly json: boolean;
-    /** Declared defaults. */
+    /** Whether the file can declare a default value for an attribute. When false, declared defaults are lost. */
     readonly defaults: boolean;
-    /** Declared enumerations (GEXF options). */
+    /**
+     * Whether the file can declare the allowed values of an attribute (GEXF `options`). When false,
+     * those declarations are lost; the values themselves are kept.
+     */
     readonly options: boolean;
-    /** Containment (parent / parents roles). */
+    /** Whether nodes can sit inside other nodes (groups or clusters). When false, the nesting is lost. */
     readonly hierarchy: boolean;
-    /** Temporal support level. */
+    /**
+     * What the file can say about time: "none" (time attributes are lost), "intervals" (one start
+     * and end per element), "spells" (several intervals per element), or "dynamic-values"
+     * (attribute values that change over time, as well).
+     */
     readonly temporal: "none" | "intervals" | "spells" | "dynamic-values";
-    /** Graph-level attributes. */
+    /** Whether the file can hold attributes of the graph itself. When false, graph attributes are lost. */
     readonly graphAttributes: boolean;
-    /** The position role. */
+    /** Whether the file can hold node positions. When false, the layout is lost. */
     readonly positions: boolean;
-    /** The visual roles (color, size, shape, thickness). */
+    /** Whether the file can hold node and edge color, size, shape and thickness. When false, they are lost. */
     readonly viz: boolean;
 }
 
-/** One thing an exporter cannot represent, reported by check() before anything is written (design section 8.5). */
+/**
+ * One thing a format cannot store, returned by checkExport() before anything is written.
+ * @category Saving
+ */
 export interface LossNote {
-    /** A stable code such as "W_OPEN_INTERVAL". */
+    /**
+     * A stable code. Codes starting with "E_" mean the export refuses to write under these options:
+     * the exportGraph*() functions throw a GraphFormatError. Codes starting with "W_" mean the file
+     * is written, but this part will not read back the same.
+     */
     readonly code: string;
-    /** A plain-ASCII human-readable explanation. */
+    /** A plain-English explanation. */
     readonly message: string;
-    /** The affected column, or null when the note is not about a column. */
+    /** The attribute column involved, or null. */
     readonly column: string | null;
-    /** How many rows or elements are affected, or null when not counted. */
+    /** How many nodes, edges or values are affected, or null when not counted. */
     readonly count: number | null;
 }
 
-/** The options every exporter accepts next to its format-specific ones (design section 8.5). */
+/**
+ * The options every exporter accepts next to its format-specific ones.
+ * @category Saving
+ */
 export interface CommonExportOptions {
-    /** "error" (default): never rename a node; "mangle": rewrite ids the format cannot hold and keep the original. */
+    /**
+     * What to do with node ids the format cannot hold. "error": the export throws (E_INVALID_ID) and
+     * no node is renamed. "mangle": such ids are rewritten and the originals are written to the
+     * file too, so an import with `restoreMangledIds` (on by default) reads the original ids back.
+     * Pajek is the exception: it always numbers nodes 1 to N and keeps the old ids as labels.
+     * @defaultValue "error"
+     */
     sanitizeIds?: "error" | "mangle" | undefined;
-    /** For formats without mixed-direction support: refuse (default) or write every edge one way. */
+    /**
+     * What a format with one direction per file does with a graph that has both directed and
+     * undirected edges: "error" throws (E_DIRECTED), "directed" writes every edge as directed (an
+     * undirected edge once, as one directed edge), "undirected" writes the whole graph undirected.
+     * A format that keeps each edge's own direction (GraphML, GEXF, CSV, Pajek, XGMML, Cytoscape
+     * sessions, and the JGF and graphology JSON dialects) ignores it and writes both kinds; to make
+     * such a graph all one direction, read it with the import option `onMixedDirection`.
+     * @defaultValue "error"
+     */
     onMixedDirection?: "error" | "directed" | "undirected" | undefined;
 }
 
 /**
- * An exporter plugin (design section 8.5): iterates nodes and logical edges (never arcs) in index
- * order and reads the role columns of section 3.6 / 3.7 to fold expanded pairs and emit explicit
- * weights only.
+ * A format's writer. Register one with `registry.registerExporter()` to make a format writable by
+ * every save function. `Opts` is the type of the format's own options.
+ * @category Writing a format
  */
 export interface GraphExporter<Opts = unknown> {
-    /** The format name. */
+    /** The name callers pass as `format`; the same as the importer's when the format has both. */
     readonly format: string;
-    /** What the format can express. */
+    /** What the format can store exactly; build it with `capabilities()`. */
     readonly capabilities: ExportCapabilities;
     /**
-     * Pre-flight: what export() would lose, without writing anything.
-     * @param snapshot - the snapshot to check
-     * @param options - format-specific and common options
-     * @returns the loss notes, empty when the export is exact
+     * File extensions with the leading dot, most common first. Optional; listFormats() uses them
+     * when no importer is registered for the format (an export-only format).
+     */
+    readonly extensions?: readonly string[] | undefined;
+    /** MIME types, most specific first. Optional; used the same way as `extensions`. */
+    readonly mimeTypes?: readonly string[] | undefined;
+    /**
+     * The names of this format's own save options, when you want misspelled options reported. While
+     * every registered exporter lists its options, `checkExport()` returns a `W_UNKNOWN_OPTION` note for
+     * a name that no format and no save function takes. Leave it out to report nothing.
+     */
+    readonly options?: readonly string[] | undefined;
+    /**
+     * What a save would lose, without writing anything; checkExport(snapshot, format, options) calls
+     * it. Start from `checkCapabilities(snapshot, capabilities, resolveExportOptions(options))` and
+     * add a note for anything else your format changes. Every difference a re-import would show
+     * needs a note.
+     * @param snapshot - the graph to check
+     * @param options - the format's own options and the options every exporter takes
+     * @returns the loss notes, empty when the save is exact
      */
     check(snapshot: GraphSnapshot, options?: Opts & CommonExportOptions): readonly LossNote[];
     /**
-     * Write the snapshot as UTF-8 chunks.
-     * @param snapshot - the snapshot to write
-     * @param options - format-specific and common options
-     * @returns the encoded chunks
+     * Write the graph as byte chunks: UTF-8 text for a text format (`encodeChunks()` turns string
+     * parts into them), the raw bytes for a binary one. Throw a GraphFormatError before writing for
+     * every "E_" note `check()` returns.
+     * @param snapshot - the graph to write
+     * @param options - the format's own options and the options every exporter takes
+     * @returns the file's bytes, chunk by chunk
      */
     export(snapshot: GraphSnapshot, options?: Opts & CommonExportOptions): AsyncIterable<Uint8Array>;
     /**
-     * Write the snapshot as one string.
-     * @param snapshot - the snapshot to write
-     * @param options - format-specific and common options
-     * @returns the whole document
+     * Write the graph as one string (`joinText()` joins string parts). A binary format rejects with
+     * a GraphFormatError E_UNSUPPORTED (`details.reason` "binary") instead.
+     * @param snapshot - the graph to write
+     * @param options - the format's own options and the options every exporter takes
+     * @returns the whole file
      */
     exportToString(snapshot: GraphSnapshot, options?: Opts & CommonExportOptions): Promise<string>;
 }
 
-/** The categories of an ImportIssue (design section 8.6). */
+/**
+ * What an ImportIssue is about, for errors and warnings alike: "parse-error" (the text is not valid
+ * in the format), "missing-value" (something required is absent), "validation-error" (a value
+ * breaks a rule of the format or of an option; an error skips it, a warning keeps it as written,
+ * such as an id with spaces around it), "unsupported" (the file uses something graph-io does not
+ * read), "precision" (a value was rounded), "coercion" (a value or id changed type) and "merged"
+ * (elements were combined). Sort by `severity` first: the category says what kind of problem it
+ * is, not how serious.
+ * @category Reports and errors
+ */
 export type IssueCategory =
     | "parse-error"
     | "missing-value"
@@ -254,37 +466,49 @@ export type IssueCategory =
     | "coercion"
     | "merged";
 
-/** One problem found while importing (design section 8.6). */
+/**
+ * One problem found while importing.
+ * @category Reports and errors
+ */
 export interface ImportIssue {
     /** The category. */
     readonly category: IssueCategory;
-    /** Errors count toward the error limit; warnings do not. */
+    /**
+     * "error": the element was skipped and counts toward `errorLimit`. "warning": the element was
+     * kept, possibly changed.
+     */
     readonly severity: "error" | "warning";
-    /** A stable code such as "E_UNKNOWN_NODE" or "W_WIDENED". */
+    /** A stable code; E_ for errors, W_ for warnings ("E_UNKNOWN_NODE", "W_WIDENED"). */
     readonly code: string;
-    /** A plain-ASCII human-readable message. */
+    /** A plain-English message. */
     readonly message: string;
-    /** The 1-based source line, or null when unknown. */
+    /** The 1-based line in the input, or null when the format has no lines or it is unknown. */
     readonly line: number | null;
-    /** The element (a node or edge id, an attribute name), or null when unknown. */
+    /** The node id, edge id or attribute name involved, or null. */
     readonly element: string | null;
 }
 
-/** What an import produced besides the sink's contents (design section 8.6). */
+/**
+ * What happened while a file was read.
+ * @category Reports and errors
+ */
 export interface ImportReport {
-    /** The importer's format name. */
+    /** The format the file was read as. */
     readonly format: string;
-    /** Element counts. */
+    /**
+     * What was read from the file, counted before the graph was built: `duplicateEdges` and
+     * `selfLoops: "drop"` can leave fewer edges in the snapshot (each reported as a warning).
+     */
     readonly counts: {
-        /** Nodes pushed. */
+        /** Nodes read. */
         readonly nodes: number;
-        /** Logical edges pushed (both halves of an expanded edge count). */
+        /** Edges read (an undirected edge expanded into two by onMixedDirection "expand" counts twice). */
         readonly edges: number;
         /** Nodes skipped after an error. */
         readonly skippedNodes: number;
         /** Edges skipped after an error. */
         readonly skippedEdges: number;
-        /** Edges expanded under onMixedDirection "expand" (design section 3.6). */
+        /** Undirected edges expanded into two by onMixedDirection "expand". */
         readonly expandedMixed: number;
     };
     /** Every issue recorded, in order. */
@@ -297,28 +521,75 @@ export interface ImportReport {
     readonly truncated: boolean;
     /** What the importer could not represent. */
     readonly lossy: readonly LossNote[];
-    /** Wall time of the parse phase; the caller's freeze reports separately. */
+    /** How long reading the file took, in milliseconds. */
     readonly durationMs: number;
 }
 
 /**
- * The error an importer throws when the error limit is reached or the input cannot be read at all
- * (design section 8.6): a GraphFormatError with code "E_IMPORT" (reserved in the core's union so
- * `err.code === "E_IMPORT"` narrows) carrying the partial report.
+ * What a load function throws when the input cannot be read: the URL failed, the format was not
+ * recognized, the file could not be parsed, or there were more errors than `errorLimit`. It is a
+ * GraphFormatError with code "E_IMPORT"; `issue` says what stopped the import and `report` holds
+ * everything recorded until then.
+ * @category Reports and errors
  */
 export class ImportError extends GraphFormatError {
-    /** The report as it stood when the import aborted. */
-    readonly report: ImportReport;
+    /**
+     * Everything recorded up to the point the import stopped. It is not an enumerable property, so an
+     * uncaught ImportError prints its message and issue, not every issue of the report.
+     */
+    declare readonly report: ImportReport;
+
+    /**
+     * The issue that stopped the import: its `code` ("E_FETCH", "E_UNKNOWN_FORMAT", "E_CSV_UNCLOSED_QUOTE", ...),
+     * `message`, `line` and `element`. This is the value to branch on; `code` is always "E_IMPORT".
+     * Null only for an ImportError constructed by hand without a matching issue.
+     * @example
+     * ```ts
+     * if (err instanceof ImportError) {
+     *     switch (err.issue?.code) {
+     *         case "E_FETCH":
+     *             console.error(`download failed with status ${String(err.details.status)}`);
+     *             break;
+     *         case "E_UNKNOWN_FORMAT":
+     *             console.error("not a graph file this library can read; pass `format`");
+     *             break;
+     *         default:
+     *             console.error(err.message);
+     *     }
+     * }
+     * ```
+     */
+    readonly issue: ImportIssue | null;
 
     /**
      * Create an ImportError.
      * @param message - a plain-ASCII human-readable message
      * @param report - the partial report
-     * @param details - optional machine-readable context
+     * @param details - optional machine-readable context; its `code` names the issue that stopped the import
      */
     constructor(message: string, report: ImportReport, details?: Readonly<Record<string, unknown>>) {
         super("E_IMPORT", message, details);
         this.name = "ImportError";
-        this.report = report;
+        Object.defineProperty(this, "report", { value: report, enumerable: false });
+        this.issue = stoppingIssue(report.issues, details?.code);
+    }
+}
+
+/**
+ * The issue that stopped an import: the last one with the code the abort named, else the last error.
+ * @param issues - the report's issues
+ * @param code - the code the abort named, if any
+ * @returns the issue, or null
+ */
+function stoppingIssue(issues: readonly ImportIssue[], code: unknown): ImportIssue | null {
+    let lastError: ImportIssue | null = null;
+    for (let i = issues.length - 1; i >= 0; i--) {
+        if (issues[i].code === code) {
+            return issues[i];
+        }
+        if (lastError === null && issues[i].severity === "error") {
+            lastError = issues[i];
+        }
     }
+    return lastError;
 }