@graphty/graph-io 0.3.9 → 0.3.11

package/src/formats/gexf/importer.ts

@@ -10,9 +10,11 @@
  * forward reference is legal; element lifetimes (`start` / `end` / `timestamp`, `<spells>`, 1.3
  * `timestamps` / `intervals`, 1.2 `startopen` / `endopen` holding the open bound's time) become
  * the temporal role columns; dynamic attribute values go into the temporal extension tables of
- * design section 5.10; the graph header's `mode`, `timeformat`, `timerepresentation` and `idtype`
- * land in the graph meta (`idtype` is informational: Gephi writes `idtype="string"` for every
- * file, so ids follow the `ids` rule, canonical by default).
+ * design section 5.10, and a spell's open bounds go to the spells.open column; the graph header's
+ * `mode`, `timeformat`, `timerepresentation` and `idtype` land in the graph meta, and its
+ * `defaultedgetype`, `start`, `end` and `timestamp` as written in `meta.extra.gexf` (`idtype` is
+ * informational: Gephi writes `idtype="string"` for every file, so ids follow the `ids` rule,
+ * canonical by default).
  *
  * Direction follows design section 8.4: `defaultedgetype` (undirected when absent, per the spec and
  * the `defaultDirected` option) sets the sink's direction once, and every per-edge `type` override,
@@ -136,7 +138,10 @@ export const WEIGHT_IGNORED_CODE = "W_GEXF_WEIGHT_IGNORED";
 export const VIZ_SKIPPED_CODE = "W_GEXF_VIZ_SKIPPED";
 /** Issue code: a 1.2 dynamic viz element (its bounds are dropped, the value kept). */
 export const VIZ_DYNAMIC_CODE = "W_GEXF_VIZ_DYNAMIC_DROPPED";
-/** Issue code: `startopen` / `endopen` on a `<spell>` (the spells column has no open bits). */
+/**
+ * Issue code: `startopen` / `endopen` on a `<spell>` stored closed. No longer recorded: the open
+ * bits of each spell are kept in the spells.open column. Kept so the exported code table is stable.
+ */
 export const SPELL_OPEN_CODE = "W_GEXF_SPELL_OPEN_DROPPED";
 /** Issue code: a viz element with a value that does not parse (the element is skipped). */
 export const VIZ_VALUE_CODE = "W_GEXF_VIZ_VALUE";
@@ -153,6 +158,16 @@ export {
 };
 
 const EDGE_TYPES: ReadonlySet<string> = new Set(["directed", "undirected", "mutual"]);
+
+/**
+ * An edge type as a keyword of {@link EDGE_TYPES}: the schema spells them in lower case, but files
+ * in the wild write `Directed`, and the keyword is read whatever its case or surrounding space.
+ * @param text - a `defaultedgetype` or edge `type` value
+ * @returns the text trimmed and in lower case
+ */
+function edgeTypeKeyword(text: string): string {
+    return text.trim().toLowerCase();
+}
 const ABORT_CHECK_INTERVAL = 64;
 
 /** The XML attributes the importer reads on `<node>`; any other one is reported once. */
@@ -351,6 +366,7 @@ interface DomainColumns {
     readonly end: TemporalColumn;
     readonly timestamp: TemporalColumn;
     readonly spells: LazyColumn;
+    readonly spellsOpen: LazyColumn;
     readonly timestamps: LazyColumn;
     readonly open: LazyColumn;
     readonly color: LazyColumn;
@@ -502,6 +518,9 @@ class GexfReader implements XmlHandler {
 
     private spellPairs: number[][] | null = null;
 
+    /** The open bits of each spell in spellPairs, in the same order. */
+    private spellOpen: number[] = [];
+
     private spellsWhere: IssueLocation | null = null;
 
     private parentIds: NodeId[] | null = null;
@@ -532,6 +551,7 @@ class GexfReader implements XmlHandler {
             end: new TemporalColumn("node", NODE_DECLS.end),
             timestamp: new TemporalColumn("node", NODE_DECLS.timestamp),
             spells: new LazyColumn("node", NODE_DECLS.spells),
+            spellsOpen: new LazyColumn("node", NODE_DECLS.spellsOpen),
             timestamps: new LazyColumn("node", NODE_DECLS.timestamps),
             open: new LazyColumn("node", NODE_DECLS.open),
             color: new LazyColumn("node", NODE_DECLS.color),
@@ -543,6 +563,7 @@ class GexfReader implements XmlHandler {
             end: new TemporalColumn("edge", EDGE_DECLS.end),
             timestamp: new TemporalColumn("edge", EDGE_DECLS.timestamp),
             spells: new LazyColumn("edge", EDGE_DECLS.spells),
+            spellsOpen: new LazyColumn("edge", EDGE_DECLS.spellsOpen),
             timestamps: new LazyColumn("edge", EDGE_DECLS.timestamps),
             open: new LazyColumn("edge", EDGE_DECLS.open),
             color: new LazyColumn("edge", EDGE_DECLS.color),
@@ -801,8 +822,8 @@ class GexfReader implements XmlHandler {
         const edgeType = attrs.get("defaultedgetype");
         if (edgeType === undefined) {
             this.defaultKind = this.options.defaultDirected ? "directed" : "undirected";
-        } else if (EDGE_TYPES.has(edgeType)) {
-            this.defaultKind = edgeType as GexfEdgeType;
+        } else if (EDGE_TYPES.has(edgeTypeKeyword(edgeType))) {
+            this.defaultKind = edgeTypeKeyword(edgeType) as GexfEdgeType;
         } else {
             this.defaultKind = this.options.defaultDirected ? "directed" : "undirected";
             this.warnHeader("defaultedgetype", edgeType, where);
@@ -846,7 +867,7 @@ class GexfReader implements XmlHandler {
             }
         }
         const extra: Record<string, unknown> = {};
-        for (const key of ["start", "end", "timestamp"]) {
+        for (const key of ["defaultedgetype", "start", "end", "timestamp"]) {
             const value = attrs.get(key);
             if (value !== undefined) {
                 extra[key] = value;
@@ -1256,6 +1277,7 @@ class GexfReader implements XmlHandler {
                 return;
             case "spells":
                 this.spellPairs = [];
+                this.spellOpen = [];
                 this.spellsWhere = frame.where;
                 this.ctx.push(Ctx.Spells);
                 return;
@@ -1408,13 +1430,14 @@ class GexfReader implements XmlHandler {
             return;
         }
         let kind: EdgeKind = this.defaultKind;
-        const type = attrs.get("type");
-        if (type !== undefined) {
+        const typeText = attrs.get("type");
+        if (typeText !== undefined) {
+            const type = edgeTypeKeyword(typeText);
             if (!EDGE_TYPES.has(type)) {
                 report.error(
                     "validation-error",
                     EDGE_TYPE_CODE,
-                    `edge type "${type}" is not directed, undirected or mutual`,
+                    `edge type "${typeText}" is not directed, undirected or mutual`,
                     where,
                 );
                 report.counts.skippedEdges++;
@@ -1525,6 +1548,7 @@ class GexfReader implements XmlHandler {
                 return;
             case "spells":
                 this.spellPairs = [];
+                this.spellOpen = [];
                 this.spellsWhere = edge.where;
                 this.ctx.push(Ctx.Spells);
                 return;
@@ -1970,36 +1994,34 @@ class GexfReader implements XmlHandler {
         const where = this.spellsWhere ?? { line };
         try {
             const bounds = this.readBounds(attrs, where);
-            if (bounds.open !== 0) {
-                this.report.warnOnce(
-                    "unsupported",
-                    SPELL_OPEN_CODE,
-                    "startopen / endopen on a <spell> cannot be kept; the spell is stored closed",
-                    where,
-                );
-            }
             this.spellPairs?.push([bounds.start.value, bounds.end.value]);
+            this.spellOpen.push(bounds.open);
         } catch (err) {
             this.report.recordError(err, where);
         }
     }
 
-    /** Close `<spells>`: write the pairs into the open element's spells column. */
+    /**
+     * Close `<spells>`: write the pairs into the open element's spells column, and their open bits
+     * into the spells.open column when any spell has an open bound.
+     */
     private finishSpells(): void {
         const pairs = this.spellPairs;
+        const open = this.spellOpen;
         const where = this.spellsWhere ?? undefined;
         this.spellPairs = null;
+        this.spellOpen = [];
         this.spellsWhere = null;
         if (pairs === null) {
             return;
         }
         try {
-            if (this.edge !== null) {
-                this.edgeColumns.spells.set(this.sink, this.report, this.edge.index, pairs, where);
-            } else {
-                const frame = this.nodeStack[this.nodeStack.length - 1];
-                if (frame.index !== INVALID_INDEX) {
-                    this.nodeColumns.spells.set(this.sink, this.report, frame.index, pairs, where);
+            const columns = this.edge === null ? this.nodeColumns : this.edgeColumns;
+            const { index } = this.edge ?? this.nodeStack[this.nodeStack.length - 1];
+            if (index !== INVALID_INDEX) {
+                columns.spells.set(this.sink, this.report, index, pairs, where);
+                if (open.some((bits) => bits !== 0)) {
+                    columns.spellsOpen.set(this.sink, this.report, index, open, where);
                 }
             }
         } catch (err) {

package/src/formats/gexf/index.ts

@@ -128,7 +128,7 @@ export const GEXF_ISSUE = Object.freeze({
     VIZ_SKIPPED: VIZ_SKIPPED_CODE,
     /** A 1.2 dynamic viz element whose bounds were dropped. */
     VIZ_DYNAMIC_DROPPED: VIZ_DYNAMIC_CODE,
-    /** A 1.2 startopen / endopen spell stored closed. */
+    /** Deprecated and no longer recorded: open spells are kept in the spells.open column. */
     SPELL_OPEN_DROPPED: SPELL_OPEN_CODE,
     /** A viz value that could not be read. */
     VIZ_VALUE: VIZ_VALUE_CODE,

package/src/formats/gexf/schema.ts

@@ -56,6 +56,7 @@ export const NODE_COLUMNS = Object.freeze({
     end: "end",
     timestamp: "timestamp",
     spells: "spells",
+    spellsOpen: "spells.open",
     timestamps: "timestamps",
     open: "open",
     position: "position",
@@ -74,6 +75,7 @@ const EDGE_COLUMNS = Object.freeze({
     end: "end",
     timestamp: "timestamp",
     spells: "spells",
+    spellsOpen: "spells.open",
     timestamps: "timestamps",
     open: "open",
     color: "color",
@@ -138,6 +140,14 @@ export const NODE_DECLS: Readonly<Record<keyof typeof NODE_COLUMNS, ColumnDecl>>
         origin: XML_ORIGIN,
     },
     open: { name: NODE_COLUMNS.open, dtype: "u8", role: "open", nullable: true, origin: XML_ORIGIN },
+    spellsOpen: {
+        name: NODE_COLUMNS.spellsOpen,
+        dtype: "list",
+        itemDtype: "u8",
+        role: "spellsOpen",
+        nullable: true,
+        origin: XML_ORIGIN,
+    },
     position: {
         name: NODE_COLUMNS.position,
         dtype: "f32",
@@ -187,6 +197,14 @@ export const EDGE_DECLS: Readonly<Record<keyof typeof EDGE_COLUMNS, ColumnDecl>>
         origin: XML_ORIGIN,
     },
     open: { name: EDGE_COLUMNS.open, dtype: "u8", role: "open", nullable: true, origin: XML_ORIGIN },
+    spellsOpen: {
+        name: EDGE_COLUMNS.spellsOpen,
+        dtype: "list",
+        itemDtype: "u8",
+        role: "spellsOpen",
+        nullable: true,
+        origin: XML_ORIGIN,
+    },
     color: {
         name: EDGE_COLUMNS.color,
         dtype: "f32",

package/src/formats/gml/exporter.ts

@@ -136,6 +136,7 @@ const SKIPPED_ROLES: ReadonlySet<string> = new Set([
     "timestamps",
     "spells",
     "open",
+    "spellsOpen",
 ]);
 
 const NODE_RESERVED: ReadonlySet<string> = new Set(["id"]);

package/src/formats/gml/importer.ts

@@ -14,9 +14,10 @@
  * a `graphics [ x y z ]` node record mapped to the `position` role (note 07 section 9) with the
  * remaining graphics keys kept as a json column.
  *
- * Node ids are the integer `id` keys (the GML spec type; a non-integer id is a validation error,
- * never a silent string) under `nodeIdFrom: "id"`, the `label` under `"label"`, and the node's
- * ordinal under `"index"`; `source` / `target` always resolve through the integer ids. A node's
+ * Node ids are the `id` keys under `nodeIdFrom: "id"`, the `label` under `"label"`, and the node's
+ * ordinal under `"index"`; `source` / `target` always resolve through the `id` keys. The GML spec
+ * types ids as integers; a string id (written by NetworkX and Gephi) is accepted under the `ids`
+ * rule with one warning per file, and a real or record id is a validation error. A node's
  * `graphty_originalId` key written by the exporter's `sanitizeIds: "mangle"` restores the
  * original id under `restoreMangledIds` (the default).
  */
@@ -96,8 +97,10 @@ export const MISSING_ID_CODE = SHARED_MISSING_ID_CODE;
 export const MISSING_LABEL_CODE = "E_GML_MISSING_LABEL";
 /** Issue code: an edge block has no `source` or no `target` key. */
 export const MISSING_ENDPOINT_CODE = SHARED_MISSING_ENDPOINT_CODE;
-/** Issue code: an `id`, `source` or `target` value is not an integer. */
+/** Issue code: an `id`, `source` or `target` value is neither an integer nor a string. */
 export const ID_TYPE_CODE = "E_GML_ID_TYPE";
+/** Issue code: string `id`, `source` or `target` values, outside the GML spec's integer ids; warned once per file. */
+export const STRING_ID_CODE = "W_GML_STRING_ID";
 /** Issue code: a node id (or label under `nodeIdFrom: "label"`) is declared twice; later keys overwrite. */
 export const DUPLICATE_NODE_CODE = SHARED_DUPLICATE_NODE_CODE;
 /** Issue code: a structural key (`id`, `source`, `target`) appears twice in one block. */
@@ -301,7 +304,7 @@ class GmlImport {
     private elementsSinceCheck = 0;
 
     /** The sink id every file id maps to when they differ (label / index / restored ids), else null. */
-    private idMap: Map<number, NodeId> | null = null;
+    private idMap: Map<NodeId, NodeId> | null = null;
 
     /** Node indices declared by a node block of this import, for duplicate detection. */
     private declared = new Uint32Array(64);
@@ -866,7 +869,9 @@ class GmlImport {
             if (idTok < 0) {
                 throw new GraphFormatError("E_INVALID_ID", "node has no id", { reason: "missing id" });
             }
-            const fileId = this.integerOf(idTok, "id");
+            // the file id under the ids rule, so `id 1` and `source "1"` meet in idMap (except under
+            // "keep", where the integer 1 and the string "1" are different ids by design)
+            const fileId = this.coerceFileId(idTok, this.fileIdOf(idTok, "id"));
             if (originalTok >= 0) {
                 sinkId = this.restoredId(originalTok);
             } else {
@@ -883,7 +888,7 @@ class GmlImport {
                         sinkId = ordinal;
                         break;
                     default:
-                        sinkId = this.coerceInteger(idTok, fileId);
+                        sinkId = fileId;
                 }
             }
             if (this.idMap !== null) {
@@ -1019,24 +1024,48 @@ class GmlImport {
     }
 
     /**
-     * The integer value of an id / source / target token (the GML grammar's integer ids; a string
-     * id is refused, as the malformed corpus pins, although NetworkX would accept it).
+     * The value of an id / source / target token: an integer (the GML spec's type) as a number, a
+     * string (NetworkX and Gephi write them) as its text with one warning per file.
      * @param v - the value token
      * @param key - the key name, for the error
-     * @returns the number
+     * @returns the number or the string
      */
-    private integerOf(v: number, key: string): number {
+    private fileIdOf(v: number, key: string): number | string {
         const t = this.requireTokens();
+        if (t.kind[v] === TOKEN_STRING) {
+            this.report.warnOnce(
+                "validation-error",
+                STRING_ID_CODE,
+                `${key} is the string "${t.textOf(v)}"; GML ids are integers, string ids are kept under the ids rule`,
+                { line: t.line[v], element: t.stringOf(v) },
+            );
+            return t.stringOf(v);
+        }
         if (t.kind[v] !== TOKEN_INT) {
-            throw new GraphFormatError("E_INVALID_ID", `${key} must be an integer, found ${describeValue(t, v)}`, {
-                reason: "not an integer",
-                key,
-                value: t.kind[v] === TOKEN_OPEN ? "[...]" : t.textOf(v),
-            });
+            throw new GraphFormatError(
+                "E_INVALID_ID",
+                `${key} must be an integer or a string, found ${describeValue(t, v)}`,
+                {
+                    reason: "not an integer",
+                    key,
+                    value: t.kind[v] === TOKEN_OPEN ? "[...]" : t.textOf(v),
+                },
+            );
         }
         return Number(t.textOf(v));
     }
 
+    /**
+     * Coerce an id / source / target value under the `ids` rule: a string by its text, an integer
+     * through coerceInteger().
+     * @param v - the value token
+     * @param id - its value (fileIdOf())
+     * @returns the id
+     */
+    private coerceFileId(v: number, id: number | string): NodeId {
+        return typeof id === "string" ? this.coercer.text(id) : this.coerceInteger(v, id);
+    }
+
     /**
      * Coerce an integer id token under the `ids` rule: a safe integer passes as a typed number
      * (so `01` is 1 and `-0` is 0), a larger one goes through the text rule (a string under
@@ -1099,14 +1128,8 @@ class GmlImport {
      * @returns the id
      */
     private endpoint(v: number, key: string): NodeId {
-        const n = this.integerOf(v, key);
-        if (this.idMap !== null) {
-            const mapped = this.idMap.get(n);
-            if (mapped !== undefined) {
-                return mapped;
-            }
-        }
-        return this.coerceInteger(v, n);
+        const id = this.coerceFileId(v, this.fileIdOf(v, key));
+        return this.idMap?.get(id) ?? id;
     }
 
     /**

package/src/formats/gml/index.ts

@@ -45,6 +45,7 @@ import {
     REPEATED_KEY_CODE,
     ROLE_TAKEN_CODE,
     SECOND_GRAPH_CODE,
+    STRING_ID_CODE,
     UNKNOWN_ENTITY_CODE,
 } from "./importer.js";
 
@@ -77,8 +78,10 @@ export const GML_ISSUE = Object.freeze({
     MISSING_LABEL: MISSING_LABEL_CODE,
     /** An edge without `source` or `target`. */
     MISSING_ENDPOINT: MISSING_ENDPOINT_CODE,
-    /** A node id, source or target that is not an integer. */
+    /** A node id, source or target that is neither an integer nor a string. */
     ID_TYPE: ID_TYPE_CODE,
+    /** String node ids, sources or targets (outside the spec's integers), kept under the ids rule; warned once. */
+    STRING_ID: STRING_ID_CODE,
     /** A node id declared twice (later keys overwrite). */
     DUPLICATE_NODE: DUPLICATE_NODE_CODE,
     /** A structural key repeated in one element. */

package/src/formats/graphml/constants.ts

@@ -233,6 +233,8 @@ export const GRAPHML_LOSS = Object.freeze({
     ID_TEXT_TYPE: ID_TEXT_TYPE_CODE,
     /** A numeric edge id column reads back as string. */
     EDGE_ID_TEXT: "W_GRAPHML_EDGE_ID_TEXT",
+    /** A `yfiles.*` graphics column that no longer matches its yFiles tree: only the tree is written. */
+    YFILES_GRAPHICS_STALE: "W_GRAPHML_YFILES_GRAPHICS_STALE",
     /** A yfiles json value that is not a serialisable tree: export() will throw E_COLUMN_TYPE. */
     YFILES_TREE: "E_GRAPHML_YFILES_TREE",
 });

package/src/formats/graphml/exporter.ts

@@ -56,6 +56,7 @@ import {
     YFILES_NAMESPACE,
 } from "./constants.js";
 import { treeProblem, writeXmlTree } from "./tree.js";
+import { isGraphicsColumn, staleGraphicsRows } from "./yfiles.js";
 
 /** The format-specific options of the GraphML exporter. */
 export interface GraphmlExportOptions {
@@ -110,6 +111,7 @@ const DROPPED_ROLES: ReadonlySet<string> = new Set([
     "timestamps",
     "spells",
     "open",
+    "spellsOpen",
 ]);
 
 /**
@@ -294,11 +296,16 @@ function graphmlMetaOf(snapshot: GraphSnapshot): GraphmlMeta | null {
  * @returns the plan
  */
 function planExport(snapshot: GraphSnapshot, options: ResolvedExportOptions, format: FormatOptions): Plan {
-    // the generic json note is replaced by planTable()'s (yfiles trees are kept, other json is text)
+    // the generic json note is replaced by planTable()'s (yfiles trees are kept, other json is
+    // text); columns mapped from a yfiles tree are never written: planTable() notes the ones
+    // that no longer match their tree, the rest lose nothing
+    const graphics = new Set(
+        [...snapshot.nodes, ...snapshot.edges].filter((c) => isGraphicsColumn(c.meta)).map((c) => c.meta.name),
+    );
     const notes = checkCapabilities(snapshot, CAPABILITIES, options, {
         roles: SLOT_ROLES,
         roleNames: ROLE_NAMES,
-    }).filter((n) => n.code !== LOSS.JSON);
+    }).filter((n) => n.code !== LOSS.JSON && (n.column === null || !graphics.has(n.column)));
     const note: NoteFn = (code, message, column = null, count = null): void => {
         notes.push(Object.freeze({ code, message, column, count }));
     };
@@ -649,6 +656,18 @@ function planTable(table: Iterable<Column>, domain: Domain, notes: LossNote[], n
     for (const column of columns) {
         const { meta } = column;
         const { role, name } = meta;
+        if (isGraphicsColumn(meta)) {
+            const stale = domain === "graph" ? 0 : staleGraphicsRows(column, columns, domain);
+            if (stale > 0) {
+                note(
+                    GRAPHML_LOSS.YFILES_GRAPHICS_STALE,
+                    `${stale} value(s) of ${domain} column "${name}" differ from the yFiles tree it was read from; only the tree is written, so they are lost`,
+                    name,
+                    stale,
+                );
+            }
+            continue;
+        }
         if (role === "parents") {
             note(
                 GRAPHML_LOSS.PARENTS_DROPPED,