@dxos/app-graph 0.6.3-main.d007b87 → 0.6.3-main.d76104f

package/src/graph.ts

@@ -2,17 +2,45 @@
 // Copyright 2023 DXOS.org
 //
 
-import { untracked } from '@preact/signals-core';
+import { batch, effect, untracked } from '@preact/signals-core';
 
-import { create } from '@dxos/echo-schema';
+import { asyncTimeout, Trigger } from '@dxos/async';
+import { type ReactiveObject, create } from '@dxos/echo-schema';
 import { invariant } from '@dxos/invariant';
 import { nonNullable } from '@dxos/util';
 
-import { isActionLike, type EdgeDirection, type Node, type NodeArg, type NodeBase } from './node';
+import { type Relation, type Node, type NodeArg, type NodeFilter, isActionLike } from './node';
+
+const graphSymbol = Symbol('graph');
+type DeepWriteable<T> = { -readonly [K in keyof T]: DeepWriteable<T[K]> };
+type NodeInternal = DeepWriteable<Node> & { [graphSymbol]: Graph };
+
+export const getGraph = (node: Node): Graph => {
+  const graph = (node as NodeInternal)[graphSymbol];
+  invariant(graph, 'Node is not associated with a graph.');
+  return graph;
+};
 
 export const ROOT_ID = 'root';
+export const ROOT_TYPE = 'dxos.org/type/GraphRoot';
+export const ACTION_TYPE = 'dxos.org/type/GraphAction';
+export const ACTION_GROUP_TYPE = 'dxos.org/type/GraphActionGroup';
+
+export type NodesOptions<T = any, U extends Record<string, any> = Record<string, any>> = {
+  relation?: Relation;
+  filter?: NodeFilter<T, U>;
+  expansion?: boolean;
+  type?: string;
+};
+
+export type GraphTraversalOptions = {
+  /**
+   * A callback which is called for each node visited during traversal.
+   *
+   * If the callback returns `false`, traversal is stops recursing.
+   */
+  visitor: (node: Node, path: string[]) => boolean | void;
 
-export type TraversalOptions = {
   /**
    * The node to start traversing from.
    *
@@ -21,40 +49,54 @@ export type TraversalOptions = {
   node?: Node;
 
   /**
-   * The direction to traverse graph edges.
+   * The relation to traverse graph edges.
    *
    * @default 'outbound'
    */
-  direction?: EdgeDirection;
+  relation?: Relation;
 
   /**
-   * A predicate to filter nodes which are passed to the `visitor` callback.
+   * Allow traversal to trigger expansion of the graph via `onInitialNodes`.
    */
-  filter?: (node: Node) => boolean;
-
-  /**
-   * A callback which is called for each node visited during traversal.
-   */
-  visitor?: (node: Node, path: string[]) => void;
+  expansion?: boolean;
 };
 
 /**
  * The Graph represents the structure of the application constructed via plugins.
  */
 export class Graph {
+  private readonly _onInitialNode?: (id: string) => Promise<void>;
+  private readonly _onInitialNodes?: (node: Node, relation: Relation, type?: string) => Promise<void>;
+  private readonly _onRemoveNode?: (id: string) => Promise<void>;
+
+  private readonly _waitingForNodes: Record<string, Trigger<Node>> = {};
+  private readonly _initialized: Record<string, boolean> = {};
+
   /**
    * @internal
    */
-  readonly _nodes = create<Record<string, NodeBase>>({
-    [ROOT_ID]: { id: ROOT_ID, properties: {}, data: null },
-  });
+  readonly _nodes: Record<string, ReactiveObject<NodeInternal>> = {};
 
   /**
    * @internal
    */
-  // Key is the `${node.id}-${direction}` and value is an ordered list of node ids.
-  // Explicit type required because TS says this is not portable.
-  readonly _edges = create<Record<string, string[]>>({});
+  readonly _edges: Record<string, ReactiveObject<{ inbound: string[]; outbound: string[] }>> = {};
+
+  constructor({
+    onInitialNode,
+    onInitialNodes,
+    onRemoveNode,
+  }: {
+    onInitialNode?: Graph['_onInitialNode'];
+    onInitialNodes?: Graph['_onInitialNodes'];
+    onRemoveNode?: Graph['_onRemoveNode'];
+  } = {}) {
+    this._onInitialNode = onInitialNode;
+    this._onInitialNodes = onInitialNodes;
+    this._onRemoveNode = onRemoveNode;
+    this._nodes[ROOT_ID] = this._constructNode({ id: ROOT_ID, type: ROOT_TYPE, properties: {}, data: null });
+    this._edges[ROOT_ID] = create({ inbound: [], outbound: [] });
+  }
 
   /**
    * Alias for `findNode('root')`.
@@ -68,9 +110,10 @@ export class Graph {
    */
   toJSON({ id = ROOT_ID, maxLength = 32 }: { id?: string; maxLength?: number } = {}) {
     const toJSON = (node: Node, seen: string[] = []): any => {
-      const nodes = node.nodes();
+      const nodes = this.nodes(node);
       const obj: Record<string, any> = {
         id: node.id.length > maxLength ? `${node.id.slice(0, maxLength - 3)}...` : node.id,
+        type: node.type,
       };
       if (node.properties.label) {
         obj.label = node.properties.label;
@@ -94,57 +137,166 @@ export class Graph {
 
   /**
    * Find the node with the given id in the graph.
+   *
+   * If a node is not found within the graph and an `onInitialNode` callback is provided,
+   * it is called with the id and type of the node, potentially initializing the node.
    */
   findNode(id: string): Node | undefined {
-    const nodeBase = this._nodes[id];
-    if (!nodeBase) {
-      return undefined;
+    const existingNode = this._nodes[id];
+    if (!existingNode) {
+      void this._onInitialNode?.(id);
     }
 
-    return this._constructNode(nodeBase);
+    return existingNode;
   }
 
-  private _constructNode = (nodeBase: NodeBase): Node => {
-    const node: Node = {
-      ...nodeBase,
-      edges: ({ direction = 'outbound' } = {}) => {
-        return this._edges[this.getEdgeKey(node.id, direction)];
-      },
-      nodes: ({ direction, filter } = {}) => {
-        const nodes = this._getNodes({ id: node.id, direction }).filter((n) => !isActionLike(n));
-        return filter ? nodes.filter((n) => filter(n, node)) : nodes;
-      },
-      node: (id: string) => {
-        return this._getNodes({ id }).find((node) => node.id === id);
-      },
-      actions: () => {
-        return this._getNodes({ id: node.id }).filter(isActionLike);
-      },
-    };
+  /**
+   * Wait for a node to be added to the graph.
+   *
+   * If the node is already present in the graph, the promise resolves immediately.
+   *
+   * @param id The id of the node to wait for.
+   * @param timeout The time in milliseconds to wait for the node to be added.
+   */
+  async waitForNode(id: string, timeout?: number): Promise<Node> {
+    const trigger = this._waitingForNodes[id] ?? (this._waitingForNodes[id] = new Trigger<Node>());
+    const node = this.findNode(id);
+    if (node) {
+      delete this._waitingForNodes[id];
+      return node;
+    }
 
-    return node;
-  };
+    if (timeout === undefined) {
+      return trigger.wait();
+    } else {
+      return asyncTimeout(trigger.wait(), timeout, `Node not found: ${id}`);
+    }
+  }
 
-  private _getNodes({ id, direction = 'outbound' }: { id: string; direction?: EdgeDirection }): Node[] {
-    const edges = this._edges[this.getEdgeKey(id, direction)];
-    if (!edges) {
-      return [];
+  /**
+   * Nodes that this node is connected to in default order.
+   */
+  nodes<T = any, U extends Record<string, any> = Record<string, any>>(node: Node, options: NodesOptions<T, U> = {}) {
+    const { relation, expansion, filter, type } = options;
+    const nodes = this._getNodes({ node, relation, expansion, type });
+    return nodes.filter((n) => untracked(() => !isActionLike(n))).filter((n) => filter?.(n, node) ?? true);
+  }
+
+  /**
+   * Edges that this node is connected to in default order.
+   */
+  edges(node: Node, { relation = 'outbound' }: { relation?: Relation } = {}) {
+    return this._edges[node.id]?.[relation] ?? [];
+  }
+
+  /**
+   * Actions or action groups that this node is connected to in default order.
+   */
+  actions(node: Node, { expansion }: { expansion?: boolean } = {}) {
+    return [
+      ...this._getNodes({ node, expansion, type: ACTION_GROUP_TYPE }),
+      ...this._getNodes({ node, expansion, type: ACTION_TYPE }),
+    ];
+  }
+
+  async expand(node: Node, relation: Relation = 'outbound', type?: string) {
+    // TODO(wittjosiah): Factor out helper.
+    const key = `${node.id}-${relation}-${type}`;
+    const initialized = this._initialized[key];
+    if (!initialized && this._onInitialNodes) {
+      await this._onInitialNodes(node, relation, type);
+      this._initialized[key] = true;
+    }
+  }
+
+  /**
+   * Recursive depth-first traversal of the graph.
+   *
+   * @param options.node The node to start traversing from.
+   * @param options.relation The relation to traverse graph edges.
+   * @param options.visitor A callback which is called for each node visited during traversal.
+   */
+  traverse(
+    { visitor, node = this.root, relation = 'outbound', expansion }: GraphTraversalOptions,
+    path: string[] = [],
+  ): void {
+    // Break cycles.
+    if (path.includes(node.id)) {
+      return;
     }
 
-    return edges.map((id) => this.findNode(id)).filter(nonNullable);
+    const shouldContinue = visitor(node, [...path, node.id]);
+    if (shouldContinue === false) {
+      return;
+    }
+
+    Object.values(this._getNodes({ node, relation, expansion })).forEach((child) =>
+      this.traverse({ node: child, relation, visitor, expansion }, [...path, node.id]),
+    );
   }
 
-  private getEdgeKey(id: string, direction: EdgeDirection) {
-    return `${id}-${direction}`;
+  /**
+   * Recursive depth-first traversal of the graph wrapping each visitor call in an effect.
+   *
+   * @param options.node The node to start traversing from.
+   * @param options.relation The relation to traverse graph edges.
+   * @param options.visitor A callback which is called for each node visited during traversal.
+   */
+  subscribeTraverse(
+    { visitor, node = this.root, relation = 'outbound', expansion }: GraphTraversalOptions,
+    currentPath: string[] = [],
+  ) {
+    return effect(() => {
+      const path = [...currentPath, node.id];
+      const result = visitor(node, path);
+      if (result === false) {
+        return;
+      }
+
+      const nodes = this._getNodes({ node, relation, expansion });
+      const nodeSubscriptions = nodes.map((n) => this.subscribeTraverse({ node: n, visitor, expansion }, path));
+
+      return () => {
+        nodeSubscriptions.forEach((unsubscribe) => unsubscribe());
+      };
+    });
+  }
+
+  /**
+   * Get the path between two nodes in the graph.
+   */
+  getPath({ source = 'root', target }: { source?: string; target: string }): string[] | undefined {
+    const start = this.findNode(source);
+    if (!start) {
+      return undefined;
+    }
+
+    let found: string[] | undefined;
+    this.traverse({
+      node: start,
+      visitor: (node, path) => {
+        if (found) {
+          return false;
+        }
+
+        if (node.id === target) {
+          found = path;
+        }
+      },
+    });
+
+    return found;
   }
 
   /**
    * Add nodes to the graph.
+   *
+   * @internal
    */
-  addNodes<TData = null, TProperties extends Record<string, any> = Record<string, any>>(
-    ...nodes: NodeArg<TData, TProperties>[]
+  _addNodes<TData = null, TProperties extends Record<string, any> = Record<string, any>>(
+    nodes: NodeArg<TData, TProperties>[],
   ): Node<TData, TProperties>[] {
-    return nodes.map((node) => this._addNode(node));
+    return batch(() => nodes.map((node) => this._addNode(node)));
   }
 
   private _addNode<TData, TProperties extends Record<string, any> = Record<string, any>>({
@@ -153,35 +305,65 @@ export class Graph {
     ..._node
   }: NodeArg<TData, TProperties>): Node<TData, TProperties> {
     return untracked(() => {
-      const node = { data: null, properties: {}, ..._node };
-      this._nodes[node.id] = node;
+      const existingNode = this._nodes[_node.id];
+      const node = existingNode ?? this._constructNode({ data: null, properties: {}, ..._node });
+      if (existingNode) {
+        const { data, properties, type } = _node;
+        if (data && data !== node.data) {
+          node.data = data;
+        }
+
+        if (type !== node.type) {
+          node.type = type;
+        }
+
+        for (const key in properties) {
+          if (properties[key] !== node.properties[key]) {
+            node.properties[key] = properties[key];
+          }
+        }
+      } else {
+        this._nodes[node.id] = node;
+        this._edges[node.id] = create({ inbound: [], outbound: [] });
+      }
+
+      const trigger = this._waitingForNodes[node.id];
+      if (trigger) {
+        trigger.wake(node);
+        delete this._waitingForNodes[node.id];
+      }
 
       if (nodes) {
         nodes.forEach((subNode) => {
           this._addNode(subNode);
-          this.addEdge({ source: node.id, target: subNode.id });
+          this._addEdge({ source: node.id, target: subNode.id });
         });
       }
 
       if (edges) {
-        edges.forEach(([id, direction]) =>
-          direction === 'outbound'
-            ? this.addEdge({ source: node.id, target: id })
-            : this.addEdge({ source: id, target: node.id }),
+        edges.forEach(([id, relation]) =>
+          relation === 'outbound'
+            ? this._addEdge({ source: node.id, target: id })
+            : this._addEdge({ source: id, target: node.id }),
         );
       }
 
-      return this._constructNode(node) as Node<TData, TProperties>;
+      return node as unknown as Node<TData, TProperties>;
     });
   }
 
   /**
    * Remove nodes from the graph.
    *
-   * @param id The id of the node to remove.
+   * @param ids The id of the node to remove.
    * @param edges Whether to remove edges connected to the node from the graph as well.
+   * @internal
    */
-  removeNode(id: string, edges = false) {
+  _removeNodes(ids: string[], edges = false) {
+    batch(() => ids.forEach((id) => this._removeNode(id, edges)));
+  }
+
+  private _removeNode(id: string, edges = false) {
     untracked(() => {
       const node = this.findNode(id);
       if (!node) {
@@ -189,123 +371,128 @@ export class Graph {
       }
 
       if (edges) {
-        // Remove edges from node.
-        delete this._edges[this.getEdgeKey(id, 'outbound')];
-        delete this._edges[this.getEdgeKey(id, 'inbound')];
-
         // Remove edges from connected nodes.
-        this._getNodes({ id }).forEach((node) => this.removeEdge({ source: id, target: node.id }));
-        this._getNodes({ id, direction: 'inbound' }).forEach((node) =>
-          this.removeEdge({ source: node.id, target: id }),
-        );
+        this._getNodes({ node }).forEach((node) => {
+          this._removeEdge({ source: id, target: node.id });
+        });
+        this._getNodes({ node, relation: 'inbound' }).forEach((node) => {
+          this._removeEdge({ source: node.id, target: id });
+        });
+
+        // Remove edges from node.
+        delete this._edges[id];
       }
 
       // Remove node.
       delete this._nodes[id];
+      void this._onRemoveNode?.(id);
     });
   }
 
   /**
-   * Add an edge to the graph.
+   * Add edges to the graph.
+   *
+   * @internal
    */
-  addEdge({ source, target }: { source: string; target: string }) {
+  _addEdges(edges: { source: string; target: string }[]) {
+    batch(() => edges.forEach((edge) => this._addEdge(edge)));
+  }
+
+  private _addEdge({ source, target }: { source: string; target: string }) {
     untracked(() => {
-      const outbound = this._edges[this.getEdgeKey(source, 'outbound')];
-      if (!outbound) {
-        this._edges[this.getEdgeKey(source, 'outbound')] = [target];
-      } else if (!outbound.includes(target)) {
-        outbound.push(target);
+      if (!this._edges[source]) {
+        this._edges[source] = create({ inbound: [], outbound: [] });
+      }
+      if (!this._edges[target]) {
+        this._edges[target] = create({ inbound: [], outbound: [] });
       }
 
-      const inbound = this._edges[this.getEdgeKey(target, 'inbound')];
-      if (!inbound) {
-        this._edges[this.getEdgeKey(target, 'inbound')] = [source];
-      } else if (!inbound.includes(source)) {
-        inbound.push(source);
+      const sourceEdges = this._edges[source];
+      if (!sourceEdges.outbound.includes(target)) {
+        sourceEdges.outbound.push(target);
       }
-    });
-  }
 
-  /**
-   * Sort edges for a node.
-   *
-   * Edges not included in the sorted list are appended to the end of the list.
-   *
-   * @param nodeId The id of the node to sort edges for.
-   * @param direction The direction of the edges from the node to sort.
-   * @param edges The ordered list of edges.
-   */
-  sortEdges(nodeId: string, direction: EdgeDirection, edges: string[]) {
-    untracked(() => {
-      const current = this._edges[this.getEdgeKey(nodeId, direction)];
-      if (current) {
-        const unsorted = current.filter((id) => !edges.includes(id)) ?? [];
-        const sorted = edges.filter((id) => current.includes(id)) ?? [];
-        current.splice(0, current.length, ...[...sorted, ...unsorted]);
+      const targetEdges = this._edges[target];
+      if (!targetEdges.inbound.includes(source)) {
+        targetEdges.inbound.push(source);
       }
     });
   }
 
   /**
-   * Remove an edge from the graph.
+   * Remove edges from the graph.
+   * @internal
    */
-  removeEdge({ source, target }: { source: string; target: string }) {
+  _removeEdges(edges: { source: string; target: string }[]) {
+    batch(() => edges.forEach((edge) => this._removeEdge(edge)));
+  }
+
+  private _removeEdge({ source, target }: { source: string; target: string }) {
     untracked(() => {
-      const outboundIndex = this._edges[this.getEdgeKey(source, 'outbound')]?.findIndex((id) => id === target);
-      if (outboundIndex !== -1) {
-        this._edges[this.getEdgeKey(source, 'outbound')].splice(outboundIndex, 1);
-      }
+      batch(() => {
+        const outboundIndex = this._edges[source]?.outbound.findIndex((id) => id === target);
+        if (outboundIndex !== undefined && outboundIndex !== -1) {
+          this._edges[source].outbound.splice(outboundIndex, 1);
+        }
 
-      const inboundIndex = this._edges[this.getEdgeKey(target, 'inbound')]?.findIndex((id) => id === source);
-      if (inboundIndex !== -1) {
-        this._edges[this.getEdgeKey(target, 'inbound')].splice(inboundIndex, 1);
-      }
+        const inboundIndex = this._edges[target]?.inbound.findIndex((id) => id === source);
+        if (inboundIndex !== undefined && inboundIndex !== -1) {
+          this._edges[target].inbound.splice(inboundIndex, 1);
+        }
+      });
     });
   }
 
   /**
-   * Recursive depth-first traversal.
+   * Sort edges for a node.
    *
-   * @param options.node The node to start traversing from.
-   * @param options.direction The direction to traverse graph edges.
-   * @param options.filter A predicate to filter nodes which are passed to the `visitor` callback.
-   * @param options.visitor A callback which is called for each node visited during traversal.
+   * Edges not included in the sorted list are appended to the end of the list.
+   *
+   * @param nodeId The id of the node to sort edges for.
+   * @param relation The relation of the edges from the node to sort.
+   * @param edges The ordered list of edges.
+   * @ignore
    */
-  traverse({ node = this.root, direction = 'outbound', filter, visitor }: TraversalOptions, path: string[] = []): void {
-    // Break cycles.
-    if (path.includes(node.id)) {
-      return;
-    }
-
-    if (!filter || filter(node)) {
-      visitor?.(node, [...path, node.id]);
-    }
-
-    Object.values(this._getNodes({ id: node.id, direction })).forEach((child) =>
-      this.traverse({ node: child, direction, filter, visitor }, [...path, node.id]),
-    );
+  _sortEdges(nodeId: string, relation: Relation, edges: string[]) {
+    untracked(() => {
+      batch(() => {
+        const current = this._edges[nodeId];
+        if (current) {
+          const unsorted = current[relation].filter((id) => !edges.includes(id)) ?? [];
+          const sorted = edges.filter((id) => current[relation].includes(id)) ?? [];
+          current[relation].splice(0, current[relation].length, ...[...sorted, ...unsorted]);
+        }
+      });
+    });
   }
 
-  /**
-   * Get the path between two nodes in the graph.
-   */
-  getPath({ source = 'root', target }: { source?: string; target: string }): string[] | undefined {
-    const start = this.findNode(source);
-    if (!start) {
-      return undefined;
-    }
+  private _constructNode = (node: Omit<Node, typeof graphSymbol>) => {
+    return create<NodeInternal>({ ...node, [graphSymbol]: this });
+  };
 
-    let found: string[] | undefined;
-    this.traverse({
-      node: start,
-      filter: () => !found,
-      visitor: (node, path) => {
-        if (node.id === target) {
-          found = path;
-        }
-      },
-    });
+  private _getNodes({
+    node,
+    relation = 'outbound',
+    type,
+    expansion,
+  }: {
+    node: Node;
+    relation?: Relation;
+    type?: string;
+    expansion?: boolean;
+  }): Node[] {
+    if (expansion) {
+      void this.expand(node, relation, type);
+    }
 
-    return found;
+    const edges = this._edges[node.id];
+    if (!edges) {
+      return [];
+    } else {
+      return edges[relation]
+        .map((id) => this._nodes[id])
+        .filter(nonNullable)
+        .filter((n) => !type || n.type === type);
+    }
   }
 }

package/src/index.ts

@@ -4,5 +4,4 @@
 
 export * from './graph';
 export * from './graph-builder';
-export * from './helpers';
 export * from './node';