@graphty/graph-io 0.3.24 → 0.3.26

package/docs/samples/got.net

@@ -0,0 +1,461 @@
+*Vertices 107
+1 Aemon
+2 Grenn
+3 Samwell
+4 Aerys
+5 Jaime
+6 Robert
+7 Tyrion
+8 Tywin
+9 Alliser
+10 Mance
+11 Amory
+12 Oberyn
+13 Arya
+14 Anguy
+15 Beric
+16 Bran
+17 Brynden
+18 Cersei
+19 Gendry
+20 Gregor
+21 Joffrey
+22 Jon
+23 Rickon
+24 Roose
+25 Sandor
+26 Thoros
+27 Balon
+28 Loras
+29 Belwas
+30 Barristan
+31 Illyrio
+32 Hodor
+33 Jojen
+34 Luwin
+35 Meera
+36 Nan
+37 Theon
+38 Brienne
+39 Bronn
+40 Podrick
+41 Lothar
+42 Walder
+43 Catelyn
+44 Edmure
+45 Hoster
+46 Jeyne
+47 Lysa
+48 Petyr
+49 Robb
+50 Roslin
+51 Sansa
+52 Stannis
+53 Elia
+54 Ilyn
+55 Meryn
+56 Pycelle
+57 Shae
+58 Varys
+59 Craster
+60 Karl
+61 Daario
+62 Drogo
+63 Irri
+64 Daenerys
+65 Aegon
+66 Jorah
+67 Kraznys
+68 Missandei
+69 Rakharo
+70 Rhaegar
+71 Viserys
+72 Worm
+73 Davos
+74 Cressen
+75 Salladhor
+76 Eddard
+77 Eddison
+78 Gilly
+79 Qyburn
+80 Renly
+81 Tommen
+82 Janos
+83 Bowen
+84 Kevan
+85 Margaery
+86 Myrcella
+87 Dalla
+88 Melisandre
+89 Orell
+90 Qhorin
+91 Rattleshirt
+92 Styr
+93 Val
+94 Ygritte
+95 "Jon Arryn"
+96 Lancel
+97 Olenna
+98 Marillion
+99 "Robert Arryn"
+100 Ellaria
+101 Mace
+102 Rickard
+103 Ramsay
+104 Chataya
+105 Shireen
+106 Doran
+107 Walton
+*Edges
+1 2 5
+1 3 31
+4 5 18
+4 6 6
+4 7 5
+4 8 8
+9 10 5
+11 12 5
+13 14 11
+13 15 23
+13 16 9
+13 17 6
+13 18 5
+13 19 43
+13 20 7
+13 5 11
+13 21 6
+13 22 7
+13 23 8
+13 6 4
+13 24 5
+13 25 46
+13 26 18
+13 7 5
+27 28 4
+29 30 18
+29 31 10
+15 14 4
+15 19 4
+15 26 21
+16 32 96
+16 33 46
+16 22 12
+16 34 4
+16 35 54
+16 36 14
+16 23 35
+16 3 11
+16 37 11
+38 28 7
+39 20 5
+39 40 19
+17 41 4
+17 42 5
+43 16 4
+43 38 7
+43 17 8
+43 18 4
+43 44 16
+43 45 9
+43 5 19
+43 46 10
+43 47 8
+43 48 5
+43 49 43
+43 24 4
+43 50 6
+43 51 8
+43 52 4
+43 7 5
+43 42 19
+18 38 5
+18 39 4
+18 53 4
+18 20 6
+18 54 7
+18 5 36
+18 21 23
+18 55 10
+18 56 4
+18 6 16
+18 25 6
+18 57 4
+18 7 46
+18 58 4
+59 60 6
+61 62 4
+61 63 5
+64 65 8
+64 30 20
+64 29 26
+64 61 14
+64 62 18
+64 63 17
+64 66 47
+64 67 10
+64 68 26
+64 69 7
+64 70 12
+64 6 5
+64 71 8
+64 72 14
+73 74 4
+73 75 16
+76 13 18
+76 15 8
+76 16 15
+76 43 5
+76 18 6
+76 5 6
+76 22 8
+76 23 8
+76 49 13
+76 6 10
+76 25 5
+76 51 6
+77 2 8
+44 17 7
+44 41 4
+44 50 16
+44 42 9
+19 26 7
+78 59 17
+20 53 9
+20 54 7
+20 55 7
+20 12 24
+20 25 12
+32 33 35
+32 35 41
+45 44 9
+63 62 7
+5 27 6
+5 30 4
+5 38 88
+5 44 5
+5 53 4
+5 20 6
+5 21 15
+5 28 16
+5 55 11
+5 79 11
+5 80 7
+5 6 17
+5 52 5
+5 81 8
+5 7 31
+82 9 9
+82 83 5
+82 10 4
+21 20 5
+21 54 4
+21 84 8
+21 28 7
+21 85 28
+21 55 5
+21 86 5
+21 12 4
+21 25 14
+21 52 10
+21 81 9
+21 7 54
+33 35 33
+33 3 11
+22 1 30
+22 9 15
+22 59 7
+22 87 6
+22 77 4
+22 78 9
+22 2 25
+22 82 8
+22 10 69
+22 35 4
+22 88 7
+22 89 6
+22 90 31
+22 91 20
+22 6 5
+22 3 52
+22 52 9
+22 92 16
+22 37 8
+22 93 12
+22 94 54
+95 47 5
+95 6 6
+66 30 11
+66 29 13
+66 61 7
+66 62 6
+84 96 7
+84 58 5
+28 85 9
+28 97 5
+41 50 4
+34 36 4
+47 18 4
+47 45 6
+47 98 10
+47 48 29
+47 99 9
+47 7 5
+47 8 4
+10 59 11
+10 87 8
+10 78 7
+10 90 10
+10 91 9
+10 92 7
+10 93 8
+10 94 12
+35 3 7
+88 73 30
+88 3 5
+55 54 5
+68 63 4
+86 81 5
+86 7 4
+12 100 6
+12 101 6
+40 85 4
+91 90 6
+80 28 8
+80 85 7
+80 58 4
+70 30 5
+70 53 7
+70 66 5
+70 6 6
+102 17 4
+23 37 8
+49 13 15
+49 27 6
+49 16 23
+49 38 6
+49 17 17
+49 44 32
+49 32 5
+49 5 15
+49 46 18
+49 21 10
+49 22 14
+49 41 10
+49 48 5
+49 103 4
+49 102 7
+49 23 15
+49 24 4
+49 51 15
+49 52 4
+49 37 11
+49 7 12
+49 8 12
+49 42 26
+6 1 4
+6 30 5
+6 80 4
+6 52 5
+6 26 4
+99 98 4
+24 38 4
+3 83 6
+3 59 34
+3 77 12
+3 78 36
+3 2 43
+3 82 6
+3 10 10
+3 90 5
+25 15 15
+25 19 5
+25 54 4
+25 55 4
+25 6 6
+25 26 10
+51 13 22
+51 16 10
+51 38 5
+51 18 16
+51 5 10
+51 21 35
+51 22 4
+51 84 5
+51 28 14
+51 47 28
+51 85 36
+51 98 9
+51 86 4
+51 97 7
+51 48 28
+51 40 8
+51 80 4
+51 23 7
+51 6 5
+51 99 6
+51 25 6
+51 57 8
+51 7 77
+57 104 4
+57 58 8
+105 73 5
+52 1 4
+52 27 4
+52 73 32
+52 88 20
+52 80 15
+52 3 13
+81 85 5
+7 27 4
+7 39 31
+7 104 5
+7 106 5
+7 53 5
+7 100 4
+7 20 22
+7 54 5
+7 82 5
+7 84 11
+7 28 6
+7 101 9
+7 85 7
+7 55 5
+7 12 25
+7 48 12
+7 40 28
+7 56 11
+7 80 6
+7 6 9
+7 25 4
+7 57 21
+7 52 6
+7 58 18
+8 27 5
+8 17 4
+8 18 16
+8 20 7
+8 5 13
+8 21 13
+8 84 14
+8 101 5
+8 12 6
+8 48 4
+8 40 5
+8 56 5
+8 6 11
+8 52 15
+8 81 4
+8 7 39
+8 93 4
+8 58 6
+8 42 4
+93 87 7
+58 56 4
+71 70 7
+71 7 4
+42 41 12
+42 48 6
+42 50 6
+107 5 10
+94 90 7
+94 91 9

package/docs/samples/movies-nodes.csv

@@ -0,0 +1,9 @@
+movieId:ID(Movie),title,released:int,:LABEL
+m1,The Matrix,1999,Movie
+m2,"Matrix, Reloaded",2003,Movie;Sequel
+m3,Cloud Atlas,2012,Movie
+personId:ID(Person),name,born:int,:LABEL
+p1,Keanu Reeves,1964,Person;Actor
+p2,Carrie-Anne Moss,1967,Person;Actor
+p3,Lana Wachowski,1965,Person;Director
+p4,Tom Hanks,1956,Person;Actor

package/docs/samples/movies-rels.csv

@@ -0,0 +1,8 @@
+:START_ID(Person),:END_ID(Movie),:TYPE,roles:string[]
+p1,m1,ACTED_IN,Neo
+p1,m2,ACTED_IN,Neo
+p2,m1,ACTED_IN,Trinity
+p4,m3,ACTED_IN,Zachry;Dr. Henry Goose
+:START_ID(Person),:END_ID(Person),:TYPE
+p3,p1,DIRECTED_WITH
+p2,p1,KNOWS

package/docs/samples/proteins.xgmml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<graph id="1" label="Network" directed="1" cy:documentVersion="3.0" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:cy="http://www.cytoscape.org" xmlns="http://www.cs.rpi.edu/XGMML">
+  <att name="name" value="small" type="string" cy:type="String"/>
+  <node id="1" label="A"><att name="name" value="A" type="string" cy:type="String"/><att name="score" value="0.5" type="real" cy:type="Double"/><att name="degree" value="2" type="integer" cy:type="Integer"/><graphics type="ELLIPSE" x="10" y="20" z="0" fill="#FF0000"/></node>
+  <node id="2" label="B"><att name="name" value="B" type="string" cy:type="String"/><att name="score" value="1.5" type="real" cy:type="Double"/><att name="degree" value="1" type="integer" cy:type="Integer"/><graphics type="ELLIPSE" x="30" y="40" z="0" fill="#00FF00"/></node>
+  <node id="3" label="C"><att name="name" value="C" type="string" cy:type="String"/><att name="degree" value="1" type="integer" cy:type="Integer"/><graphics type="RECTANGLE" x="50" y="0" z="0"/></node>
+  <edge id="4" label="A (pp) B" source="1" target="2" cy:directed="1"><att name="interaction" value="pp" type="string" cy:type="String"/></edge>
+  <edge id="5" label="A (pd) C" source="1" target="3" cy:directed="1"><att name="interaction" value="pd" type="string" cy:type="String"/></edge>
+</graph>

package/docs/samples/teams.gv

@@ -0,0 +1,24 @@
+digraph handoffs {
+    label = "Who hands work to whom";
+
+    subgraph cluster_design {
+        label = "Design";
+        style = filled;
+        color = lightgrey;
+        ana; ben;
+    }
+
+    subgraph cluster_build {
+        label = "Build";
+        cara; dev; eli;
+    }
+
+    start -> ana;
+    ana -> ben -> cara;
+    cara -> dev -> eli;
+    eli -> ana [style = dashed, label = "feedback"];
+    eli -> release;
+
+    start [shape = Mdiamond];
+    release [shape = Msquare];
+}

package/docs/samples/vehicles.obo

@@ -0,0 +1,25 @@
+format-version: 1.2
+ontology: vehicles
+
+[Term]
+id: VEH:0000001
+name: vehicle
+
+[Term]
+id: VEH:0000002
+name: road vehicle
+is_a: VEH:0000001 ! vehicle
+
+[Term]
+id: VEH:0000003
+name: car
+is_a: VEH:0000002 ! road vehicle
+
+[Term]
+id: VEH:0000004
+name: wheel
+relationship: part_of VEH:0000002 ! road vehicle
+
+[Typedef]
+id: part_of
+name: part of

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@graphty/graph-io",
-  "version": "0.3.24",
-  "description": "Importers and exporters (GEXF, GraphML, GML, DOT, Pajek, CSV, JSON, Neo4j) for the @graphty/graph-format snapshot",
+  "version": "0.3.26",
+  "description": "Read and write 13 graph file formats (JSON, GraphML, GEXF, CSV, GML, DOT, Pajek, Neo4j CSV, XGMML, CX2, CX, OBO, Cytoscape sessions) as @graphty/graph-format snapshots",
   "author": "Adam Powers <apowers@ato.ms>",
   "type": "module",
   "main": "dist/graph-io.js",
@@ -83,6 +83,7 @@
     "dist/",
     "!dist/*.tsbuildinfo",
     "src/",
+    "docs/samples/",
     "README.md",
     "LICENSE"
   ],
@@ -118,9 +119,9 @@
   "bugs": {
     "url": "https://github.com/graphty-org/graphty-monorepo/issues"
   },
-  "homepage": "https://github.com/graphty-org/graphty-monorepo/tree/master/graph-io#readme",
+  "homepage": "https://graphty.app/docs/graph-io/",
   "dependencies": {
-    "@graphty/graph-format": "^1.3.4"
+    "@graphty/graph-format": "^1.3.6"
   },
   "peerDependencies": {
     "@graphty/graph-format": "^1.0.0"
@@ -131,7 +132,9 @@
     "eslint": "^9.29.0",
     "fast-check": "^4.2.0",
     "fast-xml-parser": "^5.11.1",
+    "prettier": "^3.4.2",
     "tsx": "^4.20.3",
+    "typedoc": "^0.28.15",
     "typescript": "^5.9.3",
     "vite": "^7.0.5",
     "vitest": "4.1.11"
@@ -150,6 +153,8 @@
     "coverage": "vitest run --coverage",
     "coverage:preview": "npx serve coverage -p ${PORT:?start it through servherd, which sets PORT}",
     "benchmark": "tsx benchmarks/run.ts",
+    "docs:reference": "tsx scripts/docs-reference.ts",
+    "docs:api": "tsx scripts/docs-reference.ts --check && typedoc && node ../tools/sanitize-api-docs.js docs/api/generated",
     "ready:commit": "npm run build:all && npm run lint && npm run typecheck:strict-consumer && npm run test:run"
   }
 }

package/src/children.ts

@@ -1,5 +1,5 @@
 /**
- * The children CSR over a containment column (design sections 5.10, 7.1 and 8.2): containment
+ * The children CSR over a containment column: containment
  * (GEXF `pid` / `<parents>`, Cytoscape `parent`, DOT clusters, GraphML nested graphs) is a node
  * column with the `parent` role (u32, refersTo node) or the `parents` role (list of u32) and never
  * enters the CSR of the snapshot. Importers and exporters that need to walk containers top-down
@@ -16,10 +16,16 @@
 
 import { type Column, type GraphSnapshot, INVALID_INDEX } from "@graphty/graph-format";
 
-/** The role of the column a children CSR is built over. */
+/**
+ * The role of the column a children CSR is built over.
+ * @category Plugin helpers
+ */
 export type ContainmentRole = "parent" | "parents";
 
-/** How the CSR is built: from a role column of the snapshot (default `parent`, then `parents`) or an explicit column. */
+/**
+ * How the CSR is built: from a role column of the snapshot (default `parent`, then `parents`) or an explicit column.
+ * @category Plugin helpers
+ */
 export interface ChildrenOptions {
     /**
      * The column to read: a role name (`parent` for the u32 single-parent column, `parents` for
@@ -30,7 +36,10 @@ export interface ChildrenOptions {
     readonly column?: ContainmentRole | Column | "auto" | null | undefined;
 }
 
-/** One depth-first traversal of the containment forest. */
+/**
+ * One depth-first traversal of the containment forest.
+ * @category Plugin helpers
+ */
 export interface DepthFirstOrder {
     /** Every node index exactly once: roots in index order, each followed by its descendants, cycle members last. */
     readonly order: Uint32Array;
@@ -41,8 +50,9 @@ export interface DepthFirstOrder {
 }
 
 /**
- * The children CSR of a snapshot's containment column (design sections 5.10 and 7.1): the inverse
+ * The children CSR of a snapshot's containment column: the inverse
  * of the parent relation as a compressed sparse row structure over node indices.
+ * @category Plugin helpers
  */
 export class ChildrenCsr {
     /** The number of nodes (the row count of the CSR). */
@@ -247,10 +257,11 @@ export class ChildrenCsr {
 }
 
 /**
- * Build the children CSR of a snapshot (design section 7.1: a graph-io helper, not a core view).
+ * Build the children CSR of a snapshot.
  * @param snapshot - the snapshot
  * @param options - which column to read; the `parent` role, then `parents`, by default
  * @returns the CSR; empty (every node a root) when the snapshot has no containment column
+ * @category Plugin helpers
  */
 export function childrenCsr(snapshot: GraphSnapshot, options: ChildrenOptions = {}): ChildrenCsr {
     const column = resolveColumn(snapshot, options.column === undefined ? "auto" : options.column);
@@ -263,6 +274,7 @@ export function childrenCsr(snapshot: GraphSnapshot, options: ChildrenOptions =
  * @param nodeCount - the node count the references index into
  * @param column - a u32 `parent`-shaped column, a list-of-u32 `parents`-shaped column, or null for none
  * @returns the CSR
+ * @category Plugin helpers
  */
 export function childrenFromColumn(nodeCount: number, column: Column | null): ChildrenCsr {
     const rowPtr = new Uint32Array(nodeCount + 1);