@graphty/graph-io 0.3.24 → 0.3.26

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

@@ -35,52 +35,113 @@
  */
 import { GraphFormatError, INVALID_INDEX, } from "@graphty/graph-format";
 import { declareAttribute, declareCompanion, declareOn, losesPrecision, parseDeclaredTemporal, parseDeclaredValue, PRECISION_CODE, RENAMED_CODE, takenIn, uniqueColumnName, } from "../../common/attributes.js";
-import { DUPLICATE_NODE_CODE as SHARED_DUPLICATE_NODE_CODE, MISSING_ENDPOINT_CODE as SHARED_MISSING_ENDPOINT_CODE, MISSING_ID_CODE as SHARED_MISSING_ID_CODE, ROLE_TAKEN_CODE as SHARED_ROLE_TAKEN_CODE, } from "../../common/codes.js";
+import { DANGLING_REFERENCE_CODE as SHARED_DANGLING_REFERENCE_CODE, DUPLICATE_NODE_CODE as SHARED_DUPLICATE_NODE_CODE, MISSING_ENDPOINT_CODE as SHARED_MISSING_ENDPOINT_CODE, MISSING_ID_CODE as SHARED_MISSING_ID_CODE, ROLE_TAKEN_CODE as SHARED_ROLE_TAKEN_CODE, } from "../../common/codes.js";
 import { DirectionResolver } from "../../common/direction.js";
 import { ID_MERGED_CODE as SHARED_ID_MERGED_CODE, IdCoercer } from "../../common/ids.js";
 import { inputLength, isImportInput, throwIfAborted } from "../../common/input.js";
 import { splitListText } from "../../common/lists.js";
 import { reportSinkOptions, reportUnusedOptions, resolveImportOptions, } from "../../common/options.js";
+import { agree, plural, withArticle } from "../../common/plural.js";
 import { ImportReportBuilder } from "../../common/report.js";
+import { parseTemporal } from "../../common/temporal.js";
 import { parseWeightText } from "../../common/weights.js";
 import { ImportError, } from "../../types.js";
 import { checkRecordSyntax, RecordReader } from "../csv/records.js";
 import { isHeaderRecord, parseHeaderField } from "./header.js";
-/** The name of the node list column holding `:LABEL` values. */
+/**
+ * The name of the node list column holding `:LABEL` values.
+ * @category Built-in formats
+ */
 export const LABELS_COLUMN = "labels";
-/** The name of the edge dict column holding `:TYPE` values. */
+/**
+ * The name of the edge dict column holding `:TYPE` values.
+ * @category Built-in formats
+ */
 export const TYPE_COLUMN = "type";
-/** The name of the node dict column holding the id space of `:ID(Space)`. */
+/**
+ * The name of the node dict column holding the id space of `:ID(Space)`.
+ * @category Built-in formats
+ */
 export const ID_SPACE_COLUMN = "idSpace";
-/** The name of the node string column holding the id text of a node of an id space (its id is `Space:id`). */
+/**
+ * Neo4j CSV: the name of the node column that holds a node's id as the file wrote it, for a node of an id
+ * space (`:ID(Person)`), whose node id is `Person:<id>`. It has nothing to do with the `originalId` role that
+ * `sanitizeIds: "mangle"` uses.
+ * @category Built-in formats
+ */
 export const ORIGINAL_ID_COLUMN = "originalId";
-/** Issue code: a header row (or a whole section) is malformed; the import aborts. */
+/**
+ * A header row (or a whole section) is malformed; the import aborts.
+ * @category Issue and loss codes
+ */
 export const HEADER_CODE = "E_NEO4J_HEADER";
-/** Issue code: a row has a different number of cells than its header. */
+/**
+ * A row has a different number of cells than its header.
+ * @category Issue and loss codes
+ */
 export const COLUMN_COUNT_CODE = "E_NEO4J_COLUMN_COUNT";
-/** Issue code: a node row has an unquoted empty `:ID` cell (a quoted empty cell is the id ""). */
+/**
+ * A node row has an unquoted empty `:ID` cell (a quoted empty cell is the id "").
+ * @category Issue and loss codes
+ */
 export const MISSING_ID_CODE = SHARED_MISSING_ID_CODE;
-/** Issue code: a relationship row has an unquoted empty `:START_ID` or `:END_ID` cell. */
+/**
+ * A relationship row has an unquoted empty `:START_ID` or `:END_ID` cell.
+ * @category Issue and loss codes
+ */
 export const MISSING_ENDPOINT_CODE = SHARED_MISSING_ENDPOINT_CODE;
-/** Issue code: a node id was declared twice (same id space); the later row's properties win. */
+/**
+ * A node id was declared twice (same id space); the later row's properties win.
+ * @category Issue and loss codes
+ */
 export const DUPLICATE_NODE_CODE = SHARED_DUPLICATE_NODE_CODE;
 /**
- * Issue code: a node id was declared in two id spaces -- a spaced id `Space:id` equals the text of an
- * id declared without a space; the later row is skipped.
+ * A node id was declared in two id spaces -- a spaced id `Space:id` equals the text of an id declared without a space;
+ * the later row is skipped.
+ * @category Issue and loss codes
  */
 export const ID_SPACE_COLLISION_CODE = "E_NEO4J_ID_SPACE_COLLISION";
 /**
- * Issue code: a `:START_ID(Space)` / `:END_ID(Space)` endpoint's qualified id `Space:id` names a node a
- * node row declared in another id space (without a space); the row is skipped.
+ * A `:START_ID(Space)` / `:END_ID(Space)` endpoint's qualified id `Space:id` names a node a node row declared in
+ * another id space (without a space); the row is skipped.
+ * @category Issue and loss codes
  */
 export const ENDPOINT_SPACE_CODE = "E_NEO4J_ENDPOINT_SPACE";
-/** Issue code: two different id cells became one id under `ids: "number"`. */
+/**
+ * Two different id cells became one id under `ids: "number"`.
+ * @category Issue and loss codes
+ */
 export const ID_MERGED_CODE = SHARED_ID_MERGED_CODE;
-/** Issue code: a header brace option the importer does not act on. */
+/**
+ * A header brace option the importer does not act on.
+ * @category Issue and loss codes
+ */
 export const HEADER_OPTION_CODE = "W_NEO4J_HEADER_OPTION_IGNORED";
-/** Issue code: a reserved column (labels / type / idSpace) lost its role because the sink already holds it. */
+/**
+ * You read into a graph builder that already has the labels, type or id space attribute, so this file's one is kept
+ * without its role.
+ * @category Issue and loss codes
+ */
 export const ROLE_TAKEN_CODE = SHARED_ROLE_TAKEN_CODE;
-/** Loss code: `:IGNORE` columns were skipped. */
+/**
+ * A relationship row with an empty `:TYPE` cell (neo4j-admin requires a type); the relationship is kept.
+ * @category Issue and loss codes
+ */
+export const MISSING_TYPE_CODE = "W_NEO4J_MISSING_TYPE";
+/**
+ * A file given under the `nodes` option holds a relationship header, or the reverse.
+ * @category Issue and loss codes
+ */
+export const SECTION_KIND_CODE = "W_NEO4J_SECTION_KIND";
+/**
+ * Relationship endpoints that no node row declares became nodes (the shared W_DANGLING_REFERENCE).
+ * @category Issue and loss codes
+ */
+export const DANGLING_REFERENCE_CODE = SHARED_DANGLING_REFERENCE_CODE;
+/**
+ * `:IGNORE` columns were skipped.
+ * @category Built-in formats
+ */
 export const IGNORED_COLUMNS_LOSS = "W_NEO4J_IGNORED_COLUMNS";
 /** The common options the Neo4j importer reads (the rest is reported by reportUnusedOptions). */
 const USED_OPTIONS = new Set([
@@ -143,13 +204,16 @@ function resolveNeo4jOptions(options) {
     if (typeof arrayDelimiter !== "string" || listSyntax === undefined) {
         throw new GraphFormatError("E_UNSUPPORTED", `option arrayDelimiter: ${JSON.stringify(arrayDelimiter)} is not one of ";", ",", "|"`, { option: "arrayDelimiter", found: arrayDelimiter });
     }
+    if (arrayDelimiter === "," && o.delimiter === undefined) {
+        throw new GraphFormatError("E_UNSUPPORTED", 'option arrayDelimiter "," needs the delimiter option: the field delimiter is a comma unless another is given', { option: "arrayDelimiter", found: arrayDelimiter });
+    }
     const syntax = checkRecordSyntax({
         delimiter: o.delimiter ?? null,
         quote: o.quote ?? '"',
         candidates: NEO4J_DELIMITER_CANDIDATES.filter((d) => d !== arrayDelimiter),
     });
     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,
         });
@@ -162,7 +226,7 @@ function resolveNeo4jOptions(options) {
     };
 }
 /**
- * Normalise an input-list option.
+ * Normalize an input-list option.
  * @param name - the option name
  * @param value - one input, a list of inputs, or undefined
  * @returns the inputs; E_UNSUPPORTED for anything else
@@ -299,6 +363,8 @@ class Neo4jImportSession {
      */
     constructor(sink, report, common, options) {
         this.registry = new NodeRegistry();
+        /** The relationship property the weights were read from, when it is not "weight"; the exporter writes it back under that name. */
+        this.weightProperty = null;
         this.labelsHandle = INVALID_INDEX;
         this.typeHandle = INVALID_INDEX;
         this.idSpaceHandle = INVALID_INDEX;
@@ -312,6 +378,14 @@ class Neo4jImportSession {
         this.texts = [];
         /** Scratch: the property slots of the current row that lost precision. */
         this.precisionSlots = [];
+        /** Scratch: the values of the current row that overflowed their float / double type. */
+        this.overflows = [];
+        /** The section kind the option of the input being read names, or null for the primary input. */
+        this.expectedKind = null;
+        /** Whether any node row was read. */
+        this.nodeRows = false;
+        /** Nodes relationship endpoints created (no node row declared them yet), the first few by id. */
+        this.placeholders = [];
         this.sink = sink;
         this.report = report;
         this.common = common;
@@ -320,33 +394,59 @@ class Neo4jImportSession {
         this.direction = new DirectionResolver(sink, report, common.onMixedDirection);
     }
     /**
-     * Read every input.
-     * @param inputs - the inputs in reading order
+     * Read every input. A header-only input lends its header to the headerless input after it (the
+     * neo4j-admin convention `--nodes=header.csv,part1.csv`); an empty input is an error only when
+     * it is the only one.
+     * @param inputs - the inputs in reading order, each with the kind of section its option names (null for the primary input)
      */
     async run(inputs) {
-        const progress = new ProgressTracker(this.common.onProgress, inputs);
-        for (const input of inputs) {
-            await this.readInput(input, { ...progress.optionsFor(this.common.signal), encoding: this.common.encoding });
+        const progress = new ProgressTracker(this.common.onProgress, inputs.map((i) => i.input));
+        let carried = null;
+        for (const { input, kind } of inputs) {
+            this.expectedKind = kind;
+            if (carried !== null && kind !== null && carried.kind !== kind) {
+                // a nodes header never lends itself to a relationships file, nor the reverse
+                carried = null;
+            }
+            carried = await this.readInput(input, { ...progress.optionsFor(this.common.signal), encoding: this.common.encoding }, carried, inputs.length > 1);
             progress.finishInput();
         }
         if (this.ignoredColumns > 0) {
-            this.report.loss(IGNORED_COLUMNS_LOSS, `${this.ignoredColumns} :IGNORE column(s) were skipped as the header instructs`, null, this.ignoredColumns);
+            this.report.loss(IGNORED_COLUMNS_LOSS, `${this.ignoredColumns} :IGNORE column${plural(this.ignoredColumns)} ${agree(this.ignoredColumns, "was", "were")} skipped as the header instructs`, null, this.ignoredColumns);
         }
+        this.reportDangling();
     }
     /**
      * Read one input: a header row, then data rows until the next header row.
      * @param input - the input
      * @param readOptions - cancellation and progress
+     * @param carried - the section of a header-only input just before this one, or null
+     * @param mayBeEmpty - whether an input without any record is allowed (other inputs exist)
+     * @returns this input's section when it held a header and no data row (lent to the next input), else null
      */
-    async readInput(input, readOptions) {
-        const reader = new RecordReader(input, this.report, this.options.syntax, readOptions);
-        let section = null;
+    async readInput(input, readOptions, carried, mayBeEmpty) {
+        const reader = new RecordReader(input, this.report, this.options.syntax, {
+            ...readOptions,
+            allowEmpty: mayBeEmpty,
+        });
+        let section = carried;
+        let records = 0;
+        let rows = 0;
         let sinceCheck = 0;
         for await (const count of reader) {
-            if (section === null || isHeaderRecord(reader.cells, count)) {
+            const { cells, quoted } = reader;
+            if (records === 0 && count === 1 && !quoted[0] && cells[0].trim().length === 0) {
+                // a whitespace-only line before anything else is a blank line, not an empty header
+                continue;
+            }
+            records++;
+            // a quoted marker cell is data ("ref:id") unless the whole record is a quoted header
+            if (section === null || isHeaderRecord(cells, count, quoted)) {
                 section = this.declareSection(reader, count);
+                rows = 0;
                 continue;
             }
+            rows++;
             if (section.kind === "node") {
                 this.nodeRow(section, reader, count);
             }
@@ -358,9 +458,14 @@ class Neo4jImportSession {
                 throwIfAborted(readOptions.signal);
             }
         }
-        if (section === null) {
+        if (records === 0 && carried === null && !mayBeEmpty) {
             this.report.fail(HEADER_CODE, "the input has no header row", { line: 1 });
         }
+        // the header lent on: a header-only input's, or the one lent to this input when it had none
+        if (section === carried) {
+            return carried;
+        }
+        return rows === 0 ? section : null;
     }
     /**
      * Interpret a header row: parse every cell, check the section shape, declare its columns.
@@ -394,7 +499,13 @@ class Neo4jImportSession {
                 throw headerError("a header mixes :ID with :START_ID / :END_ID");
             }
             if (!isNode && !isRelationship) {
-                throw headerError("a header needs an :ID column (nodes) or :START_ID and :END_ID columns (relationships)");
+                const apoc = fields.some((f) => f.name === "_id" || f.name === "_start");
+                throw headerError(apoc
+                    ? "a header needs an :ID column (nodes) or :START_ID and :END_ID columns (relationships); this is the apoc.export.csv layout (_id, _labels, _start, _end, _type), which is not the neo4j-admin import format"
+                    : "a header needs an :ID column (nodes) or :START_ID and :END_ID columns (relationships)");
+            }
+            if (this.expectedKind !== null && this.expectedKind !== (isNode ? "node" : "relationship")) {
+                this.report.warning("validation-error", SECTION_KIND_CODE, `a ${isNode ? "node" : "relationship"} header in a file given as ${this.expectedKind === "node" ? "nodes" : "relationships"}; read by its header`, { line });
             }
             checkPropertyNames(fields);
             this.ignoredColumns += (kinds.get("IGNORE") ?? []).length;
@@ -421,7 +532,12 @@ class Neo4jImportSession {
         }
         catch (err) {
             if (err instanceof GraphFormatError && !(err instanceof ImportError)) {
-                this.report.fail(HEADER_CODE, `line ${line}: ${err.message}`, { line }, { cause: err.code });
+                // a header written with another delimiter reads as one cell holding it
+                const other = [";", "|", "\t", ","].find((d) => d !== reader.delimiter && reader.cells.slice(0, count).some((c) => c.includes(d)));
+                const hint = other === undefined
+                    ? ""
+                    : `; if the file is delimited by ${JSON.stringify(other)}, pass the delimiter option`;
+                this.report.fail(HEADER_CODE, `${err.message}${hint}`, { line }, { cause: err.code });
             }
             throw err;
         }
@@ -492,6 +608,9 @@ class Neo4jImportSession {
         let weightCell = -1;
         if (weightFrom !== null) {
             weightCell = fields.findIndex((field) => field.kind === "PROPERTY" && field.name === weightFrom);
+            if (weightCell >= 0 && weightFrom !== "weight") {
+                this.weightProperty = weightFrom;
+            }
         }
         const properties = this.declareProperties("edge", fields, line, weightCell);
         const { space: startSpace } = fields[startCell];
@@ -645,7 +764,7 @@ class Neo4jImportSession {
         const { sink, report } = this;
         const { cells, quoted, line } = reader;
         if (count !== section.width) {
-            report.error("validation-error", COLUMN_COUNT_CODE, `row has ${count} cell(s) but the header has ${section.width}`, { line });
+            report.error("validation-error", COLUMN_COUNT_CODE, `row has ${count} cell${plural(count)} but the header has ${section.width}`, { line });
             report.counts.skippedNodes++;
             return;
         }
@@ -666,7 +785,17 @@ class Neo4jImportSession {
         if (section.labelCells.length > 0 || section.extraLabels.length > 0) {
             labels = this.labelsOf(section, cells, quoted);
         }
-        const index = sink.addNode(id);
+        this.nodeRows = true;
+        const existed = sink.indexOf(id) !== INVALID_INDEX;
+        let index;
+        try {
+            index = sink.addNode(id);
+        }
+        catch (err) {
+            report.recordError(err, { line, element: idText });
+            report.counts.skippedNodes++;
+            return;
+        }
         const status = this.registry.declare(index, section.spaceCode);
         if (status === "collision") {
             report.error("validation-error", ID_SPACE_COLLISION_CODE, `node ${idText} is declared in id space ${section.space ?? "(none)"} and in another id space; the core has one id space and this row is skipped`, { line, element: idText });
@@ -679,19 +808,63 @@ class Neo4jImportSession {
                 element: idText,
             });
         }
+        // a write the sink refuses is recorded and the rest of the row is still written
+        const set = (column, value) => {
+            this.guarded(line, idText, () => {
+                sink.setNodeValue(column, index, value);
+            });
+        };
         if (section.idHandle !== INVALID_INDEX) {
-            sink.setNodeValue(section.idHandle, index, idText);
+            set(section.idHandle, idText);
         }
         if (section.space !== null) {
-            sink.setNodeValue(this.idSpaceHandle, index, section.space);
-            sink.setNodeValue(this.originalIdHandle, index, idText);
+            set(this.idSpaceHandle, section.space);
+            set(this.originalIdHandle, idText);
         }
         if (labels !== undefined) {
-            sink.setNodeValue(this.labelsHandle, index, labels);
+            set(this.labelsHandle, labels);
         }
-        this.writeProperties("node", section.properties, index);
+        this.writeProperties("node", section.properties, index, line, idText);
         this.reportPrecision(line, idText);
-        report.counts.nodes++;
+        // a node a relationship created before its row (or an earlier row) is counted once
+        if (!existed) {
+            report.counts.nodes++;
+        }
+    }
+    /**
+     * Run one sink write, recording a refusal (a GraphFormatError) on the row's line instead of
+     * letting it escape the import.
+     * @param line - the row's line
+     * @param element - the row's element name
+     * @param write - the write
+     */
+    guarded(line, element, write) {
+        try {
+            write();
+        }
+        catch (err) {
+            if (!(err instanceof GraphFormatError) || err instanceof ImportError) {
+                throw err;
+            }
+            this.report.recordError(err, { line, element });
+        }
+    }
+    /**
+     * Report the relationship endpoints no node row declared (the shared W_DANGLING_REFERENCE,
+     * once) when the input has node rows: each became a node, where neo4j-admin refuses the
+     * relationship.
+     */
+    reportDangling() {
+        const dangling = this.placeholders.filter((p) => this.registry.codeAt(p.index) === 0);
+        // without any node row, every node comes from the relationships (a relationships-only file)
+        if (dangling.length === 0 || !this.nodeRows) {
+            return;
+        }
+        const shown = dangling
+            .slice(0, 5)
+            .map((p) => String(p.id))
+            .join(", ");
+        this.report.warning("validation-error", DANGLING_REFERENCE_CODE, `${dangling.length} relationship endpoint${plural(dangling.length)} ${agree(dangling.length, "names", "name")} no node row and became nodes: ${shown}${dangling.length > 5 ? ", ..." : ""} (neo4j-admin refuses such relationships)`, { element: String(dangling[0].id) });
     }
     /**
      * Push one relationship row.
@@ -709,7 +882,7 @@ class Neo4jImportSession {
             this.direction.setHeader(true, { line });
         }
         if (count !== section.width) {
-            report.error("validation-error", COLUMN_COUNT_CODE, `row has ${count} cell(s) but the header has ${section.width}`, { line });
+            report.error("validation-error", COLUMN_COUNT_CODE, `row has ${count} cell${plural(count)} but the header has ${section.width}`, { line });
             report.counts.skippedEdges++;
             return;
         }
@@ -747,7 +920,7 @@ class Neo4jImportSession {
         let weight;
         if (section.weightCell >= 0) {
             try {
-                weight = parseWeightText(cells[section.weightCell]);
+                weight = parseWeightText(cells[section.weightCell], this.report);
             }
             catch (err) {
                 report.recordError(err, { line, element });
@@ -759,6 +932,7 @@ class Neo4jImportSession {
             report.counts.skippedEdges++;
             return;
         }
+        const created = [source, target].filter((id, k) => (k === 0 || id !== source) && sink.indexOf(id) === INVALID_INDEX);
         let edge;
         try {
             edge = this.direction.addEdge(source, target, "directed", weight, { line, element });
@@ -768,13 +942,23 @@ class Neo4jImportSession {
             report.counts.skippedEdges++;
             return;
         }
+        for (const id of created) {
+            // a node no row declared yet: counted now; reported at the end unless a node row follows
+            report.counts.nodes++;
+            this.placeholders.push({ id, index: sink.indexOf(id) });
+        }
         if (section.typeCell >= 0) {
             const type = cells[section.typeCell];
             if (type.length > 0) {
-                sink.setEdgeValue(this.typeHandle, edge, type);
+                this.guarded(line, element, () => {
+                    sink.setEdgeValue(this.typeHandle, edge, type);
+                });
+            }
+            else {
+                report.warning("missing-value", MISSING_TYPE_CODE, "empty :TYPE cell; neo4j-admin requires a relationship type, the relationship is kept without one", { line, element });
             }
         }
-        this.writeProperties("edge", section.properties, edge);
+        this.writeProperties("edge", section.properties, edge, line, element);
         this.reportPrecision(line, element);
         report.counts.edges++;
     }
@@ -831,6 +1015,7 @@ class Neo4jImportSession {
     parseProperties(slots, cells, quoted, line, element) {
         const { values, texts, precisionSlots } = this;
         precisionSlots.length = 0;
+        this.overflows.length = 0;
         for (const slot of slots) {
             const text = cells[slot.cell];
             texts[slot.cell] = null;
@@ -841,18 +1026,24 @@ class Neo4jImportSession {
             const { spec } = slot;
             try {
                 if (spec.temporal !== null && !spec.list) {
-                    const parsed = parseDeclaredTemporal(text, spec);
+                    const zoned = withZoneOffset(text, spec);
+                    const parsed = parseDeclaredTemporal(zoned, spec);
                     values[slot.cell] = parsed.value;
-                    texts[slot.cell] = parsed.text;
+                    // a zone name is kept in the companion text, the value is its instant
+                    texts[slot.cell] = zoned === text ? parsed.text : text;
                 }
                 else {
                     values[slot.cell] = parseDeclaredValue(text, spec, this.options.listSyntax);
+                    checkNeo4jRange(spec, values[slot.cell], text);
                 }
             }
             catch (err) {
                 this.report.recordError(err, { line, element: `${element} ${slot.name}` });
                 return false;
             }
+            if (overflows(spec, values[slot.cell], text)) {
+                this.overflows.push(slot.name);
+            }
             if (spec.precision && losesPrecision(spec, text)) {
                 precisionSlots.push(slot);
             }
@@ -864,8 +1055,10 @@ class Neo4jImportSession {
      * @param domain - node or edge
      * @param slots - the section's property slots
      * @param row - the node or edge index
+     * @param line - the row's line
+     * @param element - the row's element name for issues
      */
-    writeProperties(domain, slots, row) {
+    writeProperties(domain, slots, row, line, element) {
         const { sink, values, texts } = this;
         for (const slot of slots) {
             const value = values[slot.cell];
@@ -873,21 +1066,24 @@ class Neo4jImportSession {
                 continue;
             }
             const text = texts[slot.cell];
-            if (text !== null && slot.companion === INVALID_INDEX && slot.companionDecl !== null) {
-                slot.companion = declareCompanion(sink, domain, slot.companionDecl);
-            }
-            if (domain === "node") {
-                sink.setNodeValue(slot.handle, row, value);
-                if (text !== null) {
-                    sink.setNodeValue(slot.companion, row, text);
+            // a value the sink refuses is recorded on the row's line; the other properties are written
+            this.guarded(line, `${element} ${slot.name}`, () => {
+                if (text !== null && slot.companion === INVALID_INDEX && slot.companionDecl !== null) {
+                    slot.companion = declareCompanion(sink, domain, slot.companionDecl);
                 }
-            }
-            else {
-                sink.setEdgeValue(slot.handle, row, value);
-                if (text !== null) {
-                    sink.setEdgeValue(slot.companion, row, text);
+                if (domain === "node") {
+                    sink.setNodeValue(slot.handle, row, value);
+                    if (text !== null) {
+                        sink.setNodeValue(slot.companion, row, text);
+                    }
                 }
-            }
+                else {
+                    sink.setEdgeValue(slot.handle, row, value);
+                    if (text !== null) {
+                        sink.setEdgeValue(slot.companion, row, text);
+                    }
+                }
+            });
         }
     }
     /**
@@ -900,6 +1096,10 @@ class Neo4jImportSession {
             this.report.warning("precision", PRECISION_CODE, `long value of "${slot.name}" is beyond 2^53 and was stored as the nearest f64`, { line, element });
         }
         this.precisionSlots.length = 0;
+        for (const name of this.overflows) {
+            this.report.warning("precision", PRECISION_CODE, `the value of "${name}" is beyond the range of its float / double type and was stored as the nearest representable value`, { line, element });
+        }
+        this.overflows.length = 0;
     }
     /**
      * The labels of a node row: every `:LABEL` cell split by the array delimiter (empty items
@@ -944,6 +1144,147 @@ class Neo4jImportSession {
 function qualify(id, space) {
     return space === null ? id : `${space}:${String(id)}`;
 }
+/** The integer range of the narrow neo4j-admin types (Java byte and short). */
+const INTEGER_RANGES = {
+    byte: [-128, 127],
+    short: [-32768, 32767],
+};
+/**
+ * A Cypher duration (ISO 8601): unit form `P14DT16H12M` / `PT0.75M` / `P2.5W` (components may be
+ * signed or fractional) or the date-time form `P2012-02-02T14:37:21.545`.
+ */
+/**
+ * Whether a text is a Cypher duration (ISO 8601): unit form `P14DT16H12M` / `PT0.75M` / `P2.5W`
+ * (components may be signed or fractional) or the date-time form `P2012-02-02T14:37:21.545`.
+ * @param text - the text, trimmed
+ * @returns true when it is
+ */
+function isDuration(text) {
+    if (DURATION_DATE_TIME.test(text)) {
+        return true;
+    }
+    const m = /^[+-]?P([^T]*)(?:T(.*))?$/i.exec(text);
+    if (m === null || m[2] === "" || (m[1] === "" && m[2] === undefined)) {
+        return false;
+    }
+    return unitsInOrder(m[1], "YMWD") && unitsInOrder(m[2] ?? "", "HMS");
+}
+/** The date-time form of a Cypher duration, `P2012-02-02T14:37:21.545`. */
+const DURATION_DATE_TIME = /^[+-]?P\d{4}-?\d{2}-?\d{2}T\d{2}:?\d{2}:?\d{2}(?:\.\d+)?$/i;
+/**
+ * Whether a run of duration components (`14D`, `-1.5H30M`) names its units in the order given,
+ * each at most once.
+ * @param text - the components
+ * @param units - the unit letters in their order
+ * @returns true when it does
+ */
+function unitsInOrder(text, units) {
+    let rest = text.toUpperCase();
+    let from = 0;
+    while (rest !== "") {
+        const m = /^[-+]?\d+(?:\.\d+)?([A-Z])/.exec(rest);
+        const at = m === null ? -1 : units.indexOf(m[1], from);
+        if (m === null || at < 0) {
+            return false;
+        }
+        from = at + 1;
+        rest = rest.slice(m[0].length);
+    }
+    return true;
+}
+/**
+ * Check the neo4j-admin types the shared parser maps to a wider dtype: byte and short values within
+ * their Java range, a char of one character, a duration in Cypher's syntax.
+ * @param spec - the declared type
+ * @param value - the parsed value (a list of items for an array type)
+ * @param text - the cell text, for the error
+ */
+function checkNeo4jRange(spec, value, text) {
+    const base = spec.declared.trim().toLowerCase().replace(/\[\]$/, "");
+    const items = spec.list && Array.isArray(value) ? value : [value];
+    const range = INTEGER_RANGES[base];
+    for (const item of items) {
+        let bad = false;
+        if (range !== undefined) {
+            bad = typeof item === "number" && (item < range[0] || item > range[1]);
+        }
+        else if (base === "char") {
+            // a Java char: one UTF-16 code unit
+            bad = typeof item === "string" && item.length !== 1;
+        }
+        else if (base === "duration") {
+            bad = typeof item === "string" && !isDuration(item.trim());
+        }
+        if (bad) {
+            const span = range === undefined ? "" : ` (${range[0]} to ${range[1]})`;
+            throw new GraphFormatError("E_COLUMN_TYPE", `"${text}" is not ${withArticle(base)}${span}`, {
+                value: text,
+                kind: base,
+            });
+        }
+    }
+}
+/** The largest finite f32. */
+const F32_MAX = 3.4028234663852886e38;
+/**
+ * Whether a float / double cell overflowed: a finite literal read as an infinity, or a float beyond
+ * the f32 range (Java's Double.parseDouble accepts both silently; the value changes).
+ * @param spec - the declared type
+ * @param value - the parsed value
+ * @param text - the cell text
+ * @returns true when the stored value is not the one written
+ */
+function overflows(spec, value, text) {
+    if ((spec.kind !== "float" && spec.kind !== "double") || /inf|nan/i.test(text)) {
+        return false;
+    }
+    const items = spec.list && Array.isArray(value) ? value : [value];
+    return items.some((v) => typeof v === "number" && (!Number.isFinite(v) || (spec.kind === "float" && Math.abs(v) > F32_MAX)));
+}
+/**
+ * A Cypher date-time with a zone name (`2020-01-01T00:00:00[Europe/Berlin]`) as one with a UTC
+ * offset the temporal parser reads: the offset the text gives, else the zone's offset at that wall
+ * time. Any other text is returned unchanged.
+ * @param text - the cell text
+ * @param spec - the declared type
+ * @returns the text to parse
+ */
+function withZoneOffset(text, spec) {
+    const trimmed = text.trim();
+    const open = trimmed.lastIndexOf("[");
+    if (spec.temporal !== "dateTime" || open < 0 || !trimmed.endsWith("]")) {
+        return text;
+    }
+    const local = trimmed.slice(0, open);
+    const zone = trimmed.slice(open + 1, -1);
+    if (zone === "" || zone.includes("]") || /[\n\r\u2028\u2029]/.test(local)) {
+        return text;
+    }
+    let format;
+    try {
+        format = new Intl.DateTimeFormat("en-US", { timeZone: zone, timeZoneName: "longOffset" });
+    }
+    catch {
+        throw new GraphFormatError("E_COLUMN_TYPE", `"${text}" names an unknown time zone ${zone}`, { value: text });
+    }
+    if (/(Z|z|[+-]\d{2}(:?\d{2})?)$/.test(local)) {
+        return local;
+    }
+    const wall = parseTemporal(local, "localDateTime").value;
+    const offsetAt = (ms) => {
+        const name = format.formatToParts(new Date(ms)).find((p) => p.type === "timeZoneName")?.value ?? "GMT";
+        const o = /GMT([+-])(\d{2}):(\d{2})/.exec(name);
+        if (o === null) {
+            return 0;
+        }
+        return (o[1] === "-" ? -1 : 1) * (Number(o[2]) * 60 + Number(o[3]));
+    };
+    // the offset at the instant the wall time names (twice, so a wall time near a transition settles)
+    const minutes = offsetAt(wall - offsetAt(wall) * 60000);
+    const sign = minutes < 0 ? "-" : "+";
+    const abs = Math.abs(minutes);
+    return `${local}${sign}${String(Math.floor(abs / 60)).padStart(2, "0")}:${String(abs % 60).padStart(2, "0")}`;
+}
 /**
  * The value of a quoted empty cell: an empty string for a string-kind property, an empty list for
  * a list property, unset for anything else (neo4j-admin's default `--ignore-empty-strings=false`).
@@ -996,9 +1337,13 @@ function sniffNeo4j(head) {
     const cells = first.split(/[,;|\t]/);
     return isHeaderRecord(cells, cells.length) ? 0.95 : 0;
 }
-/** The Neo4j importer. */
+/**
+ * The Neo4j importer.
+ * @category Built-in formats
+ */
 export const neo4jImporter = Object.freeze({
     format: NEO4J,
+    options: Object.freeze(["arrayDelimiter", "delimiter", "nodes", "quote", "relationships"]),
     extensions: Object.freeze([".csv", ".tsv"]),
     mimeTypes: Object.freeze(["text/csv", "text/tab-separated-values"]),
     sniff: sniffNeo4j,
@@ -1018,7 +1363,14 @@ export const neo4jImporter = Object.freeze({
         // column and every relationship is directed
         reportUnusedOptions(options, report, USED_OPTIONS);
         const session = new Neo4jImportSession(sink, report, common, format);
-        await session.run([input, ...format.nodes, ...format.relationships]);
+        await session.run([
+            { input, kind: null },
+            ...format.nodes.map((file) => ({ input: file, kind: "node" })),
+            ...format.relationships.map((file) => ({ input: file, kind: "relationship" })),
+        ]);
+        if (session.weightProperty !== null) {
+            sink.setMeta({ extra: { neo4j: { weightProperty: session.weightProperty } } });
+        }
         throwIfAborted(common.signal);
         return report.finish();
     },