@graphty/graph-io 0.0.0 → 0.2.0

package/dist/src/common/escape.js

@@ -0,0 +1,212 @@
+/**
+ * Id, label and value escaping for the text formats (design section 8.5), one function per
+ * syntax, with the inverse where the importer needs it: XML attribute and element text (GEXF,
+ * GraphML), GML quoted strings (`"` and `&` and non-ASCII as `&#NN;` character entities, the
+ * NetworkX convention), DOT ids (bare when the grammar allows, quoted with `\"` otherwise), RFC
+ * 4180 CSV cells and Pajek labels.
+ */
+import { GraphFormatError } from "@graphty/graph-format";
+import { hasIllegalXmlChar } from "./xml.js";
+const XML_TEXT_SPECIAL = /[&<>\r]/g;
+const XML_ATTR_SPECIAL = /[&<>"\t\n\r]/g;
+const XML_REPLACEMENTS = {
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "\t": "&#9;",
+    "\n": "&#10;",
+    "\r": "&#13;",
+};
+/**
+ * Escape text for an XML element body: `&`, `<`, `>` and a carriage return (which XML
+ * end-of-line handling would turn into a line feed on every read) as character references. A
+ * character XML 1.0 forbids (a C0 control other than tab / LF / CR, U+FFFE, U+FFFF, a lone
+ * surrogate) has no XML spelling at all and is E_COLUMN_TYPE; the exporters' check() counts them.
+ * @param text - the text
+ * @returns the escaped text
+ */
+export function escapeXmlText(text) {
+    if (hasIllegalXmlChar(text)) {
+        throw illegalXml(text);
+    }
+    return text.replace(XML_TEXT_SPECIAL, (c) => XML_REPLACEMENTS[c]);
+}
+/**
+ * Escape text for a double-quoted XML attribute value: `&`, `<`, `>`, `"` and the whitespace
+ * characters attribute normalisation would fold; a character XML 1.0 forbids is E_COLUMN_TYPE.
+ * @param text - the text
+ * @returns the escaped text
+ */
+export function escapeXmlAttribute(text) {
+    if (hasIllegalXmlChar(text)) {
+        throw illegalXml(text);
+    }
+    return text.replace(XML_ATTR_SPECIAL, (c) => XML_REPLACEMENTS[c]);
+}
+/**
+ * The error of a text no XML 1.0 document can carry.
+ * @param text - the text
+ * @returns the error
+ */
+function illegalXml(text) {
+    return new GraphFormatError("E_COLUMN_TYPE", "the text holds a character XML 1.0 cannot carry", {
+        reason: "xml illegal char",
+        length: text.length,
+    });
+}
+const GML_SPECIAL = /["&]|[^ -~]/gu;
+/**
+ * Quote a GML string value: double quotes around the text with `"`, `&` and every character
+ * outside printable ASCII written as `&#NN;` (NetworkX's writer convention, which its reader and
+ * Gephi's decode).
+ * A lone surrogate cannot be written and is E_COLUMN_TYPE.
+ * @param text - the text
+ * @returns the quoted GML string
+ */
+export function quoteGmlString(text) {
+    const escaped = text.replace(GML_SPECIAL, (c) => {
+        const code = c.codePointAt(0);
+        if (code === undefined) {
+            return c;
+        }
+        if (code >= 0xd800 && code <= 0xdfff) {
+            throw new GraphFormatError("E_COLUMN_TYPE", "a lone surrogate cannot be written as a GML string", {
+                reason: "lone surrogate",
+            });
+        }
+        return `&#${code};`;
+    });
+    return `"${escaped}"`;
+}
+const GML_ENTITY = /&(#[0-9]+|#x[0-9a-fA-F]+|amp|quot|lt|gt|apos);/g;
+const GML_NAMED = { amp: "&", quot: '"', lt: "<", gt: ">", apos: "'" };
+/**
+ * Decode the character entities of a GML string body (the inverse of quoteGmlString on the text
+ * between the quotes). An unknown entity is left as written.
+ * @param body - the text between the quotes
+ * @returns the decoded text
+ */
+export function decodeGmlString(body) {
+    return body.replace(GML_ENTITY, (whole, entity) => {
+        if (entity.startsWith("#x")) {
+            return String.fromCodePoint(Number.parseInt(entity.slice(2), 16));
+        }
+        if (entity.startsWith("#")) {
+            return String.fromCodePoint(Number.parseInt(entity.slice(1), 10));
+        }
+        return GML_NAMED[entity] ?? whole;
+    });
+}
+const DOT_NUMERAL = /^-?(\.[0-9]+|[0-9]+(\.[0-9]*)?)$/;
+const DOT_KEYWORDS = new Set(["node", "edge", "graph", "digraph", "subgraph", "strict"]);
+/**
+ * Whether a text is a DOT ID that needs no quotes: an alphanumeric identifier not starting with
+ * a digit, or a numeral, and not a keyword (case-insensitive).
+ * @param text - the text
+ * @returns true when the text can be written bare
+ */
+export function isBareDotId(text) {
+    if (DOT_KEYWORDS.has(text.toLowerCase())) {
+        return false;
+    }
+    return isDotIdentifier(text) || DOT_NUMERAL.test(text);
+}
+/**
+ * Whether a text is a DOT identifier: a letter, underscore or any character of code 128 and
+ * above, followed by letters, digits, underscores or such characters.
+ * @param text - the text
+ * @returns true for a bare identifier
+ */
+function isDotIdentifier(text) {
+    if (text.length === 0) {
+        return false;
+    }
+    for (let i = 0; i < text.length; i++) {
+        const c = text.charCodeAt(i);
+        const letter = (c >= 65 && c <= 90) || (c >= 97 && c <= 122) || c === 95 || c >= 128;
+        const digit = c >= 48 && c <= 57;
+        if (!letter && (i === 0 || !digit)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Whether a text can be written as a DOT ID at all. Graphviz's scanner consumes a backslash pair
+ * `\\` as one unit and `\"` as an escaped quote, left to right, so a backslash that precedes a
+ * double quote or ends the text cannot be written: the written `\\"` reads as a pair and a closing
+ * quote, and a trailing backslash escapes the closing quote. Every other text is writable;
+ * quoteDotId() writes it.
+ * @param text - the id, name or value text
+ * @returns true when quoteDotId(text) reads back as `text`
+ */
+export function isWritableDotText(text) {
+    return !text.endsWith("\\") && !text.includes('\\"');
+}
+/**
+ * Write a DOT ID: bare when the grammar allows, otherwise double-quoted with `"` escaped as `\"`.
+ * In DOT quoted strings the dyad `\"` is the only escape; every other character, a backslash and
+ * a raw line break included, is kept as written, so nothing else is rewritten. A text ending in a
+ * backslash has no DOT spelling (isWritableDotText); the caller refuses it before writing.
+ * @param text - the id or label text
+ * @returns the DOT ID
+ */
+export function quoteDotId(text) {
+    if (isBareDotId(text)) {
+        return text;
+    }
+    return `"${text.replace(/"/g, '\\"')}"`;
+}
+/**
+ * Write a set CSV cell per RFC 4180: quoted with `"` doubled when the text contains the
+ * delimiter, a quote, a CR or LF, or leading / trailing whitespace; bare otherwise. The empty
+ * string is written as the quoted empty cell `""`, so the importers can tell a set empty string
+ * (and an empty-string node id, legal under design section 4.1) from an unset cell, which every
+ * exporter writes as nothing between the delimiters.
+ * @param text - the cell text of a set cell
+ * @param delimiter - the field delimiter (default ",")
+ * @returns the cell as written
+ */
+export function quoteCsvCell(text, delimiter = ",") {
+    if (text.length === 0) {
+        return '""';
+    }
+    if (!text.includes(delimiter) &&
+        !text.includes('"') &&
+        !text.includes("\n") &&
+        !text.includes("\r") &&
+        text === text.trim()) {
+        return text;
+    }
+    return `"${text.replace(/"/g, '""')}"`;
+}
+/**
+ * Whether a text can be a Pajek label: Pajek has no escape mechanism inside its double-quoted
+ * labels, so a text containing a double quote, a CR or an LF cannot be written.
+ * @param text - the label text
+ * @returns true when quotePajekLabel() can write it
+ */
+export function isPajekLabel(text) {
+    return !text.includes('"') && !text.includes("\n") && !text.includes("\r");
+}
+/**
+ * Write a Pajek label: bare when it is a single run of non-space, non-quote characters, otherwise
+ * double-quoted. E_UNSUPPORTED (reason "pajek label") for a text isPajekLabel() rejects; the
+ * exporter's check() counts those.
+ * @param text - the label text
+ * @returns the label as written
+ */
+export function quotePajekLabel(text) {
+    if (!isPajekLabel(text)) {
+        throw new GraphFormatError("E_UNSUPPORTED", "a Pajek label cannot contain a double quote or a line break", {
+            reason: "pajek label",
+            value: text,
+        });
+    }
+    if (text.length > 0 && !/[\s"]/.test(text)) {
+        return text;
+    }
+    return `"${text}"`;
+}
+//# sourceMappingURL=escape.js.map

package/dist/src/common/escape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape.js","sourceRoot":"","sources":["../../../src/common/escape.ts"],"names":[],"mappings":"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"}

package/dist/src/common/export.d.ts

@@ -0,0 +1,249 @@
+/**
+ * The exporter-side machinery of design section 8.5: the ExportCapabilities table helper, the
+ * generic check() that turns capability gaps into LossNotes with shared codes, and id sanitising
+ * (`sanitizeIds: "error"` by default; an exporter never silently renames a node; "mangle" rewrites
+ * the ids the format cannot hold and hands the exporter the originals to write into its
+ * `graphty:originalId` attribute).
+ *
+ * Every exporter's check() calls checkCapabilities() first and appends its format-specific notes
+ * (design section 8.5 names W_GML_RECORD_NUMBER_TYPE and W_OPEN_INTERVAL); export() calls
+ * sanitizeIds() before writing anything.
+ */
+import { type Dtype, type GraphSnapshot, type NodeId } from "@graphty/graph-format";
+import { type ExportCapabilities, type LossNote } from "../types.js";
+import { type ResolvedExportOptions } from "./options.js";
+/** The shared LossNote codes of checkCapabilities(). */
+export declare const LOSS: Readonly<{
+    /** The format has no mixed direction; expanded pairs are written per onMixedDirection. */
+    MIXED_DIRECTION: "W_MIXED_DIRECTION";
+    /** The format has no mixed direction and onMixedDirection is "error": export() will throw E_DIRECTED. */
+    MIXED_DIRECTION_ERROR: "E_MIXED_DIRECTION";
+    /** Parallel edges in a format without them. */
+    MULTI_EDGES: "W_MULTI_EDGES";
+    /** Self-loops in a format without them. */
+    SELF_LOOPS: "W_SELF_LOOPS";
+    /** The format requires edge ids and the snapshot has none; canonical e0..e{E-1} are generated. */
+    EDGE_IDS_GENERATED: "W_EDGE_IDS_GENERATED";
+    /** The snapshot has an edge id column and the format cannot write one. */
+    EDGE_IDS_DROPPED: "W_EDGE_IDS_DROPPED";
+    /** Ids outside the format's charset are rewritten (sanitizeIds "mangle"). */
+    ID_MANGLED: "W_ID_MANGLED";
+    /** Ids outside the format's charset and sanitizeIds "error": export() will throw E_INVALID_ID. */
+    ID_CHARSET: "E_ID_CHARSET";
+    /** The format numbers nodes 1..N; ids that are not their 1-based index are kept as labels only. */
+    ID_RENUMBERED: "W_ID_RENUMBERED";
+    /** A column dtype the format does not keep as declared. */
+    DTYPE: "W_DTYPE_UNSUPPORTED";
+    /** A multi-component column in a format without strides. */
+    COMPONENTS: "W_COMPONENTS_FLATTENED";
+    /** A list column in a format without lists. */
+    LIST: "W_LIST_UNSUPPORTED";
+    /** A json column in a format without nested values. */
+    JSON: "W_JSON_UNSUPPORTED";
+    /** A declared default in a format without defaults. */
+    DEFAULT: "W_DEFAULT_DROPPED";
+    /** Declared options in a format without enumerations. */
+    OPTIONS: "W_OPTIONS_DROPPED";
+    /** A parent / parents column in a format without containment. */
+    HIERARCHY: "W_HIERARCHY_DROPPED";
+    /** A start / end / timestamp column in a format without temporal support. */
+    TEMPORAL: "W_TEMPORAL_DROPPED";
+    /** A `<column>.text` companion (design section 5.1) the format cannot carry. */
+    TEMPORAL_TEXT: "W_TEMPORAL_TEXT_DROPPED";
+    /** A role column the format has no slot for; written as a plain attribute, the role lost. */
+    ROLE: "W_ROLE_DROPPED";
+    /** A parents (multi-parent) column in a format with single containment only. */
+    PARENTS: "W_PARENTS_DROPPED";
+    /** A mutual pair written as two directed edges without the mutual mark. */
+    MUTUAL_EXPANDED: "W_MUTUAL_EXPANDED";
+    /** A mutual pair written as one undirected edge; the mark is lost and the pair reads back undirected. */
+    MUTUAL_AS_UNDIRECTED: "W_MUTUAL_AS_UNDIRECTED";
+    /** Node ids whose written text reads back as the other type under the importer's id rule. */
+    ID_TEXT_TYPE: "W_ID_TEXT_TYPE";
+    /** Two node ids share one written text; export() throws E_INVALID_ID. */
+    ID_TEXT_COLLISION: "E_ID_TEXT_COLLISION";
+    /** A plain column named like the importer's weight key reads back as THE weight. */
+    WEIGHT_KEY_CLASH: "W_WEIGHT_KEY_CLASH";
+    /** A role-less column whose written name the importer maps to a role. */
+    ROLE_ASSUMED: "W_ROLE_ASSUMED";
+    /** A role column written into the format's slot reads back under the importer's fixed name. */
+    COLUMN_NAME_CHANGED: "W_COLUMN_NAME_CHANGED";
+    /** A declared column whose every row is unset vanishes through a format without declarations. */
+    EMPTY_COLUMN: "W_EMPTY_COLUMN_DROPPED";
+    /** A string / dict column that reads back as the other storage class (the dictionary heuristic). */
+    STORAGE_CLASS: "W_STORAGE_CLASS_CHANGED";
+    /** An f64 column whose set values are all integral reads back as i32 through an untyped format. */
+    INTEGRAL_F64: "W_INTEGRAL_F64_AS_I32";
+    /** Text cells that read back as numbers or booleans under the 5.1 grammar. */
+    TEXT_INFERRED: "W_TEXT_INFERRED";
+    /** A string cell holding a character XML 1.0 forbids; export() throws E_COLUMN_TYPE. */
+    XML_ILLEGAL_CHAR: "E_XML_ILLEGAL_CHAR";
+    /** A dict column without declared options gains one on re-import. */
+    OPTIONS_GAINED: "W_OPTIONS_GAINED";
+    /** A spells column in a format without spells. */
+    SPELLS: "W_SPELLS_DROPPED";
+    /** Dynamic attribute values (extension tables) in a format without them. */
+    DYNAMIC_VALUES: "W_DYNAMIC_VALUES_DROPPED";
+    /** An open-interval column in a format without open intervals (design section 5.1). */
+    OPEN_INTERVAL: "W_OPEN_INTERVAL";
+    /** Graph-level attributes in a format without them. */
+    GRAPH_ATTRIBUTES: "W_GRAPH_ATTRIBUTES_DROPPED";
+    /** A position column in a format without positions. */
+    POSITIONS: "W_POSITIONS_DROPPED";
+    /** Visual columns in a format without them. */
+    VIZ: "W_VIZ_DROPPED";
+    /** An extension table the format cannot carry. */
+    EXTENSION_TABLE: "W_EXTENSION_TABLE_DROPPED";
+}>;
+/** The capabilities of a format that keeps nothing beyond plain topology; the base every exporter overrides. */
+export declare const NO_CAPABILITIES: ExportCapabilities;
+/**
+ * Build a capabilities table from the fields a format supports; every field left out is the
+ * conservative NO_CAPABILITIES value, so an exporter states what it keeps and nothing is assumed.
+ * @param supported - the fields the format supports
+ * @returns a frozen table
+ */
+export declare function capabilities(supported: Partial<ExportCapabilities>): ExportCapabilities;
+/**
+ * Format facts checkCapabilities() needs that the 12.4 table does not carry.
+ * Consumed by the per-format importers and exporters under src/formats.
+ * @public
+ */
+export interface CheckExtras {
+    /** Whether the format can write open intervals (GEXF 1.2 startopen / endopen); default false. */
+    readonly openIntervals?: boolean | undefined;
+    /**
+     * Whether the format carries the `<column>.text` companions of design section 5.1 (the lexical
+     * form of a temporal value); default false, and every companion is then reported as
+     * W_TEMPORAL_TEXT_DROPPED.
+     */
+    readonly temporalText?: boolean | undefined;
+    /**
+     * The dtype the format's importer gives a position column; an f32 / f64 position of the other
+     * dtype is reported as W_DTYPE_UNSUPPORTED because its values differ at the other precision.
+     * Undefined skips the check.
+     */
+    readonly positionDtype?: Dtype | undefined;
+    /**
+     * The roles beyond the structural, position, viz, hierarchy and temporal ones that the format
+     * has a slot for (`label`, `kind`, `labels`, `idSpace`, `sourcePort`, `targetPort`, ...); a
+     * column with any other role is written as a plain attribute and reported as W_ROLE_DROPPED.
+     * Defaults to none.
+     */
+    readonly roles?: ReadonlySet<string> | undefined;
+    /**
+     * Roles the format writes into a fixed slot whose importer reads them back under a fixed name;
+     * a role column named otherwise is reported as W_COLUMN_NAME_CHANGED (role -> the name the
+     * importer gives it). Defaults to none.
+     */
+    readonly roleNames?: Readonly<Record<string, string>> | undefined;
+}
+/**
+ * The generic pre-flight of design section 8.5: compare a snapshot with a format's capabilities
+ * and return one LossNote per gap, with the shared codes of LOSS. Format-specific notes are the
+ * exporter's to append.
+ * @param snapshot - the snapshot about to be exported
+ * @param caps - the exporter's capabilities
+ * @param options - the resolved common export options
+ * @param extras - format facts the capabilities table does not carry
+ * @returns the notes, empty when the export is exact
+ */
+export declare function checkCapabilities(snapshot: GraphSnapshot, caps: ExportCapabilities, options: ResolvedExportOptions, extras?: CheckExtras): LossNote[];
+/**
+ * The number of source edges that were undirected in a directed snapshot (the halves of an
+ * expanded pair count once; an expanded self-loop has no mirror and counts once).
+ * @param snapshot - the snapshot
+ * @returns the count; 0 for an undirected snapshot or one without the directed role
+ */
+export declare function countMixedEdges(snapshot: GraphSnapshot): number;
+/**
+ * The number of arcs that repeat the previous arc's target within a row (parallel edges), counted
+ * over the forward CSR; an undirected parallel edge is counted in both rows.
+ * @param snapshot - the snapshot
+ * @returns the count
+ */
+export declare function countParallelArcs(snapshot: GraphSnapshot): number;
+/**
+ * The id charsets of ExportCapabilities.
+ * Consumed by the per-format importers and exporters under src/formats.
+ * @public
+ */
+export type IdCharset = ExportCapabilities["idCharset"];
+/**
+ * The ids to write for every node after sanitising (design section 8.5).
+ * Consumed by the per-format importers and exporters under src/formats.
+ * @public
+ */
+export interface SanitizedIds {
+    /** The charset applied. */
+    readonly charset: IdCharset;
+    /** How many ids differ from the snapshot's. */
+    readonly changed: number;
+    /**
+     * The id to write for a node.
+     * @param index - the node index
+     * @returns the id as the format will read it back
+     */
+    idAt(index: number): NodeId;
+    /**
+     * Whether a node's written id differs from its original.
+     * @param index - the node index
+     * @returns true when the exporter must record the original
+     */
+    isChanged(index: number): boolean;
+    /**
+     * The original id of a node.
+     * @param index - the node index
+     * @returns the snapshot's id
+     */
+    originalAt(index: number): NodeId;
+}
+/**
+ * Whether a code point is an XML NameChar.
+ * @param cp - the code point
+ * @returns true when it may appear in an NMTOKEN
+ */
+export declare function isNameChar(cp: number): boolean;
+/**
+ * Whether a text is an XML NMTOKEN (one or more NameChars; GraphML node and edge ids).
+ * @param text - the text
+ * @returns true for a non-empty text of NameChars
+ */
+export declare function isNmtoken(text: string): boolean;
+/**
+ * Whether an id can be written unchanged under a charset.
+ * @param id - the id
+ * @param charset - the charset
+ * @returns true when the id needs no rewriting ("dense-1-based" is never true: see sanitizeIds)
+ */
+export declare function isRepresentableId(id: NodeId, charset: IdCharset): boolean;
+/**
+ * How many node ids a charset cannot hold as they are (for check()); under "dense-1-based" the
+ * ids that are not their own 1-based index.
+ * @param snapshot - the snapshot
+ * @param charset - the charset
+ * @returns the count
+ */
+export declare function countUnrepresentableIds(snapshot: GraphSnapshot, charset: IdCharset): number;
+/**
+ * Sanitise the node ids for a charset (design section 8.5). Under "error" any id the charset
+ * cannot hold is E_INVALID_ID (details.reason "charset") and nothing is written; under "mangle"
+ * such ids are rewritten deterministically and uniquely: NMTOKEN by replacing every other
+ * character with `_` (an empty result becomes `_`) and suffixing `_2`, `_3`... on collision;
+ * integer by the smallest unused non-negative integers in index order. "dense-1-based" always
+ * writes the 1-based index (Pajek numbers vertices; the exporter writes the original id as the
+ * label), which is a renumbering rather than a mangling, so it never throws under "error"; under
+ * "mangle" the exporter also writes the original id under its originalId attribute.
+ * @param snapshot - the snapshot
+ * @param charset - the charset
+ * @param mode - the resolved sanitizeIds option
+ * @returns the ids to write
+ */
+export declare function sanitizeIds(snapshot: GraphSnapshot, charset: IdCharset, mode: "error" | "mangle"): SanitizedIds;
+/**
+ * Rewrite a text as an NMTOKEN: every character that is not a NameChar becomes `_`.
+ * @param text - the text
+ * @returns a non-empty NMTOKEN
+ */
+export declare function mangleNmtoken(text: string): string;
+//# sourceMappingURL=export.d.ts.map

package/dist/src/common/export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../../src/common/export.ts"],"names":[],"mappings":"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"}