@graphty/graph-io 0.3.43 → 0.3.44

package/src/positions/types.ts

@@ -0,0 +1,221 @@
+/**
+ * The types of `@graphty/graph-io/positions`: the neutral form every format's stored node
+ * coordinates are read into, and how a column or an importer says how its coordinates are spelled.
+ *
+ * The neutral convention: every coordinate is the node's center, y grows upward, in the file's own
+ * length unit (`units`), with 3 components (z = 0 when the file stored 2, or when every node has the
+ * same z).
+ */
+
+import type { GraphTool, LengthUnit } from "../common/units.js";
+import type { PositionNoteCode } from "./codes.js";
+
+export type { GraphTool, LengthUnit } from "../common/units.js";
+
+/**
+ * Which way a file's y coordinate grows. "down" is screen order (yEd, Cytoscape, Pajek, d3), "up"
+ * is math order (Gephi, Graphviz, graph-io's own position columns).
+ * @category Positions
+ */
+export type YAxis = "up" | "down";
+
+/**
+ * What a stored node coordinate points at: the node's center, or the top-left corner of its box
+ * (yEd), which needs the node's width and height to find the center.
+ * @category Positions
+ */
+export type PositionAnchor = "center" | "top-left";
+
+/**
+ * How a role-`position` column's values are spelled, as optional fields of the column's
+ * `meta.extra`. A missing field means y up, center, `"file"` units: what the Cytoscape-family,
+ * GEXF and DOT columns already hold.
+ * @category Positions
+ */
+export interface PositionColumnExtra {
+    /** The unit of the coordinates. */
+    readonly units?: LengthUnit;
+    /**
+     * How many px (points) one unit of the coordinates is, when `units` is "file" but the file's
+     * unit is a known length: 72 for Graphviz input inches. Lets a reader draw the coordinates in
+     * the same unit as the file's px style lengths; the coordinates themselves stay as written.
+     */
+    readonly pxPerUnit?: number;
+    /** How many coordinates the file wrote per node: 2, or 3 when it stored a z. */
+    readonly sourceDims?: 2 | 3;
+    /** Which way y grows; "down" is flipped to y up. */
+    readonly yAxis?: YAxis;
+    /** What the coordinate points at; "top-left" is moved to the center using `width` and `height`. */
+    readonly anchor?: PositionAnchor;
+    /** The name of the node column holding each node's width, for a top-left anchor. */
+    readonly width?: string;
+    /** The name of the node column holding each node's height, for a top-left anchor. */
+    readonly height?: string;
+    /** A z the file centers its depth on (Pajek's 0.5): subtracted from a real z before any flip. */
+    readonly zOrigin?: number;
+    /**
+     * The file writes (0, 0) for a node it has no position for (NetworkX's Pajek writer): when other
+     * rows are placed, a (0, 0) shared by two or more rows counts as unplaced.
+     */
+    readonly zeroUnplaced?: boolean;
+}
+
+/**
+ * A group container's box, as an importer's `positions()` hook gives it: (`x`, `y`) is where the
+ * box's anchor is, spelled like the node coordinates (the same y direction and anchor).
+ * @category Positions
+ */
+export interface ImporterGroupBox {
+    /** The container node, by index. */
+    readonly node: number;
+    /** The box. */
+    readonly box: {
+        /** The box's anchor, x. */
+        readonly x: number;
+        /** The box's anchor, y. */
+        readonly y: number;
+        /** The box's width. */
+        readonly width: number;
+        /** The box's height. */
+        readonly height: number;
+    };
+}
+
+/**
+ * What an importer's `positions()` hook returns: where its coordinates are and how they are spelled.
+ *
+ * The simple form names two (or three) plain numeric node columns:
+ * `{ x: "x", y: "y", yAxis: "down", units: "px" }`. The advanced form names a 3-component column
+ * (`column`) and may add the anchor, size columns, group boxes, a median node size and the tool.
+ * @category Positions
+ */
+export interface ImporterPositions extends PositionColumnExtra {
+    /** A plain numeric node column holding x (simple form). */
+    readonly x?: string;
+    /** A plain numeric node column holding y (simple form). */
+    readonly y?: string;
+    /** A plain numeric node column holding z (simple form); omit for a 2D file. */
+    readonly z?: string;
+    /** A 3-component node column holding the coordinates (advanced form); defaults to the role-`position` column. */
+    readonly column?: string;
+    /** Group container boxes the file stores apart from the node coordinates (Graphviz cluster `bb`). */
+    readonly groups?: readonly ImporterGroupBox[];
+    /** The median node diameter in the file's unit, when the importer knows it better than the size columns. */
+    readonly medianNodeSize?: number | null;
+    /** The tool that wrote the file, when the importer knows it better than `meta.creator`. */
+    readonly tool?: GraphTool | null;
+}
+
+/**
+ * What an importer's `positions()` hook is given besides the snapshot.
+ * @category Positions
+ */
+export interface PositionReadContext {
+    /** Aborts a long read. */
+    readonly signal: AbortSignal | null;
+}
+
+/**
+ * A note about the stored positions: a code with its parameters, never a sentence for a reader.
+ * `message` is graph-io's English for its own logs.
+ * @category Positions
+ */
+export interface PositionNote {
+    /** The condition. */
+    readonly code: PositionNoteCode;
+    /** How many elements (or columns) it covers, and up to 8 examples. */
+    readonly params: {
+        /** How many elements (or columns) it covers. */
+        readonly count: number;
+        /** Up to 8 of their ids (or column names). */
+        readonly samples: readonly string[];
+    };
+    /** The node indexes it covers, or only their count when it is about the file as a whole. */
+    readonly elements:
+        | readonly number[]
+        | {
+              /** How many it covers. */
+              readonly count: number;
+          };
+    /** graph-io's English; never shown to a reader by graphty-element. */
+    readonly message: string;
+}
+
+/**
+ * A group container's box in the neutral convention: (`x`, `y`) is the box's center, y up.
+ * @category Positions
+ */
+export interface FilePositionGroup {
+    /** The container node, by index. */
+    readonly node: number;
+    /** The box: center, width and height in the file's unit. */
+    readonly box: {
+        /** The box's center, x. */
+        readonly x: number;
+        /** The box's center, y. */
+        readonly y: number;
+        /** The box's width. */
+        readonly width: number;
+        /** The box's height. */
+        readonly height: number;
+    };
+}
+
+/**
+ * A file's stored node coordinates in the neutral convention: the node's center, y up, in the
+ * file's own unit, 3 components per node.
+ * @category Positions
+ */
+export interface FilePositions {
+    /** The shape version of this object. */
+    readonly version: 1;
+    /** Where the coordinates came from: the format, the tool that wrote the file, and the y direction it used. */
+    readonly source: {
+        /** The format that read the file. */
+        readonly format: string;
+        /** The tool that wrote the file, or null when the file does not say. */
+        readonly tool: GraphTool | null;
+        /** Which way y grew in the file; every coordinate here has y up. */
+        readonly yAxis: YAxis;
+    };
+    /** The unit of every coordinate and size. */
+    readonly units: LengthUnit;
+    /**
+     * How many px (points) one unit is, when `units` is "file" but the file's unit is a known
+     * length (Graphviz input inches: 72); absent otherwise. Multiply a coordinate by it to compare
+     * it with the file's px style lengths.
+     */
+    readonly pxPerUnit?: number;
+    /** The median node diameter, in `units`, when the file stores node sizes; else null. */
+    readonly medianNodeSize: number | null;
+    /** 3 when the nodes differ in z, else 2 (z is then 0). */
+    readonly dims: 2 | 3;
+    /** x, y, z per node, by node index (3 * nodeCount); NaN for a node with no position. */
+    readonly coords: Float64Array;
+    /** The nodes with a position. */
+    readonly placed: number;
+    /** The nodes that need one: every node except group containers the file gives no box. */
+    readonly total: number;
+    /** False when nothing is stored, or every node sits on one point (coords are then all NaN). */
+    readonly usable: boolean;
+    /** The box around every placed node, or null when none is placed. */
+    readonly bounds: {
+        /** The smallest x, y and z. */
+        readonly min: readonly [number, number, number];
+        /** The largest x, y and z. */
+        readonly max: readonly [number, number, number];
+    } | null;
+    /** Group containers with a box. */
+    readonly groups: readonly FilePositionGroup[];
+    /** What could not be read as written. */
+    readonly notes: readonly PositionNote[];
+}
+
+/**
+ * Options of `extractPositions()`.
+ * @category Positions
+ */
+export interface ExtractPositionsOptions {
+    /** Aborts the read; it throws the signal's reason. */
+    readonly signal?: AbortSignal | null;
+}

package/src/registry.ts

@@ -23,6 +23,7 @@ import {
     FETCH_CODE,
     OPTION_IGNORED_CODE,
     SELF_LOOPS_DROPPED_CODE,
+    STYLES_NOT_IMPORTED_CODE,
     UNKNOWN_OPTION_CODE,
     WEIGHT_NOT_FOUND_CODE,
 } from "./common/codes.js";
@@ -45,6 +46,9 @@ import { oboExporter, oboImporter } from "./formats/obo/index.js";
 import { pajekExporter, pajekImporter } from "./formats/pajek/index.js";
 import { xgmmlExporter, xgmmlImporter } from "./formats/xgmml/index.js";
 import { type FormatName, rankFormats, SNIFF_HEAD_BYTES, type SniffHints, type SniffResult } from "./sniff.js";
+import { extractStyles, type StyleImportOptions } from "./styles/io/generic.js";
+import { isKeptGraphtyProperty, prepareStyleExport } from "./styles/io/writer.js";
+import type { ExtractedStyles } from "./styles/types.js";
 import {
     type CommonExportOptions,
     type CommonImportOptions,
@@ -137,6 +141,13 @@ export interface ImportGraphOptions extends CommonImportOptions, GraphChoiceOpti
      * @defaultValue 16777216
      */
     readonly maxEmptyCells?: number | undefined;
+    /**
+     * Read the file's styles too: `true`, or `{ toolDefaults: false }` to leave out the defaults of the program
+     * that wrote the file. The styles are in `result.styles`; the graph, the report and every export are the same
+     * either way.
+     * @defaultValue false
+     */
+    readonly styles?: boolean | StyleImportOptions | undefined;
     /** Format-specific options, passed to the importer as they are. */
     readonly [formatOption: string]: unknown;
 }
@@ -172,6 +183,12 @@ export interface ImportGraphResult {
      * can ignore it. It is not enumerable, so `console.log(result)` and `{ ...result }` leave it out.
      */
     readonly freeze: FreezeReport;
+    /**
+     * The file's styles, when you passed the `styles` option: the rules that reproduce how the program that wrote
+     * the file draws each node and edge, read by the importer that read the file. Null when the file has none.
+     * Absent without the option.
+     */
+    readonly styles?: ExtractedStyles | null;
 }
 
 /**
@@ -239,6 +256,13 @@ export interface FormatInfo {
  * @category Saving
  */
 export interface ExportGraphOptions extends CommonExportOptions {
+    /**
+     * Write these styles too (`result.styles` of an import, or styles built for this graph): each element's look in
+     * the format's own style slots and, where the format can keep them, the rules, so importing the file back
+     * rebuilds them. What the format cannot hold is a W_STYLE_ note of checkExport(). Styles read from or built for a
+     * different graph fail with E_STYLES_MISMATCH before anything is written.
+     */
+    readonly styles?: ExtractedStyles | null | undefined;
     /** Format-specific options, passed to the exporter as they are. */
     readonly [formatOption: string]: unknown;
 }
@@ -272,6 +296,7 @@ const FUNCTION_OPTIONS: ReadonlySet<string> = new Set([
     "sanitizeIds",
     "selfLoops",
     "signal",
+    "styles",
     "weightDtype",
     "weightFrom",
 ]);
@@ -284,6 +309,7 @@ const REGISTRY_KEYS: ReadonlySet<string> = new Set([
     "builder",
     "freeze",
     "maxEmptyCells",
+    "styles",
 ]);
 
 /**
@@ -687,7 +713,43 @@ export class FormatRegistry {
         format: FormatName,
         options?: ExportGraphOptions | CommonExportOptions,
     ): AsyncIterable<Uint8Array> {
-        return this.exporter(format).export(snapshot, options);
+        const styled = this.styled(snapshot, format, options);
+        if (styled === null) {
+            return this.exporter(format).export(snapshot, options);
+        }
+        if (styled.refusal !== null) {
+            return refuse(styled.refusal);
+        }
+        return styled.exporter.export(styled.snapshot, styled.options);
+    }
+
+    /**
+     * An export with styles worked out, or null when no styles were given (the export is then exactly as before).
+     * @param snapshot - the graph
+     * @param format - the format name
+     * @param options - the caller's options
+     * @returns the exporter, the snapshot and options to hand it, the style losses and any refusal
+     */
+    private styled(
+        snapshot: GraphSnapshot,
+        format: FormatName,
+        options: ExportGraphOptions | CommonExportOptions | undefined,
+    ): StyledExport | null {
+        const styles = (options as ExportGraphOptions | undefined)?.styles;
+        if (styles === undefined || styles === null) {
+            return null;
+        }
+        const exporter = this.exporter(format);
+        const { styles: _given, ...rest } = options as ExportGraphOptions;
+        const prepared = prepareStyleExport(snapshot, exporter, styles, rest);
+        return {
+            exporter,
+            snapshot: prepared.snapshot,
+            options: prepared.input === null ? rest : { ...rest, styles: prepared.input },
+            plain: rest,
+            notes: prepared.notes,
+            refusal: prepared.refusal,
+        };
     }
 
     /**
@@ -702,7 +764,14 @@ export class FormatRegistry {
         format: FormatName,
         options?: ExportGraphOptions | CommonExportOptions,
     ): Promise<string> {
-        return this.exporter(format).exportToString(snapshot, options);
+        const styled = this.styled(snapshot, format, options);
+        if (styled === null) {
+            return this.exporter(format).exportToString(snapshot, options);
+        }
+        if (styled.refusal !== null) {
+            throw refusalError(styled.refusal);
+        }
+        return styled.exporter.exportToString(styled.snapshot, styled.options);
     }
 
     /**
@@ -754,7 +823,28 @@ export class FormatRegistry {
         format: FormatName,
         options?: ExportGraphOptions | CommonExportOptions,
     ): readonly LossNote[] {
-        const notes = this.exporter(format).check(snapshot, options);
+        const styled = this.styled(snapshot, format, options);
+        let notes: readonly LossNote[];
+        if (styled === null) {
+            notes = this.exporter(format).check(snapshot, options);
+        } else if (styled.refusal === null) {
+            // a property graph-io already reports as not written is reported once, whoever else notices
+            const key = (n: LossNote): string =>
+                `${n.code}\u0000${n.style?.target ?? ""}\u0000${n.style?.property ?? ""}`;
+            const reported = new Set(styled.notes.filter((n) => n.style !== undefined).map(key));
+            notes = [
+                ...styled.exporter
+                    .check(styled.snapshot, styled.options)
+                    .filter(
+                        (n) =>
+                            n.style === undefined ||
+                            (!reported.has(key(n)) && !isKeptGraphtyProperty(n, styled.exporter)),
+                    ),
+                ...styled.notes,
+            ];
+        } else {
+            notes = [...styled.exporter.check(snapshot, styled.plain), styled.refusal];
+        }
         const unknown = this.unknownOptions(options);
         if (unknown.length === 0) {
             return notes;
@@ -845,7 +935,7 @@ export class FormatRegistry {
                 mimeTypes: importer?.mimeTypes ?? exporter?.mimeTypes ?? [],
                 canImport: importer !== undefined,
                 canExport: exporter !== undefined,
-                capabilities: exporter?.capabilities ?? null,
+                capabilities: capabilitiesOf(exporter),
             });
         });
     }
@@ -1405,6 +1495,16 @@ function result(
         throw freezeFailure(err, report);
     }
     const { warnings } = chosen;
+    const wanted = options.styles;
+    let styles: ExtractedStyles | null | undefined;
+    if (wanted !== undefined && wanted !== false) {
+        styles = extractStyles(chosen.importer, frozen.snapshot, report, {
+            signal: options.signal,
+            toolDefaults: typeof wanted === "object" ? wanted.toolDefaults : undefined,
+        });
+    }
+    const read =
+        styles !== undefined && chosen.importer.styles !== undefined ? withoutStylesNotImported(report) : report;
     const result = {
         format: chosen.importer.format,
         sniff: chosen.sniff,
@@ -1412,11 +1512,11 @@ function result(
         report: withFreezeWarnings(
             weightNotFound(
                 warnings.length === 0
-                    ? report
+                    ? read
                     : Object.freeze({
-                          ...report,
-                          issues: Object.freeze([...warnings, ...report.issues]),
-                          warningCount: report.warningCount + warnings.length,
+                          ...read,
+                          issues: Object.freeze([...warnings, ...read.issues]),
+                          warningCount: read.warningCount + warnings.length,
                       }),
                 frozen.snapshot,
                 options.weightFrom,
@@ -1424,11 +1524,82 @@ function result(
             frozen.report,
         ),
     };
+    if (styles !== undefined) {
+        Object.assign(result, { styles });
+    }
     // not enumerable: it holds one entry per edge, and console.log(result) should show the graph, not that
     Object.defineProperty(result, "freeze", { value: frozen.report, enumerable: false });
     return Object.freeze(result as ImportGraphResult);
 }
 
+/**
+ * A report without its W_STYLES_NOT_IMPORTED warnings: the importer read the styles it would have named.
+ * @param report - the importer's report
+ * @returns the report, a copy only when it held such a warning
+ */
+function withoutStylesNotImported(report: ImportReport): ImportReport {
+    const issues = report.issues.filter((i) => i.code !== STYLES_NOT_IMPORTED_CODE);
+    if (issues.length === report.issues.length) {
+        return report;
+    }
+    return Object.freeze({
+        ...report,
+        issues: Object.freeze(issues),
+        warningCount: report.warningCount - (report.issues.length - issues.length),
+    });
+}
+
+/** An export with styles, worked out by FormatRegistry.styled(). */
+interface StyledExport {
+    /** The exporter. */
+    readonly exporter: GraphExporter;
+    /** The snapshot to hand it. */
+    readonly snapshot: GraphSnapshot;
+    /** The options to hand it: the caller's, with `styles` replaced by the exporter's input or left out. */
+    readonly options: ExportGraphOptions;
+    /** The caller's options without `styles`. */
+    readonly plain: ExportGraphOptions;
+    /** The style losses. */
+    readonly notes: readonly LossNote[];
+    /** E_STYLES_MISMATCH, or null. */
+    readonly refusal: LossNote | null;
+}
+
+/**
+ * The error an export refused for its styles throws.
+ * @param note - the refusal note
+ * @returns the error
+ */
+function refusalError(note: LossNote): GraphFormatError {
+    return new GraphFormatError("E_UNSUPPORTED", note.message, { code: note.code });
+}
+
+/**
+ * Chunks that fail on the first read, before any byte: an export refused for its styles.
+ * @param note - the refusal note
+ * @returns chunks whose first read rejects
+ */
+function refuse(note: LossNote): AsyncIterable<Uint8Array> {
+    return {
+        [Symbol.asyncIterator]: () => ({ next: () => Promise.reject(refusalError(note)) }),
+    };
+}
+
+/**
+ * The capabilities listFormats() reports for an exporter: its table plus, when it writes styles, their capabilities.
+ * @param exporter - the exporter, or undefined
+ * @returns the capabilities, or null
+ */
+function capabilitiesOf(exporter: GraphExporter | undefined): ExportCapabilities | null {
+    if (exporter === undefined) {
+        return null;
+    }
+    if (exporter.styles === undefined) {
+        return exporter.capabilities;
+    }
+    return Object.freeze({ ...exporter.capabilities, styles: exporter.styles.capabilities });
+}
+
 /**
  * The message of a W_UNKNOWN_OPTION warning or note.
  * @param name - the option name