@graphty/graph-io 0.3.30 → 0.3.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/graph-io",
-  "version": "0.3.30",
+  "version": "0.3.31",
   "description": "Read and write 13 graph file formats (JSON, GraphML, GEXF, CSV, GML, DOT, Pajek, Neo4j CSV, XGMML, CX2, CX, OBO, Cytoscape sessions) as @graphty/graph-format snapshots",
   "author": "Adam Powers <apowers@ato.ms>",
   "type": "module",
@@ -121,7 +121,7 @@
   },
   "homepage": "https://graphty.app/docs/graph-io/",
   "dependencies": {
-    "@graphty/graph-format": "^1.3.8"
+    "@graphty/graph-format": "^1.3.9"
   },
   "peerDependencies": {
     "@graphty/graph-format": "^1.0.0"

package/src/common/export.ts

@@ -293,9 +293,14 @@ export interface CheckExtras {
     /**
      * Roles the format writes into a fixed slot whose importer reads them back under a fixed name;
      * a role column named otherwise is reported as W_COLUMN_NAME_CHANGED (role -> the name the
-     * importer gives it). Defaults to none.
+     * importer gives it). Defaults to none. `nodeRoleNames` and `edgeRoleNames` override it for one
+     * kind, for a format whose slot exists for nodes only (or edges only).
      */
     readonly roleNames?: Readonly<Record<string, string>> | undefined;
+    /** Like `roleNames`, for node columns only. */
+    readonly nodeRoleNames?: Readonly<Record<string, string>> | undefined;
+    /** Like `roleNames`, for edge columns only: `{}` for a format with no edge slot for any role. */
+    readonly edgeRoleNames?: Readonly<Record<string, string>> | undefined;
     /**
      * False for a format that writes no node or edge attributes except the ones whose role is in
      * `roles`: every other attribute column is reported once as W_COLUMN_DROPPED, instead of the
@@ -555,6 +560,22 @@ function charsetText(charset: ExportCapabilities["idCharset"], n: number): strin
     }
 }
 
+/**
+ * The role names of one kind (CheckExtras.nodeRoleNames / edgeRoleNames, else roleNames).
+ * @param domain - "node", "edge" or "graph"
+ * @param extras - format extras
+ * @returns the role names, or undefined when the extras name none
+ */
+function roleNamesOf(domain: string, extras: CheckExtras): Readonly<Record<string, string>> | undefined {
+    if (domain === "node") {
+        return extras.nodeRoleNames ?? extras.roleNames;
+    }
+    if (domain === "edge") {
+        return extras.edgeRoleNames ?? extras.roleNames;
+    }
+    return extras.roleNames;
+}
+
 /**
  * Whether a format writes the attributes of one kind (CheckExtras.nodeAttributes / edgeAttributes, else attributes).
  * @param domain - "node", "edge" or "graph"
@@ -622,8 +643,9 @@ function checkColumns(
             continue;
         }
         const label = `${domain} column "${name}"`;
-        if (role !== null && extras.roleNames !== undefined) {
-            const fixed = extras.roleNames[role];
+        const roleNames = roleNamesOf(domain, extras);
+        if (role !== null && roleNames !== undefined) {
+            const fixed = roleNames[role];
             if (fixed !== undefined && fixed !== name) {
                 note(
                     LOSS.COLUMN_NAME_CHANGED,

package/src/common/ontology-export.ts

@@ -8,7 +8,7 @@
 
 import { type Column, GraphFormatError, type GraphSnapshot } from "@graphty/graph-format";
 
-import { type ExportCapabilities, type LossNote } from "../types.js";
+import { type ExportCapabilities } from "../types.js";
 import { COLUMN_AS_PROPERTY_VALUE_CODE, ROLE_ASSUMED_CODE } from "./codes.js";
 import { checkCapabilities, LOSS } from "./export.js";
 import { formatNumber } from "./format.js";
@@ -32,7 +32,8 @@ const SUPERSEDED: ReadonlySet<string> = new Set([
 
 /** The roles the ontology formats have a slot for, and the column names their importers give them. */
 const SLOT_ROLES: ReadonlySet<string> = new Set(["label", "kind"]);
-const ROLE_NAMES: Readonly<Record<string, string>> = Object.freeze({ label: "name", kind: "relation" });
+const NODE_ROLE_NAMES: Readonly<Record<string, string>> = Object.freeze({ label: "name" });
+const EDGE_ROLE_NAMES: Readonly<Record<string, string>> = Object.freeze({ kind: "relation" });
 
 /**
  * The roles whose columns are never written as values (their loss notes come from checkCapabilities()).
@@ -335,8 +336,15 @@ export function capabilityNotes(
     const { label, note } = spec;
     let fatal: GraphFormatError | null = null;
     const kind = snapshot.edges.byRole("kind");
-    for (const gen of checkCapabilities(snapshot, spec.caps, common, { roles: SLOT_ROLES, roleNames: ROLE_NAMES })) {
-        if (SUPERSEDED.has(gen.code) || (gen.code === LOSS.COLUMN_NAME_CHANGED && !isSlotRename(gen, label, kind))) {
+    // a node label goes into the name slot and an edge kind into the relation slot, when written there;
+    // an edge label has no slot (it becomes edge qualifiers or metadata), so it is never renamed
+    const extras = {
+        roles: SLOT_ROLES,
+        nodeRoleNames: label === null ? {} : NODE_ROLE_NAMES,
+        edgeRoleNames: kind !== null && isText(kind) ? EDGE_ROLE_NAMES : {},
+    };
+    for (const gen of checkCapabilities(snapshot, spec.caps, common, extras)) {
+        if (SUPERSEDED.has(gen.code)) {
             continue;
         }
         if (gen.code === LOSS.MIXED_DIRECTION_ERROR && fatal === null) {
@@ -384,19 +392,6 @@ function slotlessRoleNotes(snapshot: GraphSnapshot, spec: CapabilityNoteSpec): v
     }
 }
 
-/**
- * Whether a name-change note is about a column written into its slot: the node label, or a text
- * edge kind column.
- * @param gen - the note
- * @param label - the node label column, or null
- * @param kind - the edge kind column, or null
- * @returns true when it is
- */
-function isSlotRename(gen: LossNote, label: Column | null, kind: Column | null): boolean {
-    const isLabel = label !== null && gen.column === label.meta.name;
-    return isLabel || (kind !== null && gen.column === kind.meta.name && isText(kind));
-}
-
 /**
  * Record the columns that read back absent: a node or edge column without a set cell on a written
  * element (the importers declare a column when a value needs it).

package/src/formats/cx2/exporter.ts

@@ -297,6 +297,8 @@ function capabilityNotes(
     for (const gen of checkCapabilities(snapshot, CX2_CAPABILITIES, common, {
         roles: SLOT_ROLES,
         roleNames: ROLE_NAMES,
+        // only the node label is written into the "n" slot; an edge label keeps its own name
+        edgeRoleNames: {},
     })) {
         if (!keepGenericNote(gen, bypassNames)) {
             continue;
@@ -337,10 +339,6 @@ function keepGenericNote(gen: LossNote, bypassNames: ReadonlySet<string>): boole
     if (gen.column !== null && bypassNames.has(gen.column) && (gen.code === LOSS.JSON || gen.code === LOSS.DTYPE)) {
         return false;
     }
-    if (gen.code === LOSS.COLUMN_NAME_CHANGED && gen.message.startsWith("edge column")) {
-        // only the node label is written into the "n" slot; an edge label keeps its own name
-        return false;
-    }
     // ids are counted by planNodeIds(): CX2 also keeps integer ids beyond 2^53, which the generic rule refuses
     return gen.code !== LOSS.ID_CHARSET && gen.code !== LOSS.ID_MANGLED;
 }

package/src/formats/obo/exporter.ts

@@ -150,8 +150,8 @@ export const OBO_LOSS = Object.freeze({
      */
     ROLE_ASSUMED: ROLE_ASSUMED_CODE,
     /**
-     * An attribute with a role (for example, the label) is written where the format keeps that role, and reads back under the
-     * name the format's importer gives it.
+     * The node label column is written as each node's `name` and reads back as the column `name`. An edge label has no slot:
+     * it is written as a qualifier (W_ROLE_DROPPED and W_OBO_EDGE_COLUMN_AS_QUALIFIER), never under a new name.
      */
     COLUMN_NAME_CHANGED: LOSS.COLUMN_NAME_CHANGED,
     /**