@graphty/graph-io 0.3.40 → 0.3.42

package/dist/src/formats/csv/exporter.js

@@ -21,7 +21,7 @@
  * otherwise introduce out of index order gets a row of its own first, and a neighbor id holding a
  * colon is written `id:` when it has no weight so the importer does not read its tail as one.
  */
-import { GraphFormatError } from "@graphty/graph-format";
+import { GraphFormatError, } from "@graphty/graph-format";
 import { DICT_SAMPLE_ROWS, DictHeuristic } from "../../common/attributes.js";
 import { pairFolding } from "../../common/direction.js";
 import { quoteCsvCell } from "../../common/escape.js";
@@ -261,16 +261,6 @@ function cellText(column, row) {
         }
     }
 }
-/**
- * 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
@@ -293,6 +283,25 @@ function nodeTableNote(names, table, notes) {
         }));
     }
 }
+/**
+ * The number of node ids whose text an earlier id already has (a number and a string).
+ * @param ids - the snapshot's ids
+ * @returns the collisions
+ */
+function idTextCollisions(ids) {
+    const seen = new Set();
+    let collisions = 0;
+    for (let i = 0; i < ids.size; i++) {
+        const text = String(ids.idOf(i));
+        if (seen.has(text)) {
+            collisions++;
+        }
+        else {
+            seen.add(text);
+        }
+    }
+    return collisions;
+}
 /**
  * The id notes: text collisions are fatal (export() throws E_INVALID_ID); type changes under the
  * canonical re-read are reported.
@@ -303,17 +312,7 @@ function nodeTableNote(names, table, notes) {
 function idNotes(snapshot, values, note) {
     const { ids } = snapshot;
     if (ids.kind === "mixed") {
-        const seen = new Set();
-        let collisions = 0;
-        for (let i = 0; i < ids.size; i++) {
-            const text = String(ids.idOf(i));
-            if (seen.has(text)) {
-                collisions++;
-            }
-            else {
-                seen.add(text);
-            }
-        }
+        const collisions = idTextCollisions(ids);
         if (collisions > 0) {
             note(CSV_LOSS.ID_TEXT_COLLISION, `${collisions} node id${plural(collisions)} ${agree(collisions, "shares", "share")} their text with another id (a number and a string); the save fails with E_INVALID_ID`, null, collisions);
         }
@@ -331,6 +330,16 @@ function idNotes(snapshot, values, note) {
         }
     }
 }
+/**
+ * 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, options, values) {
     const common = resolveExportOptions(options);
     const csv = resolveCsvExportOptions(options);
@@ -349,7 +358,45 @@ function planExport(snapshot, options, values) {
             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,
+    };
+}
+/**
+ * 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, csv, edgeRowCount, note) {
     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);
@@ -360,18 +407,21 @@ function planExport(snapshot, options, values) {
             note(CSV_LOSS.DIRECTION_DROPPED, `${where} has no direction column; ${mixed} undirected edge${plural(mixed)} of a mixed graph read back as one directed edge each`, null, 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", null, 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, csv, edgeRows, values, note) {
     const edgeId = snapshot.edges.byRole("id");
     const edgeLabel = snapshot.edges.byRole("label");
     const edgeReserved = new Set([csv.dialect.source, csv.dialect.target, csv.dialect.weight].map(lower));
@@ -392,7 +442,17 @@ function planExport(snapshot, options, values) {
             checkValues(column, "edge", edgeRows, note);
         }
     }
-    // the node table's columns
+    return { edgeId, edgeLabel, edgeColumns };
+}
+/**
+ * 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, csv, values, note) {
     const nodeLabel = snapshot.nodes.byRole("label");
     const nodeReserved = new Set([lower(csv.dialect.id)]);
     const nodeRows = [];
@@ -402,31 +462,13 @@ function planExport(snapshot, options, values) {
         }
     }
     const nodeColumns = attributeColumns(snapshot.nodes, "node", nodeReserved, null, 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 };
 }
 /**
  * The edge table is not a node carrier (research note 07 section 2.6: node attributes and node
@@ -498,24 +540,55 @@ function attributeColumns(table, domain, reserved, idColumn, labelColumn, note)
         if (role !== null && SKIPPED_ROLES.has(role)) {
             continue;
         }
-        const low = lower(name);
         const set = column.length - column.nullCount;
-        const isIdName = domain === "edge" ? findColumn([name], EDGE_ID_NAMES) >= 0 : false;
-        if (reserved.has(low) || isIdName || (idColumn !== null && lower(idColumn.meta.name) === low)) {
-            note?.(CSV_LOSS.RESERVED_NAME, `${domain} column "${name}" is not written: the name is reserved for the ${isIdName ? "edge id" : low} column`, name, set);
+        if (isReservedName(name, domain, reserved, idColumn, set, note)) {
             continue;
         }
-        if (findColumn([name], LABEL_NAMES) >= 0) {
-            if (labelColumn !== null) {
-                note?.(CSV_LOSS.RESERVED_NAME, `${domain} column "${name}" is not written: the name is reserved for the label column`, name, set);
-                continue;
-            }
-            note?.(CSV_LOSS.ROLE_ASSUMED, `${domain} column "${name}" reads back with the label role (string)`, name, set);
+        if (findColumn([name], LABEL_NAMES) >= 0 && !labelNameWritten(name, domain, labelColumn, set, note)) {
+            continue;
         }
         out.push({ column, header: name });
     }
     return out;
 }
+/**
+ * Whether an attribute column's name is reserved for a structural column (a dialect header, an
+ * edge id name, the id column's name), with its note.
+ * @param name - the column name
+ * @param domain - node or edge, for messages
+ * @param reserved - lower-case header names the dialect writes for structure
+ * @param idColumn - the table's id role column, or null
+ * @param set - the column's set cells
+ * @param note - the recorder, or null when this table's notes are not wanted
+ * @returns true when the column is not written
+ */
+function isReservedName(name, domain, reserved, idColumn, set, note) {
+    const low = lower(name);
+    const isIdName = domain === "edge" ? findColumn([name], EDGE_ID_NAMES) >= 0 : false;
+    if (reserved.has(low) || isIdName || (idColumn !== null && lower(idColumn.meta.name) === low)) {
+        note?.(CSV_LOSS.RESERVED_NAME, `${domain} column "${name}" is not written: the name is reserved for the ${isIdName ? "edge id" : low} column`, name, set);
+        return true;
+    }
+    return false;
+}
+/**
+ * Whether an attribute column with a label header name is written, with its note: not when the
+ * table has a label column (the name is reserved for it), else it reads back with the label role.
+ * @param name - the column name
+ * @param domain - node or edge, for messages
+ * @param labelColumn - the table's label role column, or null
+ * @param set - the column's set cells
+ * @param note - the recorder, or null when this table's notes are not wanted
+ * @returns true when the column is written
+ */
+function labelNameWritten(name, domain, labelColumn, set, note) {
+    if (labelColumn !== null) {
+        note?.(CSV_LOSS.RESERVED_NAME, `${domain} column "${name}" is not written: the name is reserved for the label column`, name, set);
+        return false;
+    }
+    note?.(CSV_LOSS.ROLE_ASSUMED, `${domain} column "${name}" reads back with the label role (string)`, name, set);
+    return true;
+}
 /**
  * Notes about a role column (id or label): a name the importer does not map to the role, and a
  * dtype other than string / dict (read back as string).
@@ -571,20 +644,7 @@ function checkValues(column, domain, rows, note, roleColumn = false) {
     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, `${label}: ${nonFinite} non-finite value${plural(nonFinite)} ${agree(nonFinite, "reads", "read")} back as text`, name, nonFinite);
         }
@@ -593,15 +653,59 @@ function checkValues(column, domain, rows, note, roleColumn = false) {
     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, rows) {
+    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;
+}
+/**
+ * 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, rows) {
     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;
         }
@@ -609,26 +713,11 @@ function checkValues(column, domain, rows, note, roleColumn = false) {
         const kind = inferTextDtype(text);
         widest = Math.max(widest, WIDENING[kind]);
         if (!heuristic.decided) {
-            if (kind !== "string") {
-                candidate = false;
-            }
+            candidate && (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 };
 }
 /**
  * The Type cell of an edge row.
@@ -657,6 +746,21 @@ function neighbourCell(id, weight) {
     }
     return id.includes(":") ? `${id}:` : id;
 }
+/**
+ * The end of the run of consecutive edge rows that share the source of row `r`.
+ * @param src - the edge sources by edge index
+ * @param edgeRows - the edges in write order
+ * @param r - the run's first row
+ * @returns the index after the run's last row
+ */
+function sourceRunEnd(src, edgeRows, r) {
+    const source = src[edgeRows[r]];
+    let end = r;
+    while (end < edgeRows.length && src[edgeRows[end]] === source) {
+        end++;
+    }
+    return end;
+}
 /**
  * The rows of the adjacency table (design section 8.5: the order survives the importer's first-
  * appearance numbering). Consecutive edges with one source share a row, so the edge order is kept;
@@ -697,10 +801,7 @@ function* adjacencyLines(snapshot, plan) {
     let r = 0;
     while (r < edgeRows.length) {
         const source = list.src[edgeRows[r]];
-        let end = r;
-        while (end < edgeRows.length && list.src[edgeRows[end]] === source) {
-            end++;
-        }
+        const end = sourceRunEnd(list.src, edgeRows, r);
         // the nodes this row introduces, in the order the importer meets them; in index order from
         // `next` they need nothing more
         const fresh = [];
@@ -743,59 +844,75 @@ function* adjacencyLines(snapshot, plan) {
  * @returns nothing
  */
 function* lines(snapshot, plan) {
-    const { csv } = plan;
-    if (csv.table === "adjacency") {
+    if (plan.csv.table === "adjacency") {
         yield* adjacencyLines(snapshot, plan);
-        return;
     }
-    const { delimiter, newline } = csv;
+    else if (plan.csv.table === "nodes") {
+        yield* nodeLines(snapshot, plan);
+    }
+    else {
+        yield* edgeLines(snapshot, plan);
+    }
+}
+/**
+ * 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) {
     const quote = (text) => quoteCsvCell(text, delimiter);
     const cell = (column, row) => {
         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, plan) {
+    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, plan) {
+    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]))];
@@ -817,6 +934,31 @@ function* lines(snapshot, plan) {
         yield cells.join(delimiter) + newline;
     }
 }
+/**
+ * The header of the edge table.
+ * @param plan - the plan
+ * @returns the header names, unquoted
+ */
+function edgeHeaders(plan) {
+    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.