@dxos/app-graph 0.4.7-main.d28a540 → 0.4.7-main.e015b9e

package/src/graph.ts

@@ -2,30 +2,25 @@
 // Copyright 2023 DXOS.org
 //
 
-import { untracked } from '@preact/signals-core';
-import { type DeepSignal, deepSignal } from 'deepsignal/react';
+import { deepSignal } from 'deepsignal/react';
+// TODO(wittjosiah): Remove lodash dependency.
+import get from 'lodash.get';
 
 import { invariant } from '@dxos/invariant';
-import { nonNullable } from '@dxos/util';
 
-import { isActionLike, type EdgeDirection, type Node, type NodeArg, type NodeBase } from './node';
-
-export const ROOT_ID = 'root';
+import { type Label } from './action';
+import { type Node } from './node';
 
 export type TraversalOptions = {
   /**
-   * The node to start traversing from.
-   *
-   * @default root
+   * The node to start traversing from. Defaults to the root node.
    */
   node?: Node;
 
   /**
-   * The direction to traverse graph edges.
-   *
-   * @default 'outbound'
+   * The direction to traverse the graph. Defaults to 'down'.
    */
-  direction?: EdgeDirection;
+  direction?: 'up' | 'down';
 
   /**
    * A predicate to filter nodes which are passed to the `visitor` callback.
@@ -42,264 +37,76 @@ export type TraversalOptions = {
  * The Graph represents the structure of the application constructed via plugins.
  */
 export class Graph {
-  /**
-   * @internal
-   */
-  readonly _nodes = deepSignal<Record<string, NodeBase>>({
-    [ROOT_ID]: { id: ROOT_ID, properties: {}, data: null },
-  });
+  // TODO(wittjosiah): Should this support multiple paths to the same node?
+  private readonly _index = deepSignal<Record<string, string[]>>({});
 
-  /**
-   * @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({});
+  constructor(private readonly _root: Node) {}
 
-  /**
-   * 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 } = {}) {
+  toJSON() {
+    const toLabel = (label: Label) => (Array.isArray(label) ? `${label[1].ns}[${label[0]}]` : label);
     const toJSON = (node: Node): any => {
-      const nodes = node.nodes();
-      const obj: Record<string, any> = {
-        id: node.id.length > maxLength ? `${node.id.slice(0, maxLength - 3)}...` : node.id,
+      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,
       };
-      if (node.properties.label) {
-        obj.label = node.properties.label;
-      }
-      if (nodes.length) {
-        obj.nodes = nodes.map((node) => toJSON(node));
-      }
-      return obj;
     };
 
-    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}`;
+    return toJSON(this._root);
   }
 
   /**
-   * Add nodes to the graph.
+   * The root node of the graph which is the entry point for all knowledge.
    */
-  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 root(): Node {
+    return this._root;
   }
 
   /**
-   * 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.
+   * Get the path through the graph from the root to the node with the given 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];
-    });
-  }
-
-  /**
-   * Add an edge to the graph.
-   */
-  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);
-      }
-    });
+  getPath(id: string): string[] | undefined {
+    return this._index[id];
   }
 
   /**
-   * 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.
+   * @internal
    */
-  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]);
-      }
-    });
+  _setPath(id: string, path: string[]) {
+    invariant(id && path, 'Invalid path.');
+    this._index[id] = path;
   }
 
   /**
-   * Remove an edge from the graph.
+   * Find the node with the given id in 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);
-      }
+  findNode(id: string): Node | undefined {
+    const path = this.getPath(id);
+    if (!path) {
+      return undefined;
+    }
 
-      const inboundIndex = this._edges[this.getEdgeKey(target, 'inbound')]?.findIndex((id) => id === source);
-      if (inboundIndex !== -1) {
-        this._edges[this.getEdgeKey(target, 'inbound')].splice(inboundIndex, 1);
-      }
-    });
+    return path.length > 0 ? get(this._root, path) : this._root;
   }
 
   /**
-   * 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.
+   * Recursive breadth-first traversal.
    */
-  traverse({ node = this.root, direction = 'outbound', filter, visitor }: TraversalOptions, path: string[] = []): void {
-    // Break cycles.
-    if (path.includes(node.id)) {
-      return;
-    }
-
+  traverse({ node = this._root, direction = 'down', filter, visitor }: TraversalOptions, depth = 0): void {
     if (!filter || filter(node)) {
-      visitor?.(node, [...path, node.id]);
+      visitor?.(node, this.getPath(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;
+    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);
     }
-
-    let found: string[] | undefined;
-    this.traverse({
-      node: start,
-      filter: () => !found,
-      visitor: (node, path) => {
-        if (node.id === target) {
-          found = path;
-        }
-      },
-    });
-
-    return found;
   }
 }

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,21 +2,56 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type MaybePromise, type MakeOptional } from '@dxos/util';
+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;
 
 /**
  * Represents a node in the graph.
  */
-// TODO(wittjosiah): Use Effect Schema.
-export type NodeBase<TData = any, TProperties extends Record<string, any> = Record<string, any>> = {
+export type Node<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;
 
   /**
@@ -24,97 +59,50 @@ export type NodeBase<TData = any, TProperties extends Record<string, any> = Reco
    */
   // 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 = {
   /**
-   * Edges that this node is connected to in default order.
+   * Children of the node stored by their id.
    */
-  edges(params?: { direction?: EdgeDirection }): Readonly<string[]>;
+  // TODO(burdon): Rename nodes/nodeMap?
+  childrenMap: Record<string, Node>;
 
   /**
-   * Nodes that this node is connected to in default order.
+   * Actions of the node stored by their id.
    */
-  nodes<T = any, U extends Record<string, any> = Record<string, any>>(params?: {
-    direction?: EdgeDirection;
-    filter?: NodeFilter<T, U>;
-  }): Node<T>[];
+  actionsMap: Record<string, Action>;
 
   /**
-   * Get a specific connected node by id.
+   * Children of the node in default order.
    */
-  node(id: string): Node | undefined;
-};
+  get children(): Node[];
 
-export type ConnectedActions = {
   /**
-   * Actions or action groups that this node is connected to in default order.
+   * Actions of the node in default order.
    */
-  actions(): ActionLike[];
-};
+  get actions(): Action[];
 
-export type Node<TData = any, TProperties extends Record<string, any> = Record<string, any>> = Readonly<
-  Omit<NodeBase<TData, TProperties>, 'properties'> & { properties: Readonly<TProperties> } & ConnectedNodes &
-    ConnectedActions
->;
+  addProperty(key: string, value: any): void;
+  removeProperty(key: string): void;
 
-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
-//
+  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 type InvokeParams = {
-  /** Node the invoked action is connected to. */
-  node: Node;
-
-  caller?: string;
+  addAction<TActionProperties extends Record<string, any> = Record<string, any>>(
+    ...action: ActionArg<TActionProperties>[]
+  ): Action<TActionProperties>[];
+  removeAction(id: string): Action;
 };
 
-export type ActionData = (params: InvokeParams) => MaybePromise<void>;
-
-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 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 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);
+export const isGraphNode = (data: unknown): data is Node =>
+  data && typeof data === 'object' ? 'id' in data && 'label' in data : false;

package/src/stories/EchoGraph.stories.tsx

@@ -11,7 +11,7 @@ import React, { useEffect, useState } from 'react';
 import { EventSubscriptions } from '@dxos/async';
 import { faker } from '@dxos/random';
 import { Client } from '@dxos/react-client';
-import { Expando, type Space, SpaceState } from '@dxos/react-client/echo';
+import { Expando, type Space, SpaceProxy, SpaceState } from '@dxos/react-client/echo';
 import { ClientRepeater, TestBuilder } from '@dxos/react-client/testing';
 import { Button, DensityProvider, Input, Select } from '@dxos/react-ui';
 import { getSize, mx } from '@dxos/react-ui-theme';
@@ -19,8 +19,8 @@ import { withTheme } from '@dxos/storybook-utils';
 import { safeParseInt } from '@dxos/util';
 
 import { Tree } from './Tree';
-import { type Graph } from '../graph';
 import { GraphBuilder } from '../graph-builder';
+import { type Node } from '../node';
 
 export default {
   title: 'app-graph/EchoGraph',
@@ -36,7 +36,11 @@ await client.halo.createIdentity();
 await client.spaces.create();
 await client.spaces.create();
 
-const spaceBuilderExtension = (graph: Graph) => {
+const spaceNodeBuilder = (parent: Node) => {
+  if (parent.id !== 'root') {
+    return;
+  }
+
   const subscriptions = new EventSubscriptions();
   const { unsubscribe } = client.spaces.subscribe((spaces) => {
     subscriptions.clear();
@@ -44,23 +48,12 @@ const spaceBuilderExtension = (graph: Graph) => {
       subscriptions.add(
         effect(() => {
           if (space.state.get() === SpaceState.READY) {
-            console.log('add space');
-            graph.addNodes({ id: space.key.toHex(), properties: { label: space.properties.name }, data: space });
-            graph.addEdge({ source: 'root', target: space.key.toHex() });
+            parent.addNode('space', { id: space.key.toHex(), label: space.properties.name, data: space });
           } else {
-            graph.removeNode(space.key.toHex());
+            parent.removeNode(space.key.toHex());
           }
         }),
       );
-
-      const query = space.db.query();
-      subscriptions.add(
-        effect(() => {
-          query.objects.forEach((object) => {
-            graph.addEdge({ source: space.key.toHex(), target: object.id });
-          });
-        }),
-      );
     });
   });
 
@@ -70,53 +63,28 @@ const spaceBuilderExtension = (graph: Graph) => {
   };
 };
 
-// TODO(wittjosiah): Hypergraph query isn't working.
-// const objectBuilderExtension = (graph: Graph) => {
-//   const query = client.spaces.query({ type: 'test' });
-//   let previousObjects: Expando[] = [];
-//   return effect(() => {
-//     const removedObjects = previousObjects.filter((object) => !query.objects.includes(object));
-//     previousObjects = query.objects;
-
-//     removedObjects.forEach((object) => graph.removeNode(object.id));
-//     query.objects.forEach((object) => {
-//       console.log('add object');
-//       graph.addNodes({ id: object.id, properties: { label: object.name }, data: object });
-//     });
-//   });
-// };
-
-const objectBuilderExtension = (graph: Graph) => {
-  const subscriptions = new EventSubscriptions();
-  const { unsubscribe } = client.spaces.subscribe((spaces) => {
-    subscriptions.clear();
-    spaces.forEach((space) => {
-      const query = space.db.query({ type: 'test' });
-      let previousObjects: Expando[] = [];
-      subscriptions.add(
-        effect(() => {
-          const removedObjects = previousObjects.filter((object) => !query.objects.includes(object));
-          previousObjects = query.objects;
-
-          removedObjects.forEach((object) => graph.removeNode(object.id));
-          query.objects.forEach((object) => {
-            console.log('add object');
-            graph.addNodes({ id: object.id, properties: { label: object.name }, data: object });
-          });
-        }),
-      );
-    });
-  });
+const objectNodeBuilder = (parent: Node) => {
+  if (!(parent.data instanceof SpaceProxy)) {
+    return;
+  }
 
-  return () => {
-    unsubscribe();
-    subscriptions.clear();
-  };
+  const space = parent.data;
+  const query = space.db.query({ type: 'test' });
+  let previousObjects: Expando[] = [];
+  return effect(() => {
+    const removedObjects = previousObjects.filter((object) => !query.objects.includes(object));
+    previousObjects = query.objects;
+
+    removedObjects.forEach((object) => parent.removeNode(object.id));
+    query.objects.forEach((expando) =>
+      parent.addNode('object', { id: expando.id, label: expando.name, data: expando }),
+    );
+  });
 };
 
 const graph = new GraphBuilder()
-  .addExtension('space', spaceBuilderExtension)
-  .addExtension('object', objectBuilderExtension)
+  .addNodeBuilder('space', spaceNodeBuilder)
+  .addNodeBuilder('object', objectNodeBuilder)
   .build();
 
 enum Action {