@graphty/graph-io 0.0.0 → 0.2.0

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

@@ -0,0 +1,1093 @@
+/**
+ * The GML exporter (design section 8.5, research note 07 sections 2.2 and 9): writes a snapshot in
+ * the NetworkX dialect of GML. Node ids must be integers (`idCharset: "integer"`; `sanitizeIds:
+ * "mangle"` renumbers the others and keeps the original in a `graphty_originalId` key the importer
+ * restores); columns are written per dtype (`int` for the integer dtypes, `real` with a decimal
+ * point guaranteed for f32 / f64 so the dtype survives a re-import, quoted strings with `&#NN;`
+ * references, repeated keys for lists with the `_networkx_list_start` marker for one-element
+ * lists and `"[]"` for empty ones, nested records for json objects); the position role becomes
+ * `graphics [ x y z ]` merged with the node's `graphics` json record; graph columns are written
+ * inside `graph [ ]` (or at the top level when the importer found them there); `Creator` and
+ * `Version` come from the metadata.
+ *
+ * check() reports, before anything is written, the capability gaps of the common check plus the
+ * GML-specific ones: json columns holding numbers (JSON cannot keep the int / real distinction:
+ * `W_GML_RECORD_NUMBER_TYPE`), booleans (written 1 / 0) or nulls (omitted), arrays nested in
+ * arrays (no GML spelling; export() throws), column names and record keys that are not GML keys
+ * or collide with the structural keys (`E_GML_INVALID_KEY` / `E_GML_RESERVED_KEY`, or
+ * `W_GML_KEY_MANGLED` under `sanitizeKeys: "mangle"`), and graphics / position overlaps.
+ */
+import { GraphFormatError, } from "@graphty/graph-format";
+import { DICT_SAMPLE_ROWS, DictHeuristic } from "../../common/attributes.js";
+import { pairFolding } from "../../common/direction.js";
+import { quoteGmlString } from "../../common/escape.js";
+import { capabilities, checkCapabilities, countMixedEdges, LOSS, sanitizeIds, } from "../../common/export.js";
+import { formatGmlReal, formatInteger } from "../../common/format.js";
+import { resolveExportOptions } from "../../common/options.js";
+import { explicitWeights } from "../../common/weights.js";
+import { encodeChunks, joinText } from "../../common/writer.js";
+import { EMPTY_LIST_TEXT, isGmlKey, LIST_START_MARKER, mangleGmlKey, ORIGINAL_ID_KEY } from "./syntax.js";
+/** Loss code: a json column holds numbers; JSON cannot keep GML's int / real distinction (design section 8.5). */
+export const RECORD_NUMBER_TYPE_CODE = "W_GML_RECORD_NUMBER_TYPE";
+/** Loss code: a json column holds booleans, written as 1 / 0. */
+export const RECORD_BOOLEAN_CODE = "W_GML_RECORD_BOOLEAN";
+/** Loss code: a json column holds nulls, which GML cannot write; the key (or the row) is omitted. */
+export const RECORD_NULL_CODE = "W_GML_RECORD_NULL";
+/** Loss code: a json column holds an array inside an array, which GML cannot write; export() throws. */
+export const NESTED_ARRAY_CODE = "E_GML_NESTED_ARRAY";
+/** Loss code: a json column holds arrays as row values; written as repeated keys, they re-import as a list column. */
+export const JSON_ARRAY_CODE = "W_GML_JSON_ARRAY";
+/** Loss code: a column name or record key is not a GML key; export() throws unless sanitizeKeys is "mangle". */
+export const INVALID_KEY_CODE = "E_GML_INVALID_KEY";
+/** Loss code: a column name collides with a structural GML key; export() throws unless sanitizeKeys is "mangle". */
+export const RESERVED_KEY_CODE = "E_GML_RESERVED_KEY";
+/** Loss code: keys rewritten under sanitizeKeys "mangle". */
+export const KEY_MANGLED_CODE = "W_GML_KEY_MANGLED";
+/** Loss code: a position column with more than three components; x, y and z are written. */
+export const POSITION_COMPONENTS_CODE = "W_GML_POSITION_COMPONENTS";
+/** Loss code: a node's graphics record has x / y / z keys the position column replaces. */
+export const GRAPHICS_OVERRIDDEN_CODE = "W_GML_GRAPHICS_OVERRIDDEN";
+/** Loss code: a node's graphics value is not a record and cannot hold the position; export() throws. */
+export const GRAPHICS_CONFLICT_CODE = "E_GML_GRAPHICS_CONFLICT";
+/** The default weight key (design section 8.4: GML weights are read from `value` by default). */
+export const DEFAULT_WEIGHT_KEY = "value";
+/** The roles GML has a key for (`label`, the edge `id` and `key`); every other role is reported. */
+const KEPT_ROLES = new Set(["label", "id", "key"]);
+/** The key the importer maps each kept role back from (the column name after re-import). */
+const ROLE_NAMES = Object.freeze({
+    label: "label",
+    id: "id",
+    key: "key",
+});
+const GML_CAPABILITIES = capabilities({
+    mixedDirection: false,
+    multiEdges: true,
+    selfLoops: true,
+    edgeIds: "optional",
+    idCharset: "integer",
+    dtypes: ["i32", "f64", "string", "dict", "json"],
+    components: false,
+    lists: true,
+    json: true,
+    defaults: false,
+    options: false,
+    hierarchy: false,
+    temporal: "none",
+    graphAttributes: true,
+    positions: true,
+    viz: false,
+});
+/** Roles whose columns are never written as attributes (structural, or dropped per the capabilities). */
+const SKIPPED_ROLES = new Set([
+    "directed",
+    "pair",
+    "mutual",
+    "weight",
+    "timeText",
+    "originalId",
+    "position",
+    "color",
+    "size",
+    "shape",
+    "thickness",
+    "parent",
+    "parents",
+    "start",
+    "end",
+    "timestamp",
+    "timestamps",
+    "spells",
+    "open",
+]);
+const NODE_RESERVED = new Set(["id"]);
+const EDGE_RESERVED = new Set(["source", "target"]);
+const GRAPH_RESERVED = new Set(["node", "edge", "directed", "multigraph"]);
+const TOP_RESERVED = new Set(["graph"]);
+const NUMBER_TEXT = /^[+-]?(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)(?:[eE][+-]?[0-9]+)?$/;
+/**
+ * Resolve the options of one export call.
+ * @param snapshot - the snapshot
+ * @param options - the caller's options
+ * @returns the plan
+ */
+function planOf(snapshot, options) {
+    const common = resolveExportOptions(options);
+    const mode = options?.sanitizeKeys ?? "error";
+    if (mode !== "error" && mode !== "mangle") {
+        throw new GraphFormatError("E_UNSUPPORTED", `option sanitizeKeys: ${JSON.stringify(mode)} is not "error" or "mangle"`, {
+            option: "sanitizeKeys",
+            found: mode,
+        });
+    }
+    let weightKey = options?.weightKey;
+    if (weightKey === undefined) {
+        const origin = snapshot.meta.weightOrigin;
+        weightKey = origin !== null && origin.format === "gml" && origin.id !== null ? origin.id : DEFAULT_WEIGHT_KEY;
+    }
+    else if (typeof weightKey !== "string" || !isGmlKey(weightKey)) {
+        throw new GraphFormatError("E_UNSUPPORTED", `option weightKey: ${JSON.stringify(weightKey)} is not a GML key`, {
+            option: "weightKey",
+            found: weightKey,
+        });
+    }
+    return { common, weightKey, mangle: mode === "mangle" };
+}
+/**
+ * Whether a column is written as an attribute (its role is neither structural nor dropped).
+ * @param column - the column
+ * @returns true when written
+ */
+function isWritten(column) {
+    const { role } = column.meta;
+    return role === null || !SKIPPED_ROLES.has(role);
+}
+/**
+ * The key a column is written under.
+ * @param meta - the column metadata
+ * @returns origin.id when the column came from GML (the key it was read from), else the name
+ */
+function preferredKey(meta) {
+    const { origin } = meta;
+    return origin !== null && origin.format === "gml" && origin.id !== null ? origin.id : meta.name;
+}
+/**
+ * Whether a snapshot has explicit weights to write.
+ * @param snapshot - the snapshot
+ * @returns true when weighted
+ */
+function hasWeights(snapshot) {
+    return snapshot.flags.weighted;
+}
+/**
+ * Whether the graph column is a top-level key (the importer's `extra.gmlTopLevel`).
+ * @param column - the column
+ * @returns true for a top-level key
+ */
+function isTopLevel(column) {
+    return column.meta.extra.gmlTopLevel === true;
+}
+/**
+ * The text of a `Version` value: bare when it is a number text, quoted otherwise.
+ * @param text - the version text
+ * @returns the GML value
+ */
+function versionText(text) {
+    return NUMBER_TEXT.test(text) ? text : quoteGmlString(text);
+}
+/**
+ * Select the written columns of a table and assign their keys, recording invalid and reserved
+ * keys as notes (or rewriting them under mangle).
+ * @param table - the columns
+ * @param reserved - the structural keys of the table
+ * @param label - the table name for messages
+ * @param plan - the export plan
+ * @param notes - where to record
+ * @param filter - an extra selection predicate
+ * @returns the written columns with their keys
+ */
+function selectColumns(table, reserved, label, plan, notes, filter = () => true) {
+    const used = new Set(reserved);
+    const out = [];
+    for (const column of table) {
+        if (!isWritten(column) || !filter(column)) {
+            continue;
+        }
+        const preferred = preferredKey(column.meta);
+        let key = preferred;
+        const valid = isGmlKey(preferred);
+        const taken = used.has(preferred);
+        if (!valid || taken) {
+            const code = valid ? RESERVED_KEY_CODE : INVALID_KEY_CODE;
+            let why = "is not a GML key";
+            if (valid) {
+                why = reserved.has(preferred) ? "collides with a structural GML key" : "repeats another column's key";
+            }
+            if (!plan.mangle) {
+                if (notes === null) {
+                    throw new GraphFormatError("E_UNSUPPORTED", `${label} column "${column.meta.name}" ${why}; pass sanitizeKeys: "mangle" to rewrite it`, {
+                        reason: "gml key",
+                        column: column.meta.name,
+                        key: preferred,
+                    });
+                }
+                notes.push(note(code, `${label} column "${column.meta.name}" ${why}; export() will throw unless sanitizeKeys is "mangle"`, column.meta.name));
+                continue;
+            }
+            key = uniqueKey(valid ? preferred : mangleGmlKey(preferred), used);
+            notes?.push(note(KEY_MANGLED_CODE, `${label} column "${column.meta.name}" is written as "${key}"`, column.meta.name));
+        }
+        used.add(key);
+        out.push({ column, key });
+    }
+    return out;
+}
+/**
+ * A key not yet used: the base, else base_2, base_3...
+ * @param base - a valid key
+ * @param used - the keys taken
+ * @returns a free key
+ */
+function uniqueKey(base, used) {
+    let candidate = base;
+    for (let k = 2; used.has(candidate); k++) {
+        candidate = `${base}_${k}`;
+    }
+    return candidate;
+}
+/**
+ * Build a frozen note.
+ * @param code - the code
+ * @param message - the message
+ * @param column - the column, or null
+ * @param count - the count, or null
+ * @returns the note
+ */
+function note(code, message, column = null, count = null) {
+    return Object.freeze({ code, message, column, count });
+}
+/**
+ * Inspect a JSON value for what GML cannot write exactly.
+ * @param value - the value
+ * @param stats - the counters to update (each counted at most once per call for numbers / booleans / nulls)
+ * @param inArray - whether the value is an array item
+ * @param seen - the flags already counted for this row
+ */
+function inspectJson(value, stats, inArray, seen) {
+    if (value === null) {
+        if (!seen.nulls) {
+            seen.nulls = true;
+            stats.nulls++;
+        }
+        return;
+    }
+    switch (typeof value) {
+        case "number":
+            if (!seen.numbers) {
+                seen.numbers = true;
+                stats.numbers++;
+            }
+            return;
+        case "boolean":
+            if (!seen.booleans) {
+                seen.booleans = true;
+                stats.booleans++;
+            }
+            return;
+        case "string":
+            return;
+        default:
+            break;
+    }
+    if (Array.isArray(value)) {
+        if (inArray && !seen.nested) {
+            seen.nested = true;
+            stats.nestedArrays++;
+        }
+        for (const item of value) {
+            inspectJson(item, stats, true, seen);
+        }
+        return;
+    }
+    const record = value;
+    for (const key of Object.keys(record)) {
+        if (!isGmlKey(key)) {
+            stats.invalidKeys++;
+        }
+        inspectJson(record[key], stats, false, seen);
+    }
+}
+/**
+ * The GML-specific notes of one table's json columns.
+ * @param columns - the written columns
+ * @param label - the table name
+ * @param plan - the export plan
+ * @param notes - where to record
+ */
+function jsonNotes(columns, label, plan, notes) {
+    for (const { column } of columns) {
+        const stats = jsonStatsOf(column);
+        if (stats === null) {
+            continue;
+        }
+        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(s); 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(s); written as 1 / 0`, name, stats.booleans));
+        }
+        if (stats.nulls > 0) {
+            notes.push(note(RECORD_NULL_CODE, `${where} holds nulls in ${stats.nulls} row(s); 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(s); 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(s); GML cannot write them and export() will throw`, name, stats.nestedArrays));
+        }
+        if (stats.invalidKeys > 0) {
+            notes.push(plan.mangle
+                ? note(KEY_MANGLED_CODE, `${where}: ${stats.invalidKeys} record key(s) are not GML keys and are rewritten`, name, stats.invalidKeys)
+                : note(INVALID_KEY_CODE, `${where}: ${stats.invalidKeys} record key(s) are not GML keys; export() will throw unless sanitizeKeys is "mangle"`, name, stats.invalidKeys));
+        }
+    }
+}
+/**
+ * The json statistics of a json column, or of a list column with json items; null for other dtypes.
+ * @param column - the column
+ * @returns the stats, or null
+ */
+function jsonStatsOf(column) {
+    const stats = { numbers: 0, booleans: 0, nulls: 0, nestedArrays: 0, arrays: 0, invalidKeys: 0 };
+    if (column.dtype === "json") {
+        for (let r = 0; r < column.length; r++) {
+            if (!column.isSet(r)) {
+                continue;
+            }
+            const value = column.values[r];
+            const seen = { numbers: false, booleans: false, nulls: false, nested: false };
+            if (Array.isArray(value)) {
+                stats.arrays++;
+                for (const item of value) {
+                    inspectJson(item, stats, true, seen);
+                }
+            }
+            else {
+                inspectJson(value, stats, false, seen);
+            }
+        }
+        return stats;
+    }
+    if (column.dtype === "list" && column.meta.itemDtype === "json") {
+        for (let r = 0; r < column.length; r++) {
+            if (!column.isSet(r)) {
+                continue;
+            }
+            const seen = { numbers: false, booleans: false, nulls: false, nested: false };
+            for (const item of column.sliceOf(r)) {
+                inspectJson(item, stats, true, seen);
+            }
+        }
+        return stats;
+    }
+    return null;
+}
+/**
+ * The node position column when it can be mapped to graphics x / y / z: a numeric scalar column
+ * with the position role.
+ * @param snapshot - the snapshot
+ * @returns the column, or null
+ */
+function positionColumn(snapshot) {
+    const column = snapshot.nodes.byRole("position");
+    if (column === null) {
+        return null;
+    }
+    switch (column.dtype) {
+        case "f32":
+        case "f64":
+        case "i32":
+        case "u32":
+        case "u8":
+            return column;
+        default:
+            return null;
+    }
+}
+/**
+ * The node `graphics` json column, when present.
+ * @param snapshot - the snapshot
+ * @returns the column, or null
+ */
+function graphicsColumn(snapshot) {
+    return snapshot.nodes.typed("graphics", "json");
+}
+/**
+ * The GML-specific notes about the position / graphics mapping.
+ * @param snapshot - the snapshot
+ * @param notes - where to record
+ */
+function graphicsNotes(snapshot, notes) {
+    const position = positionColumn(snapshot);
+    if (position === null) {
+        return;
+    }
+    if (position.meta.components > 3) {
+        notes.push(note(POSITION_COMPONENTS_CODE, `node column "${position.meta.name}" has ${position.meta.components} components; only x, y and z are written`, position.meta.name, position.length - position.nullCount));
+    }
+    const graphics = graphicsColumn(snapshot);
+    if (graphics === null) {
+        return;
+    }
+    let overridden = 0;
+    let conflicts = 0;
+    for (let r = 0; r < snapshot.nodeCount; r++) {
+        if (!position.isSet(r) || !graphics.isSet(r)) {
+            continue;
+        }
+        const value = graphics.values[r];
+        if (typeof value !== "object" || value === null || Array.isArray(value)) {
+            conflicts++;
+        }
+        else if ("x" in value || "y" in value || "z" in value) {
+            overridden++;
+        }
+    }
+    if (overridden > 0) {
+        notes.push(note(GRAPHICS_OVERRIDDEN_CODE, `${overridden} node graphics record(s) have x / y / z keys the position column replaces`, "graphics", overridden));
+    }
+    if (conflicts > 0) {
+        notes.push(note(GRAPHICS_CONFLICT_CODE, `${conflicts} node graphics value(s) are not records and cannot hold the position; export() will throw`, "graphics", conflicts));
+    }
+}
+/**
+ * What the importer's own rules change on re-import of the written columns: an all-unset column
+ * vanishes (GML writes cells, never declarations), a role-less column named like a role key
+ * gains the role, and the dictionary heuristic of design section 5.4 turns a low-cardinality
+ * string column into a dict (or a wide dict into a string).
+ * @param columns - the written columns
+ * @param domain - node or edge
+ * @param notes - where to record
+ */
+function reimportNotes(columns, domain, notes) {
+    for (const { column, key } of columns) {
+        const { meta } = column;
+        const set = column.length - column.nullCount;
+        if (set === 0) {
+            notes.push(note(LOSS.EMPTY_COLUMN, `${domain} column "${meta.name}" has no set cell and is not written: GML writes cells, never declarations`, meta.name, 0));
+            continue;
+        }
+        if (meta.role === null && (key === "label" || (domain === "edge" && (key === "id" || key === "key")))) {
+            notes.push(note(LOSS.ROLE_ASSUMED, `${domain} column "${meta.name}" is written under "${key}" and reads back with the ${key === "label" ? "label" : key} role`, meta.name, set));
+            continue;
+        }
+        if (column.dtype === "list" || !(column.dtype === "string" || column.dtype === "dict")) {
+            continue;
+        }
+        const heuristic = new DictHeuristic(DICT_SAMPLE_ROWS);
+        for (let r = 0; r < column.length && !heuristic.decided; r++) {
+            if (column.isSet(r)) {
+                heuristic.observe(column.value(r));
+            }
+        }
+        const readsAsDict = heuristic.decide() === "dict";
+        if (column.dtype === "string" && readsAsDict) {
+            notes.push(note(LOSS.STORAGE_CLASS, `${domain} column "${meta.name}" reads back as dict (low cardinality)`, meta.name, null));
+        }
+        else if (column.dtype === "dict" && !readsAsDict) {
+            notes.push(note(LOSS.STORAGE_CLASS, `${domain} column "${meta.name}" reads back as string (cardinality too high for a dict)`, meta.name, null));
+        }
+    }
+}
+/**
+ * The importer names the graphics-derived position column `position`, or `position#graphics`
+ * when a plain `position` key is written next to it (design section 5.6); a position column
+ * named otherwise reads back under that name.
+ * @param snapshot - the snapshot
+ * @param nodeColumns - the written node columns
+ * @param notes - where to record
+ */
+function positionNameNote(snapshot, nodeColumns, notes) {
+    const position = positionColumn(snapshot);
+    if (position === null) {
+        return;
+    }
+    const { name } = position.meta;
+    const plainPosition = nodeColumns.some((c) => c.key === "position");
+    const reimportName = plainPosition ? "position#graphics" : "position";
+    if (name !== reimportName) {
+        notes.push(note(LOSS.COLUMN_NAME_CHANGED, `node column "${name}" (position) is written as the graphics x / y / z keys and reads back as "${reimportName}"`, name, position.length - position.nullCount));
+    }
+}
+/**
+ * Pre-flight: the common capability notes plus the GML-specific ones.
+ * @param snapshot - the snapshot
+ * @param options - the options
+ * @returns the notes, empty when the export is exact
+ */
+function check(snapshot, options) {
+    const plan = planOf(snapshot, options);
+    const notes = checkCapabilities(snapshot, GML_CAPABILITIES, plan.common, {
+        positionDtype: "f64",
+        roles: KEPT_ROLES,
+        roleNames: ROLE_NAMES,
+    });
+    const nodeReserved = new Set(NODE_RESERVED);
+    if ((plan.common.sanitizeIds === "mangle" && countMangled(snapshot) > 0) ||
+        snapshot.nodes.byRole("originalId") !== null) {
+        nodeReserved.add(ORIGINAL_ID_KEY);
+    }
+    const edgeIds = snapshot.edges.byRole("id");
+    const edgeReserved = edgeReservedKeys(snapshot, plan, edgeIds);
+    const topReserved = topReservedKeys(snapshot);
+    const nodeColumns = selectColumns(snapshot.nodes, nodeReserved, "node", plan, notes);
+    const edgeColumns = selectColumns(snapshot.edges, edgeReserved, "edge", plan, notes, (c) => c !== edgeIds);
+    const graphColumns = selectColumns(snapshot.graph, GRAPH_RESERVED, "graph", plan, notes, (c) => !isTopLevel(c));
+    const topColumns = selectColumns(snapshot.graph, topReserved, "top-level", plan, notes, isTopLevel);
+    jsonNotes(nodeColumns, "node", plan, notes);
+    jsonNotes(edgeColumns, "edge", plan, notes);
+    jsonNotes(graphColumns, "graph", plan, notes);
+    jsonNotes(topColumns, "top-level", plan, notes);
+    graphicsNotes(snapshot, notes);
+    positionNameNote(snapshot, nodeColumns, notes);
+    reimportNotes(nodeColumns, "node", notes);
+    reimportNotes(edgeColumns, "edge", notes);
+    if (!hasWeights(snapshot)) {
+        const clash = edgeColumns.find((c) => c.key === plan.weightKey);
+        if (clash !== undefined) {
+            notes.push(note(LOSS.WEIGHT_KEY_CLASH, `edge column "${clash.column.meta.name}" is written under "${plan.weightKey}", the key the importer reads THE weight from; it reads back as the weight, not as a column`, clash.column.meta.name, clash.column.length - clash.column.nullCount));
+        }
+    }
+    const folding = pairFolding(snapshot);
+    if (folding.mutualCount > 0) {
+        notes.push(note(LOSS.MUTUAL_EXPANDED, `${folding.mutualCount} mutual pair(s) are written as two directed edges; the mutual mark is lost`, null, folding.mutualCount));
+    }
+    return Object.freeze(notes);
+}
+/**
+ * The structural keys of the edge table: source, target, the weight key when weights are written,
+ * and `id` when a role-id column is written as the edge id.
+ * @param snapshot - the snapshot
+ * @param plan - the export plan
+ * @param edgeIds - the role-id edge column, or null
+ * @returns the reserved keys
+ */
+function edgeReservedKeys(snapshot, plan, edgeIds) {
+    const reserved = new Set(EDGE_RESERVED);
+    if (hasWeights(snapshot)) {
+        reserved.add(plan.weightKey);
+    }
+    if (edgeIds !== null) {
+        reserved.add("id");
+    }
+    return reserved;
+}
+/**
+ * The structural keys of the top level: graph, plus Creator and Version when the metadata writes them.
+ * @param snapshot - the snapshot
+ * @returns the reserved keys
+ */
+function topReservedKeys(snapshot) {
+    const reserved = new Set(TOP_RESERVED);
+    if (snapshot.meta.creator !== null) {
+        reserved.add("Creator");
+    }
+    if (snapshot.meta.sourceFormat === "gml" && snapshot.meta.sourceVersion !== null) {
+        reserved.add("Version");
+    }
+    return reserved;
+}
+/**
+ * How many node ids are not safe integers (what sanitizeIds "mangle" rewrites).
+ * @param snapshot - the snapshot
+ * @returns the count
+ */
+function countMangled(snapshot) {
+    let count = 0;
+    for (let i = 0; i < snapshot.nodeCount; i++) {
+        const id = snapshot.ids.idOf(i);
+        if (typeof id !== "number" || !Number.isSafeInteger(id)) {
+            count++;
+        }
+    }
+    return count;
+}
+// ============================================================ writing
+/**
+ * The GML text of a real: the shortest text of the dtype with a decimal point guaranteed
+ * (`2.0`, `1.0e-7`), the NetworkX spellings `+INF` / `-INF` / `NAN` for the non-finite values.
+ * @param value - the value
+ * @param dtype - the dtype the value came from (f32 uses the fround-shortest text)
+ * @returns the text
+ */
+export function gmlRealText(value, dtype = "f64") {
+    return formatGmlReal(value, dtype);
+}
+/**
+ * The GML text of a number by the dtype and origin of its column: an integer text for the integer
+ * dtypes and for an f64 column that came from GML `int` values, a real text otherwise.
+ * @param value - the value
+ * @param meta - the column metadata
+ * @returns the text
+ */
+function numberText(value, meta) {
+    switch (meta.dtype) {
+        case "i32":
+        case "u32":
+        case "u8":
+            return formatInteger(value);
+        case "f32":
+            return gmlRealText(value, "f32");
+        default:
+            if (meta.origin?.type === "int" && Number.isInteger(value)) {
+                return formatInteger(value);
+            }
+            return gmlRealText(value, "f64");
+    }
+}
+/**
+ * The GML text of a JSON scalar inside a record: integers as int, other numbers as real, strings
+ * quoted, booleans as 1 / 0.
+ * @param value - the scalar
+ * @returns the text
+ */
+function jsonScalarText(value) {
+    switch (typeof value) {
+        case "number":
+            return Number.isInteger(value) ? formatInteger(value) : gmlRealText(value, "f64");
+        case "boolean":
+            return value ? "1" : "0";
+        default:
+            return quoteGmlString(value);
+    }
+}
+/**
+ * The GML text of a list item or components lane by the item dtype.
+ * @param item - the item
+ * @param itemDtype - the list's item dtype
+ * @param meta - the list column metadata
+ * @returns the text
+ */
+function itemText(item, itemDtype, meta) {
+    switch (typeof item) {
+        case "number":
+            switch (itemDtype) {
+                case "i32":
+                case "u32":
+                case "u8":
+                    return formatInteger(item);
+                case "f32":
+                    return gmlRealText(item, "f32");
+                case "json":
+                    return jsonScalarText(item);
+                default:
+                    return meta.origin?.type === "int" && Number.isInteger(item)
+                        ? formatInteger(item)
+                        : gmlRealText(item, "f64");
+            }
+        case "boolean":
+            return item ? "1" : "0";
+        case "string":
+            return quoteGmlString(item);
+        default:
+            throw new GraphFormatError("E_COLUMN_TYPE", `column "${meta.name}": a ${typeof item} list item cannot be written as GML`, {
+                column: meta.name,
+                found: typeof item,
+            });
+    }
+}
+/** Writes lines with indentation into an array of parts. */
+class GmlWriter {
+    /**
+     * Create a writer.
+     * @param mangle - whether record keys are rewritten rather than refused
+     */
+    constructor(mangle) {
+        this.lines = [];
+        this.mangle = mangle;
+    }
+    /**
+     * Take the lines written so far as one string.
+     * @returns the text; the writer is empty afterwards
+     */
+    take() {
+        const text = this.lines.join("");
+        this.lines.length = 0;
+        return text;
+    }
+    /**
+     * Write one `key value` line.
+     * @param indent - the indentation
+     * @param key - the key
+     * @param value - the value text
+     */
+    line(indent, key, value) {
+        this.lines.push(`${indent}${key} ${value}\n`);
+    }
+    /**
+     * Write a raw line.
+     * @param text - the line without its terminator
+     */
+    raw(text) {
+        this.lines.push(`${text}\n`);
+    }
+    /**
+     * Write one column cell of a row.
+     * @param indent - the indentation
+     * @param key - the key
+     * @param column - the column
+     * @param row - the row
+     */
+    cell(indent, key, column, row) {
+        const { meta, dtype } = column;
+        switch (dtype) {
+            case "f32":
+            case "f64":
+            case "i32":
+            case "u32":
+            case "u8": {
+                const { components } = meta;
+                if (components === 1) {
+                    this.line(indent, key, numberText(column.data[row], meta));
+                }
+                else {
+                    for (let k = 0; k < components; k++) {
+                        this.line(indent, key, numberText(column.data[row * components + k], meta));
+                    }
+                }
+                return;
+            }
+            case "bool":
+                this.line(indent, key, column.value(row) === true ? "1" : "0");
+                return;
+            case "dict":
+            case "string":
+                this.line(indent, key, quoteGmlString(column.value(row) ?? ""));
+                return;
+            case "list":
+                this.list(indent, key, column.sliceOf(row), meta.itemDtype ?? "string", meta);
+                return;
+            case "json":
+                this.json(indent, key, column.values[row], meta.name);
+                return;
+            default: {
+                const name = dtype;
+                throw new GraphFormatError("E_COLUMN_TYPE", `unknown dtype ${name}`, { dtype: name });
+            }
+        }
+    }
+    /**
+     * Write a list as repeated keys with the NetworkX conventions.
+     * @param indent - the indentation
+     * @param key - the key
+     * @param items - the items
+     * @param itemDtype - the item dtype
+     * @param meta - the column metadata
+     */
+    list(indent, key, items, itemDtype, meta) {
+        if (items.length === 0) {
+            this.line(indent, key, quoteGmlString(EMPTY_LIST_TEXT));
+            return;
+        }
+        if (items.length === 1) {
+            this.line(indent, key, quoteGmlString(LIST_START_MARKER));
+        }
+        for (const item of items) {
+            if (itemDtype === "json" && typeof item === "object") {
+                this.json(indent, key, item, meta.name, true);
+            }
+            else {
+                this.line(indent, key, itemText(item, itemDtype, meta));
+            }
+        }
+    }
+    /**
+     * Write a JSON value: a record for an object, repeated keys for an array, a scalar otherwise;
+     * null writes nothing.
+     * @param indent - the indentation
+     * @param key - the key
+     * @param value - the value
+     * @param column - the column name, for errors
+     * @param inArray - whether the value is an array item (an array here has no GML spelling)
+     */
+    json(indent, key, value, column, inArray = false) {
+        if (value === null || value === undefined) {
+            return;
+        }
+        if (Array.isArray(value)) {
+            if (inArray) {
+                throw new GraphFormatError("E_UNSUPPORTED", `column "${column}": an array nested in an array cannot be written as GML`, {
+                    reason: "nested array",
+                    column,
+                });
+            }
+            if (value.length === 0) {
+                this.line(indent, key, quoteGmlString(EMPTY_LIST_TEXT));
+                return;
+            }
+            if (value.length === 1) {
+                this.line(indent, key, quoteGmlString(LIST_START_MARKER));
+            }
+            for (const item of value) {
+                this.json(indent, key, item, column, true);
+            }
+            return;
+        }
+        if (typeof value === "object") {
+            this.record(indent, key, value, column);
+            return;
+        }
+        if (typeof value === "number" || typeof value === "string" || typeof value === "boolean") {
+            this.line(indent, key, jsonScalarText(value));
+            return;
+        }
+        throw new GraphFormatError("E_COLUMN_TYPE", `column "${column}": a ${typeof value} cannot be written as GML`, {
+            column,
+            found: typeof value,
+        });
+    }
+    /**
+     * Write a record `key [ ... ]`.
+     * @param indent - the indentation
+     * @param key - the key
+     * @param record - the object
+     * @param column - the column name, for errors
+     * @param extra - lines to write first (the position of a graphics record), or null
+     */
+    record(indent, key, record, column, extra = null) {
+        this.raw(`${indent}${key} [`);
+        const inner = `${indent}  `;
+        const used = new Set();
+        if (extra !== null) {
+            for (const [k, v] of extra) {
+                this.line(inner, k, v);
+                used.add(k);
+            }
+        }
+        for (const name of Object.keys(record)) {
+            if (used.has(name) && extra !== null && (name === "x" || name === "y" || name === "z")) {
+                continue;
+            }
+            const written = this.recordKey(name, used, column);
+            used.add(written);
+            this.json(inner, written, record[name], column);
+        }
+        this.raw(`${indent}]`);
+    }
+    /**
+     * The key a record field is written under.
+     * @param name - the field name
+     * @param used - the keys already written in the record
+     * @param column - the column name, for errors
+     * @returns a valid, unused key; E_UNSUPPORTED for an invalid key unless mangling
+     */
+    recordKey(name, used, column) {
+        if (isGmlKey(name) && !used.has(name)) {
+            return name;
+        }
+        if (!this.mangle) {
+            throw new GraphFormatError("E_UNSUPPORTED", `column "${column}": record key "${name}" ${isGmlKey(name) ? "repeats a key" : "is not a GML key"}; pass sanitizeKeys: "mangle" to rewrite it`, {
+                reason: "gml key",
+                column,
+                key: name,
+            });
+        }
+        return uniqueKey(isGmlKey(name) ? name : mangleGmlKey(name), used);
+    }
+}
+/**
+ * Resolve everything export() needs, throwing for what check() reported as an error.
+ * @param snapshot - the snapshot
+ * @param options - the options
+ * @returns the context
+ */
+function contextOf(snapshot, options) {
+    const plan = planOf(snapshot, options);
+    const ids = sanitizeIds(snapshot, "integer", plan.common.sanitizeIds);
+    const mixed = countMixedEdges(snapshot);
+    if (mixed > 0 && plan.common.onMixedDirection === "error") {
+        throw new GraphFormatError("E_DIRECTED", `${mixed} undirected edge(s) in a directed graph; GML has no mixed direction (onMixedDirection: "error")`, {
+            reason: "mixed direction",
+            count: mixed,
+        });
+    }
+    // design 8.5: exporters fold expanded pairs back; under "directed" the folded edge is written
+    // once, as one directed edge, under "undirected" the whole graph is written undirected
+    const foldPairs = mixed > 0;
+    const writeDirected = snapshot.directed && plan.common.onMixedDirection !== "undirected";
+    const originalIds = snapshot.nodes.byRole("originalId");
+    const nodeReserved = new Set(NODE_RESERVED);
+    if (ids.changed > 0 || originalIds !== null) {
+        nodeReserved.add(ORIGINAL_ID_KEY);
+    }
+    const edgeIds = snapshot.edges.byRole("id");
+    const edgeReserved = edgeReservedKeys(snapshot, plan, edgeIds);
+    const topReserved = topReservedKeys(snapshot);
+    return {
+        snapshot,
+        plan,
+        ids,
+        writeDirected,
+        foldPairs,
+        nodeColumns: selectColumns(snapshot.nodes, nodeReserved, "node", plan, null, (c) => !(c.meta.name === "graphics" && c.dtype === "json")),
+        edgeColumns: selectColumns(snapshot.edges, edgeReserved, "edge", plan, null, (c) => c !== edgeIds),
+        graphColumns: selectColumns(snapshot.graph, GRAPH_RESERVED, "graph", plan, null, (c) => !isTopLevel(c)),
+        topColumns: selectColumns(snapshot.graph, topReserved, "top-level", plan, null, isTopLevel),
+        position: positionColumn(snapshot),
+        graphics: graphicsColumn(snapshot),
+        originalIds,
+        edgeIds,
+        weights: explicitWeights(snapshot),
+        folding: pairFolding(snapshot),
+    };
+}
+/**
+ * The GML text of an id written into `graphty_originalId`: quoted for a string, a number text
+ * otherwise (an integer as int, else real, so the importer restores the same typed value).
+ * @param id - the original id
+ * @returns the text
+ */
+function originalIdText(id) {
+    if (typeof id === "string") {
+        return quoteGmlString(id);
+    }
+    return Number.isSafeInteger(id) ? formatInteger(id) : gmlRealText(id, "f64");
+}
+/**
+ * The parts of the document.
+ * @param context - the resolved context
+ * @yields one string per header line, node or edge
+ * @returns nothing
+ */
+function* gmlParts(context) {
+    const { snapshot, plan, ids } = context;
+    const w = new GmlWriter(plan.mangle);
+    const { meta } = snapshot;
+    if (meta.creator !== null) {
+        w.line("", "Creator", quoteGmlString(meta.creator));
+    }
+    if (meta.sourceFormat === "gml" && meta.sourceVersion !== null) {
+        w.line("", "Version", versionText(meta.sourceVersion));
+    }
+    for (const { column, key } of context.topColumns) {
+        if (column.isSet(0)) {
+            w.cell("", key, column, 0);
+        }
+    }
+    w.raw("graph [");
+    w.line("  ", "directed", context.writeDirected ? "1" : "0");
+    const multigraph = meta.declaredMultigraph ?? (snapshot.flags.multigraph ? true : null);
+    if (multigraph !== null) {
+        w.line("  ", "multigraph", multigraph ? "1" : "0");
+    }
+    for (const { column, key } of context.graphColumns) {
+        if (column.isSet(0)) {
+            w.cell("  ", key, column, 0);
+        }
+    }
+    yield w.take();
+    for (let i = 0; i < snapshot.nodeCount; i++) {
+        w.raw("  node [");
+        w.line("    ", "id", formatInteger(ids.idAt(i)));
+        if (ids.isChanged(i)) {
+            w.line("    ", ORIGINAL_ID_KEY, originalIdText(ids.originalAt(i)));
+        }
+        else if (context.originalIds !== null && context.originalIds.isSet(i)) {
+            const original = context.originalIds.value(i);
+            if (typeof original === "string" || typeof original === "number") {
+                w.line("    ", ORIGINAL_ID_KEY, originalIdText(original));
+            }
+        }
+        for (const { column, key } of context.nodeColumns) {
+            if (column.isSet(i)) {
+                w.cell("    ", key, column, i);
+            }
+        }
+        writeGraphics(w, context, i);
+        w.raw("  ]");
+        yield w.take();
+    }
+    const el = snapshot.edgeList();
+    const origin = meta.weightOrigin;
+    const integerWeights = origin !== null && origin.type === "int";
+    for (let e = 0; e < snapshot.edgeCount; e++) {
+        if (context.foldPairs && context.folding.folded(e)) {
+            continue;
+        }
+        w.raw("  edge [");
+        w.line("    ", "source", formatInteger(ids.idAt(el.src[e])));
+        w.line("    ", "target", formatInteger(ids.idAt(el.dst[e])));
+        if (context.edgeIds !== null && context.edgeIds.isSet(e)) {
+            w.cell("    ", "id", context.edgeIds, e);
+        }
+        if (context.weights.isExplicit(e)) {
+            const weight = context.weights.value(e);
+            const text = integerWeights && Number.isInteger(weight)
+                ? formatInteger(weight)
+                : gmlRealText(weight, context.weights.dtype);
+            w.line("    ", plan.weightKey, text);
+        }
+        for (const { column, key } of context.edgeColumns) {
+            if (column.isSet(e)) {
+                w.cell("    ", key, column, e);
+            }
+        }
+        w.raw("  ]");
+        yield w.take();
+    }
+    w.raw("]");
+    yield w.take();
+}
+/**
+ * Write a node's `graphics [ ... ]` record from the position column and the graphics json column.
+ * @param w - the writer
+ * @param context - the context
+ * @param i - the node
+ */
+function writeGraphics(w, context, i) {
+    const { position, graphics } = context;
+    const hasPosition = position !== null && position.isSet(i);
+    const graphicsValue = graphics !== null && graphics.isSet(i) ? graphics.values[i] : undefined;
+    if (!hasPosition) {
+        if (graphics !== null && graphicsValue !== undefined) {
+            w.cell("    ", "graphics", graphics, i);
+        }
+        return;
+    }
+    const numeric = position;
+    const { components } = numeric.meta;
+    const lanes = Math.min(components, 3);
+    const extra = [];
+    const names = ["x", "y", "z"];
+    for (let k = 0; k < lanes; k++) {
+        extra.push([names[k], numberText(numeric.data[i * components + k], numeric.meta)]);
+    }
+    let record = {};
+    if (graphicsValue !== undefined) {
+        if (typeof graphicsValue !== "object" || graphicsValue === null || Array.isArray(graphicsValue)) {
+            throw new GraphFormatError("E_UNSUPPORTED", `node ${i}: the graphics value is not a record and cannot hold the position`, {
+                reason: "graphics conflict",
+                node: i,
+            });
+        }
+        record = graphicsValue;
+    }
+    w.record("    ", "graphics", record, "graphics", extra);
+}
+/** The GML exporter plugin. */
+export const gmlExporter = Object.freeze({
+    format: "gml",
+    capabilities: GML_CAPABILITIES,
+    check,
+    /**
+     * Write the snapshot as UTF-8 chunks; the context is resolved on the first pull, so the
+     * errors check() announced surface from the iteration.
+     * @param snapshot - the snapshot
+     * @param options - the options
+     * @returns the chunks
+     */
+    export(snapshot, options) {
+        return encodeChunks(lazyParts(snapshot, options));
+    },
+    /**
+     * Write the snapshot as one string.
+     * @param snapshot - the snapshot
+     * @param options - the options
+     * @returns the document
+     */
+    exportToString(snapshot, options) {
+        return joinText(lazyParts(snapshot, options));
+    },
+});
+/**
+ * The document parts, with the context resolved when iteration starts.
+ * @param snapshot - the snapshot
+ * @param options - the options
+ * @yields the parts
+ * @returns nothing
+ */
+function* lazyParts(snapshot, options) {
+    yield* gmlParts(contextOf(snapshot, options));
+}
+//# sourceMappingURL=exporter.js.map