@graphty/graph-io 0.3.39 → 0.3.41

package/src/formats/json/obographs.ts

@@ -503,21 +503,7 @@ function writeMeta(
     element: string,
 ): void {
     const path = `${element}.meta`;
-    const { definition } = meta;
-    if (isJsonObject(definition)) {
-        const xrefs = strings(ctx, definition.xrefs, `${path}.definition.xrefs`);
-        if (typeof definition.val === "string") {
-            columns.node("def", row, definition.val);
-            columns.node("def.xrefs", row, xrefs);
-        } else {
-            badValue(ctx, `${path}.definition has no string val; it is dropped`, `${path}.definition.val`);
-        }
-        if (definition.meta !== undefined) {
-            unrecognized["meta.definition.meta"] = definition.meta;
-        }
-    } else if (definition !== undefined && definition !== null) {
-        badValue(ctx, `${path}.definition must be an object with a val; it is dropped`, `${path}.definition`);
-    }
+    writeDefinition(ctx, columns, meta.definition, row, unrecognized, path);
     const comments = strings(ctx, meta.comments, `${path}.comments`);
     if (comments.length > 0) {
         columns.node("comment", row, comments.join("\n"));
@@ -547,6 +533,40 @@ function writeMeta(
     }
 }
 
+/**
+ * Write a node's `meta.definition`: the text and its xrefs; a nested `meta` is kept in
+ * `obo.unrecognized`.
+ * @param ctx - the context
+ * @param columns - the column writer
+ * @param definition - the `definition` field
+ * @param row - the node index
+ * @param unrecognized - where keys without a column go
+ * @param path - the meta path in messages
+ */
+function writeDefinition(
+    ctx: ImportContext,
+    columns: ColumnWriter,
+    definition: unknown,
+    row: number,
+    unrecognized: JsonRecord,
+    path: string,
+): void {
+    if (isJsonObject(definition)) {
+        const xrefs = strings(ctx, definition.xrefs, `${path}.definition.xrefs`);
+        if (typeof definition.val === "string") {
+            columns.node("def", row, definition.val);
+            columns.node("def.xrefs", row, xrefs);
+        } else {
+            badValue(ctx, `${path}.definition has no string val; it is dropped`, `${path}.definition.val`);
+        }
+        if (definition.meta !== undefined) {
+            unrecognized["meta.definition.meta"] = definition.meta;
+        }
+    } else if (definition !== undefined && definition !== null) {
+        badValue(ctx, `${path}.definition must be an object with a val; it is dropped`, `${path}.definition`);
+    }
+}
+
 /**
  * The synonyms of a node's meta as the OBO `synonym` items: each entry that is not an object or
  * has no string val reported and dropped, a predicate that is not one of the four scopes kept with

package/src/formats/neo4j/exporter.ts

@@ -400,6 +400,17 @@ class ExportPlan {
         this.checkStoredIds();
         this.directionNotes();
         const slots = new Set([this.kind, this.labels, this.idSpace].flatMap((c) => (c === null ? [] : [c.meta.name])));
+        this.addGenericNotes(generic, slots);
+        this.notes.push(...this.ownNotes);
+        this.filterNotesByPart();
+    }
+
+    /**
+     * Add the generic capability notes, leaving out the ones this format reads back as they were.
+     * @param generic - the notes the capability check found
+     * @param slots - the names of the :TYPE, :LABEL and :ID(Space) columns
+     */
+    private addGenericNotes(generic: ReturnType<typeof checkCapabilities>, slots: ReadonlySet<string>): void {
         for (const gen of generic) {
             if (gen.code === LOSS.JSON && gen.column !== null && this.writtenAsPoint(gen.column)) {
                 continue;
@@ -425,8 +436,6 @@ class ExportPlan {
             }
             this.notes.push(gen);
         }
-        this.notes.push(...this.ownNotes);
-        this.filterNotesByPart();
     }
 
     /**
@@ -617,22 +626,7 @@ class ExportPlan {
      * @returns the scalar plan
      */
     private integralOrDouble(column: Column, declared: string, label: string): ScalarPlan {
-        let integral = true;
-        if (column.dtype === "f64") {
-            for (let r = 0; r < column.length && integral; r++) {
-                if (column.isSet(r) && !Number.isInteger(column.data[r])) {
-                    integral = false;
-                }
-            }
-        } else if (column.dtype === "list" && column.child.dtype === "f64") {
-            const { data } = column.child;
-            for (let i = 0; i < data.length && integral; i++) {
-                if (!Number.isInteger(data[i])) {
-                    integral = false;
-                }
-            }
-        }
-        if (integral) {
+        if (holdsOnlyIntegers(column)) {
             return { type: declared, kind: "integer", temporal: null };
         }
         this.note(
@@ -1186,23 +1180,34 @@ class ExportPlan {
             return null;
         }
         if (plan.list) {
-            const items = column.dtype === "list" ? column.sliceOf(row) : (column.value(row) as ArrayLike<unknown>);
-            const texts: string[] = [];
-            for (const item of Array.from(items)) {
-                // an item of several components (itemComponents > 1) is flattened into the array
-                if (Array.isArray(item) || ArrayBuffer.isView(item)) {
-                    for (const component of Array.from(item as ArrayLike<unknown>)) {
-                        texts.push(formatScalar(component, scalar, null));
-                    }
-                } else {
-                    texts.push(formatScalar(item, scalar, null));
-                }
-            }
-            return texts.join(this.options.arrayDelimiter);
+            return this.listText(plan, row);
         }
         const text = companion?.isSet(row) ? textOf(companion, row) : null;
         return formatScalar(column.dtype === "json" ? column.values[row] : column.value(row), scalar, text);
     }
+
+    /**
+     * The text of one list cell: its items joined by the array delimiter.
+     * @param plan - the column plan
+     * @param row - the row, which is set
+     * @returns the text
+     */
+    private listText(plan: ColumnPlan, row: number): string {
+        const { column, scalar } = plan;
+        const items = column.dtype === "list" ? column.sliceOf(row) : (column.value(row) as ArrayLike<unknown>);
+        const texts: string[] = [];
+        for (const item of Array.from(items)) {
+            // an item of several components (itemComponents > 1) is flattened into the array
+            if (Array.isArray(item) || ArrayBuffer.isView(item)) {
+                for (const component of Array.from(item as ArrayLike<unknown>)) {
+                    texts.push(formatScalar(component, scalar, null));
+                }
+            } else {
+                texts.push(formatScalar(item, scalar, null));
+            }
+        }
+        return texts.join(this.options.arrayDelimiter);
+    }
 }
 
 /**
@@ -1319,6 +1324,16 @@ function defaultScalar(dtype: Dtype | ScalarDtype): ScalarPlan {
     }
 }
 
+/**
+ * Format a number with a formatter; any other value is written as String(value).
+ * @param value - the value
+ * @param format - the number formatter
+ * @returns the text
+ */
+function numberOrString(value: unknown, format: (n: number) => string): string {
+    return typeof value === "number" ? format(value) : String(value);
+}
+
 /**
  * Format one scalar value for a cell.
  * @param value - the value
@@ -1329,22 +1344,22 @@ function defaultScalar(dtype: Dtype | ScalarDtype): ScalarPlan {
 function formatScalar(value: unknown, scalar: ScalarPlan, text: string | null): string {
     switch (scalar.kind) {
         case "integer":
-            return typeof value === "number" ? formatInteger(value) : String(value);
+            return numberOrString(value, formatInteger);
         case "float":
-            return typeof value === "number" ? formatF32(value) : String(value);
+            return numberOrString(value, formatF32);
         case "double":
-            return typeof value === "number" ? formatF64(value) : String(value);
+            return numberOrString(value, formatF64);
         case "boolean":
             return value === true ? "true" : "false";
         case "string":
-            return typeof value === "string" ? value : String(value);
+            return String(value);
         case "temporal":
-            if (text !== null) {
-                return text;
-            }
-            return typeof value === "number" && scalar.temporal !== null
-                ? formatTemporal(value, scalar.temporal)
-                : String(value);
+            return (
+                text ??
+                numberOrString(value, (n) =>
+                    scalar.temporal === null ? String(n) : formatTemporal(n, scalar.temporal),
+                )
+            );
         case "point":
             return formatPoint(value);
         case "json":
@@ -1539,3 +1554,26 @@ function weightPropertyOf(snapshot: GraphSnapshot): string | null {
     const name = neo4j?.weightProperty;
     return typeof name === "string" && name !== "" ? name : null;
 }
+
+/**
+ * Whether every set value of an f64 column, or of an f64 list column's items, is integral.
+ * @param column - the column
+ * @returns false when a value is not an integer
+ */
+function holdsOnlyIntegers(column: Column): boolean {
+    if (column.dtype === "f64") {
+        for (let r = 0; r < column.length; r++) {
+            if (column.isSet(r) && !Number.isInteger(column.data[r])) {
+                return false;
+            }
+        }
+    } else if (column.dtype === "list" && column.child.dtype === "f64") {
+        const { data } = column.child;
+        for (let i = 0; i < data.length; i++) {
+            if (!Number.isInteger(data[i])) {
+                return false;
+            }
+        }
+    }
+    return true;
+}

package/src/formats/neo4j/header.ts

@@ -108,28 +108,14 @@ export function parseHeaderField(text: string): HeaderField {
     const space = m[3] === undefined ? null : m[3].trim();
     const options = parseOptions(text, m[4]);
     if (rawType === null) {
-        // `name` alone: a string property
-        if (name.length === 0) {
-            throw headerError(text, "an empty header cell");
-        }
-        if (space !== null || options.size > 0) {
-            throw headerError(text, "an id space or options need a field type");
-        }
-        return { text, name, kind: "PROPERTY", type: null, space: null, options };
+        return untypedField(text, name, space, options);
     }
     if (rawType.length === 0) {
         throw headerError(text, "an empty field type");
     }
     const upper = rawType.toUpperCase();
     if (STRUCTURAL.has(upper)) {
-        const kind = upper as Exclude<FieldKind, "PROPERTY">;
-        if (space !== null && !SPACE_KINDS.has(kind)) {
-            throw headerError(text, `an id space is only allowed on ID, START_ID and END_ID, not ${kind}`);
-        }
-        if (name.length > 0 && kind !== "ID" && kind !== "IGNORE") {
-            throw headerError(text, `a ${kind} field cannot be stored as a property`);
-        }
-        return { text, name, kind, type: null, space: space === "" ? null : space, options };
+        return structuralField(text, name, upper as Exclude<FieldKind, "PROPERTY">, space, options);
     }
     if (name.length === 0) {
         throw headerError(text, "a property column needs a name");
@@ -140,6 +126,54 @@ export function parseHeaderField(text: string): HeaderField {
     return { text, name, kind: "PROPERTY", type: rawType, space: null, options };
 }
 
+/**
+ * The field of a cell with no type: `name` alone is a string property.
+ * @param text - the whole cell, for errors
+ * @param name - the property name
+ * @param space - the id space, or null
+ * @param options - the options
+ * @returns the field
+ */
+function untypedField(
+    text: string,
+    name: string,
+    space: string | null,
+    options: ReadonlyMap<string, string>,
+): HeaderField {
+    if (name.length === 0) {
+        throw headerError(text, "an empty header cell");
+    }
+    if (space !== null || options.size > 0) {
+        throw headerError(text, "an id space or options need a field type");
+    }
+    return { text, name, kind: "PROPERTY", type: null, space: null, options };
+}
+
+/**
+ * The field of a cell with a structural type (ID, START_ID, END_ID, LABEL, TYPE, IGNORE).
+ * @param text - the whole cell, for errors
+ * @param name - the property name, or empty
+ * @param kind - the structural kind
+ * @param space - the id space, or null
+ * @param options - the options
+ * @returns the field
+ */
+function structuralField(
+    text: string,
+    name: string,
+    kind: Exclude<FieldKind, "PROPERTY">,
+    space: string | null,
+    options: ReadonlyMap<string, string>,
+): HeaderField {
+    if (space !== null && !SPACE_KINDS.has(kind)) {
+        throw headerError(text, `an id space is only allowed on ID, START_ID and END_ID, not ${kind}`);
+    }
+    if (name.length > 0 && kind !== "ID" && kind !== "IGNORE") {
+        throw headerError(text, `a ${kind} field cannot be stored as a property`);
+    }
+    return { text, name, kind, type: null, space: space === "" ? null : space, options };
+}
+
 /**
  * Parse the `{key:value, key:value}` options of a header cell.
  * @param text - the whole cell, for errors

package/src/formats/neo4j/importer.ts

@@ -1385,16 +1385,7 @@ class Neo4jImportSession {
             }
             const { spec } = slot;
             try {
-                if (spec.temporal !== null && !spec.list) {
-                    const zoned = withZoneOffset(text, spec);
-                    const parsed = parseDeclaredTemporal(zoned, spec);
-                    values[slot.cell] = parsed.value;
-                    // 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);
-                }
+                this.parseCell(slot, text);
             } catch (err) {
                 this.report.recordError(err, { line, element: `${element} ${slot.name}` });
                 return false;
@@ -1409,6 +1400,26 @@ class Neo4jImportSession {
         return true;
     }
 
+    /**
+     * Parse one non-empty property cell into the scratch arrays; throws on a malformed value.
+     * @param slot - the cell's property slot
+     * @param text - the cell text
+     */
+    private parseCell(slot: PropertySlot, text: string): void {
+        const { values, texts } = this;
+        const { spec } = slot;
+        if (spec.temporal !== null && !spec.list) {
+            const zoned = withZoneOffset(text, spec);
+            const parsed = parseDeclaredTemporal(zoned, spec);
+            values[slot.cell] = parsed.value;
+            // 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);
+        }
+    }
+
     /**
      * Write the parsed property values of a row.
      * @param domain - node or edge

package/src/formats/obo/exporter.ts

@@ -972,6 +972,39 @@ function keptObo(snapshot: GraphSnapshot): {
     return { header: clauses(record.header), typedefs, unknownFrames };
 }
 
+/**
+ * Note the frame kinds the written nodes read back as: the type column gained, and the nodes
+ * written as [Typedef] frames.
+ * @param snapshot - the snapshot
+ * @param rows - the node indices written as frames
+ * @param kinds - the frame kind of each node
+ * @param note - receives the notes
+ */
+function noteFrameKinds(
+    snapshot: GraphSnapshot,
+    rows: readonly number[],
+    kinds: readonly string[],
+    note: NoteFn,
+): void {
+    if (rows.length > 0 && !snapshot.nodes.has("type")) {
+        note(
+            OBO_LOSS.TYPE_GAINED,
+            `${rows.length} node${plural(rows.length)} ${agree(rows.length, "is", "are")} written as [Term] frames and ${agree(rows.length, "reads", "read")} back with the type Term in a new node column "type"`,
+            null,
+            rows.length,
+        );
+    }
+    const typedefNodes = rows.filter((i) => kinds[i] === "Typedef").length;
+    if (typedefNodes > 0) {
+        note(
+            OBO_LOSS.TYPEDEF_NODES,
+            `${typedefNodes} node${plural(typedefNodes)} ${agree(typedefNodes, "is", "are")} written as [Typedef] frames; they read back as nodes only when imported with typedefs: "nodes", and then after the other nodes, with the [Typedef] frames that declare the relations`,
+            "type",
+            typedefNodes,
+        );
+    }
+}
+
 /**
  * Plan an export: the notes, the fatal condition and what is written.
  * @param snapshot - the snapshot
@@ -1014,23 +1047,7 @@ function plan(snapshot: GraphSnapshot, options: (OboExportOptions & CommonExport
         }
     }
     const { kinds, type } = planKinds(snapshot, frameless);
-    if (rows.length > 0 && !snapshot.nodes.has("type")) {
-        note(
-            OBO_LOSS.TYPE_GAINED,
-            `${rows.length} node${plural(rows.length)} ${agree(rows.length, "is", "are")} written as [Term] frames and ${agree(rows.length, "reads", "read")} back with the type Term in a new node column "type"`,
-            null,
-            rows.length,
-        );
-    }
-    const typedefNodes = rows.filter((i) => kinds[i] === "Typedef").length;
-    if (typedefNodes > 0) {
-        note(
-            OBO_LOSS.TYPEDEF_NODES,
-            `${typedefNodes} node${plural(typedefNodes)} ${agree(typedefNodes, "is", "are")} written as [Typedef] frames; they read back as nodes only when imported with typedefs: "nodes", and then after the other nodes, with the [Typedef] frames that declare the relations`,
-            "type",
-            typedefNodes,
-        );
-    }
+    noteFrameKinds(snapshot, rows, kinds, note);
 
     const kept = keptObo(snapshot);
     const scopes = synonymTypeScopes(kept.header);