@deck.gl-community/graph-layers 9.2.0-beta.2 → 9.2.0-beta.3

package/src/graph-data/arrow-graph-data-builder.ts

@@ -0,0 +1,165 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// eslint-disable-next-line import/no-unresolved
+import * as arrow from 'apache-arrow';
+
+import type {EdgeState, NodeState} from '../core/constants';
+import type {GraphEdgeData, GraphNodeData,ArrowGraphData} from './graph-data';
+import {
+  cloneRecord,
+  normalizeEdgeState,
+  normalizeNodeState,
+  normalizeVersion
+} from '../graph/graph-normalization';
+
+type Builder = ReturnType<typeof arrow.makeBuilder>;
+type ArrowVector = ReturnType<Builder['toVector']>;
+type ColumnArray = ReturnType<ArrowVector['toArray']>;
+type ColumnBuilderMap = Map<string, Builder>;
+
+export type ArrowGraphDataBuilderOptions = {
+  version?: number;
+};
+
+export class ArrowGraphDataBuilder {
+  private readonly nodeBuilders: ColumnBuilderMap = new Map();
+  private readonly edgeBuilders: ColumnBuilderMap = new Map();
+
+  private nodeLength = 0;
+  private edgeLength = 0;
+
+  private _version: number;
+
+  constructor(options: ArrowGraphDataBuilderOptions = {}) {
+    this._version = normalizeVersion(options.version);
+  }
+
+  get version(): number {
+    return this._version;
+  }
+
+  setVersion(version: unknown): void {
+    this._version = normalizeVersion(version);
+  }
+
+  addNode(node: GraphNodeData): number {
+    if (typeof node?.id === 'undefined') {
+      throw new Error('Graph node requires an "id" field.');
+    }
+
+    const index = this.nodeLength++;
+    const attributes = cloneRecord(node.attributes);
+
+    if (typeof node.label !== 'undefined') {
+      attributes.label = node.label;
+    }
+
+    if (typeof node.weight !== 'undefined') {
+      attributes.weight = node.weight;
+    }
+
+    const stateCandidate = node.state ?? (attributes.state as NodeState | undefined);
+    const selectableCandidate = node.selectable ?? (attributes.selectable as boolean | undefined);
+    const highlightCandidate =
+      node.highlightConnectedEdges ?? (attributes.highlightConnectedEdges as boolean | undefined);
+
+    this.appendUtf8(this.nodeBuilders, 'id', node.id);
+    this.appendUtf8(this.nodeBuilders, 'state', normalizeNodeState(stateCandidate));
+    this.appendBoolean(this.nodeBuilders, 'selectable', Boolean(selectableCandidate));
+    this.appendBoolean(this.nodeBuilders, 'highlightConnectedEdges', Boolean(highlightCandidate));
+    this.appendJson(this.nodeBuilders, 'data', attributes);
+
+    return index;
+  }
+
+  addEdge(edge: GraphEdgeData): number {
+    if (
+      typeof edge?.id === 'undefined' ||
+      typeof edge?.sourceId === 'undefined' ||
+      typeof edge?.targetId === 'undefined'
+    ) {
+      throw new Error('Graph edge requires "id", "sourceId", and "targetId" fields.');
+    }
+
+    const index = this.edgeLength++;
+    const attributes = cloneRecord(edge.attributes);
+
+    if (typeof edge.label !== 'undefined') {
+      attributes.label = edge.label;
+    }
+
+    if (typeof edge.weight !== 'undefined') {
+      attributes.weight = edge.weight;
+    }
+
+    const stateCandidate = edge.state ?? (attributes.state as EdgeState | undefined);
+    const directedCandidate = edge.directed ?? (attributes.directed as boolean | undefined);
+
+    this.appendUtf8(this.edgeBuilders, 'id', edge.id);
+    this.appendUtf8(this.edgeBuilders, 'sourceId', edge.sourceId);
+    this.appendUtf8(this.edgeBuilders, 'targetId', edge.targetId);
+    this.appendBoolean(this.edgeBuilders, 'directed', Boolean(directedCandidate));
+    this.appendUtf8(this.edgeBuilders, 'state', normalizeEdgeState(stateCandidate));
+    this.appendJson(this.edgeBuilders, 'data', attributes);
+
+    return index;
+  }
+
+  finish(): ArrowGraphData {
+    return {
+      shape: 'arrow-graph-data',
+      version: this._version,
+      nodes: tableFromBuilders(this.nodeBuilders),
+      edges: tableFromBuilders(this.edgeBuilders)
+    };
+  }
+
+  private appendUtf8(builders: ColumnBuilderMap, columnName: string, value: string | number): void {
+    const builder = this.getOrCreateBuilder(builders, columnName, () =>
+      arrow.makeBuilder({type: new arrow.Utf8(), nullValues: [null, undefined]})
+    );
+    builder.append(typeof value === 'number' ? String(value) : value);
+  }
+
+  private appendBoolean(builders: ColumnBuilderMap, columnName: string, value: boolean): void {
+    const builder = this.getOrCreateBuilder(builders, columnName, () =>
+      arrow.makeBuilder({type: new arrow.Bool(), nullValues: [null, undefined]})
+    );
+    builder.append(value);
+  }
+
+  private appendJson(builders: ColumnBuilderMap, columnName: string, value: Record<string, unknown>): void {
+    const builder = this.getOrCreateBuilder(builders, columnName, () =>
+      arrow.makeBuilder({type: new arrow.Utf8(), nullValues: [null, undefined]})
+    );
+    builder.append(JSON.stringify(value));
+  }
+
+  private getOrCreateBuilder(
+    builders: ColumnBuilderMap,
+    columnName: string,
+    factory: () => Builder
+  ): Builder {
+    let builder = builders.get(columnName);
+    if (!builder) {
+      builder = factory();
+      builders.set(columnName, builder);
+    }
+    return builder;
+  }
+}
+
+function tableFromBuilders(builders: ColumnBuilderMap): arrow.Table {
+  const columns: Record<string, ColumnArray> = {};
+
+  for (const [columnName, builder] of builders.entries()) {
+    builder.finish();
+    const vector = builder.toVector();
+    columns[columnName] = vector.toArray();
+  }
+
+  return arrow.tableFromArrays(columns);
+}
+

package/src/graph-data/graph-data-builder.ts

@@ -0,0 +1,7 @@
+import type { GraphData } from "./graph-data";
+
+export interface GraphDataBuilder {
+  addNode(node: Record<string, unknown>): number;
+  addEdge(edge: Record<string, unknown>): number;
+  build(): GraphData;
+}

package/src/graph-data/graph-data.ts

@@ -0,0 +1,57 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {NodeState, EdgeState} from '../core/constants';
+import * as arrow from 'apache-arrow';
+
+/** Graph data types supported by this library */
+export type GraphData = PlainGraphData | ArrowGraphData;
+
+/** Graph data stored in Apache Arrow binary columnar tables */
+export type ArrowGraphData = {
+  shape: 'arrow-graph-data';
+  version: number;
+  metadata?: Record<string, unknown>;
+  nodes: arrow.Table;
+  edges: arrow.Table;
+};
+
+export type PlainGraphData = {
+  shape: 'plain-graph-data';
+  version?: number;
+  metadata?: Record<string, unknown>;
+  nodes?: GraphNodeData[] | null;
+  edges?: GraphEdgeData[] | null;
+};
+
+export type GraphNodeData = {
+  id: string | number;
+  label?: string;
+  state?: NodeState;
+  selectable?: boolean;
+  highlightConnectedEdges?: boolean;
+  weight?: number;
+  attributes?: Record<string, unknown> | null | undefined;
+};
+
+export type GraphEdgeData = {
+  id: string | number;
+  sourceId: string | number;
+  targetId: string | number;
+  label?: string;
+  state?: EdgeState;
+  directed?: boolean;
+  weight?: number;
+  attributes?: Record<string, unknown> | null | undefined;
+};
+
+export function isArrowGraphData(value: unknown): value is ArrowGraphData {
+  const candidate = value as ArrowGraphData;
+  return typeof value === 'object' && candidate?.shape === 'arrow-graph-data';
+}
+
+export function isPlainGraphData(value: unknown): value is PlainGraphData {
+  const candidate = value as PlainGraphData;
+  return typeof value === 'object' && candidate?.shape === 'plain-graph-data';
+}

package/src/graph-data/plain-graph-data-builder.ts

@@ -0,0 +1,132 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {PlainGraphData, GraphEdgeData, GraphNodeData} from './graph-data';
+import { GraphDataBuilder } from './graph-data-builder';
+import {cloneRecord, normalizeVersion} from '../graph/graph-normalization';
+
+export type PlainGraphDataBuilderOptions = {
+  version?: number;
+};
+
+export class PlainGraphDataBuilder implements GraphDataBuilder {
+  private readonly nodes: GraphNodeData[] = [];
+  private readonly edges: GraphEdgeData[] = [];
+
+  private _version: number;
+
+  constructor(options: PlainGraphDataBuilderOptions = {}) {
+    this._version = normalizeVersion(options.version);
+  }
+
+  get version(): number {
+    return this._version;
+  }
+
+  setVersion(version: unknown): void {
+    this._version = normalizeVersion(version);
+  }
+
+  get nodeCount(): number {
+    return this.nodes.length;
+  }
+
+  get edgeCount(): number {
+    return this.edges.length;
+  }
+
+  addNode(node: GraphNodeData): number {
+    if (typeof node?.id === 'undefined') {
+      throw new Error('Graph node requires an "id" field.');
+    }
+
+    const attributes = cloneRecord(node.attributes);
+    this._assignNodeAttributes(attributes, node);
+    const record: GraphNodeData = {
+      ...node,
+      attributes
+    };
+
+    this.nodes.push(record);
+    return this.nodes.length - 1;
+  }
+
+  addEdge(edge: GraphEdgeData): number {
+    if (
+      typeof edge?.id === 'undefined' ||
+      typeof edge?.sourceId === 'undefined' ||
+      typeof edge?.targetId === 'undefined'
+    ) {
+      throw new Error('Graph edge requires "id", "sourceId", and "targetId" fields.');
+    }
+
+    const attributes = cloneRecord(edge.attributes);
+    this._assignEdgeAttributes(attributes, edge);
+    const record: GraphEdgeData = {
+      ...edge,
+      attributes
+    };
+
+    this.edges.push(record);
+    return this.edges.length - 1;
+  }
+
+  private _assignNodeAttributes(target: Record<string, unknown>, node: GraphNodeData): void {
+    if (typeof node.label !== 'undefined') {
+      target.label = node.label;
+    }
+    if (typeof node.weight !== 'undefined') {
+      target.weight = node.weight;
+    }
+    if (typeof node.state !== 'undefined') {
+      target.state = node.state;
+    }
+    if (typeof node.selectable !== 'undefined') {
+      target.selectable = node.selectable;
+    }
+    if (typeof node.highlightConnectedEdges !== 'undefined') {
+      target.highlightConnectedEdges = node.highlightConnectedEdges;
+    }
+  }
+
+  private _assignEdgeAttributes(target: Record<string, unknown>, edge: GraphEdgeData): void {
+    if (typeof edge.label !== 'undefined') {
+      target.label = edge.label;
+    }
+    if (typeof edge.weight !== 'undefined') {
+      target.weight = edge.weight;
+    }
+    if (typeof edge.state !== 'undefined') {
+      target.state = edge.state;
+    }
+    if (typeof edge.directed !== 'undefined') {
+      target.directed = edge.directed;
+    }
+  }
+
+  build(): PlainGraphData {
+    return {
+      shape: 'plain-graph-data',
+      version: this._version,
+      nodes: this.nodes.map(cloneNodeData),
+      edges: this.edges.map(cloneEdgeData)
+    };
+  }
+}
+
+function cloneNodeData(node: GraphNodeData): GraphNodeData {
+  const attributes = cloneRecord(node.attributes);
+  return {
+    ...node,
+    attributes
+  };
+}
+
+function cloneEdgeData(edge: GraphEdgeData): GraphEdgeData {
+  const attributes = cloneRecord(edge.attributes);
+  return {
+    ...edge,
+    attributes
+  };
+}

package/src/index.ts

@@ -2,11 +2,37 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
+// Graph Data - output from loaders, input to writers
+
+export type {GraphData, PlainGraphData, ArrowGraphData /* , GraphNodeData, GraphEdgeData */} from './graph-data/graph-data';
+export type {GraphDataBuilder /* , GraphDataBuilderOptions */} from './graph-data/graph-data-builder';
+export {
+  ArrowGraphDataBuilder,
+  type ArrowGraphDataBuilderOptions
+} from './graph-data/arrow-graph-data-builder';
+
+
 // core - Graph representation and layout
-export {Graph} from './graph/graph';
+export type {Graph, NodeInterface, EdgeInterface} from './graph/graph';
 export {Node} from './graph/node';
 export {Edge} from './graph/edge';
 
+export {ClassicGraph} from './graph/classic-graph';
+export {ArrowGraph} from './graph/arrow-graph';
+// export {
+//   TabularGraph,
+//   TabularNode,
+//   TabularEdge,
+//   type NodeIndex,
+//   type EdgeIndex,
+//   type TabularGraphSource,
+//   type TabularGraphAccessors,
+//   type TabularNodeAccessors,
+//   type TabularEdgeAccessors
+// } from './graph/tabular-graph';
+
+// Graph Engine
+
 export {GraphEngine} from './core/graph-engine';
 
 // graph-layers layouts
@@ -20,6 +46,7 @@ export {GraphLayout} from './core/graph-layout';
 export {SimpleLayout} from './layouts/simple-layout';
 export {D3ForceLayout} from './layouts/d3-force/d3-force-layout';
 export {D3DagLayout} from './layouts/d3-dag/d3-dag-layout';
+export {CollapsableD3DagLayout} from './layouts/d3-dag/collapsable-d3-dag-layout';
 export {GPUForceLayout} from './layouts/gpu-force/gpu-force-layout';
 export {RadialLayout} from './layouts/experimental/radial-layout';
 export {ForceMultiGraphLayout} from './layouts/experimental/force-multi-graph-layout';
@@ -29,9 +56,11 @@ export type {Marker, NodeState, NodeType, EdgeType, EdgeDecoratorType, LayoutSta
 
 // deck.gl components
 export {GraphLayer} from './layers/graph-layer';
+export type {RankGridConfig} from './layers/graph-layer';
 export {EdgeLayer} from './layers/edge-layer';
-export {StyleEngine} from './style/style-engine';
-export {GraphStyleEngine} from './style/graph-style-engine';
+export {GridLayer, type GridLayerProps, type GridLineDatum} from './layers/common-layers/grid-layer/grid-layer';
+export {StylesheetEngine} from './style/stylesheet-engine';
+export {GraphStylesheetEngine, GraphStyleEngine} from './style/graph-style-engine';
 export type {
   GraphStylesheet,
   GraphStylesheetInput,
@@ -49,19 +78,30 @@ export {
   type GraphLayerNodeStyle
 } from './style/graph-layer-stylesheet';
 
-// Widgets
-
-export {ViewControlWidget} from './widgets/view-control-widget';
-
-// graph format loaders
-export {loadSimpleJSONGraph} from './loaders/simple-json-graph-loader';
-
 // utils
 export {mixedGetPosition} from './utils/layer-utils';
 export {log} from './utils/log';
+export {
+  mapRanksToYPositions,
+  selectRankLines,
+  type RankAccessor,
+  type LabelAccessor,
+  type RankPosition,
+  type MapRanksToYPositionsOptions,
+  type SelectRankLinesOptions
+} from './utils/rank-grid';
 
-// DEPRECATED
-export {createGraph} from './loaders/create-graph';
-export {JSONLoader} from './loaders/simple-json-graph-loader';
+// graph format loaders
+export {
+  JSONGraphLoader,
+  type JSONGraphLoaderOptions,
+} from './loaders/json-graph-loader';
+
+export {
+  DOTGraphLoader,
+  type DOTGraphLoaderOptions,
+  type DOTGraphLoaderMetadata,
+} from './loaders/dot-graph-loader';
 
+// Deprecated exports
 export {MARKER_TYPE, NODE_STATE,EDGE_STATE,NODE_TYPE,EDGE_TYPE,EDGE_DECORATOR_TYPE,LAYOUT_STATE} from './_deprecated/old-constants';

package/src/layers/common-layers/flow-path-layer/flow-path-layer.ts

@@ -4,7 +4,6 @@
 
 // import {Buffer, Transform} from '@luma.gl/core';
 import {LineLayer} from '@deck.gl/layers';
-import {window} from 'global';
 
 import {vs} from './flow-path-layer-vertex.glsl';
 import {fs} from './flow-path-layer-fragment.glsl';
@@ -42,7 +41,7 @@ export class FlowPathLayer extends LineLayer {
     this.setupTransformFeedback();
     this.setState({
       ...this.state,
-      animation: window.requestAnimationFrame(this.animate.bind(this))
+      animation: globalThis.window.requestAnimationFrame(this.animate.bind(this))
     });
   }