@graphty/graph-io 0.3.19 → 0.3.21

package/src/formats/xgmml/importer.ts

@@ -0,0 +1,491 @@
+/**
+ * The XGMML importer (design `design/graph-io/cytoscape-and-obo/design.md` section 1.1;
+ * `research-xgmml.md`): one reader for the 1.0 draft, the Cytoscape 2.x and 3.x exports and the
+ * Cytoscape 3 session network files. The document is read in one pass of the shared XML tokenizer
+ * into records (document.ts), and resolved into the sink once the outermost `</graph>` closes
+ * (emit.ts), so forward references and edges before their nodes need nothing special.
+ *
+ * Direction follows the specification: the root `directed` (0 by the DTD, else the
+ * `defaultDirected` option), then `cy:directed` per edge, overruling Cytoscape, which ignores the
+ * root attribute. Ids are kept as written (`ids: "keep"`), so `"1"`, `"01"` and `" 1 "` stay three
+ * nodes. Positions are stored y-up (Cytoscape writes screen coordinates). Graphics values are kept
+ * as a json column, never interpreted (style import is issue #706).
+ */
+
+import { GraphFormatError, type GraphSink } from "@graphty/graph-format";
+
+import { textChunks, throwIfAborted } from "../../common/input.js";
+import {
+    chooseGraph,
+    type ImportFormatDefaults,
+    reportSinkOptions,
+    reportUnusedOptions,
+    type ResolvedImportOptions,
+    resolveImportOptions,
+} from "../../common/options.js";
+import { ImportReportBuilder } from "../../common/report.js";
+import { isWhitespace, tokenizeXml, xmlDeclaredEncoding, type XmlRepairs, XmlSyntaxError } from "../../common/xml.js";
+import {
+    type CommonImportOptions,
+    type GraphChoiceOptions,
+    type GraphImporter,
+    type GraphListing,
+    type ImportInput,
+    type ImportReport,
+} from "../../types.js";
+import { EXTENSIONS, FORMAT, MIME_TYPES, XGMML_ISSUE } from "./constants.js";
+import { type GraphRec, type XgmmlDocument, XgmmlParser } from "./document.js";
+import {
+    type Dialect,
+    dialectOf,
+    type EmitExtras,
+    graphsOf,
+    membersOf,
+    XgmmlEmitter,
+    type XgmmlSettings,
+} from "./emit.js";
+
+/** The format-specific options of the XGMML importer. */
+export interface XgmmlImportOptions extends GraphChoiceOptions {
+    /**
+     * Resolve an edge endpoint that is missing or names no node through Cytoscape's
+     * `"source (interaction) target"` edge label, and fill a missing interaction from it. Default:
+     * on for files that use the Cytoscape (`cy`) namespace, off otherwise.
+     */
+    labelAliases?: boolean | undefined;
+    /**
+     * Decode Cytoscape's two-character `\n` and `\t` escapes in string values. Default: on for
+     * files that use the Cytoscape namespace, off otherwise.
+     */
+    cytoscapeEscapes?: boolean | undefined;
+    /** Read an `&` not followed by `;` within 7 characters as `&amp;` (warned per occurrence). Default false. */
+    repairBareAmpersands?: boolean | undefined;
+    /** Join two surrogate character references into one character (warned per pair). Default false. */
+    pairSurrogateReferences?: boolean | undefined;
+    /** Where Cytoscape's z (a stacking order) goes: the `z` column (default) or the position. */
+    zAs?: "column" | "position" | undefined;
+}
+
+/** The per-format defaults: ids as written, undirected by the DTD, the edge `weight` attribute. */
+const FORMAT_DEFAULTS: ImportFormatDefaults = {
+    ids: "keep",
+    defaultDirected: false,
+    weightFrom: "weight",
+    addMissingNodes: false,
+};
+
+/** The common options the XGMML importer reads. */
+const USED_OPTIONS: ReadonlySet<keyof CommonImportOptions> = new Set<keyof CommonImportOptions>([
+    "ids",
+    "addMissingNodes",
+    "duplicateEdges",
+    "selfLoops",
+    "onMixedDirection",
+    "defaultDirected",
+    "weightFrom",
+    "weightDtype",
+    "long",
+    "errorLimit",
+    "signal",
+    "onProgress",
+    "encoding",
+]);
+
+/** Bytes inspected by sniff(). */
+const SNIFF_BYTES = 4096;
+
+/** The head of the document kept for the DOCTYPE check. */
+const HEAD_CHARS = 2048;
+
+/** An XGMML DOCTYPE (Cytoscape's file filter tests the same). */
+const XGMML_DOCTYPE = /<!DOCTYPE\s+graph\s[^<>]*xgmml\.dtd/i;
+
+/**
+ * The XGMML option values, checked.
+ * @param options - the caller's options
+ * @param cytoscape - whether the document uses the Cytoscape namespace
+ * @returns the settings; E_UNSUPPORTED for a value of the wrong type
+ */
+export function resolveSettings(options: XgmmlImportOptions | undefined, cytoscape: boolean): XgmmlSettings {
+    const zAs = options?.zAs ?? "column";
+    if (zAs !== "column" && zAs !== "position") {
+        throw new GraphFormatError(
+            "E_UNSUPPORTED",
+            `option zAs: ${JSON.stringify(zAs)} is not "column" or "position"`,
+            {
+                option: "zAs",
+                found: zAs,
+            },
+        );
+    }
+    return {
+        labelAliases: booleanOption("labelAliases", options?.labelAliases, cytoscape),
+        cytoscapeEscapes: booleanOption("cytoscapeEscapes", options?.cytoscapeEscapes, cytoscape),
+        zAs,
+    };
+}
+
+/**
+ * One boolean option.
+ * @param name - the option name
+ * @param value - the caller's value
+ * @param fallback - the default
+ * @returns the value; E_UNSUPPORTED when not a boolean
+ */
+function booleanOption(name: string, value: unknown, fallback: boolean): boolean {
+    if (value === undefined) {
+        return fallback;
+    }
+    if (typeof value !== "boolean") {
+        throw new GraphFormatError("E_UNSUPPORTED", `option ${name}: ${JSON.stringify(value)} is not a boolean`, {
+            option: name,
+            found: value,
+        });
+    }
+    return value;
+}
+
+/**
+ * Read an XGMML document into records. Fatal conditions (not XML, not a graph, empty) fail the
+ * report.
+ * @param input - the input
+ * @param report - the report
+ * @param common - the resolved common options
+ * @param options - the XGMML options (for the repairs)
+ * @returns the document
+ */
+export async function parseXgmml(
+    input: ImportInput,
+    report: ImportReportBuilder,
+    common: ResolvedImportOptions,
+    options: XgmmlImportOptions | undefined,
+): Promise<XgmmlDocument> {
+    const repairs: XmlRepairs = {
+        bareAmpersand: booleanOption("repairBareAmpersands", options?.repairBareAmpersands, false)
+            ? (line): void => {
+                  report.warning("parse-error", XGMML_ISSUE.AMPERSAND_REPAIRED, "a bare & was read as &amp;", { line });
+              }
+            : undefined,
+        surrogatePair: booleanOption("pairSurrogateReferences", options?.pairSurrogateReferences, false)
+            ? (line): void => {
+                  report.warning(
+                      "parse-error",
+                      XGMML_ISSUE.SURROGATE_PAIRED,
+                      "two surrogate character references were joined into one character",
+                      { line },
+                  );
+              }
+            : undefined,
+    };
+    const parser = new XgmmlParser(report);
+    const seen = { head: "", content: false };
+    try {
+        await tokenizeXml(
+            watch(textChunks(input, report, { ...common, declaredEncoding: xmlDeclaredEncoding }), seen),
+            parser,
+            repairs,
+        );
+    } catch (err) {
+        if (err instanceof XmlSyntaxError) {
+            if (!seen.content) {
+                report.fail(XGMML_ISSUE.EMPTY_INPUT, "the input is empty");
+            }
+            report.fail(XGMML_ISSUE.XML_SYNTAX, err.message, { line: err.line });
+        }
+        throw err;
+    }
+    const doc = parser.document();
+    if (!doc.xgmmlNamespace && !XGMML_DOCTYPE.test(seen.head)) {
+        report.warning(
+            "validation-error",
+            XGMML_ISSUE.NO_NAMESPACE,
+            "the root <graph> has neither the XGMML namespace nor an XGMML DOCTYPE; it is read as XGMML",
+            { line: doc.root.line },
+        );
+    }
+    return doc;
+}
+
+/**
+ * Pass text chunks through while keeping the head and noting non-whitespace content.
+ * @param chunks - the chunks
+ * @param seen - where the head and the content flag are kept
+ * @param seen.head - the first characters of the document
+ * @param seen.content - whether non-whitespace text was seen
+ * @yields the chunks unchanged
+ * @returns nothing
+ */
+async function* watch(
+    chunks: AsyncIterable<string>,
+    seen: { head: string; content: boolean },
+): AsyncGenerator<string, void, undefined> {
+    for await (const chunk of chunks) {
+        if (seen.head.length < HEAD_CHARS) {
+            seen.head += chunk.slice(0, HEAD_CHARS - seen.head.length);
+        }
+        seen.content ||= !isWhitespace(chunk);
+        yield chunk;
+    }
+}
+
+/** What an import call sets up before it emits. */
+interface Prepared {
+    readonly report: ImportReportBuilder;
+    readonly common: ResolvedImportOptions;
+    readonly doc: XgmmlDocument;
+    readonly dialect: Dialect;
+    readonly settings: XgmmlSettings;
+    readonly graphs: readonly GraphRec[];
+}
+
+/**
+ * Resolve the options, read the document and check it is a graph document.
+ * @param input - the input
+ * @param sink - the sink, or null for listGraphs
+ * @param options - the options
+ * @returns what the import needs
+ */
+async function prepare(
+    input: ImportInput,
+    sink: GraphSink | null,
+    options: (XgmmlImportOptions & CommonImportOptions) | undefined,
+): Promise<Prepared> {
+    const common = resolveImportOptions(options, FORMAT_DEFAULTS);
+    const report = new ImportReportBuilder(FORMAT, common.errorLimit);
+    if (sink !== null) {
+        reportSinkOptions(sink, options, report, true);
+        reportUnusedOptions(options, report, USED_OPTIONS);
+    }
+    resolveSettings(options, false);
+    const doc = await parseXgmml(input, report, common, options);
+    const dialect = dialectOf(doc, report);
+    if (dialect.view) {
+        report.fail(
+            XGMML_ISSUE.VIEW_DOCUMENT,
+            "this is a Cytoscape session view file (cy:view): it holds positions keyed by view ids and no topology; open the session (.cys) instead",
+            { line: doc.root.line },
+        );
+    }
+    return {
+        report,
+        common,
+        doc,
+        dialect,
+        settings: resolveSettings(options, doc.cytoscape),
+        graphs: graphsOf(doc, dialect),
+    };
+}
+
+/**
+ * Emit one graph of a prepared document.
+ * @param prepared - the prepared import
+ * @param graph - the graph to read
+ * @param sink - the sink
+ * @param extras - what a session adds
+ * @returns the report
+ */
+function emitOne(prepared: Prepared, graph: GraphRec, sink: GraphSink, extras?: EmitExtras): ImportReport {
+    const { doc, dialect, report, common, settings } = prepared;
+    const emitter = new XgmmlEmitter(doc, dialect, sink, report, common, settings, extras);
+    emitter.emit(dialect.session ? graph : null);
+    if (dialect.session) {
+        reportRootOnly(prepared);
+    }
+    throwIfAborted(common.signal);
+    return report.finish();
+}
+
+/**
+ * W_XGMML_ROOT_ONLY_ELEMENTS: elements of a session network document no registered subnetwork
+ * holds (group meta-edges, members of collapsed groups).
+ * @param prepared - the prepared import
+ */
+function reportRootOnly(prepared: Prepared): void {
+    const held = new Set<unknown>();
+    for (const graph of prepared.graphs) {
+        const members = membersOf(prepared.doc, graph);
+        members.nodes.forEach((n) => held.add(n));
+        members.edges.forEach((e) => held.add(e));
+    }
+    const nodes = prepared.doc.nodes.filter((n) => !held.has(n)).length;
+    const edges = prepared.doc.edges.filter((e) => !held.has(e)).length;
+    if (nodes + edges > 0) {
+        prepared.report.warning(
+            "unsupported",
+            XGMML_ISSUE.ROOT_ONLY_ELEMENTS,
+            `${nodes} node(s) and ${edges} edge(s) belong to no registered network (group meta-edges, collapsed group members) and were not read`,
+        );
+    }
+}
+
+/**
+ * Import one graph of an XGMML document.
+ * @param input - the document
+ * @param sink - the sink
+ * @param options - format-specific and common options
+ * @returns the report; ImportError when the document cannot be read or the error limit is exceeded
+ */
+async function importXgmml(
+    input: ImportInput,
+    sink: GraphSink,
+    options?: XgmmlImportOptions & CommonImportOptions,
+): Promise<ImportReport> {
+    const prepared = await prepare(input, sink, options);
+    const index = chooseGraph(
+        prepared.graphs.map((g) => graphName(g, prepared.doc)),
+        options,
+        prepared.report,
+    );
+    if (prepared.graphs.length > 1) {
+        prepared.report.warning(
+            "unsupported",
+            XGMML_ISSUE.MULTIPLE_GRAPHS,
+            `the session network document holds ${prepared.graphs.length} registered networks; ${prepared.graphs.length - 1} were not read (use importAll, graphIndex or graphName)`,
+        );
+    }
+    return emitOne(prepared, prepared.graphs[index], sink);
+}
+
+/**
+ * Import every graph of an XGMML document: each registered subnetwork of a session network
+ * document, else the one graph.
+ * @param input - the document
+ * @param sinkFor - a sink per graph
+ * @param options - format-specific and common options
+ * @returns one report per graph
+ */
+async function importAllXgmml(
+    input: ImportInput,
+    sinkFor: (index: number) => GraphSink,
+    options?: XgmmlImportOptions & CommonImportOptions,
+): Promise<ImportReport[]> {
+    const bytes = await reread(input);
+    const first = await prepare(bytes, null, options);
+    const reports: ImportReport[] = [];
+    for (let i = 0; i < first.graphs.length; i++) {
+        const sink = sinkFor(i);
+        const prepared = i === 0 ? first : await prepare(bytes, null, options);
+        reportSinkOptions(sink, options, prepared.report, true);
+        reportUnusedOptions(options, prepared.report, USED_OPTIONS);
+        reports.push(emitOne(prepared, prepared.graphs[i], sink));
+    }
+    return reports;
+}
+
+/**
+ * List the graphs of an XGMML document without importing them.
+ * @param input - the document
+ * @param options - the options
+ * @returns one listing per graph
+ */
+async function listXgmmlGraphs(
+    input: ImportInput,
+    options?: XgmmlImportOptions & CommonImportOptions,
+): Promise<readonly GraphListing[]> {
+    const prepared = await prepare(input, null, options);
+    return prepared.graphs.map((graph, index) => {
+        const members = membersOf(prepared.doc, prepared.dialect.session ? graph : null);
+        return Object.freeze({
+            index,
+            name: graphName(graph, prepared.doc),
+            nodes: new Set(members.nodes.map((n) => n.id)).size,
+            edges: members.edges.length,
+        });
+    });
+}
+
+/**
+ * The name of a graph: its label, else the RDF title (root only), else its id.
+ * @param graph - the graph
+ * @param doc - the document
+ * @returns the name, or null
+ */
+function graphName(graph: GraphRec, doc: XgmmlDocument): string | null {
+    return graph.label ?? (graph === doc.root ? (doc.rdf.title ?? null) : null) ?? graph.id ?? null;
+}
+
+/**
+ * The input in a form that can be read more than once (a stream is read into bytes).
+ * @param input - the input
+ * @returns the same input when it is a string or bytes, else the collected bytes
+ */
+async function reread(input: ImportInput): Promise<string | Uint8Array> {
+    if (typeof input === "string" || input instanceof Uint8Array) {
+        return input;
+    }
+    const parts: (string | Uint8Array)[] = [];
+    const iterable: AsyncIterable<string | Uint8Array> =
+        typeof (input as { getReader?: unknown }).getReader === "function"
+            ? streamIterable(input as ReadableStream<Uint8Array>)
+            : (input as AsyncIterable<string | Uint8Array>);
+    for await (const chunk of iterable) {
+        parts.push(chunk);
+    }
+    if (parts.every((p) => typeof p === "string")) {
+        return parts.join("");
+    }
+    const bytes = parts.map((p) => (typeof p === "string" ? new TextEncoder().encode(p) : p));
+    const out = new Uint8Array(bytes.reduce((n, b) => n + b.byteLength, 0));
+    let at = 0;
+    for (const b of bytes) {
+        out.set(b, at);
+        at += b.byteLength;
+    }
+    return out;
+}
+
+/**
+ * A ReadableStream as an async iterable.
+ * @param stream - the stream
+ * @yields its chunks
+ * @returns nothing
+ */
+async function* streamIterable(stream: ReadableStream<Uint8Array>): AsyncGenerator<Uint8Array, void, undefined> {
+    const reader = stream.getReader();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) {
+                return;
+            }
+            yield value;
+        }
+    } finally {
+        reader.releaseLock();
+    }
+}
+
+/**
+ * Confidence that a head of bytes is XGMML: 0.95 for a root `graph` in the XGMML namespace or an
+ * XGMML DOCTYPE (Cytoscape's file filter tests the same two things, and a session view file still
+ * scores so its failure names it), 0.5 for a root local name `graph` without either.
+ * @param head - the first bytes
+ * @returns the confidence
+ */
+function sniffXgmml(head: Uint8Array): number {
+    const text = new TextDecoder("utf-8", { fatal: false }).decode(head.subarray(0, SNIFF_BYTES));
+    if (!/^\uFEFF?\s*</.test(text)) {
+        return 0;
+    }
+    if (XGMML_DOCTYPE.test(text)) {
+        return 0.95;
+    }
+    const root = /<(?!\?|!)([A-Za-z_][\w.-]*:)?([A-Za-z_][\w.-]*)[\s/>]/.exec(text.replace(/<!--[\s\S]*?-->/g, ""));
+    if (root === null || root[2] !== "graph") {
+        return 0;
+    }
+    const tagEnd = text.indexOf(">", root.index);
+    const tag = text.slice(root.index, tagEnd < 0 ? undefined : tagEnd);
+    return tag.includes("http://www.cs.rpi.edu/XGMML") ? 0.95 : 0.5;
+}
+
+/** The XGMML importer. */
+export const xgmmlImporter: GraphImporter<XgmmlImportOptions> = Object.freeze({
+    format: FORMAT,
+    extensions: EXTENSIONS,
+    mimeTypes: MIME_TYPES,
+    sniff: sniffXgmml,
+    import: importXgmml,
+    importAll: importAllXgmml,
+    listGraphs: listXgmmlGraphs,
+});

package/src/formats/xgmml/index.ts

@@ -0,0 +1,8 @@
+/**
+ * The `@graphty/graph-io/xgmml` subpath: the XGMML importer and exporter, their option types and
+ * their issue and loss-note code tables.
+ */
+
+export { XGMML_ISSUE, XGMML_LOSS } from "./constants.js";
+export { xgmmlExporter, type XgmmlExportOptions } from "./exporter.js";
+export { xgmmlImporter, type XgmmlImportOptions } from "./importer.js";

package/src/formats/xgmml/values.ts

@@ -0,0 +1,183 @@
+/**
+ * XGMML attribute types and values (`research-xgmml.md` sections 3.6, 3.8 and 4.3): which kind an
+ * `<att>` declares (Cytoscape's `cy:type` before the draft's `type`, case-insensitively), and the
+ * lexical rules of each kind as Cytoscape writes them. A value that does not parse is never
+ * guessed at: the caller records E_BAD_VALUE and leaves the cell unset.
+ */
+
+import { type AttRec } from "./document.js";
+
+/** The scalar kinds of a column, in widening order (string beats everything). */
+export type ScalarKind = "bool" | "int" | "long" | "real" | "string";
+
+/** What one att declares. */
+type DeclaredKind = ScalarKind | "list" | "map";
+
+/** The declared kind of an att and the type text to keep in `origin.type`. */
+interface AttType {
+    /** The kind. */
+    readonly kind: DeclaredKind;
+    /** The type as declared (`cy:type` when given, else `type`), or null for an untyped att. */
+    readonly declared: string | null;
+    /** The type text no kind matched (kept as text, W_UNKNOWN_ATTR_TYPE), or null. */
+    readonly unknown: string | null;
+}
+
+/** Cytoscape's `cy:type` names (3.3+), lower-cased. */
+const CY_TYPES: Readonly<Record<string, DeclaredKind>> = {
+    string: "string",
+    double: "real",
+    integer: "int",
+    long: "long",
+    boolean: "bool",
+    list: "list",
+};
+
+/** The XGMML draft's types, Cytoscape's `boolean` and the 2.x `map`, lower-cased. */
+const XGMML_TYPES: Readonly<Record<string, DeclaredKind>> = {
+    string: "string",
+    real: "real",
+    integer: "int",
+    boolean: "bool",
+    list: "list",
+    map: "map",
+};
+
+/**
+ * The kind an att declares: `cy:type` first, then `type`, both case-insensitive; no type is a
+ * string; an unknown type is a string the caller reports. An untyped-by-Cytoscape `integer` att
+ * whose name ends in `.SUID` is a long (Cytoscape keeps SUID references as Long).
+ * @param att - the att
+ * @returns the declared kind
+ */
+export function attType(att: AttRec): AttType {
+    let kind: DeclaredKind | undefined;
+    let declared: string | null = null;
+    if (att.cyType !== null && att.cyType.length > 0) {
+        kind = CY_TYPES[att.cyType.trim().toLowerCase()];
+        declared = att.cyType;
+    }
+    if (kind === undefined && att.type !== null && att.type.length > 0) {
+        kind = XGMML_TYPES[att.type.trim().toLowerCase()];
+        declared = att.type;
+    }
+    if (kind === undefined) {
+        const unknown = declared ?? null;
+        return { kind: "string", declared, unknown };
+    }
+    if (kind === "int" && att.cyType === null && att.name?.endsWith(".SUID") === true) {
+        // pre-3.3 Cytoscape wrote its Long SUID references as "integer"; a real one stays real
+        // (Cytoscape writes Double.toString forms such as "21.0", which no integer rule reads)
+        kind = "long";
+    }
+    return { kind, declared, unknown: null };
+}
+
+/**
+ * The scalar kind a list element type names (`cy:elementType`), or null when it names none.
+ * @param text - the element type text
+ * @returns the kind, or null
+ */
+export function elementKind(text: string | null): ScalarKind | null {
+    if (text === null) {
+        return null;
+    }
+    const kind = CY_TYPES[text.trim().toLowerCase()] ?? XGMML_TYPES[text.trim().toLowerCase()];
+    return kind === undefined || kind === "list" || kind === "map" ? null : kind;
+}
+
+/**
+ * The wider of two scalar kinds (design section 5.1): int and long widen to long, any two numbers
+ * to real, a boolean and a number to string, anything and a string to string.
+ * @param a - one kind
+ * @param b - the other
+ * @returns the kind both fit
+ */
+export function widenScalar(a: ScalarKind, b: ScalarKind): ScalarKind {
+    if (a === b) {
+        return a;
+    }
+    if (a === "string" || b === "string" || a === "bool" || b === "bool") {
+        return "string";
+    }
+    if (a === "real" || b === "real") {
+        return "real";
+    }
+    return "long";
+}
+
+const INTEGER_TEXT = /^[+-]?[0-9]+$/;
+
+/** Java's Double.valueOf forms that Cytoscape writes: no hex, no `d` / `f` suffix. */
+const REAL_TEXT = /^[+-]?(NaN|Infinity|([0-9]+\.?[0-9]*|\.[0-9]+)([eE][+-]?[0-9]+)?)$/;
+
+const I32_MIN = -2147483648;
+const I32_MAX = 2147483647;
+
+/** A parsed scalar and what parsing it found. */
+interface ParsedScalar {
+    /** The value. */
+    readonly value: boolean | number | string;
+    /** An integer beyond i32 (the column widens), or a long / real beyond what a double holds exactly. */
+    readonly overflow?: "i32" | "precision" | undefined;
+}
+
+/**
+ * Parse one value text by its declared scalar kind. Numbers and booleans are trimmed; strings
+ * never are. Booleans accept 1 / 0 / true / false / yes / no in any case.
+ * @param text - the value text
+ * @param kind - the declared kind
+ * @param unescape - decode Cytoscape's two-character `\n` and `\t` in strings
+ * @returns the value, or null when the text does not parse as the kind
+ */
+export function parseScalar(text: string, kind: ScalarKind, unescape: boolean): ParsedScalar | null {
+    switch (kind) {
+        case "string":
+            return { value: unescape ? unescapeCytoscape(text) : text };
+        case "bool": {
+            const t = text.trim().toLowerCase();
+            if (t === "1" || t === "true" || t === "yes") {
+                return { value: true };
+            }
+            if (t === "0" || t === "false" || t === "no") {
+                return { value: false };
+            }
+            return null;
+        }
+        case "int":
+        case "long": {
+            const t = text.trim();
+            if (!INTEGER_TEXT.test(t)) {
+                return null;
+            }
+            const n = Number(t);
+            if (kind === "int" && (n < I32_MIN || n > I32_MAX)) {
+                return { value: n, overflow: Number.isSafeInteger(n) ? "i32" : "precision" };
+            }
+            return { value: n, overflow: Number.isSafeInteger(n) ? undefined : "precision" };
+        }
+        case "real": {
+            const t = text.trim();
+            if (!REAL_TEXT.test(t)) {
+                return null;
+            }
+            const n = Number(t);
+            // only a finite spelling that overflows (1e400) loses precision; NaN and the infinities are exact
+            const overflow = !Number.isFinite(n) && !/Infinity|NaN/.test(t) ? "precision" : undefined;
+            return { value: n, overflow };
+        }
+        default: {
+            const name: never = kind;
+            throw new Error(`unknown scalar kind ${String(name)}`);
+        }
+    }
+}
+
+/**
+ * Decode the two-character escapes the Cytoscape writer uses for newline and tab.
+ * @param text - the text
+ * @returns the text with `\n` and `\t` decoded
+ */
+function unescapeCytoscape(text: string): string {
+    return text.includes("\\") ? text.replace(/\\t/g, "\t").replace(/\\n/g, "\n") : text;
+}