@graphty/graph-io 0.3.25 → 0.3.26

package/src/formats/xgmml/importer.ts

@@ -17,12 +17,14 @@ import { GraphFormatError, type GraphSink } from "@graphty/graph-format";
 import { textChunks, throwIfAborted } from "../../common/input.js";
 import {
     chooseGraph,
+    graphChosen,
     type ImportFormatDefaults,
     reportSinkOptions,
     reportUnusedOptions,
     type ResolvedImportOptions,
     resolveImportOptions,
 } from "../../common/options.js";
+import { agree, elementCount } from "../../common/plural.js";
 import { ImportReportBuilder } from "../../common/report.js";
 import { isWhitespace, tokenizeXml, xmlDeclaredEncoding, type XmlRepairs, XmlSyntaxError } from "../../common/xml.js";
 import {
@@ -45,24 +47,41 @@ import {
     type XgmmlSettings,
 } from "./emit.js";
 
-/** The format-specific options of the XGMML importer. */
-export interface XgmmlImportOptions extends GraphChoiceOptions {
+/**
+ * The format-specific options of the XGMML importer.
+ * @category Built-in formats
+ */
+export interface XgmmlImportOptions extends GraphChoiceOptions, CommonImportOptions {
     /**
-     * Resolve an edge endpoint that is missing or names no node through Cytoscape's
-     * `"source (interaction) target"` edge label, and fill a missing interaction from it. Default:
-     * on for files that use the Cytoscape (`cy`) namespace, off otherwise.
+     * Find an edge end that is missing, or names no node, from Cytoscape's `"source (interaction)
+     * target"` edge label, and fill a missing interaction from it. The default is on for files that
+     * use Cytoscape's (`cy`) namespace, off for others.
+     * @defaultValue on for Cytoscape files
      */
     labelAliases?: boolean | undefined;
     /**
-     * Decode Cytoscape's two-character `\n` and `\t` escapes in string values. Default: on for
-     * files that use the Cytoscape namespace, off otherwise.
+     * Decode Cytoscape's two-character `\n` and `\t` escapes in text values. The default is on for
+     * files that use Cytoscape's namespace, off for others.
+     * @defaultValue on for Cytoscape files
      */
     cytoscapeEscapes?: boolean | undefined;
-    /** Read an `&` not followed by `;` within 7 characters as `&` (warned per occurrence). Default false. */
+    /**
+     * Read an `&` that is not followed by `;` within 7 characters as `&`, with a warning for
+     * each, instead of failing on the invalid XML.
+     * @defaultValue false
+     */
     repairBareAmpersands?: boolean | undefined;
-    /** Join two surrogate character references into one character (warned per pair). Default false. */
+    /**
+     * Join two character references that each hold half of a character (`��`) into
+     * that character, with a warning for each pair, instead of failing.
+     * @defaultValue false
+     */
     pairSurrogateReferences?: boolean | undefined;
-    /** Where Cytoscape's z (a stacking order) goes: the `z` column (default) or the position. */
+    /**
+     * Where Cytoscape's `z` value (a drawing order, not a depth) goes: "column" keeps it as a node
+     * attribute named `z`; "position" makes it the third coordinate of the position.
+     * @defaultValue "column"
+     */
     zAs?: "column" | "position" | undefined;
 }
 
@@ -91,12 +110,6 @@ const USED_OPTIONS: ReadonlySet<keyof CommonImportOptions> = new Set<keyof Commo
     "encoding",
 ]);
 
-/** Bytes inspected by sniff(). */
-const SNIFF_BYTES = 4096;
-
-/** The head of the document kept for the DOCTYPE check. */
-const HEAD_CHARS = 2048;
-
 /** An XGMML DOCTYPE (Cytoscape's file filter tests the same). */
 const XGMML_DOCTYPE = /<!DOCTYPE\s+graph\s[^<>]*xgmml\.dtd/i;
 
@@ -105,6 +118,7 @@ const XGMML_DOCTYPE = /<!DOCTYPE\s+graph\s[^<>]*xgmml\.dtd/i;
  * @param options - the caller's options
  * @param cytoscape - whether the document uses the Cytoscape namespace
  * @returns the settings; E_UNSUPPORTED for a value of the wrong type
+ * @category Plugin helpers
  */
 export function resolveSettings(options: XgmmlImportOptions | undefined, cytoscape: boolean): XgmmlSettings {
     const zAs = options?.zAs ?? "column";
@@ -178,10 +192,10 @@ export async function parseXgmml(
             : undefined,
     };
     const parser = new XgmmlParser(report);
-    const seen = { head: "", content: false };
+    const seen = { content: false };
     try {
         await tokenizeXml(
-            watch(textChunks(input, report, { ...common, declaredEncoding: xmlDeclaredEncoding }), seen),
+            watch(textChunks(input, report, { ...common, declaredEncoding: xmlDeclaredEncoding, xml: true }), seen),
             parser,
             repairs,
         );
@@ -195,7 +209,7 @@ export async function parseXgmml(
         throw err;
     }
     const doc = parser.document();
-    if (!doc.xgmmlNamespace && !XGMML_DOCTYPE.test(seen.head)) {
+    if (!doc.xgmmlNamespace && !XGMML_DOCTYPE.test(doc.doctype ?? "")) {
         report.warning(
             "validation-error",
             XGMML_ISSUE.NO_NAMESPACE,
@@ -207,22 +221,18 @@ export async function parseXgmml(
 }
 
 /**
- * Pass text chunks through while keeping the head and noting non-whitespace content.
+ * Pass text chunks through while noting non-whitespace content.
  * @param chunks - the chunks
- * @param seen - where the head and the content flag are kept
- * @param seen.head - the first characters of the document
+ * @param seen - where the content flag is kept
  * @param seen.content - whether non-whitespace text was seen
  * @yields the chunks unchanged
  * @returns nothing
  */
 async function* watch(
     chunks: AsyncIterable<string>,
-    seen: { head: string; content: boolean },
+    seen: { content: boolean },
 ): AsyncGenerator<string, void, undefined> {
     for await (const chunk of chunks) {
-        if (seen.head.length < HEAD_CHARS) {
-            seen.head += chunk.slice(0, HEAD_CHARS - seen.head.length);
-        }
         seen.content ||= !isWhitespace(chunk);
         yield chunk;
     }
@@ -313,7 +323,7 @@ function reportRootOnly(prepared: Prepared): void {
         prepared.report.warning(
             "unsupported",
             XGMML_ISSUE.ROOT_ONLY_ELEMENTS,
-            `${nodes} node(s) and ${edges} edge(s) belong to no registered network (group meta-edges, collapsed group members) and were not read`,
+            `${elementCount(nodes, edges)} ${agree(nodes + edges, "belongs", "belong")} to none of the file's networks (group meta-edges or collapsed group members) and ${agree(nodes + edges, "was", "were")} not read`,
         );
     }
 }
@@ -336,11 +346,11 @@ async function importXgmml(
         options,
         prepared.report,
     );
-    if (prepared.graphs.length > 1) {
+    if (prepared.graphs.length > 1 && !graphChosen(options)) {
         prepared.report.warning(
             "unsupported",
             XGMML_ISSUE.MULTIPLE_GRAPHS,
-            `the session network document holds ${prepared.graphs.length} registered networks; ${prepared.graphs.length - 1} were not read (use importAll, graphIndex or graphName)`,
+            `the session network document holds ${prepared.graphs.length} registered networks; only the first is read (importAllGraphs() reads every one; graphIndex or graphName chooses one)`,
         );
     }
     return emitOne(prepared, prepared.graphs[index], sink);
@@ -359,12 +369,13 @@ async function importAllXgmml(
     sinkFor: (index: number) => GraphSink,
     options?: XgmmlImportOptions & CommonImportOptions,
 ): Promise<ImportReport[]> {
-    const bytes = await reread(input);
-    const first = await prepare(bytes, null, options);
+    const first = await prepare(input, null, options);
+    // the document is read once; every graph's report starts from what reading it recorded
+    const parsed = first.report.fork();
     const reports: ImportReport[] = [];
     for (let i = 0; i < first.graphs.length; i++) {
         const sink = sinkFor(i);
-        const prepared = i === 0 ? first : await prepare(bytes, null, options);
+        const prepared = i === 0 ? first : { ...first, report: parsed.fork() };
         reportSinkOptions(sink, options, prepared.report, true);
         reportUnusedOptions(options, prepared.report, USED_OPTIONS);
         reports.push(emitOne(prepared, prepared.graphs[i], sink));
@@ -404,57 +415,6 @@ function graphName(graph: GraphRec, doc: XgmmlDocument): string | null {
     return graph.label ?? (graph === doc.root ? (doc.rdf.title ?? null) : null) ?? graph.id ?? null;
 }
 
-/**
- * The input in a form that can be read more than once (a stream is read into bytes).
- * @param input - the input
- * @returns the same input when it is a string or bytes, else the collected bytes
- */
-async function reread(input: ImportInput): Promise<string | Uint8Array> {
-    if (typeof input === "string" || input instanceof Uint8Array) {
-        return input;
-    }
-    const parts: (string | Uint8Array)[] = [];
-    const iterable: AsyncIterable<string | Uint8Array> =
-        typeof (input as { getReader?: unknown }).getReader === "function"
-            ? streamIterable(input as ReadableStream<Uint8Array>)
-            : (input as AsyncIterable<string | Uint8Array>);
-    for await (const chunk of iterable) {
-        parts.push(chunk);
-    }
-    if (parts.every((p) => typeof p === "string")) {
-        return parts.join("");
-    }
-    const bytes = parts.map((p) => (typeof p === "string" ? new TextEncoder().encode(p) : p));
-    const out = new Uint8Array(bytes.reduce((n, b) => n + b.byteLength, 0));
-    let at = 0;
-    for (const b of bytes) {
-        out.set(b, at);
-        at += b.byteLength;
-    }
-    return out;
-}
-
-/**
- * A ReadableStream as an async iterable.
- * @param stream - the stream
- * @yields its chunks
- * @returns nothing
- */
-async function* streamIterable(stream: ReadableStream<Uint8Array>): AsyncGenerator<Uint8Array, void, undefined> {
-    const reader = stream.getReader();
-    try {
-        for (;;) {
-            const { done, value } = await reader.read();
-            if (done) {
-                return;
-            }
-            yield value;
-        }
-    } finally {
-        reader.releaseLock();
-    }
-}
-
 /**
  * Confidence that a head of bytes is XGMML: 0.95 for a root `graph` in the XGMML namespace or an
  * XGMML DOCTYPE (Cytoscape's file filter tests the same two things, and a session view file still
@@ -463,14 +423,22 @@ async function* streamIterable(stream: ReadableStream<Uint8Array>): AsyncGenerat
  * @returns the confidence
  */
 function sniffXgmml(head: Uint8Array): number {
-    const text = new TextDecoder("utf-8", { fatal: false }).decode(head.subarray(0, SNIFF_BYTES));
+    let encoding = "utf-8";
+    if ((head[0] === 0xff && head[1] === 0xfe) || (head[0] === 0x3c && head[1] === 0 && head[2] === 0x3f)) {
+        encoding = "utf-16le";
+    } else if ((head[0] === 0xfe && head[1] === 0xff) || (head[0] === 0 && head[1] === 0x3c && head[2] === 0)) {
+        encoding = "utf-16be";
+    }
+    const text = new TextDecoder(encoding, { fatal: false }).decode(head);
     if (!/^\uFEFF?\s*</.test(text)) {
         return 0;
     }
     if (XGMML_DOCTYPE.test(text)) {
         return 0.95;
     }
-    const root = /<(?!\?|!)([A-Za-z_][\w.-]*:)?([A-Za-z_][\w.-]*)[\s/>]/.exec(text.replace(/<!--[\s\S]*?-->/g, ""));
+    const root = /<(?![?!])([A-Za-z_][\w.-]*:)?([A-Za-z_][\w.-]*)[\s/>]/.exec(
+        text.replaceAll(/<!--[\s\S]*?(-->|$)/g, ""),
+    );
     if (root === null || root[2] !== "graph") {
         return 0;
     }
@@ -479,9 +447,19 @@ function sniffXgmml(head: Uint8Array): number {
     return tag.includes("http://www.cs.rpi.edu/XGMML") ? 0.95 : 0.5;
 }
 
-/** The XGMML importer. */
+/**
+ * The XGMML importer.
+ * @category Built-in formats
+ */
 export const xgmmlImporter: GraphImporter<XgmmlImportOptions> = Object.freeze({
     format: FORMAT,
+    options: Object.freeze([
+        "cytoscapeEscapes",
+        "labelAliases",
+        "pairSurrogateReferences",
+        "repairBareAmpersands",
+        "zAs",
+    ]),
     extensions: EXTENSIONS,
     mimeTypes: MIME_TYPES,
     sniff: sniffXgmml,

package/src/formats/xgmml/index.ts

@@ -1,6 +1,7 @@
 /**
  * The `@graphty/graph-io/xgmml` subpath: the XGMML importer and exporter, their option types and
  * their issue and loss-note code tables.
+ * @module @graphty/graph-io/xgmml
  */
 
 export { XGMML_ISSUE, XGMML_LOSS } from "./constants.js";

package/src/formats/xgmml/values.ts

@@ -7,7 +7,10 @@
 
 import { type AttRec } from "./document.js";
 
-/** The scalar kinds of a column, in widening order (string beats everything). */
+/**
+ * The scalar kinds of a column, in widening order (string beats everything).
+ * @category Plugin helpers
+ */
 export type ScalarKind = "bool" | "int" | "long" | "real" | "string";
 
 /** What one att declares. */
@@ -49,6 +52,7 @@ const XGMML_TYPES: Readonly<Record<string, DeclaredKind>> = {
  * whose name ends in `.SUID` is a long (Cytoscape keeps SUID references as Long).
  * @param att - the att
  * @returns the declared kind
+ * @category Plugin helpers
  */
 export function attType(att: AttRec): AttType {
     let kind: DeclaredKind | undefined;
@@ -77,6 +81,7 @@ export function attType(att: AttRec): AttType {
  * The scalar kind a list element type names (`cy:elementType`), or null when it names none.
  * @param text - the element type text
  * @returns the kind, or null
+ * @category Plugin helpers
  */
 export function elementKind(text: string | null): ScalarKind | null {
     if (text === null) {
@@ -92,6 +97,7 @@ export function elementKind(text: string | null): ScalarKind | null {
  * @param a - one kind
  * @param b - the other
  * @returns the kind both fit
+ * @category Plugin helpers
  */
 export function widenScalar(a: ScalarKind, b: ScalarKind): ScalarKind {
     if (a === b) {
@@ -109,7 +115,8 @@ export function widenScalar(a: ScalarKind, b: ScalarKind): ScalarKind {
 const INTEGER_TEXT = /^[+-]?[0-9]+$/;
 
 /** Java's Double.valueOf forms that Cytoscape writes: no hex, no `d` / `f` suffix. */
-const REAL_TEXT = /^[+-]?(NaN|Infinity|([0-9]+\.?[0-9]*|\.[0-9]+)([eE][+-]?[0-9]+)?)$/;
+const REAL_TEXT = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
+const NON_FINITE_TEXT = /^[+-]?(?:NaN|Infinity)$/;
 
 const I32_MIN = -2147483648;
 const I32_MAX = 2147483647;
@@ -129,6 +136,7 @@ interface ParsedScalar {
  * @param kind - the declared kind
  * @param unescape - decode Cytoscape's two-character `\n` and `\t` in strings
  * @returns the value, or null when the text does not parse as the kind
+ * @category Plugin helpers
  */
 export function parseScalar(text: string, kind: ScalarKind, unescape: boolean): ParsedScalar | null {
     switch (kind) {
@@ -158,7 +166,7 @@ export function parseScalar(text: string, kind: ScalarKind, unescape: boolean):
         }
         case "real": {
             const t = text.trim();
-            if (!REAL_TEXT.test(t)) {
+            if (!REAL_TEXT.test(t) && !NON_FINITE_TEXT.test(t)) {
                 return null;
             }
             const n = Number(t);

package/src/index.ts

@@ -1,13 +1,35 @@
 /**
- * The public barrel of @graphty/graph-io (design sections 8.2, 12.4 and 13.1): the io contract
- * types and ImportError, the registry with `importGraph()` / `exportGraph()` / `sniff()`, the
- * `children` CSR helper, every built-in importer and exporter (also reachable through the per-format
- * subpath exports `@graphty/graph-io/<format>`), and the shared helpers a third-party importer or
- * exporter builds on (report builder, input reader, option resolution, direction resolver, id
- * coercion, the capability check and the loss / issue codes callers branch on). Named exports
- * only; no default export.
+ * Read and write graph files as `@graphty/graph-format` snapshots.
+ *
+ * Most programs need eight functions: `loadFromUrl()`, `loadFromFile()` and `importGraph()` to read
+ * a graph; `exportGraphToBytes()`, `exportGraphToString()`, `exportGraphToBlob()` and
+ * `downloadGraph()` to write one; and `checkExport()` to see what a format would not keep. They are
+ * under Loading and Saving. Each format's importer, exporter, options and codes are in its own
+ * module, `@graphty/graph-io/<format>`, and are also exported here. Writing a format and Plugin
+ * helpers are for adding a format of your own. The guide is at https://graphty.app/docs/graph-io/.
+ * @module @graphty/graph-io
  */
 
+// ============================================================ graph-format re-exports
+// The error class every deliberate graph-io failure extends, the graph type every function takes
+// or returns, the column type its attribute tables hold, the builder that copies or combines graphs,
+// the graph an importer fills, and the "no such index" value a plugin compares with, so a caller
+// needs no second import.
+export {
+    type Column,
+    GraphBuilder,
+    GraphFormatError,
+    type GraphSink,
+    type GraphSnapshot,
+    INVALID_INDEX,
+} from "@graphty/graph-format";
+
+// ============================================================ a line format in one function
+export { defineLineFormat, type LineAttributes, type LineFormat, type LineGraph } from "./common/line-format.js";
+
+// ============================================================ testing a plugin
+export { type CompareOptions, compareSnapshots, describeDiffs, type SnapshotDiff } from "./common/compare.js";
+
 // ============================================================ io contract types (12.4)
 export {
     type CommonExportOptions,
@@ -38,21 +60,32 @@ export {
     type BuilderSeed,
     checkExport,
     createRegistry,
+    downloadGraph,
+    type DownloadGraphOptions,
     exportGraph,
     type ExportGraphOptions,
+    exportGraphToBlob,
+    exportGraphToBytes,
     exportGraphToString,
+    type FormatInfo,
     FormatRegistry,
     importAllGraphs,
     importGraph,
     type ImportGraphOptions,
     type ImportGraphResult,
+    listFormats,
     listGraphs,
+    loadFromFile,
+    loadFromUrl,
+    type LoadFromUrlOptions,
     registry,
     sniff,
+    SNIFF_FAILED_CODE,
     UNKNOWN_FORMAT_CODE,
 } from "./registry.js";
 export {
     extensionOf,
+    type FormatName,
     GRAPH_FORMATS,
     type GraphFormatName,
     headBytes,
@@ -76,7 +109,15 @@ export {
     csvImporter,
     type CsvImportOptions,
 } from "./formats/csv/index.js";
-export { CX_ISSUE, cxImporter, type CxImportOptions } from "./formats/cx/index.js";
+export {
+    CX_CAPABILITIES,
+    CX_ISSUE,
+    CX_LOSS,
+    cxExporter,
+    type CxExportOptions,
+    cxImporter,
+    type CxImportOptions,
+} from "./formats/cx/index.js";
 export {
     CX2_CAPABILITIES,
     CX2_ISSUE,
@@ -86,7 +127,15 @@ export {
     cx2Importer,
     type Cx2ImportOptions,
 } from "./formats/cx2/index.js";
-export { CYS_ISSUE, cysImporter, type CysImportOptions } from "./formats/cys/index.js";
+export {
+    CYS_CAPABILITIES,
+    CYS_ISSUE,
+    CYS_LOSS,
+    cysExporter,
+    type CysExportOptions,
+    cysImporter,
+    type CysImportOptions,
+} from "./formats/cys/index.js";
 export {
     DOT_ISSUE,
     DOT_LOSS,
@@ -134,8 +183,10 @@ export {
     jsonImporter,
     type JsonImportOptions,
     type JsonShapeMeta,
+    jsonShapeOf,
 } from "./formats/json/index.js";
 export {
+    exportNeo4jFiles,
     ID_SPACE_COLUMN,
     LABELS_COLUMN,
     NEO4J_CAPABILITIES,
@@ -143,12 +194,21 @@ export {
     NEO4J_LOSS,
     neo4jExporter,
     type Neo4jExportOptions,
+    type Neo4jFile,
     neo4jImporter,
     type Neo4jImportOptions,
     ORIGINAL_ID_COLUMN,
     TYPE_COLUMN,
 } from "./formats/neo4j/index.js";
-export { OBO_ISSUE, oboImporter, type OboImportOptions } from "./formats/obo/index.js";
+export {
+    OBO_CAPABILITIES,
+    OBO_ISSUE,
+    OBO_LOSS,
+    oboExporter,
+    type OboExportOptions,
+    oboImporter,
+    type OboImportOptions,
+} from "./formats/obo/index.js";
 export {
     PAJEK_ISSUE,
     PAJEK_LOSS,
@@ -202,6 +262,7 @@ export {
     LOSS,
     mangleNmtoken,
     NO_CAPABILITIES,
+    refusedSave,
     type SanitizedIds,
     sanitizeIds,
 } from "./common/export.js";
@@ -228,6 +289,8 @@ export {
 export {
     chooseGraph,
     DEFAULT_ERROR_LIMIT,
+    forDecodedText,
+    graphChosen,
     type ImportFormatDefaults,
     reportSinkOptions,
     reportUnusedOptions,
@@ -252,7 +315,13 @@ export {
     type TextDtype,
     WIDENING_UNSUPPORTED_CODE,
 } from "./common/text.js";
-export { type ExplicitWeights, explicitWeights, isWeightField, parseWeightText } from "./common/weights.js";
+export {
+    edgeWeights,
+    type ExplicitWeights,
+    explicitWeights,
+    isWeightField,
+    parseWeightText,
+} from "./common/weights.js";
 export {
     collectBytes,
     decodeChunks,
@@ -267,6 +336,7 @@ export {
     tokenizeXml,
     type XmlHandler,
     xmlIllegalTextNotes,
+    type XmlRepairs,
     XmlSyntaxError,
     XmlTokenizer,
 } from "./common/xml.js";