@graphty/graph-io 0.2.4 → 0.3.0

package/src/common/xml.ts

@@ -226,6 +226,20 @@ function countIllegalRows(column: Column): number {
     return bad;
 }
 
+/** The encoding pseudo-attribute of an XML declaration at the very start of a document. */
+const XML_DECLARED_ENCODING = /^<\?xml\s[^>]*?\bencoding\s*=\s*["']([A-Za-z][A-Za-z0-9._-]*)["']/;
+
+/**
+ * The encoding an XML document declares in its prolog (`<?xml version="1.0" encoding="..."?>`),
+ * for the shared byte decoder (common/input.ts).
+ * @param head - the start of the document, decoded as windows-1252
+ * @returns the declared label, or null when there is no declaration or it names no encoding
+ */
+export function xmlDeclaredEncoding(head: string): string | null {
+    const match = XML_DECLARED_ENCODING.exec(head);
+    return match === null ? null : match[1];
+}
+
 /**
  * Whether a text is an XML Name.
  * @param text - the text

package/src/formats/csv/exporter.ts

@@ -55,7 +55,11 @@ export const CSV_LOSS = Object.freeze({
     ID_TEXT_COLLISION: LOSS.ID_TEXT_COLLISION,
     /** Ids whose text reads back as the other type under the canonical rule. */
     ID_TEXT_TYPE: LOSS.ID_TEXT_TYPE,
-    /** The generic dialect has no direction column; an undirected or mixed graph reads back as directed. */
+    /**
+     * The generic dialect has no direction column; an undirected or mixed graph reads back as
+     * directed. The Gephi dialect loses the direction of an undirected graph without edges (no
+     * row carries a Type cell).
+     */
     DIRECTION_DROPPED: "W_CSV_DIRECTION_DROPPED",
     /** Mutual pairs are written as two directed rows. */
     MUTUAL_EXPANDED: LOSS.MUTUAL_EXPANDED,
@@ -390,6 +394,13 @@ function planExport(
                 mixed,
             );
         }
+    } else if (csv.table === "edges" && !snapshot.directed && edgeRows.length === 0) {
+        note(
+            CSV_LOSS.DIRECTION_DROPPED,
+            "the direction lives in the Type cell of each edge row; an undirected graph without edges reads back as directed",
+            null,
+            0,
+        );
     }
     if (folding.mutualCount > 0) {
         note(

package/src/formats/csv/importer.ts

@@ -453,6 +453,7 @@ class TableReader {
             comments: COMMENT_CHARS,
             signal: state.common.signal,
             onProgress: progress ? state.common.onProgress : null,
+            encoding: state.common.encoding,
         };
         this.reader = new CsvRecordReader(input, state.report, readerOptions);
     }

package/src/formats/csv/index.ts

@@ -6,10 +6,13 @@ import {
     COLUMN_RENAMED_CODE,
     DIRECTION_FORCED_CODE,
     DIRECTION_REFUSED_CODE,
+    ENCODING_FALLBACK_CODE,
+    INVALID_ENCODING_CODE,
     INVALID_UTF8_CODE,
     MIXED_DIRECTION_CODE,
     OPTION_IGNORED_CODE,
     SINK_OPTION_CODE,
+    UNKNOWN_ENCODING_CODE,
 } from "../../common/codes.js";
 import { WIDENING_UNSUPPORTED_CODE } from "../../common/text.js";
 import {
@@ -43,6 +46,12 @@ export const CSV_ISSUE = Object.freeze({
     EMPTY_INPUT: EMPTY_INPUT_CODE,
     /** The input holds invalid UTF-8 (fatal). */
     INVALID_UTF8: INVALID_UTF8_CODE,
+    /** Invalid bytes in the encoding a BOM, a declaration or the encoding option chose (fatal). */
+    INVALID_ENCODING: INVALID_ENCODING_CODE,
+    /** Bytes that are not UTF-8 and declare no encoding were read as windows-1252. */
+    ENCODING_FALLBACK: ENCODING_FALLBACK_CODE,
+    /** A declared encoding the platform cannot decode was ignored. */
+    UNKNOWN_ENCODING: UNKNOWN_ENCODING_CODE,
     /** The header names neither endpoint columns nor an id column (fatal). */
     NO_ENDPOINT_COLUMNS: NO_ENDPOINT_COLUMNS_CODE,
     /** A node table without an id column (fatal). */

package/src/formats/csv/records.ts

@@ -760,7 +760,7 @@ export class CsvRecordReader implements AsyncIterable<string[]> {
             input,
             report,
             { delimiter: options.delimiter ?? null, quote: '"', comments: options.comments },
-            { signal: options.signal, onProgress: options.onProgress },
+            { signal: options.signal, onProgress: options.onProgress, encoding: options.encoding },
         );
     }
 

package/src/formats/dot/exporter.ts

@@ -50,7 +50,7 @@ export interface DotExportOptions {
 
 /** The LossNote codes of the DOT exporter; the shared ones are LOSS's. */
 export const DOT_LOSS = Object.freeze({
-    /** An id, name or text with a backslash before a quote or at its end cannot be written as a DOT quoted string; export() throws. */
+    /** An id, name or text with a backslash before a quote or a line break, or at its end, cannot be written as a DOT quoted string; export() throws. */
     TRAILING_BACKSLASH: "E_DOT_TRAILING_BACKSLASH",
     /** A non-finite f32 / f64 cell has no numeric DOT spelling and reads back as text. */
     NON_FINITE: "W_DOT_NON_FINITE",
@@ -448,7 +448,7 @@ class ExportPlan {
         if (unwritable > 0) {
             note(
                 DOT_LOSS.TRAILING_BACKSLASH,
-                `${unwritable} id(s), name(s) or text value(s) hold a backslash before a quote or at the end, which a DOT quoted string cannot carry; export() will throw`,
+                `${unwritable} id(s), name(s) or text value(s) hold a backslash before a quote or a line break, or at the end, which a DOT quoted string cannot carry; export() will throw`,
                 null,
                 unwritable,
             );
@@ -576,7 +576,7 @@ class ExportPlan {
         if (first !== null) {
             throw new GraphFormatError(
                 first.kind === "id" ? "E_INVALID_ID" : "E_COLUMN_TYPE",
-                `${first.kind} ${JSON.stringify(first.text)} ends in a backslash, which a DOT quoted string cannot carry`,
+                `${first.kind} ${JSON.stringify(first.text)} holds a backslash before a quote or a line break, or at its end, which a DOT quoted string cannot carry`,
                 { reason: "trailing backslash", kind: first.kind, value: first.text },
             );
         }

package/src/formats/dot/importer.ts

@@ -47,7 +47,9 @@ import {
     DIRECTION_FORCED_CODE,
     DIRECTION_REFUSED_CODE,
     EMPTY_INPUT_CODE,
+    ENCODING_FALLBACK_CODE,
     ID_MERGED_CODE,
+    INVALID_ENCODING_CODE,
     INVALID_UTF8_CODE,
     MIXED_DIRECTION_CODE,
     MULTIPLE_GRAPHS_CODE,
@@ -55,6 +57,7 @@ import {
     ROLE_TAKEN_CODE,
     SINK_OPTION_CODE,
     SYNTAX_CODE,
+    UNKNOWN_ENCODING_CODE,
 } from "../../common/codes.js";
 import { DirectionResolver, type EdgeKind } from "../../common/direction.js";
 import { IdCoercer } from "../../common/ids.js";
@@ -106,6 +109,12 @@ export const DOT_ISSUE = Object.freeze({
     EMPTY_INPUT: EMPTY_INPUT_CODE,
     /** The input holds invalid UTF-8 (fatal). */
     INVALID_UTF8: INVALID_UTF8_CODE,
+    /** Invalid bytes in the encoding a BOM, a declaration or the encoding option chose (fatal). */
+    INVALID_ENCODING: INVALID_ENCODING_CODE,
+    /** Bytes that are not UTF-8 and declare no encoding were read as windows-1252. */
+    ENCODING_FALLBACK: ENCODING_FALLBACK_CODE,
+    /** A declared encoding the platform cannot decode was ignored. */
+    UNKNOWN_ENCODING: UNKNOWN_ENCODING_CODE,
     /** Subgraphs or braces nested deeper than the parser's limit; fatal. */
     NESTING: "E_DOT_NESTING",
     /** An edge operator contradicting the graph keyword (warning under "operator" / "header"). */
@@ -264,22 +273,166 @@ export const dotImporter: GraphImporter<DotImportOptions> = Object.freeze({
         const report = new ImportReportBuilder(DOT_FORMAT, resolved.errorLimit);
         reportUnusedOptions(options, report, USED_OPTIONS);
         reportSinkOptions(sink, options, report);
-        const text = await readText(input, report, resolved);
-        const parser = new DotParser(text, sink, report, resolved, mismatch);
-        try {
-            parser.parse();
-        } catch (err) {
-            if (err instanceof DotSyntaxError) {
-                report.fail(SYNTAX_CODE, err.message, { line: err.line }, { line: err.line });
-            }
-            throw err;
+        const text = await readText(input, report, { ...resolved, declaredEncoding: dotCharset });
+        const reports = { current: report };
+        const lexer = dotLexer(text, reports);
+        const first = guard(report, () => lexer.next());
+        const trailing = parseGraph(new DotParser(lexer, sink, report, resolved, mismatch), report, first);
+        if (trailing.kind !== "eof") {
+            const skipped = guard(report, () => countGraphs(lexer, trailing));
+            report.warning(
+                "unsupported",
+                MULTIPLE_GRAPHS_CODE,
+                `the input holds ${skipped} more graph(s) after the first; import() reads the first, importAll() reads every one`,
+                { line: trailing.line },
+            );
         }
         // an abort raised during the last few statements (after the last periodic check) still rejects
         throwIfAborted(resolved.signal);
         return report.finish();
     },
+
+    /**
+     * Read every graph of a DOT file (Graphviz renders each one), each into its own sink.
+     * @param input - the text, bytes or stream
+     * @param sinkFor - the sink of the graph with this index, called before its first push
+     * @param options - format-specific and common options
+     * @returns one report per graph; ImportError (E_IMPORT) on a syntax error anywhere
+     */
+    async importAll(
+        input: ImportInput,
+        sinkFor: (index: number) => GraphSink,
+        options?: DotImportOptions & CommonImportOptions,
+    ): Promise<ImportReport[]> {
+        const resolved = resolveImportOptions(options, {
+            ids: "canonical",
+            defaultDirected: true,
+            weightFrom: "weight",
+        });
+        const mismatch = mismatchOption(options?.mismatchedEdgeOperator);
+        const first = new ImportReportBuilder(DOT_FORMAT, resolved.errorLimit);
+        reportUnusedOptions(options, first, USED_OPTIONS);
+        const text = await readText(input, first, { ...resolved, declaredEncoding: dotCharset });
+        const reports = { current: first };
+        const lexer = dotLexer(text, reports);
+        const done: ImportReport[] = [];
+        let token = guard(first, () => lexer.next());
+        do {
+            const report = done.length === 0 ? first : new ImportReportBuilder(DOT_FORMAT, resolved.errorLimit);
+            reports.current = report;
+            const sink = sinkFor(done.length);
+            reportSinkOptions(sink, options, report);
+            token = parseGraph(new DotParser(lexer, sink, report, resolved, mismatch), report, token);
+            throwIfAborted(resolved.signal);
+            done.push(report.finish());
+        } while (token.kind !== "eof");
+        return done;
+    },
 });
 
+/**
+ * The tokenizer of one input; its badly-delimited-numeral warnings go to the report of the graph
+ * being read.
+ * @param text - the DOT text
+ * @param reports - holds the current graph's report
+ * @param reports.current - the report warnings are recorded in
+ * @returns the tokenizer
+ */
+function dotLexer(text: string, reports: { current: ImportReportBuilder }): DotTokenizer {
+    return new DotTokenizer(text, (numeral, line) => {
+        reports.current.warning(
+            "validation-error",
+            DOT_ISSUE.NUMERAL_AMBIGUITY,
+            `badly delimited number ${JSON.stringify(numeral)} splits into two tokens (Graphviz warns the same)`,
+            { line, element: numeral },
+        );
+    });
+}
+
+/**
+ * Run a step that may throw DotSyntaxError, turning it into the fatal E_SYNTAX issue.
+ * @param report - the report of the graph being read
+ * @param step - the step
+ * @returns the step's result
+ */
+function guard<T>(report: ImportReportBuilder, step: () => T): T {
+    try {
+        return step();
+    } catch (err) {
+        if (err instanceof DotSyntaxError) {
+            report.fail(SYNTAX_CODE, err.message, { line: err.line }, { line: err.line });
+        }
+        throw err;
+    }
+}
+
+/**
+ * Parse one graph.
+ * @param parser - the parser of this graph
+ * @param report - its report
+ * @param first - the graph's first token (already read)
+ * @returns the token after the graph's closing brace
+ */
+function parseGraph(parser: DotParser, report: ImportReportBuilder, first: DotToken): DotToken {
+    return guard(report, () => parser.parse(first));
+}
+
+/**
+ * Count the graphs that follow the first one without reading their statements: each must be
+ * `[strict] (graph | digraph) [ID] { ... }` with balanced braces, as Graphviz requires.
+ * @param lexer - the tokenizer, positioned after `first`
+ * @param first - the first token after the first graph
+ * @returns how many graphs follow; DotSyntaxError on anything else
+ */
+function countGraphs(lexer: DotTokenizer, first: DotToken): number {
+    let count = 0;
+    let token = first;
+    while (token.kind !== "eof") {
+        if (isKeyword(token, "strict")) {
+            token = lexer.next();
+        }
+        if (!isKeyword(token, "graph") && !isKeyword(token, "digraph")) {
+            throw new DotSyntaxError(`expected "graph" or "digraph", found ${describeToken(token)}`, token.line);
+        }
+        token = lexer.next();
+        if (token.kind === "id") {
+            token = lexer.next();
+        }
+        if (!isPunct(token, "{")) {
+            throw new DotSyntaxError(`expected "{" after the graph header, found ${describeToken(token)}`, token.line);
+        }
+        for (let depth = 1; depth > 0; ) {
+            token = lexer.next();
+            if (token.kind === "eof") {
+                throw new DotSyntaxError('missing "}" at the end of a graph', token.line);
+            }
+            if (isPunct(token, "{")) {
+                depth++;
+            } else if (isPunct(token, "}")) {
+                depth--;
+            }
+        }
+        count++;
+        token = lexer.next();
+    }
+    return count;
+}
+
+/** A `charset` attribute assignment (Graphviz's declaration of the input encoding). */
+const DOT_CHARSET = /\bcharset\s*=\s*"?([A-Za-z][A-Za-z0-9._-]*)/i;
+
+/**
+ * The encoding a DOT file declares with the graph attribute `charset` (Graphviz reads UTF-8,
+ * Latin1 and Big-5), for the shared byte decoder; Graphviz's spellings `latin-1` and `big-5` are
+ * mapped to the WHATWG labels.
+ * @param head - the start of the file, decoded as windows-1252
+ * @returns the declared label, or null
+ */
+function dotCharset(head: string): string | null {
+    const match = DOT_CHARSET.exec(head);
+    return match === null ? null : match[1].replace(/^(latin|big)-/i, "$1");
+}
+
 /**
  * Resolve the mismatchedEdgeOperator option.
  * @param value - the caller's value
@@ -447,28 +600,21 @@ class DotParser {
     private readonly edgeWriters = new Map<string, TextCellWriter>();
 
     /**
-     * Create a parser over one document.
-     * @param text - the DOT text
+     * Create a parser for one graph of a document.
+     * @param lexer - the document's tokenizer, positioned at the graph
      * @param sink - the sink
      * @param report - the report
      * @param options - the resolved common options
      * @param mismatch - the resolved mismatchedEdgeOperator option
      */
     constructor(
-        text: string,
+        lexer: DotTokenizer,
         sink: GraphSink,
         report: ImportReportBuilder,
         options: ResolvedImportOptions,
         mismatch: "operator" | "header" | "error",
     ) {
-        this.lexer = new DotTokenizer(text, (numeral, line) => {
-            report.warning(
-                "validation-error",
-                DOT_ISSUE.NUMERAL_AMBIGUITY,
-                `badly delimited number ${JSON.stringify(numeral)} splits into two tokens (Graphviz warns the same)`,
-                { line, element: numeral },
-            );
-        });
+        this.lexer = lexer;
         this.sink = sink;
         this.report = report;
         this.options = options;
@@ -478,11 +624,13 @@ class DotParser {
     }
 
     /**
-     * Parse the whole document: `[strict] (graph | digraph) [ID] { stmt_list }`.
+     * Parse one graph: `[strict] (graph | digraph) [ID] { stmt_list }`.
+     * @param first - the graph's first token (already read from the tokenizer)
+     * @returns the token after the closing brace (eof when the document ends there)
      */
-    parse(): void {
+    parse(first: DotToken): DotToken {
         const { lexer } = this;
-        let token = lexer.next();
+        let token = first;
         if (token.kind === "eof") {
             this.report.fail(EMPTY_INPUT_CODE, "the input holds no graph (empty or only comments)", {
                 line: token.line,
@@ -517,15 +665,7 @@ class DotParser {
         });
         const root = this.newScope(null, headerLine, true, null);
         this.statementList(root);
-        const trailing = lexer.next();
-        if (trailing.kind !== "eof") {
-            this.report.warning(
-                "unsupported",
-                MULTIPLE_GRAPHS_CODE,
-                `content after the closing brace of the graph (${describeToken(trailing)}) was not read; one graph per input`,
-                { line: trailing.line },
-            );
-        }
+        return lexer.next();
     }
 
     /**

package/src/formats/gexf/exporter.ts

@@ -290,6 +290,14 @@ function planExport(
                 );
             }
         }
+        if (graphExtraText(snapshot, "timestamp") !== null) {
+            note(
+                GEXF_LOSS.TIMESTAMP_AS_INTERVAL,
+                "the graph timestamp is written as a closed interval (start = end); GEXF 1.2 has no timestamp representation",
+                null,
+                null,
+            );
+        }
         if (edgeRoles.kind !== null) {
             note(
                 GEXF_LOSS.KIND_DROPPED,
@@ -1647,18 +1655,41 @@ function graphStart(snapshot: GraphSnapshot, plan: ExportPlan): string {
     if (plan.version === "1.3" && plan.timeRepresentation !== null) {
         attrs += ` timerepresentation="${plan.timeRepresentation}"`;
     }
-    const gexfExtra = meta.extra.gexf;
-    if (typeof gexfExtra === "object" && gexfExtra !== null) {
-        for (const key of ["start", "end", "timestamp"]) {
-            const value = (gexfExtra as Record<string, unknown>)[key];
-            if (typeof value === "string") {
-                attrs += ` ${key}="${escapeXmlAttribute(value)}"`;
-            }
+    const timestamp = graphExtraText(snapshot, "timestamp");
+    const header: Record<string, string | null> = {
+        start: graphExtraText(snapshot, "start"),
+        end: graphExtraText(snapshot, "end"),
+        timestamp,
+    };
+    if (plan.version === "1.2" && timestamp !== null) {
+        // GEXF 1.2 has no timestamp: the graph's becomes a closed interval, as an element's does
+        header.start ??= timestamp;
+        header.end ??= timestamp;
+        header.timestamp = null;
+    }
+    for (const [key, value] of Object.entries(header)) {
+        if (value !== null) {
+            attrs += ` ${key}="${escapeXmlAttribute(value)}"`;
         }
     }
     return `  <graph${attrs}>\n`;
 }
 
+/**
+ * A graph header value the GEXF importer recorded in `meta.extra.gexf` (start, end, timestamp).
+ * @param snapshot - the snapshot
+ * @param key - the attribute name
+ * @returns the text, or null when absent
+ */
+function graphExtraText(snapshot: GraphSnapshot, key: string): string | null {
+    const gexfExtra = snapshot.meta.extra.gexf;
+    if (typeof gexfExtra !== "object" || gexfExtra === null) {
+        return null;
+    }
+    const value = (gexfExtra as Record<string, unknown>)[key];
+    return typeof value === "string" ? value : null;
+}
+
 /** The GEXF exporter (design section 8.5); `capabilities` describes the default 1.3 output. */
 export const gexfExporter: GraphExporter<GexfExportOptions> = Object.freeze({
     format: GEXF_FORMAT,

package/src/formats/gexf/importer.ts

@@ -74,7 +74,14 @@ import {
 import { ImportReportBuilder, type IssueLocation } from "../../common/report.js";
 import { parseTimeText, type TemporalValue, type TimeFormat, timeTextCompanion } from "../../common/temporal.js";
 import { isWeightField, parseWeightText } from "../../common/weights.js";
-import { isWhitespace, localName, tokenizeXml, type XmlHandler, XmlSyntaxError } from "../../common/xml.js";
+import {
+    isWhitespace,
+    localName,
+    tokenizeXml,
+    xmlDeclaredEncoding,
+    type XmlHandler,
+    XmlSyntaxError,
+} from "../../common/xml.js";
 import { type CommonImportOptions, type GraphImporter, type ImportInput, type ImportReport } from "../../types.js";
 import {
     EDGE_DECLS,
@@ -2318,7 +2325,10 @@ export const gexfImporter: GraphImporter<GexfImportOptions> = Object.freeze({
         reportUnusedOptions(options, report, USED_OPTIONS);
         const reader = new GexfReader(sink, report, resolved, viz);
         try {
-            await tokenizeXml(textChunks(input, report, resolved), reader);
+            await tokenizeXml(
+                textChunks(input, report, { ...resolved, declaredEncoding: xmlDeclaredEncoding }),
+                reader,
+            );
         } catch (err) {
             if (err instanceof XmlSyntaxError) {
                 report.fail(XML_SYNTAX_CODE, err.message, { line: err.line });

package/src/formats/gexf/index.ts

@@ -13,7 +13,9 @@ import {
     DIRECTION_REFUSED_CODE,
     DUPLICATE_EDGE_ID_CODE,
     DUPLICATE_NODE_CODE,
+    ENCODING_FALLBACK_CODE,
     ID_MERGED_CODE,
+    INVALID_ENCODING_CODE,
     INVALID_UTF8_CODE,
     MISSING_ENDPOINT_CODE,
     MISSING_ID_CODE,
@@ -26,6 +28,7 @@ import {
     STRAY_TEXT_CODE,
     UNKNOWN_ATTR_TYPE_CODE,
     UNKNOWN_ELEMENT_CODE,
+    UNKNOWN_ENCODING_CODE,
     UNKNOWN_PARENT_CODE,
     XML_SYNTAX_CODE,
 } from "../../common/codes.js";
@@ -63,6 +66,12 @@ export const GEXF_ISSUE = Object.freeze({
     XML_SYNTAX: XML_SYNTAX_CODE,
     /** The input holds invalid UTF-8 (fatal). */
     INVALID_UTF8: INVALID_UTF8_CODE,
+    /** Invalid bytes in the encoding a BOM, a declaration or the encoding option chose (fatal). */
+    INVALID_ENCODING: INVALID_ENCODING_CODE,
+    /** Bytes that are not UTF-8 and declare no encoding were read as windows-1252. */
+    ENCODING_FALLBACK: ENCODING_FALLBACK_CODE,
+    /** A declared encoding the platform cannot decode was ignored. */
+    UNKNOWN_ENCODING: UNKNOWN_ENCODING_CODE,
     /** The root element is not `<gexf>` (fatal). */
     NOT_GEXF: NOT_GEXF_CODE,
     /** The document has no `<graph>` (fatal). */

package/src/formats/gml/importer.ts

@@ -39,6 +39,7 @@ import {
     DUPLICATE_NODE_CODE as SHARED_DUPLICATE_NODE_CODE,
     MISSING_ENDPOINT_CODE as SHARED_MISSING_ENDPOINT_CODE,
     MISSING_ID_CODE as SHARED_MISSING_ID_CODE,
+    MULTIPLE_GRAPHS_CODE,
     NO_GRAPH_CODE as SHARED_NO_GRAPH_CODE,
     PRECISION_CODE as SHARED_PRECISION_CODE,
     ROLE_TAKEN_CODE as SHARED_ROLE_TAKEN_CODE,
@@ -87,8 +88,8 @@ export interface GmlImportOptions {
 
 /** Issue code: the text holds no `graph [ ... ]` block. */
 export const NO_GRAPH_CODE = SHARED_NO_GRAPH_CODE;
-/** Issue code: the text holds more than one `graph [ ... ]` block (fatal; one network per file). */
-export const SECOND_GRAPH_CODE = "E_GML_SECOND_GRAPH";
+/** Issue code: the text holds more than one `graph [ ... ]` block; import() reads the first, importAll() every one. */
+export const SECOND_GRAPH_CODE = MULTIPLE_GRAPHS_CODE;
 /** Issue code: a node block has no `id` key. */
 export const MISSING_ID_CODE = SHARED_MISSING_ID_CODE;
 /** Issue code: a node block has no `label` key under `nodeIdFrom: "label"`. */
@@ -248,6 +249,9 @@ class GmlImport {
 
     private tokens: GmlTokens | null = null;
 
+    /** How many `graph [ ... ]` blocks the text holds (known after the scan). */
+    graphCount = 0;
+
     private resolver: DirectionResolver | null = null;
 
     private readonly nodeSchema = new Map<string, KeySchema>();
@@ -315,12 +319,14 @@ class GmlImport {
      * @param report - the report
      * @param options - the resolved common options
      * @param format - the format-specific options
+     * @param which - which `graph [ ... ]` block to read (0: the first)
      */
     constructor(
         sink: GraphSink,
         report: ImportReportBuilder,
         options: ResolvedImportOptions,
         format: GmlImportOptions | undefined,
+        private readonly which = 0,
     ) {
         this.sink = sink;
         this.report = report;
@@ -331,19 +337,11 @@ class GmlImport {
     }
 
     /**
-     * Run the import over a text.
-     * @param text - the whole GML text
+     * Run the import over the tokens of a text.
+     * @param tokens - the whole text, tokenized (tokenize())
      */
-    run(text: string): void {
-        const { report } = this;
-        try {
-            this.tokens = tokenizeGml(text);
-        } catch (err) {
-            if (err instanceof GmlSyntaxError) {
-                report.fail(err.code, err.message, { line: err.line });
-            }
-            throw err;
-        }
+    run(tokens: GmlTokens): void {
+        this.tokens = tokens;
         this.scan();
         this.push();
     }
@@ -361,13 +359,10 @@ class GmlImport {
             const v = p + 1;
             const record = t.kind[v] === TOKEN_OPEN;
             if (key === "graph" && record) {
-                if (this.graphOpen >= 0) {
-                    this.report.fail(SECOND_GRAPH_CODE, "the input contains more than one graph", {
-                        line: t.line[p],
-                    });
+                if (this.graphCount++ === this.which) {
+                    this.graphOpen = v;
+                    this.scanGraph(v);
                 }
-                this.graphOpen = v;
-                this.scanGraph(v);
             } else if (key === "Creator" && !record && this.creatorToken < 0) {
                 this.creatorToken = v;
             } else if (key === "Version" && !record && this.versionToken < 0) {
@@ -1581,11 +1576,69 @@ export const gmlImporter: GraphImporter<GmlImportOptions> = Object.freeze({
         const report = new ImportReportBuilder("gml", resolved.errorLimit);
         reportSinkOptions(sink, options, report);
         reportUnusedOptions(options, report, USED_OPTIONS);
-        const text = await readText(input, report, resolved);
+        const tokens = tokenize(await readText(input, report, resolved), report);
         throwIfAborted(resolved.signal);
-        new GmlImport(sink, report, resolved, options).run(text);
+        const gml = new GmlImport(sink, report, resolved, options);
+        gml.run(tokens);
+        if (gml.graphCount > 1) {
+            report.warning(
+                "unsupported",
+                SECOND_GRAPH_CODE,
+                `the input holds ${gml.graphCount - 1} more graph block(s) after the first; import() reads the first, importAll() reads every one`,
+            );
+        }
         // an abort raised during the last few elements (after the last periodic check) still rejects
         throwIfAborted(resolved.signal);
         return report.finish();
     },
+
+    /**
+     * Read every `graph [ ... ]` block of a GML text, each into its own sink; the top-level keys
+     * (Creator, Version, ...) apply to each.
+     * @param input - the text, bytes or stream
+     * @param sinkFor - the sink of the graph with this index, called before its first push
+     * @param options - format-specific and common options
+     * @returns one report per graph block
+     */
+    async importAll(
+        input: ImportInput,
+        sinkFor: (index: number) => GraphSink,
+        options?: GmlImportOptions & CommonImportOptions,
+    ): Promise<ImportReport[]> {
+        const resolved = resolveImportOptions(options, FORMAT_DEFAULTS);
+        const first = new ImportReportBuilder("gml", resolved.errorLimit);
+        reportUnusedOptions(options, first, USED_OPTIONS);
+        const tokens = tokenize(await readText(input, first, resolved), first);
+        const reports: ImportReport[] = [];
+        let count = 1;
+        for (let i = 0; i < count; i++) {
+            throwIfAborted(resolved.signal);
+            const report = i === 0 ? first : new ImportReportBuilder("gml", resolved.errorLimit);
+            const sink = sinkFor(i);
+            reportSinkOptions(sink, options, report);
+            const gml = new GmlImport(sink, report, resolved, options, i);
+            gml.run(tokens);
+            count = gml.graphCount;
+            reports.push(report.finish());
+        }
+        throwIfAborted(resolved.signal);
+        return reports;
+    },
 });
+
+/**
+ * Tokenize a GML text; a syntax error is fatal.
+ * @param text - the whole text
+ * @param report - where the syntax error is recorded
+ * @returns the tokens
+ */
+function tokenize(text: string, report: ImportReportBuilder): GmlTokens {
+    try {
+        return tokenizeGml(text);
+    } catch (err) {
+        if (err instanceof GmlSyntaxError) {
+            report.fail(err.code, err.message, { line: err.line });
+        }
+        throw err;
+    }
+}