@graphty/graph-io 0.3.25 → 0.3.26

package/dist/src/registry.js

@@ -1,5 +1,5 @@
 /**
- * The importer / exporter registry (design sections 8.2 and 8.4): the eight built-in formats
+ * The importer / exporter registry: the built-in formats
  * registered by name, `sniff()` over them, and the two conveniences for callers who do not own a
  * sink: `importGraph()` sniffs the format, creates a builder seeded from the common options
  * (`directed: true` as a placeholder; the importer sets the real value), imports and freezes;
@@ -8,24 +8,71 @@
  */
 import { GraphFormatError, } from "@graphty/graph-format";
 import { CellBudgetBuilder, maxEmptyCellsOption } from "./common/cell-budget.js";
-import { throwIfAborted } from "./common/input.js";
-import { ImportReportBuilder } from "./common/report.js";
+import { EDGES_MERGED_CODE, EMPTY_INPUT_CODE, FETCH_CODE, OPTION_IGNORED_CODE, SELF_LOOPS_DROPPED_CODE, UNKNOWN_OPTION_CODE, WEIGHT_NOT_FOUND_CODE, } from "./common/codes.js";
+import { abortable, foreignKind, lockReader, normalizeInput, throwIfAborted } from "./common/input.js";
+import { chooseGraph, resolveImportOptions } from "./common/options.js";
+import { agree, plural } from "./common/plural.js";
+import { ImportReportBuilder, isAbortError, messageOf } from "./common/report.js";
+import { collectBytes } from "./common/writer.js";
 import { csvExporter, csvImporter } from "./formats/csv/index.js";
-import { cxImporter } from "./formats/cx/index.js";
+import { cxExporter, cxImporter } from "./formats/cx/index.js";
 import { cx2Exporter, cx2Importer } from "./formats/cx2/index.js";
-import { cysImporter } from "./formats/cys/index.js";
+import { cysExporter, cysImporter } from "./formats/cys/index.js";
 import { dotExporter, dotImporter } from "./formats/dot/index.js";
 import { gexfExporter, gexfImporter } from "./formats/gexf/index.js";
 import { gmlExporter, gmlImporter } from "./formats/gml/index.js";
 import { graphmlExporter, graphmlImporter } from "./formats/graphml/index.js";
 import { jsonExporter, jsonImporter } from "./formats/json/index.js";
 import { neo4jExporter, neo4jImporter } from "./formats/neo4j/index.js";
-import { oboImporter } from "./formats/obo/index.js";
+import { oboExporter, oboImporter } from "./formats/obo/index.js";
 import { pajekExporter, pajekImporter } from "./formats/pajek/index.js";
 import { xgmmlExporter, xgmmlImporter } from "./formats/xgmml/index.js";
 import { rankFormats, SNIFF_HEAD_BYTES } from "./sniff.js";
-/** The issue code of an input whose format no registered importer recognises. */
+import { ImportError, } from "./types.js";
+/**
+ * The input is in no format graph-io can read (or none of the formats you registered, for your own FormatRegistry).
+ * Pass `format` when you know what the file is.
+ * @category Issue and loss codes
+ */
 export const UNKNOWN_FORMAT_CODE = "E_UNKNOWN_FORMAT";
+/**
+ * Registered importer whose sniff() threw while the format was being chosen; that importer was treated as not
+ * recognizing the input (a defect in that importer).
+ * @category Issue and loss codes
+ */
+export const SNIFF_FAILED_CODE = "W_SNIFF_FAILED";
+/**
+ * The options the load and save functions take themselves: the common import and export options and the functions'
+ * own. With the formats' own `options` lists, these are the names a load or a save knows.
+ */
+const FUNCTION_OPTIONS = new Set([
+    "addMissingNodes",
+    "builder",
+    "defaultDirected",
+    "duplicateEdges",
+    "encoding",
+    "errorLimit",
+    "filename",
+    "format",
+    "freeze",
+    "graphIndex",
+    "graphName",
+    "hyperedges",
+    "ids",
+    "long",
+    "maxEmptyCells",
+    "mimeType",
+    "nodeIdFrom",
+    "onMixedDirection",
+    "onProgress",
+    "request",
+    "restoreMangledIds",
+    "sanitizeIds",
+    "selfLoops",
+    "signal",
+    "weightDtype",
+    "weightFrom",
+]);
 /** The keys of ImportGraphOptions that belong to the registry, never to an importer. */
 const REGISTRY_KEYS = new Set([
     "format",
@@ -37,8 +84,9 @@ const REGISTRY_KEYS = new Set([
 ]);
 /**
  * A registry of importers and exporters by format name. Registration order is the tie-break
- * order of sniffing (design section 8.2); the default registry lists the built-in formats in the
+ * order of sniffing; the default registry lists the built-in formats in the
  * order of GRAPH_FORMATS.
+ * @category Formats and detection
  */
 export class FormatRegistry {
     constructor() {
@@ -126,10 +174,10 @@ export class FormatRegistry {
         return [...new Set([...this.importerMap.keys(), ...this.exporterMap.keys()])];
     }
     /**
-     * Rank the registered importers for an input (design section 8.2; the successor of
-     * graphty-element's detectFormat()).
-     * @param hints - the filename, MIME type and / or head of the input
-     * @returns the candidates, best first; empty when nothing matches
+     * Every format that could be the input, best first, from the same hints as sniff(): use it to
+     * offer the user a choice when the best guess is not certain.
+     * @param hints - `{ filename, mimeType, head }`, any of them
+     * @returns the candidates, best first; empty when no format claims the input
      */
     sniffAll(hints) {
         return rankFormats(hints, this.importerMap.values());
@@ -144,40 +192,116 @@ export class FormatRegistry {
         return ranked.length > 0 ? ranked[0] : null;
     }
     /**
-     * Read an input into a fresh builder and freeze it (design section 8.4: for callers who do not
-     * own a sink). The format is the one named in the options, else sniffed from the filename,
-     * the MIME type and the first bytes of the content; the builder is seeded from the common
-     * options with `directed: true` as a placeholder that the importer overrides from the file.
-     * An input holding several graphs yields the first, with a warning naming how many were
-     * skipped; importAllGraphs() returns every one.
+     * Read a graph from a string, bytes or a stream. The format is the one you name in `format`,
+     * else it is detected from `filename`, `mimeType` and the first bytes of the content. From an
+     * input that holds several graphs, it reads the one `graphIndex` or `graphName` chooses, else
+     * the first, with a W_MULTIPLE_GRAPHS warning; importAllGraphs() returns every one.
      * @param input - the text, bytes, stream or chunks to read
      * @param options - the format, hints, common and format-specific import options
-     * @returns the snapshot, the import report and the freeze report
+     * @returns the graph (`snapshot`), the format it was read as, and the import report
      */
     async importGraph(input, options = {}) {
-        const chosen = await this.choose(input, options);
-        const builder = seededBuilder(options, chosen.importer.format);
+        const opts = options;
+        const picked = await this.choose(input, opts);
+        const unknown = this.unknownOptions(opts).map((name) => Object.freeze({
+            category: "unsupported",
+            severity: "warning",
+            code: UNKNOWN_OPTION_CODE,
+            message: unknownOptionText(name),
+            line: null,
+            element: name,
+        }));
+        const chosen = unknown.length === 0 ? picked : { ...picked, warnings: [...picked.warnings, ...unknown] };
+        const { importer } = chosen;
+        if ((opts.graphIndex !== undefined || opts.graphName !== undefined) &&
+            importer.importAll !== undefined &&
+            importer.listGraphs === undefined) {
+            // an importer that reads several graphs but does not choose among them itself (DOT, GML,
+            // Pajek): read them all and return the chosen one, so the choice is never ignored
+            const all = await this.readAll(chosen, opts);
+            const names = all.map((r) => r.snapshot.meta.name);
+            return all[chooseGraph(names, opts, new ImportReportBuilder(importer.format, 0))];
+        }
+        let builder;
         let report;
         try {
-            report = await chosen.importer.import(chosen.source, builder, importerOptions(options));
+            builder = seededBuilder(opts, chosen.importer.format);
+            report = await chosen.importer.import(chosen.source, builder, importerOptions(opts));
         }
         catch (err) {
             await chosen.peeked?.close();
-            throw err;
+            throw chosen.sniff === null ? notReadableAs(err, importer.format, opts.filename) : err;
+        }
+        return result(chosen, builder, report, opts);
+    }
+    /**
+     * Fetch a graph file from a URL and load it; see the top-level loadFromUrl() for the full
+     * description.
+     * @param url - an absolute URL, or in a browser one relative to the page
+     * @param options - import options, plus `request` for fetch
+     * @returns the graph, the format it was read as, and the import report
+     */
+    async loadFromUrl(url, options = {}) {
+        const opts = options;
+        const { request, ...rest } = opts;
+        const signal = request?.signal ?? rest.signal ?? null;
+        const method = request?.method ?? "GET";
+        const where = `${method} ${String(url)}`;
+        let response;
+        try {
+            response = await fetch(url, { signal: rest.signal, ...request });
+        }
+        catch (err) {
+            if (signal?.aborted === true || isAbortError(err)) {
+                throw err;
+            }
+            return fetchFailed(rest, url, `${where} failed: ${fetchErrorText(url, err)}`, null, err);
+        }
+        if (!response.ok) {
+            await response.body?.cancel().catch(() => undefined);
+            const status = `${String(response.status)} ${response.statusText}`.trim();
+            return fetchFailed(rest, url, `${where} failed: ${status}`, response.status, null);
         }
-        return result(chosen, builder, report, options);
+        return this.importGraph(response.body ?? new Uint8Array(0), {
+            ...rest,
+            filename: rest.filename ?? urlFilename(url),
+            mimeType: rest.mimeType ?? response.headers.get("content-type"),
+        });
+    }
+    /**
+     * Load a graph from a File or Blob; see the top-level loadFromFile() for the full description.
+     * @param file - the File or Blob to read
+     * @param options - the same options as importGraph()
+     * @returns the graph, the format it was read as, and the import report
+     */
+    loadFromFile(file, options = {}) {
+        const opts = options;
+        const { name } = file;
+        return this.importGraph(file.stream(), {
+            ...opts,
+            filename: opts.filename ?? (typeof name === "string" ? name : null),
+            mimeType: opts.mimeType ?? (file.type === "" ? null : file.type),
+        });
     }
     /**
      * Read every graph of an input (a DOT file with several graphs, a Pajek project with several
-     * networks, a JGF document with a `graphs` array), each into its own fresh builder, frozen.
-     * A format whose importer has no importAll() holds one graph per input, so the result has one
-     * entry. Options, sniffing and the builder seed are those of importGraph().
+     * networks, a JGF document with a `graphs` array), each as its own snapshot. A format that holds
+     * one graph per file gives one result. Options and detection are those of importGraph().
      * @param input - the text, bytes, stream or chunks to read
      * @param options - the format, hints, common and format-specific import options
      * @returns one result per graph, in document order
      */
     async importAllGraphs(input, options = {}) {
-        const chosen = await this.choose(input, options);
+        const opts = options;
+        return this.readAll(await this.choose(input, opts), opts);
+    }
+    /**
+     * Read every graph of an input with the chosen importer.
+     * @param chosen - the importer and the input to hand it
+     * @param options - the importGraph options
+     * @returns one result per graph, in document order
+     */
+    async readAll(chosen, options) {
         const { importer } = chosen;
         const builders = [];
         let reports;
@@ -196,9 +320,16 @@ export class FormatRegistry {
         }
         catch (err) {
             await chosen.peeked?.close();
-            throw err;
+            throw inGraph(chosen.sniff === null ? notReadableAs(err, importer.format, options.filename) : err, builders.length - 1);
         }
-        return reports.map((report, i) => result(chosen, builders[i], report, options));
+        return reports.map((report, i) => {
+            try {
+                return result(chosen, builders[i], report, options);
+            }
+            catch (err) {
+                throw inGraph(err, i);
+            }
+        });
     }
     /**
      * The graphs of an input that can hold several, without importing them (a Cytoscape session's
@@ -210,11 +341,12 @@ export class FormatRegistry {
      * list its graphs (importGraph() then reads the first)
      */
     async listGraphs(input, options = {}) {
-        const chosen = await this.choose(input, options);
+        const opts = options;
+        const chosen = await this.choose(input, opts);
         try {
             return chosen.importer.listGraphs === undefined
                 ? null
-                : await chosen.importer.listGraphs(chosen.source, importerOptions(options));
+                : await chosen.importer.listGraphs(chosen.source, importerOptions(opts));
         }
         finally {
             await chosen.peeked?.close();
@@ -222,25 +354,69 @@ export class FormatRegistry {
     }
     /**
      * The importer for an input: the named format, or the sniffed one.
-     * @param input - the input
+     * @param rawInput - the input as the caller passed it
      * @param options - the importGraph options
      * @returns the importer, the sniff, and the input to read (replayed for a stream)
      */
-    async choose(input, options) {
+    async choose(rawInput, options) {
+        const input = normalizeInput(rawInput);
         const requested = options.format ?? "auto";
         if (requested !== "auto") {
-            return { importer: this.importer(requested), sniff: null, source: input, peeked: null };
+            return { importer: this.importer(requested), sniff: null, source: input, peeked: null, warnings: [] };
+        }
+        // the options are checked before the input is touched, so a bad option never leaves a
+        // peeked stream locked; the importer resolves them again with its own defaults
+        const common = resolveImportOptions(options, { ids: "keep", defaultDirected: true, weightFrom: null });
+        maxEmptyCellsOption(options.maxEmptyCells);
+        const peeked = await peekHead(input, SNIFF_HEAD_BYTES, common.signal);
+        // the head is sniffed as the importer will read it: in the caller's encoding when given
+        const head = common.encoding !== null && peeked.head instanceof Uint8Array
+            ? new TextDecoder(common.encoding).decode(peeked.head, { stream: true })
+            : peeked.head;
+        let sniff;
+        const failures = new ImportReportBuilder("unknown", 0);
+        const warnings = [];
+        try {
+            const hints = { filename: options.filename, mimeType: options.mimeType, head };
+            const ranked = rankFormats(hints, this.importerMap.values(), (format, err) => {
+                warnings.push(failures.warning("unsupported", SNIFF_FAILED_CODE, `the ${format} importer's sniff() threw (${messageOf(err)}); it was treated as not recognizing the input`, { element: format }));
+            });
+            sniff = ranked.length > 0 ? ranked[0] : null;
+        }
+        catch (err) {
+            await peeked.close();
+            throw err;
+        }
+        // a known non-graph file is refused whatever its name says, unless an importer claims its
+        // content (a Cytoscape session is a zip); an HTML page always (the XML sniffers would
+        // otherwise claim it by its markup)
+        const foreign = foreignKind(peeked.head);
+        const claimed = sniff !== null && sniff.content > 0 && !(foreign?.startsWith("an HTML") ?? false);
+        if (sniff === null || (foreign !== null && !claimed)) {
+            await peeked.close();
+            return this.refuseUndetected(failures, head, foreign, options);
         }
-        const peeked = await peekHead(input, SNIFF_HEAD_BYTES, options.signal ?? null);
-        const sniff = this.sniff({ filename: options.filename, mimeType: options.mimeType, head: peeked.head });
-        if (sniff === null) {
-            const report = new ImportReportBuilder("unknown", 0);
-            return report.fail(UNKNOWN_FORMAT_CODE, `no registered importer recognises the input${describeHints(options)}; pass the format explicitly`, undefined, { formats: this.formats() });
+        return { importer: this.importer(sniff.format), sniff, source: peeked.input, peeked, warnings };
+    }
+    /**
+     * Refuse an input no importer recognizes: empty, or not in a known graph format.
+     * @param failures - the report the error is recorded in
+     * @param head - the head, as sniffed
+     * @param foreign - what known non-graph file the head is, or null
+     * @param options - the importGraph options
+     * @returns never: always throws
+     */
+    refuseUndetected(failures, head, foreign, options) {
+        const text = typeof head === "string" ? head : new TextDecoder().decode(head ?? new Uint8Array(0));
+        if (text.trim() === "" && text.length < SNIFF_HEAD_BYTES) {
+            // nothing to detect: say the input is empty, as a named format would
+            return failures.fail(EMPTY_INPUT_CODE, text === "" ? "the input is empty" : "the input holds only whitespace");
         }
-        return { importer: this.importer(sniff.format), sniff, source: peeked.input, peeked };
+        const what = foreign === null ? "" : `: it is ${foreign}`;
+        return failures.fail(UNKNOWN_FORMAT_CODE, `the input is not in a graph format graph-io recognizes${describeHints(options)}${what}; if you know its format, pass it as the format option`, undefined, { formats: this.formats() });
     }
     /**
-     * Write a snapshot in a format, as UTF-8 chunks (design section 8.5).
+     * Write a snapshot in a format, as UTF-8 chunks.
      * @param snapshot - the snapshot
      * @param format - the format name
      * @param options - the exporter's common and format-specific options
@@ -259,6 +435,33 @@ export class FormatRegistry {
     async exportGraphToString(snapshot, format, options) {
         return this.exporter(format).exportToString(snapshot, options);
     }
+    /**
+     * Write a snapshot in a format as one buffer of UTF-8 bytes; see the top-level
+     * exportGraphToBytes().
+     * @param snapshot - the graph to write
+     * @param format - a format name where `canExport` is true
+     * @param options - sanitizeIds, onMixedDirection and the format's own options
+     * @returns the encoded file
+     */
+    exportGraphToBytes(snapshot, format, options) {
+        return collectBytes(this.exportGraph(snapshot, format, options));
+    }
+    /**
+     * Write a snapshot in a format as a Blob typed with the format's first MIME type; see the
+     * top-level exportGraphToBlob().
+     * @param snapshot - the graph to write
+     * @param format - a format name where `canExport` is true
+     * @param options - sanitizeIds, onMixedDirection and the format's own options
+     * @returns the file as a Blob
+     */
+    async exportGraphToBlob(snapshot, format, options) {
+        const parts = [];
+        for await (const chunk of this.exportGraph(snapshot, format, options)) {
+            parts.push(chunk);
+        }
+        const info = this.listFormats().find((f) => f.format === format);
+        return new Blob(parts, { type: info?.mimeTypes[0] ?? "application/octet-stream" });
+    }
     /**
      * What exporting a snapshot in a format would lose, without writing anything.
      * @param snapshot - the snapshot
@@ -267,12 +470,94 @@ export class FormatRegistry {
      * @returns the loss notes, empty when the export is exact
      */
     checkExport(snapshot, format, options) {
-        return this.exporter(format).check(snapshot, options);
+        const notes = this.exporter(format).check(snapshot, options);
+        const unknown = this.unknownOptions(options);
+        if (unknown.length === 0) {
+            return notes;
+        }
+        return Object.freeze([
+            ...notes,
+            ...unknown.map((name) => Object.freeze({
+                code: UNKNOWN_OPTION_CODE,
+                message: unknownOptionText(name),
+                column: null,
+                count: null,
+            })),
+        ]);
+    }
+    /**
+     * The option names no registered format and no load or save function takes (misspellings), or none while a
+     * registered format does not list its options.
+     * @param options - the caller's options
+     * @returns the unknown names
+     */
+    unknownOptions(options) {
+        if (options === null || options === undefined) {
+            return [];
+        }
+        const known = new Set(FUNCTION_OPTIONS);
+        for (const plugin of [...this.importerMap.values(), ...this.exporterMap.values()]) {
+            if (plugin.options === undefined) {
+                return [];
+            }
+            for (const name of plugin.options) {
+                known.add(name);
+            }
+        }
+        return Object.entries(options)
+            .filter(([name, value]) => value !== undefined && !known.has(name))
+            .map(([name]) => name);
+    }
+    /**
+     * Browser only: write a graph in a format and have the browser save it as a file; see the
+     * top-level downloadGraph(). Use this method on a registry from createRegistry() to download
+     * without bundling every built-in format.
+     * @param snapshot - the graph to write
+     * @param format - a format name from listFormats() where `canExport` is true
+     * @param options - the export options, plus `filename`
+     * @returns resolves once the download has been handed to the browser
+     */
+    async downloadGraph(snapshot, format, options = {}) {
+        if (typeof document === "undefined") {
+            throw new GraphFormatError("E_UNSUPPORTED", "downloadGraph() needs a browser document; use exportGraphToBytes() and write the bytes yourself");
+        }
+        const { filename, ...rest } = options;
+        const blob = await this.exportGraphToBlob(snapshot, format, rest);
+        const extension = this.listFormats().find((f) => f.format === format)?.extensions[0] ?? `.${format}`;
+        const href = URL.createObjectURL(blob);
+        const anchor = document.createElement("a");
+        anchor.href = href;
+        anchor.download = filename ?? `graph${extension}`;
+        anchor.click();
+        // Safari cancels the download when the URL is revoked in the same task
+        setTimeout(() => {
+            URL.revokeObjectURL(href);
+        }, 0);
+    }
+    /**
+     * Every format this registry can read or write, in registration order; see the top-level
+     * listFormats().
+     * @returns one entry per format
+     */
+    listFormats() {
+        return this.formats().map((format) => {
+            const importer = this.importerMap.get(format);
+            const exporter = this.exporterMap.get(format);
+            return Object.freeze({
+                format,
+                extensions: importer?.extensions ?? exporter?.extensions ?? [],
+                mimeTypes: importer?.mimeTypes ?? exporter?.mimeTypes ?? [],
+                canImport: importer !== undefined,
+                canExport: exporter !== undefined,
+                capabilities: exporter?.capabilities ?? null,
+            });
+        });
     }
 }
 /**
- * A registry holding the eight built-in importers and exporters in the order of GRAPH_FORMATS.
+ * A new registry holding every built-in importer and exporter, in the order of GRAPH_FORMATS.
  * @returns a new registry
+ * @category Formats and detection
  */
 export function createRegistry() {
     return new FormatRegistry()
@@ -297,77 +582,355 @@ export function createRegistry() {
         .registerImporter(cx2Importer)
         .registerExporter(cx2Exporter)
         .registerImporter(cxImporter)
+        .registerExporter(cxExporter)
         .registerImporter(oboImporter)
-        .registerImporter(cysImporter);
+        .registerExporter(oboExporter)
+        .registerImporter(cysImporter)
+        .registerExporter(cysExporter);
 }
-/** The default registry: every built-in format. */
-export const registry = createRegistry();
 /**
- * Read an input into a fresh builder and freeze it, through the default registry (design section
- * 8.4: `importGraph(input, { format?, ...options })`).
- * @param input - the text, bytes, stream or chunks to read
- * @param options - the format, hints, common and format-specific import options
- * @returns the snapshot, the import report and the freeze report
+ * The default registry: every built-in format.
+ * @category Formats and detection
+ */
+export const registry = /* @__PURE__ */ createRegistry();
+/**
+ * Read a graph from a string, bytes or a stream. The format is the one you name in `format`, else
+ * it is detected from `filename`, `mimeType` and the first bytes; an input that matches no format
+ * fails with E_UNKNOWN_FORMAT. From a file that holds several graphs it reads the one `graphIndex`
+ * or `graphName` chooses, else the first, with a W_MULTIPLE_GRAPHS warning. For a File or Blob use
+ * loadFromFile(), for a URL loadFromUrl().
+ * @param input - the whole text, the bytes (a Uint8Array or a Node Buffer), a ReadableStream of
+ *   bytes, or an async iterable of text or byte chunks (a Node read stream)
+ * @param options - the format, format hints, the options every importer takes and the format's own
+ *   options
+ * @returns the graph (`snapshot`), the format it was read as, and the import report
+ * @throws ImportError when the input could not be read; `err.issue?.code` says why
+ * @throws GraphFormatError with code E_UNSUPPORTED for a `format` no importer is registered for, or
+ *   an option value that is not allowed (`err.details.option` names it)
+ * @throws the signal's reason when `signal` aborts
+ * @category Loading
  */
 export function importGraph(input, options) {
     return registry.importGraph(input, options);
 }
 /**
- * Read every graph of an input, each into its own frozen snapshot, through the default registry.
- * @param input - the text, bytes, stream or chunks to read
- * @param options - the format, hints, common and format-specific import options
- * @returns one result per graph, in document order
+ * Read every graph of a file that can hold several (DOT, GML, a Pajek project, a JSON Graph Format
+ * or OBO Graphs document, CX, XGMML, a Cytoscape session). A format that holds one graph per file
+ * gives one result. Options and errors are the same as importGraph()'s.
+ * @param input - the text, bytes or stream to read
+ * @param options - the same options as importGraph()
+ * @returns one result per graph, in file order
+ * @category Loading
  */
 export function importAllGraphs(input, options) {
     return registry.importAllGraphs(input, options);
 }
 /**
- * The graphs of an input that can hold several, through the default registry.
- * @param input - the text, bytes, stream or chunks to read
- * @param options - the format, hints, common and format-specific import options
- * @returns one listing per graph, in document order; null when the format does not list its graphs
+ * List the graphs of a file without reading them: each one's `index`, `name`, and node and edge
+ * counts when the file states them. Pass the index or name to importGraph() as `graphIndex` or
+ * `graphName`. The counts come from the file and can differ from what an import reads, for example
+ * when the import adds edges the listing does not count. JSON, CX, XGMML and Cytoscape sessions can
+ * list their graphs; for DOT, GML and Pajek it returns null, and importAllGraphs() is the way to see
+ * them.
+ * @param input - the text, bytes or stream to read
+ * @param options - the same options as importGraph()
+ * @returns one listing per graph, in file order; null when the format cannot list its graphs
+ * @category Loading
  */
 export function listGraphs(input, options) {
     return registry.listGraphs(input, options);
 }
 /**
- * Write a snapshot in a format through the default registry, as UTF-8 chunks.
- * @param snapshot - the snapshot
- * @param format - the format name
- * @param options - the exporter's common and format-specific options
- * @returns the encoded chunks
+ * Write a graph in a format as a stream of UTF-8 byte chunks, for a graph too large to hold as one
+ * file in memory. In Node, pipe it to a file with `pipeline(exportGraph(...), createWriteStream(path))`.
+ * Options and errors are the same as exportGraphToBytes()'s.
+ * @param snapshot - the graph to write
+ * @param format - a format name from listFormats() where `canExport` is true
+ * @param options - sanitizeIds, onMixedDirection and the format's own options
+ * @returns the file's bytes, chunk by chunk
+ * @category Saving
  */
 export function exportGraph(snapshot, format, options) {
     return registry.exportGraph(snapshot, format, options);
 }
 /**
- * Write a snapshot in a format through the default registry, as one string.
- * @param snapshot - the snapshot
- * @param format - the format name
- * @param options - the exporter's common and format-specific options
- * @returns the whole document
+ * Write a graph in a format and return the file as one string. A binary format (a Cytoscape
+ * session) cannot be a string and fails with E_UNSUPPORTED; use exportGraphToBytes() for it. Options
+ * and errors are the same as exportGraphToBytes()'s.
+ * @param snapshot - the graph to write
+ * @param format - a format name from listFormats() where `canExport` is true
+ * @param options - sanitizeIds, onMixedDirection and the format's own options
+ * @returns the whole file
+ * @category Saving
  */
 export async function exportGraphToString(snapshot, format, options) {
     return registry.exportGraphToString(snapshot, format, options);
 }
 /**
- * What exporting a snapshot in a format would lose, through the default registry.
- * @param snapshot - the snapshot
- * @param format - the format name
- * @param options - the exporter's common and format-specific options
- * @returns the loss notes, empty when the export is exact
+ * What saving a graph in a format would lose, without writing anything. Pass the same options you
+ * will pass to the save. Each note has a stable `code`: "E_" means the save would throw, "W_" means
+ * the file is written but that part does not read back the same. An empty array means the file
+ * reads back as the same graph. Runs synchronously.
+ * @param snapshot - the graph to check
+ * @param format - a format name from listFormats() where `canExport` is true
+ * @param options - the options you will save with
+ * @returns the loss notes, empty when the save is exact
+ * @throws GraphFormatError with code E_UNSUPPORTED when no exporter is registered for `format`, or
+ *   when an option value is not allowed (`err.details.option` names it)
+ * @category Saving
  */
 export function checkExport(snapshot, format, options) {
     return registry.checkExport(snapshot, format, options);
 }
 /**
- * Sniff an input's format through the default registry.
- * @param hints - the filename, MIME type and / or head of the input
- * @returns the best candidate, or null when no built-in importer claims it
+ * Fetch a graph file from a URL and load it. The file is streamed into the importer as it
+ * downloads, so a large file is not held in memory twice. When you do not name a `format`, it is
+ * worked out from the URL's file name, the response's Content-Type and the first bytes of the
+ * file. Your own `filename` or `mimeType` option takes the place of the hint from the URL or the
+ * response. Every other option goes to importGraph() unchanged, including format-specific ones
+ * such as `delimiter` or `dialect`, and `graphIndex` / `graphName` for files that hold several
+ * graphs. The result is the same as importGraph()'s. A successful load can still have skipped
+ * elements; check `report.errorCount` and `report.warningCount`, or pass `errorLimit: 0` to make
+ * the first error fatal. Works wherever fetch exists: browsers, Node 18 and later, Deno, Bun and
+ * workers.
+ * @param url - an absolute URL, or in a browser one relative to the page
+ * @param options - import options, plus `request` for fetch
+ * @returns the graph, the format it was read as, and the import report
+ * @throws ImportError when the file could not be loaded; `err.issue?.code` is "E_FETCH" for a
+ *   network failure, a CORS refusal or a status outside 200-299 (`err.details.url`,
+ *   `err.details.status` -- null for a network failure -- and `err.details.cause`, fetch's own
+ *   error), "E_UNKNOWN_FORMAT" when no format recognizes the file (pass `format`), or the code of
+ *   the parse error
+ * @throws GraphFormatError with code E_UNSUPPORTED when `format` names no registered importer
+ * @throws the signal's reason when `signal` aborts
+ * @example
+ * ```ts
+ * import { GraphFormatError, loadFromUrl } from "@graphty/graph-io";
+ *
+ * try {
+ *     const { snapshot, format } = await loadFromUrl("https://example.com/data/karate.gml");
+ *     console.log(`${format}: ${snapshot.nodeCount} nodes, ${snapshot.edgeCount} edges`);
+ * } catch (err) {
+ *     if (err instanceof GraphFormatError) {
+ *         console.error(err.message);
+ *     } else {
+ *         throw err;
+ *     }
+ * }
+ * ```
+ * @category Loading
+ */
+export function loadFromUrl(url, options) {
+    return registry.loadFromUrl(url, options);
+}
+/**
+ * Load a graph from a File or Blob: a file the user picked in an `<input type="file">`, a file
+ * dropped on the page, a Blob you built, or in Node a Blob from `fs.openAsBlob(path)`. The content
+ * is streamed into the importer. A File's `name` and the Blob's `type` are used as format hints
+ * unless you pass `filename` or `mimeType` yourself. Options, result and errors are the same as
+ * loadFromUrl()'s, without E_FETCH.
+ * @param file - the File or Blob to read
+ * @param options - the same options as importGraph()
+ * @returns the graph, the format it was read as, and the import report
+ * @throws ImportError when the file could not be loaded (`err.issue?.code` E_UNKNOWN_FORMAT or a parse error)
+ * @throws GraphFormatError with code E_UNSUPPORTED when `format` names no registered importer
+ * @throws the signal's reason when `signal` aborts
+ * @example
+ * ```ts
+ * input.addEventListener("change", async () => {
+ *     const file = input.files?.[0];
+ *     if (file) {
+ *         const { snapshot, report } = await loadFromFile(file);
+ *         console.log(`${snapshot.nodeCount} nodes, ${report.errorCount} skipped`);
+ *     }
+ * });
+ * ```
+ * @category Loading
+ */
+export function loadFromFile(file, options) {
+    return registry.loadFromFile(file, options);
+}
+/**
+ * Write a graph in a format and return the whole file as UTF-8 bytes, ready for fs.writeFile, a
+ * fetch body or a zip entry. Prefer this over exportGraphToString() when the result goes to a file
+ * or the network. To stream a very large graph, use exportGraph(). To find out beforehand what the
+ * file will not keep, call checkExport() with the same format and the same options object: every
+ * "E_" note it returns makes this call throw, and every "W_" note describes a loss this call
+ * accepts. Most "E_" notes go away with `sanitizeIds: "mangle"` (rewrite ids the format cannot
+ * hold) or `onMixedDirection: "directed"` / `"undirected"`. The format's own options (the CSV
+ * `table` and `dialect`, the GEXF `version`, ...) go in the same object.
+ * @param snapshot - the graph to write
+ * @param format - a format name from listFormats() where `canExport` is true
+ * @param options - sanitizeIds, onMixedDirection and the format's own options
+ * @returns the encoded file
+ * @throws GraphFormatError with code E_UNSUPPORTED when no exporter is registered for `format`
+ * @throws GraphFormatError when the graph cannot be written in this format under these options
+ *   (checkExport() returns an "E_" note for the same call). The thrown code names the kind of
+ *   failure rather than the note: E_INVALID_ID for ids (the E_ID_CHARSET and E_ID_TEXT_COLLISION
+ *   notes), E_DIRECTED for direction (E_MIXED_DIRECTION), and E_COLUMN_TYPE or E_UNSUPPORTED for a
+ *   value the format cannot write; each note's entry on the codes page says which
+ * @throws GraphFormatError with code E_UNSUPPORTED for an option value that is not allowed
+ *   (`err.details.option` names it)
+ * @example
+ * ```ts
+ * import { writeFile } from "node:fs/promises";
+ *
+ * await writeFile("out.gexf", await exportGraphToBytes(snapshot, "gexf"));
+ * ```
+ * @category Saving
+ */
+export function exportGraphToBytes(snapshot, format, options) {
+    return registry.exportGraphToBytes(snapshot, format, options);
+}
+/**
+ * Write a graph in a format and return it as a Blob, for uploading with fetch or FormData or for
+ * offering as a download. The Blob's `type` is the first entry of the format's `mimeTypes` in
+ * listFormats(), or application/octet-stream when the format lists none. The exporter's chunks
+ * are kept as they are and never joined into one string. Options and errors are the same as
+ * exportGraphToBytes().
+ * @param snapshot - the graph to write
+ * @param format - a format name from listFormats() where `canExport` is true
+ * @param options - sanitizeIds, onMixedDirection and the format's own options
+ * @returns the file as a Blob
+ * @throws the same errors as exportGraphToBytes()
+ * @example
+ * ```ts
+ * const body = new FormData();
+ * body.append("file", await exportGraphToBlob(snapshot, "graphml"), "graph.graphml");
+ * await fetch("/api/graphs", { method: "POST", body });
+ * ```
+ * @category Saving
+ */
+export function exportGraphToBlob(snapshot, format, options) {
+    return registry.exportGraphToBlob(snapshot, format, options);
+}
+/**
+ * Browser only: write a graph in a format and have the browser save it as a file, the same as
+ * clicking a download link. Call it from a click handler; awaiting other work first is fine. The
+ * promise resolves once the file has been handed to the browser. There is no way to learn
+ * whether the user then canceled the save. Calling it where there is no `document` (Node, a
+ * worker) throws instead of silently doing nothing; importing it is safe everywhere. Formats you
+ * registered with `registry.registerExporter()` can be downloaded too.
+ * @param snapshot - the graph to write
+ * @param format - a format name from listFormats() where `canExport` is true
+ * @param options - the export options, plus `filename`
+ * @returns resolves once the download has been handed to the browser
+ * @throws GraphFormatError with code E_UNSUPPORTED when called without a DOM `document`
+ * @throws the same errors as exportGraphToBytes()
+ * @example
+ * ```ts
+ * saveButton.addEventListener("click", () => {
+ *     void downloadGraph(snapshot, "graphml", { filename: "network.graphml" });
+ * });
+ * ```
+ * @category Saving
+ */
+export async function downloadGraph(snapshot, format, options = {}) {
+    return registry.downloadGraph(snapshot, format, options);
+}
+/**
+ * Every format the default registry can read or write, including any you registered yourself:
+ * the built-in formats in the order of GRAPH_FORMATS (the order format detection prefers them),
+ * then yours in registration order. Use it to fill a "Save as" menu (the entries with
+ * `canExport`), a file input's `accept` attribute (the `extensions` of the entries with
+ * `canImport`), or to pick the output format from a file name.
+ * @returns one entry per format
+ * @example
+ * ```ts
+ * input.accept = listFormats().filter((f) => f.canImport).flatMap((f) => f.extensions).join(",");
+ * const target = listFormats().find((f) => f.canExport && f.extensions.includes(extensionOf(path) ?? ""));
+ * ```
+ * @category Formats and detection
+ */
+export function listFormats() {
+    return registry.listFormats();
+}
+/**
+ * Detect a file's format without reading it, from what you know about it: a `filename` (only the
+ * extension counts), a `mimeType`, and `head`, the file's first bytes or characters (up to
+ * SNIFF_HEAD_BYTES; pass `bytes.subarray(0, SNIFF_HEAD_BYTES)`). It uses every format of the default
+ * registry, including the ones you registered. For every candidate, best first, call
+ * `registry.sniffAll(hints)`.
+ * @param hints - `{ filename, mimeType, head }`, any of them
+ * @returns the best candidate (`format`, `confidence` and what matched), or null when no format
+ *   claims the input
+ * @example
+ * ```ts
+ * sniff({ filename: "graph.xml", head: "<?xml version=\"1.0\"?><gexf" })?.format; // "gexf"
+ * ```
+ * @category Formats and detection
  */
 export function sniff(hints) {
     return registry.sniff(hints);
 }
+/**
+ * Abort a loadFromUrl() whose fetch failed with an E_FETCH ImportError.
+ * @param options - the import options (for the format name on the report)
+ * @param url - the URL
+ * @param message - the message
+ * @param status - the HTTP status, or null for a network failure
+ * @param cause - fetch's own error, or null
+ * @returns never; always throws
+ */
+function fetchFailed(options, url, message, status, cause) {
+    const format = options.format === undefined || options.format === "auto" ? "unknown" : options.format;
+    return new ImportReportBuilder(format, 0).fail(FETCH_CODE, message, undefined, { url: String(url), status, cause });
+}
+/**
+ * The error for an input refused by the format the caller named before any element was read: the
+ * parser's message ("line 1: text outside the root element") prefixed with the file and the format,
+ * since the likely cause is a file of another kind, not a damaged one.
+ * @param err - what the importer threw
+ * @param format - the format named in `format`
+ * @param filename - the file name hint, if any
+ * @returns the error to throw
+ */
+function notReadableAs(err, format, filename) {
+    if (!(err instanceof ImportError) ||
+        err.issue?.category !== "parse-error" ||
+        err.report.errorCount > 1 ||
+        err.report.counts.nodes + err.report.counts.edges > 0) {
+        return err;
+    }
+    const what = filename === undefined || filename === null ? "the input" : JSON.stringify(filename);
+    return new ImportError(`${what} could not be read as ${format}: ${err.message}`, err.report, err.details);
+}
+/**
+ * Why fetch() rejected, in words that point at the fix: a relative URL with no page to resolve it
+ * against (Node), a file: URL fetch() does not read, or a network error, which in a browser
+ * includes a CORS refusal.
+ * @param url - the URL as given
+ * @param err - what fetch() threw
+ * @returns the reason
+ */
+function fetchErrorText(url, err) {
+    let absolute = null;
+    try {
+        absolute = new URL(url);
+    }
+    catch {
+        // relative: resolvable only against a page's location
+    }
+    if (absolute === null && globalThis.location === undefined) {
+        return "a relative URL needs a web page to resolve against; outside a browser pass an absolute http(s) URL, or read a local file with loadFromFile() or importGraph()";
+    }
+    if (absolute?.protocol === "file:") {
+        return "fetch() cannot read file: URLs here; read a local file with loadFromFile() or importGraph()";
+    }
+    const cause = err?.cause?.message;
+    const detail = typeof cause === "string" && cause !== "" ? ` (${cause})` : "";
+    return `the server could not be reached, or (in a browser) it does not allow this page to read the file (CORS)${detail}`;
+}
+/**
+ * The last path segment of a URL, as a format hint.
+ * @param url - the URL, absolute or relative
+ * @returns the file name, or null when the path ends in "/"
+ */
+function urlFilename(url) {
+    const path = new URL(url, "http://localhost/").pathname;
+    const name = path.slice(path.lastIndexOf("/") + 1);
+    return name === "" ? null : name;
+}
 /**
  * The options handed to the importer: everything but the registry's own keys.
  * @param options - the importGraph options
@@ -391,6 +954,26 @@ function importerOptions(options) {
  */
 function seededBuilder(options, format) {
     const maxEmptyCells = maxEmptyCellsOption(options.maxEmptyCells);
+    try {
+        return newBuilder(options, format, maxEmptyCells);
+    }
+    catch (err) {
+        // the builder names a bad value by its field; report it as the option the caller passed
+        if (err instanceof GraphFormatError && err.code === "E_UNSUPPORTED" && typeof err.details.field === "string") {
+            const option = err.details.field;
+            throw new GraphFormatError("E_UNSUPPORTED", `option ${option}: ${JSON.stringify(err.details.found)} is not one of the values it takes`, { option, found: err.details.found });
+        }
+        throw err;
+    }
+}
+/**
+ * The builder of seededBuilder(), before its option errors are reworded.
+ * @param options - the importGraph options
+ * @param format - the format being read
+ * @param maxEmptyCells - the empty-cell budget
+ * @returns the builder
+ */
+function newBuilder(options, format, maxEmptyCells) {
     return new CellBudgetBuilder({
         weightDtype: options.weightDtype ?? "f64",
         ...options.builder,
@@ -400,6 +983,20 @@ function seededBuilder(options, format) {
         selfLoops: options.selfLoops ?? "keep",
     }, format, maxEmptyCells);
 }
+/**
+ * Name the graph an importAllGraphs() failure belongs to: the report is that graph's own, so the
+ * message is prefixed with its index and `details.graphIndex` set, for every graph including the
+ * first. Anything other than an ImportError raised while a graph was being read passes unchanged.
+ * @param err - the error thrown while reading or freezing a graph
+ * @param index - the index of that graph, -1 before the first graph began
+ * @returns the error to throw
+ */
+function inGraph(err, index) {
+    if (!(err instanceof ImportError) || index < 0) {
+        return err;
+    }
+    return new ImportError(`graph ${index}: ${err.message}`, err.report, { ...err.details, graphIndex: index });
+}
 /**
  * Freeze an imported builder into an importGraph result.
  * @param chosen - the importer and its sniff
@@ -409,15 +1006,125 @@ function seededBuilder(options, format) {
  * @returns the frozen result
  */
 function result(chosen, builder, report, options) {
-    const frozen = builder.freezeWithReport(options.freeze);
-    return Object.freeze({
+    let frozen;
+    try {
+        frozen = builder.freezeWithReport(options.freeze);
+    }
+    catch (err) {
+        throw freezeFailure(err, report);
+    }
+    const { warnings } = chosen;
+    const result = {
         format: chosen.importer.format,
         sniff: chosen.sniff,
         snapshot: frozen.snapshot,
-        report,
-        freeze: frozen.report,
+        report: withFreezeWarnings(weightNotFound(warnings.length === 0
+            ? report
+            : Object.freeze({
+                ...report,
+                issues: Object.freeze([...warnings, ...report.issues]),
+                warningCount: report.warningCount + warnings.length,
+            }), frozen.snapshot, options.weightFrom), frozen.report),
+    };
+    // not enumerable: it holds one entry per edge, and console.log(result) should show the graph, not that
+    Object.defineProperty(result, "freeze", { value: frozen.report, enumerable: false });
+    return Object.freeze(result);
+}
+/**
+ * The message of a W_UNKNOWN_OPTION warning or note.
+ * @param name - the option name
+ * @returns the message
+ */
+function unknownOptionText(name) {
+    return `option ${JSON.stringify(name)} is not an option of any format or of the load and save functions, so it has no effect; check its spelling`;
+}
+/**
+ * The import report with one W_WEIGHT_NOT_FOUND warning when the caller's `weightFrom` named an attribute that gave
+ * no edge a weight, so a name that misses (a shared options object read against GML's `value`) is not silent. A
+ * format that does not read `weightFrom` already reported it as W_OPTION_IGNORED.
+ * @param report - the import's report
+ * @param snapshot - the graph read
+ * @param weightFrom - the caller's option
+ * @returns the report, with the warning added when it applies
+ */
+function weightNotFound(report, snapshot, weightFrom) {
+    if (typeof weightFrom !== "string" ||
+        snapshot.edgeCount === 0 ||
+        snapshot.edgeList().weights !== null ||
+        report.issues.some((i) => i.code === OPTION_IGNORED_CODE && i.element === "weightFrom")) {
+        return report;
+    }
+    const issue = Object.freeze({
+        category: "missing-value",
+        severity: "warning",
+        code: WEIGHT_NOT_FOUND_CODE,
+        message: `weightFrom: ${JSON.stringify(weightFrom)} names no attribute an edge has a value for, so the graph has no weights`,
+        line: null,
+        element: "weightFrom",
+    });
+    return Object.freeze({
+        ...report,
+        issues: Object.freeze([...report.issues, issue]),
+        warningCount: report.warningCount + 1,
+    });
+}
+/**
+ * The import report with what the builder's policies changed while the graph was built: one
+ * W_EDGES_MERGED warning when `duplicateEdges` merged parallel edges (whatever told them apart, a
+ * relation or a label, is lost) and one W_SELF_LOOPS_DROPPED warning when `selfLoops: "drop"`
+ * removed self-loops, so nothing the caller's options removed goes unreported.
+ * @param report - the import's report
+ * @param freeze - the freeze report
+ * @returns the report, with the warnings added
+ */
+function withFreezeWarnings(report, freeze) {
+    const added = [];
+    const warn = (category, code, message) => {
+        added.push(Object.freeze({ category, severity: "warning", code, message, line: null, element: null }));
+    };
+    if (freeze.mergedEdges > 0) {
+        warn("merged", EDGES_MERGED_CODE, `${freeze.mergedEdges} parallel edge${plural(freeze.mergedEdges)} ${agree(freeze.mergedEdges, "was", "were")} merged into one edge per pair by the duplicateEdges policy; whatever told them apart (a relation, a label) is lost`);
+    }
+    if (freeze.droppedSelfLoops > 0) {
+        warn("validation-error", SELF_LOOPS_DROPPED_CODE, `${freeze.droppedSelfLoops} self-loop${plural(freeze.droppedSelfLoops)} ${agree(freeze.droppedSelfLoops, "was", "were")} removed by selfLoops: "drop"`);
+    }
+    if (added.length === 0) {
+        return report;
+    }
+    return Object.freeze({
+        ...report,
+        issues: Object.freeze([...report.issues, ...added]),
+        warningCount: report.warningCount + added.length,
     });
 }
+/**
+ * The ImportError of a freeze the builder refused (a `duplicateEdges: "error"` or `selfLoops:
+ * "error"` policy meeting a duplicate edge or a self-loop the file holds): the builder's code
+ * recorded as an error issue on the import's report, so the caller gets the report and the file's
+ * defect rather than a bare GraphFormatError.
+ * @param err - what freezeWithReport() threw
+ * @param report - the import's report
+ * @returns the error to throw (anything that is not a GraphFormatError, unchanged)
+ */
+function freezeFailure(err, report) {
+    if (!(err instanceof GraphFormatError) || err instanceof ImportError) {
+        return err;
+    }
+    const issue = Object.freeze({
+        category: "validation-error",
+        severity: "error",
+        code: err.code,
+        message: err.message,
+        line: null,
+        element: null,
+    });
+    const failed = Object.freeze({
+        ...report,
+        issues: Object.freeze([...report.issues, issue]),
+        errorCount: report.errorCount + 1,
+    });
+    return new ImportError(`the graph cannot be frozen: ${err.message}`, failed, { code: err.code, ...err.details });
+}
 /**
  * The E_UNSUPPORTED error of a format name nothing is registered under.
  * @param kind - importer or exporter
@@ -463,7 +1170,7 @@ async function peekHead(input, bytes, signal) {
     }
     throwIfAborted(signal);
     const source = typeof input.getReader === "function"
-        ? readerIterator(input)
+        ? readerIterator(input, signal)
         : input[Symbol.asyncIterator]();
     const buffered = [];
     let size = 0;
@@ -565,19 +1272,31 @@ function replay(buffered, source, finished) {
     };
 }
 /**
- * An async iterator over a ReadableStream's chunks that cancels the stream when closed early.
+ * An async iterator over a ReadableStream's chunks that cancels the stream (with the signal's
+ * reason) when closed early or when the signal fires during a read, and releases the reader when
+ * the stream ends or errors.
  * @param stream - the stream
+ * @param signal - the cancellation signal, or null
  * @returns the iterator
  */
-function readerIterator(stream) {
-    const reader = stream.getReader();
+function readerIterator(stream, signal) {
+    const reader = lockReader(stream);
     let done = false;
     return {
         async next() {
             if (done) {
                 return { done: true, value: undefined };
             }
-            const result = await reader.read();
+            let result;
+            try {
+                result = await abortable(reader.read(), signal);
+            }
+            catch (err) {
+                done = true;
+                await reader.cancel(signal?.reason).catch(() => undefined);
+                reader.releaseLock();
+                throw err;
+            }
             if (result.done) {
                 done = true;
                 reader.releaseLock();
@@ -588,7 +1307,7 @@ function readerIterator(stream) {
         async return() {
             if (!done) {
                 done = true;
-                await reader.cancel().catch(() => undefined);
+                await reader.cancel(signal?.reason).catch(() => undefined);
                 reader.releaseLock();
             }
             return { done: true, value: undefined };