@deck.gl-community/graph-layers 9.0.0

package/dist/core/graph-engine.js

@@ -0,0 +1,128 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+import { Cache } from './cache';
+// Graph engine controls the graph data and layout calculation
+export class GraphEngine extends EventTarget {
+    _graph;
+    _layout;
+    _cache = new Cache();
+    _layoutDirty = false;
+    _transactionInProgress = false;
+    constructor(graph, layout) {
+        super();
+        this._graph = graph;
+        this._layout = layout;
+    }
+    /** Getters */
+    getNodes = () => {
+        this._updateCache('nodes', () => this._graph.getNodes().filter((node) => this.getNodePosition(node)));
+        return this._cache.get('nodes');
+    };
+    getEdges = () => {
+        this._updateCache('edges', () => this._graph.getEdges().filter((edge) => this.getEdgePosition(edge)));
+        return this._cache.get('edges');
+    };
+    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/dist/core/graph.d.ts

@@ -0,0 +1,155 @@
+import { Edge } from './edge';
+import { Node } from './node';
+export declare class Graph extends EventTarget {
+    /** List object of nodes. */
+    private _nodeMap;
+    /** List of object edges. */
+    private _edgeMap;
+    /**
+     * 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;
+    /** Version the graph. A version is a number that is incremented every time the graph is updated. */
+    version: number;
+    /** Cached data: create array data from maps. */
+    private _cache;
+    /**
+     * The constructor of the Graph class.
+     * @param  {Object} graph - copy the graph if this exists.
+     */
+    constructor(graph?: Graph | null);
+    /**
+     * Set graph name
+     * @param {string} name
+     */
+    setGraphName(name: string): void;
+    /** Get the name of the graph. Default value is the time stamp when creating this graph.
+     * @return {string} graph name.
+     */
+    getGraphName(): string;
+    /**
+     * 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;
+    /**
+     * Add a new node to the graph.
+     * @param {Node} node - expect a Node object to be added to the graph.
+     */
+    addNode(node: Node): void;
+    /**
+     * Batch add nodes to the graph.
+     * @param  {Node[]} nodes - a list of nodes to be added.
+     */
+    batchAddNodes(nodes: Node[]): void;
+    /**
+     * Get all the nodes of the graph.
+     * @return {Node[]} - get all the nodes in the graph.
+     */
+    getNodes(): 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>;
+    /**
+     * Find a node by id
+     * @param  {String} nodeId The id of the node
+     * @return {Object} Node
+     */
+    findNode(nodeId: string | number): Node | undefined;
+    /**
+     * Update the indicated node to the provided value
+     * @param {Node} node
+     */
+    updateNode(node: Node): void;
+    /**
+     * Add a new edge to the graph.
+     * @param {Edge} edge - expect a Edge object to be added to the graph.
+     */
+    addEdge(edge: Edge): void;
+    /**
+     * Batch add edges to the graph
+     * @param  {Edge[]} edges - a list of edges to be added.
+     */
+    batchAddEdges(edges: Edge[]): void;
+    /**
+     * Update the indicated edge to the provided value
+     * @param {Edge} edge
+     */
+    updateEdge(edge: Edge): void;
+    /**
+     * Remove a node from the graph by node ID
+     * @param  {String|Number} nodeId - the ID of the target node.
+     */
+    removeNode(nodeId: string | number): void;
+    /**
+     * Get all the edges of the graph.
+     * @return {Edge[]} get all the edges in the graph.
+     */
+    getEdges(): 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>;
+    /**
+     * Remove an edge from the graph by the edge ID
+     * @param  {String|Number} edgeId - the target edge ID.
+     */
+    removeEdge(edgeId: string | number): void;
+    /**
+     * 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 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[];
+    /**
+     * 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[];
+    /**
+     * 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;
+    /**
+     * Clean up all the nodes in the graph.
+     */
+    resetNodes(): void;
+    /**
+     * Clean up all the edges in the graph.
+     */
+    resetEdges(): void;
+    /**
+     * Clean up everything in the graph.
+     */
+    reset(): void;
+    /**
+     * Trigger an update to the graph.
+     */
+    triggerUpdate(): void;
+    /**
+     * Return true if the graph is empty.
+     * @return {Boolean} Return true if the graph is empty.
+     */
+    isEmpty(): boolean;
+    /**
+     * 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;
+    _bumpVersion(): void;
+    _updateCache(key: 'nodes' | 'edges', updateValue: unknown): void;
+}

package/dist/core/graph.js

@@ -0,0 +1,301 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+import { log } from '../utils/log';
+import { Cache } from './cache';
+// Basic graph data structure
+export class Graph extends EventTarget {
+    /** List object of nodes. */
+    _nodeMap = {};
+    /** List of object edges. */
+    _edgeMap = {};
+    /**
+     * 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.
+     */
+    _name = Date.now().toString();
+    /** Version the graph. A version is a number that is incremented every time the graph is updated. */
+    version = 0;
+    /** Cached data: create array data from maps. */
+    _cache = new Cache();
+    /**
+     * The constructor of the Graph class.
+     * @param  {Object} graph - copy the graph if this exists.
+     */
+    constructor(graph = 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) {
+        this._name = name;
+    }
+    /** Get the name of the graph. Default value is the time stamp when creating this graph.
+     * @return {string} graph name.
+     */
+    getGraphName() {
+        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(cb) {
+        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) {
+        // 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 }));
+    }
+    /**
+     * Batch add nodes to the graph.
+     * @param  {Node[]} nodes - a list of nodes to be added.
+     */
+    batchAddNodes(nodes) {
+        // convert an array of objects to an object
+        this._nodeMap = nodes.reduce((res, node) => {
+            res[node.getId()] = node;
+            this.dispatchEvent(new CustomEvent('onNodeAdded', { node }));
+            return res;
+        }, { ...this._nodeMap });
+        this._bumpVersion();
+    }
+    /**
+     * Get all the nodes of the graph.
+     * @return {Node[]} - get all the nodes in the graph.
+     */
+    getNodes() {
+        this._updateCache('nodes', () => Object.values(this._nodeMap));
+        return this._cache.get('nodes');
+    }
+    /**
+     * 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() {
+        return this._nodeMap;
+    }
+    /**
+     * Find a node by id
+     * @param  {String} nodeId The id of the node
+     * @return {Object} Node
+     */
+    findNode(nodeId) {
+        return this._nodeMap[nodeId];
+    }
+    /**
+     * Update the indicated node to the provided value
+     * @param {Node} node
+     */
+    updateNode(node) {
+        this._nodeMap[node.getId()] = node;
+        this._bumpVersion();
+        this.dispatchEvent(new CustomEvent('onNodeUpdated', { node }));
+    }
+    /**
+     * Add a new edge to the graph.
+     * @param {Edge} edge - expect a Edge object to be added to the graph.
+     */
+    addEdge(edge) {
+        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 }));
+    }
+    /**
+     * Batch add edges to the graph
+     * @param  {Edge[]} edges - a list of edges to be added.
+     */
+    batchAddEdges(edges) {
+        edges.forEach((edge) => this.addEdge(edge));
+        this._bumpVersion();
+    }
+    /**
+     * Update the indicated edge to the provided value
+     * @param {Edge} edge
+     */
+    updateEdge(edge) {
+        this._edgeMap[edge.getId()] = edge;
+        this._bumpVersion();
+        this.dispatchEvent(new CustomEvent('onEdgeUpdated', { edge }));
+    }
+    /**
+     * Remove a node from the graph by node ID
+     * @param  {String|Number} nodeId - the ID of the target node.
+     */
+    removeNode(nodeId) {
+        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 }));
+    }
+    /**
+     * Get all the edges of the graph.
+     * @return {Edge[]} get all the edges in the graph.
+     */
+    getEdges() {
+        this._updateCache('edges', () => Object.values(this._edgeMap));
+        return this._cache.get('edges');
+    }
+    /**
+     * 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() {
+        return this._edgeMap;
+    }
+    /**
+     * Remove an edge from the graph by the edge ID
+     * @param  {String|Number} edgeId - the target edge ID.
+     */
+    removeEdge(edgeId) {
+        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) {
+        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) {
+        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) {
+        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) {
+        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() {
+        this._nodeMap = {};
+        this._bumpVersion();
+    }
+    /**
+     * Clean up all the edges in the graph.
+     */
+    resetEdges() {
+        this._edgeMap = {};
+        this._bumpVersion();
+    }
+    /**
+     * Clean up everything in the graph.
+     */
+    reset() {
+        this.resetNodes();
+        this.resetEdges();
+        this._bumpVersion();
+    }
+    /**
+     * Trigger an update to the graph.
+     */
+    triggerUpdate() {
+        this._bumpVersion();
+    }
+    /**
+     * Return true if the graph is empty.
+     * @return {Boolean} Return true if the graph is empty.
+     */
+    isEmpty() {
+        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) {
+        if (!g || !(g instanceof Graph)) {
+            return false;
+        }
+        return this.version === g.version;
+    }
+    _bumpVersion() {
+        this.version += 1;
+    }
+    _updateCache(key, updateValue) {
+        this._cache.set(key, updateValue, this.version);
+    }
+}

package/dist/core/interaction-manager.d.ts

@@ -0,0 +1,40 @@
+import { GraphEngine } from './graph-engine';
+import { Node } from './node';
+interface EventMap {
+    onClick?: (info: unknown, event: Event) => void;
+    onHover?: (info: unknown) => void;
+    onMouseEnter?: (info: unknown) => void;
+    onMouseLeave?: (node: Node) => void;
+    onDragStart?: (info: unknown) => void;
+    onDrag?: (info: unknown) => void;
+    onDragEnd?: (info: unknown) => void;
+}
+export interface InteractionManagerProps {
+    nodeEvents?: EventMap;
+    edgeEvents?: EventMap;
+    engine: GraphEngine;
+    enableDragging: boolean;
+    resumeLayoutAfterDragging: boolean;
+}
+export declare class InteractionManager {
+    notifyCallback: Function;
+    private _lastInteraction;
+    private _lastHoveredNode;
+    private _lastSelectedNode;
+    nodeEvents: EventMap;
+    edgeEvents: EventMap;
+    engine: GraphEngine;
+    enableDragging: boolean;
+    resumeLayoutAfterDragging: boolean;
+    constructor(props: InteractionManagerProps, notifyCallback: Function);
+    updateProps({ nodeEvents, edgeEvents, engine, enableDragging, resumeLayoutAfterDragging }: InteractionManagerProps): void;
+    getLastInteraction(): number;
+    onClick(info: any, event: any): void;
+    _mouseLeaveNode(): void;
+    _mouseEnterNode(info: any): void;
+    onHover(info: any, event: any): void;
+    onDragStart(info: any, event: any): void;
+    onDrag(info: any, event: any): void;
+    onDragEnd(info: any, event: any): void;
+}
+export {};