@graphty/graph-io 0.3.25 → 0.3.26

package/dist/src/registry.d.ts

@@ -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;
@@ -7,62 +7,183 @@
  * objects directly (the subpath exports) and this module never touches their sink.
  */
 import { type FreezeOptions, type FreezeReport, type GraphBuilderOptions, type GraphSnapshot } from "@graphty/graph-format";
-import { type SniffHints, type SniffResult } from "./sniff.js";
-import { type CommonExportOptions, type CommonImportOptions, type GraphChoiceOptions, type GraphExporter, type GraphImporter, type GraphListing, type ImportInput, type ImportReport, type LossNote } from "./types.js";
-/** The issue code of an input whose format no registered importer recognises. */
+import { type FormatName, type SniffHints, type SniffResult } from "./sniff.js";
+import { type CommonExportOptions, type CommonImportOptions, type ExportCapabilities, type GraphChoiceOptions, type GraphExporter, type GraphImporter, type GraphListing, type ImportInput, type ImportReport, type LossNote } 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 declare const UNKNOWN_FORMAT_CODE = "E_UNKNOWN_FORMAT";
-/** The builder options importGraph() accepts beyond the ones the common import options seed. */
+/**
+ * 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 declare const SNIFF_FAILED_CODE = "W_SNIFF_FAILED";
+/**
+ * The `builder` option of importGraph(): settings for building the graph that the common import
+ * options do not cover. `weighted`: "auto" (the default) gives the graph weights when any edge has
+ * one, true always does (every weight 1 when the file has none), false never does. `expectedNodes`
+ * and `expectedEdges`: how many nodes and edges to make room for up front, which saves time on a
+ * large file whose size you know.
+ * @category Loading
+ */
 export type BuilderSeed = Omit<GraphBuilderOptions, "directed" | "addMissingNodes" | "duplicateEdges" | "selfLoops" | "weightDtype">;
 /**
- * The options of importGraph(): the common import options (which also seed the registry's
- * builder, design section 8.4), the format choice and the hints sniffing uses, the builder and
- * freeze options, and any format-specific option (`delimiter`, `dialect`, ...) passed through to
- * the importer unchanged. `graphIndex` / `graphName` choose one graph of an input that holds
- * several, for the formats that list their graphs.
+ * The options of importGraph(), importAllGraphs(), listGraphs() and loadFromFile(): the common
+ * import options, the format and the hints used to detect it, the graph to read from a file that
+ * holds several, and any format-specific option (`delimiter`, `dialect`, ...), which reaches the
+ * importer unchanged.
+ * @category Loading
  */
 export interface ImportGraphOptions extends CommonImportOptions, GraphChoiceOptions {
-    /** The format name, or "auto" (default) to sniff it from the filename, MIME type and content. */
-    readonly format?: string | undefined;
-    /** The file name or path the input came from, a hint for sniffing. */
+    /**
+     * The format to read the input as ("graphml", "csv", ...; `listFormats()` names them all), or
+     * "auto" to work it out from `filename`, `mimeType` and the first bytes of the input. Name it to
+     * be strict: detection reads a file graph-io cannot place as the closest format it recognizes.
+     * @defaultValue "auto"
+     */
+    readonly format?: FormatName | "auto" | undefined;
+    /**
+     * The file name or full path the input came from; only its extension is used, as a format hint.
+     * loadFromUrl() takes it from the URL and loadFromFile() from a File's name when you do not pass
+     * it.
+     */
     readonly filename?: string | null | undefined;
-    /** The MIME type the input was served as, a hint for sniffing. */
+    /**
+     * The MIME type the input was served as, a format hint. loadFromUrl() takes it from the
+     * response's Content-Type and loadFromFile() from the Blob's `type` when you do not pass it.
+     */
     readonly mimeType?: string | null | undefined;
-    /** Builder options the common options do not cover (`weighted`, `expectedNodes`, ...). */
+    /**
+     * Settings for building the graph: `weighted` ("auto", true or false: whether the graph gets
+     * weights), `expectedNodes` and `expectedEdges` (room to make up front for a large file). Most
+     * programs never set it.
+     */
     readonly builder?: BuilderSeed | undefined;
-    /** Options of the freeze that follows the import. */
+    /**
+     * Settings for the last step of an import, which turns what was read into the snapshot:
+     * `label` (a name for debugging, read back as `snapshot.label`), `prepare` (views of the graph
+     * to compute up front, such as `["reverse"]`), `checksum` (record checksums, which
+     * `snapshot.validate({ checksum: true })` compares later to catch changed memory) and `profile` (record how long each step took, in `result.freeze.timings`). Most
+     * programs never set it.
+     */
     readonly freeze?: FreezeOptions | undefined;
     /**
-     * The most attribute slots that hold no value the import may allocate before it stops with
-     * E_TOO_MANY_EMPTY_CELLS. Every attribute is a column with one slot per node (or edge), so a file
+     * The most attribute slots that hold no value the import may allocate before it stops with an
+     * ImportError whose `issue.code` is E_TOO_MANY_EMPTY_CELLS. Every attribute is a column with one slot per node (or edge), so a file
      * whose nodes each have a differently named attribute would otherwise need nodes x attributes
-     * memory. Default 2^24 (16,777,216); Infinity turns the check off. Dense files are never stopped.
+     * memory. Infinity turns the check off. Files whose elements mostly share their attributes are
+     * never stopped.
+     * @defaultValue 16777216
      */
     readonly maxEmptyCells?: number | undefined;
     /** Format-specific options, passed to the importer as they are. */
     readonly [formatOption: string]: unknown;
 }
-/** What importGraph() returns (design section 8.4). */
+/**
+ * What importGraph(), loadFromUrl() and loadFromFile() return.
+ * @category Loading
+ */
 export interface ImportGraphResult {
-    /** The format the input was read as. */
+    /** The format the input was read as ("graphml", ...). */
     readonly format: string;
-    /** The sniff that chose the importer, or null when the caller named the format. */
+    /**
+     * How the format was detected (the candidate's `confidence` and what matched), or null when you
+     * named the format. Most callers can ignore it. For the JSON dialect that was read, call
+     * `jsonShapeOf(snapshot)` from `@graphty/graph-io/json`.
+     */
     readonly sniff: SniffResult | null;
-    /** The frozen snapshot. */
+    /**
+     * The graph. `snapshot.nodeCount`, `snapshot.edgeCount`, attribute tables and so on come from
+     * the `@graphty/graph-format` package.
+     */
     readonly snapshot: GraphSnapshot;
-    /** The importer's report. */
+    /**
+     * What happened during the import. `errorCount` counts skipped elements (see `errorLimit`,
+     * default 100); `warningCount` counts elements that were kept but changed; `issues` lists both;
+     * `counts.skippedNodes` / `counts.skippedEdges` say how much is missing from `snapshot`.
+     */
     readonly report: ImportReport;
-    /** The freeze report (design section 6.6). */
+    /**
+     * What the last step of the import did to the graph: `mergedEdges` (parallel edges merged by
+     * `duplicateEdges`), `droppedSelfLoops` (removed by `selfLoops: "drop"`), and `timings` when you
+     * passed `freeze: { profile: true }`. Both counts are also reported as warnings, so most callers
+     * can ignore it. It is not enumerable, so `console.log(result)` and `{ ...result }` leave it out.
+     */
     readonly freeze: FreezeReport;
 }
-/** The options of exportGraph(): the common export options plus any format-specific option, passed through. */
+/**
+ * Options for loadFromUrl(): everything importGraph() accepts, plus the fetch request settings.
+ * @example
+ * ```ts
+ * await loadFromUrl("/api/graph.csv", { request: { headers: { Authorization: token } }, delimiter: ";" });
+ * ```
+ * @category Loading
+ */
+export interface LoadFromUrlOptions extends ImportGraphOptions {
+    /**
+     * Passed to fetch() as its second argument: headers, credentials, mode and so on. If you set
+     * `signal` in the import options and not here, the same signal also cancels the download.
+     */
+    readonly request?: RequestInit | undefined;
+}
+/**
+ * Options for downloadGraph(): the export options plus the name of the saved file.
+ * @example
+ * ```ts
+ * await downloadGraph(snapshot, "graphml", { filename: "network.graphml" });
+ * ```
+ * @category Saving
+ */
+export interface DownloadGraphOptions extends ExportGraphOptions {
+    /**
+     * The file name the browser saves as. The default is "graph" plus the first entry of the
+     * format's `extensions` ("graph.graphml"), or "graph.<format>" when it lists none.
+     * @defaultValue "graph" plus the format's extension
+     */
+    readonly filename?: string | undefined;
+}
+/**
+ * One format the registry can read, write or both.
+ * @category Formats and detection
+ */
+export interface FormatInfo {
+    /** The name you pass as `format`: "graphml", "gexf", "csv", "pajek", ... */
+    readonly format: string;
+    /**
+     * File extensions with the leading dot, most common first (".graphml", ".net"). Empty only for a
+     * custom format that declares none.
+     */
+    readonly extensions: readonly string[];
+    /** MIME types, most specific first. Empty when the format declares none. */
+    readonly mimeTypes: readonly string[];
+    /** Whether loadFromUrl(), loadFromFile() and importGraph() can read it. */
+    readonly canImport: boolean;
+    /** Whether the export functions can write it. */
+    readonly canExport: boolean;
+    /**
+     * What the format can store exactly, or null when it cannot be written. The fields are
+     * mixedDirection, multiEdges, selfLoops, edgeIds, idCharset, dtypes, components, lists, json,
+     * defaults, options, hierarchy, temporal, graphAttributes, positions and viz (each documented on
+     * ExportCapabilities). checkExport() tells you where a particular graph goes beyond this.
+     */
+    readonly capabilities: ExportCapabilities | null;
+}
+/**
+ * The options of exportGraph(): the common export options plus any format-specific option, passed through.
+ * @category Saving
+ */
 export interface ExportGraphOptions extends CommonExportOptions {
     /** Format-specific options, passed to the exporter as they are. */
     readonly [formatOption: string]: unknown;
 }
 /**
  * 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 declare class FormatRegistry {
     private readonly importerMap;
@@ -85,25 +206,25 @@ export declare class FormatRegistry {
      * @param format - the format name
      * @returns the importer; E_UNSUPPORTED when none is registered
      */
-    importer(format: string): GraphImporter;
+    importer(format: FormatName): GraphImporter;
     /**
      * The exporter of a format.
      * @param format - the format name
      * @returns the exporter; E_UNSUPPORTED when none is registered
      */
-    exporter(format: string): GraphExporter;
+    exporter(format: FormatName): GraphExporter;
     /**
      * Whether an importer is registered for a format.
      * @param format - the format name
      * @returns true when importer(format) would succeed
      */
-    hasImporter(format: string): boolean;
+    hasImporter(format: FormatName): boolean;
     /**
      * Whether an exporter is registered for a format.
      * @param format - the format name
      * @returns true when exporter(format) would succeed
      */
-    hasExporter(format: string): boolean;
+    hasExporter(format: FormatName): boolean;
     /**
      * Every registered importer, in registration order.
      * @returns the importers
@@ -120,10 +241,10 @@ export declare class FormatRegistry {
      */
     formats(): readonly string[];
     /**
-     * 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: SniffHints): readonly SniffResult[];
     /**
@@ -133,27 +254,46 @@ export declare class FormatRegistry {
      */
     sniff(hints: SniffHints): SniffResult | 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
      */
-    importGraph(input: ImportInput, options?: ImportGraphOptions): Promise<ImportGraphResult>;
+    importGraph(input: ImportInput, options?: ImportGraphOptions | CommonImportOptions): Promise<ImportGraphResult>;
+    /**
+     * 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
+     */
+    loadFromUrl(url: string | URL, options?: LoadFromUrlOptions | CommonImportOptions): Promise<ImportGraphResult>;
+    /**
+     * 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: Blob, options?: ImportGraphOptions | CommonImportOptions): Promise<ImportGraphResult>;
     /**
      * 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
      */
-    importAllGraphs(input: ImportInput, options?: ImportGraphOptions): Promise<ImportGraphResult[]>;
+    importAllGraphs(input: ImportInput, options?: ImportGraphOptions | CommonImportOptions): Promise<ImportGraphResult[]>;
+    /**
+     * 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
+     */
+    private readAll;
     /**
      * The graphs of an input that can hold several, without importing them (a Cytoscape session's
      * networks, a JGF `graphs` array), so a caller can offer a choice and then pass `graphIndex`
@@ -163,22 +303,31 @@ export declare class FormatRegistry {
      * @returns one listing per graph, in document order; null when the format's importer does not
      * list its graphs (importGraph() then reads the first)
      */
-    listGraphs(input: ImportInput, options?: ImportGraphOptions): Promise<readonly GraphListing[] | null>;
+    listGraphs(input: ImportInput, options?: ImportGraphOptions | CommonImportOptions): Promise<readonly GraphListing[] | null>;
     /**
      * 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)
      */
     private choose;
     /**
-     * Write a snapshot in a format, as UTF-8 chunks (design section 8.5).
+     * 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
+     */
+    private refuseUndetected;
+    /**
+     * 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
      * @returns the encoded chunks
      */
-    exportGraph(snapshot: GraphSnapshot, format: string, options?: ExportGraphOptions): AsyncIterable<Uint8Array>;
+    exportGraph(snapshot: GraphSnapshot, format: FormatName, options?: ExportGraphOptions | CommonExportOptions): AsyncIterable<Uint8Array>;
     /**
      * Write a snapshot in a format, as one string.
      * @param snapshot - the snapshot
@@ -186,7 +335,25 @@ export declare class FormatRegistry {
      * @param options - the exporter's common and format-specific options
      * @returns the whole document
      */
-    exportGraphToString(snapshot: GraphSnapshot, format: string, options?: ExportGraphOptions): Promise<string>;
+    exportGraphToString(snapshot: GraphSnapshot, format: FormatName, options?: ExportGraphOptions | CommonExportOptions): Promise<string>;
+    /**
+     * 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: GraphSnapshot, format: FormatName, options?: ExportGraphOptions | CommonExportOptions): Promise<Uint8Array>;
+    /**
+     * 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
+     */
+    exportGraphToBlob(snapshot: GraphSnapshot, format: FormatName, options?: ExportGraphOptions | CommonExportOptions): Promise<Blob>;
     /**
      * What exporting a snapshot in a format would lose, without writing anything.
      * @param snapshot - the snapshot
@@ -194,65 +361,284 @@ export declare class FormatRegistry {
      * @param options - the exporter's common and format-specific options
      * @returns the loss notes, empty when the export is exact
      */
-    checkExport(snapshot: GraphSnapshot, format: string, options?: ExportGraphOptions): readonly LossNote[];
+    checkExport(snapshot: GraphSnapshot, format: FormatName, options?: ExportGraphOptions | CommonExportOptions): readonly LossNote[];
+    /**
+     * 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
+     */
+    private unknownOptions;
+    /**
+     * 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
+     */
+    downloadGraph(snapshot: GraphSnapshot, format: FormatName, options?: DownloadGraphOptions | CommonExportOptions): Promise<void>;
+    /**
+     * Every format this registry can read or write, in registration order; see the top-level
+     * listFormats().
+     * @returns one entry per format
+     */
+    listFormats(): readonly FormatInfo[];
 }
 /**
- * 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 declare function createRegistry(): FormatRegistry;
-/** The default registry: every built-in format. */
+/**
+ * The default registry: every built-in format.
+ * @category Formats and detection
+ */
 export declare const registry: FormatRegistry;
 /**
- * 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
+ * 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 declare function importGraph(input: ImportInput, options?: ImportGraphOptions | CommonImportOptions): Promise<ImportGraphResult>;
+/**
+ * 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 declare function importAllGraphs(input: ImportInput, options?: ImportGraphOptions | CommonImportOptions): Promise<ImportGraphResult[]>;
+/**
+ * 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 declare function listGraphs(input: ImportInput, options?: ImportGraphOptions | CommonImportOptions): Promise<readonly GraphListing[] | null>;
+/**
+ * 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 declare function exportGraph(snapshot: GraphSnapshot, format: FormatName, options?: ExportGraphOptions | CommonExportOptions): AsyncIterable<Uint8Array>;
+/**
+ * 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 declare function exportGraphToString(snapshot: GraphSnapshot, format: FormatName, options?: ExportGraphOptions | CommonExportOptions): Promise<string>;
+/**
+ * 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 declare function checkExport(snapshot: GraphSnapshot, format: FormatName, options?: ExportGraphOptions | CommonExportOptions): readonly LossNote[];
+/**
+ * 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 declare function importGraph(input: ImportInput, options?: ImportGraphOptions): Promise<ImportGraphResult>;
+export declare function loadFromUrl(url: string | URL, options?: LoadFromUrlOptions | CommonImportOptions): Promise<ImportGraphResult>;
 /**
- * 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
+ * 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 declare function importAllGraphs(input: ImportInput, options?: ImportGraphOptions): Promise<ImportGraphResult[]>;
+export declare function loadFromFile(file: Blob, options?: ImportGraphOptions | CommonImportOptions): Promise<ImportGraphResult>;
 /**
- * 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
+ * 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 declare function listGraphs(input: ImportInput, options?: ImportGraphOptions): Promise<readonly GraphListing[] | null>;
+export declare function exportGraphToBytes(snapshot: GraphSnapshot, format: FormatName, options?: ExportGraphOptions | CommonExportOptions): Promise<Uint8Array>;
 /**
- * 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 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 declare function exportGraph(snapshot: GraphSnapshot, format: string, options?: ExportGraphOptions): AsyncIterable<Uint8Array>;
+export declare function exportGraphToBlob(snapshot: GraphSnapshot, format: FormatName, options?: ExportGraphOptions | CommonExportOptions): Promise<Blob>;
 /**
- * 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
+ * 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 declare function exportGraphToString(snapshot: GraphSnapshot, format: string, options?: ExportGraphOptions): Promise<string>;
+export declare function downloadGraph(snapshot: GraphSnapshot, format: FormatName, options?: DownloadGraphOptions | CommonExportOptions): Promise<void>;
 /**
- * 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
+ * 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 declare function checkExport(snapshot: GraphSnapshot, format: string, options?: ExportGraphOptions): readonly LossNote[];
+export declare function listFormats(): readonly FormatInfo[];
 /**
- * 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
+ * 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 declare function sniff(hints: SniffHints): SniffResult | null;
 //# sourceMappingURL=registry.d.ts.map