@graphty/graph-io 0.3.24 → 0.3.26

package/src/formats/neo4j/exporter.ts

@@ -39,6 +39,7 @@ import { capabilities, checkCapabilities, LOSS } from "../../common/export.js";
 import { formatF32, formatF64, formatInteger } from "../../common/format.js";
 import { isCanonicalIntegerText } from "../../common/ids.js";
 import { type ResolvedExportOptions, resolveExportOptions } from "../../common/options.js";
+import { agree, plural } from "../../common/plural.js";
 import { formatTemporal, type TemporalKind } from "../../common/temporal.js";
 import { type ExplicitWeights, explicitWeights } from "../../common/weights.js";
 import { encodeChunks, joinText } from "../../common/writer.js";
@@ -47,50 +48,100 @@ import { checkRecordSyntax, type RecordSyntax } from "../csv/records.js";
 import { formatHeaderField } from "./header.js";
 import { ID_SPACE_COLUMN, LABELS_COLUMN, TYPE_COLUMN } from "./importer.js";
 
-/** The format-specific options of the Neo4j exporter. */
-export interface Neo4jExportOptions {
-    /** Which tables to write: both (node sections first; default), the node sections or the relationship sections. */
+/**
+ * The format-specific options of the Neo4j exporter.
+ * @category Built-in formats
+ */
+export interface Neo4jExportOptions extends CommonExportOptions {
+    /**
+     * Which tables to write: "all" (the node sections, then the relationship sections), "nodes" or
+     * "relationships".
+     * @defaultValue "all"
+     */
     part?: "all" | "nodes" | "relationships" | undefined;
-    /** The field delimiter; one character; "," by default. */
+    /**
+     * The field delimiter, one character. It must differ from `arrayDelimiter`: with
+     * `delimiter: ";"`, also pass `arrayDelimiter: ","` or `"|"`.
+     * @defaultValue ","
+     */
     delimiter?: string | undefined;
-    /** The array delimiter of list values and `:LABEL` cells; ";" by default. */
+    /**
+     * The delimiter inside list values and `:LABEL` cells. It must differ from `delimiter`.
+     * @defaultValue ";"
+     */
     arrayDelimiter?: ";" | "," | "|" | undefined;
-    /** The quote character; one character; a double quote by default. */
+    /**
+     * The quote character, one character. Cells that hold the delimiter, the quote character or a
+     * line break are quoted with it. Pass the same value as the `quote` import option to read the
+     * file back.
+     * @defaultValue '"'
+     */
     quote?: string | undefined;
     /**
-     * The property that receives explicit edge weights (`<name>:double`); "weight" by default (the
-     * importer's `weightFrom` default); null writes no weights.
+     * The relationship property that holds the edge weights, written as `<name>:double`; null
+     * writes no weights (checkExport() then returns W_WEIGHTS_DROPPED). graph-io reads the
+     * "weight" property back as the weight; for any other name, pass the same name as the
+     * `weightFrom` import option to read the weights back (`weightColumn: "strength"` with
+     * `weightFrom: "strength"`), or they come back as a plain edge attribute. A graph read from Neo4j
+     * CSV with `weightFrom` writes its weights back under the property they were read from.
+     * @defaultValue "weight", or the property a Neo4j import read the weights from
      */
     weightColumn?: string | null | undefined;
     /**
-     * The property name of the `:ID` column for nodes that have no stored-id column of their own
-     * (`<name>:ID`); null (default) writes a bare `:ID`.
+     * The property name of the `:ID` column (`<name>:ID`) for nodes that have no id property of
+     * their own; null writes a bare `:ID`.
+     * @defaultValue null
      */
     idColumn?: string | null | undefined;
 }
 
-/** 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)`. */
@@ -110,10 +161,11 @@ const ROLE_NAMES: Readonly<Record<string, string>> = Object.freeze({
 });
 
 /**
- * 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: ExportCapabilities = capabilities({
     mixedDirection: false,
@@ -211,9 +263,13 @@ interface ColumnPlan {
 /**
  * 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: Neo4jExportOptions | undefined): ResolvedNeo4jExportOptions {
+function resolveNeo4jExportOptions(
+    options: Neo4jExportOptions | undefined,
+    readFrom: string | null,
+): ResolvedNeo4jExportOptions {
     const o: Neo4jExportOptions = options ?? {};
     const part = o.part ?? "all";
     if (!PARTS.has(part)) {
@@ -237,12 +293,16 @@ function resolveNeo4jExportOptions(options: Neo4jExportOptions | undefined): Res
     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", {
-            option: "arrayDelimiter",
-            found: arrayDelimiter,
-        });
+        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",
@@ -329,6 +389,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);
@@ -380,7 +441,7 @@ class ExportPlan {
         if (!snapshot.directed) {
             this.note(
                 UNDIRECTED_LOSS,
-                `the snapshot is undirected; every edge is written as a directed relationship (${snapshot.edgeCount} edge(s))`,
+                `the snapshot is undirected; every edge is written as a directed relationship (${snapshot.edgeCount} edge${plural(snapshot.edgeCount)})`,
                 null,
                 snapshot.edgeCount,
             );
@@ -394,7 +455,7 @@ 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`,
+                    `${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,
                 );
@@ -403,7 +464,7 @@ class ExportPlan {
         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`,
+                `${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,
             );
@@ -612,7 +673,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`,
+                `${label}: ${rows} row${plural(rows)} ${agree(rows, "holds", "hold")} an item containing the array delimiter "${arrayDelimiter}", which Neo4j cannot escape`,
                 column.meta.name,
                 rows,
             );
@@ -648,7 +709,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`,
+                `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,
             );
@@ -703,7 +764,7 @@ 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)`,
+                `${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,
             );
@@ -711,13 +772,13 @@ class ExportPlan {
         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`,
+                `${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(s) share their text with another id; Neo4j ids are text`,
+                `${collisions} node id${plural(collisions)} ${agree(collisions, "shares", "share")} their text with another id; Neo4j ids are text`,
                 { reason: "text collision", count: collisions },
             );
         }
@@ -770,7 +831,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`,
+                `${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,
             );
@@ -877,6 +938,17 @@ class ExportPlan {
      * @returns nothing
      */
     *lines(): Generator<string, void, undefined> {
+        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(): Generator<SectionLine, void, undefined> {
         if (this.fatal !== null) {
             throw this.fatal;
         }
@@ -889,19 +961,53 @@ class ExportPlan {
         }
     }
 
+    /**
+     * 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(): Neo4jFile[] {
+        // keyed by the header row: sections with the same header are one file
+        const files = new Map<string, { name: string; kind: "nodes" | "relationships"; rows: string[] }>();
+        const names = new Set<string>();
+        let current: { rows: string[] } | null = 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
      */
-    private *nodeLines(): Generator<string, void, undefined> {
-        const { snapshot, labels, nodeColumns } = this;
-        const { delimiter } = this.options.syntax;
-        const propertyHeaders = nodeColumns.map((plan) => plan.header).join(delimiter);
+    private *nodeLines(): Generator<SectionLine, void, undefined> {
+        const { snapshot } = this;
         let sections = 0;
         let sectionSpace: string | null = null;
         let sectionIdName: string | null = null;
-        const cells: string[] = [];
         for (let i = 0; i < snapshot.nodeCount; i++) {
             const space = this.spaceOf(i);
             const stored = this.storedIdOf(i);
@@ -910,36 +1016,50 @@ 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
+     */
+    private nodeHeader(idName: string, space: string | null, fileKey: string | null): SectionLine {
+        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
+     */
+    private nodeRow(i: number): string {
+        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`;
     }
 
     /**
@@ -947,30 +1067,12 @@ class ExportPlan {
      * @yields one line at a time
      * @returns nothing
      */
-    private *relationshipLines(): Generator<string, void, undefined> {
-        const { snapshot, kind, weights, edgeColumns, folding } = this;
-        const { delimiter } = this.options.syntax;
+    private *relationshipLines(): Generator<SectionLine, void, undefined> {
+        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: string | null = null;
         let sectionEnd: string | null = null;
-        const cells: string[] = [];
-        const headerOf = (startSpace: string | null, endSpace: string | null): string => {
-            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;
@@ -983,24 +1085,60 @@ class ExportPlan {
                 sections++;
                 sectionStart = startSpace;
                 sectionEnd = endSpace;
-                yield headerOf(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 this.relationshipHeader(startSpace, endSpace);
             }
-            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
+     */
+    private relationshipHeader(startSpace: string | null, endSpace: string | null): SectionLine {
+        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
+     */
+    private relationshipRow(e: number, u: number, v: number): string {
+        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`;
     }
 
     /**
@@ -1017,7 +1155,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);
     }
 
     /**
@@ -1281,9 +1419,13 @@ function textOf(column: Column, row: number): string {
     }
 }
 
-/** The Neo4j exporter. */
+/**
+ * The Neo4j exporter.
+ * @category Built-in formats
+ */
 export const neo4jExporter: GraphExporter<Neo4jExportOptions> = Object.freeze({
     format: NEO4J,
+    options: Object.freeze(["arrayDelimiter", "delimiter", "idColumn", "part", "quote", "weightColumn"]),
     capabilities: NEO4J_CAPABILITIES,
     /**
      * Pre-flight: what export() would lose.
@@ -1314,6 +1456,68 @@ export const neo4jExporter: GraphExporter<Neo4jExportOptions> = Object.freeze({
     },
 });
 
+/** One line of the export; a header line names the file it starts. */
+interface SectionLine {
+    readonly line: string;
+    readonly file: { readonly kind: "nodes" | "relationships"; readonly name: string } | null;
+}
+
+/**
+ * One file of exportNeo4jFiles(): the header row and the rows of one section kind.
+ * @category Built-in formats
+ */
+export interface Neo4jFile {
+    /** A file name made from the section: `nodes-Movie.csv`, `relationships-Person-Movie.csv`, or `nodes.csv` and `relationships.csv` without id spaces. */
+    readonly name: string;
+    /** Whether neo4j-admin takes the file with `--nodes` or with `--relationships`. */
+    readonly kind: "nodes" | "relationships";
+    /** The CSV text, one header row first. */
+    readonly text: string;
+}
+
+/**
+ * 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: string, first: string | null, second: string | null): string {
+    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: GraphSnapshot,
+    options?: Neo4jExportOptions & CommonExportOptions,
+): Promise<Neo4jFile[]> {
+    try {
+        return Promise.resolve(plan(snapshot, options).files());
+    } catch (err) {
+        return Promise.reject(err as Error);
+    }
+}
+
 /**
  * Build the export plan of a snapshot.
  * @param snapshot - the snapshot
@@ -1321,5 +1525,20 @@ export const neo4jExporter: GraphExporter<Neo4jExportOptions> = Object.freeze({
  * @returns the plan
  */
 function plan(snapshot: GraphSnapshot, options: (Neo4jExportOptions & CommonExportOptions) | undefined): ExportPlan {
-    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: GraphSnapshot): string | null {
+    const neo4j = (snapshot.meta.extra as { neo4j?: { weightProperty?: unknown } } | null)?.neo4j;
+    const name = neo4j?.weightProperty;
+    return typeof name === "string" && name !== "" ? name : null;
 }