@graphty/graph-io 0.3.24 → 0.3.26

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

@@ -29,27 +29,53 @@ import { capabilities, checkCapabilities, LOSS } from "../../common/export.js";
 import { formatF32, formatF64, formatInteger } from "../../common/format.js";
 import { isCanonicalIntegerText } from "../../common/ids.js";
 import { resolveExportOptions } from "../../common/options.js";
+import { agree, plural } from "../../common/plural.js";
 import { formatTemporal } from "../../common/temporal.js";
 import { explicitWeights } from "../../common/weights.js";
 import { encodeChunks, joinText } from "../../common/writer.js";
 import { checkRecordSyntax } from "../csv/records.js";
 import { formatHeaderField } from "./header.js";
 import { ID_SPACE_COLUMN, LABELS_COLUMN, TYPE_COLUMN } from "./importer.js";
-/** Loss code: undirected edges (an undirected snapshot, or the folded pairs of a mixed one) written as directed relationships. */
+/**
+ * Neo4j relationships are always directed, so the edges of an undirected graph, and the undirected edges of a mixed
+ * graph, read back as directed.
+ * @category Built-in formats
+ */
 export const UNDIRECTED_LOSS = "W_NEO4J_UNDIRECTED_AS_DIRECTED";
-/** Loss code: node ids whose text re-imports as another type under the canonical id rule. */
+/**
+ * Node ids that read back as a different type, such as the text "7" as the number 7.
+ * @category Built-in formats
+ */
 export const ID_TEXT_TYPE_LOSS = ID_TEXT_TYPE_CODE;
-/** Loss code: two node ids share one text; export() throws E_INVALID_ID. */
+/**
+ * Two node ids share one text; export() throws E_INVALID_ID.
+ * @category Built-in formats
+ */
 export const ID_TEXT_COLLISION_LOSS = ID_TEXT_COLLISION_CODE;
-/** Loss code: an edge property column already uses the weight column name; export() throws E_COLUMN_EXISTS. */
+/**
+ * The `weightColumn` name is already an edge attribute; the save fails.
+ * @category Built-in formats
+ */
 export const WEIGHT_COLUMN_TAKEN_LOSS = "E_NEO4J_WEIGHT_COLUMN_TAKEN";
-/** Loss code: a node property column already uses the idColumn name; export() throws E_COLUMN_EXISTS. */
+/**
+ * The `idColumn` name is already a node attribute; the save fails.
+ * @category Built-in formats
+ */
 export const ID_COLUMN_TAKEN_LOSS = "E_NEO4J_ID_COLUMN_TAKEN";
-/** Loss code: a node has more than one stored-id column set; only the first is written. */
+/**
+ * A node has more than one stored-id column set; only the first is written.
+ * @category Built-in formats
+ */
 export const MULTIPLE_ID_PROPERTIES_LOSS = "W_NEO4J_MULTIPLE_ID_PROPERTIES";
-/** Loss code: a declared integer type holds non-integral values and is written as double. */
+/**
+ * A declared integer type holds non-integral values and is written as double.
+ * @category Built-in formats
+ */
 export const DECLARED_TYPE_CHANGED_LOSS = "W_NEO4J_DECLARED_TYPE_CHANGED";
-/** Loss code: a list item contains the array delimiter, which Neo4j cannot escape. */
+/**
+ * A list item contains the array delimiter, which Neo4j cannot escape.
+ * @category Built-in formats
+ */
 export const ARRAY_DELIMITER_LOSS = "W_NEO4J_ARRAY_DELIMITER";
 /** The roles Neo4j has a slot for: `:TYPE`, `:LABEL` and the id space of `:ID(Space)`. */
 const SLOT_ROLES = new Set(["kind", "labels", "idSpace"]);
@@ -64,10 +90,11 @@ const ROLE_NAMES = Object.freeze({
     idSpace: ID_SPACE_COLUMN,
 });
 /**
- * The capabilities of neo4j-admin CSV (research note 07 section 9): declared scalar types and
+ * The capabilities of neo4j-admin CSV: declared scalar types and
  * arrays; a dict column reads back as string (the header has no enumeration type); a position or
  * visual column is written as a plain property (a point for a 2- or 3-component position) and
  * reads back without its role.
+ * @category Built-in formats
  */
 export const NEO4J_CAPABILITIES = capabilities({
     mixedDirection: false,
@@ -130,9 +157,10 @@ const PARTS = new Set(["all", "nodes", "relationships"]);
 /**
  * Resolve the format options.
  * @param options - the caller's options
+ * @param readFrom - the property a Neo4j import read the weights from, the default weightColumn
  * @returns the resolved options; E_UNSUPPORTED for an invalid value
  */
-function resolveNeo4jExportOptions(options) {
+function resolveNeo4jExportOptions(options, readFrom) {
     const o = options ?? {};
     const part = o.part ?? "all";
     if (!PARTS.has(part)) {
@@ -148,12 +176,12 @@ function resolveNeo4jExportOptions(options) {
     const delimiter = o.delimiter ?? ",";
     const syntax = { ...checkRecordSyntax({ delimiter, quote: o.quote ?? '"' }), delimiter };
     if (syntax.delimiter === arrayDelimiter) {
-        throw new GraphFormatError("E_UNSUPPORTED", "options delimiter and arrayDelimiter must differ", {
+        throw new GraphFormatError("E_UNSUPPORTED", `options delimiter and arrayDelimiter must differ: both are ${JSON.stringify(arrayDelimiter)}; pass another arrayDelimiter (";", "," or "|")`, {
             option: "arrayDelimiter",
             found: arrayDelimiter,
         });
     }
-    const weightColumn = o.weightColumn === undefined ? "weight" : o.weightColumn;
+    const weightColumn = o.weightColumn === undefined ? (readFrom ?? "weight") : o.weightColumn;
     if (weightColumn !== null && (typeof weightColumn !== "string" || weightColumn.length === 0)) {
         throw new GraphFormatError("E_UNSUPPORTED", "option weightColumn: expected a non-empty name or null", {
             option: "weightColumn",
@@ -211,6 +239,7 @@ class ExportPlan {
             roles: SLOT_ROLES,
             roleNames: ROLE_NAMES,
             temporalText: true,
+            weights: options.weightColumn !== null,
         });
         this.planColumns("node", snapshot.nodes, this.nodeColumns);
         this.planColumns("edge", snapshot.edges, this.edgeColumns);
@@ -257,7 +286,7 @@ class ExportPlan {
     directionNotes() {
         const { snapshot, folding } = this;
         if (!snapshot.directed) {
-            this.note(UNDIRECTED_LOSS, `the snapshot is undirected; every edge is written as a directed relationship (${snapshot.edgeCount} edge(s))`, null, snapshot.edgeCount);
+            this.note(UNDIRECTED_LOSS, `the snapshot is undirected; every edge is written as a directed relationship (${snapshot.edgeCount} edge${plural(snapshot.edgeCount)})`, null, snapshot.edgeCount);
         }
         else if (this.common.onMixedDirection !== "error") {
             let undirected = 0;
@@ -267,11 +296,11 @@ class ExportPlan {
                 }
             }
             if (undirected > 0) {
-                this.note(UNDIRECTED_LOSS, `${undirected} undirected edge(s) are written as one directed relationship each (source to target, a pair folded to its primary); Neo4j has no undirected relationship`, null, undirected);
+                this.note(UNDIRECTED_LOSS, `${undirected} undirected edge${plural(undirected)} ${agree(undirected, "is", "are")} written as one directed relationship each (source to target, a pair folded to its primary); Neo4j has no undirected relationship`, null, undirected);
             }
         }
         if (folding.mutualCount > 0) {
-            this.note(LOSS.MUTUAL_EXPANDED, `${folding.mutualCount} mutual pair(s) are written as two directed relationships; the mutual mark is lost`, null, folding.mutualCount);
+            this.note(LOSS.MUTUAL_EXPANDED, `${folding.mutualCount} mutual pair${plural(folding.mutualCount)} ${agree(folding.mutualCount, "is", "are")} written as two directed relationships; the mutual mark is lost`, null, folding.mutualCount);
         }
     }
     /**
@@ -444,7 +473,7 @@ class ExportPlan {
             }
         }
         if (rows > 0) {
-            this.note(ARRAY_DELIMITER_LOSS, `${label}: ${rows} row(s) hold an item containing the array delimiter "${arrayDelimiter}", which Neo4j cannot escape`, column.meta.name, rows);
+            this.note(ARRAY_DELIMITER_LOSS, `${label}: ${rows} row${plural(rows)} ${agree(rows, "holds", "hold")} an item containing the array delimiter "${arrayDelimiter}", which Neo4j cannot escape`, column.meta.name, rows);
         }
     }
     /**
@@ -466,7 +495,7 @@ class ExportPlan {
             }
         }
         else if (taken !== undefined && name === DEFAULT_WEIGHT_COLUMN) {
-            this.note(LOSS.WEIGHT_KEY_CLASH, `edge column "${name}" is written under the property the importer reads THE weight from (weightFrom "${name}"); it reads back as the weight, not as a column`, name, taken.column.length - taken.column.nullCount);
+            this.note(LOSS.WEIGHT_KEY_CLASH, `edge column "${name}" is written under the property the importer reads edge weights from (weightFrom "${name}"); it reads back as the weight, not as a column`, name, taken.column.length - taken.column.nullCount);
         }
         return weights.weighted ? weights : null;
     }
@@ -516,11 +545,11 @@ class ExportPlan {
             }
         }
         if (typeChanges > 0) {
-            this.note(ID_TEXT_TYPE_LOSS, `${typeChanges} node id(s) re-import as another type under the canonical id rule (a string of canonical integer text, or a non-integer number)`, null, typeChanges);
+            this.note(ID_TEXT_TYPE_LOSS, `${typeChanges} node id${plural(typeChanges)} re-import as another type under the canonical id rule (a string of canonical integer text, or a non-integer number)`, null, typeChanges);
         }
         if (collisions > 0) {
-            this.note(ID_TEXT_COLLISION_LOSS, `${collisions} node id(s) share their text with another id (a number and a string); export() will throw`, null, collisions);
-            this.fatalAll = new GraphFormatError("E_INVALID_ID", `${collisions} node id(s) share their text with another id; Neo4j ids are text`, { reason: "text collision", count: collisions });
+            this.note(ID_TEXT_COLLISION_LOSS, `${collisions} node id${plural(collisions)} ${agree(collisions, "shares", "share")} their text with another id (a number and a string); the save fails`, null, collisions);
+            this.fatalAll = new GraphFormatError("E_INVALID_ID", `${collisions} node id${plural(collisions)} ${agree(collisions, "shares", "share")} their text with another id; Neo4j ids are text`, { reason: "text collision", count: collisions });
         }
     }
     /** Check that the idColumn option does not name an existing node property. */
@@ -557,7 +586,7 @@ class ExportPlan {
             }
         }
         if (count > 0) {
-            this.note(MULTIPLE_ID_PROPERTIES_LOSS, `${count} node(s) have more than one stored-id column set; only the first in declaration order is written`, null, count);
+            this.note(MULTIPLE_ID_PROPERTIES_LOSS, `${count} node${plural(count)} ${agree(count, "has", "have")} more than one stored-id column set; only the first in declaration order is written`, null, count);
         }
     }
     /**
@@ -654,6 +683,16 @@ class ExportPlan {
      * @returns nothing
      */
     *lines() {
+        for (const row of this.rows()) {
+            yield row.line;
+        }
+    }
+    /**
+     * The lines of the requested part, each header line tagged with the file it starts.
+     * @yields one line at a time, with the file name on a header line
+     * @returns nothing
+     */
+    *rows() {
         if (this.fatal !== null) {
             throw this.fatal;
         }
@@ -665,19 +704,51 @@ class ExportPlan {
             yield* this.relationshipLines();
         }
     }
+    /**
+     * The requested part as one file per section kind: a node file per id space (and stored-id
+     * property), a relationship file per pair of endpoint id spaces, rows of one kind gathered
+     * under one header.
+     * @returns the files, node files first
+     */
+    files() {
+        // keyed by the header row: sections with the same header are one file
+        const files = new Map();
+        const names = new Set();
+        let current = null;
+        for (const row of this.rows()) {
+            if (row.file !== null) {
+                let file = files.get(row.line);
+                if (file === undefined) {
+                    let name = `${row.file.name}.csv`;
+                    let k = 2;
+                    while (names.has(name)) {
+                        name = `${row.file.name}-${k}.csv`;
+                        k++;
+                    }
+                    names.add(name);
+                    file = { name, kind: row.file.kind, rows: [] };
+                    files.set(row.line, file);
+                }
+                current = file;
+            }
+            else if (current !== null) {
+                current.rows.push(row.line);
+            }
+        }
+        // a part with no rows (a graph without edges) is a header alone, which neo4j-admin does not need
+        const written = [...files].filter(([, f], i) => f.rows.length > 0 || (i === 0 && files.size === 1));
+        return written.map(([header, f]) => Object.freeze({ name: f.name, kind: f.kind, text: header + f.rows.join("") }));
+    }
     /**
      * The node sections.
      * @yields one line at a time
      * @returns nothing
      */
     *nodeLines() {
-        const { snapshot, labels, nodeColumns } = this;
-        const { delimiter } = this.options.syntax;
-        const propertyHeaders = nodeColumns.map((plan) => plan.header).join(delimiter);
+        const { snapshot } = this;
         let sections = 0;
         let sectionSpace = null;
         let sectionIdName = null;
-        const cells = [];
         for (let i = 0; i < snapshot.nodeCount; i++) {
             const space = this.spaceOf(i);
             const stored = this.storedIdOf(i);
@@ -686,36 +757,48 @@ class ExportPlan {
                 sections++;
                 sectionSpace = space;
                 sectionIdName = idName;
-                const header = [formatHeaderField(idName, ID_TYPE, space)];
-                if (labels !== null) {
-                    header.push(":LABEL");
-                }
-                if (propertyHeaders.length > 0) {
-                    header.push(propertyHeaders);
-                }
-                yield `${header.join(delimiter)}\n`;
+                yield this.nodeHeader(idName, space, space ?? idName);
             }
-            cells.length = 0;
-            cells.push(this.cell(this.idTextOf(i)));
-            if (labels !== null) {
-                cells.push(this.cell(this.labelsText(i)));
-            }
-            for (const plan of nodeColumns) {
-                cells.push(this.cell(this.valueText(plan, i)));
-            }
-            yield `${cells.join(delimiter)}\n`;
+            yield { line: this.nodeRow(i), file: null };
         }
         if (sections === 0) {
             // no nodes: one header so the section (and its columns) still exists
-            const header = [formatHeaderField(this.options.idColumn ?? "", ID_TYPE, null)];
-            if (labels !== null) {
-                header.push(":LABEL");
-            }
-            if (propertyHeaders.length > 0) {
-                header.push(propertyHeaders);
-            }
-            yield `${header.join(delimiter)}\n`;
+            yield this.nodeHeader(this.options.idColumn ?? "", null, null);
+        }
+    }
+    /**
+     * The header line of a node section, which starts its file.
+     * @param idName - the id column's name
+     * @param space - the id space, or null
+     * @param fileKey - what names the file, or null for the default name
+     * @returns the line
+     */
+    nodeHeader(idName, space, fileKey) {
+        const { delimiter } = this.options.syntax;
+        const header = [formatHeaderField(idName, ID_TYPE, space)];
+        if (this.labels !== null) {
+            header.push(":LABEL");
+        }
+        const properties = this.nodeColumns.map((plan) => plan.header).join(delimiter);
+        if (properties.length > 0) {
+            header.push(properties);
         }
+        return { line: `${header.join(delimiter)}\n`, file: { kind: "nodes", name: fileName("nodes", fileKey, null) } };
+    }
+    /**
+     * One node's line: the id, the labels, the properties.
+     * @param i - the node
+     * @returns the line
+     */
+    nodeRow(i) {
+        const cells = [this.cell(this.idTextOf(i))];
+        if (this.labels !== null) {
+            cells.push(this.cell(this.labelsText(i)));
+        }
+        for (const plan of this.nodeColumns) {
+            cells.push(this.cell(this.valueText(plan, i)));
+        }
+        return `${cells.join(this.options.syntax.delimiter)}\n`;
     }
     /**
      * The relationship sections.
@@ -723,28 +806,11 @@ class ExportPlan {
      * @returns nothing
      */
     *relationshipLines() {
-        const { snapshot, kind, weights, edgeColumns, folding } = this;
-        const { delimiter } = this.options.syntax;
+        const { snapshot, folding } = this;
         const list = snapshot.edgeList();
-        const propertyHeaders = edgeColumns.map((plan) => plan.header).join(delimiter);
-        const weightHeader = weights === null ? null : formatHeaderField(this.options.weightColumn ?? "weight", "double", null);
         let sections = 0;
         let sectionStart = null;
         let sectionEnd = null;
-        const cells = [];
-        const headerOf = (startSpace, endSpace) => {
-            const header = [formatHeaderField("", "START_ID", startSpace), formatHeaderField("", "END_ID", endSpace)];
-            if (kind !== null) {
-                header.push(":TYPE");
-            }
-            if (weightHeader !== null) {
-                header.push(weightHeader);
-            }
-            if (propertyHeaders.length > 0) {
-                header.push(propertyHeaders);
-            }
-            return `${header.join(delimiter)}\n`;
-        };
         for (let e = 0; e < snapshot.edgeCount; e++) {
             if (folding.folded(e)) {
                 continue;
@@ -757,24 +823,58 @@ class ExportPlan {
                 sections++;
                 sectionStart = startSpace;
                 sectionEnd = endSpace;
-                yield headerOf(startSpace, endSpace);
+                yield this.relationshipHeader(startSpace, endSpace);
             }
-            cells.length = 0;
-            cells.push(this.cell(this.idTextOf(u)), this.cell(this.idTextOf(v)));
-            if (kind !== null) {
-                cells.push(this.cell(kind.isSet(e) ? textOf(kind, e) : null));
-            }
-            if (weights !== null) {
-                cells.push(this.cell(weights.text(e)));
-            }
-            for (const plan of edgeColumns) {
-                cells.push(this.cell(this.valueText(plan, e)));
-            }
-            yield `${cells.join(delimiter)}\n`;
+            yield { line: this.relationshipRow(e, u, v), file: null };
         }
         if (sections === 0) {
-            yield headerOf(null, null);
+            yield this.relationshipHeader(null, null);
+        }
+    }
+    /**
+     * The header line of a relationship section, which starts its file.
+     * @param startSpace - the id space of the start nodes, or null
+     * @param endSpace - the id space of the end nodes, or null
+     * @returns the line
+     */
+    relationshipHeader(startSpace, endSpace) {
+        const { delimiter } = this.options.syntax;
+        const header = [formatHeaderField("", "START_ID", startSpace), formatHeaderField("", "END_ID", endSpace)];
+        if (this.kind !== null) {
+            header.push(":TYPE");
+        }
+        if (this.weights !== null) {
+            header.push(formatHeaderField(this.options.weightColumn ?? "weight", "double", null));
+        }
+        const properties = this.edgeColumns.map((plan) => plan.header).join(delimiter);
+        if (properties.length > 0) {
+            header.push(properties);
         }
+        return {
+            line: `${header.join(delimiter)}\n`,
+            file: { kind: "relationships", name: fileName("relationships", startSpace, endSpace) },
+        };
+    }
+    /**
+     * One relationship's line: the ends, the type, the weight, the properties.
+     * @param e - the edge
+     * @param u - its source
+     * @param v - its target
+     * @returns the line
+     */
+    relationshipRow(e, u, v) {
+        const { kind, weights } = this;
+        const cells = [this.cell(this.idTextOf(u)), this.cell(this.idTextOf(v))];
+        if (kind !== null) {
+            cells.push(this.cell(kind.isSet(e) ? textOf(kind, e) : null));
+        }
+        if (weights !== null) {
+            cells.push(this.cell(weights.text(e)));
+        }
+        for (const plan of this.edgeColumns) {
+            cells.push(this.cell(this.valueText(plan, e)));
+        }
+        return `${cells.join(this.options.syntax.delimiter)}\n`;
     }
     /**
      * A CSV cell: empty for an unset value, a quoted empty string for a set empty string, the
@@ -790,7 +890,7 @@ class ExportPlan {
         if (text.length === 0) {
             return quote + quote;
         }
-        return quoteCsvCell(text, this.options.syntax.delimiter);
+        return quoteCsvCell(text, this.options.syntax.delimiter, quote);
     }
     /**
      * The `:LABEL` cell of a node.
@@ -1040,9 +1140,13 @@ function textOf(column, row) {
         }
     }
 }
-/** The Neo4j exporter. */
+/**
+ * The Neo4j exporter.
+ * @category Built-in formats
+ */
 export const neo4jExporter = Object.freeze({
     format: NEO4J,
+    options: Object.freeze(["arrayDelimiter", "delimiter", "idColumn", "part", "quote", "weightColumn"]),
     capabilities: NEO4J_CAPABILITIES,
     /**
      * Pre-flight: what export() would lose.
@@ -1072,6 +1176,45 @@ export const neo4jExporter = Object.freeze({
         return joinText(plan(snapshot, options).lines());
     },
 });
+/**
+ * The file name of a section, without ".csv": the kind, then the id spaces that set it apart.
+ * @param kind - "nodes" or "relationships"
+ * @param first - the id space or id property (nodes), or the start id space (relationships)
+ * @param second - the end id space (relationships)
+ * @returns the name, with characters outside letters, digits, "." , "_" and "-" replaced by "_"
+ */
+function fileName(kind, first, second) {
+    const parts = [kind, first ?? "", second ?? ""].filter((p) => p !== "");
+    return parts.join("-").replaceAll(/[^\w.-]/g, "_");
+}
+/**
+ * Write a graph as the separate CSV files `neo4j-admin database import` takes: one node file per id
+ * space and one relationship file per pair of endpoint id spaces, each with a single header row.
+ * `exportGraph(snapshot, "neo4j")` writes the same sections into one file, which graph-io reads
+ * back but neo4j-admin does not, since it reads one header per file. The options are the Neo4j
+ * export options (`part` limits the result to the node or the relationship files), and
+ * `checkExport(snapshot, "neo4j", options)` returns what the files lose.
+ * @param snapshot - the graph to write
+ * @param options - the Neo4j export options
+ * @returns the files, node files first
+ * @category Built-in formats
+ * @example
+ * ```ts
+ * for (const file of await exportNeo4jFiles(snapshot)) {
+ *     await writeFile(file.name, file.text);
+ * }
+ * // neo4j-admin database import full --nodes=nodes-Movie.csv --nodes=nodes-Person.csv \
+ * //     --relationships=relationships-Person-Movie.csv neo4j
+ * ```
+ */
+export function exportNeo4jFiles(snapshot, options) {
+    try {
+        return Promise.resolve(plan(snapshot, options).files());
+    }
+    catch (err) {
+        return Promise.reject(err);
+    }
+}
 /**
  * Build the export plan of a snapshot.
  * @param snapshot - the snapshot
@@ -1079,6 +1222,16 @@ export const neo4jExporter = Object.freeze({
  * @returns the plan
  */
 function plan(snapshot, options) {
-    return new ExportPlan(snapshot, resolveNeo4jExportOptions(options), resolveExportOptions(options));
+    return new ExportPlan(snapshot, resolveNeo4jExportOptions(options, weightPropertyOf(snapshot)), resolveExportOptions(options));
+}
+/**
+ * The relationship property a Neo4j import read the weights from, when it was not "weight".
+ * @param snapshot - the snapshot
+ * @returns the property name, or null
+ */
+function weightPropertyOf(snapshot) {
+    const neo4j = snapshot.meta.extra?.neo4j;
+    const name = neo4j?.weightProperty;
+    return typeof name === "string" && name !== "" ? name : null;
 }
 //# sourceMappingURL=exporter.js.map