@graphty/graph-io 0.3.25 → 0.3.26

package/src/formats/gexf/index.ts

@@ -1,28 +1,38 @@
 /**
- * The GEXF subpath entry (`@graphty/graph-io/gexf`, design section 8.2): the importer and exporter
+ * The GEXF subpath entry (`@graphty/graph-io/gexf`): the importer and exporter
  * objects with their format-specific option types, the exporter's loss-note codes and the
  * importer's issue codes grouped in one table.
+ * @module @graphty/graph-io/gexf
  */
 
 import {
     BAD_DEFAULT_CODE,
     BAD_OPTIONS_CODE,
+    BAD_VALUE_CODE,
     COLUMN_RENAMED_CODE,
+    COLUMN_TYPE_CODE,
     COUNT_HINT_CODE,
+    COUNT_MISMATCH_CODE,
     DIRECTION_FORCED_CODE,
     DIRECTION_REFUSED_CODE,
     DUPLICATE_ATTRIBUTE_CODE,
     DUPLICATE_EDGE_ID_CODE,
     DUPLICATE_NODE_CODE,
+    ELEMENT_ISSUE,
+    EMPTY_INPUT_CODE,
+    ENCODING_CONFLICT_CODE,
     ENCODING_FALLBACK_CODE,
     ID_MERGED_CODE,
+    INPUT_ISSUE,
     INVALID_ENCODING_CODE,
     INVALID_UTF8_CODE,
     MISSING_ENDPOINT_CODE,
     MISSING_ID_CODE,
     MIXED_DIRECTION_CODE,
+    MULTIPLE_GRAPHS_CODE,
     NO_GRAPH_CODE,
     OPTION_IGNORED_CODE,
+    PARENT_CYCLE_CODE,
     PRECISION_CODE,
     ROLE_TAKEN_CODE,
     SINK_OPTION_CODE,
@@ -31,6 +41,7 @@ import {
     UNKNOWN_ELEMENT_CODE,
     UNKNOWN_ENCODING_CODE,
     UNKNOWN_PARENT_CODE,
+    UNKNOWN_XML_ATTRIBUTE_CODE,
     XML_SYNTAX_CODE,
 } from "../../common/codes.js";
 import {
@@ -45,7 +56,9 @@ import {
     OPEN_BOUND_CONFLICT_CODE,
     SPELL_OPEN_CODE,
     TIMED_STATIC_CODE,
+    TIMESTAMP_CONFLICT_CODE,
     UNKNOWN_ATTRIBUTE_CODE,
+    VALUE_OUTSIDE_OPTIONS_CODE,
     VIZ_DYNAMIC_CODE,
     VIZ_SKIPPED_CODE,
     VIZ_VALUE_CODE,
@@ -57,43 +70,77 @@ export { gexfImporter, type GexfImportOptions } from "./importer.js";
 export { type GexfVersion } from "./schema.js";
 
 /**
- * The issue codes the GEXF importer records (design section 8.6), by name: the codes shared with
- * the other importers (src/common/codes.ts) and the GEXF-specific ones. A key is the code without
+ * The issue codes the GEXF importer records, by name: the codes shared with
+ * the other importers and the GEXF-specific ones. A key is the code without
  * its severity and format prefixes.
+ * @category Built-in formats
  */
 export const GEXF_ISSUE = Object.freeze({
-    /** The XML is not well-formed (fatal). */
+    ...INPUT_ISSUE,
+    ...ELEMENT_ISSUE,
+    /**
+     * A value that does not parse as the type its attribute declares ("x" in an integer attribute). The value is
+     * left unset; the node or edge is kept.
+     */
+    COLUMN_TYPE: COLUMN_TYPE_CODE,
+    /** The XML is not well-formed. The import stops. */
     XML_SYNTAX: XML_SYNTAX_CODE,
-    /** The input holds invalid UTF-8 (fatal). */
+    /** The input is not valid UTF-8. The import stops. */
     INVALID_UTF8: INVALID_UTF8_CODE,
-    /** Invalid bytes in the encoding a BOM, a declaration or the encoding option chose (fatal). */
+    /**
+     * Some bytes are not valid in the encoding that was chosen (by a byte order mark, the file's declaration or the
+     * `encoding` option). The import stops.
+     */
     INVALID_ENCODING: INVALID_ENCODING_CODE,
     /** Bytes that are not UTF-8 and declare no encoding were read as windows-1252. */
     ENCODING_FALLBACK: ENCODING_FALLBACK_CODE,
     /** A declared encoding the platform cannot decode was ignored. */
     UNKNOWN_ENCODING: UNKNOWN_ENCODING_CODE,
-    /** The root element is not `<gexf>` (fatal). */
+    /** A declared encoding the byte order mark contradicts (the mark wins). */
+    ENCODING_CONFLICT: ENCODING_CONFLICT_CODE,
+    /** The input holds no XML at all: it is empty, whitespace or a byte order mark only. The import stops. */
+    EMPTY_INPUT: EMPTY_INPUT_CODE,
+    /** The root element is not `<gexf>`. The import stops. */
     NOT_GEXF: NOT_GEXF_CODE,
-    /** The document has no `<graph>` (fatal). */
+    /** The document has no `<graph>`. The import stops. */
     NO_GRAPH: NO_GRAPH_CODE,
+    /**
+     * The file holds more than one `<graph>` element; their nodes and edges are merged into one graph.
+     * `importAllGraphs()` reads every one.
+     */
+    MULTIPLE_GRAPHS: MULTIPLE_GRAPHS_CODE,
     /** `<edges>` without `<nodes>`. */
     MISSING_NODES: MISSING_NODES_CODE,
     /** A node without an id. */
     MISSING_ID: MISSING_ID_CODE,
     /** An edge without a source or target. */
     MISSING_ENDPOINT: MISSING_ENDPOINT_CODE,
+    /** An edge endpoint that names no declared node (addMissingNodes false, the GEXF default). */
+    UNKNOWN_NODE: "E_UNKNOWN_NODE",
     /** An edge `type` outside directed / undirected / mutual. */
     EDGE_TYPE: EDGE_TYPE_CODE,
-    /** A `pid` / `<parent for>` naming an unknown node. */
+    /** A `pid` / `<parent for>` naming an unknown node, a `<parent>` without for, or the children of a skipped node. */
     UNKNOWN_PARENT: UNKNOWN_PARENT_CODE,
+    /** A `pid` / nested containment that would close a parent cycle; that link is dropped. */
+    PARENT_CYCLE: PARENT_CYCLE_CODE,
+    /** An inverted interval (start after end) of an element, a spell or a value; it is not kept. */
+    BAD_VALUE: BAD_VALUE_CODE,
     /** An `<attributes class>` outside node / edge. */
     ATTRIBUTES_CLASS: ATTRIBUTES_CLASS_CODE,
     /** An `<attribute>` without an id. */
     ATTRIBUTE_ID: ATTRIBUTE_ID_CODE,
     /** A `<graph>` header attribute with an unknown value. */
     HEADER_VALUE: HEADER_VALUE_CODE,
-    /** A `count` hint the sink cannot reserve (ignored). */
+    /**
+     * A node or edge count the file announces is too large to reserve room for; it is ignored and the elements are
+     * read as they come.
+     */
     COUNT_HINT: COUNT_HINT_CODE,
+    /**
+     * A `count` attribute disagrees with the number of nodes or edges actually in its section. The elements are read
+     * as they are.
+     */
+    COUNT_MISMATCH: COUNT_MISMATCH_CODE,
     /** A node id declared twice. */
     DUPLICATE_NODE: DUPLICATE_NODE_CODE,
     /** An edge id declared twice (the second edge is skipped). */
@@ -108,9 +155,15 @@ export const GEXF_ISSUE = Object.freeze({
     BAD_DEFAULT: BAD_DEFAULT_CODE,
     /** Options that do not parse as the declared type. */
     BAD_OPTIONS: BAD_OPTIONS_CODE,
-    /** A column renamed `<name>#<id>` because the name was taken (design section 5.6). */
+    /**
+     * An attribute was renamed `<name>#<suffix>` because another attribute already has its name, for example
+     * two attributes declared with the same name.
+     */
     COLUMN_RENAMED: COLUMN_RENAMED_CODE,
-    /** A column declared without its role because the table already holds it. */
+    /**
+     * You read into a graph builder that already has an id, label or position attribute, so this file's one is kept as
+     * a plain attribute.
+     */
     ROLE_TAKEN: ROLE_TAKEN_CODE,
     /** An `<attvalue for>` naming an undeclared attribute. */
     UNKNOWN_ATTRIBUTE: UNKNOWN_ATTRIBUTE_CODE,
@@ -118,13 +171,13 @@ export const GEXF_ISSUE = Object.freeze({
     ATTVALUE_SHAPE: ATTVALUE_SHAPE_CODE,
     /** A timed value on an attribute of a static group. */
     TIMED_VALUE_ON_STATIC: TIMED_STATIC_CODE,
-    /** A long value beyond 2^53 rounded. */
+    /** An integer beyond 2^53 was stored as the nearest 64-bit float; pass `long: "string"` to keep every digit. */
     PRECISION: PRECISION_CODE,
-    /** Two id texts merged into one number under ids "number". */
+    /** Two different id texts became the same number because `ids` is "number", so their nodes were merged. */
     ID_MERGED: ID_MERGED_CODE,
     /** The XML weight attribute ignored under weightFrom null. */
     WEIGHT_IGNORED: WEIGHT_IGNORED_CODE,
-    /** viz elements skipped under viz: false. */
+    /** Viz elements skipped under viz: false. */
     VIZ_SKIPPED: VIZ_SKIPPED_CODE,
     /** A 1.2 dynamic viz element whose bounds were dropped. */
     VIZ_DYNAMIC_DROPPED: VIZ_DYNAMIC_CODE,
@@ -134,18 +187,34 @@ export const GEXF_ISSUE = Object.freeze({
     VIZ_VALUE: VIZ_VALUE_CODE,
     /** Both `start` and `startopen` (or `end` and `endopen`) on one element. */
     OPEN_BOUND_CONFLICT: OPEN_BOUND_CONFLICT_CODE,
-    /** An element or attribute GEXF does not define was skipped. */
+    /** Both `timestamp` and `start` / `end` on one element or value. */
+    TIMESTAMP_CONFLICT: TIMESTAMP_CONFLICT_CODE,
+    /** A value outside the declared `<options>` (kept). */
+    VALUE_OUTSIDE_OPTIONS: VALUE_OUTSIDE_OPTIONS_CODE,
+    /** An element GEXF does not define at that place was skipped. */
     UNKNOWN_ELEMENT: UNKNOWN_ELEMENT_CODE,
+    /** An XML attribute GEXF does not define on that element was ignored. */
+    UNKNOWN_XML_ATTRIBUTE: UNKNOWN_XML_ATTRIBUTE_CODE,
     /** Text where GEXF allows only elements was ignored. */
     STRAY_TEXT: STRAY_TEXT_CODE,
-    /** A common option the importer has no use for was given. */
+    /** You set an option this format does not use; it had no effect. The message names the option. */
     OPTION_IGNORED: OPTION_IGNORED_CODE,
-    /** A builder-policy option the sink does not honour. */
+    /**
+     * You read into your own graph builder, which was created with a different `addMissingNodes`, `duplicateEdges`,
+     * `selfLoops` or `weightDtype` than the option you passed; the builder's setting applies.
+     */
     SINK_OPTION: SINK_OPTION_CODE,
-    /** The sink refused the file's direction. */
+    /**
+     * You read into a graph builder whose direction is already set, or which already holds edges, so the file is read
+     * with the builder's direction instead of its own.
+     */
     DIRECTION_REFUSED: DIRECTION_REFUSED_CODE,
-    /** Edges forced to the policy's direction. */
+    /** Edges of the other direction were read with the direction `onMixedDirection` chose. */
     DIRECTION_FORCED: DIRECTION_FORCED_CODE,
-    /** A mixed file under onMixedDirection "error" (fatal). */
+    /**
+     * The graph has both directed and undirected edges and `onMixedDirection` is "error". An import stops; a save to a
+     * format that holds one direction per file fails with E_DIRECTED. Pass "directed" or "undirected" to read or write
+     * it anyway.
+     */
     MIXED_DIRECTION: MIXED_DIRECTION_CODE,
 });

package/src/formats/gexf/schema.ts

@@ -11,31 +11,55 @@ import { type ColumnDecl, type Dtype } from "@graphty/graph-format";
 
 import { TIME_TEXT_ROLE, TIME_TEXT_SUFFIX } from "../../common/temporal.js";
 
-/** The GEXF versions the exporter writes. */
+/**
+ * The GEXF versions the exporter writes.
+ * @category Built-in formats
+ */
 export type GexfVersion = "1.2" | "1.3";
 
-/** The format name. */
+/**
+ * The format name.
+ * @category Plugin helpers
+ */
 export const GEXF_FORMAT = "gexf";
 
-/** The namespace URIs of each version. */
+/**
+ * The namespace URIs of each version.
+ * @category Plugin helpers
+ */
 export const GEXF_NAMESPACES: Readonly<Record<GexfVersion, { readonly gexf: string; readonly viz: string }>> = {
     "1.2": { gexf: "http://www.gexf.net/1.2draft", viz: "http://www.gexf.net/1.2draft/viz" },
     "1.3": { gexf: "http://gexf.net/1.3", viz: "http://gexf.net/1.3/viz" },
 };
 
-/** The default edge type values of `<graph defaultedgetype>` and `<edge type>`. */
+/**
+ * The default edge type values of `<graph defaultedgetype>` and `<edge type>`.
+ * @category Plugin helpers
+ */
 export type GexfEdgeType = "directed" | "undirected" | "mutual";
 
-/** The GEXF `timeformat` values. */
+/**
+ * The GEXF `timeformat` values.
+ * @category Plugin helpers
+ */
 export const TIME_FORMATS: ReadonlySet<string> = new Set(["integer", "double", "date", "dateTime"]);
 
-/** The GEXF graph `mode` values. */
+/**
+ * The GEXF graph `mode` values.
+ * @category Plugin helpers
+ */
 export const GRAPH_MODES: ReadonlySet<string> = new Set(["static", "dynamic", "slice"]);
 
-/** The GEXF 1.3 `timerepresentation` values. */
+/**
+ * The GEXF 1.3 `timerepresentation` values.
+ * @category Plugin helpers
+ */
 export const TIME_REPRESENTATIONS: ReadonlySet<string> = new Set(["interval", "timestamp"]);
 
-/** The `origin.namespace` of viz-derived columns. */
+/**
+ * The `origin.namespace` of viz-derived columns.
+ * @category Plugin helpers
+ */
 export const VIZ_NAMESPACE = "viz";
 
 /** The origin every XML-derived column declares. */
@@ -47,6 +71,7 @@ const VIZ_ORIGIN = { format: GEXF_FORMAT, namespace: VIZ_NAMESPACE };
 /**
  * The fixed node column names the importer owns (design section 5.6): a declared attribute with
  * one of these titles is renamed `<title>#<id>` so the XML-derived column keeps its name and role.
+ * @category Plugin helpers
  */
 export const NODE_COLUMNS = Object.freeze({
     label: "label",
@@ -83,7 +108,10 @@ const EDGE_COLUMNS = Object.freeze({
     shape: "shape",
 });
 
-/** Every reserved node column name, including the temporal companions. */
+/**
+ * Every reserved node column name, including the temporal companions.
+ * @category Plugin helpers
+ */
 export const RESERVED_NODE_NAMES: ReadonlySet<string> = new Set([
     ...Object.values(NODE_COLUMNS),
     NODE_COLUMNS.start + TIME_TEXT_SUFFIX,
@@ -91,7 +119,10 @@ export const RESERVED_NODE_NAMES: ReadonlySet<string> = new Set([
     NODE_COLUMNS.timestamp + TIME_TEXT_SUFFIX,
 ]);
 
-/** Every reserved edge column name, including the temporal companions. */
+/**
+ * Every reserved edge column name, including the temporal companions.
+ * @category Plugin helpers
+ */
 export const RESERVED_EDGE_NAMES: ReadonlySet<string> = new Set([
     ...Object.values(EDGE_COLUMNS),
     EDGE_COLUMNS.start + TIME_TEXT_SUFFIX,
@@ -99,7 +130,10 @@ export const RESERVED_EDGE_NAMES: ReadonlySet<string> = new Set([
     EDGE_COLUMNS.timestamp + TIME_TEXT_SUFFIX,
 ]);
 
-/** The declarations of the XML-derived node columns, keyed as NODE_COLUMNS. */
+/**
+ * The declarations of the XML-derived node columns, keyed as NODE_COLUMNS.
+ * @category Plugin helpers
+ */
 export const NODE_DECLS: Readonly<Record<keyof typeof NODE_COLUMNS, ColumnDecl>> = {
     label: { name: NODE_COLUMNS.label, dtype: "string", role: "label", nullable: true, origin: XML_ORIGIN },
     parent: {
@@ -171,7 +205,10 @@ export const NODE_DECLS: Readonly<Record<keyof typeof NODE_COLUMNS, ColumnDecl>>
     shapeUri: { name: NODE_COLUMNS.shapeUri, dtype: "string", nullable: true, origin: VIZ_ORIGIN },
 };
 
-/** The declarations of the XML-derived edge columns, keyed as EDGE_COLUMNS. */
+/**
+ * The declarations of the XML-derived edge columns, keyed as EDGE_COLUMNS.
+ * @category Plugin helpers
+ */
 export const EDGE_DECLS: Readonly<Record<keyof typeof EDGE_COLUMNS, ColumnDecl>> = {
     id: { name: EDGE_COLUMNS.id, dtype: "string", role: "id", unique: true, nullable: true, origin: XML_ORIGIN },
     label: { name: EDGE_COLUMNS.label, dtype: "string", role: "label", nullable: true, origin: XML_ORIGIN },
@@ -217,16 +254,25 @@ export const EDGE_DECLS: Readonly<Record<keyof typeof EDGE_COLUMNS, ColumnDecl>>
     shape: { name: EDGE_COLUMNS.shape, dtype: "dict", role: "shape", nullable: true, origin: VIZ_ORIGIN },
 };
 
-/** The bit of the `open` column marking an open start (design section 5.1). */
+/**
+ * The bit of the `open` column marking an open start (design section 5.1).
+ * @category Plugin helpers
+ */
 export const OPEN_START = 1;
 
-/** The bit of the `open` column marking an open end. */
+/**
+ * The bit of the `open` column marking an open end.
+ * @category Plugin helpers
+ */
 export const OPEN_END = 2;
 
 /** The prefix of a temporal extension table's name (design section 5.10). */
 const TEMPORAL_TABLE_PREFIX = "temporal:";
 
-/** The column names of a temporal extension table (design section 5.10). */
+/**
+ * The column names of a temporal extension table (design section 5.10).
+ * @category Plugin helpers
+ */
 export const TEMPORAL_COLUMNS = Object.freeze({
     element: "element",
     start: "start",
@@ -243,6 +289,7 @@ export const TEMPORAL_COLUMNS = Object.freeze({
  * @param domain - node or edge
  * @param column - the static column's name
  * @returns `temporal:<domain>:<column>`
+ * @category Plugin helpers
  */
 export function temporalTableName(domain: "node" | "edge", column: string): string {
     return `${TEMPORAL_TABLE_PREFIX}${domain}:${column}`;
@@ -252,6 +299,7 @@ export function temporalTableName(domain: "node" | "edge", column: string): stri
  * Split a temporal table name into its domain and column.
  * @param name - the table name
  * @returns the parts, or null when the name is not a temporal table's
+ * @category Plugin helpers
  */
 export function parseTemporalTableName(name: string): { domain: "node" | "edge"; column: string } | null {
     if (!name.startsWith(TEMPORAL_TABLE_PREFIX)) {
@@ -277,6 +325,7 @@ export function parseTemporalTableName(name: string): { domain: "node" | "edge";
  * @param value - the value column's declaration fields (dtype, itemDtype, options...)
  * @param temporalValue - whether the value is itself a temporal type needing a text companion
  * @returns the declarations in table order
+ * @category Plugin helpers
  */
 export function temporalTableDecls(
     domain: "node" | "edge",
@@ -330,6 +379,7 @@ const TYPES_1_3: ReadonlySet<string> = new Set([
  * @param type - the type text
  * @param version - the target version
  * @returns true when the version declares it
+ * @category Plugin helpers
  */
 export function isScalarType(type: string, version: GexfVersion): boolean {
     return (version === "1.2" ? TYPES_1_2 : TYPES_1_3).has(type);
@@ -340,6 +390,7 @@ export function isScalarType(type: string, version: GexfVersion): boolean {
  * @param type - the type text
  * @param version - the target version
  * @returns true when the version declares it
+ * @category Plugin helpers
  */
 export function isListType(type: string, version: GexfVersion): boolean {
     if (version === "1.2") {
@@ -352,6 +403,7 @@ export function isListType(type: string, version: GexfVersion): boolean {
  * The canonical GEXF scalar type of a column dtype (design section 5.1 reversed).
  * @param dtype - a scalar dtype
  * @returns the type text; u32 becomes `long` (its range exceeds `integer`), u8 `integer`, json `string`
+ * @category Plugin helpers
  */
 export function canonicalScalarType(dtype: Dtype): string {
     switch (dtype) {