@graphty/graph-io 0.3.41 → 0.3.42

package/src/formats/csv/exporter.ts

@@ -22,7 +22,14 @@
  * colon is written `id:` when it has no weight so the importer does not read its tail as one.
  */
 
-import { type Column, GraphFormatError, type GraphSnapshot, type NodeId } from "@graphty/graph-format";
+import {
+    type Column,
+    type F32Column,
+    type F64Column,
+    GraphFormatError,
+    type GraphSnapshot,
+    type NodeId,
+} from "@graphty/graph-format";
 
 import { DICT_SAMPLE_ROWS, DictHeuristic } from "../../common/attributes.js";
 import { type PairFolding, pairFolding } from "../../common/direction.js";
@@ -371,16 +378,6 @@ function cellText(column: Column, row: number): string | null {
     }
 }
 
-/**
- * Build the plan of an export: resolve options, choose the rows and columns, and collect the
- * CSV-specific loss notes (check() adds the generic ones). The value-level notes need a pass over
- * every written cell and are collected for check() only; export() needs the plan and the fatal
- * id-collision note alone.
- * @param snapshot - the snapshot
- * @param options - the caller's options
- * @param values - whether to scan the values for notes
- * @returns the plan
- */
 /**
  * W_CSV_NODE_TABLE: the node columns an edge-table or adjacency export leaves for a second, node-table export.
  * @param names - the node columns, label first
@@ -469,6 +466,16 @@ function idNotes(
     }
 }
 
+/**
+ * Build the plan of an export: resolve options, choose the rows and columns, and collect the
+ * CSV-specific loss notes (check() adds the generic ones). The value-level notes need a pass over
+ * every written cell and are collected for check() only; export() needs the plan and the fatal
+ * id-collision note alone.
+ * @param snapshot - the snapshot
+ * @param options - the caller's options
+ * @param values - whether to scan the values for notes
+ * @returns the plan
+ */
 function planExport(
     snapshot: GraphSnapshot,
     options: (CsvExportOptions & CommonExportOptions) | undefined,
@@ -492,7 +499,66 @@ function planExport(
             edgeRows.push(e);
         }
     }
-    // A node table holds no edge: the direction and mutual notes are the edge table's.
+    directionNotes(snapshot, csv, edgeRows.length, note);
+    if (folding.mutualCount > 0 && csv.table !== "nodes") {
+        note(
+            CSV_LOSS.MUTUAL_EXPANDED,
+            `${folding.mutualCount} mutual pair${plural(folding.mutualCount)} ${agree(folding.mutualCount, "is", "are")} written as two directed rows; the mutual mark is lost`,
+            null,
+            folding.mutualCount,
+        );
+    }
+    if (csv.table === "edges") {
+        noteNodeCoverage(snapshot, edgeRows, note);
+    }
+
+    // weights
+    const weights = explicitWeights(snapshot);
+
+    const { edgeId, edgeLabel, edgeColumns } = planEdgeColumns(snapshot, csv, edgeRows, values, note);
+    const { nodeLabel, nodeColumns } = planNodeColumns(snapshot, csv, values, note);
+    if (csv.table !== "nodes") {
+        nodeTableNote(
+            [...(nodeLabel === null ? [] : [nodeLabel.meta.name]), ...nodeColumns.map((c) => c.column.meta.name)],
+            csv.table,
+            notes,
+        );
+    }
+
+    return {
+        csv,
+        common,
+        notes,
+        edgeRows,
+        folding,
+        edgeId,
+        edgeLabel,
+        weights,
+        edgeColumns,
+        nodeLabel,
+        nodeColumns,
+        idText,
+    };
+}
+
+/** Records one loss note. */
+type NoteFn = (code: string, message: string, column?: string | null, count?: number | null) => void;
+
+/**
+ * W_CSV_DIRECTION_DROPPED: a table with no direction column (the generic dialect, an adjacency
+ * table) loses the direction of undirected edges, and the Gephi edge table of an undirected graph
+ * without edges has no Type cell to carry it. A node table holds no edge, so it gets no note.
+ * @param snapshot - the snapshot
+ * @param csv - the resolved CSV options
+ * @param edgeRowCount - how many edge rows are written
+ * @param note - the recorder
+ */
+function directionNotes(
+    snapshot: GraphSnapshot,
+    csv: ResolvedCsvExportOptions,
+    edgeRowCount: number,
+    note: NoteFn,
+): void {
     if (csv.table !== "nodes" && (csv.dialect.type === null || csv.table === "adjacency")) {
         const where = csv.table === "adjacency" ? "an adjacency table" : "the generic dialect";
         const mixed = countMixedEdges(snapshot);
@@ -511,7 +577,7 @@ function planExport(
                 mixed,
             );
         }
-    } else if (csv.table === "edges" && !snapshot.directed && edgeRows.length === 0) {
+    } else if (csv.table === "edges" && !snapshot.directed && edgeRowCount === 0) {
         note(
             CSV_LOSS.DIRECTION_DROPPED,
             "the direction lives in the Type cell of each edge row; an undirected graph without edges reads back as directed",
@@ -519,22 +585,25 @@ function planExport(
             0,
         );
     }
-    if (folding.mutualCount > 0 && csv.table !== "nodes") {
-        note(
-            CSV_LOSS.MUTUAL_EXPANDED,
-            `${folding.mutualCount} mutual pair${plural(folding.mutualCount)} ${agree(folding.mutualCount, "is", "are")} written as two directed rows; the mutual mark is lost`,
-            null,
-            folding.mutualCount,
-        );
-    }
-    if (csv.table === "edges") {
-        noteNodeCoverage(snapshot, edgeRows, note);
-    }
-
-    // weights
-    const weights = explicitWeights(snapshot);
+}
 
-    // the edge table's columns
+/**
+ * The edge table's columns, with their notes: the attribute columns' names (edge table only), the
+ * columns an adjacency table drops, and the values of every column the edge table writes.
+ * @param snapshot - the snapshot
+ * @param csv - the resolved CSV options
+ * @param edgeRows - the edge rows written
+ * @param values - whether the values are inspected
+ * @param note - the recorder
+ * @returns the id and label role columns and the attribute columns
+ */
+function planEdgeColumns(
+    snapshot: GraphSnapshot,
+    csv: ResolvedCsvExportOptions,
+    edgeRows: readonly number[],
+    values: boolean,
+    note: NoteFn,
+): { edgeId: Column | null; edgeLabel: Column | null; edgeColumns: ColumnOut[] } {
     const edgeId = snapshot.edges.byRole("id");
     const edgeLabel = snapshot.edges.byRole("label");
     const edgeReserved = new Set<string>([csv.dialect.source, csv.dialect.target, csv.dialect.weight].map(lower));
@@ -567,8 +636,23 @@ function planExport(
             checkValues(column, "edge", edgeRows, note);
         }
     }
+    return { edgeId, edgeLabel, edgeColumns };
+}
 
-    // the node table's columns
+/**
+ * The node table's columns, with their notes when the node table is the one written.
+ * @param snapshot - the snapshot
+ * @param csv - the resolved CSV options
+ * @param values - whether the values are inspected
+ * @param note - the recorder
+ * @returns the label role column and the attribute columns
+ */
+function planNodeColumns(
+    snapshot: GraphSnapshot,
+    csv: ResolvedCsvExportOptions,
+    values: boolean,
+    note: NoteFn,
+): { nodeLabel: Column | null; nodeColumns: ColumnOut[] } {
     const nodeLabel = snapshot.nodes.byRole("label");
     const nodeReserved = new Set<string>([lower(csv.dialect.id)]);
     const nodeRows: number[] = [];
@@ -585,35 +669,13 @@ function planExport(
         nodeLabel,
         csv.table === "nodes" ? note : null,
     );
-    if (csv.table === "nodes") {
-        if (values) {
-            checkRoleColumn(nodeLabel, "label", LABEL_NAMES, "node", nodeRows, note);
-            for (const { column } of nodeColumns) {
-                checkValues(column, "node", nodeRows, note);
-            }
+    if (csv.table === "nodes" && values) {
+        checkRoleColumn(nodeLabel, "label", LABEL_NAMES, "node", nodeRows, note);
+        for (const { column } of nodeColumns) {
+            checkValues(column, "node", nodeRows, note);
         }
-    } else {
-        nodeTableNote(
-            [...(nodeLabel === null ? [] : [nodeLabel.meta.name]), ...nodeColumns.map((c) => c.column.meta.name)],
-            csv.table,
-            notes,
-        );
     }
-
-    return {
-        csv,
-        common,
-        notes,
-        edgeRows,
-        folding,
-        edgeId,
-        edgeLabel,
-        weights,
-        edgeColumns,
-        nodeLabel,
-        nodeColumns,
-        idText,
-    };
+    return { nodeLabel, nodeColumns };
 }
 
 /**
@@ -859,26 +921,13 @@ function checkValues(
     column: Column,
     domain: "node" | "edge",
     rows: readonly number[],
-    note: (code: string, message: string, column?: string | null, count?: number | null) => void,
+    note: NoteFn,
     roleColumn = false,
 ): void {
     const { name, dtype } = column.meta;
     const label = `${domain} column "${name}"`;
     if (column.dtype === "f32" || column.dtype === "f64") {
-        let nonFinite = 0;
-        const { components } = column.meta;
-        const { data } = column;
-        for (const row of rows) {
-            if (!column.isSet(row)) {
-                continue;
-            }
-            for (let k = 0; k < components; k++) {
-                if (!Number.isFinite(data[row * components + k])) {
-                    nonFinite++;
-                    break;
-                }
-            }
-        }
+        const nonFinite = countNonFinite(column, rows);
         if (nonFinite > 0) {
             note(
                 CSV_LOSS.NONFINITE,
@@ -892,15 +941,77 @@ function checkValues(
     if (dtype !== "string" && dtype !== "dict") {
         return;
     }
+    const scan = scanText(column, rows);
+    if (roleColumn || scan.widest < 0) {
+        return;
+    }
+    const readsAsDict = scan.candidate && scan.heuristic.decide() === "dict";
+    if (scan.widest < WIDENING.string && !readsAsDict) {
+        note(CSV_LOSS.TEXT_INFERRED, `${label}: every value reads back as ${TEXT_DTYPES[scan.widest]}`, name, scan.set);
+        return;
+    }
+    if (dtype === "dict" && !readsAsDict) {
+        note(
+            CSV_LOSS.STORAGE_CLASS_CHANGED,
+            `${label}: reads back as string (cardinality too high for a dict)`,
+            name,
+            null,
+        );
+    } else if (dtype === "string" && readsAsDict) {
+        note(CSV_LOSS.STORAGE_CLASS_CHANGED, `${label}: reads back as dict (low cardinality)`, name, null);
+    }
+}
+
+/**
+ * The rows of a float column holding at least one non-finite component.
+ * @param column - the f32 or f64 column
+ * @param rows - the rows written
+ * @returns how many rows hold one
+ */
+function countNonFinite(column: F32Column | F64Column, rows: readonly number[]): number {
+    let nonFinite = 0;
+    const { components } = column.meta;
+    const { data } = column;
+    for (const row of rows) {
+        if (!column.isSet(row)) {
+            continue;
+        }
+        for (let k = 0; k < components; k++) {
+            if (!Number.isFinite(data[row * components + k])) {
+                nonFinite++;
+                break;
+            }
+        }
+    }
+    return nonFinite;
+}
+
+/** What a text column's written values read back as. */
+interface TextScan {
+    /** The widest dtype the values infer to (WIDENING), -1 when no value is set. */
+    readonly widest: number;
+    /** Whether every value the dict heuristic sampled infers to string. */
+    readonly candidate: boolean;
+    /** How many rows hold a string. */
+    readonly set: number;
+    /** The dict heuristic over the sampled values. */
+    readonly heuristic: DictHeuristic;
+}
+
+/**
+ * Infer the dtype every written value of a text column reads back as, and sample the values for
+ * the dict heuristic.
+ * @param column - the string or dict column
+ * @param rows - the rows written
+ * @returns the scan
+ */
+function scanText(column: Column, rows: readonly number[]): TextScan {
     let widest = -1;
     let candidate = true;
     let set = 0;
     const heuristic = new DictHeuristic(DICT_SAMPLE_ROWS);
     for (const row of rows) {
-        if (!column.isSet(row)) {
-            continue;
-        }
-        const text = column.value(row);
+        const text = column.isSet(row) ? column.value(row) : null;
         if (typeof text !== "string") {
             continue;
         }
@@ -908,30 +1019,11 @@ function checkValues(
         const kind = inferTextDtype(text);
         widest = Math.max(widest, WIDENING[kind]);
         if (!heuristic.decided) {
-            if (kind !== "string") {
-                candidate = false;
-            }
+            candidate &&= kind === "string";
             heuristic.observe(text);
         }
     }
-    if (roleColumn || widest < 0) {
-        return;
-    }
-    const readsAsDict = candidate && heuristic.decide() === "dict";
-    if (widest < WIDENING.string && !readsAsDict) {
-        note(CSV_LOSS.TEXT_INFERRED, `${label}: every value reads back as ${TEXT_DTYPES[widest]}`, name, set);
-        return;
-    }
-    if (dtype === "dict" && !readsAsDict) {
-        note(
-            CSV_LOSS.STORAGE_CLASS_CHANGED,
-            `${label}: reads back as string (cardinality too high for a dict)`,
-            name,
-            null,
-        );
-    } else if (dtype === "string" && readsAsDict) {
-        note(CSV_LOSS.STORAGE_CLASS_CHANGED, `${label}: reads back as dict (low cardinality)`, name, null);
-    }
+    return { widest, candidate, set, heuristic };
 }
 
 /**
@@ -1064,59 +1156,79 @@ function* adjacencyLines(snapshot: GraphSnapshot, plan: Plan): Generator<string,
  * @returns nothing
  */
 function* lines(snapshot: GraphSnapshot, plan: Plan): Generator<string, void, undefined> {
-    const { csv } = plan;
-    if (csv.table === "adjacency") {
+    if (plan.csv.table === "adjacency") {
         yield* adjacencyLines(snapshot, plan);
-        return;
+    } else if (plan.csv.table === "nodes") {
+        yield* nodeLines(snapshot, plan);
+    } else {
+        yield* edgeLines(snapshot, plan);
     }
-    const { delimiter, newline } = csv;
+}
+
+/**
+ * The cell writers of a delimiter.
+ * @param delimiter - the field delimiter
+ * @returns `quote` for a text and `cell` for a column value (an unset value is the empty cell)
+ */
+function cellWriters(delimiter: string): {
+    quote: (text: string) => string;
+    cell: (column: Column, row: number) => string;
+} {
     const quote = (text: string): string => quoteCsvCell(text, delimiter);
     const cell = (column: Column, row: number): string => {
         const text = cellText(column, row);
         return text === null ? "" : quote(text);
     };
-    if (csv.table === "nodes") {
-        const headers = [csv.dialect.id];
-        if (plan.nodeLabel !== null) {
-            headers.push(plan.nodeLabel.meta.name);
-        }
-        for (const { header } of plan.nodeColumns) {
-            headers.push(header);
-        }
-        if (csv.header) {
-            yield headers.map(quote).join(delimiter) + newline;
-        }
-        for (let i = 0; i < snapshot.nodeCount; i++) {
-            const cells = [quote(plan.idText(i))];
-            if (plan.nodeLabel !== null) {
-                cells.push(cell(plan.nodeLabel, i));
-            }
-            for (const { column } of plan.nodeColumns) {
-                cells.push(cell(column, i));
-            }
-            yield cells.join(delimiter) + newline;
-        }
-        return;
-    }
-    const headers = [csv.dialect.source, csv.dialect.target];
-    if (csv.dialect.type !== null) {
-        headers.push(csv.dialect.type);
-    }
-    if (plan.edgeId !== null) {
-        headers.push(plan.edgeId.meta.name);
-    }
-    if (plan.edgeLabel !== null) {
-        headers.push(plan.edgeLabel.meta.name);
-    }
-    if (plan.weights.weighted) {
-        headers.push(csv.dialect.weight);
+    return { quote, cell };
+}
+
+/**
+ * The lines of the node table: the id, the label and the attribute columns of every node.
+ * @param snapshot - the snapshot
+ * @param plan - the plan
+ * @yields one line at a time
+ * @returns nothing
+ */
+function* nodeLines(snapshot: GraphSnapshot, plan: Plan): Generator<string, void, undefined> {
+    const { csv } = plan;
+    const { delimiter, newline } = csv;
+    const { quote, cell } = cellWriters(delimiter);
+    const headers = [csv.dialect.id];
+    if (plan.nodeLabel !== null) {
+        headers.push(plan.nodeLabel.meta.name);
     }
-    for (const { header } of plan.edgeColumns) {
+    for (const { header } of plan.nodeColumns) {
         headers.push(header);
     }
     if (csv.header) {
         yield headers.map(quote).join(delimiter) + newline;
     }
+    for (let i = 0; i < snapshot.nodeCount; i++) {
+        const cells = [quote(plan.idText(i))];
+        if (plan.nodeLabel !== null) {
+            cells.push(cell(plan.nodeLabel, i));
+        }
+        for (const { column } of plan.nodeColumns) {
+            cells.push(cell(column, i));
+        }
+        yield cells.join(delimiter) + newline;
+    }
+}
+
+/**
+ * The lines of the edge table: one row per written edge.
+ * @param snapshot - the snapshot
+ * @param plan - the plan
+ * @yields one line at a time
+ * @returns nothing
+ */
+function* edgeLines(snapshot: GraphSnapshot, plan: Plan): Generator<string, void, undefined> {
+    const { csv } = plan;
+    const { delimiter, newline } = csv;
+    const { quote, cell } = cellWriters(delimiter);
+    if (csv.header) {
+        yield edgeHeaders(plan).map(quote).join(delimiter) + newline;
+    }
     const list = snapshot.edgeList();
     for (const e of plan.edgeRows) {
         const cells = [quote(plan.idText(list.src[e])), quote(plan.idText(list.dst[e]))];
@@ -1139,6 +1251,32 @@ function* lines(snapshot: GraphSnapshot, plan: Plan): Generator<string, void, un
     }
 }
 
+/**
+ * The header of the edge table.
+ * @param plan - the plan
+ * @returns the header names, unquoted
+ */
+function edgeHeaders(plan: Plan): string[] {
+    const { dialect } = plan.csv;
+    const headers = [dialect.source, dialect.target];
+    if (dialect.type !== null) {
+        headers.push(dialect.type);
+    }
+    if (plan.edgeId !== null) {
+        headers.push(plan.edgeId.meta.name);
+    }
+    if (plan.edgeLabel !== null) {
+        headers.push(plan.edgeLabel.meta.name);
+    }
+    if (plan.weights.weighted) {
+        headers.push(dialect.weight);
+    }
+    for (const { header } of plan.edgeColumns) {
+        headers.push(header);
+    }
+    return headers;
+}
+
 /**
  * Plan an export and refuse it when a fatal note is present (E_INVALID_ID for id text collisions),
  * before anything is written.