@graphty/graph-io 0.3.25 → 0.3.26

package/src/formats/cx2/index.ts

@@ -1,6 +1,7 @@
 /**
- * The `@graphty/graph-io/cx2` subpath (design/graph-io/cytoscape-and-obo/design.md section 1.3):
+ * The `@graphty/graph-io/cx2` subpath:
  * the CX2 importer and exporter with their option types and code tables.
+ * @module @graphty/graph-io/cx2
  */
 
 export { CX2_CAPABILITIES, CX2_LOSS, cx2Exporter, type Cx2ExportOptions } from "./exporter.js";

package/src/formats/cys/constants.ts

@@ -1,49 +1,82 @@
 /**
  * What the Cytoscape session importer's modules share: the format facts, the column and metadata
- * names it adds, and its issue code table (design `design/graph-io/cytoscape-and-obo/design.md`
- * sections 1.4 and 3).
+ * names it adds, and its issue code table.
  */
 
 import {
     AMBIGUOUS_GRAPH_NAME_CODE,
     DANGLING_REFERENCE_CODE,
+    ELEMENT_ISSUE,
     EMPTY_INPUT_CODE,
+    ENCODING_FALLBACK_CODE,
     GRAPH_NOT_FOUND_CODE,
+    INPUT_ISSUE,
     MULTIPLE_GRAPHS_CODE,
     NO_GRAPH_CODE,
     STYLES_NOT_IMPORTED_CODE,
     TOO_LARGE_CODE,
+    UNKNOWN_ENCODING_CODE,
 } from "../../common/codes.js";
 import { XGMML_ISSUE } from "../xgmml/constants.js";
 
-/** The format name. */
+/**
+ * The format name.
+ * @category Plugin helpers
+ */
 export const FORMAT = "cys";
 
-/** File extensions. */
+/**
+ * File extensions.
+ * @category Plugin helpers
+ */
 export const EXTENSIONS: readonly string[] = Object.freeze([".cys"]);
 
-/** MIME types: Cytoscape declares none, so the generic zip type. */
+/**
+ * MIME types: Cytoscape declares none, so the generic zip type.
+ * @category Plugin helpers
+ */
 export const MIME_TYPES: readonly string[] = Object.freeze(["application/zip"]);
 
-/** The `meta.extra` key of the session facts. */
+/**
+ * The `meta.extra` key of the session facts.
+ * @category Plugin helpers
+ */
 export const META_KEY = "cytoscape";
 
-/** The origin namespace of the columns the session importer adds (selection, hidden state). */
+/**
+ * The origin namespace of the columns the session importer adds (selection, hidden state).
+ * @category Plugin helpers
+ */
 export const CYTOSCAPE_NAMESPACE = "cytoscape";
 
-/** The 2.x selected state (bool node and edge column). */
+/**
+ * The 2.x selected state (bool node and edge column).
+ * @category Plugin helpers
+ */
 export const SELECTED_COLUMN = "cytoscape.selected";
 
-/** The 2.x hidden state (bool node and edge column). */
+/**
+ * The 2.x hidden state (bool node and edge column).
+ * @category Plugin helpers
+ */
 export const HIDDEN_COLUMN = "cytoscape.hidden";
 
-/** The prefix of the node columns of a second and further view's positions (`position@2`). */
+/**
+ * The prefix of the node columns of a second and further view's positions (`position@2`).
+ * @category Plugin helpers
+ */
 export const VIEW_POSITION_PREFIX = "position@";
 
-/** The default total of uncompressed bytes one import may inflate (2 GiB). */
+/**
+ * The default total of uncompressed bytes one import may inflate (2 GiB).
+ * @category Plugin helpers
+ */
 export const DEFAULT_MAX_UNCOMPRESSED = 2 * 1024 * 1024 * 1024;
 
-/** The largest uncompressed-to-compressed ratio an entry may have (real sessions reach 30:1). */
+/**
+ * The largest uncompressed-to-compressed ratio an entry may have (real sessions reach 30:1).
+ * @category Plugin helpers
+ */
 export const MAX_RATIO = 1000;
 
 /**
@@ -57,8 +90,15 @@ const RELAYED: Readonly<Record<string, string>> = Object.fromEntries(
 /**
  * Issue codes of the Cytoscape session importer: its own, the shared ones it records and the
  * XGMML codes it relays from the files inside (with the entry name in the message).
+ * @category Built-in formats
  */
 export const CYS_ISSUE = Object.freeze({
+    ...INPUT_ISSUE,
+    ...ELEMENT_ISSUE,
+    /** A session XML entry that is not UTF-8 and declares no encoding was read as windows-1252. */
+    ENCODING_FALLBACK: ENCODING_FALLBACK_CODE,
+    /** A session XML entry declares an encoding the platform cannot decode; read as UTF-8. */
+    UNKNOWN_ENCODING: UNKNOWN_ENCODING_CODE,
     ...RELAYED,
     /** The input is not a zip archive (or is text). */
     NOT_ZIP: "E_CYS_NOT_ZIP",
@@ -74,15 +114,17 @@ export const CYS_ISSUE = Object.freeze({
     TABLE: "E_CYS_TABLE",
     /** Table rows with too few or too many cells, a repeated key, or a key matching no element. */
     TABLE_ROW: "W_CYS_TABLE_ROW",
-    /** A collapsed group's members are not in the network; they are recorded in meta.extra. */
+    /** The members of a collapsed group are not in the network itself; they are listed in `snapshot.meta.extra`. */
     COLLAPSED_GROUP: "W_CYS_COLLAPSED_GROUP",
     /** Entries the importer does not read (apps, global tables, properties, images, thumbnails). */
     ENTRY_SKIPPED: "W_CYS_ENTRY_SKIPPED",
     /** Two entries with one name; the first is read. */
     DUPLICATE_ENTRY: "W_CYS_DUPLICATE_ENTRY",
+    /** A cysession.xml network record without an id, or naming a file an earlier record names. */
+    SESSION_RECORD: "W_CYS_SESSION_RECORD",
     /** The archive inflates beyond maxUncompressedBytes, or an entry beyond the ratio limit. */
     TOO_LARGE: TOO_LARGE_CODE,
-    /** The session's styles are not applied (issue #706). */
+    /** The session's styles are not applied. */
     STYLES_NOT_IMPORTED: STYLES_NOT_IMPORTED_CODE,
     /** A view, table or network the session names but does not hold. */
     DANGLING_REFERENCE: DANGLING_REFERENCE_CODE,
@@ -90,10 +132,13 @@ export const CYS_ISSUE = Object.freeze({
     EMPTY_INPUT: EMPTY_INPUT_CODE,
     /** The session holds no network. */
     NO_GRAPH: NO_GRAPH_CODE,
-    /** The session holds several networks; one was read. */
+    /**
+     * The file holds several graphs and only the first was read. It is not added when `graphIndex` or `graphName` chose the graph.
+     * `importAllGraphs()` reads every one.
+     */
     MULTIPLE_GRAPHS: MULTIPLE_GRAPHS_CODE,
-    /** graphIndex / graphName names no network (fatal). */
+    /** `graphIndex` or `graphName` matches no network in the session. The import stops. */
     GRAPH_NOT_FOUND: GRAPH_NOT_FOUND_CODE,
-    /** graphName names several networks (fatal). */
+    /** `graphName` matches several networks in the session. The import stops. */
     AMBIGUOUS_GRAPH_NAME: AMBIGUOUS_GRAPH_NAME_CODE,
 });