@deck.gl-community/graph-layers 9.0.0

package/src/core/constants.ts

@@ -0,0 +1,58 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {MarkerList} from '../layers/common-layers/marker-layer/marker-list';
+
+/** All the markers supported by node type MARKER */
+export const MARKER_TYPE = MarkerList;
+
+export type ValueOf<T> = T[keyof T];
+
+// the interaction state of a node.
+export const NODE_STATE = {
+  DEFAULT: 'default',
+  HOVER: 'hover',
+  DRAGGING: 'dragging',
+  SELECTED: 'selected'
+};
+
+export const EDGE_STATE = {
+  DEFAULT: 'default',
+  HOVER: 'hover',
+  DRAGGING: 'dragging',
+  SELECTED: 'selected'
+};
+
+// node visual marker type
+export const NODE_TYPE = {
+  CIRCLE: 'CIRCLE',
+  RECTANGLE: 'RECTANGLE',
+  ROUNDED_RECTANGLE: 'ROUNDED_RECTANGLE',
+  PATH_ROUNDED_RECTANGLE: 'PATH_ROUNDED_RECTANGLE',
+  ICON: 'ICON',
+  LABEL: 'LABEL',
+  MARKER: 'MARKER'
+};
+
+// edge shape
+export const EDGE_TYPE = {
+  SPLINE_CURVE: 'SPLINE_CURVE',
+  LINE: 'LINE',
+  PATH: 'PATH'
+};
+
+// decorators on edges
+export const EDGE_DECORATOR_TYPE = {
+  LABEL: 'EDGE_LABEL',
+  FLOW: 'FLOW'
+};
+
+// the status of the layout
+export const LAYOUT_STATE = {
+  INIT: 'INIT',
+  START: 'START',
+  CALCULATING: 'CALCULATING',
+  DONE: 'DONE',
+  ERROR: 'ERROR'
+};

package/src/core/edge.ts

@@ -0,0 +1,145 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// Basic data structure of an edge
+import {EDGE_STATE} from './constants';
+import {Node} from './node';
+
+interface EdgeOptions {
+  id: string | number;
+  sourceId: string | number;
+  targetId: string | number;
+  directed?: boolean;
+  data: Record<string, unknown>;
+}
+
+export class Edge {
+  /** Unique uuid of the edge. */
+  public id: string | number;
+  /** ID of the source node. */
+  private _sourceId: string | number;
+  /** ID of the target node. */
+  private _targetId: string | number;
+  /** Whether the edge is directed or not. */
+  private _directed: boolean;
+  /** Origin data reference of the edge. */
+  private _data: Record<string, unknown>;
+  /** Check the type of the object when picking engine gets it. */
+  public readonly isEdge = true;
+  /** Nodes at either end of this edge. */
+  private readonly _connectedNodes: Record<string, Node> = {};
+  /** Edge state. */
+  public state = EDGE_STATE.DEFAULT;
+
+  /**
+   * The constructor
+   * @param  {String|Number} options.id - the unique ID of the edge
+   * @param  {String|Number} options.sourceId - the ID of the source node
+   * @param  {String|Number} options.targetId - the ID of the target node
+   * @param  {Boolean} options.directed - whether the edge is directed or not
+   * @param  {Record<string, unknown>} options.data - origin data reference
+   */
+  constructor({id, sourceId, targetId, data, directed = false}: EdgeOptions) {
+    this.id = id;
+    this._sourceId = sourceId;
+    this._targetId = targetId;
+    this._directed = directed;
+    this._data = data;
+  }
+
+  /**
+   * Return the ID of the edge
+   * @return {String|Number} - the ID of the edge.
+   */
+  getId(): string | number {
+    return this.id;
+  }
+
+  /**
+   * Return whether the edge is directed or not.
+   * @return {Boolean} true if the edge is directed.
+   */
+  isDirected(): boolean {
+    return this._directed;
+  }
+
+  /**
+   * Get the ID of the source node.
+   * @return {String|Number} the ID of the source node.
+   */
+  getSourceNodeId(): string | number {
+    return this._sourceId;
+  }
+
+  /**
+   * Get the ID of the target node.
+   * @return {String|Number} the ID of the target node.
+   */
+  getTargetNodeId(): string | number {
+    return this._targetId;
+  }
+
+  /**
+   * Return of the value of the selected property key.
+   * @param  {String} key - property key.
+   * @return {Any} - the value of the property.
+   */
+  getPropertyValue(key: string): unknown {
+    // try to search the key within this object
+    if (this.hasOwnProperty(key)) {
+      return this[key];
+    }
+    // try to search the key in the original data reference
+    else if (this._data.hasOwnProperty(key)) {
+      return this._data[key];
+    }
+    // otherwise, not found
+    return undefined;
+  }
+
+  /**
+   * Set the origin data as a reference.
+   * @param {Object} data - the origin data.
+   */
+  setData(data: Record<string, unknown>): void {
+    this._data = data;
+  }
+
+  /**
+   * Update a data property.
+   * @param {String} key - the key of the property
+   * @param {Any} value - the value of the property.
+   */
+  setDataProperty(key: string, value: unknown): void {
+    this._data[key] = value;
+  }
+
+  /**
+   * Set edge state
+   * @param {String} state - one of EDGE_STATE
+   */
+  setState(state: string): void {
+    this.state = state;
+  }
+
+  /**
+   * Get edge state
+   * @returns {string} state - one of EDGE_STATE
+   */
+  getState(): string {
+    return this.state;
+  }
+
+  addNode(node: Node): void {
+    this._connectedNodes[node.getId()] = node;
+  }
+
+  removeNode(node: Node): void {
+    delete this._connectedNodes[node.getId()];
+  }
+
+  getConnectedNodes(): Node[] {
+    return Object.values(this._connectedNodes);
+  }
+}

package/src/core/graph-engine.ts

@@ -0,0 +1,170 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {BaseLayout} from './base-layout';
+import {Cache} from './cache';
+import {Edge} from './edge';
+import {Graph} from './graph';
+
+// Graph engine controls the graph data and layout calculation
+export class GraphEngine extends EventTarget {
+  private readonly _graph: Graph;
+  private readonly _layout: BaseLayout;
+  private readonly _cache = new Cache<'nodes' | 'edges', Node[] | Edge[]>();
+  private _layoutDirty = false;
+  private _transactionInProgress = false;
+
+  constructor(graph: Graph, layout: BaseLayout) {
+    super();
+    this._graph = graph;
+    this._layout = layout;
+  }
+
+  /** Getters */
+
+  getNodes = (): Node[] => {
+    this._updateCache('nodes', () =>
+      this._graph.getNodes().filter((node) => this.getNodePosition(node))
+    );
+
+    return this._cache.get('nodes') as Node[];
+  };
+
+  getEdges = () => {
+    this._updateCache('edges', () =>
+      this._graph.getEdges().filter((edge) => this.getEdgePosition(edge))
+    );
+
+    return this._cache.get('edges') as Edge[];
+  };
+
+  getNodePosition = (node) => this._layout.getNodePosition(node);
+
+  getEdgePosition = (edge) => this._layout.getEdgePosition(edge);
+
+  getGraphVersion = () => this._graph.version;
+
+  getLayoutLastUpdate = () => this._layout.version;
+
+  getLayoutState = () => this._layout.state;
+
+  /** Operations on the graph */
+
+  lockNodePosition = (node, x, y) => this._layout.lockNodePosition(node, x, y);
+
+  unlockNodePosition = (node) => this._layout.unlockNodePosition(node);
+
+  /**
+   * @fires GraphEngine#onLayoutStart
+   */
+  _onLayoutStart = () => {
+    /**
+     * @event GraphEngine#onLayoutStart
+     * @type {CustomEvent}
+     */
+    this.dispatchEvent(new CustomEvent('onLayoutStart'));
+  };
+
+  /**
+   * @fires GraphEngine#onLayoutChange
+   */
+  _onLayoutChange = () => {
+    /**
+     * @event GraphEngine#onLayoutChange
+     * @type {CustomEvent}
+     */
+    this.dispatchEvent(new CustomEvent('onLayoutChange'));
+  };
+
+  /**
+   * @fires GraphEngine#onLayoutDone
+   */
+  _onLayoutDone = () => {
+    /**
+     * @event GraphEngine#onLayoutDone
+     * @type {CustomEvent}
+     */
+    this.dispatchEvent(new CustomEvent('onLayoutDone'));
+  };
+
+  /**
+   * @fires GraphEngine#onLayoutError
+   */
+  _onLayoutError = () => {
+    /**
+     * @event GraphEngine#onLayoutError
+     * @type {CustomEvent}
+     */
+    this.dispatchEvent(new CustomEvent('onLayoutError'));
+  };
+
+  _onGraphStructureChanged = (entity) => {
+    this._layoutDirty = true;
+    this._graphChanged();
+  };
+
+  _onTransactionStart = () => {
+    this._transactionInProgress = true;
+  };
+
+  _onTransactionEnd = () => {
+    this._transactionInProgress = false;
+    this._graphChanged();
+  };
+
+  /** Layout calculations */
+
+  run = () => {
+    // TODO: throw if running on a cleared engine
+
+    this._graph.addEventListener('transactionStart', this._onTransactionStart);
+    this._graph.addEventListener('transactionEnd', this._onTransactionEnd);
+    this._graph.addEventListener('onNodeAdded', this._onGraphStructureChanged);
+    this._graph.addEventListener('onNodeRemoved', this._onGraphStructureChanged);
+    this._graph.addEventListener('onEdgeAdded', this._onGraphStructureChanged);
+    this._graph.addEventListener('onEdgeRemoved', this._onGraphStructureChanged);
+
+    this._layout.addEventListener('onLayoutStart', this._onLayoutStart);
+    this._layout.addEventListener('onLayoutChange', this._onLayoutChange);
+    this._layout.addEventListener('onLayoutDone', this._onLayoutDone);
+    this._layout.addEventListener('onLayoutError', this._onLayoutError);
+
+    this._layout.initializeGraph(this._graph);
+    this._layout.start();
+  };
+
+  clear = () => {
+    this._graph.removeEventListener('transactionStart', this._onTransactionStart);
+    this._graph.removeEventListener('transactionEnd', this._onTransactionEnd);
+    this._graph.removeEventListener('onNodeAdded', this._onGraphStructureChanged);
+    this._graph.removeEventListener('onNodeRemoved', this._onGraphStructureChanged);
+    this._graph.removeEventListener('onEdgeAdded', this._onGraphStructureChanged);
+    this._graph.removeEventListener('onEdgeRemoved', this._onGraphStructureChanged);
+
+    this._layout.removeEventListener('onLayoutStart', this._onLayoutStart);
+    this._layout.removeEventListener('onLayoutChange', this._onLayoutChange);
+    this._layout.removeEventListener('onLayoutDone', this._onLayoutDone);
+    this._layout.removeEventListener('onLayoutError', this._onLayoutError);
+  };
+
+  resume = () => this._layout.resume();
+
+  stop = () => this._layout.stop();
+
+  _graphChanged = () => {
+    if (this._layoutDirty && !this._transactionInProgress) {
+      this._updateLayout();
+    }
+  };
+
+  _updateLayout = () => {
+    this._layout.updateGraph(this._graph);
+    this._layout.update();
+    this._layoutDirty = false;
+  };
+
+  _updateCache(key, updateValue) {
+    this._cache.set(key, updateValue, this._graph.version + this._layout.version);
+  }
+}

package/src/core/graph.ts

@@ -0,0 +1,342 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {log} from '../utils/log';
+import {Cache} from './cache';
+import {Edge} from './edge';
+import {Node} from './node';
+
+// Basic graph data structure
+export class Graph extends EventTarget {
+  /** List object of nodes. */
+  private _nodeMap: Record<string, Node> = {};
+  /** List of object edges. */
+  private _edgeMap: Record<string, Edge> = {};
+  /**
+   * Identifies whether performing dirty check when streaming new data. If
+   * the name of the graph is not specified, will fall back to current time stamp.
+   */
+  private _name: string = Date.now().toString();
+  /** Version the graph. A version is a number that is incremented every time the graph is updated. */
+  public version = 0;
+  /** Cached data: create array data from maps. */
+  private _cache = new Cache<'nodes' | 'edges', Node[] | Edge[]>();
+
+  /**
+   * The constructor of the Graph class.
+   * @param  {Object} graph - copy the graph if this exists.
+   */
+  constructor(graph: Graph | null = null) {
+    super();
+
+    // copy the graph if it exists in the parameter
+    if (graph) {
+      // start copying the graph
+      this._nodeMap = graph._nodeMap;
+      this._edgeMap = graph._edgeMap;
+      this._name = graph && graph._name;
+    }
+  }
+
+  /**
+   * Set graph name
+   * @param {string} name
+   */
+  setGraphName(name: string): void {
+    this._name = name;
+  }
+
+  /** Get the name of the graph. Default value is the time stamp when creating this graph.
+   * @return {string} graph name.
+   */
+  getGraphName(): string {
+    return this._name.toString();
+  }
+
+  /**
+   * Perform a batch of operations defined by cb before indicating graph is updated
+   * @param {function} cb - a callback fuction containing the operations to perform
+   */
+  transaction<T>(cb: (...args: unknown[]) => T): T {
+    try {
+      this.dispatchEvent(new CustomEvent('transactionStart'));
+      return cb();
+    } finally {
+      this.dispatchEvent(new CustomEvent('transactionEnd'));
+    }
+  }
+
+  /**
+   * Add a new node to the graph.
+   * @param {Node} node - expect a Node object to be added to the graph.
+   */
+  addNode(node: Node): void {
+    // add it to the list and map
+    this._nodeMap[node.getId()] = node;
+    // update last update time stamp
+    this._bumpVersion();
+    this.dispatchEvent(new CustomEvent('onNodeAdded', {node} as any));
+  }
+
+  /**
+   * Batch add nodes to the graph.
+   * @param  {Node[]} nodes - a list of nodes to be added.
+   */
+  batchAddNodes(nodes: Node[]): void {
+    // convert an array of objects to an object
+    this._nodeMap = nodes.reduce(
+      (res, node) => {
+        res[node.getId()] = node;
+        this.dispatchEvent(new CustomEvent('onNodeAdded', {node} as any));
+        return res;
+      },
+      {...this._nodeMap}
+    );
+    this._bumpVersion();
+  }
+
+  /**
+   * Get all the nodes of the graph.
+   * @return {Node[]} - get all the nodes in the graph.
+   */
+  getNodes(): Node[] {
+    this._updateCache('nodes', () => Object.values(this._nodeMap));
+
+    return this._cache.get('nodes') as Node[];
+  }
+
+  /**
+   * Get the node map of the graph. The key of the map is the ID of the nodes.
+   * @return {Object} - a map of nodes keyed by node IDs.
+   */
+  getNodeMap(): Record<string | number, Node> {
+    return this._nodeMap;
+  }
+
+  /**
+   * Find a node by id
+   * @param  {String} nodeId The id of the node
+   * @return {Object} Node
+   */
+  findNode(nodeId: string | number): Node | undefined {
+    return this._nodeMap[nodeId];
+  }
+
+  /**
+   * Update the indicated node to the provided value
+   * @param {Node} node
+   */
+  updateNode(node: Node): void {
+    this._nodeMap[node.getId()] = node;
+    this._bumpVersion();
+    this.dispatchEvent(new CustomEvent('onNodeUpdated', {node} as any));
+  }
+
+  /**
+   * Add a new edge to the graph.
+   * @param {Edge} edge - expect a Edge object to be added to the graph.
+   */
+  addEdge(edge: Edge): void {
+    const sourceNode = this.findNode(edge.getSourceNodeId());
+    const targetNode = this.findNode(edge.getTargetNodeId());
+
+    if (!sourceNode || !targetNode) {
+      log.warn(`Unable to add edge ${edge.id},  source or target node is missing.`)();
+      return;
+    }
+
+    this._edgeMap[edge.getId()] = edge;
+    sourceNode.addConnectedEdges(edge);
+    targetNode.addConnectedEdges(edge);
+    this._bumpVersion();
+    this.dispatchEvent(new CustomEvent('onEdgeAdded', {edge} as any));
+  }
+
+  /**
+   * Batch add edges to the graph
+   * @param  {Edge[]} edges - a list of edges to be added.
+   */
+  batchAddEdges(edges: Edge[]): void {
+    edges.forEach((edge) => this.addEdge(edge));
+    this._bumpVersion();
+  }
+
+  /**
+   * Update the indicated edge to the provided value
+   * @param {Edge} edge
+   */
+  updateEdge(edge: Edge): void {
+    this._edgeMap[edge.getId()] = edge;
+    this._bumpVersion();
+    this.dispatchEvent(new CustomEvent('onEdgeUpdated', {edge} as any));
+  }
+
+  /**
+   * Remove a node from the graph by node ID
+   * @param  {String|Number} nodeId - the ID of the target node.
+   */
+  removeNode(nodeId: string | number): void {
+    const node = this.findNode(nodeId);
+    if (!node) {
+      log.warn(`Unable to remove node ${nodeId} - doesn't exist`)();
+      return;
+    }
+    // remove all edges connect to this node from map
+    node.getConnectedEdges().forEach((e) => {
+      delete this._edgeMap[e.getId()];
+    });
+    // remove the node from map
+    delete this._nodeMap[nodeId];
+    this._bumpVersion();
+    this.dispatchEvent(new CustomEvent('onNodeRemoved', {node} as any));
+  }
+
+  /**
+   * Get all the edges of the graph.
+   * @return {Edge[]} get all the edges in the graph.
+   */
+  getEdges(): Edge[] {
+    this._updateCache('edges', () => Object.values(this._edgeMap));
+
+    return this._cache.get('edges') as Edge[];
+  }
+
+  /**
+   * Get the edge map of the graph. The key of the map is the ID of the edges.
+   * @return {Object} - a map of edges keyed by edge IDs.
+   */
+  getEdgeMap(): Record<string, Edge> {
+    return this._edgeMap;
+  }
+
+  /**
+   * Remove an edge from the graph by the edge ID
+   * @param  {String|Number} edgeId - the target edge ID.
+   */
+  removeEdge(edgeId: string | number): void {
+    const edge = this.findEdge(edgeId);
+    if (!edge) {
+      log.warn(`Unable to remove edge ${edgeId} - doesn't exist`)();
+      return;
+    }
+    const sourceNode = this.findNode(edge.getSourceNodeId());
+    const targetNode = this.findNode(edge.getTargetNodeId());
+
+    delete this._edgeMap[edgeId];
+    sourceNode.removeConnectedEdges(edge);
+    targetNode.removeConnectedEdges(edge);
+    this._bumpVersion();
+  }
+
+  /**
+   * Find the edge by edge ID.
+   * @param  {String|Number} id - the target edge ID
+   * @return {Edge} - the target edge.
+   */
+  findEdge(edgeId: string | number): Edge {
+    return this._edgeMap[edgeId];
+  }
+
+  /**
+   * Return all the connected edges of a node by nodeID.
+   * @param  {String|Number} nodeId - the target node ID
+   * @return {Edge[]} - an array of the connected edges.
+   */
+  getConnectedEdges(nodeId: string | number): Edge[] {
+    const node = this.findNode(nodeId);
+    if (!node) {
+      log.warn(`Unable to find node ${nodeId} - doesn't exist`)();
+      return [];
+    }
+    return node.getConnectedEdges();
+  }
+
+  /**
+   * Return all the sibling nodes of a node by nodeID.
+   * @param  {String|Number} nodeId - the target node ID
+   * @return {Node[]} - an array of the sibling nodes.
+   */
+  getNodeSiblings(nodeId: string | number): Node[] {
+    const node = this.findNode(nodeId);
+    if (!node) {
+      log.warn(`Unable to find node ${nodeId} - doesn't exist`)();
+      return [];
+    }
+    return node.getSiblingIds().map((siblingNodeId) => this.findNode(siblingNodeId));
+  }
+
+  /**
+   * Get the degree of a node.
+   * @param  {String|Number} nodeId - the target node ID.
+   * @return {Number} - the degree of the node.
+   */
+  getDegree(nodeId: string | number): number {
+    const node = this.findNode(nodeId);
+    if (!node) {
+      log.warn(`Unable to find node ${nodeId} - doesn't exist`)();
+      return 0;
+    }
+    return node.getDegree();
+  }
+
+  /**
+   * Clean up all the nodes in the graph.
+   */
+  resetNodes(): void {
+    this._nodeMap = {};
+    this._bumpVersion();
+  }
+
+  /**
+   * Clean up all the edges in the graph.
+   */
+  resetEdges(): void {
+    this._edgeMap = {};
+    this._bumpVersion();
+  }
+
+  /**
+   * Clean up everything in the graph.
+   */
+  reset(): void {
+    this.resetNodes();
+    this.resetEdges();
+    this._bumpVersion();
+  }
+
+  /**
+   * Trigger an update to the graph.
+   */
+  triggerUpdate(): void {
+    this._bumpVersion();
+  }
+
+  /**
+   * Return true if the graph is empty.
+   * @return {Boolean} Return true if the graph is empty.
+   */
+  isEmpty(): boolean {
+    return Object.keys(this._nodeMap).length === 0;
+  }
+
+  /**
+   * Check the equality of two graphs data by checking last update time stamp
+   * @param  {Object} g Another graph to be compared against itself
+   * @return {Bool}   True if the graph is the same as itself.
+   */
+  equals(g: Graph): boolean {
+    if (!g || !(g instanceof Graph)) {
+      return false;
+    }
+    return this.version === g.version;
+  }
+
+  _bumpVersion(): void {
+    this.version += 1;
+  }
+
+  _updateCache(key: 'nodes' | 'edges', updateValue: unknown): void {
+    this._cache.set(key, updateValue as any, this.version);
+  }
+}