@deck.gl-community/graph-layers 9.0.2 → 9.1.0-beta.2

package/src/{core → graph}/graph.ts

@@ -3,11 +3,17 @@
 // Copyright (c) vis.gl contributors
 
 import {log} from '../utils/log';
-import {Cache} from './cache';
+import {Cache} from '../core/cache';
 import {Edge} from './edge';
 import {Node} from './node';
 
-// Basic graph data structure
+export type GraphProps = {
+  name?: string;
+  nodes?: Node[];
+  edges?: Edge[];
+};
+
+/** Basic graph data structure */
 export class Graph extends EventTarget {
   /** List object of nodes. */
   private _nodeMap: Record<string, Node> = {};
@@ -23,32 +29,41 @@ export class Graph extends EventTarget {
   /** Cached data: create array data from maps. */
   private _cache = new Cache<'nodes' | 'edges', Node[] | Edge[]>();
 
+  constructor(props?: GraphProps);
+  constructor(graph: Graph);
+
   /**
    * The constructor of the Graph class.
-   * @param  {Object} graph - copy the graph if this exists.
+   * @param graph - copy the graph if this exists.
    */
-  constructor(graph: Graph | null = null) {
+  constructor(propsOrGraph?: GraphProps | Graph) {
     super();
 
-    // copy the graph if it exists in the parameter
-    if (graph) {
-      // start copying the graph
+    if (propsOrGraph instanceof Graph) {
+      // if a Graph instance was supplied, copy the supplied graph into this graph
+      const graph = propsOrGraph;
+      this._name = graph?._name || this._name;
       this._nodeMap = graph._nodeMap;
       this._edgeMap = graph._edgeMap;
-      this._name = graph && graph._name;
+    } else {
+      // If graphProps were supplied, initialize this graph from the supplied props
+      const props = propsOrGraph;
+      this._name = props?.name || this._name;
+      this.batchAddNodes(props?.nodes || []);
+      this.batchAddEdges(props?.edges || []);
     }
   }
 
   /**
    * Set graph name
-   * @param {string} name
+   * @param 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.
+   * @return graph name.
    */
   getGraphName(): string {
     return this._name.toString();
@@ -56,7 +71,7 @@ export class Graph extends EventTarget {
 
   /**
    * Perform a batch of operations defined by cb before indicating graph is updated
-   * @param {function} cb - a callback fuction containing the operations to perform
+   * @param {function} cb - a callback function containing the operations to perform
    */
   transaction<T>(cb: (...args: unknown[]) => T): T {
     try {
@@ -69,7 +84,7 @@ export class Graph extends EventTarget {
 
   /**
    * Add a new node to the graph.
-   * @param {Node} node - expect a Node object to be added to the graph.
+   * @paramnode - expect a Node object to be added to the graph.
    */
   addNode(node: Node): void {
     // add it to the list and map
@@ -81,7 +96,7 @@ export class Graph extends EventTarget {
 
   /**
    * Batch add nodes to the graph.
-   * @param  {Node[]} nodes - a list of nodes to be added.
+   * @param nodes - a list of nodes to be added.
    */
   batchAddNodes(nodes: Node[]): void {
     // convert an array of objects to an object
@@ -108,7 +123,7 @@ export class Graph extends EventTarget {
 
   /**
    * 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.
+   * @return - a map of nodes keyed by node IDs.
    */
   getNodeMap(): Record<string | number, Node> {
     return this._nodeMap;
@@ -116,8 +131,8 @@ export class Graph extends EventTarget {
 
   /**
    * Find a node by id
-   * @param  {String} nodeId The id of the node
-   * @return {Object} Node
+   * @param nodeId The id of the node
+   * @return  Node
    */
   findNode(nodeId: string | number): Node | undefined {
     return this._nodeMap[nodeId];
@@ -125,7 +140,7 @@ export class Graph extends EventTarget {
 
   /**
    * Update the indicated node to the provided value
-   * @param {Node} node
+   * @param node
    */
   updateNode(node: Node): void {
     this._nodeMap[node.getId()] = node;
@@ -135,7 +150,7 @@ export class Graph extends EventTarget {
 
   /**
    * Add a new edge to the graph.
-   * @param {Edge} edge - expect a Edge object to be added to the graph.
+   * @param edge - expect a Edge object to be added to the graph.
    */
   addEdge(edge: Edge): void {
     const sourceNode = this.findNode(edge.getSourceNodeId());
@@ -155,7 +170,7 @@ export class Graph extends EventTarget {
 
   /**
    * Batch add edges to the graph
-   * @param  {Edge[]} edges - a list of edges to be added.
+   * @param edges - a list of edges to be added.
    */
   batchAddEdges(edges: Edge[]): void {
     edges.forEach((edge) => this.addEdge(edge));
@@ -164,7 +179,7 @@ export class Graph extends EventTarget {
 
   /**
    * Update the indicated edge to the provided value
-   * @param {Edge} edge
+   * @param edge
    */
   updateEdge(edge: Edge): void {
     this._edgeMap[edge.getId()] = edge;
@@ -174,7 +189,7 @@ export class Graph extends EventTarget {
 
   /**
    * Remove a node from the graph by node ID
-   * @param  {String|Number} nodeId - the ID of the target node.
+   * @param nodeId - the ID of the target node.
    */
   removeNode(nodeId: string | number): void {
     const node = this.findNode(nodeId);
@@ -194,7 +209,7 @@ export class Graph extends EventTarget {
 
   /**
    * Get all the edges of the graph.
-   * @return {Edge[]} get all the edges in the graph.
+   * @return get all the edges in the graph.
    */
   getEdges(): Edge[] {
     this._updateCache('edges', () => Object.values(this._edgeMap));
@@ -204,7 +219,7 @@ export class Graph extends EventTarget {
 
   /**
    * 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.
+   * @return - a map of edges keyed by edge IDs.
    */
   getEdgeMap(): Record<string, Edge> {
     return this._edgeMap;
@@ -231,8 +246,8 @@ export class Graph extends EventTarget {
 
   /**
    * Find the edge by edge ID.
-   * @param  {String|Number} id - the target edge ID
-   * @return {Edge} - the target edge.
+   * @param id - the target edge ID
+   * @return - the target edge.
    */
   findEdge(edgeId: string | number): Edge {
     return this._edgeMap[edgeId];
@@ -240,8 +255,8 @@ export class Graph extends EventTarget {
 
   /**
    * 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.
+   * @param  nodeId - the target node ID
+   * @return - an array of the connected edges.
    */
   getConnectedEdges(nodeId: string | number): Edge[] {
     const node = this.findNode(nodeId);
@@ -254,8 +269,8 @@ export class Graph extends EventTarget {
 
   /**
    * 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.
+   * @param nodeId - the target node ID
+   * @return - an array of the sibling nodes.
    */
   getNodeSiblings(nodeId: string | number): Node[] {
     const node = this.findNode(nodeId);
@@ -268,8 +283,8 @@ export class Graph extends EventTarget {
 
   /**
    * Get the degree of a node.
-   * @param  {String|Number} nodeId - the target node ID.
-   * @return {Number} - the degree of the node.
+   * @param nodeId - the target node ID.
+   * @return - the degree of the node.
    */
   getDegree(nodeId: string | number): number {
     const node = this.findNode(nodeId);
@@ -322,14 +337,14 @@ export class Graph extends EventTarget {
 
   /**
    * 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.
+   * @param graph Another graph to be compared against itself
+   * @return true if the graph is the same as itself.
    */
-  equals(g: Graph): boolean {
-    if (!g || !(g instanceof Graph)) {
+  equals(graph: Graph): boolean {
+    if (!graph || !(graph instanceof Graph)) {
       return false;
     }
-    return this.version === g.version;
+    return this.version === graph.version;
   }
 
   _bumpVersion(): void {

package/src/{core → graph}/node.ts

@@ -2,17 +2,20 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {NODE_STATE, ValueOf} from './constants';
+import {NODE_STATE, ValueOf} from '../core/constants';
 import {Edge} from './edge';
 
-interface NodeOptions {
+/** Properties for creating a new node */
+export interface NodeOptions {
+  /** the unique ID of the node */
   id: number | string;
   selectable?: boolean;
   highlightConnectedEdges?: boolean;
-  data: Record<string, unknown>;
+  /* origin data reference */
+  data?: Record<string, unknown>;
 }
 
-// Basic data structure of a node
+/** Basic data structure of a node */
 export class Node {
   public id: string | number;
   /** Keep a reference to origin data. */
@@ -29,8 +32,6 @@ export class Node {
   public readonly isNode = true;
   /**
    * The constructor of a node
-   * @param  {String|Number} options.id   - the unique ID of the node
-   * @param  {Record<string, unknown>} options.data - origin data reference
    */
   constructor({id, selectable = false, highlightConnectedEdges = false, data = {}}: NodeOptions) {
     this.id = id;
@@ -41,7 +42,7 @@ export class Node {
 
   /**
    * Return the ID of the node
-   * @return {String|Number} - the ID of the node.
+   * @return - the ID of the node.
    */
   getId(): string | number {
     return this.id;
@@ -57,7 +58,7 @@ export class Node {
 
   /**
    * Return the in-degree of the node.
-   * @return {Number} - the in-degree of the node.
+   * @return - the in-degree of the node.
    */
   getInDegree(): number {
     const nodeId = this.getId();
@@ -72,7 +73,7 @@ export class Node {
 
   /**
    * Return the out-degree of the node.
-   * @return {Number} - the out-degree of the node.
+   * @return - the out-degree of the node.
    */
   getOutDegree(): number {
     const nodeId = this.getId();
@@ -87,7 +88,7 @@ export class Node {
 
   /**
    * Return all the IDs of the sibling nodes.
-   * @return {String[]} [description]
+   * @return [description]
    */
   getSiblingIds(): (string | number)[] {
     const nodeId = this.getId();
@@ -106,7 +107,7 @@ export class Node {
 
   /**
    * Return all the connected edges.
-   * @return {Object[]} - an array of the connected edges.
+   * @return - an array of the connected edges.
    */
   getConnectedEdges(): Edge[] {
     return Object.values(this._connectedEdges);
@@ -114,8 +115,8 @@ export class Node {
 
   /**
    * Return of the value of the selected property key.
-   * @param  {String} key - property key.
-   * @return {Any} - the value of the property or undefined (not found).
+   * @param key - property key.
+   * @return - the value of the property or undefined (not found).
    */
   getPropertyValue(key: string): unknown {
     // try to search the key within this object
@@ -132,7 +133,7 @@ export class Node {
 
   /**
    * Set the new node data.
-   * @param {Record<string, unknown>} data - the new data of the node
+   * @param data - the new data of the node
    */
   setData(data: Record<string, unknown>): void {
     this._data = data;
@@ -140,8 +141,8 @@ export class Node {
 
   /**
    * Update a data property.
-   * @param {String} key - the key of the property
-   * @param {Any} value - the value of the property.
+   * @param key - the key of the property
+   * @param value - the value of the property.
    */
   setDataProperty(key: string, value: unknown): void {
     this._data[key] = value;
@@ -149,7 +150,7 @@ export class Node {
 
   /**
    * Set node state
-   * @param {String} state - one of NODE_STATE
+   * @param state - one of NODE_STATE
    */
   setState(state: ValueOf<typeof NODE_STATE>): void {
     this.state = state;
@@ -157,7 +158,7 @@ export class Node {
 
   /**
    * Get node state
-   * @returns {string} state - one of NODE_STATE
+   * @returns state - one of NODE_STATE
    */
   getState(): ValueOf<typeof NODE_STATE> {
     return this.state;
@@ -165,7 +166,7 @@ export class Node {
 
   /**
    * Add connected edges to the node
-   * @param {Edge || Edge[]} edge an edge or an array of edges to be added to this._connectedEdges
+   * @param edge an edge or an array of edges to be added to this._connectedEdges
    */
   addConnectedEdges(edge: Edge | Edge[]): void {
     const iterableEdges = Array.isArray(edge) ? edge : [edge];
@@ -177,7 +178,7 @@ export class Node {
 
   /**
    * Remove edges from this._connectedEdges
-   * @param {Edge | Edge[]} edge an edge or an array of edges to be removed from this._connectedEdges
+   * @param edge an edge or an array of edges to be removed from this._connectedEdges
    */
   removeConnectedEdges(edge: Edge | Edge[]): void {
     const iterableEdges = Array.isArray(edge) ? edge : [edge];

package/src/index.ts

@@ -2,41 +2,41 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-// react-graph-layers core
+// core - Graph representation and layout
+export {Graph} from './graph/graph';
+export {Node} from './graph/node';
+export {Edge} from './graph/edge';
+
 export {GraphEngine} from './core/graph-engine';
-export {Graph} from './core/graph';
-export {Node} from './core/node';
-export {Edge} from './core/edge';
-export {
-  NODE_STATE,
-  NODE_TYPE,
-  EDGE_TYPE,
-  EDGE_DECORATOR_TYPE,
-  LAYOUT_STATE,
-  MARKER_TYPE
-} from './core/constants';
-
-// react-graph-layers layouts
-export {BaseLayout} from './core/base-layout';
+
+// graph-layers layouts
+export type {GraphLayoutState} from './core/graph-layout';
+export {GraphLayout} from './core/graph-layout';
+
+export {SimpleLayout} from './layouts//simple-layout';
 export {D3ForceLayout} from './layouts/d3-force/d3-force-layout';
 export {GPUForceLayout} from './layouts/gpu-force/gpu-force-layout';
-export {SimpleLayout} from './layouts/simple-layout/simple-layout';
+export {RadialLayout as _RadialLayout} from './layouts/experimental/radial-layout';
+export {ForceMultiGraphLayout as _MultigraphLayout} from './layouts/experimental/force-multi-graph-layout';
+export {HivePlotLayout as _HivePlotLayout} from './layouts/experimental/hive-plot-layout';
 
-// react-graph-layers loaders
-export {JSONLoader} from './loaders/json-loader';
-export {basicNodeParser} from './loaders/node-parsers';
-export {basicEdgeParser} from './loaders/edge-parsers';
-
-// react-graph-layers utils
-export {createGraph} from './utils/create-graph';
-export * from './utils/layer-utils';
-export * from './utils/log';
+export {NODE_STATE, NODE_TYPE, EDGE_TYPE, EDGE_DECORATOR_TYPE, MARKER_TYPE} from './core/constants';
 
 // deck.gl components
 export {GraphLayer} from './layers/graph-layer';
 export {EdgeLayer} from './layers/edge-layer';
 
-// DEPRECATED
+// Widgets
 
-/** @deprecated Use EdgeLayer */
-export {EdgeLayer as CompositeEdgeLayer} from './layers/edge-layer';
+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';
+
+// DEPRECATED
+export {createGraph} from './loaders/create-graph';
+export {JSONLoader} from './loaders/simple-json-graph-loader';