@graphty/graph-io 0.0.0 → 0.2.0

package/dist/src/formats/graphml/exporter.js

@@ -0,0 +1,1176 @@
+/**
+ * The GraphML exporter (design section 8.5; research note 07 section 9): `<key>` declarations
+ * regenerated from ColumnMeta.origin when the column came from GraphML (key id, attr.name,
+ * attr.type, yfiles.type) and derived from the dtype otherwise; node ids sanitised to NMTOKEN
+ * (`sanitizeIds: "error"` refuses, `"mangle"` rewrites and keeps the original in a
+ * `graphty:originalId` data attribute the importer restores); mixed direction written with
+ * `edgedefault` plus per-edge `directed` attributes, folding expanded pairs back through the
+ * `pair` / `directed` role columns; explicit weights only (the role-weight column's validity);
+ * containment (`parent` role) as nested graphs; yFiles json columns as nested XML again.
+ *
+ * check() lists every loss before anything is written: the generic capability gaps of
+ * checkCapabilities() (dict / u32 / u8 dtypes, lists, components, options, positions, visual and
+ * temporal roles, extension tables) plus the GraphML-specific ones (mutual edges written as
+ * undirected, json columns without a yfiles origin written as JSON text, multi-parent columns,
+ * containment order, ids that change type under the canonical rule, edge ids that read back as
+ * strings, roles GraphML cannot express, yfiles values that are not serialisable trees).
+ */
+import { GraphFormatError, INVALID_INDEX } from "@graphty/graph-format";
+import { childrenCsr } from "../../children.js";
+import { pairFolding } from "../../common/direction.js";
+import { escapeXmlAttribute, escapeXmlText } from "../../common/escape.js";
+import { capabilities, checkCapabilities, isNmtoken, LOSS, mangleNmtoken, sanitizeIds, } from "../../common/export.js";
+import { formatF32, formatF64, formatInteger } from "../../common/format.js";
+import { isCanonicalIntegerText } from "../../common/ids.js";
+import { resolveExportOptions } from "../../common/options.js";
+import { explicitWeights } from "../../common/weights.js";
+import { encodeChunks, joinText } from "../../common/writer.js";
+import { xmlIllegalTextNotes } from "../../common/xml.js";
+import { EDGE_ID_COLUMN, FORMAT, GRAPHML_LOSS, GRAPHML_NAMESPACE, LABEL_COLUMN, META_KEY, ORIGINAL_ID_ATTRIBUTE, PARENT_COLUMN, RESERVED_EDGE_NAMES, RESERVED_NODE_NAMES, SCHEMA_LOCATION, SOURCE_PORT_COLUMN, TARGET_PORT_COLUMN, XSI_NAMESPACE, YFILES_NAMESPACE, } from "./constants.js";
+import { treeProblem, writeXmlTree } from "./tree.js";
+/** What GraphML keeps as declared (research note 07 section 9). */
+const CAPABILITIES = capabilities({
+    mixedDirection: true,
+    multiEdges: true,
+    selfLoops: true,
+    edgeIds: "optional",
+    idCharset: "nmtoken",
+    dtypes: ["bool", "i32", "f32", "f64", "string"],
+    components: false,
+    lists: false,
+    json: false,
+    defaults: true,
+    options: false,
+    hierarchy: true,
+    temporal: "none",
+    graphAttributes: true,
+    positions: false,
+    viz: false,
+});
+/** Roles handled structurally (never written as a key) or reported by checkCapabilities() and not written. */
+const STRUCTURAL_ROLES = new Set([
+    "directed",
+    "pair",
+    "mutual",
+    "weight",
+    "timeText",
+    "originalId",
+]);
+const DROPPED_ROLES = new Set([
+    "position",
+    "color",
+    "size",
+    "shape",
+    "thickness",
+    "start",
+    "end",
+    "timestamp",
+    "timestamps",
+    "spells",
+    "open",
+]);
+/**
+ * The roles GraphML has a slot for (checkCapabilities() reports every other role as lost): the
+ * label key, the edge `id`, `sourceport` and `targetport` attributes and nested graphs.
+ */
+const SLOT_ROLES = new Set(["label", "id", "sourcePort", "targetPort", "parent"]);
+/** The slot roles written structurally per domain (never as a key); a label is a key titled `label`. */
+const SLOT_ROLES_BY_DOMAIN = {
+    graph: new Set(),
+    node: new Set(["parent"]),
+    edge: new Set(["id", "sourcePort", "targetPort"]),
+};
+/** The names the importer gives the slot columns (design section 5.6), for the name-change notes. */
+const ROLE_NAMES = Object.freeze({
+    label: LABEL_COLUMN,
+    id: EDGE_ID_COLUMN,
+    sourcePort: SOURCE_PORT_COLUMN,
+    targetPort: TARGET_PORT_COLUMN,
+    parent: PARENT_COLUMN,
+});
+/** The attr.name of the weight key when the weight did not come from GraphML (the importer's weightFrom default). */
+const DEFAULT_WEIGHT_NAME = "weight";
+/** The GraphML attr.type values and the dtype each maps to, for restoring origin.type. */
+const TYPE_DTYPES = {
+    boolean: "bool",
+    int: "i32",
+    long: "f64",
+    float: "f32",
+    double: "f64",
+    string: "string",
+};
+const I32_MAX = 2147483647;
+/** The yfiles.type written for a yfiles json column whose origin records none. */
+const DEFAULT_YFILES_TYPES = {
+    node: "nodegraphics",
+    edge: "edgegraphics",
+    graph: "resources",
+};
+/**
+ * Resolve the format-specific options.
+ * @param options - the caller's options
+ * @returns the pretty flag and the edgedefault override
+ */
+function resolveFormatOptions(options) {
+    const pretty = options?.pretty ?? true;
+    if (typeof pretty !== "boolean") {
+        throw new GraphFormatError("E_UNSUPPORTED", "option pretty must be a boolean", {
+            option: "pretty",
+            found: typeof pretty,
+        });
+    }
+    const edgedefault = options?.edgedefault ?? null;
+    if (edgedefault !== null && edgedefault !== "directed" && edgedefault !== "undirected") {
+        throw new GraphFormatError("E_UNSUPPORTED", `option edgedefault: ${JSON.stringify(edgedefault)} is not "directed" or "undirected"`, { option: "edgedefault", found: edgedefault });
+    }
+    return { pretty, edgedefault };
+}
+/**
+ * The importer's `meta.extra.graphml`, when the snapshot has one of the expected shape.
+ * @param snapshot - the snapshot
+ * @returns the meta, or null
+ */
+function graphmlMetaOf(snapshot) {
+    const value = snapshot.meta.extra[META_KEY];
+    if (typeof value !== "object" || value === null) {
+        return null;
+    }
+    const record = value;
+    const graphId = typeof record.graphId === "string" ? record.graphId : null;
+    const edgedefault = record.edgedefault === "directed" || record.edgedefault === "undirected" ? record.edgedefault : null;
+    const namespaces = {};
+    if (typeof record.namespaces === "object" && record.namespaces !== null) {
+        for (const [prefix, uri] of Object.entries(record.namespaces)) {
+            if (typeof uri === "string") {
+                namespaces[prefix] = uri;
+            }
+        }
+    }
+    return { graphId, edgedefault, namespaces };
+}
+/**
+ * Build the plan: classify every column, assign key ids, decide the edgedefault and the
+ * containment order, and collect every loss note.
+ * @param snapshot - the snapshot
+ * @param options - the resolved common options
+ * @param format - the resolved format options
+ * @returns the plan
+ */
+function planExport(snapshot, options, format) {
+    // the generic json note is replaced by planTable()'s (yfiles trees are kept, other json is text)
+    const notes = checkCapabilities(snapshot, CAPABILITIES, options, {
+        roles: SLOT_ROLES,
+        roleNames: ROLE_NAMES,
+    }).filter((n) => n.code !== LOSS.JSON);
+    const note = (code, message, column = null, count = null) => {
+        notes.push(Object.freeze({ code, message, column, count }));
+    };
+    notes.push(...xmlIllegalTextNotes(snapshot));
+    const meta = graphmlMetaOf(snapshot);
+    const keyIds = new KeyIds();
+    const graphColumns = planTable(snapshot.graph, "graph", notes, note);
+    const nodeColumns = planTable(snapshot.nodes, "node", notes, note);
+    const edgeColumns = planTable(snapshot.edges, "edge", notes, note);
+    const keys = planKeys([...graphColumns, ...nodeColumns, ...edgeColumns], keyIds);
+    reservedNameNotes(nodeColumns, RESERVED_NODE_NAMES, note);
+    reservedNameNotes(edgeColumns, RESERVED_EDGE_NAMES, note);
+    const weight = planWeight(snapshot, edgeColumns, keyIds, keys, note);
+    // ids
+    const idTypeChanges = countIdTypeChanges(snapshot);
+    if (idTypeChanges > 0) {
+        note(GRAPHML_LOSS.ID_TEXT_TYPE, `${idTypeChanges} node id(s) change type when read back under ids: "canonical" (string ids that are integer text, non-integer numbers)`, null, idTypeChanges);
+    }
+    const edgeIdColumn = snapshot.edges.byRole("id");
+    if (edgeIdColumn !== null) {
+        planEdgeIds(snapshot, edgeIdColumn, options, note);
+    }
+    const unrepresentable = countUnrepresentableNodeIds(snapshot);
+    const needsOriginalIdKey = unrepresentable > 0 && options.sanitizeIds === "mangle";
+    const originalIdKey = needsOriginalIdKey ? keyIds.next(null) : null;
+    // direction: an undirected pair folds to one undirected edge, a mutual pair too (the mark is lost)
+    const folding = pairFolding(snapshot, { foldMutual: true });
+    if (folding.mutualCount > 0) {
+        note(GRAPHML_LOSS.MUTUAL_AS_UNDIRECTED, `${folding.mutualCount} mutual pair(s) are written as undirected edges; the mutual mark is lost`, null, folding.mutualCount);
+    }
+    const edgedefault = planEdgedefault(snapshot, folding, format, meta);
+    // containment
+    const hierarchy = planHierarchy(snapshot);
+    if (hierarchy.reordered) {
+        note(GRAPHML_LOSS.HIERARCHY_REORDERED, "nodes are written in containment order (children nested under their parent); node indices change after a round trip", hierarchy.parent?.meta.name ?? null);
+    }
+    if (hierarchy.unreachable > 0) {
+        note(GRAPHML_LOSS.PARENT_CYCLE, `${hierarchy.unreachable} node(s) whose parent chain never reaches a root are written at the top level`, hierarchy.parent?.meta.name ?? null, hierarchy.unreachable);
+    }
+    return {
+        options,
+        pretty: format.pretty,
+        notes,
+        keys,
+        graphColumns,
+        nodeColumns,
+        edgeColumns,
+        weight,
+        originalIdKey,
+        edgedefault,
+        folding,
+        edgeIdColumn,
+        sourcePortColumn: snapshot.edges.byRole("sourcePort"),
+        targetPortColumn: snapshot.edges.byRole("targetPort"),
+        hierarchy,
+        meta,
+        needsOriginalIdKey,
+    };
+}
+/**
+ * A plain column titled like one of the importer's XML-derived columns (`id`, `sourceport`,
+ * `targetport` on edges, `parent` on nodes) reads back renamed `<name>#<key id>` (design section
+ * 5.6); the note says so.
+ * @param plans - the column plans of one domain, key ids assigned
+ * @param reserved - the reserved names of that domain
+ * @param note - the note recorder
+ */
+function reservedNameNotes(plans, reserved, note) {
+    for (const plan of plans) {
+        const { column, attrName, keyId } = plan;
+        if (attrName === null || !reserved.has(attrName)) {
+            continue;
+        }
+        note(LOSS.COLUMN_NAME_CHANGED, `${plan.domain} column "${column.meta.name}" is titled like the importer's ${attrName} column and reads back as "${attrName}#${keyId}"`, column.meta.name, column.length - column.nullCount);
+    }
+}
+/** The key ids handed out so far: a preferred NMTOKEN when free, else the next free `d<n>`. */
+class KeyIds {
+    constructor() {
+        this.used = new Set();
+        this.counter = 0;
+    }
+    /**
+     * Take a key id.
+     * @param preferred - the id to keep when it is an NMTOKEN not handed out yet, or null
+     * @returns the id
+     */
+    next(preferred) {
+        if (preferred !== null && isNmtoken(preferred) && !this.used.has(preferred)) {
+            this.used.add(preferred);
+            return preferred;
+        }
+        for (;;) {
+            const candidate = `d${this.counter}`;
+            this.counter++;
+            if (!this.used.has(candidate)) {
+                this.used.add(candidate);
+                return candidate;
+            }
+        }
+    }
+}
+/**
+ * The `<key>` elements: columns sharing a GraphML origin.id across domains become one for="all"
+ * key when their name, type and default agree; every other column is its own key.
+ * @param all - the column plans of the three domains, in writing order
+ * @param keyIds - the key id allocator
+ * @returns the keys, in declaration order
+ */
+function planKeys(all, keyIds) {
+    const keys = [];
+    const byOrigin = new Map();
+    for (const plan of all) {
+        const { origin } = plan.column.meta;
+        if (origin !== null && origin.format === FORMAT && origin.id !== null) {
+            const group = byOrigin.get(origin.id) ?? [];
+            group.push(plan);
+            byOrigin.set(origin.id, group);
+        }
+    }
+    const planned = new Set();
+    for (const plan of all) {
+        if (planned.has(plan)) {
+            continue;
+        }
+        const { origin } = plan.column.meta;
+        const group = origin !== null && origin.format === FORMAT && origin.id !== null
+            ? (byOrigin.get(origin.id) ?? [plan])
+            : [plan];
+        const shared = group.length > 1 && group.every((other) => other === plan || sameKey(plan, other));
+        const members = shared ? group : [plan];
+        const id = keyIds.next(origin !== null && origin.format === FORMAT ? origin.id : null);
+        for (const member of members) {
+            member.keyId = id;
+            planned.add(member);
+        }
+        const domains = members.map((member) => member.domain);
+        // a yfiles key carries attr.name only when the column name is not the key id (yEd writes none)
+        const yfilesName = plan.column.meta.origin?.title ?? plan.column.meta.name;
+        let { attrName } = plan;
+        if (plan.yfiles) {
+            attrName = yfilesName === id ? null : yfilesName;
+        }
+        keys.push({
+            id,
+            domains: domains.length > 1 ? ["graph", "node", "edge"] : domains,
+            attrName,
+            attrType: plan.attrType,
+            yfilesType: plan.yfilesType,
+            column: plan.column,
+        });
+    }
+    return keys;
+}
+/**
+ * The weight key of a weighted snapshot (its attr.name and attr.type restored from
+ * meta.weightOrigin when the weight came from GraphML), and the note for an edge column the
+ * importer would read as THE weight: every edge key titled like the weight key (`weight` by
+ * default) is a weight key on import, so such a column reads back as the weight, not as a column.
+ * @param snapshot - the snapshot
+ * @param edgeColumns - the edge column plans
+ * @param keyIds - the key id allocator
+ * @param keys - receives the weight key
+ * @param note - the note recorder
+ * @returns the weight plan, or null for an unweighted snapshot
+ */
+function planWeight(snapshot, edgeColumns, keyIds, keys, note) {
+    const weights = explicitWeights(snapshot);
+    const origin = snapshot.meta.weightOrigin;
+    const fromGraphml = weights.weighted && origin !== null && origin.format === FORMAT;
+    const attrName = fromGraphml && origin.title !== null ? origin.title : DEFAULT_WEIGHT_NAME;
+    for (const plan of edgeColumns) {
+        if (plan.attrName === attrName) {
+            note(LOSS.WEIGHT_KEY_CLASH, `edge column "${plan.column.meta.name}" is written as a key titled "${attrName}", which the importer reads as THE weight (weightFrom); it reads back as the weight, not as a column`, plan.column.meta.name, plan.column.length - plan.column.nullCount);
+        }
+    }
+    if (!weights.weighted) {
+        return null;
+    }
+    let attrType = "double";
+    if (fromGraphml && origin.type !== null) {
+        const declared = origin.type.trim().toLowerCase();
+        if (declared === "float" || declared === "double" || declared === "long" || declared === "int") {
+            attrType = declared;
+        }
+    }
+    if ((attrType === "int" || attrType === "long") && !weightsIntegral(snapshot, weights)) {
+        // a declared integer weight only survives when every explicit weight is integral
+        attrType = "double";
+    }
+    const id = keyIds.next(fromGraphml ? origin.id : null);
+    keys.push({ id, domains: ["edge"], attrName, attrType, yfilesType: null, column: null });
+    return { keyId: id, attrType, weights };
+}
+/**
+ * The notes about the edge id column: a numeric column reads back as string; ids outside the
+ * NMTOKEN charset are refused or mangled per sanitizeIds.
+ * @param snapshot - the snapshot
+ * @param column - the edge id column
+ * @param options - the resolved options
+ * @param note - the note recorder
+ */
+function planEdgeIds(snapshot, column, options, note) {
+    if (column.dtype !== "string" && column.dtype !== "dict") {
+        note(GRAPHML_LOSS.EDGE_ID_TEXT, `edge id column "${column.meta.name}" is ${column.dtype}; GraphML edge ids read back as strings`, column.meta.name, snapshot.edgeCount - column.nullCount);
+    }
+    const bad = countBadEdgeIds(column);
+    if (bad === 0) {
+        return;
+    }
+    if (options.sanitizeIds === "mangle") {
+        note(LOSS.ID_MANGLED, `${bad} edge id(s) outside the nmtoken charset are rewritten`, column.meta.name, bad);
+    }
+    else {
+        note(LOSS.ID_CHARSET, `${bad} edge id(s) outside the nmtoken charset; export() will throw unless sanitizeIds is "mangle"`, column.meta.name, bad);
+    }
+}
+/**
+ * The top-level edgedefault: the override, else undirected for an undirected snapshot, else
+ * directed when no written edge is undirected, else the one the importer recorded, else the
+ * majority direction.
+ * @param snapshot - the snapshot
+ * @param folding - the pair folding
+ * @param format - the resolved format options
+ * @param meta - the importer's meta, or null
+ * @returns the edgedefault
+ */
+function planEdgedefault(snapshot, folding, format, meta) {
+    if (format.edgedefault !== null) {
+        return format.edgedefault;
+    }
+    if (!snapshot.directed) {
+        return "undirected";
+    }
+    let directedCount = 0;
+    let undirectedCount = 0;
+    for (let e = 0; e < snapshot.edgeCount; e++) {
+        if (folding.folded(e)) {
+            continue;
+        }
+        if (isDirectedEdge(folding, e)) {
+            directedCount++;
+        }
+        else {
+            undirectedCount++;
+        }
+    }
+    if (undirectedCount === 0) {
+        return "directed";
+    }
+    const recorded = meta === null ? null : meta.edgedefault;
+    if (recorded !== null) {
+        return recorded;
+    }
+    return undirectedCount > directedCount ? "undirected" : "directed";
+}
+/**
+ * Whether two column plans can share one for="all" key.
+ * @param a - one plan
+ * @param b - another
+ * @returns true when name, type and default agree
+ */
+function sameKey(a, b) {
+    return (a.attrName === b.attrName &&
+        a.attrType === b.attrType &&
+        a.yfilesType === b.yfilesType &&
+        a.domain !== b.domain &&
+        JSON.stringify(a.column.meta.default ?? null) === JSON.stringify(b.column.meta.default ?? null));
+}
+/**
+ * Classify the columns of one table: which are written as keys and what each loses. A label
+ * column is written into the label slot (a key titled `label`, which the importer reads back
+ * with the role) unless the table holds another column of that name, in which case it keeps
+ * its own title and the role is lost.
+ * @param table - the table
+ * @param domain - its domain
+ * @param notes - the notes so far (the generic name-change note of a label column that cannot take the slot is withdrawn)
+ * @param note - the note recorder
+ * @returns the plans of the written columns, in declaration order
+ */
+function planTable(table, domain, notes, note) {
+    const plans = [];
+    const columns = [...table];
+    const names = new Set(columns.map((column) => column.meta.name));
+    for (const column of columns) {
+        const { meta } = column;
+        const { role, name } = meta;
+        if (role === "parents") {
+            note(GRAPHML_LOSS.PARENTS_DROPPED, `${domain} column "${name}" (parents) cannot be written: nested graphs hold one parent per node`, name, column.length - column.nullCount);
+            continue;
+        }
+        if (role !== null &&
+            (STRUCTURAL_ROLES.has(role) || DROPPED_ROLES.has(role) || SLOT_ROLES_BY_DOMAIN[domain].has(role))) {
+            continue;
+        }
+        if (role !== null && role !== "label" && SLOT_ROLES.has(role)) {
+            // the slot belongs to another domain (an edge id on a node, a port on a graph)
+            withdrawNameChange(notes, name);
+            note(LOSS.ROLE, `${domain} column "${name}" (${role}) is written as a plain attribute; GraphML has no ${role} slot for a ${domain} and the role is lost`, name, column.length - column.nullCount);
+        }
+        const yfiles = meta.dtype === "json" && meta.origin?.namespace === "yfiles";
+        if (meta.dtype === "json" && !yfiles) {
+            note(LOSS.JSON, `${domain} column "${name}" holds nested values; written as JSON text, which reads back as string`, name, column.length - column.nullCount);
+        }
+        if (yfiles) {
+            const bad = countBadTrees(column);
+            if (bad > 0) {
+                note(GRAPHML_LOSS.YFILES_TREE, `${bad} value(s) of yfiles column "${name}" are not XML trees; export() will throw E_COLUMN_TYPE`, name, bad);
+            }
+        }
+        const { origin } = meta;
+        const fromGraphml = origin !== null && origin.format === FORMAT;
+        let attrName = null;
+        if (!yfiles) {
+            attrName = fromGraphml && origin.title !== null ? origin.title : name;
+            if (role === "label" && domain !== "graph" && attrName !== LABEL_COLUMN) {
+                attrName = labelSlot(column, domain, names, notes, note);
+            }
+            else if (role === null && domain !== "graph" && attrName === LABEL_COLUMN) {
+                note(LOSS.ROLE_ASSUMED, `${domain} column "${name}" has no role but is titled "${LABEL_COLUMN}", which the importer reads back with the label role`, name, column.length - column.nullCount);
+            }
+        }
+        plans.push({
+            column,
+            domain,
+            keyId: "",
+            attrType: yfiles ? null : attrTypeFor(column),
+            attrName,
+            yfilesType: yfiles ? (origin?.type ?? DEFAULT_YFILES_TYPES[domain]) : null,
+            yfiles,
+        });
+    }
+    return plans;
+}
+/**
+ * The title a label column not named `label` is written under: the label slot when the table has
+ * no other column of that name (checkCapabilities() has noted the name change), else its own
+ * name with the role lost (the name-change note is withdrawn and a role note recorded).
+ * @param column - the label column
+ * @param domain - its domain
+ * @param names - the column names of the table
+ * @param notes - the notes so far
+ * @param note - the note recorder
+ * @returns the attr.name
+ */
+function labelSlot(column, domain, names, notes, note) {
+    const { name } = column.meta;
+    if (!names.has(LABEL_COLUMN)) {
+        return LABEL_COLUMN;
+    }
+    withdrawNameChange(notes, name);
+    note(LOSS.ROLE, `${domain} column "${name}" (label) is written as a plain attribute: the label slot (a key titled "${LABEL_COLUMN}") is taken by column "${LABEL_COLUMN}" and the role is lost`, name, column.length - column.nullCount);
+    return name;
+}
+/**
+ * Withdraw the name-change note checkCapabilities() recorded for a role column that does not
+ * take the slot after all.
+ * @param notes - the notes so far
+ * @param name - the column name
+ */
+function withdrawNameChange(notes, name) {
+    const at = notes.findIndex((n) => n.code === LOSS.COLUMN_NAME_CHANGED && n.column === name);
+    if (at >= 0) {
+        notes.splice(at, 1);
+    }
+}
+/**
+ * The attr.type a column is declared with: the GraphML origin.type when it still describes the
+ * column, else the type of the dtype (u32 / u8 as int or long, dict as string, list / json /
+ * multi-component as string holding JSON text).
+ * @param column - the column
+ * @returns the attr.type text
+ */
+function attrTypeFor(column) {
+    const { meta } = column;
+    const { origin } = meta;
+    const declared = origin !== null && origin.format === FORMAT && origin.type !== null ? origin.type : null;
+    if (meta.components > 1) {
+        return "string";
+    }
+    switch (meta.dtype) {
+        case "bool":
+            return "boolean";
+        case "i32":
+            return "int";
+        case "f32":
+            return "float";
+        case "f64": {
+            if (declared !== null && declared.trim().toLowerCase() === "long" && columnIntegral(column)) {
+                return "long";
+            }
+            return "double";
+        }
+        case "u8":
+            return "int";
+        case "u32":
+            return columnMax(column) <= I32_MAX ? "int" : "long";
+        case "string":
+            if (declared !== null && TYPE_DTYPES[declared.trim().toLowerCase()] === undefined) {
+                // an unknown declared type kept as text (W_UNKNOWN_ATTR_TYPE on import) is restored as declared
+                return declared;
+            }
+            return "string";
+        case "dict":
+        case "list":
+        case "json":
+            return "string";
+        default: {
+            const { dtype } = meta;
+            throw new GraphFormatError("E_UNSUPPORTED", `unknown dtype ${String(dtype)}`, { dtype });
+        }
+    }
+}
+/**
+ * Whether every set value of a numeric column is an integer.
+ * @param column - an f64 column
+ * @returns true when all set values are integral
+ */
+function columnIntegral(column) {
+    if (column.dtype !== "f64") {
+        return false;
+    }
+    const { data } = column;
+    for (let r = 0; r < column.length; r++) {
+        if (column.isSet(r) && !Number.isInteger(data[r])) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * The largest set value of a u32 column.
+ * @param column - a u32 column
+ * @returns the maximum, 0 for an empty column
+ */
+function columnMax(column) {
+    if (column.dtype !== "u32") {
+        return 0;
+    }
+    let max = 0;
+    const { data } = column;
+    for (let r = 0; r < column.length; r++) {
+        if (column.isSet(r) && data[r] > max) {
+            max = data[r];
+        }
+    }
+    return max;
+}
+/**
+ * Whether every explicit weight is integral (so a declared int / long weight key survives).
+ * @param snapshot - the snapshot
+ * @param weights - the explicit weights
+ * @returns true when all explicit weights are integers
+ */
+function weightsIntegral(snapshot, weights) {
+    for (let e = 0; e < snapshot.edgeCount; e++) {
+        if (weights.isExplicit(e) && !Number.isInteger(weights.value(e))) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * How many values of a yfiles column are not serialisable trees.
+ * @param column - a json column
+ * @returns the count
+ */
+function countBadTrees(column) {
+    if (column.dtype !== "json") {
+        return 0;
+    }
+    let bad = 0;
+    for (let r = 0; r < column.length; r++) {
+        if (column.isSet(r) && treeProblem(column.values[r]) !== null) {
+            bad++;
+        }
+    }
+    return bad;
+}
+/**
+ * Node ids that read back as another type under the canonical rule: string ids that are
+ * canonical integer text, and numbers that are not safe integers.
+ * @param snapshot - the snapshot
+ * @returns the count
+ */
+function countIdTypeChanges(snapshot) {
+    const { ids } = snapshot;
+    if (ids.kind === "identity" || ids.kind === "dense") {
+        return 0;
+    }
+    let count = 0;
+    for (let i = 0; i < ids.size; i++) {
+        const id = ids.idOf(i);
+        if (typeof id === "string" ? isNmtoken(id) && isCanonicalIntegerText(id) : !Number.isSafeInteger(id)) {
+            count++;
+        }
+    }
+    return count;
+}
+/**
+ * Node ids the nmtoken charset cannot hold.
+ * @param snapshot - the snapshot
+ * @returns the count
+ */
+function countUnrepresentableNodeIds(snapshot) {
+    const { ids } = snapshot;
+    if (ids.kind === "identity" || ids.kind === "dense") {
+        return 0;
+    }
+    let count = 0;
+    for (let i = 0; i < ids.size; i++) {
+        if (!isNmtoken(String(ids.idOf(i)))) {
+            count++;
+        }
+    }
+    return count;
+}
+/**
+ * Edge ids that are not NMTOKENs.
+ * @param column - the edge id column
+ * @returns the count
+ */
+function countBadEdgeIds(column) {
+    let bad = 0;
+    for (let e = 0; e < column.length; e++) {
+        if (column.isSet(e) && !isNmtoken(edgeIdText(column, e))) {
+            bad++;
+        }
+    }
+    return bad;
+}
+/**
+ * The text of an edge id cell.
+ * @param column - the edge id column
+ * @param e - the edge
+ * @returns the id as text
+ */
+function edgeIdText(column, e) {
+    const value = column.value(e);
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number") {
+        return Number.isInteger(value) ? formatInteger(value) : formatF64(value);
+    }
+    return String(value);
+}
+/**
+ * Whether a logical edge is written as directed: never in an undirected snapshot; never for a
+ * half of an expanded pair (an undirected or a mutual source edge, whose halves the resolver
+ * flags directed); otherwise per the directed role column, with directed as the default.
+ * @param folding - the pair folding
+ * @param e - the edge
+ * @returns false for a paired edge or an edge flagged undirected
+ */
+function isDirectedEdge(folding, e) {
+    return folding.mateOf(e) === INVALID_INDEX && folding.sourceDirected(e);
+}
+/**
+ * The containment order: the children CSR over the parent column (src/children.ts), roots in
+ * index order, unreachable nodes (cycles) forced to the top level.
+ * @param snapshot - the snapshot
+ * @returns the hierarchy
+ */
+function planHierarchy(snapshot) {
+    const parent = snapshot.nodes.byRole("parent");
+    const csr = childrenCsr(snapshot, { column: parent !== null && parent.dtype === "u32" ? parent : null });
+    const walk = csr.depthFirst();
+    // the top-level nodes in written order: the roots, then the cycle members forced out
+    const roots = walk.order.filter((u) => walk.depth[u] === 0);
+    return {
+        parent: csr.column,
+        roots,
+        childStart: csr.rowPtr,
+        childList: csr.children,
+        reordered: walk.reordered,
+        unreachable: csr.unreachable,
+    };
+}
+// ============================================================ writing
+/**
+ * The text of one set cell for a `<data>` element or a `<default>`.
+ * @param column - the column
+ * @param row - the row
+ * @param attrType - the declared attr.type
+ * @returns the text
+ */
+function cellText(column, row, attrType) {
+    if (column.meta.components > 1) {
+        const value = column.value(row);
+        return JSON.stringify(Array.from(value));
+    }
+    switch (column.dtype) {
+        case "bool":
+            return column.value(row) === true ? "true" : "false";
+        case "i32":
+        case "u32":
+        case "u8":
+            return String(column.data[row]);
+        case "f32":
+            return formatF32(column.data[row]);
+        case "f64": {
+            const value = column.data[row];
+            return (attrType === "long" || attrType === "int") && Number.isInteger(value)
+                ? formatInteger(value)
+                : formatF64(value);
+        }
+        case "string":
+            return column.valueAt(row);
+        case "dict":
+            return column.dictionary[column.codes[row]];
+        case "list":
+            return JSON.stringify(Array.from(column.sliceOf(row)));
+        case "json":
+            return JSON.stringify(column.values[row]) ?? "";
+        default: {
+            const dtype = column;
+            throw new GraphFormatError("E_UNSUPPORTED", `unknown dtype ${String(dtype)}`, {});
+        }
+    }
+}
+/**
+ * The text of a declared default.
+ * @param column - the column
+ * @param attrType - the declared attr.type
+ * @returns the text, or null when the column has no default
+ */
+function defaultText(column, attrType) {
+    const value = column.meta.default;
+    if (value === undefined) {
+        return null;
+    }
+    switch (typeof value) {
+        case "boolean":
+            return value ? "true" : "false";
+        case "number":
+            if (column.dtype === "f32") {
+                return formatF32(value);
+            }
+            return (attrType === "long" || attrType === "int") && Number.isInteger(value)
+                ? formatInteger(value)
+                : formatF64(value);
+        case "string":
+            return value;
+        default:
+            return JSON.stringify(value) ?? "";
+    }
+}
+/**
+ * Write one `<data>` element.
+ * @param plan - the column plan
+ * @param row - the row
+ * @param indent - the indentation
+ * @param out - receives the parts
+ */
+function writeData(plan, row, indent, out) {
+    const { column } = plan;
+    if (!column.isSet(row)) {
+        return;
+    }
+    if (plan.yfiles && column.dtype === "json") {
+        writeTreeData(plan.keyId, column.values[row], indent, out);
+        return;
+    }
+    out.push(`\n${indent}<data key="${plan.keyId}">${escapeXmlText(cellText(column, row, plan.attrType))}</data>`);
+}
+/**
+ * Write a `<data>` holding a yfiles tree.
+ * @param keyId - the key id
+ * @param value - the tree
+ * @param indent - the indentation
+ * @param out - receives the parts
+ */
+function writeTreeData(keyId, value, indent, out) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        const parts = [];
+        writeXmlTree(value, indent, parts);
+        out.push(`\n${indent}<data key="${keyId}">${parts.join("")}</data>`);
+        return;
+    }
+    out.push(`\n${indent}<data key="${keyId}">`);
+    writeXmlTree(value, `${indent}  `, out);
+    out.push(`\n${indent}</data>`);
+}
+/**
+ * The `<key>` element of a plan.
+ * @param key - the key plan
+ * @param indent - the indentation
+ * @returns the element text
+ */
+function keyElement(key, indent) {
+    const domain = key.domains.length === 3 ? "all" : key.domains[0];
+    let text = `${indent}<key id="${escapeXmlAttribute(key.id)}" for="${domain}"`;
+    if (key.attrName !== null) {
+        text += ` attr.name="${escapeXmlAttribute(key.attrName)}"`;
+    }
+    if (key.attrType !== null) {
+        text += ` attr.type="${escapeXmlAttribute(key.attrType)}"`;
+    }
+    if (key.yfilesType !== null) {
+        text += ` yfiles.type="${escapeXmlAttribute(key.yfilesType)}"`;
+    }
+    const { column } = key;
+    const desc = column?.meta.extra.desc;
+    const hasDefault = column !== null && column.meta.default !== undefined;
+    if (column === null || (typeof desc !== "string" && !hasDefault)) {
+        return `${text}/>\n`;
+    }
+    const parts = [`${text}>`];
+    const inner = `${indent}  `;
+    if (typeof desc === "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 = [];
+                writeXmlTree(value, inner, tree);
+                parts.push(`\n${inner}<default>${tree.join("")}</default>`);
+            }
+        }
+        else {
+            parts.push(`\n${inner}<default>${escapeXmlText(defaultText(column, key.attrType) ?? "")}</default>`);
+        }
+    }
+    parts.push(`\n${indent}</key>\n`);
+    return parts.join("");
+}
+/**
+ * Sanitised edge ids: NMTOKENs as they are; the rest refused or mangled per sanitizeIds.
+ * @param column - the edge id column, or null
+ * @param mode - the resolved sanitizeIds option
+ * @param edgeCount - the edge count
+ * @returns the id text per edge (null for edges without one)
+ */
+function sanitizeEdgeIds(column, mode, edgeCount) {
+    const out = new Array(edgeCount).fill(null);
+    if (column === null) {
+        return out;
+    }
+    const used = new Set();
+    const bad = [];
+    for (let e = 0; e < edgeCount; e++) {
+        if (!column.isSet(e)) {
+            continue;
+        }
+        const text = edgeIdText(column, e);
+        if (isNmtoken(text)) {
+            out[e] = text;
+            used.add(text);
+        }
+        else {
+            bad.push(e);
+        }
+    }
+    if (bad.length > 0 && mode === "error") {
+        throw new GraphFormatError("E_INVALID_ID", `${bad.length} edge id(s) cannot be written as nmtoken (first: ${JSON.stringify(edgeIdText(column, bad[0]))} at edge ${bad[0]}); pass sanitizeIds: "mangle" to rewrite them`, { reason: "charset", charset: "nmtoken", count: bad.length, edge: bad[0] });
+    }
+    for (const e of bad) {
+        const base = mangleNmtoken(edgeIdText(column, e));
+        let candidate = base;
+        for (let k = 2; used.has(candidate); k++) {
+            candidate = `${base}_${k}`;
+        }
+        used.add(candidate);
+        out[e] = candidate;
+    }
+    return out;
+}
+/**
+ * The document as text parts.
+ * @param snapshot - the snapshot
+ * @param plan - the plan
+ * @yields one element (or a group of small ones) at a time
+ * @returns nothing
+ */
+function* writeGraphml(snapshot, plan) {
+    const ids = sanitizeIds(snapshot, "nmtoken", plan.options.sanitizeIds);
+    const edgeIds = sanitizeEdgeIds(plan.edgeIdColumn, plan.options.sanitizeIds, snapshot.edgeCount);
+    const i1 = plan.pretty ? "  " : "";
+    const i2 = plan.pretty ? "    " : "";
+    const i3 = plan.pretty ? "      " : "";
+    const step = plan.pretty ? "  " : "";
+    yield '<?xml version="1.0" encoding="UTF-8"?>\n';
+    let root = `<graphml xmlns="${GRAPHML_NAMESPACE}"`;
+    const namespaces = { ...(plan.meta?.namespaces ?? {}) };
+    if ((plan.nodeColumns.some((c) => c.yfiles) ||
+        plan.edgeColumns.some((c) => c.yfiles) ||
+        plan.graphColumns.some((c) => c.yfiles)) &&
+        !Object.values(namespaces).includes(YFILES_NAMESPACE)) {
+        namespaces.y = YFILES_NAMESPACE;
+    }
+    if (!Object.values(namespaces).includes(XSI_NAMESPACE)) {
+        namespaces.xsi = XSI_NAMESPACE;
+    }
+    for (const [prefix, uri] of Object.entries(namespaces)) {
+        root += ` xmlns:${prefix}="${escapeXmlAttribute(uri)}"`;
+    }
+    const xsiPrefix = Object.entries(namespaces).find(([, uri]) => uri === XSI_NAMESPACE)?.[0] ?? "xsi";
+    root += ` ${xsiPrefix}:schemaLocation="${SCHEMA_LOCATION}">\n`;
+    yield root;
+    for (const key of plan.keys) {
+        yield keyElement(key, i1);
+    }
+    if (plan.originalIdKey !== null) {
+        yield `${i1}<key id="${plan.originalIdKey}" for="node" attr.name="${ORIGINAL_ID_ATTRIBUTE}" attr.type="string"/>\n`;
+    }
+    const graphId = plan.meta?.graphId ?? "G";
+    yield `${i1}<graph id="${escapeXmlAttribute(graphId)}" edgedefault="${plan.edgedefault}">`;
+    const { description } = snapshot.meta;
+    if (description !== null) {
+        yield `\n${i2}<desc>${escapeXmlText(description)}</desc>`;
+    }
+    const graphParts = [];
+    for (const column of plan.graphColumns) {
+        writeData(column, 0, i2, graphParts);
+    }
+    if (graphParts.length > 0) {
+        yield graphParts.join("");
+    }
+    // nodes in containment order, children nested under their parent
+    const { hierarchy } = plan;
+    const nested = hierarchy.childList.length > 0;
+    const stackNode = [];
+    const stackCursor = [];
+    const written = nested ? new Uint8Array(snapshot.nodeCount) : null;
+    for (const rootNode of hierarchy.roots) {
+        yield* writeNodeSubtree(rootNode, plan, ids, i2, step, stackNode, stackCursor, written);
+    }
+    // edges: primaries only, in index order
+    const list = snapshot.edgeList();
+    const { folding } = plan;
+    for (let e = 0; e < snapshot.edgeCount; e++) {
+        if (folding.folded(e)) {
+            continue;
+        }
+        const parts = [`\n${i2}<edge`];
+        const id = edgeIds[e];
+        if (id !== null) {
+            parts.push(` id="${escapeXmlAttribute(id)}"`);
+        }
+        parts.push(` source="${escapeXmlAttribute(String(ids.idAt(list.src[e])))}" target="${escapeXmlAttribute(String(ids.idAt(list.dst[e])))}"`);
+        const directed = snapshot.directed && isDirectedEdge(folding, e);
+        if (directed !== (plan.edgedefault === "directed")) {
+            parts.push(` directed="${directed ? "true" : "false"}"`);
+        }
+        const sourcePort = portText(plan.sourcePortColumn, e);
+        if (sourcePort !== null) {
+            parts.push(` sourceport="${escapeXmlAttribute(sourcePort)}"`);
+        }
+        const targetPort = portText(plan.targetPortColumn, e);
+        if (targetPort !== null) {
+            parts.push(` targetport="${escapeXmlAttribute(targetPort)}"`);
+        }
+        const open = parts.length;
+        if (plan.weight !== null) {
+            const { keyId, attrType } = plan.weight;
+            const weight = plan.weight.weights.text(e, attrType === "int" || attrType === "long");
+            if (weight !== null) {
+                parts.push(`\n${i3}<data key="${keyId}">${escapeXmlText(weight)}</data>`);
+            }
+        }
+        for (const column of plan.edgeColumns) {
+            writeData(column, e, i3, parts);
+        }
+        if (parts.length === open) {
+            parts.push("/>");
+        }
+        else {
+            parts.splice(open, 0, ">");
+            parts.push(`\n${i2}</edge>`);
+        }
+        yield parts.join("");
+    }
+    yield `\n${i1}</graph>\n</graphml>\n`;
+}
+/**
+ * The text of a port reference cell.
+ * @param column - the sourcePort / targetPort column, or null
+ * @param e - the edge
+ * @returns the port name, or null when unset
+ */
+function portText(column, e) {
+    if (column === null || !column.isSet(e)) {
+        return null;
+    }
+    const value = column.value(e);
+    return typeof value === "string" ? value : String(value);
+}
+/**
+ * Write a top-level node and, nested, every node contained in it (iteratively, so a deep chain
+ * cannot overflow the call stack).
+ * @param root - the top-level node
+ * @param plan - the plan
+ * @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)
+ * @yields the node elements
+ * @returns nothing
+ */
+function* writeNodeSubtree(root, plan, ids, indent, step, stackNode, stackCursor, written) {
+    const { hierarchy } = plan;
+    const hasChildren = (u) => hierarchy.childStart[u + 1] > hierarchy.childStart[u];
+    const openNode = (u, depth) => {
+        const pad = indent + step.repeat(depth * 2);
+        const parts = [`\n${pad}<node id="${escapeXmlAttribute(String(ids.idAt(u)))}"`];
+        const open = parts.length;
+        if (plan.originalIdKey !== null && ids.isChanged(u)) {
+            parts.push(`\n${pad}${step}<data key="${plan.originalIdKey}">${escapeXmlText(String(ids.originalAt(u)))}</data>`);
+        }
+        for (const column of plan.nodeColumns) {
+            writeData(column, u, pad + step, parts);
+        }
+        if (hasChildren(u)) {
+            parts.splice(open, 0, ">");
+            parts.push(`\n${pad}${step}<graph id="${escapeXmlAttribute(`${String(ids.idAt(u))}:`)}" edgedefault="${plan.edgedefault}">`);
+            return parts.join("");
+        }
+        if (parts.length === open) {
+            parts.push("/>");
+        }
+        else {
+            parts.splice(open, 0, ">");
+            parts.push(`\n${pad}</node>`);
+        }
+        return parts.join("");
+    };
+    const closeNode = (depth) => {
+        const pad = indent + step.repeat(depth * 2);
+        return `\n${pad}${step}</graph>\n${pad}</node>`;
+    };
+    if (written !== null) {
+        written[root] = 1;
+    }
+    yield openNode(root, 0);
+    if (!hasChildren(root)) {
+        return;
+    }
+    stackNode.push(root);
+    stackCursor.push(hierarchy.childStart[root]);
+    while (stackNode.length > 0) {
+        const top = stackNode.length - 1;
+        const u = stackNode[top];
+        const cursor = stackCursor[top];
+        if (cursor >= hierarchy.childStart[u + 1]) {
+            stackNode.pop();
+            stackCursor.pop();
+            yield closeNode(top);
+            continue;
+        }
+        stackCursor[top] = cursor + 1;
+        const v = hierarchy.childList[cursor];
+        if (written !== null && written[v] === 1) {
+            continue;
+        }
+        if (written !== null) {
+            written[v] = 1;
+        }
+        yield openNode(v, top + 1);
+        if (hasChildren(v)) {
+            stackNode.push(v);
+            stackCursor.push(hierarchy.childStart[v]);
+        }
+    }
+}
+/**
+ * The GraphML exporter (design section 8.5).
+ */
+export const graphmlExporter = Object.freeze({
+    format: FORMAT,
+    capabilities: CAPABILITIES,
+    /**
+     * Pre-flight: every loss the export would incur.
+     * @param snapshot - the snapshot
+     * @param options - format-specific and common options
+     * @returns the notes
+     */
+    check(snapshot, options) {
+        const plan = planExport(snapshot, resolveExportOptions(options), resolveFormatOptions(options));
+        return Object.freeze(plan.notes);
+    },
+    /**
+     * Write the document as UTF-8 chunks.
+     * @param snapshot - the snapshot
+     * @param options - format-specific and common options
+     * @returns the chunks
+     */
+    export(snapshot, options) {
+        const plan = planExport(snapshot, resolveExportOptions(options), resolveFormatOptions(options));
+        return encodeChunks(writeGraphml(snapshot, plan));
+    },
+    /**
+     * Write the document as one string.
+     * @param snapshot - the snapshot
+     * @param options - format-specific and common options
+     * @returns the document
+     */
+    exportToString(snapshot, options) {
+        const plan = planExport(snapshot, resolveExportOptions(options), resolveFormatOptions(options));
+        return joinText(writeGraphml(snapshot, plan));
+    },
+});
+//# sourceMappingURL=exporter.js.map