@loaders.gl/graphs 5.0.0-alpha.9 → 5.0.0-beta.1

package/LICENSE

@@ -0,0 +1,24 @@
+loaders.gl is licensed under the MIT license
+
+Copyright (c) vis.gl contributors
+Copyright (c) 2015 Uber Technologies, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+For adapted portions, see THIRD-PARTY-NOTICES.md and the applicable upstream terms.

package/README.md

@@ -1,6 +1,65 @@
 # @loaders.gl/graphs
 
-Framework-independent loaders for GraphML and Graphviz DOT documents.
+Framework-independent loaders for GraphML, Graphviz DOT, and GEXF documents.
+
+## Graph output shapes
+
+Graph loaders default to `graphml.shape: 'arrow-table'`, `dot.shape: 'arrow-table'`,
+or `gexf.shape: 'arrow-table'`.
+The result uses the standard table collection shape:
+
+```typescript
+{
+  shape: 'tables',
+  tables: [
+    {name: 'nodes', table: {shape: 'arrow-table', schema, data: nodes}},
+    {name: 'edges', table: {shape: 'arrow-table', schema, data: edges}}
+  ]
+}
+```
+
+Each `data` is an Apache Arrow `Table`; each `schema` is a loaders.gl schema.
+The node table has `id`, nullable `label`, and nullable `attributes` columns.
+The edge table additionally has `sourceId`, `targetId`, and `directed`.
+Structural identifiers are strings, including numeric DOT edge IDs. Row order follows
+document order after DOT strict-edge coalescing. Edges may reference undeclared nodes;
+the loaders preserve their endpoints without inventing GraphML nodes.
+
+Application attributes live in a typed `attributes` struct, so keys such as `id` cannot
+replace structural columns. GraphML declarations determine Boolean, Int32, Int64,
+Float32, Float64, and Utf8 fields, including unused declarations on empty graphs.
+GraphML `long` values are parsed as exact integers and read as `bigint`.
+Invalid or out-of-range integer values make the affected attribute column Utf8,
+preserving values as strings. DOT scalar types are inferred across the whole column;
+numbers use Float64, booleans use Bool, and mixed scalar types use Utf8. Nested DOT
+subgraph membership uses List and Struct columns. Missing values become Arrow nulls.
+Empty undeclared attributes have a Struct with no child fields.
+
+```typescript
+const graph = await load('network.graphml', GraphMLLoader);
+if (graph.shape === 'tables' && graph.tables[0].table.shape === 'arrow-table') {
+  const nodes = graph.tables[0].table.data;
+  console.log(nodes.getChild('id')?.get(0));
+}
+```
+
+Select `'object-row-table'` for the same named table collection with object arrays in
+`table.data`. This mode also preserves GraphML long values as `bigint`; it retains original
+application attribute values rather than applying Arrow column normalization.
+
+For compatibility with existing graph-layer consumers, request plain graph records:
+
+```typescript
+const graph = await load('network.graphml', GraphMLLoader, {
+  graphml: {shape: 'plain-graph-data'}
+});
+// DOT: {dot: {shape: 'plain-graph-data'}}
+```
+
+Plain output retains `shape: 'plain-graph-data'`, `nodes`, and `edges`, with original
+DOT edge ID types. GraphML long values in this compatibility mode remain JavaScript
+numbers and can lose precision outside the safe integer range.
+DOT graph metadata is available as `graph.metadata` in every output shape.
 
 ## GraphML loader
 
@@ -17,7 +76,7 @@ For synchronous parsing, import `GraphMLLoaderWithParser` from
 `@loaders.gl/graphs/graphml-loader` and pass it to `parseSync` from `@loaders.gl/core`.
 The package root exports metadata only; asynchronous core APIs preload the implementation.
 
-The result is `GraphData` with `shape: 'plain-graph-data'`, `nodes`, and `edges`.
+The explicit plain compatibility result is `GraphData` with `shape: 'plain-graph-data'`, `nodes`, and `edges`.
 Nodes have `id`, optional `label`, and optional `attributes`. Edges additionally have
 `sourceId`, `targetId`, and `directed`. This shape is compatible with
 `createGraphFromData` in `@deck.gl-community/graph-layers`.
@@ -25,7 +84,7 @@ Nodes have `id`, optional `label`, and optional `attributes`. Edges additionally
 Supported constructs include node and edge identifiers, generated IDs for unnamed edges,
 `edgedefault` and per-edge direction overrides, node/edge/all keys, typed data and defaults,
 unknown data keys, and namespace-prefixed elements. Numeric and boolean keys become JavaScript
-values; other values remain strings. Nested XML data becomes a JSON string.
+values; string values preserve their whitespace. Nested XML data becomes a JSON string.
 
 Only the first graph is returned. Nested graphs, hyperedges, ports, and graph-level data are
 ignored. Nodes without IDs and edges without endpoints are skipped. This is a permissive
@@ -45,8 +104,10 @@ const graph = await load('network.dot', DOTLoader);
 Use `DOTLoaderWithParser` from `@loaders.gl/graphs/dot-loader` with `parseSync`
 for synchronous text or UTF-8 `ArrayBuffer` parsing. `DOTLoader` recognizes `.dot` and `.gv` files.
 
-The loader returns the same plain `GraphData` node/edge shape as GraphML, plus typed
+The loader returns the same named node/edge table collection as GraphML, plus typed
 DOT metadata: graph ID, direction, strictness, graph attributes, and subgraph descriptors.
+Unknown backslash sequences are preserved for downstream attribute interpretation.
+Backslashes followed by physical line endings join quoted identifiers and labels across lines.
 Identifiers remain strings, including numeric-looking IDs. Unquoted numeric attributes
 become numbers; quoted attributes remain strings. Node and edge `label` attributes are
 also exposed as record labels.
@@ -64,3 +125,59 @@ This is a parser for the supported DOT subset, not a Graphviz renderer. Node por
 subgraph endpoints in edge statements, and concatenated quoted strings are unsupported.
 Port syntax is rejected; identifiers containing colons must be quoted. Truncated input,
 trailing content, and edge operators inconsistent with the graph declaration are rejected.
+
+## GEXF loader
+
+`GEXFLoader` reads static GEXF 1.2 (including `1.2draft`) and 1.3 documents.
+
+```typescript
+import {load} from '@loaders.gl/core';
+import {GEXFLoader} from '@loaders.gl/graphs';
+
+const graph = await load('network.gexf', GEXFLoader);
+// Optional: {gexf: {shape: 'object-row-table'}} or {gexf: {shape: 'plain-graph-data'}}
+```
+
+For synchronous parsing, use `GEXFLoaderWithParser` from
+`@loaders.gl/graphs/gexf-loader` with `parseSync`. The package root exports metadata
+only; asynchronous core APIs preload the parser. Text and UTF-8 binary inputs are supported.
+The loader recognizes `.gexf` and `application/gexf+xml`.
+
+The default result contains named Arrow node and edge tables in the standard `tables`
+collection. Application attributes use declaration titles inside the `attributes` struct;
+node and edge declarations are scoped separately. Boolean, integer, long, float, double,
+and string declarations retain their Arrow types, even for empty graphs. Byte and short
+attributes use Int32. `anyURI`, date, char, bigdecimal, and biginteger values retain their text
+as Utf8. Long integers remain exact `bigint` values in every output shape, including
+plain records. Invalid or out-of-range scalar values promote the affected Arrow field
+to Utf8, preserving the original text.
+
+List attributes become typed Arrow Lists, including unused declarations. Both bracketed
+comma-separated lists and legacy pipe/comma/semicolon-separated values are accepted.
+Single and double quotes preserve embedded delimiters and whitespace; malformed
+list quoting is rejected. An empty value becomes an empty list. Defaults apply before explicit values; absent
+attributes without defaults become Arrow nulls. String values and labels preserve whitespace.
+
+Native edge weight and kind properties are retained under `attributes.gexf.weight` and
+`attributes.gexf.kind`. Namespaced color, position, size, shape, and thickness elements
+are retained as nested structs under `attributes.gexf.viz`, with numeric coordinates,
+color components, sizes, and thicknesses. Shape names, image URIs, and hex colors remain
+strings. The application attribute title `gexf` is reserved to prevent collisions.
+
+`graph.metadata` contains the document version, default direction, and an `attributes`
+object with creator, description, keywords, and lastmodifieddate when supplied.
+Directed and undirected edges, per-edge direction overrides, self-loops, and parallel
+edges are preserved in document order. IDs remain strings; missing edge IDs receive
+stable `edge-<index>` identifiers that avoid collisions with supplied IDs.
+
+This is a static graph parser, not a complete GEXF schema validator. Dynamic graphs,
+slice graphs, temporal values/spells, hierarchical/parent structures, mutual edges,
+unsupported attribute types, and document type declarations are rejected explicitly.
+Duplicate IDs or attribute declarations, undeclared application attributes, missing
+required record attributes, and endpoints referencing undeclared nodes are rejected.
+Foreign namespace extensions are ignored. See the [GEXF specification](https://gexf.net/schema.html).
+
+## Sources and credits
+
+See [THIRD-PARTY-NOTICES.md](./THIRD-PARTY-NOTICES.md) for implementation lineage
+and applicable notices, and the project-wide [References and credits](https://loaders.gl/docs/references-and-credits).

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,17 @@
+# @loaders.gl/graphs: sources and credits
+
+Graph loaders are developed by vis.gl contributors against DOT, GEXF and GraphML format definitions. Separately installed fast-xml-parser supplies XML parsing; Apache Arrow supplies columnar tables.
+
+## Scope and maintenance
+
+Original loaders.gl contributions are covered by [LICENSE](./LICENSE). The upstream
+notices above apply to their respective portions and do not change those terms.
+Source adaptations, separately installed libraries, format definitions and test
+data are different contributions. This index is not a transitive dependency
+bill of materials. Runtime dependencies can bring additional notices.
+
+Version information is recorded where the repository preserves it. Unpinned
+historical ports are identified by retained source and Git history; no upstream
+version is inferred from a current dependency. Keep copyright headers, full
+terms, source/version information and material modification notes when updating.
+Retain this file and the applicable licenses when redistributing bundles or workers.

package/dist/dot-loader-types.d.ts

@@ -1,9 +1,18 @@
-import type { DOTGraphData } from "./dot-types.js";
+import type { DOTOutput } from "./dot-types.js";
+import type { GraphShape } from "./graph-types.js";
+/** Options for selecting the DOT graph output representation. */
+export type DOTLoaderOptions = {
+    /** Format-specific graph options. */
+    dot?: {
+        /** Representation of each named table; defaults to Arrow. */
+        shape?: GraphShape;
+    };
+};
 /** Preloads the DOT parser implementation. */
 declare function preload(): Promise<{
-    parse: (data: ArrayBuffer) => Promise<DOTGraphData>;
-    parseSync: (data: ArrayBuffer) => DOTGraphData;
-    parseTextSync: typeof import("./lib/parse-dot").parseDOT;
+    parse: (data: ArrayBuffer, options?: DOTLoaderOptions) => Promise<DOTOutput>;
+    parseSync: (data: ArrayBuffer, options?: DOTLoaderOptions) => DOTOutput;
+    parseTextSync: (data: string, options?: DOTLoaderOptions) => DOTOutput;
     name: "DOT";
     id: "dot";
     module: "graphs";
@@ -12,9 +21,13 @@ declare function preload(): Promise<{
     mimeTypes: ["text/vnd.graphviz", "text/x-graphviz", "application/vnd.graphviz"];
     text: true;
     worker: false;
-    dataType: DOTGraphData;
+    dataType: DOTOutput;
     batchType: never;
-    options: {};
+    options: {
+        readonly dot: {
+            readonly shape: "arrow-table";
+        };
+    };
     preload: typeof preload;
 }>;
 /** Metadata-only loader for Graphviz DOT documents. */
@@ -27,9 +40,13 @@ export declare const DOTLoader: {
     readonly mimeTypes: ["text/vnd.graphviz", "text/x-graphviz", "application/vnd.graphviz"];
     readonly text: true;
     readonly worker: false;
-    readonly dataType: DOTGraphData;
+    readonly dataType: DOTOutput;
     readonly batchType: never;
-    readonly options: {};
+    readonly options: {
+        readonly dot: {
+            readonly shape: "arrow-table";
+        };
+    };
     readonly preload: typeof preload;
 };
 export {};

package/dist/dot-loader-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dot-loader-types.d.ts","sourceRoot":"","sources":["../src/dot-loader-types.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAC,YAAY,EAAC,uBAAoB;AAK9C,8CAA8C;AAC9C,iBAAe,OAAO;;;;;;;;;;;;cAeS,YAAY;eACtB,KAAK;;;GAbzB;AAED,uDAAuD;AACvD,eAAO,MAAM,SAAS;;;;;;;;;uBASS,YAAY;wBACtB,KAAK;;;CAGsB,CAAC"}
+{"version":3,"file":"dot-loader-types.d.ts","sourceRoot":"","sources":["../src/dot-loader-types.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAC,SAAS,EAAC,uBAAoB;AAC3C,OAAO,KAAK,EAAC,UAAU,EAAC,yBAAsB;AAE9C,iEAAiE;AACjE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,qCAAqC;IACrC,GAAG,CAAC,EAAE;QACJ,6DAA6D;QAC7D,KAAK,CAAC,EAAE,UAAU,CAAC;KACpB,CAAC;CACH,CAAC;AAKF,8CAA8C;AAC9C,iBAAe,OAAO;;;;;;;;;;;;cAeS,SAAS;eACnB,KAAK;;;;;;;GAbzB;AAED,uDAAuD;AACvD,eAAO,MAAM,SAAS;;;;;;;;;uBASS,SAAS;wBACnB,KAAK;;;;;;;CAGqC,CAAC"}

package/dist/dot-loader-types.js

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 // @ts-ignore __VERSION__ is injected by the build.
-const VERSION = typeof "5.0.0-alpha.9" !== 'undefined' ? "5.0.0-alpha.9" : 'latest';
+const VERSION = typeof "5.0.0-beta.1" !== 'undefined' ? "5.0.0-beta.1" : 'latest';
 /** Preloads the DOT parser implementation. */
 async function preload() {
     const { DOTLoaderWithParser } = await import('@loaders.gl/graphs/dot-loader');
@@ -20,7 +20,7 @@ export const DOTLoader = {
     worker: false,
     dataType: null,
     batchType: null,
-    options: {},
+    options: { dot: { shape: 'arrow-table' } },
     preload
 };
 //# sourceMappingURL=dot-loader-types.js.map

package/dist/dot-loader-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"dot-loader-types.js","sourceRoot":"","sources":["../src/dot-loader-types.ts"],"names":[],"mappings":"AAAA,aAAa;AACb,+BAA+B;AAC/B,oCAAoC;AAKpC,mDAAmD;AACnD,MAAM,OAAO,GAAG,sBAAkB,KAAK,WAAW,CAAC,CAAC,iBAAa,CAAC,CAAC,QAAQ,CAAC;AAE5E,8CAA8C;AAC9C,KAAK,UAAU,OAAO;IACpB,MAAM,EAAC,mBAAmB,EAAC,GAAG,MAAM,MAAM,CAAC,+BAA+B,CAAC,CAAC;IAC5E,OAAO,mBAAmB,CAAC;AAC7B,CAAC;AAED,uDAAuD;AACvD,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,IAAI,EAAE,KAAK;IACX,EAAE,EAAE,KAAK;IACT,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,OAAO;IAChB,UAAU,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC;IACzB,SAAS,EAAE,CAAC,mBAAmB,EAAE,iBAAiB,EAAE,0BAA0B,CAAC;IAC/E,IAAI,EAAE,IAAI;IACV,MAAM,EAAE,KAAK;IACb,QAAQ,EAAE,IAA+B;IACzC,SAAS,EAAE,IAAa;IACxB,OAAO,EAAE,EAAE;IACX,OAAO;CACuC,CAAC"}
+{"version":3,"file":"dot-loader-types.js","sourceRoot":"","sources":["../src/dot-loader-types.ts"],"names":[],"mappings":"AAAA,aAAa;AACb,+BAA+B;AAC/B,oCAAoC;AAepC,mDAAmD;AACnD,MAAM,OAAO,GAAG,qBAAkB,KAAK,WAAW,CAAC,CAAC,gBAAa,CAAC,CAAC,QAAQ,CAAC;AAE5E,8CAA8C;AAC9C,KAAK,UAAU,OAAO;IACpB,MAAM,EAAC,mBAAmB,EAAC,GAAG,MAAM,MAAM,CAAC,+BAA+B,CAAC,CAAC;IAC5E,OAAO,mBAAmB,CAAC;AAC7B,CAAC;AAED,uDAAuD;AACvD,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,IAAI,EAAE,KAAK;IACX,EAAE,EAAE,KAAK;IACT,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,OAAO;IAChB,UAAU,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC;IACzB,SAAS,EAAE,CAAC,mBAAmB,EAAE,iBAAiB,EAAE,0BAA0B,CAAC;IAC/E,IAAI,EAAE,IAAI;IACV,MAAM,EAAE,KAAK;IACb,QAAQ,EAAE,IAA4B;IACtC,SAAS,EAAE,IAAa;IACxB,OAAO,EAAE,EAAC,GAAG,EAAE,EAAC,KAAK,EAAE,aAAa,EAAC,EAAC;IACtC,OAAO;CACsD,CAAC"}