@dxos/app-graph 0.6.3-main.9e4e207 → 0.6.3-next.2f65b78

package/src/graph.ts

@@ -2,47 +2,17 @@
 // Copyright 2023 DXOS.org
 //
 
-import { batch, effect, untracked } from '@preact/signals-core';
+import { untracked } from '@preact/signals-core';
 
-import { Trigger } from '@dxos/async';
-import { type ReactiveObject, create } from '@dxos/echo-schema';
+import { create } from '@dxos/echo-schema';
 import { invariant } from '@dxos/invariant';
 import { nonNullable } from '@dxos/util';
 
-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;
-};
+import { isActionLike, type EdgeDirection, type Node, type NodeArg, type NodeBase } from './node';
 
 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';
-
-const NODE_TIMEOUT = 5_000;
-
-export type NodesOptions<T = any, U extends Record<string, any> = Record<string, any>> = {
-  relation?: Relation;
-  filter?: NodeFilter<T, U>;
-  onlyLoaded?: 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.
    *
@@ -51,54 +21,40 @@ export type GraphTraversalOptions = {
   node?: Node;
 
   /**
-   * The relation to traverse graph edges.
+   * The direction to traverse graph edges.
    *
    * @default 'outbound'
    */
-  relation?: Relation;
+  direction?: EdgeDirection;
 
   /**
-   * Only traverse nodes that are already loaded.
+   * A predicate to filter nodes which are passed to the `visitor` callback.
    */
-  onlyLoaded?: boolean;
+  filter?: (node: Node) => boolean;
+
+  /**
+   * A callback which is called for each node visited during traversal.
+   */
+  visitor?: (node: Node, path: string[]) => void;
 };
 
 /**
  * The Graph represents the structure of the application constructed via plugins.
  */
 export class Graph {
-  private readonly _onInitialNode?: (id: string, type?: string) => NodeArg<any> | undefined;
-  private readonly _onInitialNodes?: (node: Node, relation: Relation, type?: string) => NodeArg<any>[] | undefined;
-  private readonly _onRemoveNode?: (id: string) => void;
-
-  private readonly _waitingForNodes: Record<string, Trigger<Node>> = {};
-  private readonly _initialized: Record<string, boolean> = {};
-
   /**
    * @internal
    */
-  readonly _nodes: Record<string, ReactiveObject<NodeInternal>> = {};
+  readonly _nodes = create<Record<string, NodeBase>>({
+    [ROOT_ID]: { id: ROOT_ID, properties: {}, data: null },
+  });
 
   /**
    * @internal
    */
-  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: [] });
-  }
+  // 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[]>>({});
 
   /**
    * Alias for `findNode('root')`.
@@ -110,16 +66,11 @@ export class Graph {
   /**
    * Convert the graph to a JSON object.
    */
-  toJSON({
-    id = ROOT_ID,
-    maxLength = 32,
-    onlyLoaded = true,
-  }: { id?: string; maxLength?: number; onlyLoaded?: boolean } = {}) {
+  toJSON({ id = ROOT_ID, maxLength = 32 }: { id?: string; maxLength?: number } = {}) {
     const toJSON = (node: Node, seen: string[] = []): any => {
-      const nodes = this.nodes(node, { onlyLoaded });
+      const nodes = node.nodes();
       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;
@@ -143,148 +94,57 @@ 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, type?: string): Node | undefined {
-    const existingNode = this._nodes[id];
-    const nodeArg = !existingNode && this._onInitialNode?.(id, type);
-    return existingNode ?? (nodeArg ? this._addNode(nodeArg) : undefined);
-  }
-
-  /**
-   * 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.
    */
-  waitForNode(id: string, timeout = NODE_TIMEOUT): Promise<Node> {
-    if (this._nodes[id]) {
-      return Promise.resolve(this._nodes[id]);
+  findNode(id: string): Node | undefined {
+    const nodeBase = this._nodes[id];
+    if (!nodeBase) {
+      return undefined;
     }
 
-    const trigger = this._waitingForNodes[id] ?? (this._waitingForNodes[id] = new Trigger<Node>());
-    return trigger.wait({ timeout });
-  }
-
-  /**
-   * 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 { onlyLoaded, relation, filter, type } = options;
-    const nodes = this._getNodes({ node, relation, type, onlyLoaded });
-    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] ?? [];
+    return this._constructNode(nodeBase);
   }
 
-  /**
-   * Actions or action groups that this node is connected to in default order.
-   */
-  actions(node: Node, { onlyLoaded }: { onlyLoaded?: boolean } = {}) {
-    return [
-      ...this._getNodes({ node, type: ACTION_GROUP_TYPE, onlyLoaded }),
-      ...this._getNodes({ node, type: ACTION_TYPE, onlyLoaded }),
-    ];
-  }
+  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);
+      },
+    };
 
-  /**
-   * 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', onlyLoaded }: GraphTraversalOptions,
-    path: string[] = [],
-  ): void {
-    // Break cycles.
-    if (path.includes(node.id)) {
-      return;
-    }
+    return node;
+  };
 
-    const shouldContinue = visitor(node, [...path, node.id]);
-    if (shouldContinue === false) {
-      return;
+  private _getNodes({ id, direction = 'outbound' }: { id: string; direction?: EdgeDirection }): Node[] {
+    const edges = this._edges[this.getEdgeKey(id, direction)];
+    if (!edges) {
+      return [];
     }
 
-    Object.values(this._getNodes({ node, relation, onlyLoaded })).forEach((child) =>
-      this.traverse({ node: child, relation, visitor, onlyLoaded }, [...path, node.id]),
-    );
+    return edges.map((id) => this.findNode(id)).filter(nonNullable);
   }
 
-  /**
-   * 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', onlyLoaded }: 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, onlyLoaded });
-      const nodeSubscriptions = nodes.map((n) => this.subscribeTraverse({ node: n, visitor, onlyLoaded }, 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({
-      onlyLoaded: true,
-      node: start,
-      visitor: (node, path) => {
-        if (found) {
-          return false;
-        }
-
-        if (node.id === target) {
-          found = path;
-        }
-      },
-    });
-
-    return found;
+  private getEdgeKey(id: string, direction: EdgeDirection) {
+    return `${id}-${direction}`;
   }
 
   /**
    * 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 batch(() => nodes.map((node) => this._addNode(node)));
+    return nodes.map((node) => this._addNode(node));
   }
 
   private _addNode<TData, TProperties extends Record<string, any> = Record<string, any>>({
@@ -293,65 +153,35 @@ export class Graph {
     ..._node
   }: NodeArg<TData, TProperties>): Node<TData, TProperties> {
     return untracked(() => {
-      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];
-      }
+      const node = { data: null, properties: {}, ..._node };
+      this._nodes[node.id] = node;
 
       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, relation]) =>
-          relation === 'outbound'
-            ? this._addEdge({ source: node.id, target: id })
-            : this._addEdge({ source: id, target: node.id }),
+        edges.forEach(([id, direction]) =>
+          direction === 'outbound'
+            ? this.addEdge({ source: node.id, target: id })
+            : this.addEdge({ source: id, target: node.id }),
         );
       }
 
-      return node as unknown as Node<TData, TProperties>;
+      return this._constructNode(node) as Node<TData, TProperties>;
     });
   }
 
   /**
    * Remove nodes from the graph.
    *
-   * @param ids The id of the node to remove.
+   * @param id The id of the node to remove.
    * @param edges Whether to remove edges connected to the node from the graph as well.
-   * @internal
    */
-  _removeNodes(ids: string[], edges = false) {
-    batch(() => ids.forEach((id) => this._removeNode(id, edges)));
-  }
-
-  private _removeNode(id: string, edges = false) {
+  removeNode(id: string, edges = false) {
     untracked(() => {
       const node = this.findNode(id);
       if (!node) {
@@ -359,75 +189,40 @@ export class Graph {
       }
 
       if (edges) {
-        // Remove edges from connected nodes.
-        this._getNodes({ node, onlyLoaded: true }).forEach((node) => {
-          this._removeEdge({ source: id, target: node.id });
-        });
-        this._getNodes({ node, relation: 'inbound', onlyLoaded: true }).forEach((node) => {
-          this._removeEdge({ source: node.id, target: id });
-        });
-
         // Remove edges from node.
-        delete this._edges[id];
+        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 }),
+        );
       }
 
       // Remove node.
       delete this._nodes[id];
-      this._onRemoveNode?.(id);
     });
   }
 
   /**
-   * Add edges to the graph.
-   *
-   * @internal
+   * Add an edge to the graph.
    */
-  _addEdges(edges: { source: string; target: string }[]) {
-    batch(() => edges.forEach((edge) => this._addEdge(edge)));
-  }
-
-  private _addEdge({ source, target }: { source: string; target: string }) {
+  addEdge({ source, target }: { source: string; target: string }) {
     untracked(() => {
-      if (!this._edges[source]) {
-        this._edges[source] = create({ inbound: [], outbound: [] });
-      }
-      if (!this._edges[target]) {
-        this._edges[target] = create({ inbound: [], outbound: [] });
+      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);
       }
 
-      const sourceEdges = this._edges[source];
-      if (!sourceEdges.outbound.includes(target)) {
-        sourceEdges.outbound.push(target);
+      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 targetEdges = this._edges[target];
-      if (!targetEdges.inbound.includes(source)) {
-        targetEdges.inbound.push(source);
-      }
-    });
-  }
-
-  /**
-   * Remove edges from the graph.
-   * @internal
-   */
-  _removeEdges(edges: { source: string; target: string }[]) {
-    batch(() => edges.forEach((edge) => this._removeEdge(edge)));
-  }
-
-  private _removeEdge({ source, target }: { source: string; target: string }) {
-    untracked(() => {
-      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[target]?.inbound.findIndex((id) => id === source);
-        if (inboundIndex !== undefined && inboundIndex !== -1) {
-          this._edges[target].inbound.splice(inboundIndex, 1);
-        }
-      });
     });
   }
 
@@ -437,62 +232,80 @@ export class Graph {
    * 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 direction The direction of the edges from the node to sort.
    * @param edges The ordered list of edges.
-   * @ignore
    */
-  _sortEdges(nodeId: string, relation: Relation, edges: string[]) {
+  sortEdges(nodeId: string, direction: EdgeDirection, 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]);
-        }
-      });
+      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]);
+      }
     });
   }
 
-  private _constructNode = (node: Omit<Node, typeof graphSymbol>) => {
-    return create<NodeInternal>({ ...node, [graphSymbol]: this });
-  };
+  /**
+   * Remove an edge from the graph.
+   */
+  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);
+      }
 
-  private _getNodes({
-    node,
-    relation = 'outbound',
-    type,
-    onlyLoaded,
-  }: {
-    node: Node;
-    relation?: Relation;
-    type?: string;
-    onlyLoaded?: boolean;
-  }): Node[] {
-    // TODO(wittjosiah): Factor out helper.
-    const key = `${node.id}-${relation}-${type}`;
-    const initialized = this._initialized[key];
-    if (!initialized && !onlyLoaded && this._onInitialNodes) {
-      const args = this._onInitialNodes(node, relation, type)?.filter((n) => !type || n.type === type);
-      this._initialized[key] = true;
-      if (args && args.length > 0) {
-        const nodes = this._addNodes(args);
-        this._addEdges(
-          nodes.map(({ id }) =>
-            relation === 'outbound' ? { source: node.id, target: id } : { source: id, target: node.id },
-          ),
-        );
+      const inboundIndex = this._edges[this.getEdgeKey(target, 'inbound')]?.findIndex((id) => id === source);
+      if (inboundIndex !== -1) {
+        this._edges[this.getEdgeKey(target, 'inbound')].splice(inboundIndex, 1);
       }
+    });
+  }
+
+  /**
+   * Recursive depth-first traversal.
+   *
+   * @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.
+   */
+  traverse({ node = this.root, direction = 'outbound', filter, visitor }: TraversalOptions, path: string[] = []): void {
+    // Break cycles.
+    if (path.includes(node.id)) {
+      return;
     }
 
-    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);
+    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]),
+    );
+  }
+
+  /**
+   * 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,
+      filter: () => !found,
+      visitor: (node, path) => {
+        if (node.id === target) {
+          found = path;
+        }
+      },
+    });
+
+    return found;
   }
 }

package/src/helpers.ts

@@ -0,0 +1,27 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type Graph } from './graph';
+import { type Node, type NodeArg } from './node';
+
+/**
+ * If the condition is true, adds the nodes to the graph, otherwise removes the nodes from the graph.
+ */
+export const manageNodes = <TData = null, TProperties extends Record<string, any> = Record<string, any>>({
+  graph,
+  condition,
+  nodes,
+  removeEdges,
+}: {
+  graph: Graph;
+  condition: boolean;
+  nodes: NodeArg<TData, TProperties>[];
+  removeEdges?: boolean;
+}): Node<TData, TProperties>[] | void => {
+  if (condition) {
+    return graph.addNodes(...nodes);
+  } else {
+    nodes.forEach(({ id }) => graph.removeNode(id, removeEdges));
+  }
+};

package/src/index.ts

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