@graphty/graph-io 0.3.40 → 0.3.41

package/src/formats/gml/exporter.ts

@@ -420,6 +420,20 @@ function note(code: string, message: string, column: string | null = null, count
     return Object.freeze({ code, message, column, count });
 }
 
+/**
+ * Count a kind of json value once per row.
+ * @param seen - the flags already counted for this row
+ * @param flag - the flag of the kind
+ * @param stats - the counters
+ * @param counter - the counter of the kind
+ */
+function countOnce(seen: SeenFlags, flag: keyof SeenFlags, stats: JsonStats, counter: keyof JsonStats): void {
+    if (!seen[flag]) {
+        seen[flag] = true;
+        stats[counter]++;
+    }
+}
+
 /**
  * Inspect a JSON value for what GML cannot write exactly.
  * @param value - the value
@@ -429,24 +443,15 @@ function note(code: string, message: string, column: string | null = null, count
  */
 function inspectJson(value: unknown, stats: JsonStats, inArray: boolean, seen: SeenFlags): void {
     if (value === null) {
-        if (!seen.nulls) {
-            seen.nulls = true;
-            stats.nulls++;
-        }
+        countOnce(seen, "nulls", stats, "nulls");
         return;
     }
     switch (typeof value) {
         case "number":
-            if (!seen.numbers) {
-                seen.numbers = true;
-                stats.numbers++;
-            }
+            countOnce(seen, "numbers", stats, "numbers");
             return;
         case "boolean":
-            if (!seen.booleans) {
-                seen.booleans = true;
-                stats.booleans++;
-            }
+            countOnce(seen, "booleans", stats, "booleans");
             return;
         case "string":
             return;
@@ -454,9 +459,8 @@ function inspectJson(value: unknown, stats: JsonStats, inArray: boolean, seen: S
             break;
     }
     if (Array.isArray(value)) {
-        if (inArray && !seen.nested) {
-            seen.nested = true;
-            stats.nestedArrays++;
+        if (inArray) {
+            countOnce(seen, "nested", stats, "nestedArrays");
         }
         for (const item of value) {
             inspectJson(item, stats, true, seen);
@@ -472,6 +476,29 @@ function inspectJson(value: unknown, stats: JsonStats, inArray: boolean, seen: S
     }
 }
 
+/**
+ * A row count in words.
+ * @param count - the count
+ * @returns the count and the word row, pluralised
+ */
+function rowCount(count: number): string {
+    return `${count} row${plural(count)}`;
+}
+
+/**
+ * Record a note for a counter that is not zero.
+ * @param notes - where to record
+ * @param count - the counter
+ * @param code - the note code
+ * @param text - the note message
+ * @param column - the column name
+ */
+function pushCounted(notes: LossNote[], count: number, code: string, text: string, column: string): void {
+    if (count > 0) {
+        notes.push(note(code, text, column, count));
+    }
+}
+
 /**
  * The GML-specific notes of one table's json columns.
  * @param columns - the written columns
@@ -487,73 +514,42 @@ function jsonNotes(columns: readonly WrittenColumn[], label: string, plan: GmlEx
         }
         const { name } = column.meta;
         const where = `${label} column "${name}"`;
-        if (stats.numbers > 0) {
-            notes.push(
-                note(
-                    RECORD_NUMBER_TYPE_CODE,
-                    `${where} holds numbers in ${stats.numbers} row${plural(stats.numbers)}; GML records cannot keep the int / real distinction`,
-                    name,
-                    stats.numbers,
-                ),
-            );
-        }
-        if (stats.booleans > 0) {
-            notes.push(
-                note(
-                    RECORD_BOOLEAN_CODE,
-                    `${where} holds booleans in ${stats.booleans} row${plural(stats.booleans)}; written as 1 / 0`,
-                    name,
-                    stats.booleans,
-                ),
-            );
-        }
-        if (stats.nulls > 0) {
-            notes.push(
-                note(
-                    RECORD_NULL_CODE,
-                    `${where} holds nulls in ${stats.nulls} row${plural(stats.nulls)}; GML has no null, the key is omitted`,
-                    name,
-                    stats.nulls,
-                ),
-            );
-        }
-        if (stats.arrays > 0) {
-            notes.push(
-                note(
-                    JSON_ARRAY_CODE,
-                    `${where} holds arrays as values in ${stats.arrays} row${plural(stats.arrays)}; written as repeated keys, they re-import as a list`,
-                    name,
-                    stats.arrays,
-                ),
-            );
-        }
-        if (stats.nestedArrays > 0) {
-            notes.push(
-                note(
-                    NESTED_ARRAY_CODE,
-                    `${where} holds arrays nested in arrays in ${stats.nestedArrays} row${plural(stats.nestedArrays)}; GML cannot write them and the save fails`,
-                    name,
-                    stats.nestedArrays,
-                ),
-            );
-        }
-        if (stats.invalidKeys > 0) {
-            notes.push(
-                plan.mangle
-                    ? note(
-                          KEY_MANGLED_CODE,
-                          `${where}: ${stats.invalidKeys} record key${plural(stats.invalidKeys)} ${agree(stats.invalidKeys, "is", "are")} not GML keys and are rewritten`,
-                          name,
-                          stats.invalidKeys,
-                      )
-                    : note(
-                          INVALID_KEY_CODE,
-                          `${where}: ${stats.invalidKeys} record key${plural(stats.invalidKeys)} ${agree(stats.invalidKeys, "is", "are")} not GML keys; the save fails unless sanitizeKeys is "mangle"`,
-                          name,
-                          stats.invalidKeys,
-                      ),
-            );
-        }
+        const counted = (count: number, code: string, text: string): void => {
+            pushCounted(notes, count, code, text, name);
+        };
+        counted(
+            stats.numbers,
+            RECORD_NUMBER_TYPE_CODE,
+            `${where} holds numbers in ${rowCount(stats.numbers)}; GML records cannot keep the int / real distinction`,
+        );
+        counted(
+            stats.booleans,
+            RECORD_BOOLEAN_CODE,
+            `${where} holds booleans in ${rowCount(stats.booleans)}; written as 1 / 0`,
+        );
+        counted(
+            stats.nulls,
+            RECORD_NULL_CODE,
+            `${where} holds nulls in ${rowCount(stats.nulls)}; GML has no null, the key is omitted`,
+        );
+        counted(
+            stats.arrays,
+            JSON_ARRAY_CODE,
+            `${where} holds arrays as values in ${rowCount(stats.arrays)}; written as repeated keys, they re-import as a list`,
+        );
+        counted(
+            stats.nestedArrays,
+            NESTED_ARRAY_CODE,
+            `${where} holds arrays nested in arrays in ${rowCount(stats.nestedArrays)}; GML cannot write them and the save fails`,
+        );
+        const keys = `${stats.invalidKeys} record key${plural(stats.invalidKeys)} ${agree(stats.invalidKeys, "is", "are")} not GML keys`;
+        counted(
+            stats.invalidKeys,
+            plan.mangle ? KEY_MANGLED_CODE : INVALID_KEY_CODE,
+            plan.mangle
+                ? `${where}: ${keys} and are rewritten`
+                : `${where}: ${keys}; the save fails unless sanitizeKeys is "mangle"`,
+        );
     }
 }
 

package/src/formats/gml/importer.ts

@@ -518,31 +518,50 @@ class GmlImport {
             if (key === "graph" && !record && scalarGraph < 0) {
                 scalarGraph = v;
             }
-            if (key === "graph" && record) {
-                if (this.graphCount++ === this.which) {
-                    this.graphOpen = v;
-                    this.scanGraph(v);
-                }
-            } else if (key === "Creator" && !record && this.creatorToken < 0) {
-                this.creatorToken = v;
-            } else if (key === "Version" && !record && this.versionToken < 0) {
-                this.versionToken = v;
-            } else {
-                this.observe(this.topSchema, "graph", key, v, TOP_SEQ);
-            }
+            this.scanTopPair(key, record, v);
         }
         if (this.graphOpen < 0) {
-            if (scalarGraph >= 0) {
-                this.report.fail(
-                    NO_GRAPH_CODE,
-                    `the graph key at line ${t.line[scalarGraph]} holds ${describeValue(t, scalarGraph)}, not a [ ... ] block; the input contains no graph block`,
-                    { line: t.line[scalarGraph] },
-                );
+            this.failNoGraph(t, scalarGraph);
+        }
+    }
+
+    /**
+     * Handle one top-level pair other than a scalar `graph`.
+     * @param key - the key
+     * @param record - whether the value is a `[ ... ]` block
+     * @param v - the value token
+     */
+    private scanTopPair(key: string, record: boolean, v: number): void {
+        if (key === "graph" && record) {
+            if (this.graphCount++ === this.which) {
+                this.graphOpen = v;
+                this.scanGraph(v);
             }
-            this.report.fail(NO_GRAPH_CODE, "the input contains no graph [ ... ] block", { line: null });
+        } else if (key === "Creator" && !record && this.creatorToken < 0) {
+            this.creatorToken = v;
+        } else if (key === "Version" && !record && this.versionToken < 0) {
+            this.versionToken = v;
+        } else {
+            this.observe(this.topSchema, "graph", key, v, TOP_SEQ);
         }
     }
 
+    /**
+     * Fail because the input holds no graph block.
+     * @param t - the tokens
+     * @param scalarGraph - the token of a scalar `graph` key, or -1
+     */
+    private failNoGraph(t: ReturnType<GmlImport["requireTokens"]>, scalarGraph: number): void {
+        if (scalarGraph >= 0) {
+            this.report.fail(
+                NO_GRAPH_CODE,
+                `the graph key at line ${t.line[scalarGraph]} holds ${describeValue(t, scalarGraph)}, not a [ ... ] block; the input contains no graph block`,
+                { line: t.line[scalarGraph] },
+            );
+        }
+        this.report.fail(NO_GRAPH_CODE, "the input contains no graph [ ... ] block", { line: null });
+    }
+
     /**
      * Walk the graph block for the schema.
      * @param open - the index of the block's `[`
@@ -592,31 +611,43 @@ class GmlImport {
         const close = t.match[open];
         const seq = this.seq++;
         const schema = domain === "node" ? this.nodeSchema : this.edgeSchema;
-        const { weightFrom, restoreMangledIds } = this.options;
         for (let p = open + 1; p < close; p = t.nextPair(p)) {
             const key = t.textOf(p);
             const v = p + 1;
-            if (domain === "node") {
-                if (key === "id") {
-                    continue;
-                }
-                if (key === ORIGINAL_ID_KEY && restoreMangledIds) {
-                    this.hasOriginalId = true;
-                    continue;
-                }
-            } else {
-                if (key === "source" || key === "target" || key === "directed") {
-                    continue;
-                }
-                if (key === weightFrom) {
-                    this.weightKinds |= kindBit(t, v);
-                    continue;
-                }
+            if (this.skipsKey(domain, key, v)) {
+                continue;
             }
             this.observe(schema, domain, key, v, seq);
         }
     }
 
+    /**
+     * Whether a key of a node or edge block is structural (id, endpoints, weight, original id), not
+     * a column; notes the original id and the weight's kinds on the way.
+     * @param domain - node or edge
+     * @param key - the key
+     * @param v - the value token
+     * @returns true when the key is not a column
+     */
+    private skipsKey(domain: "node" | "edge", key: string, v: number): boolean {
+        const { weightFrom, restoreMangledIds } = this.options;
+        if (domain === "node") {
+            if (key === ORIGINAL_ID_KEY && restoreMangledIds) {
+                this.hasOriginalId = true;
+                return true;
+            }
+            return key === "id";
+        }
+        if (key === "source" || key === "target" || key === "directed") {
+            return true;
+        }
+        if (key === weightFrom) {
+            this.weightKinds |= kindBit(this.requireTokens(), v);
+            return true;
+        }
+        return false;
+    }
+
     /**
      * Record one value of one key in a table's schema.
      * @param schema - the table's schema
@@ -816,26 +847,12 @@ class GmlImport {
     }
 
     /**
-     * The plan of one schema entry.
+     * Warn about a key that mixes numbers and strings, or holds integers beyond 2^53.
      * @param domain - the table
      * @param entry - the schema entry
-     * @param top - whether the key is a top-level one (graph table)
-     * @returns the plan
+     * @param asText - whether the integers are kept as text
      */
-    private planOf(domain: "node" | "edge" | "graph", entry: KeySchema, top = false): ColumnPlan {
-        // long: "string" keeps every digit of an integer key that holds values beyond 2^53, as text
-        const asText = entry.unsafe && this.options.long === "string" && kindOf(entry) === "int";
-        const kind = asText ? "string" : kindOf(entry);
-        let scalar: ScalarDtype = dtypeOfKind(kind, entry);
-        if (
-            scalar === "string" &&
-            !entry.list &&
-            entry.dict !== null &&
-            entry.kinds === KIND_STRING &&
-            entry.dict.decide() === "dict"
-        ) {
-            scalar = "dict";
-        }
+    private warnKinds(domain: "node" | "edge" | "graph", entry: KeySchema, asText: boolean): void {
         if (
             (entry.kinds & KIND_STRING) !== 0 &&
             (entry.kinds & (KIND_INT | KIND_REAL)) !== 0 &&
@@ -858,6 +875,54 @@ class GmlImport {
                 `${PRECISION_CODE}:${domain}:${entry.key}`,
             );
         }
+    }
+
+    /**
+     * The plan of a node `graphics` record: the plan plus its position and rest columns.
+     * @param plan - the record's plan
+     * @param entry - the schema entry
+     * @returns the plan with its position (and rest) plans
+     */
+    private graphicsPlan(plan: ColumnPlan, entry: KeySchema): ColumnPlan {
+        const taken = (candidate: string): boolean =>
+            this.nodeSchema.has(candidate) || this.sink.nodeColumn(candidate) !== INVALID_INDEX;
+        const position: ColumnPlan = {
+            ...plan,
+            name: uniqueColumnName("position", "graphics", taken),
+            dtype: "f64",
+            itemDtype: null,
+            kind: "real",
+            list: false,
+            role: "position",
+        };
+        const rest: ColumnPlan | null = entry.rest
+            ? { ...plan, dtype: "json", itemDtype: null, kind: "record", list: false }
+            : null;
+        return { ...plan, position, rest };
+    }
+
+    /**
+     * The plan of one schema entry.
+     * @param domain - the table
+     * @param entry - the schema entry
+     * @param top - whether the key is a top-level one (graph table)
+     * @returns the plan
+     */
+    private planOf(domain: "node" | "edge" | "graph", entry: KeySchema, top = false): ColumnPlan {
+        // long: "string" keeps every digit of an integer key that holds values beyond 2^53, as text
+        const asText = entry.unsafe && this.options.long === "string" && kindOf(entry) === "int";
+        const kind = asText ? "string" : kindOf(entry);
+        let scalar: ScalarDtype = dtypeOfKind(kind, entry);
+        if (
+            scalar === "string" &&
+            !entry.list &&
+            entry.dict !== null &&
+            entry.kinds === KIND_STRING &&
+            entry.dict.decide() === "dict"
+        ) {
+            scalar = "dict";
+        }
+        this.warnKinds(domain, entry, asText);
         const name = domain === "graph" ? this.uniqueGraphName(entry.key) : entry.key;
         let itemDtype: ScalarDtype | null = null;
         if (entry.list) {
@@ -880,21 +945,7 @@ class GmlImport {
             seq: Number.NEGATIVE_INFINITY,
         };
         if (domain === "node" && entry.key === "graphics" && this.positions && (entry.kinds & KIND_RECORD) !== 0) {
-            const taken = (candidate: string): boolean =>
-                this.nodeSchema.has(candidate) || this.sink.nodeColumn(candidate) !== INVALID_INDEX;
-            const position: ColumnPlan = {
-                ...plan,
-                name: uniqueColumnName("position", "graphics", taken),
-                dtype: "f64",
-                itemDtype: null,
-                kind: "real",
-                list: false,
-                role: "position",
-            };
-            const rest: ColumnPlan | null = entry.rest
-                ? { ...plan, dtype: "json", itemDtype: null, kind: "record", list: false }
-                : null;
-            return { ...plan, position, rest };
+            return this.graphicsPlan(plan, entry);
         }
         return plan;
     }

package/src/formats/gml/syntax.ts

@@ -583,14 +583,7 @@ export function parseRecord(tokens: GmlTokens, open: number): Record<string, unk
         const key = tokens.textOf(p);
         const v = p + 1;
         if (tokens.kind[v] === TOKEN_STRING) {
-            const text = tokens.stringOf(v);
-            if (text === LIST_START_MARKER) {
-                frame.record[key] = [];
-                frame.listKeys ??= new Set();
-                frame.listKeys.add(key);
-                continue;
-            }
-            storeValue(frame, key, text === EMPTY_LIST_TEXT || text === EMPTY_TUPLE_TEXT ? [] : text);
+            storeString(frame, key, tokens.stringOf(v));
         } else if (tokens.kind[v] === TOKEN_OPEN) {
             stack.push({
                 record: Object.create(null) as Record<string, unknown>,
@@ -606,6 +599,23 @@ export function parseRecord(tokens: GmlTokens, open: number): Record<string, unk
     return root;
 }
 
+/**
+ * Store a string value: the list-start marker opens an empty list for the key, the empty list and
+ * tuple texts store an empty list, anything else stores the text.
+ * @param frame - the open record
+ * @param key - the key
+ * @param text - the string
+ */
+function storeString(frame: RecordFrame, key: string, text: string): void {
+    if (text === LIST_START_MARKER) {
+        frame.record[key] = [];
+        frame.listKeys ??= new Set();
+        frame.listKeys.add(key);
+        return;
+    }
+    storeValue(frame, key, text === EMPTY_LIST_TEXT || text === EMPTY_TUPLE_TEXT ? [] : text);
+}
+
 /**
  * Store one value under a key: appended to the key's list when the key is a list, paired with the
  * earlier value when the key repeats, set otherwise.

package/src/formats/graphml/exporter.ts

@@ -1153,6 +1153,30 @@ function writeTreeData(keyId: string, value: unknown, indent: string, out: strin
     out.push(`\n${indent}</data>`);
 }
 
+/**
+ * Append the `<default>` element of a key.
+ * @param key - the key
+ * @param column - the key's column
+ * @param inner - the indentation of the element
+ * @param parts - where to append
+ */
+function pushDefault(key: KeyPlan, column: Column, inner: string, parts: string[]): void {
+    if (key.yfilesType === null) {
+        parts.push(`\n${inner}<default>${escapeXmlText(defaultText(column, key.attrType) ?? "")}</default>`);
+        return;
+    }
+    const value = column.meta.default;
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        parts.push(`\n${inner}<default>`);
+        writeXmlTree(value, `${inner}  `, parts);
+        parts.push(`\n${inner}</default>`);
+    } else {
+        const tree: string[] = [];
+        writeXmlTree(value, inner, tree);
+        parts.push(`\n${inner}<default>${tree.join("")}</default>`);
+    }
+}
+
 /**
  * The `<key>` element of a plan.
  * @param key - the key plan
@@ -1183,20 +1207,7 @@ function keyElement(key: KeyPlan, indent: string): string {
         parts.push(`\n${inner}<desc>${escapeXmlText(desc)}</desc>`);
     }
     if (hasDefault) {
-        if (key.yfilesType !== null) {
-            const value = column.meta.default;
-            if (value !== null && typeof value === "object" && !Array.isArray(value)) {
-                parts.push(`\n${inner}<default>`);
-                writeXmlTree(value, `${inner}  `, parts);
-                parts.push(`\n${inner}</default>`);
-            } else {
-                const tree: string[] = [];
-                writeXmlTree(value, inner, tree);
-                parts.push(`\n${inner}<default>${tree.join("")}</default>`);
-            }
-        } else {
-            parts.push(`\n${inner}<default>${escapeXmlText(defaultText(column, key.attrType) ?? "")}</default>`);
-        }
+        pushDefault(key, column, inner, parts);
     }
     parts.push(`\n${indent}</key>\n`);
     return parts.join("");
@@ -1307,11 +1318,13 @@ function* writeGraphml(snapshot: GraphSnapshot, plan: Plan): Generator<string, v
     // nodes in containment order, children nested under their parent
     const { hierarchy } = plan;
     const nested = hierarchy.childList.length > 0;
-    const stackNode: number[] = [];
-    const stackCursor: number[] = [];
-    const written = nested ? new Uint8Array(snapshot.nodeCount) : null;
+    const walk: SubtreeWalk = {
+        stackNode: [],
+        stackCursor: [],
+        written: nested ? new Uint8Array(snapshot.nodeCount) : null,
+    };
     for (const rootNode of hierarchy.roots) {
-        yield* writeNodeSubtree(rootNode, plan, ids, i2, step, stackNode, stackCursor, written);
+        yield* writeNodeSubtree(rootNode, plan, ids, i2, step, walk);
     }
 
     // edges: primaries only, in index order
@@ -1378,6 +1391,16 @@ function portText(column: Column | null, e: number): string | null {
     return typeof value === "string" ? value : String(value);
 }
 
+/** The state a subtree walk reuses from one top-level node to the next. */
+interface SubtreeWalk {
+    /** A reusable stack of open nodes. */
+    readonly stackNode: number[];
+    /** A reusable stack of child cursors. */
+    readonly stackCursor: number[];
+    /** Nodes already written (null when nothing is nested). */
+    readonly written: Uint8Array | null;
+}
+
 /**
  * Write a top-level node and, nested, every node contained in it (iteratively, so a deep chain
  * cannot overflow the call stack).
@@ -1386,9 +1409,7 @@ function portText(column: Column | null, e: number): string | null {
  * @param ids - the sanitised ids
  * @param indent - the indentation of top-level nodes
  * @param step - one indentation step
- * @param stackNode - a reusable stack of open nodes
- * @param stackCursor - a reusable stack of child cursors
- * @param written - nodes already written (null when nothing is nested)
+ * @param walk - the reusable walk state
  * @yields the node elements
  * @returns nothing
  */
@@ -1398,10 +1419,9 @@ function* writeNodeSubtree(
     ids: SanitizedIds,
     indent: string,
     step: string,
-    stackNode: number[],
-    stackCursor: number[],
-    written: Uint8Array | null,
+    walk: SubtreeWalk,
 ): Generator<string, void, undefined> {
+    const { stackNode, stackCursor, written } = walk;
     const { hierarchy } = plan;
     const hasChildren = (u: number): boolean => hierarchy.childStart[u + 1] > hierarchy.childStart[u];
     const openNode = (u: number, depth: number): string => {

package/src/formats/graphml/importer.ts

@@ -1126,9 +1126,6 @@ class GraphmlReader implements XmlHandler {
         known: ReadonlySet<string>,
         line: number,
     ): void {
-        if (attrs.size === 0) {
-            return;
-        }
         for (const name of attrs.keys()) {
             if (known.has(name) || name === "xmlns" || /^(xmlns|xml|xsi):/.test(name)) {
                 continue;
@@ -1150,14 +1147,7 @@ class GraphmlReader implements XmlHandler {
             if (names.size > MAX_UNKNOWN_ATTRIBUTE_NAMES && !hint) {
                 continue;
             }
-            let message: string;
-            if (hint) {
-                message = `the <${kind}> parse hint ${name} is ignored`;
-            } else if (SCHEMA_ATTRIBUTES.has(name)) {
-                message = `the <${kind}> attribute ${name} is not kept`;
-            } else {
-                message = `the <${kind}> attribute ${name} is not a GraphML attribute; it is not kept`;
-            }
+            const message = unreadAttributeMessage(kind, name, hint);
             this.report.warning("unsupported", code, message, { line, element: name });
         }
     }
@@ -2729,3 +2719,20 @@ function unknownElementMessage(name: string): string {
         ? `element <${name}> is not allowed at this place in a GraphML file and was skipped`
         : `element <${name}> is not GraphML and was skipped`;
 }
+
+/**
+ * The warning text for an attribute the importer does not keep.
+ * @param kind - the element name
+ * @param name - the attribute name
+ * @param hint - whether the attribute is a `parse.*` hint
+ * @returns the message
+ */
+function unreadAttributeMessage(kind: string, name: string, hint: boolean): string {
+    if (hint) {
+        return `the <${kind}> parse hint ${name} is ignored`;
+    }
+    if (SCHEMA_ATTRIBUTES.has(name)) {
+        return `the <${kind}> attribute ${name} is not kept`;
+    }
+    return `the <${kind}> attribute ${name} is not a GraphML attribute; it is not kept`;
+}