@graphty/graph-io 0.3.25 → 0.3.27

package/src/formats/cx/index.ts

@@ -1,7 +1,8 @@
 /**
- * The `@graphty/graph-io/cx` subpath (design/graph-io/cytoscape-and-obo/design.md section 1.2):
- * the CX version 1 importer with its option type and code table. CX1 is read only: CX2 is what
- * NDEx and Cytoscape write today, and `@graphty/graph-io/cx2` writes it.
+ * The `@graphty/graph-io/cx` subpath: the CX version 1 importer and exporter with their option
+ * types and code tables.
+ * @module @graphty/graph-io/cx
  */
 
+export { CX_CAPABILITIES, CX_LOSS, cxExporter, type CxExportOptions } from "./exporter.js";
 export { CX_ISSUE, cxImporter, type CxImportOptions } from "./importer.js";

package/src/formats/cx2/exporter.ts

@@ -13,26 +13,44 @@
  * the infinities as null (W_CX2_NONFINITE_AS_NULL), and the generic notes of checkCapabilities().
  */
 
-import { type Column, GraphFormatError, type GraphSnapshot, type NodeId } from "@graphty/graph-format";
-
+import { type Column, GraphFormatError, type GraphSnapshot } from "@graphty/graph-format";
+
+import {
+    aspectBlock,
+    declaredType,
+    directionNotes,
+    nonFinitePositions,
+    planEdgeIds,
+    planNodeIds,
+    stringify,
+    type WrittenIds,
+} from "../../common/cx-export.js";
 import { type PairFolding, pairFolding } from "../../common/direction.js";
 import { capabilities, checkCapabilities, LOSS } from "../../common/export.js";
 import { isRecord, POSITION_COLUMN } from "../../common/json-elements.js";
 import { type ResolvedExportOptions, resolveExportOptions } from "../../common/options.js";
+import { plural } from "../../common/plural.js";
 import { type ExplicitWeights, explicitWeights } from "../../common/weights.js";
 import { encodeChunks, joinText } from "../../common/writer.js";
 import { type CommonExportOptions, type ExportCapabilities, type GraphExporter, type LossNote } from "../../types.js";
 import { BYPASS_NAMESPACE, CX2_FORMAT, cx2Type, ORIGINAL_ID_ATTRIBUTE } from "./importer.js";
 
-/** The format-specific options of the CX2 exporter: none yet. */
-export type Cx2ExportOptions = Readonly<Record<never, never>>;
+/**
+ * The options of the CX2 exporter: the common export options; it has none of its own.
+ * @category Built-in formats
+ */
+export type Cx2ExportOptions = CommonExportOptions;
 
 /**
- * The loss notes the CX2 exporter's check() returns (design section 1.3), by name. A key is the
+ * The loss notes the CX2 exporter's check() returns, by name. A key is the
  * code without its severity and format prefixes.
+ * @category Built-in formats
  */
 export const CX2_LOSS = Object.freeze({
-    /** Every edge is written directed: an undirected snapshot, or the undirected pairs of a mixed one. */
+    /**
+     * Every edge is written as directed, so an undirected graph, or the undirected edges of a mixed graph, read back
+     * as directed.
+     */
     UNDIRECTED_AS_DIRECTED: "W_CX2_UNDIRECTED_AS_DIRECTED",
     /** A nested (json) column is written as a string attribute holding its JSON text. */
     JSON_AS_STRING: "W_CX2_JSON_AS_STRING",
@@ -40,17 +58,26 @@ export const CX2_LOSS = Object.freeze({
     NONFINITE_AS_NULL: "W_CX2_NONFINITE_AS_NULL",
     /** A mutual pair is written as two directed edges without its mark. */
     MUTUAL_EXPANDED: LOSS.MUTUAL_EXPANDED,
-    /** A plain edge column named like the weight key reads back as THE weight (or is skipped when weights are written). */
+    /**
+     * An attribute without the weight role is named like the key weights are written under; it reads back as the edge
+     * weight, or is not written when the graph has weights of its own.
+     */
     WEIGHT_KEY_CLASH: LOSS.WEIGHT_KEY_CLASH,
     /** A parent / parents column: CX2 has no containment. */
     HIERARCHY_DROPPED: LOSS.HIERARCHY,
     /** A start / end / timestamp column: CX2 has no time. */
     TEMPORAL_DROPPED: LOSS.TEMPORAL,
-    /** A role column written as a plain attribute. */
+    /** An attribute with a role the format has no place for is written as a plain attribute; the role is lost. */
     ROLE_DROPPED: LOSS.ROLE,
-    /** A dtype CX2 declares as another (f32 as double, u32 as long, dict as string, ...). */
+    /**
+     * An attribute type CX2 stores as another (a 32-bit float as double, an unsigned integer as long, a dictionary as
+     * string); it reads back with that type.
+     */
     DTYPE_UNSUPPORTED: LOSS.DTYPE,
-    /** Node ids that are not integers under the default sanitizeIds "error": export() throws E_INVALID_ID. */
+    /**
+     * Node ids the format cannot write, under `sanitizeIds: "error"`; the save fails with E_INVALID_ID. Pass
+     * `sanitizeIds: "mangle"` to rewrite them.
+     */
     ID_CHARSET: LOSS.ID_CHARSET,
     /** Node ids that are not integers under sanitizeIds "mangle": renumbered, originals kept. */
     ID_MANGLED: LOSS.ID_MANGLED,
@@ -59,10 +86,11 @@ export const CX2_LOSS = Object.freeze({
 });
 
 /**
- * What CX2 keeps (design section 1.3): directed multigraphs with self-loops, integer node ids,
+ * What CX2 keeps: directed multigraphs with self-loops, integer node ids,
  * required integer edge ids, declared string / double / integer / boolean columns and lists of
  * them, declared defaults, network attributes and the position role. f32, u32, u8 and dict columns
  * are written as the nearest declared type and read back as it.
+ * @category Built-in formats
  */
 export const CX2_CAPABILITIES: ExportCapabilities = capabilities({
     mixedDirection: false,
@@ -129,104 +157,6 @@ const CORE_ASPECTS: ReadonlySet<string> = new Set([
 /** The weight attribute name. */
 const WEIGHT_ATTRIBUTE = "weight";
 
-/**
- * The prefix of a string that stands for a raw number literal in the output: -0 (which
- * JSON.stringify writes as 0) and an integer id beyond 2^53 (kept as its digits).
- */
-const RAW = `${String.fromCharCode(0)}cx2:`;
-
-/** A raw literal as JSON.stringify writes it, to be unquoted. */
-const RAW_JSON = /"\\u0000cx2:(-?[0-9]+)"/g;
-
-/** An integer literal beyond 2^53 as text: a CX2 id graph-io keeps as its digits. */
-const BIG_INTEGER_TEXT = /^-?[1-9][0-9]{15,}$/;
-
-/** The node ids as written: the original, a renumbered one, or a raw big integer. */
-interface WrittenIds {
-    /** How many ids were renumbered (sanitizeIds "mangle"). */
-    readonly changed: number;
-    /** The written id of node i (a number, or a RAW string for a big integer). */
-    idAt(i: number): NodeId;
-    /** Whether node i was renumbered. */
-    isChanged(i: number): boolean;
-    /** The original id of node i. */
-    originalAt(i: number): NodeId;
-}
-
-/**
- * Whether an id can be written as a CX2 id unchanged: a safe integer, or the digits of an integer
- * beyond 2^53 (the CX2 importer reads those back as the same digits).
- * @param id - the id
- * @returns true when writable
- */
-function writableId(id: NodeId): boolean {
-    return typeof id === "number"
-        ? Number.isSafeInteger(id)
-        : BIG_INTEGER_TEXT.test(id) && !Number.isSafeInteger(Number(id));
-}
-
-/**
- * The written node ids; under "error" an id that is not writable throws E_INVALID_ID, under
- * "mangle" it gets the next unused integer.
- * @param snapshot - the snapshot
- * @param mode - the sanitizeIds option
- * @returns the ids
- */
-function writtenIds(snapshot: GraphSnapshot, mode: "error" | "mangle"): WrittenIds {
-    const { ids } = snapshot;
-    const bad: number[] = [];
-    const used = new Set<number>();
-    for (let i = 0; i < ids.size; i++) {
-        const id = ids.idOf(i);
-        if (!writableId(id)) {
-            bad.push(i);
-        } else if (typeof id === "number") {
-            used.add(id);
-        }
-    }
-    if (bad.length > 0 && mode === "error") {
-        const first = ids.idOf(bad[0]);
-        throw new GraphFormatError(
-            "E_INVALID_ID",
-            `${bad.length} node id(s) cannot be written as CX2 integers (first: ${JSON.stringify(first)} at index ${bad[0]}); pass sanitizeIds: "mangle" to rewrite them`,
-            { reason: "charset", charset: "integer", count: bad.length, index: bad[0] },
-        );
-    }
-    const renumbered = new Map<number, number>();
-    let next = 0;
-    for (const i of bad) {
-        while (used.has(next)) {
-            next++;
-        }
-        used.add(next);
-        renumbered.set(i, next);
-    }
-    return {
-        changed: bad.length,
-        idAt: (i: number): NodeId => {
-            const id = renumbered.get(i) ?? ids.idOf(i);
-            return typeof id === "string" ? `${RAW}${id}` : id;
-        },
-        isChanged: (i: number): boolean => renumbered.has(i),
-        originalAt: (i: number): NodeId => ids.idOf(i),
-    };
-}
-
-/**
- * How many node ids are not writable unchanged.
- * @param snapshot - the snapshot
- * @returns the count
- */
-function unwritableIds(snapshot: GraphSnapshot): number {
-    let count = 0;
-    for (let i = 0; i < snapshot.ids.size; i++) {
-        if (!writableId(snapshot.ids.idOf(i))) {
-            count++;
-        }
-    }
-    return count;
-}
-
 /** One attribute column as it will be written. */
 interface AttributePlan {
     readonly column: Column;
@@ -277,62 +207,6 @@ function isZ(column: Column): boolean {
     return column.meta.extra.cytoscape === "z";
 }
 
-/**
- * The CX2 type of a scalar dtype.
- * @param dtype - the dtype
- * @param longOrigin - whether the source declared the column long
- * @returns the type text
- */
-function scalarType(dtype: string, longOrigin: boolean): string {
-    switch (dtype) {
-        case "f64":
-            return longOrigin ? "long" : "double";
-        case "f32":
-            return "double";
-        case "i32":
-        case "u8":
-            return "integer";
-        case "u32":
-            return "long";
-        case "bool":
-            return "boolean";
-        default:
-            return "string";
-    }
-}
-
-/**
- * Whether every set value of an f64 column is integral (so a declared long stays long).
- * @param column - the column
- * @returns true when every set value is a safe integer
- */
-function allIntegral(column: Column): boolean {
-    for (let i = 0; i < column.length; i++) {
-        if (column.isSet(i) && !Number.isSafeInteger(column.value(i))) {
-            return false;
-        }
-    }
-    return true;
-}
-
-/**
- * The declared type of a column.
- * @param column - the column
- * @returns the CX2 type text
- */
-function declaredType(column: Column): string {
-    const { meta } = column;
-    const origin = meta.origin?.type ?? null;
-    const longOrigin = origin !== null && /long$/.test(origin) && (meta.dtype !== "f64" || allIntegral(column));
-    if (meta.dtype === "list") {
-        return meta.itemDtype === null || meta.itemDtype === "json"
-            ? "string"
-            : `list_of_${scalarType(meta.itemDtype, longOrigin)}`;
-    }
-    // a multi-component column (a color, a 3D vector) is written as a list of its components
-    return meta.components > 1 ? `list_of_${scalarType(meta.dtype, false)}` : scalarType(meta.dtype, longOrigin);
-}
-
 /**
  * Count the non-finite numbers of a column.
  * @param column - the column
@@ -355,7 +229,7 @@ function nonFiniteCount(column: Column): number {
             if ((value as readonly number[]).some((v) => !Number.isFinite(v))) {
                 count++;
             }
-        } else if (!Number.isFinite(value as number)) {
+        } else if (!Number.isFinite(value)) {
             count++;
         }
     }
@@ -439,27 +313,12 @@ function plan(snapshot: GraphSnapshot, common: ResolvedExportOptions): Plan {
     }
 
     const folding = pairFolding(snapshot);
-    directionNotes(snapshot, folding, common, note);
+    directionNotes(snapshot, folding, common, CX2_LOSS.UNDIRECTED_AS_DIRECTED, note);
 
-    const unwritable = unwritableIds(snapshot);
-    if (unwritable > 0) {
-        note(
-            common.sanitizeIds === "mangle" ? LOSS.ID_MANGLED : LOSS.ID_CHARSET,
-            common.sanitizeIds === "mangle"
-                ? `${unwritable} node id(s) that are not integers are renumbered; the originals are kept in the ${ORIGINAL_ID_ATTRIBUTE} attribute (restored by restoreMangledIds)`
-                : `${unwritable} node id(s) that are not integers; export() will throw unless sanitizeIds is "mangle"`,
-            null,
-            unwritable,
-        );
-    }
-    let ids: WrittenIds | null = null;
-    try {
-        ids = writtenIds(snapshot, common.sanitizeIds);
-    } catch (err) {
-        if (!(err instanceof GraphFormatError)) {
-            throw err;
-        }
-        fatal ??= err;
+    const planned = planNodeIds(snapshot, common, "CX2", ORIGINAL_ID_ATTRIBUTE, note);
+    const ids = planned instanceof GraphFormatError ? null : planned;
+    if (planned instanceof GraphFormatError) {
+        fatal ??= planned;
     }
 
     const weights = explicitWeights(snapshot);
@@ -513,22 +372,13 @@ function plan(snapshot: GraphSnapshot, common: ResolvedExportOptions): Plan {
     if (nonfinite > 0) {
         note(
             CX2_LOSS.NONFINITE_AS_NULL,
-            `${nonfinite} NaN or infinite value(s) cannot be written in CX2; written as null, they read back unset`,
+            `${nonfinite} NaN or infinite value${plural(nonfinite)} cannot be written in CX2; written as null, they read back unset`,
             null,
             nonfinite,
         );
     }
 
     const edgeIds = planEdgeIds(snapshot, note);
-    const idColumn = snapshot.edges.byRole("id");
-    if (idColumn !== null && idColumn.dtype !== "f64") {
-        note(
-            LOSS.DTYPE,
-            `edge id column "${idColumn.meta.name}" is ${idColumn.dtype}; CX2 edge ids are integers and read back as f64`,
-            idColumn.meta.name,
-            snapshot.edgeCount - idColumn.nullCount,
-        );
-    }
     const z = [...snapshot.nodes].find(isZ) ?? null;
     const positionZ = position !== null && z === null && position.meta.extra.sourceDims === 3;
     return {
@@ -550,139 +400,8 @@ function plan(snapshot: GraphSnapshot, common: ResolvedExportOptions): Plan {
     };
 }
 
-/**
- * The direction notes: every CX2 edge is directed, so an undirected snapshot (or the undirected
- * pairs of a mixed one, folded under onMixedDirection) is written directed, and a mutual pair as
- * two edges without its mark.
- * @param snapshot - the snapshot
- * @param folding - the pair folding
- * @param common - the resolved common options
- * @param note - records a note
- */
-function directionNotes(
-    snapshot: GraphSnapshot,
-    folding: PairFolding,
-    common: ResolvedExportOptions,
-    note: (code: string, message: string, column?: string | null, count?: number | null) => void,
-): void {
-    if (!snapshot.directed) {
-        note(
-            CX2_LOSS.UNDIRECTED_AS_DIRECTED,
-            `the snapshot is undirected; every edge is written as a directed CX2 edge (${snapshot.edgeCount} edge(s))`,
-            null,
-            snapshot.edgeCount,
-        );
-    } else if (common.onMixedDirection !== "error") {
-        let undirected = 0;
-        for (let e = 0; e < snapshot.edgeCount; e++) {
-            if (!folding.folded(e) && !folding.sourceDirected(e)) {
-                undirected++;
-            }
-        }
-        if (undirected > 0) {
-            note(
-                CX2_LOSS.UNDIRECTED_AS_DIRECTED,
-                `${undirected} undirected edge(s) are written as one directed edge each (a pair folded to its primary); CX2 has no undirected edge`,
-                null,
-                undirected,
-            );
-        }
-    }
-    if (folding.mutualCount > 0) {
-        note(
-            LOSS.MUTUAL_EXPANDED,
-            `${folding.mutualCount} mutual pair(s) are written as two directed edges; the mutual mark is lost`,
-            null,
-            folding.mutualCount,
-        );
-    }
-}
-
-/**
- * Count the positions with a non-finite x or y.
- * @param position - the position column
- * @returns the count
- */
-function nonFinitePositions(position: Column): number {
-    let count = 0;
-    for (let i = 0; i < position.length; i++) {
-        if (position.isSet(i)) {
-            const p = position.value(i) as ArrayLike<number>;
-            if (!Number.isFinite(p[0]) || !Number.isFinite(p[1])) {
-                count++;
-            }
-        }
-    }
-    return count;
-}
-
-/**
- * The edge ids to write: the id role column's values when they are distinct safe integers,
- * next unused integers for edges without one.
- * @param snapshot - the snapshot
- * @param note - records a note
- * @returns one id per edge
- */
-function planEdgeIds(
-    snapshot: GraphSnapshot,
-    note: (code: string, message: string, column?: string | null, count?: number | null) => void,
-): number[] {
-    const column = snapshot.edges.byRole("id");
-    const ids: (number | null)[] = new Array<number | null>(snapshot.edgeCount).fill(null);
-    const used = new Set<number>();
-    let generated = 0;
-    if (column !== null) {
-        for (let e = 0; e < snapshot.edgeCount; e++) {
-            const value = column.isSet(e) ? column.value(e) : undefined;
-            let n = NaN;
-            if (typeof value === "number") {
-                n = value;
-            } else if (typeof value === "string") {
-                n = Number(value);
-            }
-            if (Number.isSafeInteger(n) && !used.has(n)) {
-                ids[e] = n === 0 ? 0 : n;
-                used.add(n);
-            }
-        }
-    }
-    let next = 0;
-    const out: number[] = [];
-    for (let e = 0; e < snapshot.edgeCount; e++) {
-        let id = ids[e];
-        if (id === null) {
-            while (used.has(next)) {
-                next++;
-            }
-            id = next;
-            used.add(next);
-            generated++;
-        }
-        out.push(id);
-    }
-    if (column !== null && generated > 0) {
-        note(
-            LOSS.EDGE_IDS_GENERATED,
-            `${generated} edge(s) have no distinct integer id in "${column.meta.name}"; they are written with generated ids`,
-            column.meta.name,
-            generated,
-        );
-    }
-    return out;
-}
-
 // ============================================================ writing
 
-/**
- * The JSON text of a value, keeping -0.
- * @param value - the value
- * @returns the text
- */
-function stringify(value: unknown): string {
-    const text = JSON.stringify(value, (_key, v: unknown) => (Object.is(v, -0) ? `${RAW}-0` : v));
-    return text.includes("\\u0000cx2:") ? text.replace(RAW_JSON, "$1") : text;
-}
-
 /**
  * The value written for one cell.
  * @param p - the attribute plan
@@ -913,15 +632,17 @@ function* write(snapshot: GraphSnapshot, p: Plan): Generator<string, void, undef
  * @param aspect - the aspect name
  * @param count - its element count
  * @param element - the JSON text of element k
- * @yields the block's text
- * @returns nothing
+ * @returns the block's text parts
  */
-function* block(aspect: string, count: number, element: (k: number) => string): Generator<string, void, undefined> {
-    yield `{${JSON.stringify(aspect)}:[`;
-    for (let k = 0; k < count; k++) {
-        yield k === 0 ? `\n${element(k)}` : `,\n${element(k)}`;
-    }
-    yield "]},\n";
+function block(aspect: string, count: number, element: (k: number) => string): Generator<string, void, undefined> {
+    return aspectBlock(
+        aspect,
+        (function* elements(): Generator<string, void, undefined> {
+            for (let k = 0; k < count; k++) {
+                yield element(k);
+            }
+        })(),
+    );
 }
 
 /**
@@ -998,10 +719,12 @@ function bypassValues(columns: readonly Column[], row: number): Record<string, u
 }
 
 /**
- * The CX2 exporter plugin (design section 1.3).
+ * The CX2 exporter plugin.
+ * @category Built-in formats
  */
 export const cx2Exporter: GraphExporter<Cx2ExportOptions> = Object.freeze({
     format: CX2_FORMAT,
+    options: Object.freeze([]),
     capabilities: CX2_CAPABILITIES,
 
     /**
@@ -1010,7 +733,7 @@ export const cx2Exporter: GraphExporter<Cx2ExportOptions> = Object.freeze({
      * @param options - the common options
      * @returns the notes, empty when the export is exact
      */
-    check(snapshot: GraphSnapshot, options?: Cx2ExportOptions & CommonExportOptions): readonly LossNote[] {
+    check(snapshot: GraphSnapshot, options?: Cx2ExportOptions): readonly LossNote[] {
         return Object.freeze([...plan(snapshot, resolveExportOptions(options)).notes]);
     },
 
@@ -1020,7 +743,7 @@ export const cx2Exporter: GraphExporter<Cx2ExportOptions> = Object.freeze({
      * @param options - the common options
      * @returns the chunks
      */
-    export(snapshot: GraphSnapshot, options?: Cx2ExportOptions & CommonExportOptions): AsyncIterable<Uint8Array> {
+    export(snapshot: GraphSnapshot, options?: Cx2ExportOptions): AsyncIterable<Uint8Array> {
         return encodeChunks(write(snapshot, plan(snapshot, resolveExportOptions(options))));
     },
 
@@ -1030,7 +753,7 @@ export const cx2Exporter: GraphExporter<Cx2ExportOptions> = Object.freeze({
      * @param options - the common options
      * @returns the document
      */
-    exportToString(snapshot: GraphSnapshot, options?: Cx2ExportOptions & CommonExportOptions): Promise<string> {
+    exportToString(snapshot: GraphSnapshot, options?: Cx2ExportOptions): Promise<string> {
         return joinText(write(snapshot, plan(snapshot, resolveExportOptions(options))));
     },
 });