@dxos/app-graph 0.4.6 → 0.4.7-main.0aeacda

package/src/graph.ts

@@ -2,25 +2,30 @@
 // Copyright 2023 DXOS.org
 //
 
-import { deepSignal } from 'deepsignal/react';
-// TODO(wittjosiah): Remove lodash dependency.
-import get from 'lodash.get';
+import { untracked } from '@preact/signals-core';
+import { type DeepSignal, deepSignal } from 'deepsignal/react';
 
 import { invariant } from '@dxos/invariant';
+import { nonNullable } from '@dxos/util';
 
-import { type Label } from './action';
-import { type Node } from './node';
+import { isActionLike, type EdgeDirection, type Node, type NodeArg, type NodeBase } from './node';
+
+export const ROOT_ID = 'root';
 
 export type TraversalOptions = {
   /**
-   * The node to start traversing from. Defaults to the root node.
+   * The node to start traversing from.
+   *
+   * @default root
    */
   node?: Node;
 
   /**
-   * The direction to traverse the graph. Defaults to 'down'.
+   * The direction to traverse graph edges.
+   *
+   * @default 'outbound'
    */
-  direction?: 'up' | 'down';
+  direction?: EdgeDirection;
 
   /**
    * A predicate to filter nodes which are passed to the `visitor` callback.
@@ -37,76 +42,264 @@ export type TraversalOptions = {
  * The Graph represents the structure of the application constructed via plugins.
  */
 export class Graph {
-  // TODO(wittjosiah): Should this support multiple paths to the same node?
-  private readonly _index = deepSignal<Record<string, string[]>>({});
+  /**
+   * @internal
+   */
+  readonly _nodes = deepSignal<Record<string, NodeBase>>({
+    [ROOT_ID]: { id: ROOT_ID, properties: {}, data: null },
+  });
 
-  constructor(private readonly _root: Node) {}
+  /**
+   * @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: DeepSignal<Record<string, string[]>> = deepSignal({});
 
-  toJSON() {
-    const toLabel = (label: Label) => (Array.isArray(label) ? `${label[1].ns}[${label[0]}]` : label);
+  /**
+   * Alias for `findNode('root')`.
+   */
+  get root() {
+    return this.findNode(ROOT_ID)!;
+  }
+
+  /**
+   * Convert the graph to a JSON object.
+   */
+  toJSON({ id = ROOT_ID, maxLength = 32 }: { id?: string; maxLength?: number } = {}) {
     const toJSON = (node: Node): any => {
-      return {
-        id: node.id.slice(0, 16),
-        label: toLabel(node.label),
-        children: node.children.length ? node.children.map((node) => toJSON(node)) : undefined,
-        actions: node.actions.length
-          ? node.actions.map(({ id, label }) => ({
-              id,
-              label: toLabel(label),
-            }))
-          : undefined,
+      const nodes = node.nodes();
+      const obj: Record<string, any> = {
+        id: node.id.length > maxLength ? `${node.id.slice(0, maxLength - 3)}...` : node.id,
       };
+      if (node.properties.label) {
+        obj.label = node.properties.label;
+      }
+      if (nodes.length) {
+        obj.nodes = nodes.map((node) => toJSON(node));
+      }
+      return obj;
     };
 
-    return toJSON(this._root);
+    const root = this.findNode(id);
+    invariant(root, `Node not found: ${id}`);
+    return toJSON(root);
+  }
+
+  /**
+   * Find the node with the given id in the graph.
+   */
+  findNode(id: string): Node | undefined {
+    const nodeBase = this._nodes[id];
+    if (!nodeBase) {
+      return undefined;
+    }
+
+    return this._constructNode(nodeBase);
+  }
+
+  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);
+      },
+    };
+
+    return node;
+  };
+
+  private _getNodes({ id, direction = 'outbound' }: { id: string; direction?: EdgeDirection }): Node[] {
+    const edges = this._edges[this.getEdgeKey(id, direction)];
+    if (!edges) {
+      return [];
+    }
+
+    return edges.map((id) => this.findNode(id)).filter(nonNullable);
+  }
+
+  private getEdgeKey(id: string, direction: EdgeDirection) {
+    return `${id}-${direction}`;
   }
 
   /**
-   * The root node of the graph which is the entry point for all knowledge.
+   * Add nodes to the graph.
    */
-  get root(): Node {
-    return this._root;
+  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));
+  }
+
+  private _addNode<TData, TProperties extends Record<string, any> = Record<string, any>>({
+    nodes,
+    edges,
+    ..._node
+  }: NodeArg<TData, TProperties>): Node<TData, TProperties> {
+    return untracked(() => {
+      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 });
+        });
+      }
+
+      if (edges) {
+        edges.forEach(([id, direction]) =>
+          direction === 'outbound'
+            ? this.addEdge({ source: node.id, target: id })
+            : this.addEdge({ source: id, target: node.id }),
+        );
+      }
+
+      return this._constructNode(node) as Node<TData, TProperties>;
+    });
   }
 
   /**
-   * Get the path through the graph from the root to the node with the given id.
+   * Remove nodes from the graph.
+   *
+   * @param id The id of the node to remove.
+   * @param edges Whether to remove edges connected to the node from the graph as well.
    */
-  getPath(id: string): string[] | undefined {
-    return this._index[id];
+  removeNode(id: string, edges = false) {
+    untracked(() => {
+      const node = this.findNode(id);
+      if (!node) {
+        return;
+      }
+
+      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 }),
+        );
+      }
+
+      // Remove node.
+      delete this._nodes[id];
+    });
   }
 
   /**
-   * @internal
+   * Add an edge to the graph.
    */
-  _setPath(id: string, path: string[]) {
-    invariant(id && path, 'Invalid path.');
-    this._index[id] = path;
+  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);
+      }
+
+      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);
+      }
+    });
   }
 
   /**
-   * Find the node with the given id in the graph.
+   * 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.
    */
-  findNode(id: string): Node | undefined {
-    const path = this.getPath(id);
-    if (!path) {
-      return undefined;
-    }
+  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]);
+      }
+    });
+  }
 
-    return path.length > 0 ? get(this._root, path) : this._root;
+  /**
+   * 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);
+      }
+
+      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 breadth-first traversal.
+   * 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 = 'down', filter, visitor }: TraversalOptions, depth = 0): void {
+  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, this.getPath(node.id)!);
+      visitor?.(node, [...path, node.id]);
     }
 
-    if (direction === 'down') {
-      Object.values(node.children).forEach((child) => this.traverse({ node: child, filter, visitor }));
-    } else if (direction === 'up' && node.parent) {
-      this.traverse({ node: node.parent, direction, filter, visitor }, depth + 1);
+    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

@@ -2,7 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
-export * from './action';
 export * from './graph';
 export * from './graph-builder';
+export * from './helpers';
 export * from './node';

package/src/node.ts

@@ -2,56 +2,21 @@
 // Copyright 2023 DXOS.org
 //
 
-import type { IconProps } from '@phosphor-icons/react';
-import { type FC } from 'react';
-
-import type { UnsubscribeCallback } from '@dxos/async';
-
-import { type ActionArg, type Action, type Label } from './action';
-
-/**
- * Called when a node is added to the graph, allowing other node builders to add children, actions or properties.
- */
-export type NodeBuilder = (parent: Node) => UnsubscribeCallback | void;
+import { type MaybePromise, type MakeOptional } from '@dxos/util';
 
 /**
  * Represents a node in the graph.
  */
-export type Node<TData = any, TProperties extends Record<string, any> = Record<string, any>> = {
+// TODO(wittjosiah): Use Effect Schema.
+export type NodeBase<TData = any, TProperties extends Record<string, any> = Record<string, any>> = {
   /**
    * Globally unique ID.
    */
   id: string;
 
-  /**
-   * Parent node in the graph.
-   */
-  parent: Node | null;
-
-  /**
-   * Label to be used when displaying the node.
-   * For default labels, use a translated string.
-   *
-   * @example 'My Node'
-   * @example ['unknown node label, { ns: 'example-plugin' }]
-   */
-  label: Label;
-
-  /**
-   * Description to be used when displaying a detailed view of the node.
-   * For default descriptions, use a translated string.
-   */
-  description?: Label;
-
-  /**
-   * Icon to be used when displaying the node.
-   */
-  icon?: FC<IconProps>;
-
   /**
    * Properties of the node relevant to displaying the node.
    */
-  // TODO(burdon): Make this extensible and move label, description, and icon into here?
   properties: TProperties;
 
   /**
@@ -59,50 +24,97 @@ export type Node<TData = any, TProperties extends Record<string, any> = Record<s
    */
   // TODO(burdon): Type system (e.g., minimally provide identifier string vs. TypedObject vs. Graph mixin type system)?
   //  type field would prevent convoluted sniffing of object properties. And allow direct pass-through for ECHO TypedObjects.
-  // TODO(burdon): In some places `null` is cast to TData so make optional?
   data: TData;
+};
 
+export type NodeFilter<T = any, U extends Record<string, any> = Record<string, any>> = (
+  node: Node<unknown, Record<string, any>>,
+  connectedNode: Node,
+) => node is Node<T, U>;
+
+export type EdgeDirection = 'outbound' | 'inbound';
+
+export type ConnectedNodes = {
   /**
-   * Children of the node stored by their id.
+   * Edges that this node is connected to in default order.
    */
-  // TODO(burdon): Rename nodes/nodeMap?
-  childrenMap: Record<string, Node>;
+  edges(params?: { direction?: EdgeDirection }): Readonly<string[]>;
 
   /**
-   * Actions of the node stored by their id.
+   * Nodes that this node is connected to in default order.
    */
-  actionsMap: Record<string, Action>;
+  nodes<T = any, U extends Record<string, any> = Record<string, any>>(params?: {
+    direction?: EdgeDirection;
+    filter?: NodeFilter<T, U>;
+  }): Node<T>[];
 
   /**
-   * Children of the node in default order.
+   * Get a specific connected node by id.
    */
-  get children(): Node[];
+  node(id: string): Node | undefined;
+};
 
+export type ConnectedActions = {
   /**
-   * Actions of the node in default order.
+   * Actions or action groups that this node is connected to in default order.
    */
-  get actions(): Action[];
+  actions(): ActionLike[];
+};
 
-  addProperty(key: string, value: any): void;
-  removeProperty(key: string): void;
+export type Node<TData = any, TProperties extends Record<string, any> = Record<string, any>> = Readonly<
+  Omit<NodeBase<TData, TProperties>, 'properties'> & { properties: Readonly<TProperties> } & ConnectedNodes &
+    ConnectedActions
+>;
 
-  addNode<TChildData = null, TChildProperties extends Record<string, any> = Record<string, any>>(
-    id: string,
-    ...node: NodeArg<TChildData, TChildProperties>[]
-  ): Node<TChildData, TChildProperties>[];
-  removeNode(id: string): Node;
+export const isGraphNode = (data: unknown): data is Node =>
+  data && typeof data === 'object' && 'id' in data && 'properties' in data && data.properties
+    ? typeof data.properties === 'object' && 'data' in data
+    : false;
+
+export type NodeArg<TData, TProperties extends Record<string, any> = Record<string, any>> = MakeOptional<
+  NodeBase<TData, TProperties>,
+  'data' | 'properties'
+> & {
+  /** Will automatically add nodes with an edge from this node to each. */
+  nodes?: NodeArg<unknown>[];
+
+  /** Will automatically add specified edges. */
+  edges?: [string, EdgeDirection][];
+};
+
+//
+// Actions
+//
 
-  addAction<TActionProperties extends Record<string, any> = Record<string, any>>(
-    ...action: ActionArg<TActionProperties>[]
-  ): Action<TActionProperties>[];
-  removeAction(id: string): Action;
+export type InvokeParams = {
+  /** Node the invoked action is connected to. */
+  node: Node;
+
+  caller?: string;
 };
 
-export type NodeArg<TData = null, TProperties extends Record<string, any> = Record<string, any>> = Pick<
-  Node,
-  'id' | 'label'
-> &
-  Partial<Omit<Node<TData, TProperties>, 'id' | 'label' | 'actions'>> & { actions?: ActionArg[] };
+export type ActionData = (params: InvokeParams) => MaybePromise<void>;
 
-export const isGraphNode = (data: unknown): data is Node =>
-  data && typeof data === 'object' ? 'id' in data && 'label' in data : false;
+export type Action<TProperties extends Record<string, any> = Record<string, any>> = Readonly<
+  Omit<NodeBase<ActionData, TProperties>, 'properties'> & {
+    properties: Readonly<TProperties>;
+  } & ConnectedNodes
+>;
+
+export const isAction = (data: unknown): data is Action =>
+  isGraphNode(data) ? typeof data.data === 'function' : false;
+
+export const actionGroupSymbol = Symbol('ActionGroup');
+
+export type ActionGroup = Readonly<
+  Omit<NodeBase<typeof actionGroupSymbol, Record<string, any>>, 'properties'> & {
+    properties: Readonly<Record<string, any>>;
+  } & ConnectedActions
+>;
+
+export const isActionGroup = (data: unknown): data is ActionGroup =>
+  isGraphNode(data) ? data.data === actionGroupSymbol : false;
+
+export type ActionLike = Action | ActionGroup;
+
+export const isActionLike = (data: unknown): data is Action | ActionGroup => isAction(data) || isActionGroup(data);