@graphty/graph-io 0.0.0 → 0.2.0

package/dist/src/common/direction.js

@@ -0,0 +1,370 @@
+/**
+ * Direction resolution through the sink (design sections 3.6 and 8.4, decision D-DIR): the
+ * importer reads the file's header direction, calls `sink.setDirected()` once before the first
+ * edge, then pushes every edge as it is read. Mixed files are handled per `onMixedDirection`:
+ *
+ * - "expand" (default): an undirected edge into a directed sink becomes two logical edges linked
+ *   by the `graphty.pair` column with `graphty.directed` = false on both halves; a directed edge
+ *   into an undirected sink triggers ONE `setDirected(true, { expand: true })`, after which the
+ *   builder has expanded everything pushed so far and the importer continues in directed mode.
+ * - "directed" / "undirected": every edge is treated that way (the distinction is dropped and
+ *   reported once, with the count).
+ * - "error": the first edge whose direction differs from the sink's aborts the import.
+ *
+ * A locked or non-empty sink wins over the file (design section 8.4 precedence): a refused
+ * `setDirected` is recorded as a coercion issue and the importer continues with `sink.directed`,
+ * expanding every edge that differs. A GEXF `mutual` edge expands like an undirected one with the
+ * additional `graphty.mutual` role column set on its primary half.
+ *
+ * The reserved columns are declared with exactly the builder's own declarations so that a sink the
+ * builder already expanded hands back the existing handles.
+ */
+import { GraphFormatError, INVALID_INDEX, } from "@graphty/graph-format";
+import { DIRECTION_FORCED_CODE, DIRECTION_REFUSED_CODE, MIXED_DIRECTION_CODE } from "./codes.js";
+/** The name of the bool edge column marking source-directed edges (design section 3.6). */
+export const DIRECTED_COLUMN = "graphty.directed";
+/** The name of the u32 edge column pairing the halves of an expanded edge (design section 3.6). */
+export const PAIR_COLUMN = "graphty.pair";
+/** The name of the bool edge column marking GEXF mutual edges (design section 3.6). */
+export const MUTUAL_COLUMN = "graphty.mutual";
+export { DIRECTION_FORCED_CODE, DIRECTION_REFUSED_CODE, MIXED_DIRECTION_CODE };
+const DIRECTED_DECL = { name: DIRECTED_COLUMN, dtype: "bool", role: "directed" };
+const PAIR_DECL = { name: PAIR_COLUMN, dtype: "u32", role: "pair", refersTo: "edge" };
+const MUTUAL_DECL = { name: MUTUAL_COLUMN, dtype: "bool", role: "mutual" };
+/**
+ * Pushes edges into a sink while resolving direction per design section 8.4. One instance per
+ * import call; `setHeader()` before the first `addEdge()`.
+ */
+export class DirectionResolver {
+    /**
+     * Create a resolver.
+     * @param sink - the sink edges are pushed into
+     * @param report - the report issues are recorded in
+     * @param policy - the resolved onMixedDirection option
+     */
+    constructor(sink, report, policy) {
+        this.directedHandle = INVALID_INDEX;
+        this.pairHandle = INVALID_INDEX;
+        this.mutualHandle = INVALID_INDEX;
+        /** The first edge index this resolver pushed, for the backfill of graphty.directed; -1 before the first. */
+        this.firstEdge = -1;
+        /** The next edge index this resolver expects to receive (contiguity between compactions, I16). */
+        this.nextEdge = -1;
+        this.forcedCount = 0;
+        this.headerSet = false;
+        this.mirrorOfLast = INVALID_INDEX;
+        this.sink = sink;
+        this.report = report;
+        this.policy = policy;
+    }
+    /**
+     * The sink's current direction.
+     * @returns true when directed
+     */
+    get directed() {
+        return this.sink.directed;
+    }
+    /**
+     * Whether the reserved direction columns exist (the sink holds expanded edges).
+     * @returns true once graphty.pair was declared or adopted
+     */
+    get expanded() {
+        return this.pairHandle !== INVALID_INDEX;
+    }
+    /**
+     * Rule 1 of design section 8.4: set the sink's direction from the file's header (or the
+     * `defaultDirected` option for a file that declares none) before the first edge. Under the
+     * "directed" / "undirected" policies the policy's direction is used instead and the difference
+     * is reported. A refusal (E_DIRECTED: locked, or a non-empty directed sink for an undirected
+     * header) is recorded as a coercion issue and the sink's direction stands; a non-empty unlocked
+     * undirected sink with a directed header is expanded in place.
+     * @param headerDirected - the direction the file declares (or the default)
+     * @param where - the line of the header, when known
+     */
+    setHeader(headerDirected, where) {
+        this.headerSet = true;
+        let wanted = headerDirected;
+        if (this.policy === "directed" || this.policy === "undirected") {
+            wanted = this.policy === "directed";
+            if (wanted !== headerDirected) {
+                this.report.warning("coercion", DIRECTION_FORCED_CODE, `the file declares ${direction(headerDirected)} edges; read as ${direction(wanted)} per onMixedDirection`, { line: where?.line ?? null });
+            }
+        }
+        const { sink } = this;
+        if (sink.directed === wanted) {
+            this.adoptExisting();
+            return;
+        }
+        try {
+            if (wanted && sink.edgeCount > 0 && !sink.directedLocked) {
+                const before = sink.edgeCount;
+                sink.setDirected(true, { expand: true });
+                this.adoptExpansionColumns();
+                this.report.counts.expandedMixed += before;
+            }
+            else {
+                sink.setDirected(wanted);
+            }
+        }
+        catch (err) {
+            if (!(err instanceof GraphFormatError) || err.code !== "E_DIRECTED") {
+                throw err;
+            }
+            this.report.warning("coercion", DIRECTION_REFUSED_CODE, `the file is ${direction(wanted)} but the sink is ${direction(sink.directed)} (${reasonOf(err)}); read as ${direction(sink.directed)}`, { line: where?.line ?? null });
+        }
+        this.adoptExisting();
+    }
+    /**
+     * Pick up reserved columns a caller's sink already holds (an earlier expansion), so every edge
+     * pushed from now on gets its graphty.directed value.
+     */
+    adoptExisting() {
+        if (this.pairHandle === INVALID_INDEX && this.sink.edgeColumn(PAIR_COLUMN) !== INVALID_INDEX) {
+            this.adoptExpansionColumns();
+        }
+    }
+    /**
+     * The mirror half of the edge most recently pushed by addEdge(), when it was expanded into a
+     * pair; INVALID_INDEX otherwise. An importer that learns an edge's weight after pushing it
+     * (a GEXF attvalue) sets it on both halves.
+     * @returns the mirror's logical index, or INVALID_INDEX
+     */
+    get lastMirror() {
+        return this.mirrorOfLast;
+    }
+    /**
+     * Rule 2 of design section 8.4: push one source edge. An edge whose direction equals the
+     * sink's is one addEdge; one that differs is expanded, forced or refused per the policy.
+     * @param source - the source id
+     * @param target - the target id
+     * @param kind - the edge's direction in the file
+     * @param weight - the weight, or undefined when the file gives none
+     * @param where - the line and element, for issues
+     * @returns the logical index of the (primary) edge
+     */
+    addEdge(source, target, kind, weight, where) {
+        if (!this.headerSet) {
+            throw new GraphFormatError("E_DIRECTED", "DirectionResolver.setHeader() must run before the first edge", {
+                reason: "header not set",
+            });
+        }
+        const { sink } = this;
+        this.mirrorOfLast = INVALID_INDEX;
+        const edgeDirected = kind !== "undirected";
+        if (edgeDirected === sink.directed && kind !== "mutual") {
+            const e = sink.addEdge(source, target, weight);
+            this.track(e);
+            if (this.directedHandle !== INVALID_INDEX) {
+                sink.setEdgeValue(this.directedHandle, e, edgeDirected);
+            }
+            return e;
+        }
+        switch (this.policy) {
+            case "directed":
+            case "undirected": {
+                // the sink's direction is the policy's (or a locked sink's); the edge is pushed as the sink's kind
+                this.forcedCount++;
+                this.report.warnOnce("coercion", DIRECTION_FORCED_CODE, `${kind} edges read as ${direction(sink.directed)} per onMixedDirection`, where);
+                const e = sink.addEdge(source, target, weight);
+                this.track(e);
+                if (this.directedHandle !== INVALID_INDEX) {
+                    sink.setEdgeValue(this.directedHandle, e, sink.directed);
+                }
+                return e;
+            }
+            case "error":
+                this.report.error("validation-error", MIXED_DIRECTION_CODE, `${kind} edge in a ${direction(sink.directed)} graph (onMixedDirection: "error")`, where);
+                throw this.report.abort("mixed direction refused", { code: MIXED_DIRECTION_CODE });
+            case "expand":
+                return this.expand(source, target, kind, weight, where);
+            default: {
+                const name = this.policy;
+                throw new GraphFormatError("E_UNSUPPORTED", `unknown onMixedDirection ${name}`, {
+                    option: "onMixedDirection",
+                    found: name,
+                });
+            }
+        }
+    }
+    /**
+     * How many edges were pushed with a direction other than their own under the forcing policies.
+     * @returns the count
+     */
+    get forced() {
+        return this.forcedCount;
+    }
+    /**
+     * Expand one edge that differs from the sink's direction.
+     * @param source - the source id
+     * @param target - the target id
+     * @param kind - the edge's direction in the file
+     * @param weight - the weight, or undefined
+     * @param where - the line and element, for issues
+     * @returns the primary edge index
+     */
+    expand(source, target, kind, weight, where) {
+        const { sink } = this;
+        if (!sink.directed) {
+            // a directed (or mutual) edge into an undirected sink: expand the sink once
+            try {
+                const before = sink.edgeCount;
+                sink.setDirected(true, { expand: true });
+                this.adoptExpansionColumns();
+                this.report.counts.expandedMixed += before;
+            }
+            catch (err) {
+                if (!(err instanceof GraphFormatError) || err.code !== "E_DIRECTED") {
+                    throw err;
+                }
+                this.report.error("coercion", DIRECTION_REFUSED_CODE, `${direction(true)} edge in a locked ${direction(false)} sink cannot be expanded`, where);
+                throw this.report.abort("the sink refused the expansion to directed", {
+                    code: DIRECTION_REFUSED_CODE,
+                    reason: err.details.reason,
+                });
+            }
+            if (kind === "directed") {
+                const e = sink.addEdge(source, target, weight);
+                this.track(e);
+                sink.setEdgeValue(this.directedHandle, e, true);
+                return e;
+            }
+        }
+        this.ensureExpansionColumns();
+        const first = sink.addEdge(source, target, weight);
+        this.track(first);
+        const mutual = kind === "mutual";
+        sink.setEdgeValue(this.directedHandle, first, mutual);
+        this.report.counts.expandedMixed++;
+        if (mutual) {
+            this.ensureMutualColumn();
+            sink.setEdgeValue(this.mutualHandle, first, true);
+        }
+        const u = sink.indexOf(source);
+        const v = sink.indexOf(target);
+        if (u === v) {
+            // an undirected self-loop is one arc (I7); the builder does not mirror it either
+            return first;
+        }
+        const mirror = sink.addEdge(target, source, weight);
+        this.track(mirror);
+        this.mirrorOfLast = mirror;
+        sink.setEdgeValue(this.directedHandle, mirror, mutual);
+        sink.setEdgeValue(this.pairHandle, first, mirror);
+        sink.setEdgeValue(this.pairHandle, mirror, first);
+        return first;
+    }
+    /**
+     * Note an edge index this resolver pushed, for the backfill of graphty.directed.
+     * @param e - the edge index
+     */
+    track(e) {
+        if (this.firstEdge < 0) {
+            this.firstEdge = e;
+        }
+        this.nextEdge = e + 1;
+    }
+    /**
+     * Pick up the reserved columns the builder wrote during its own expansion.
+     */
+    adoptExpansionColumns() {
+        this.directedHandle = this.sink.declareEdgeColumn(DIRECTED_DECL);
+        this.pairHandle = this.sink.declareEdgeColumn(PAIR_DECL);
+    }
+    /**
+     * Declare the reserved columns on first use in a directed sink and backfill graphty.directed
+     * = true for every edge this resolver pushed so far (they were directed in the source).
+     */
+    ensureExpansionColumns() {
+        if (this.pairHandle !== INVALID_INDEX) {
+            return;
+        }
+        this.directedHandle = this.sink.declareEdgeColumn(DIRECTED_DECL);
+        this.pairHandle = this.sink.declareEdgeColumn(PAIR_DECL);
+        if (this.firstEdge >= 0) {
+            for (let e = this.firstEdge; e < this.nextEdge; e++) {
+                this.sink.setEdgeValue(this.directedHandle, e, true);
+            }
+        }
+    }
+    /** Declare graphty.mutual on first use. */
+    ensureMutualColumn() {
+        if (this.mutualHandle === INVALID_INDEX) {
+            this.mutualHandle = this.sink.declareEdgeColumn(MUTUAL_DECL);
+        }
+    }
+}
+/**
+ * The reason of a refused setDirected(), for messages.
+ * @param err - the E_DIRECTED error
+ * @returns details.reason when it is a string, "refused" otherwise
+ */
+function reasonOf(err) {
+    const { reason } = err.details;
+    return typeof reason === "string" ? reason : "refused";
+}
+/**
+ * The word for a direction, for messages.
+ * @param directed - the direction
+ * @returns "directed" or "undirected"
+ */
+function direction(directed) {
+    return directed ? "directed" : "undirected";
+}
+/**
+ * Build the pair-folding view of a snapshot (one pass over the role columns).
+ * @param snapshot - the snapshot
+ * @param options - the per-format choice
+ * @returns the view
+ */
+export function pairFolding(snapshot, options = {}) {
+    const foldMutual = options.foldMutual ?? false;
+    const directedColumn = roleColumn(snapshot.edges.byRole("directed"), "bool");
+    const pairColumn = roleColumn(snapshot.edges.byRole("pair"), "u32");
+    const mutualColumn = roleColumn(snapshot.edges.byRole("mutual"), "bool");
+    const { edgeCount } = snapshot;
+    const mateOf = (e) => {
+        if (pairColumn === null || !pairColumn.isSet(e)) {
+            return INVALID_INDEX;
+        }
+        const mate = pairColumn.value(e);
+        return typeof mate === "number" && mate !== INVALID_INDEX ? mate : INVALID_INDEX;
+    };
+    const sourceDirected = (e) => directedColumn === null || !directedColumn.isSet(e) || directedColumn.value(e) === true;
+    const isMutual = (e) => {
+        if (mutualColumn === null) {
+            return false;
+        }
+        if (mutualColumn.isSet(e) && mutualColumn.value(e) === true) {
+            return true;
+        }
+        const mate = mateOf(e);
+        return mate !== INVALID_INDEX && mutualColumn.isSet(mate) && mutualColumn.value(mate) === true;
+    };
+    const folded = (e) => {
+        const mate = mateOf(e);
+        if (mate === INVALID_INDEX || mate >= e) {
+            return false;
+        }
+        // an undirected pair always folds; a mutual pair (directed on both halves) folds on request
+        return !sourceDirected(e) || (foldMutual && isMutual(e));
+    };
+    let mutualCount = 0;
+    if (mutualColumn !== null) {
+        for (let e = 0; e < edgeCount; e++) {
+            if (mutualColumn.isSet(e) && mutualColumn.value(e) === true && mateOf(e) > e) {
+                mutualCount++;
+            }
+        }
+    }
+    return { expanded: pairColumn !== null, mutualCount, folded, mateOf, sourceDirected, isMutual };
+}
+/**
+ * A role column when it has the dtype the role requires, else null.
+ * @param column - the column, or null
+ * @param dtype - the required dtype
+ * @returns the column or null
+ */
+function roleColumn(column, dtype) {
+    return column !== null && column.dtype === dtype ? column : null;
+}
+//# sourceMappingURL=direction.js.map

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

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

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

@@ -0,0 +1,92 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function escapeXmlText(text: string): string;
+/**
+ * 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 declare function escapeXmlAttribute(text: string): string;
+/**
+ * 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 declare function quoteGmlString(text: string): string;
+/**
+ * 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 declare function decodeGmlString(body: string): string;
+/**
+ * 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 declare function isBareDotId(text: string): boolean;
+/**
+ * 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 declare function isWritableDotText(text: string): boolean;
+/**
+ * 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 declare function quoteDotId(text: string): string;
+/**
+ * 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 declare function quoteCsvCell(text: string, delimiter?: string): string;
+/**
+ * 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 declare function isPajekLabel(text: string): boolean;
+/**
+ * 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 declare function quotePajekLabel(text: string): string;
+//# sourceMappingURL=escape.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"escape.d.ts","sourceRoot":"","sources":["../../../src/common/escape.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAkBH;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKlD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKvD;AAgBD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAcnD;AAKD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAUpD;AAKD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAKjD;AAuBD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK/C;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAM,GAAG,MAAM,CAclE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWpD"}