@dxos/app-graph 0.3.3-main.052ad73

package/src/graph.test.ts

@@ -0,0 +1,220 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { expect } from 'chai';
+
+import { describe, test } from '@dxos/test';
+
+import { GraphBuilder } from './graph-builder';
+import { createTestNodeBuilder } from './testing';
+
+describe('Graph', () => {
+  test('returns root node', () => {
+    const graph = new GraphBuilder().build();
+    expect(graph.root).to.not.be.undefined;
+    expect(graph.root.id).to.equal('root');
+  });
+
+  test('root node unmodified without builders', () => {
+    const graph = new GraphBuilder().build();
+    expect(graph.root.properties).to.be.empty;
+    expect(graph.root.children).to.be.empty;
+    expect(graph.root.actions).to.be.empty;
+  });
+
+  test('builder can add children to root node', () => {
+    const builder = new GraphBuilder();
+    const testNode = { id: 'test', label: 'Test', data: null };
+    const id = 'test';
+    builder.addNodeBuilder(id, (parent) => {
+      if (parent.id === 'root') {
+        parent.addNode(id, testNode);
+      }
+    });
+
+    const graph = builder.build();
+    expect(graph.root.childrenMap.test.id).to.equal(testNode.id);
+    expect(graph.root.childrenMap.test.parent!.id).to.equal(graph.root.id);
+  });
+
+  test('builder can add actions to root node', () => {
+    const builder = new GraphBuilder();
+    const testAction = { id: 'test', label: 'Test', invoke: () => {} };
+    builder.addNodeBuilder('test', (parent) => {
+      if (parent.id === 'root') {
+        parent.addAction(testAction);
+      }
+    });
+
+    const graph = builder.build();
+    expect(graph.root.actionsMap.test.id).to.equal(testAction.id);
+  });
+
+  test('multiple builders can add children to root node', () => {
+    const builder = new GraphBuilder();
+    builder.addNodeBuilder('test1', createTestNodeBuilder('test1').nodeBuilder);
+    builder.addNodeBuilder('test2', createTestNodeBuilder('test2').nodeBuilder);
+
+    const graph = builder.build();
+    expect(Object.keys(graph.root.childrenMap)).to.deep.equal(['root-test1', 'root-test2']);
+    for (const node of graph.root.children) {
+      expect(graph.root.id).to.equal(node.parent!.id);
+    }
+  });
+
+  test('multiple builders can add actions to root node', () => {
+    const builder = new GraphBuilder();
+    builder.addNodeBuilder('test1', createTestNodeBuilder('test1').nodeBuilder);
+    builder.addNodeBuilder('test2', createTestNodeBuilder('test2').nodeBuilder);
+
+    const graph = builder.build();
+    expect(Object.keys(graph.root.actionsMap)).to.deep.equal(['root-test1', 'root-test2']);
+  });
+
+  test('builders can add children to child node', () => {
+    const builder = new GraphBuilder();
+    builder.addNodeBuilder('test1', createTestNodeBuilder('test1', 2).nodeBuilder);
+    builder.addNodeBuilder('test2', createTestNodeBuilder('test2').nodeBuilder);
+
+    const graph = builder.build();
+    expect(Object.keys(graph.root.childrenMap['root-test1'].children)).to.be.empty;
+    expect(Object.keys(graph.root.childrenMap['root-test2'].childrenMap)).to.deep.equal(['root-test2-test1']);
+    for (const node of graph.root.childrenMap['root-test2'].children) {
+      expect(graph.root.childrenMap['root-test2'].id).to.equal(node.parent!.id);
+    }
+  });
+
+  test('builders can add actions to child node', () => {
+    const builder = new GraphBuilder();
+    builder.addNodeBuilder('test1', createTestNodeBuilder('test1', 2).nodeBuilder);
+    builder.addNodeBuilder('test2', createTestNodeBuilder('test2').nodeBuilder);
+
+    const graph = builder.build();
+    expect(Object.keys(graph.root.childrenMap['root-test1'].actionsMap)).to.be.empty;
+    expect(Object.keys(graph.root.childrenMap['root-test2'].actionsMap)).to.deep.equal(['root-test2-test1']);
+  });
+
+  test('builders can add actions to action sets', () => {
+    const builder = new GraphBuilder();
+    builder.addNodeBuilder('test', (parent) => {
+      const [set] = parent.addAction({ id: 'test-set', label: 'Test Set', invoke: () => {} });
+      set.addAction({ id: 'test-action', label: 'Test', invoke: () => {} });
+    });
+
+    const graph = builder.build();
+    expect(Object.keys(graph.root.actionsMap['test-set'].actionsMap)).to.deep.equal(['test-action']);
+  });
+
+  test('is updated when nodes change', async () => {
+    const builder = new GraphBuilder();
+
+    // TODO(burdon): Return TestNodeBuilder object.
+    const { nodeBuilder, addNode, removeNode, addAction, removeAction, addProperty, removeProperty } =
+      createTestNodeBuilder('test1', 2);
+    builder.addNodeBuilder('test1', nodeBuilder);
+
+    const graph = builder.build();
+    expect(graph.root.children).to.have.length(1);
+    addNode('root', { id: 'root-test2', label: 'root-test2' });
+    expect(graph.root.children).to.have.length(2);
+    expect(graph.root.childrenMap['root-test2'].children).to.have.length(0);
+
+    expect(graph.root.childrenMap['root-test1'].children).to.have.length(0);
+    addNode('root-test1', { id: 'root-test1-test2', label: 'root-test1-test2' });
+    expect(graph.root.childrenMap['root-test1'].children).to.have.length(1);
+    expect(graph.root.childrenMap['root-test1'].childrenMap['root-test1-test2'].children).to.have.length(0);
+
+    expect(graph.root.actions).to.have.length(1);
+    addAction('root', { id: 'root-test2', label: 'root-test2', invoke: () => {} });
+    expect(graph.root.actions).to.have.length(2);
+
+    expect(graph.root.childrenMap['root-test1'].properties).to.not.have.property('test');
+    addProperty('root-test1', 'test', 'test');
+    expect(graph.root.childrenMap['root-test1'].properties.test).to.equal('test');
+
+    expect(graph.root.children).to.have.length(2);
+    removeNode('root', 'root-test2');
+    expect(graph.root.children).to.have.length(1);
+
+    expect(graph.root.childrenMap['root-test1'].children).to.have.length(1);
+    removeNode('root-test1', 'root-test1-test2');
+    expect(graph.root.childrenMap['root-test1'].children).to.have.length(0);
+
+    expect(graph.root.actions).to.have.length(2);
+    removeAction('root', 'root-test2');
+    expect(graph.root.actions).to.have.length(1);
+
+    expect(graph.root.childrenMap['root-test1'].properties.test).to.equal('test');
+    removeProperty('root-test1', 'test');
+    expect(graph.root.childrenMap['root-test1'].properties).to.not.have.property('test');
+  });
+
+  test.skip('node builder unsubscribe is called when builder is re-run', async () => {
+    // TODO(wittjosiah): Implement.
+  });
+
+  test('can find nodes', () => {
+    const builder = new GraphBuilder();
+    builder.addNodeBuilder('test1', createTestNodeBuilder('test1', 2).nodeBuilder);
+    builder.addNodeBuilder('test2', createTestNodeBuilder('test2').nodeBuilder);
+
+    const graph = builder.build();
+    expect(graph.findNode('root-test1')?.id).to.equal('root-test1');
+    expect(graph.findNode('root-test2-test1')?.id).to.equal('root-test2-test1');
+  });
+
+  test('can be traversed', () => {
+    const builder = new GraphBuilder();
+    builder.addNodeBuilder('test1', createTestNodeBuilder('test1', 2).nodeBuilder);
+    builder.addNodeBuilder('test2', createTestNodeBuilder('test2').nodeBuilder);
+
+    const graph = builder.build();
+    const nodes: string[] = [];
+    graph.traverse({ visitor: (node) => nodes.push(node.id) });
+    expect(nodes).to.deep.equal(['root', 'root-test1', 'root-test2', 'root-test2-test1']);
+  });
+
+  test('traversal can be limited by predicate', () => {
+    const builder = new GraphBuilder();
+    builder.addNodeBuilder('test1', createTestNodeBuilder('test1', 2).nodeBuilder);
+    builder.addNodeBuilder('test2', createTestNodeBuilder('test2').nodeBuilder);
+
+    const graph = builder.build();
+    const nodes: string[] = [];
+    graph.traverse({
+      filter: (node) => node.id.includes('test1'),
+      visitor: (node) => nodes.push(node.id),
+    });
+    expect(nodes).to.deep.equal(['root-test1', 'root-test2-test1']);
+  });
+
+  test('traversal can be started from any node', () => {
+    const builder = new GraphBuilder();
+    builder.addNodeBuilder('test1', createTestNodeBuilder('test1', 2).nodeBuilder);
+    builder.addNodeBuilder('test2', createTestNodeBuilder('test2').nodeBuilder);
+
+    const graph = builder.build();
+    const nodes: string[] = [];
+    graph.traverse({
+      node: graph.root.childrenMap['root-test2'],
+      visitor: (node) => nodes.push(node.id),
+    });
+    expect(nodes).to.deep.equal(['root-test2', 'root-test2-test1']);
+  });
+
+  test('can traverse up', () => {
+    const builder = new GraphBuilder();
+    builder.addNodeBuilder('test1', createTestNodeBuilder('test1', 2).nodeBuilder);
+    builder.addNodeBuilder('test2', createTestNodeBuilder('test2').nodeBuilder);
+
+    const graph = builder.build();
+    const nodes: string[] = [];
+    graph.traverse({
+      direction: 'up',
+      node: graph.root.childrenMap['root-test2'].childrenMap['root-test2-test1'],
+      visitor: (node) => nodes.push(node.id),
+    });
+    expect(nodes).to.deep.equal(['root-test2-test1', 'root-test2', 'root']);
+  });
+});

package/src/graph.ts

@@ -0,0 +1,110 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { deepSignal } from 'deepsignal/react';
+// TODO(wittjosiah): Remove lodash dependency.
+import get from 'lodash.get';
+
+import { type Label } from './action';
+import { type Node } from './node';
+
+export type TraversalOptions = {
+  /**
+   * The node to start traversing from. Defaults to the root node.
+   */
+  node?: Node;
+
+  /**
+   * The direction to traverse the graph. Defaults to 'down'.
+   */
+  direction?: 'up' | 'down';
+
+  /**
+   * A predicate to filter nodes which are passed to the `visitor` callback.
+   */
+  filter?: (node: Node) => boolean;
+
+  /**
+   * A callback which is called for each node visited during traversal.
+   */
+  visitor?: (node: Node) => void;
+};
+
+/**
+ * The Graph represents...
+ */
+export class Graph {
+  // TODO(burdon): Document.
+  // TODO(wittjosiah): Should this support multiple paths to the same node?
+  private readonly _index = deepSignal<{ [key: string]: string[] }>({});
+
+  constructor(private readonly _root: Node) {}
+
+  toJSON() {
+    const toLabel = (label: Label) => (Array.isArray(label) ? `${label[1].ns}[${label[0]}]` : label);
+    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,
+      };
+    };
+
+    return toJSON(this._root);
+  }
+
+  /**
+   * The root node of the graph which is the entry point for all knowledge.
+   */
+  get root(): Node {
+    return this._root;
+  }
+
+  /**
+   * Get the path through the graph from the root to the node with the given id.
+   */
+  getPath(id: string): string[] | undefined {
+    return this._index[id];
+  }
+
+  /**
+   * @internal
+   */
+  _setPath(id: string, path: string[]) {
+    this._index[id] = path;
+  }
+
+  /**
+   * Find the node with the given id in the graph.
+   */
+  findNode(id: string): Node | undefined {
+    const path = this.getPath(id);
+    if (!path) {
+      return undefined;
+    }
+
+    return path.length > 0 ? get(this._root, path) : this._root;
+  }
+
+  /**
+   * Recursive breadth-first traversal.
+   */
+  traverse({ node = this._root, direction = 'down', filter, visitor }: TraversalOptions, depth = 0): void {
+    if (!filter || filter(node)) {
+      visitor?.(node);
+    }
+
+    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);
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './action';
+export * from './graph';
+export * from './graph-builder';
+export * from './node';

package/src/node.ts

@@ -0,0 +1,101 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import type { IconProps } from '@phosphor-icons/react';
+import { type FC } from 'react';
+
+import type { UnsubscribeCallback } from '@dxos/async';
+
+import { 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.
+ */
+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.
+   *
+   * @example { index: 'a1' }
+   */
+  // TODO(burdon): Make this extensible and move label, description, and icon into here?
+  properties: TProperties;
+
+  /**
+   * Data the node represents.
+   */
+  // 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;
+
+  /**
+   * Children of the node stored by their id.
+   */
+  // TODO(burdon): Rename nodes/nodeMap?
+  childrenMap: Record<string, Node>;
+
+  /**
+   * Actions of the node stored by their id.
+   */
+  actionsMap: Record<string, Action>;
+
+  /**
+   * Children of the node in default order.
+   */
+  get children(): Node[];
+
+  /**
+   * Actions of the node in default order.
+   */
+  get actions(): Action[];
+
+  addProperty(key: string, value: any): void;
+  removeProperty(key: string): void;
+
+  addNode<TChildData = null, TChildProperties extends Record<string, any> = Record<string, any>>(
+    id: string,
+    ...node: (Pick<Node, 'id' | 'label'> & Partial<Node<TChildData, TChildProperties>>)[]
+  ): Node<TChildData, TChildProperties>[];
+  removeNode(id: string): Node;
+
+  addAction<TActionProperties extends Record<string, any> = Record<string, any>>(
+    ...action: (Pick<Action, 'id' | 'label' | 'invoke'> & Partial<Action<TActionProperties>>)[]
+  ): Action<TActionProperties>[];
+  removeAction(id: string): Action;
+};

package/src/stories/EchoGraph.stories.tsx

@@ -0,0 +1,233 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import '@dxosTheme';
+import { faker } from '@faker-js/faker';
+import { Pause, Play, Plus, Timer } from '@phosphor-icons/react';
+import { effect } from '@preact/signals-react';
+import React, { useEffect, useState } from 'react';
+
+import { EventSubscriptions } from '@dxos/async';
+import { Client } from '@dxos/react-client';
+import { Expando, type Space, SpaceProxy, SpaceState } from '@dxos/react-client/echo';
+import { ClientDecorator, TestBuilder } from '@dxos/react-client/testing';
+import { Button, DensityProvider, Input, Select } from '@dxos/react-ui';
+import { getSize, mx } from '@dxos/react-ui-theme';
+import { safeParseInt } from '@dxos/util';
+
+import { Tree } from './Tree';
+import { GraphBuilder } from '../graph-builder';
+import { type Node } from '../node';
+
+export default {
+  title: 'Echo Graph',
+};
+
+const DEFAULT_PERIOD = 500;
+
+const testBuilder = new TestBuilder();
+const client = new Client({ services: testBuilder.createLocal() });
+await client.initialize();
+await client.halo.createIdentity();
+await client.spaces.create();
+await client.spaces.create();
+
+const spaceNodeBuilder = (parent: Node) => {
+  if (parent.id !== 'root') {
+    return;
+  }
+
+  const subscriptions = new EventSubscriptions();
+  const { unsubscribe } = client.spaces.subscribe((spaces) => {
+    subscriptions.clear();
+    spaces.forEach((space) => {
+      subscriptions.add(
+        effect(() => {
+          if (space.state.get() === SpaceState.READY) {
+            parent.addNode('space', { id: space.key.toHex(), label: space.properties.name, data: space });
+          } else {
+            parent.removeNode(space.key.toHex());
+          }
+        }),
+      );
+    });
+  });
+
+  return () => {
+    unsubscribe();
+    subscriptions.clear();
+  };
+};
+
+const objectNodeBuilder = (parent: Node) => {
+  if (!(parent.data instanceof SpaceProxy)) {
+    return;
+  }
+
+  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()
+  .addNodeBuilder('space', spaceNodeBuilder)
+  .addNodeBuilder('object', objectNodeBuilder)
+  .build();
+
+enum Action {
+  CREATE_SPACE = 'CREATE_SPACE',
+  CLOSE_SPACE = 'CLOSE_SPACE',
+  RENAME_SPACE = 'RENAME_SPACE',
+  ADD_OBJECT = 'ADD_OBJECT',
+  REMOVE_OBJECT = 'REMOVE_OBJECT',
+  RENAME_OBJECT = 'RENAME_OBJECT',
+}
+
+const actionWeights = {
+  [Action.CREATE_SPACE]: 2,
+  [Action.CLOSE_SPACE]: 1,
+  [Action.RENAME_SPACE]: 2,
+  [Action.ADD_OBJECT]: 4,
+  [Action.REMOVE_OBJECT]: 3,
+  [Action.RENAME_OBJECT]: 4,
+};
+
+const randomAction = () => {
+  const actionDistribution = Object.entries(actionWeights)
+    .map(([action, weight]): Action[] => Array(weight).fill(action))
+    .flat();
+
+  return actionDistribution[Math.floor(Math.random() * actionDistribution.length)];
+};
+
+const getSpace = (): Space | undefined => {
+  const spaces = client.spaces.get().filter((space) => space.state.get() === SpaceState.READY);
+  return spaces[Math.floor(Math.random() * spaces.length)];
+};
+
+const getSpaceWithObjects = (): Space | undefined => {
+  const spaces = client.spaces
+    .get()
+    .filter((space) => space.state.get() === SpaceState.READY)
+    .filter((space) => space.db.query({ type: 'test' }).objects.length > 0);
+
+  return spaces[Math.floor(Math.random() * spaces.length)];
+};
+
+const runAction = (action: Action) => {
+  switch (action) {
+    case Action.CREATE_SPACE:
+      void client.spaces.create();
+      break;
+
+    case Action.CLOSE_SPACE:
+      void getSpace()?.internal.close();
+      break;
+
+    case Action.RENAME_SPACE: {
+      const space = getSpace();
+      if (space) {
+        space.properties.name = faker.animal.lion();
+      }
+      break;
+    }
+
+    case Action.ADD_OBJECT:
+      getSpace()?.db.add(new Expando({ type: 'test', name: faker.animal.cat() }));
+      break;
+
+    case Action.REMOVE_OBJECT: {
+      const space = getSpaceWithObjects();
+      if (space) {
+        const objects = space.db.query({ type: 'test' }).objects;
+        space.db.remove(objects[Math.floor(Math.random() * objects.length)]);
+      }
+      break;
+    }
+
+    case Action.RENAME_OBJECT: {
+      const space = getSpaceWithObjects();
+      if (space) {
+        const objects = space.db.query({ type: 'test' }).objects;
+        objects[Math.floor(Math.random() * objects.length)].name = faker.animal.cat();
+      }
+      break;
+    }
+  }
+};
+
+const EchoGraphStory = () => {
+  const [generating, setGenerating] = useState(false);
+  const [actionInterval, setActionInterval] = useState(String(DEFAULT_PERIOD));
+  const [action, setAction] = useState<Action>();
+
+  useEffect(() => {
+    if (!generating) {
+      return;
+    }
+
+    const interval = setInterval(() => runAction(randomAction()), safeParseInt(actionInterval) ?? DEFAULT_PERIOD);
+    return () => clearInterval(interval);
+  }, [generating, actionInterval]);
+
+  return (
+    <>
+      <div className='flex shrink-0 p-2 space-x-2'>
+        <DensityProvider density='fine'>
+          <Button onClick={() => setGenerating((generating) => !generating)}>
+            {generating ? <Pause /> : <Play />}
+          </Button>
+          <div className='relative' title='mutation period'>
+            <Input.Root>
+              <Input.TextInput
+                autoComplete='off'
+                size={5}
+                classNames='w-[100px] text-right pie-[22px]'
+                placeholder='Interval'
+                value={actionInterval}
+                onChange={({ target: { value } }) => setActionInterval(value)}
+              />
+            </Input.Root>
+            <Timer className={mx('absolute inline-end-1 block-start-1 mt-[6px]', getSize(3))} />
+          </div>
+          <Button onClick={() => action && runAction(action)}>
+            <Plus />
+          </Button>
+          <Select.Root value={action?.toString()} onValueChange={(action) => setAction(action as unknown as Action)}>
+            <Select.TriggerButton placeholder='Select value' />
+            <Select.Portal>
+              <Select.Content>
+                <Select.ScrollUpButton />
+                <Select.Viewport>
+                  {Object.keys(actionWeights).map((action) => (
+                    <Select.Option key={action} value={action}>
+                      {action}
+                    </Select.Option>
+                  ))}
+                </Select.Viewport>
+                <Select.ScrollDownButton />
+                <Select.Arrow />
+              </Select.Content>
+            </Select.Portal>
+          </Select.Root>
+        </DensityProvider>
+      </div>
+      <Tree data={graph.toJSON()} />
+    </>
+  );
+};
+
+export const EchoGraph = {
+  render: () => <EchoGraphStory />,
+  decorators: [ClientDecorator({ clients: [client], className: 'flex flex-col' })],
+};