@graphty/graph-io 0.3.25 → 0.3.27

package/dist/src/formats/cx2/importer.d.ts

@@ -18,48 +18,68 @@
  * (`visualProperties`, `visualEditorProperties`) and every opaque aspect are kept verbatim in
  * `meta.extra.cx2.opaque` and are not applied (W_STYLES_NOT_IMPORTED, issue #706).
  */
-import { type GraphImporter } from "../../types.js";
-/** The format name. */
+import { type CommonImportOptions, type GraphImporter } from "../../types.js";
+/**
+ * The format name.
+ * @category Plugin helpers
+ */
 export declare const CX2_FORMAT = "cx2";
-/** The node attribute the exporter's `sanitizeIds: "mangle"` keeps an original id in. */
+/**
+ * The node attribute the exporter's `sanitizeIds: "mangle"` keeps an original id in.
+ * @category Plugin helpers
+ */
 export declare const ORIGINAL_ID_ATTRIBUTE = "graphty:originalId";
-/** The origin namespace of the per-element visual property columns. */
+/**
+ * The origin namespace of the per-element visual property columns.
+ * @category Plugin helpers
+ */
 export declare const BYPASS_NAMESPACE = "cx2.bypass";
-/** The format-specific options of the CX2 importer. */
-export interface Cx2ImportOptions {
+/**
+ * The format-specific options of the CX2 importer.
+ * @category Built-in formats
+ */
+export interface Cx2ImportOptions extends CommonImportOptions {
     /**
-     * Where a node's `z` goes: "column" (default) keeps it in the f64 node column `z` (Cytoscape
-     * writes a stacking order there); "position" makes it the third component of the position.
+     * Where Cytoscape's `z` value (a drawing order, not a depth) goes: "column" keeps it as a node
+     * attribute named `z`; "position" makes it the third coordinate of the position.
+     * @defaultValue "column"
      */
     zAs?: "column" | "position" | undefined;
 }
 /**
- * The issue codes the CX2 importer records (design section 1.3), by name: the codes shared with
- * the other importers (src/common/codes.ts) and the CX2-specific ones. A key is the code without
+ * The issue codes the CX2 importer records, by name: the codes shared with
+ * the other importers and the CX2-specific ones. A key is the code without
  * its severity and format prefixes.
+ * @category Built-in formats
  */
 export declare const CX2_ISSUE: Readonly<{
-    /** The input is empty (fatal). */
+    /** The input is empty. The import stops. */
     EMPTY_INPUT: "E_EMPTY_INPUT";
-    /** The text is not JSON (fatal). */
+    /** The text is not valid JSON. The import stops. */
     SYNTAX: "E_SYNTAX";
-    /** Invalid UTF-8 (fatal). */
+    /** The input is not valid UTF-8. The import stops. */
     INVALID_UTF8: "E_INVALID_UTF8";
-    /** Invalid bytes in the encoding a BOM or the encoding option chose (fatal). */
+    /**
+     * Some bytes are not valid in the encoding that was chosen (by a byte order mark or the `encoding` option). The
+     * import stops.
+     */
     INVALID_ENCODING: "E_INVALID_ENCODING";
     /** Bytes that are not UTF-8 were read as windows-1252. */
     ENCODING_FALLBACK: "W_ENCODING_FALLBACK";
     /** An encoding the platform cannot decode was ignored. */
     UNKNOWN_ENCODING: "W_UNKNOWN_ENCODING";
-    /** The document is not an array or does not start with a descriptor holding CXVersion (fatal). */
+    /**
+     * The document is not a JSON array, or its first element is not the CX2 descriptor with `CXVersion`. The import
+     * stops.
+     */
     NO_DESCRIPTOR: "E_CX2_NO_DESCRIPTOR";
-    /** CXVersion names a major version other than 2 (fatal); "1.x" says the file is CX1. */
+    /** `CXVersion` names a version other than 2 ("1.x" means the file is CX1; read it as `cx`). The import stops. */
     VERSION: "E_CX2_VERSION";
     /** CXVersion is a 2.x other than "2.0" (or not a string); the document is read. */
     MINOR_VERSION: "W_CX2_MINOR_VERSION";
     /** The document has no status block, or a malformed one. */
     NO_STATUS: "E_CX2_NO_STATUS";
-    /** The producer marked the document as failed (fatal). */
+    /** The program that wrote the file marked it as failed, so it is incomplete. The import stops. */
     STATUS_FAILED: "E_STATUS_FAILED";
     /** The producer marked the document as successful with an error text. */
     STATUS_WARNING: "W_STATUS_WARNING";
@@ -83,9 +103,18 @@ export declare const CX2_ISSUE: Readonly<{
     ALIAS_BYPASSED: "W_CX2_ALIAS_BYPASSED";
     /** A CX1 cartesianLayout aspect next to node coordinates; kept, not applied. */
     LEGACY_LAYOUT: "W_CX2_LEGACY_LAYOUT";
-    /** The file's style rules are not applied (issue #706). */
+    /** An aspect CX2 defines as an array of elements written as one object; read as one element. */
+    SINGLE_OBJECT_ASPECT: "W_SINGLE_OBJECT_ASPECT";
+    /** A member holding several aspects; each array-valued key is read as its own block. */
+    MULTI_ASPECT_FRAGMENT: "W_MULTI_ASPECT_FRAGMENT";
+    /** The bare tokens NaN / Infinity / -Infinity (Python's json writes them), read as numbers. */
+    JSON_NONSTANDARD_NUMBER: "W_JSON_NONSTANDARD_NUMBER";
+    /** The file's style rules are not applied; they are kept so a CX2 export writes them back. */
     STYLES_NOT_IMPORTED: "W_STYLES_NOT_IMPORTED";
-    /** A member of the top-level array that is not a one-key aspect block, or an element that is not an object. */
+    /**
+     * A member of the file's top-level array that is not a block with one key (`{"nodes": [...]}`), or an element of a
+     * block that is not an object. It is skipped; the rest of the file is read.
+     */
     BAD_ASPECT_BLOCK: "E_BAD_ASPECT_BLOCK";
     /** An aspect out of its place (after the post-metadata or the status, a third metaData, late declarations). */
     ASPECT_ORDER: "W_ASPECT_ORDER";
@@ -117,26 +146,44 @@ export declare const CX2_ISSUE: Readonly<{
     INVALID_WEIGHT: "E_INVALID_WEIGHT";
     /** An id spelled as a string or a non-integer literal; read as the integer. */
     ID_TEXT_TYPE: "W_ID_TEXT_TYPE";
-    /** An integer beyond 2^53: an id kept as its digits, a value stored as the nearest f64. */
+    /** An integer beyond 2^53 was stored as the nearest 64-bit float; pass `long: "string"` to keep every digit. */
     PRECISION: "W_PRECISION";
     /** Two id texts merged under `ids: "number"`. */
     ID_MERGED: "W_ID_MERGED";
     /** An element key CX2 does not define. */
     UNKNOWN_ELEMENT: "W_UNKNOWN_ELEMENT";
-    /** A column renamed because its name was taken. */
+    /**
+     * An attribute was renamed `<name>#<suffix>` because another attribute already has its name, for example
+     * two attributes declared with the same name.
+     */
     COLUMN_RENAMED: "W_COLUMN_RENAMED";
-    /** A column that lost its role because another column 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: "W_ROLE_TAKEN";
-    /** The sink refused the 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: "W_DIRECTION_REFUSED";
-    /** Edges forced to the policy's direction. */
+    /** Edges of the other direction were read with the direction `onMixedDirection` chose. */
     DIRECTION_FORCED: "W_DIRECTION_FORCED";
-    /** A common option CX2 has no use for. */
+    /** You set an option this format does not use; it had no effect. The message names the option. */
     OPTION_IGNORED: "W_OPTION_IGNORED";
-    /** A builder option the caller's 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: "W_SINK_OPTION";
-    /** The input is beyond a size limit (fatal). */
+    /** The input is larger than graph-io's size limit. The import stops. */
     TOO_LARGE: "E_TOO_LARGE";
+    DUPLICATE_EDGE: "E_DUPLICATE_EDGE";
+    SELF_LOOP: "E_SELF_LOOP";
+    ENCODING_CONFLICT: "W_ENCODING_CONFLICT";
+    CONTROL_CHARACTER: "W_CONTROL_CHARACTER";
+    FOREIGN_FORMAT: "E_FOREIGN_FORMAT";
+    ISSUES_SUPPRESSED: "W_ISSUES_SUPPRESSED";
 }>;
 /** The canonical CX2 scalar types. */
 type Cx2Scalar = "string" | "long" | "integer" | "double" | "boolean";
@@ -153,16 +200,19 @@ interface Cx2Type {
  * Resolve a declared type text.
  * @param d - the `d` value
  * @returns the type, or null when CX2 does not define it
+ * @category Plugin helpers
  */
 export declare function cx2Type(d: string): Cx2Type | null;
 /**
  * Resolve the zAs option.
  * @param value - the option
  * @returns the mode; E_UNSUPPORTED for any other value
+ * @category Plugin helpers
  */
 export declare function zAsOption(value: unknown): "column" | "position";
 /**
- * The CX2 importer plugin (design section 1.3).
+ * The CX2 importer plugin.
+ * @category Built-in formats
  */
 export declare const cx2Importer: GraphImporter<Cx2ImportOptions>;
 export {};

package/dist/src/formats/cx2/importer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"importer.d.ts","sourceRoot":"","sources":["../../../../src/formats/cx2/importer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA4EH,OAAO,EAA4B,KAAK,aAAa,EAAuC,MAAM,gBAAgB,CAAC;AAEnH,uBAAuB;AACvB,eAAO,MAAM,UAAU,QAAQ,CAAC;AAEhC,yFAAyF;AACzF,eAAO,MAAM,qBAAqB,uBAAuB,CAAC;AAE1D,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,eAAe,CAAC;AAE7C,uDAAuD;AACvD,MAAM,WAAW,gBAAgB;IAC7B;;;OAGG;IACH,GAAG,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;CAC3C;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS;IAClB,kCAAkC;;IAElC,oCAAoC;;IAEpC,6BAA6B;;IAE7B,gFAAgF;;IAEhF,0DAA0D;;IAE1D,0DAA0D;;IAE1D,kGAAkG;;IAElG,wFAAwF;;IAExF,mFAAmF;;IAEnF,4DAA4D;;IAE5D,0DAA0D;;IAE1D,yEAAyE;;IAEzE,8FAA8F;;IAE9F,wFAAwF;;IAExF,mFAAmF;;IAEnF,6EAA6E;;IAE7E,oGAAoG;;IAEpG,mGAAmG;;IAEnG,yEAAyE;;IAEzE,8EAA8E;;IAE9E,0FAA0F;;IAE1F,gFAAgF;;IAEhF,2DAA2D;;IAE3D,+GAA+G;;IAE/G,+GAA+G;;IAE/G,6DAA6D;;IAE7D,wEAAwE;;IAExE,uDAAuD;;IAEvD,mFAAmF;;IAEnF,yDAAyD;;IAEzD,6EAA6E;;IAE7E,4BAA4B;;IAE5B,8BAA8B;;IAE9B,kEAAkE;;IAElE,6DAA6D;;IAE7D,oCAAoC;;IAEpC,4EAA4E;;IAE5E,qCAAqC;;IAErC,+EAA+E;;IAE/E,2FAA2F;;IAE3F,iDAAiD;;IAEjD,0CAA0C;;IAE1C,mDAAmD;;IAEnD,mEAAmE;;IAEnE,sCAAsC;;IAEtC,8CAA8C;;IAE9C,0CAA0C;;IAE1C,0DAA0D;;IAE1D,gDAAgD;;EAElD,CAAC;AAgDH,sCAAsC;AACtC,KAAK,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEtE,2BAA2B;AAC3B,UAAU,OAAO;IACb,kDAAkD;IAClD,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CAC1B;AAeD;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAOjD;AA4xDD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,UAAU,CAW/D;AAED;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,aAAa,CAAC,gBAAgB,CAwCtD,CAAC"}
+{"version":3,"file":"importer.d.ts","sourceRoot":"","sources":["../../../../src/formats/cx2/importer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAuFH,OAAO,EAAE,KAAK,mBAAmB,EAAE,KAAK,aAAa,EAAuC,MAAM,gBAAgB,CAAC;AAEnH;;;GAGG;AACH,eAAO,MAAM,UAAU,QAAQ,CAAC;AAEhC;;;GAGG;AACH,eAAO,MAAM,qBAAqB,uBAAuB,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,gBAAgB,eAAe,CAAC;AAE7C;;;GAGG;AACH,MAAM,WAAW,gBAAiB,SAAQ,mBAAmB;IACzD;;;;OAIG;IACH,GAAG,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;CAC3C;AAED;;;;;GAKG;AACH,eAAO,MAAM,SAAS;IAGlB,4CAA4C;;IAE5C,oDAAoD;;IAEpD,sDAAsD;;IAEtD;;;OAGG;;IAEH,0DAA0D;;IAE1D,0DAA0D;;IAE1D;;;OAGG;;IAEH,iHAAiH;;IAEjH,mFAAmF;;IAEnF,4DAA4D;;IAE5D,kGAAkG;;IAElG,yEAAyE;;IAEzE,8FAA8F;;IAE9F,wFAAwF;;IAExF,mFAAmF;;IAEnF,6EAA6E;;IAE7E,oGAAoG;;IAEpG,mGAAmG;;IAEnG,yEAAyE;;IAEzE,8EAA8E;;IAE9E,0FAA0F;;IAE1F,gFAAgF;;IAEhF,gGAAgG;;IAEhG,wFAAwF;;IAExF,+FAA+F;;IAE/F,8FAA8F;;IAE9F;;;OAGG;;IAEH,+GAA+G;;IAE/G,6DAA6D;;IAE7D,wEAAwE;;IAExE,uDAAuD;;IAEvD,mFAAmF;;IAEnF,yDAAyD;;IAEzD,6EAA6E;;IAE7E,4BAA4B;;IAE5B,8BAA8B;;IAE9B,kEAAkE;;IAElE,6DAA6D;;IAE7D,oCAAoC;;IAEpC,4EAA4E;;IAE5E,qCAAqC;;IAErC,+EAA+E;;IAE/E,gHAAgH;;IAEhH,iDAAiD;;IAEjD,0CAA0C;;IAE1C;;;OAGG;;IAEH;;;OAGG;;IAEH;;;OAGG;;IAEH,0FAA0F;;IAE1F,kGAAkG;;IAElG;;;OAGG;;IAEH,wEAAwE;;;;;;;;EAE1E,CAAC;AA4DH,sCAAsC;AACtC,KAAK,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEtE,2BAA2B;AAC3B,UAAU,OAAO;IACb,kDAAkD;IAClD,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CAC1B;AAeD;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAOjD;AA67DD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,UAAU,CAW/D;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,aAAa,CAAC,gBAAgB,CAyCtD,CAAC"}