@graphty/graph-io 0.2.4 → 0.3.0

package/src/formats/gml/index.ts

@@ -7,12 +7,15 @@ import {
     COLUMN_RENAMED_CODE,
     DIRECTION_FORCED_CODE,
     DIRECTION_REFUSED_CODE,
+    ENCODING_FALLBACK_CODE,
     ID_MERGED_CODE,
+    INVALID_ENCODING_CODE,
     INVALID_UTF8_CODE,
     MIXED_DIRECTION_CODE,
     OPTION_IGNORED_CODE,
     SINK_OPTION_CODE,
     SYNTAX_CODE,
+    UNKNOWN_ENCODING_CODE,
 } from "../../common/codes.js";
 import {
     GRAPHICS_CONFLICT_CODE,
@@ -57,10 +60,16 @@ export const GML_ISSUE = Object.freeze({
     SYNTAX: SYNTAX_CODE,
     /** The input holds invalid UTF-8 (fatal). */
     INVALID_UTF8: INVALID_UTF8_CODE,
+    /** Invalid bytes in the encoding a BOM, a declaration or the encoding option chose (fatal). */
+    INVALID_ENCODING: INVALID_ENCODING_CODE,
+    /** Bytes that are not UTF-8 and declare no encoding were read as windows-1252. */
+    ENCODING_FALLBACK: ENCODING_FALLBACK_CODE,
+    /** A declared encoding the platform cannot decode was ignored. */
+    UNKNOWN_ENCODING: UNKNOWN_ENCODING_CODE,
     /** No `graph [` block (fatal). */
     NO_GRAPH: NO_GRAPH_CODE,
     /** More than one `graph` block (fatal). */
-    SECOND_GRAPH: SECOND_GRAPH_CODE,
+    MULTIPLE_GRAPHS: SECOND_GRAPH_CODE,
     /** A node without an `id`. */
     MISSING_ID: MISSING_ID_CODE,
     /** A node without a `label` under nodeIdFrom "label". */

package/src/formats/graphml/constants.ts

@@ -13,9 +13,11 @@ import {
     DUPLICATE_EDGE_ID_CODE,
     DUPLICATE_KEY_CODE,
     DUPLICATE_NODE_CODE,
+    ENCODING_FALLBACK_CODE,
     HYPEREDGE_CODE,
     ID_MERGED_CODE,
     ID_TEXT_TYPE_CODE,
+    INVALID_ENCODING_CODE,
     INVALID_UTF8_CODE,
     MISSING_ENDPOINT_CODE,
     MISSING_ID_CODE,
@@ -32,6 +34,7 @@ import {
     STRAY_TEXT_CODE,
     UNKNOWN_ATTR_TYPE_CODE,
     UNKNOWN_ELEMENT_CODE,
+    UNKNOWN_ENCODING_CODE,
     XML_SYNTAX_CODE,
 } from "../../common/codes.js";
 
@@ -114,6 +117,12 @@ export const GRAPHML_ISSUE = Object.freeze({
     XML_SYNTAX: XML_SYNTAX_CODE,
     /** Fatal: the input holds invalid UTF-8. */
     INVALID_UTF8: INVALID_UTF8_CODE,
+    /** Invalid bytes in the encoding a BOM, a declaration or the encoding option chose (fatal). */
+    INVALID_ENCODING: INVALID_ENCODING_CODE,
+    /** Bytes that are not UTF-8 and declare no encoding were read as windows-1252. */
+    ENCODING_FALLBACK: ENCODING_FALLBACK_CODE,
+    /** A declared encoding the platform cannot decode was ignored. */
+    UNKNOWN_ENCODING: UNKNOWN_ENCODING_CODE,
     /** Fatal: the root element is not `<graphml>`. */
     NOT_GRAPHML: "E_NOT_GRAPHML",
     /** Fatal: the document has no `<graph>`. */

package/src/formats/graphml/importer.ts

@@ -51,7 +51,14 @@ import {
 } from "../../common/options.js";
 import { ImportReportBuilder } from "../../common/report.js";
 import { isWeightField, parseWeightText } from "../../common/weights.js";
-import { isWhitespace, localName, tokenizeXml, type XmlHandler, XmlSyntaxError } from "../../common/xml.js";
+import {
+    isWhitespace,
+    localName,
+    tokenizeXml,
+    xmlDeclaredEncoding,
+    type XmlHandler,
+    XmlSyntaxError,
+} from "../../common/xml.js";
 import { type CommonImportOptions, type GraphImporter, type ImportInput, type ImportReport } from "../../types.js";
 import {
     EDGE_ID_COLUMN,
@@ -2005,7 +2012,7 @@ async function importGraphml(
     reportUnusedOptions(options, report, USED_OPTIONS);
     const reader = new GraphmlReader(sink, report, common, yfilesMode);
     try {
-        await tokenizeXml(textChunks(input, report, common), reader);
+        await tokenizeXml(textChunks(input, report, { ...common, declaredEncoding: xmlDeclaredEncoding }), reader);
     } catch (err) {
         if (err instanceof XmlSyntaxError) {
             report.fail(GRAPHML_ISSUE.XML_SYNTAX, err.message, { line: err.line });

package/src/formats/json/exporter.ts

@@ -22,7 +22,7 @@ import { type Column, GraphFormatError, type GraphSnapshot, INVALID_INDEX, type
 
 import { type PairFolding, pairFolding } from "../../common/direction.js";
 import { checkCapabilities, countMixedEdges, LOSS } from "../../common/export.js";
-import { formatF32 } from "../../common/format.js";
+import { formatF32, formatF64 } from "../../common/format.js";
 import { type ResolvedExportOptions, resolveExportOptions } from "../../common/options.js";
 import { explicitWeights } from "../../common/weights.js";
 import { encodeChunks, joinText } from "../../common/writer.js";
@@ -283,7 +283,8 @@ function numberText(value: number, f32: boolean, nonfinite: Counter): string {
     if (f32) {
         return formatF32(value);
     }
-    return Object.is(value, -0) ? "0" : String(value);
+    // -0 is a JSON number too ("-0"); JSON.parse reads it back as -0
+    return formatF64(value);
 }
 
 /**
@@ -776,7 +777,7 @@ function planSlot(ctx: PlanContext, column: Column, domain: Domain): ColumnPlan
  * What the importer's inference (design section 5.1: JSON numbers are i32 when integral, else
  * f64; strings are strings; arrays and objects are json) changes about a written attribute
  * column beyond what checkCapabilities() already reported for its dtype: an f64 column whose set
- * values are all integers reads back as i32.
+ * finite values are all integers reads back as i32 (its non-finite values are written as null).
  * @param ctx - the plan context
  * @param column - the column
  * @param domain - its domain
@@ -787,11 +788,19 @@ function inferenceNotes(ctx: PlanContext, column: Column, domain: Domain, setRow
         return;
     }
     const { data } = column;
+    let finite = 0;
     for (let r = 0; r < column.length; r++) {
-        if (column.isSet(r) && !Number.isInteger(data[r])) {
-            return;
+        // a non-finite value is written as null and reads back unset, so it does not keep the column f64
+        if (column.isSet(r) && Number.isFinite(data[r])) {
+            if (!Number.isInteger(data[r])) {
+                return;
+            }
+            finite++;
         }
     }
+    if (finite === 0) {
+        return;
+    }
     ctx.note(
         LOSS.INTEGRAL_F64,
         `${domain} column "${column.meta.name}" is f64 with integral values only; JSON declares no types and it reads back as i32`,

package/src/formats/json/importer.ts

@@ -40,12 +40,16 @@ import {
     DUPLICATE_EDGE_ID_CODE,
     DUPLICATE_NODE_CODE,
     EMPTY_INPUT_CODE,
+    ENCODING_FALLBACK_CODE,
     HYPEREDGE_CODE,
+    INVALID_ENCODING_CODE,
+    INVALID_UTF8_CODE,
     MISSING_ENDPOINT_CODE,
     MISSING_ID_CODE,
     MULTIPLE_GRAPHS_CODE,
     OPTION_IGNORED_CODE,
     SYNTAX_CODE,
+    UNKNOWN_ENCODING_CODE,
     UNKNOWN_PARENT_CODE,
 } from "../../common/codes.js";
 import { DirectionResolver, type EdgeKind } from "../../common/direction.js";
@@ -157,6 +161,14 @@ export const JSON_ISSUE = Object.freeze({
     SINK_OPTION: SINK_OPTION_CODE,
     /** A common option the dialect has no use for (nodeIdFrom outside node-link, long, restoreMangledIds). */
     OPTION_IGNORED: OPTION_IGNORED_CODE,
+    /** The input holds invalid UTF-8 (fatal). */
+    INVALID_UTF8: INVALID_UTF8_CODE,
+    /** Invalid bytes in the encoding a BOM, a declaration or the encoding option chose (fatal). */
+    INVALID_ENCODING: INVALID_ENCODING_CODE,
+    /** Bytes that are not UTF-8 and declare no encoding were read as windows-1252. */
+    ENCODING_FALLBACK: ENCODING_FALLBACK_CODE,
+    /** A declared encoding the platform cannot decode was ignored. */
+    UNKNOWN_ENCODING: UNKNOWN_ENCODING_CODE,
 });
 
 /** The common options the JSON importer reads (the rest is reported by reportUnusedOptions). */
@@ -236,6 +248,8 @@ interface ResolvedJsonOptions {
     readonly targetKey: string | null;
     readonly indexLinks: boolean | "auto";
     readonly graphIndex: number;
+    /** Set by importAll(): every graph of a `graphs` array is read, so none is reported as skipped. */
+    readonly all?: boolean;
 }
 
 /**
@@ -1741,11 +1755,11 @@ function jgfGraphOf(ctx: ImportContext, root: JsonRecord): JsonRecord {
     if (graphs.length === 0) {
         report.fail(JSON_ISSUE.SHAPE, "a JGF document needs a graph object or a non-empty graphs array");
     }
-    if (graphs.length > 1) {
+    if (graphs.length > 1 && ctx.json.all !== true) {
         report.warning(
             "unsupported",
             JSON_ISSUE.MULTIPLE_GRAPHS,
-            `the document holds ${graphs.length} graphs; only graphs[${ctx.json.graphIndex}] is read`,
+            `the document holds ${graphs.length} graphs; only graphs[${ctx.json.graphIndex}] is read (${graphs.length - 1} skipped), importAll() reads every one`,
             { element: "graphs" },
         );
     }
@@ -2232,40 +2246,94 @@ export const jsonImporter: GraphImporter<JsonImportOptions> = Object.freeze({
         const text = await readText(input, report, resolved);
         const root = parseDocument(text, report);
         const dialect = detectDialect(root, json.dialect, report);
-        const ctx = new ImportContext(sink, report, resolved, json, options?.defaultDirected !== undefined);
-        reportSinkOptions(sink, options, report);
-        reportUnusedOptions(options, report, USED_OPTIONS);
-        if (dialect === "cytoscape") {
-            importCytoscape(ctx, root);
-            throwIfAborted(resolved.signal);
-            return report.finish();
-        }
-        const doc = isJsonObject(root)
-            ? root
-            : report.fail(JSON_ISSUE.SHAPE, `a ${dialect} document must be a JSON object, found ${describe(root)}`);
-        switch (dialect) {
-            case "node-link":
-            case "d3":
-                importNodeLink(ctx, doc, dialect);
-                break;
-            case "jgf":
-                importJgf(ctx, doc);
-                break;
-            case "graphology":
-                importGraphology(ctx, doc);
-                break;
-            case "vis":
-                importVis(ctx, doc);
-                break;
-            default: {
-                const name: string = dialect;
-                throw new GraphFormatError("E_UNSUPPORTED", `unknown dialect ${name}`, {
-                    option: "dialect",
-                    found: name,
-                });
-            }
-        }
-        throwIfAborted(resolved.signal);
+        readGraph(root, dialect, sink, report, resolved, json, options);
         return report.finish();
     },
+
+    /**
+     * Read every graph of a JSON document: each entry of a JGF `graphs` array into its own sink;
+     * any other document holds one graph.
+     * @param input - the text, bytes or stream
+     * @param sinkFor - the sink of the graph with this index, called before its first push
+     * @param options - format-specific and common options
+     * @returns one report per graph
+     */
+    async importAll(
+        input: ImportInput,
+        sinkFor: (index: number) => GraphSink,
+        options?: JsonImportOptions & CommonImportOptions,
+    ): Promise<ImportReport[]> {
+        const resolved = resolveImportOptions(options, FORMAT_DEFAULTS);
+        const json = resolveJsonOptions(options);
+        const first = new ImportReportBuilder("json", resolved.errorLimit);
+        const text = await readText(input, first, resolved);
+        const root = parseDocument(text, first);
+        const dialect = detectDialect(root, json.dialect, first);
+        const graphs =
+            dialect === "jgf" && isJsonObject(root) && !isJsonObject(root.graph) && Array.isArray(root.graphs)
+                ? root.graphs.length
+                : 1;
+        const reports: ImportReport[] = [];
+        for (let i = 0; i < Math.max(graphs, 1); i++) {
+            const report = i === 0 ? first : new ImportReportBuilder("json", resolved.errorLimit);
+            readGraph(root, dialect, sinkFor(i), report, resolved, { ...json, graphIndex: i, all: true }, options);
+            reports.push(report.finish());
+        }
+        return reports;
+    },
 });
+
+/**
+ * Read one graph of a parsed document into a sink.
+ * @param root - the parsed document
+ * @param dialect - its dialect
+ * @param sink - the sink
+ * @param report - the graph's report
+ * @param resolved - the resolved common options
+ * @param json - the resolved JSON options (graphIndex picks the JGF graph)
+ * @param options - the caller's options, for the sink and unused-option checks
+ */
+function readGraph(
+    root: unknown,
+    dialect: JsonDialect,
+    sink: GraphSink,
+    report: ImportReportBuilder,
+    resolved: ResolvedImportOptions,
+    json: ResolvedJsonOptions,
+    options: (JsonImportOptions & CommonImportOptions) | undefined,
+): void {
+    const ctx = new ImportContext(sink, report, resolved, json, options?.defaultDirected !== undefined);
+    reportSinkOptions(sink, options, report);
+    reportUnusedOptions(options, report, USED_OPTIONS);
+    if (dialect === "cytoscape") {
+        importCytoscape(ctx, root);
+        throwIfAborted(resolved.signal);
+        return;
+    }
+    const doc = isJsonObject(root)
+        ? root
+        : report.fail(JSON_ISSUE.SHAPE, `a ${dialect} document must be a JSON object, found ${describe(root)}`);
+    switch (dialect) {
+        case "node-link":
+        case "d3":
+            importNodeLink(ctx, doc, dialect);
+            break;
+        case "jgf":
+            importJgf(ctx, doc);
+            break;
+        case "graphology":
+            importGraphology(ctx, doc);
+            break;
+        case "vis":
+            importVis(ctx, doc);
+            break;
+        default: {
+            const name: string = dialect;
+            throw new GraphFormatError("E_UNSUPPORTED", `unknown dialect ${name}`, {
+                option: "dialect",
+                found: name,
+            });
+        }
+    }
+    throwIfAborted(resolved.signal);
+}

package/src/formats/neo4j/importer.ts

@@ -467,7 +467,7 @@ class Neo4jImportSession {
     async run(inputs: readonly ImportInput[]): Promise<void> {
         const progress = new ProgressTracker(this.common.onProgress, inputs);
         for (const input of inputs) {
-            await this.readInput(input, progress.optionsFor(this.common.signal));
+            await this.readInput(input, { ...progress.optionsFor(this.common.signal), encoding: this.common.encoding });
             progress.finishInput();
         }
         if (this.ignoredColumns > 0) {

package/src/formats/neo4j/index.ts

@@ -6,6 +6,8 @@
 
 import {
     COLUMN_RENAMED_CODE,
+    ENCODING_FALLBACK_CODE,
+    INVALID_ENCODING_CODE,
     INVALID_UTF8_CODE,
     MUTUAL_EXPANDED_CODE,
     OPTION_IGNORED_CODE,
@@ -13,6 +15,7 @@ import {
     ROLE_DROPPED_CODE,
     SINK_OPTION_CODE,
     UNKNOWN_ATTR_TYPE_CODE,
+    UNKNOWN_ENCODING_CODE,
     WEIGHT_KEY_CLASH_CODE,
 } from "../../common/codes.js";
 import { BAD_QUOTE_CODE, UNCLOSED_QUOTE_CODE } from "../csv/records.js";
@@ -50,6 +53,12 @@ export { ID_SPACE_COLUMN, LABELS_COLUMN, neo4jImporter, type Neo4jImportOptions,
 export const NEO4J_ISSUE = Object.freeze({
     /** The input holds invalid UTF-8 (fatal). */
     INVALID_UTF8: INVALID_UTF8_CODE,
+    /** Invalid bytes in the encoding a BOM, a declaration or the encoding option chose (fatal). */
+    INVALID_ENCODING: INVALID_ENCODING_CODE,
+    /** Bytes that are not UTF-8 and declare no encoding were read as windows-1252. */
+    ENCODING_FALLBACK: ENCODING_FALLBACK_CODE,
+    /** A declared encoding the platform cannot decode was ignored. */
+    UNKNOWN_ENCODING: UNKNOWN_ENCODING_CODE,
     /** An unterminated quoted field (fatal). */
     CSV_UNCLOSED_QUOTE: UNCLOSED_QUOTE_CODE,
     /** Text after a closing quote (fatal). */

package/src/formats/pajek/exporter.ts

@@ -20,6 +20,7 @@ import { capabilities, checkCapabilities, LOSS, type SanitizedIds, sanitizeIds }
 import { formatDecimal, formatF32, formatF64, formatInteger } from "../../common/format.js";
 import { canonicalId } from "../../common/ids.js";
 import { resolveExportOptions } from "../../common/options.js";
+import { inferTextDtype } from "../../common/text.js";
 import { explicitWeights } from "../../common/weights.js";
 import { encodeChunks, joinText } from "../../common/writer.js";
 import { type CommonExportOptions, type ExportCapabilities, type GraphExporter, type LossNote } from "../../types.js";
@@ -74,6 +75,8 @@ export const PAJEK_LOSS = Object.freeze({
     ROLE_ASSUMED: LOSS.ROLE_ASSUMED,
     /** Under sanitizeIds "mangle": an original id whose text reads back as the other type under ids "canonical". */
     ID_TEXT_TYPE: LOSS.ID_TEXT_TYPE,
+    /** Parameter text that looks like a number or a boolean reads back as one (parameters are untyped, design 5.1). */
+    TEXT_INFERRED: LOSS.TEXT_INFERRED,
 });
 
 /** The roles Pajek has a slot for beyond the structural, position and temporal ones. */
@@ -400,7 +403,7 @@ function cellText(column: Column, row: number): string {
 
 /**
  * Count the cells of a plan that cannot be written (text with a quote or line break, non-finite
- * f64) and add the notes.
+ * f64) or read back typed (parameter text that looks like a number or a boolean) and add the notes.
  * @param planned - the plan
  * @param domain - node or edge
  * @param notes - the note list
@@ -413,6 +416,7 @@ function checkCells(planned: readonly PlannedColumn[], domain: "node" | "edge",
         const { name } = column.meta;
         let badText = 0;
         let nonFinite = 0;
+        let typed = 0;
         for (let r = 0; r < column.length; r++) {
             if (!column.isSet(r)) {
                 continue;
@@ -427,8 +431,11 @@ function checkCells(planned: readonly PlannedColumn[], domain: "node" | "edge",
                     nonFinite++;
                 }
             } else if (column.dtype === "string" || column.dtype === "dict") {
-                if (!isPajekLabel(column.value(r) as string)) {
+                const text = column.value(r) as string;
+                if (!isPajekLabel(text)) {
                     badText++;
+                } else if (slot === "param" && inferTextDtype(text) !== "string") {
+                    typed++;
                 }
             }
         }
@@ -442,6 +449,16 @@ function checkCells(planned: readonly PlannedColumn[], domain: "node" | "edge",
                 ),
             );
         }
+        if (typed > 0) {
+            notes.push(
+                note(
+                    PAJEK_LOSS.TEXT_INFERRED,
+                    `${typed} value(s) of ${domain} column "${name}" look like numbers or booleans; Pajek parameters are untyped and they read back as such`,
+                    name,
+                    typed,
+                ),
+            );
+        }
         if (nonFinite > 0) {
             notes.push(
                 note(