@graphty/graph-io 0.3.25 → 0.3.26

package/src/formats/graphml/index.ts

@@ -1,6 +1,7 @@
 /**
- * The `@graphty/graph-io/graphml` subpath: the GraphML importer and exporter (design section 8.2),
+ * The `@graphty/graph-io/graphml` subpath: the GraphML importer and exporter,
  * their option types and their issue and loss-note code tables.
+ * @module @graphty/graph-io/graphml
  */
 
 export { GRAPHML_ISSUE, GRAPHML_LOSS } from "./constants.js";

package/src/formats/graphml/tree.ts

@@ -39,6 +39,7 @@ interface Frame {
  * Builds the tree of one subtree from start / end / text events. The outermost frame is the
  * `<data>` element itself; `finish()` returns its content: the object of its children, or its
  * text when it has none.
+ * @category Plugin helpers
  */
 export class XmlTreeBuilder {
     private readonly frames: Frame[] = [];
@@ -151,20 +152,22 @@ function attachChild(parent: Frame, name: string, value: unknown): void {
 }
 
 /**
- * Whether a value is a tree the writer can serialise: a string, number, boolean or null (text),
+ * Whether a value is a tree the writer can serialize: a string, number, boolean or null (text),
  * an array of such trees, or an object whose keys are `#text`, `@_<Name>` or `<Name>` with tree
  * values.
  * @param value - the value
  * @returns true when writeXmlTree() accepts it
+ * @category Plugin helpers
  */
 export function isXmlTree(value: unknown): boolean {
     return treeProblem(value) === null;
 }
 
 /**
- * Why a value is not a serialisable tree.
+ * Why a value is not a serializable tree.
  * @param value - the value
  * @returns a message, or null when the value is a tree
+ * @category Plugin helpers
  */
 export function treeProblem(value: unknown): string | null {
     if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
@@ -220,6 +223,7 @@ export function treeProblem(value: unknown): string | null {
  * @param value - the tree (the content of a `<data>` element)
  * @param indent - the indentation of the containing element's children
  * @param out - receives the text parts
+ * @category Plugin helpers
  */
 export function writeXmlTree(value: unknown, indent: string, out: string[]): void {
     const problem = treeProblem(value);

package/src/formats/graphml/yfiles.ts

@@ -1,9 +1,9 @@
 /**
  * yFiles / yEd graphics read out of the JSON tree of a `yfiles.type` key (tree.ts) into typed
  * columns, beside the tree itself: a `y:ShapeNode` gives the node's position, size, fill and
- * border colours, label and shape, and a `y:PolyLineEdge` gives the edge's line colour and width,
+ * border colors, label and shape, and a `y:PolyLineEdge` gives the edge's line color and width,
  * its arrows and the direction they draw. The values are the ones graphty-element's own GraphML
- * parser produced, so a consumer rebuilds its records by dropping the `yfiles.` prefix: colours
+ * parser produced, so a consumer rebuilds its records by dropping the `yfiles.` prefix: colors
  * are `#RRGGBB` in upper case (a `#RGB` is expanded, any other text is kept as written), numbers
  * are parsed with parseFloat, the position is `[x, y, 0]` and the shape is the yFiles shape type
  * as written. One difference: a label whose text is a number (`<y:NodeLabel>0</y:NodeLabel>`) is
@@ -52,6 +52,7 @@ const EDGE_FIELDS: Readonly<Record<string, Omit<ColumnDecl, "name">>> = {
  * @param field - the field name (a key of the values graphicsValues() returns)
  * @param keyId - the id of the GraphML key whose tree it is read from
  * @returns the declaration
+ * @category Plugin helpers
  */
 export function graphicsDecl(domain: "node" | "edge", field: string, keyId: string): ColumnDecl {
     const fields = domain === "node" ? NODE_FIELDS : EDGE_FIELDS;
@@ -76,6 +77,7 @@ export function graphicsDecl(domain: "node" | "edge", field: string, keyId: stri
  * @param meta.dtype - the column dtype
  * @param meta.origin - the column origin
  * @returns true for a mapped graphics column
+ * @category Plugin helpers
  */
 export function isGraphicsColumn(meta: {
     readonly name: string;
@@ -95,6 +97,7 @@ export function isGraphicsColumn(meta: {
  * @param table - the table it is in
  * @param domain - node or edge
  * @returns the number of rows that differ from the trees
+ * @category Plugin helpers
  */
 export function staleGraphicsRows(column: Column, table: Iterable<Column>, domain: "node" | "edge"): number {
     const field = column.meta.name.slice(YFILES_COLUMN_PREFIX.length);
@@ -130,19 +133,21 @@ export function staleGraphicsRows(column: Column, table: Iterable<Column>, domai
  * PolyLineEdge's for an edge; nothing for any other graphics (GenericNode, BezierEdge, ...).
  * @param domain - node or edge
  * @param tree - the `<data>` content as tree.ts builds it
+ * @param unmapped - receives the fields whose text is present but not a number (not mapped)
  * @returns field name -> value, in declaration order
+ * @category Plugin helpers
  */
-export function graphicsValues(domain: "node" | "edge", tree: unknown): [string, unknown][] {
+export function graphicsValues(domain: "node" | "edge", tree: unknown, unmapped: string[] = []): [string, unknown][] {
     const out: [string, unknown][] = [];
     if (domain === "node") {
         const shape = child(tree, "ShapeNode");
         if (shape !== undefined) {
-            shapeNodeValues(shape, out);
+            shapeNodeValues(shape, out, unmapped);
         }
     } else {
         const edge = child(tree, "PolyLineEdge");
         if (edge !== undefined) {
-            polyLineEdgeValues(edge, out);
+            polyLineEdgeValues(edge, out, unmapped);
         }
     }
     return out;
@@ -152,21 +157,22 @@ export function graphicsValues(domain: "node" | "edge", tree: unknown): [string,
  * Read a ShapeNode.
  * @param shape - the ShapeNode element
  * @param out - receives the values
+ * @param unmapped - receives the fields whose text is not a number
  */
-function shapeNodeValues(shape: unknown, out: [string, unknown][]): void {
+function shapeNodeValues(shape: unknown, out: [string, unknown][], unmapped: string[]): void {
     const geometry = child(shape, "Geometry");
     // yFiles requires x, y, width and height on Geometry; a position needs both coordinates
-    const x = number(attr(geometry, "x"));
-    const y = number(attr(geometry, "y"));
+    const x = checked(attr(geometry, "x"), "x", unmapped);
+    const y = checked(attr(geometry, "y"), "y", unmapped);
     if (x !== undefined && y !== undefined) {
         out.push(["position", [x, y, 0]]);
     }
-    push(out, "width", number(attr(geometry, "width")));
-    push(out, "height", number(attr(geometry, "height")));
+    push(out, "width", checked(attr(geometry, "width"), "width", unmapped));
+    push(out, "height", checked(attr(geometry, "height"), "height", unmapped));
     push(out, "color", color(attr(child(shape, "Fill"), "color")));
     const border = child(shape, "BorderStyle");
     push(out, "borderColor", color(attr(border, "color")));
-    push(out, "borderWidth", number(attr(border, "width")));
+    push(out, "borderWidth", checked(attr(border, "width"), "borderWidth", unmapped));
     const label = child(shape, "NodeLabel");
     // an element with no text and no attributes is "" (no label); one with attributes but no text is a blank label
     if (typeof label === "string" ? label.length > 0 : label !== undefined) {
@@ -180,11 +186,12 @@ function shapeNodeValues(shape: unknown, out: [string, unknown][]): void {
  * Read a PolyLineEdge.
  * @param edge - the PolyLineEdge element
  * @param out - receives the values
+ * @param unmapped - receives the fields whose text is not a number
  */
-function polyLineEdgeValues(edge: unknown, out: [string, unknown][]): void {
+function polyLineEdgeValues(edge: unknown, out: [string, unknown][], unmapped: string[]): void {
     const line = child(edge, "LineStyle");
     push(out, "color", color(attr(line, "color")));
-    push(out, "width", number(attr(line, "width")));
+    push(out, "width", checked(attr(line, "width"), "width", unmapped));
     const arrows = child(edge, "Arrows");
     if (arrows !== undefined && typeof arrows === "object") {
         const target = attr(arrows, "target");
@@ -273,9 +280,24 @@ function number(value: string | undefined): number | undefined {
 }
 
 /**
- * A colour attribute: `#RRGGBB` upper-cased, `#RGB` expanded, anything else as written.
+ * A number attribute, recording a present text that is not a number.
  * @param value - the text
- * @returns the colour, or undefined when absent or empty
+ * @param field - the field it maps to
+ * @param unmapped - receives the field when the text is not a number
+ * @returns the number, or undefined
+ */
+function checked(value: string | undefined, field: string, unmapped: string[]): number | undefined {
+    const n = number(value);
+    if (n === undefined && value !== undefined && value.length > 0) {
+        unmapped.push(field);
+    }
+    return n;
+}
+
+/**
+ * A color attribute: `#RRGGBB` upper-cased, `#RGB` expanded, anything else as written.
+ * @param value - the text
+ * @returns the color, or undefined when absent or empty
  */
 function color(value: string | undefined): string | undefined {
     if (value === undefined || value.length === 0) {

package/src/formats/json/dialect.ts

@@ -8,20 +8,27 @@
  * / `graph`), the d3 lineage of the same shape (`links`, `name` ids, integer index endpoints),
  * JSON Graph Format v2 (`graph.nodes` keyed by id, per-edge `directed`, hyperedges), Cytoscape.js
  * elements (`data.id` / `data.source` / `data.target`, `position`, `classes`, `data.parent`),
- * graphology serialisation (`key` / `attributes`, `undirected` edges, `options.type` / `multi`) and
+ * graphology serialization (`key` / `attributes`, `undirected` edges, `options.type` / `multi`) and
  * vis.js (`from` / `to`); read only: NetworkX adjacency_data (`nodes` + `adjacency`) and tree_data
  * (nested `id` / `children`).
  */
 
-import { type GraphMeta } from "@graphty/graph-format";
+import { type GraphMeta, type GraphSnapshot } from "@graphty/graph-format";
 
 import { capabilities } from "../../common/export.js";
+import { trimTrailingZeros } from "../../common/text.js";
 import { type ExportCapabilities } from "../../types.js";
 
-/** The JSON dialects the plugin reads and writes. */
-export type JsonDialect = "node-link" | "d3" | "jgf" | "cytoscape" | "graphology" | "vis";
+/**
+ * The JSON dialects the plugin reads and writes.
+ * @category Built-in formats
+ */
+export type JsonDialect = "node-link" | "d3" | "jgf" | "cytoscape" | "graphology" | "vis" | "obographs";
 
-/** Every dialect name, for option checking and messages. */
+/**
+ * Every dialect name, for option checking and messages.
+ * @category Built-in formats
+ */
 export const JSON_DIALECTS: readonly JsonDialect[] = Object.freeze([
     "node-link",
     "d3",
@@ -29,31 +36,38 @@ export const JSON_DIALECTS: readonly JsonDialect[] = Object.freeze([
     "cytoscape",
     "graphology",
     "vis",
+    "obographs",
 ]);
 
 /**
- * The dialects the importer reads: every JsonDialect plus three it only reads, NetworkX
- * adjacency_data (`nodes` plus one neighbour list per node under `adjacency`), tree_data (a
- * nested `id` / `children` record) and OBO Graphs (`graphs[]` of `sub` / `pred` / `obj` edges, the
- * JSON form of the Gene Ontology and the OBO Foundry ontologies). The exporter writes none of them.
+ * The dialects the importer reads: every JsonDialect plus two it only reads, NetworkX
+ * adjacency_data (`nodes` plus one neighbor list per node under `adjacency`) and tree_data (a
+ * nested `id` / `children` record). The exporter writes neither.
+ * @category Built-in formats
  */
-export type JsonImportDialect = JsonDialect | "adjacency" | "tree" | "obographs";
+export type JsonImportDialect = JsonDialect | "adjacency" | "tree";
 
-/** Every dialect the importer reads, for option checking and messages. */
+/**
+ * Every dialect the importer reads, for option checking and messages.
+ * @category Plugin helpers
+ */
 export const JSON_IMPORT_DIALECTS: readonly JsonImportDialect[] = Object.freeze([
     ...JSON_DIALECTS,
     "adjacency",
     "tree",
-    "obographs",
 ]);
 
-/** The key under `meta.extra` that holds the shape record (design section 8.5). */
+/**
+ * The key under `meta.extra` that holds the shape record (design section 8.5).
+ * @category Plugin helpers
+ */
 export const META_KEY = "json";
 
 /**
  * The shape information the importer records under `meta.extra.json` so the exporter can write the
- * same file back (design section 8.5). Every field is optional because a snapshot may come from
- * another format or from an older record.
+ * same file back; `jsonShapeOf(snapshot)` reads it. Every field is optional because a graph may
+ * come from another format.
+ * @category Built-in formats
  */
 export interface JsonShapeMeta {
     /** The dialect the file was read as. */
@@ -78,10 +92,24 @@ export interface JsonShapeMeta {
     readonly cytoscape?: Readonly<Record<string, unknown>> | undefined;
 }
 
+/**
+ * What a JSON import recorded about the document's shape: the dialect it was read as
+ * (`jsonShapeOf(snapshot)?.dialect`), the keys it used, and so on. A JSON export with default
+ * options writes the same shape back.
+ * @param snapshot - a graph read from a JSON document
+ * @returns the shape, or null for a graph that was not read from JSON
+ * @category Built-in formats
+ */
+export function jsonShapeOf(snapshot: GraphSnapshot): JsonShapeMeta | null {
+    const shape = snapshot.meta.extra[META_KEY];
+    return isJsonObject(shape) ? (shape as JsonShapeMeta) : null;
+}
+
 /**
  * Whether a value is a plain JSON object (not null, not an array).
  * @param value - any value
  * @returns true for an object that is not an array
+ * @category Plugin helpers
  */
 export function isJsonObject(value: unknown): value is Record<string, unknown> {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -93,6 +121,7 @@ export function isJsonObject(value: unknown): value is Record<string, unknown> {
  * @param record - the record
  * @param key - the key
  * @returns true when the key is an own property
+ * @category Plugin helpers
  */
 export function hasKey(record: Readonly<Record<string, unknown>>, key: string): boolean {
     return Object.prototype.hasOwnProperty.call(record, key);
@@ -102,6 +131,7 @@ export function hasKey(record: Readonly<Record<string, unknown>>, key: string):
  * Whether a text names a dialect.
  * @param value - any value
  * @returns true for one of JSON_DIALECTS
+ * @category Plugin helpers
  */
 export function isJsonDialect(value: unknown): value is JsonDialect {
     return typeof value === "string" && (JSON_DIALECTS as readonly string[]).includes(value);
@@ -111,6 +141,7 @@ export function isJsonDialect(value: unknown): value is JsonDialect {
  * Whether a text names a dialect the importer reads.
  * @param value - any value
  * @returns true for one of JSON_IMPORT_DIALECTS
+ * @category Plugin helpers
  */
 export function isJsonImportDialect(value: unknown): value is JsonImportDialect {
     return typeof value === "string" && (JSON_IMPORT_DIALECTS as readonly string[]).includes(value);
@@ -121,13 +152,15 @@ export function isJsonImportDialect(value: unknown): value is JsonImportDialect
  * `elements` or a top-level array of `{ data }` elements; OBO Graphs: `graphs[]` whose first graph
  * has an edge with `sub` (or `subj`) and `obj` or a `pred`, or a node with `lbl`, `meta` or an OWL
  * `type`; JGF: `graph.nodes` / `graph.edges` or any other `graphs[]`; graphology: `options.type` / `options.multi`, `key` nodes without `id`, edges with
- * `undirected` or an `attributes` record; vis: edges with `from` / `to`; d3: `links` without
+ * `undirected` or an `attributes` record, and vis: edges with `from` / `to`, both only without
+ * NetworkX's `links` / `directed` / `multigraph` / `graph` keys; d3: `links` without
  * `directed` / `multigraph` / `graph`; NetworkX adjacency_data: `nodes` and `adjacency` without
  * `links` / `edges`; NetworkX tree_data: `children` without `nodes` / `links` / `edges`; else
  * node-link). Pure: the importer wraps it with its issue
  * codes, the registry's sniff() uses it on a head that parses as a whole document.
  * @param root - the parsed document
  * @returns the dialect, or null when the document is not a graph document in any dialect
+ * @category Plugin helpers
  */
 export function sniffJsonDialect(root: unknown): JsonImportDialect | null {
     if (Array.isArray(root)) {
@@ -144,7 +177,8 @@ export function sniffJsonDialect(root: unknown): JsonImportDialect | null {
         return "jgf";
     }
     if (Array.isArray(root.graphs)) {
-        return isOboGraph(firstJsonObject(root.graphs)) ? "obographs" : "jgf";
+        // any graph decides: an ontology's first graph may be an empty stub before its imports
+        return root.graphs.some((g: unknown) => isJsonObject(g) && isOboGraph(g)) ? "obographs" : "jgf";
     }
     if (!hasKey(root, "edges") && !hasKey(root, "links")) {
         if (hasKey(root, "nodes") && hasKey(root, "adjacency")) {
@@ -159,15 +193,25 @@ export function sniffJsonDialect(root: unknown): JsonImportDialect | null {
     if (isJsonObject(root.options) && (hasKey(root.options, "type") || hasKey(root.options, "multi"))) {
         return "graphology";
     }
-    if (firstNode !== null && hasKey(firstNode, "key") && !hasKey(firstNode, "id")) {
+    // NetworkX's own keys (links, directed, multigraph, graph) settle node-link: one attribute named
+    // like a graphology or vis field (`attributes`, `undirected`, `key`, `from`) must not re-route it
+    const networkx =
+        hasKey(root, "links") || hasKey(root, "directed") || hasKey(root, "multigraph") || hasKey(root, "graph");
+    if (!networkx && firstNode !== null && hasKey(firstNode, "key") && !hasKey(firstNode, "id")) {
         return "graphology";
     }
-    if (firstEdge !== null && !hasKey(firstEdge, "from")) {
+    if (!networkx && firstEdge !== null && !hasKey(firstEdge, "from")) {
         if (hasKey(firstEdge, "undirected") || isJsonObject(firstEdge.attributes)) {
             return "graphology";
         }
     }
-    if (firstEdge !== null && hasKey(firstEdge, "from") && hasKey(firstEdge, "to") && !hasKey(firstEdge, "source")) {
+    if (
+        !networkx &&
+        firstEdge !== null &&
+        hasKey(firstEdge, "from") &&
+        hasKey(firstEdge, "to") &&
+        !hasKey(firstEdge, "source")
+    ) {
         return "vis";
     }
     const bare = !hasKey(root, "directed") && !hasKey(root, "multigraph") && !hasKey(root, "graph");
@@ -217,6 +261,7 @@ function firstJsonObject(value: unknown): Record<string, unknown> | null {
  * from the JSON importer.
  * @param meta - the snapshot's metadata
  * @returns the fields found under `meta.extra.json`, each only when it has the expected type
+ * @category Plugin helpers
  */
 export function shapeMetaOf(meta: GraphMeta): JsonShapeMeta {
     const raw: unknown = meta.extra[META_KEY];
@@ -240,7 +285,10 @@ export function shapeMetaOf(meta: GraphMeta): JsonShapeMeta {
     };
 }
 
-/** The direction a dialect assumes when the file declares none (design section 8.4, `defaultDirected`). */
+/**
+ * The direction a dialect assumes when the file declares none (design section 8.4, `defaultDirected`).
+ * @category Plugin helpers
+ */
 export const DIALECT_DEFAULT_DIRECTED: Readonly<Record<JsonImportDialect, boolean>> = Object.freeze({
     "node-link": false,
     d3: false,
@@ -322,10 +370,19 @@ const TABLES: Readonly<Record<JsonDialect, ExportCapabilities>> = Object.freeze(
         hierarchy: false,
         graphAttributes: false,
     }),
+    // the OBO flat file's table: no column of the snapshot's own reads back as a column (the
+    // vocabulary columns have their places; every other one becomes property values or edge meta)
+    obographs: capabilities({
+        mixedDirection: false,
+        multiEdges: true,
+        selfLoops: true,
+        edgeIds: "none",
+        idCharset: "any",
+    }),
 });
 
 /**
- * What one dialect can express (design section 8.5): positions and visual columns are written as
+ * What one dialect can express: positions and visual columns are written as
  * plain attributes (an array for a multi-component column) and read back without their role,
  * except Cytoscape's `position` object; containment only as the Cytoscape `data.parent`; mixed
  * direction only where the dialect carries a per-edge flag (JGF `directed`, graphology
@@ -333,12 +390,16 @@ const TABLES: Readonly<Record<JsonDialect, ExportCapabilities>> = Object.freeze(
  * graph attributes everywhere but d3 (the bare shape) and vis.
  * @param dialect - the dialect
  * @returns its frozen capability table
+ * @category Built-in formats
  */
 export function dialectCapabilities(dialect: JsonDialect): ExportCapabilities {
     return TABLES[dialect];
 }
 
-/** The Cytoscape element-level keys (everything else on an element lives under `data`). */
+/**
+ * The Cytoscape element-level keys (everything else on an element lives under `data`).
+ * @category Plugin helpers
+ */
 export const CYTOSCAPE_ELEMENT_KEYS: ReadonlySet<string> = new Set([
     "selected",
     "selectable",
@@ -350,13 +411,17 @@ export const CYTOSCAPE_ELEMENT_KEYS: ReadonlySet<string> = new Set([
     "renderedPosition",
 ]);
 
-/** The Cytoscape element keys the importer maps structurally rather than to columns. */
+/**
+ * The Cytoscape element keys the importer maps structurally rather than to columns.
+ * @category Plugin helpers
+ */
 export const CYTOSCAPE_STRUCTURAL_KEYS: ReadonlySet<string> = new Set(["data", "group", "position", "classes"]);
 
 /**
  * The suffix the importer appends to a column name that collides with a structural column or a
  * reserved key of its dialect (design section 5.6 names collisions deterministically); the exporter
  * strips it when the value goes back to the level the suffix names.
+ * @category Plugin helpers
  */
 export const SUFFIX = Object.freeze({
     /** A Cytoscape `data` key or a JGF / graphology attribute that collides with a structural column. */
@@ -365,17 +430,51 @@ export const SUFFIX = Object.freeze({
     element: "#element",
 });
 
-/** The default source keys of a node-link edge record, tried in order (as fromRecords does). */
+/**
+ * The default source keys of a node-link edge record, tried in order (as fromRecords does).
+ * @category Plugin helpers
+ */
 export const NODE_LINK_SOURCE_KEYS: readonly string[] = Object.freeze(["source", "src", "from"]);
 
-/** The default target keys of a node-link edge record, tried in order. */
+/**
+ * The default target keys of a node-link edge record, tried in order.
+ * @category Plugin helpers
+ */
 export const NODE_LINK_TARGET_KEYS: readonly string[] = Object.freeze(["target", "dst", "to"]);
 
-/** The name of the position column every JSON dialect writes / reads (design section 5.2). */
+/**
+ * The name of the position column every JSON dialect writes / reads (design section 5.2).
+ * @category Plugin helpers
+ */
 export const POSITION_COLUMN = "position";
 
-/** The name of the Cytoscape classes column (a list of strings with role "classes"). */
+/**
+ * The name of the Cytoscape classes column (a list of strings with role "classes").
+ * @category Plugin helpers
+ */
 export const CLASSES_COLUMN = "classes";
 
-/** The name of the Cytoscape parent column (u32 refersTo node, role "parent"). */
+/**
+ * The name of the Cytoscape parent column (u32 refersTo node, role "parent").
+ * @category Plugin helpers
+ */
 export const PARENT_COLUMN = "parent";
+
+/**
+ * An integer text beyond 2^53 in exponent form (`100000000000000000000` -> `1e+20`, the same
+ * digits): the importer reads an integer literal that large as its exact digits (a string), so
+ * a number must not be written as one.
+ * @param text - the shortest decimal text of a finite number
+ * @returns the text, or its exponent form for an integer literal of 16 or more digits
+ * @category Plugin helpers
+ */
+export function exponentIfUnsafe(text: string): string {
+    const match = /^(-?)(\d{16,})$/.exec(text);
+    if (match === null || Number.isSafeInteger(Number(text))) {
+        return text;
+    }
+    const [, sign, digits] = match;
+    const mantissa = trimTrailingZeros(digits);
+    const fraction = mantissa.length > 1 ? `.${mantissa.slice(1)}` : "";
+    return `${sign}${mantissa[0]}${fraction}e+${digits.length - 1}`;
+}