@loaders.gl/graphs 4.5.3 → 5.0.0-alpha.10

package/LICENSE

@@ -24,8 +24,20 @@ THE SOFTWARE.
 
 Copyright (c) 2015 Uber Technologies, Inc.
 
-loaders.gl includes certain files from Cesium (https://github.com/AnalyticalGraphicsInc/cesium) 
-under the  Apache 2 License (found in the submodule: modules/3d-tiles):)
+Portions of modules/images/src/lib/category-api/binary-image-api.ts are based on
+binary-gltf-utils (https://github.com/Qantas94Heavy/binary-gltf-utils) under the
+MIT License reproduced above.
+
+Copyright (c) 2016-17 Karl Cheng
+
+Portions of modules/schema-utils/src/lib/utils/async-queue.ts are adapted from
+async-iter-demo (https://github.com/rauschma/async-iter-demo) under the MIT
+License reproduced above.
+
+Copyright (c) 2016 Axel Rauschmayer
+
+loaders.gl includes certain files from Cesium (https://github.com/CesiumGS/cesium)
+under the Apache 2.0 License, including files in modules/3d-tiles.
 
 Copyright 2011-2018 CesiumJS Contributors
 
@@ -38,4 +50,3 @@ Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and limitations under the License.
-

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
 
@@ -13,11 +72,11 @@ import {GraphMLLoader} from '@loaders.gl/graphs';
 const graph = await load('network.graphml', GraphMLLoader);
 ```
 
-Pass `GraphMLLoader` to `parseSync` from `@loaders.gl/core` for synchronous parsing.
-The direct parser subpath also exports `GraphMLLoaderWithParser` from
-`@loaders.gl/graphs/graphml-loader`.
+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,13 +84,14 @@ 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
 parser, not a GraphML schema validator. Long integers use JavaScript numbers and may lose
 precision outside the safe integer range.
 
+
 ## DOT loader
 
 ```typescript
@@ -41,12 +101,13 @@ import {DOTLoader} from '@loaders.gl/graphs';
 const graph = await load('network.dot', DOTLoader);
 ```
 
-Pass `DOTLoader` to `parseSync` for synchronous text or UTF-8 `ArrayBuffer` parsing.
-The direct parser subpath also exports `DOTLoaderWithParser` from
-`@loaders.gl/graphs/dot-loader`. `DOTLoader` recognizes `.dot` and `.gv` files.
+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,54 @@ 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).

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

@@ -1,4 +1,35 @@
-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, options?: DOTLoaderOptions) => Promise<DOTOutput>;
+    parseSync: (data: ArrayBuffer, options?: DOTLoaderOptions) => DOTOutput;
+    parseTextSync: (data: string, options?: DOTLoaderOptions) => DOTOutput;
+    name: "DOT";
+    id: "dot";
+    module: "graphs";
+    version: any;
+    extensions: ["dot", "gv"];
+    mimeTypes: ["text/vnd.graphviz", "text/x-graphviz", "application/vnd.graphviz"];
+    text: true;
+    worker: false;
+    dataType: DOTOutput;
+    batchType: never;
+    options: {
+        readonly dot: {
+            readonly shape: "arrow-table";
+        };
+    };
+    preload: typeof preload;
+}>;
 /** Metadata-only loader for Graphviz DOT documents. */
 export declare const DOTLoader: {
     readonly name: "DOT";
@@ -9,8 +40,14 @@ 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 {};
 //# sourceMappingURL=dot-loader-types.d.ts.map

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,uDAAuD;AACvD,eAAO,MAAM,SAAS;;;;;;;;;uBASS,YAAY;wBACtB,KAAK;;CAEsB,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,12 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 // @ts-ignore __VERSION__ is injected by the build.
-const VERSION = typeof "4.5.3" !== 'undefined' ? "4.5.3" : 'latest';
+const VERSION = typeof "5.0.0-alpha.10" !== 'undefined' ? "5.0.0-alpha.10" : 'latest';
+/** Preloads the DOT parser implementation. */
+async function preload() {
+    const { DOTLoaderWithParser } = await import('@loaders.gl/graphs/dot-loader');
+    return DOTLoaderWithParser;
+}
 /** Metadata-only loader for Graphviz DOT documents. */
 export const DOTLoader = {
     name: 'DOT',
@@ -15,6 +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,cAAkB,KAAK,WAAW,CAAC,CAAC,SAAa,CAAC,CAAC,QAAQ,CAAC;AAE5E,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;CACmC,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,uBAAkB,KAAK,WAAW,CAAC,CAAC,kBAAa,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"}