@dxos/app-graph 0.6.14-staging.e15392e → 0.7.0

package/dist/types/src/graph.d.ts

@@ -34,6 +34,13 @@ export type GraphTraversalOptions = {
      */
     expansion?: boolean;
 };
+export type GraphParams = {
+    nodes?: Omit<Node, 'data'>[];
+    edges?: Record<string, string[]>;
+    onInitialNode?: Graph['_onInitialNode'];
+    onInitialNodes?: Graph['_onInitialNodes'];
+    onRemoveNode?: Graph['_onRemoveNode'];
+};
 /**
  * The Graph represents the structure of the application constructed via plugins.
  */
@@ -43,11 +50,8 @@ export declare class Graph {
     private readonly _onRemoveNode?;
     private readonly _waitingForNodes;
     private readonly _initialized;
-    constructor({ onInitialNode, onInitialNodes, onRemoveNode, }?: {
-        onInitialNode?: Graph['_onInitialNode'];
-        onInitialNodes?: Graph['_onInitialNodes'];
-        onRemoveNode?: Graph['_onRemoveNode'];
-    });
+    constructor({ nodes, edges, onInitialNode, onInitialNodes, onRemoveNode }?: GraphParams);
+    static from(pickle: string, options?: Omit<GraphParams, 'nodes' | 'edges'>): Graph;
     /**
      * Alias for `findNode('root')`.
      */
@@ -64,6 +68,7 @@ export declare class Graph {
         id?: string;
         maxLength?: number;
     }): any;
+    pickle(): string;
     /**
      * Find the node with the given id in the graph.
      *
@@ -131,6 +136,16 @@ export declare class Graph {
         source?: string;
         target: string;
     }): string[] | undefined;
+    /**
+     * Wait for the path between two nodes in the graph to be established.
+     */
+    waitForPath(params: {
+        source?: string;
+        target: string;
+    }, { timeout, interval }?: {
+        timeout?: number;
+        interval?: number;
+    }): Promise<string[]>;
     private _addNode;
     private _removeNode;
     private _addEdge;

package/dist/types/src/graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../src/graph.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../src/graph.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/app-graph",
-  "version": "0.6.14-staging.e15392e",
+  "version": "0.7.0",
   "description": "Constructs knowledge graphs for the purpose of building applications on top of",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -25,13 +25,13 @@
   "dependencies": {
     "@preact/signals-core": "^1.6.0",
     "main-thread-scheduling": "^14.1.1",
-    "@dxos/async": "0.6.14-staging.e15392e",
-    "@dxos/debug": "0.6.14-staging.e15392e",
-    "@dxos/echo-schema": "0.6.14-staging.e15392e",
-    "@dxos/echo-signals": "0.6.14-staging.e15392e",
-    "@dxos/log": "0.6.14-staging.e15392e",
-    "@dxos/invariant": "0.6.14-staging.e15392e",
-    "@dxos/util": "0.6.14-staging.e15392e"
+    "@dxos/async": "0.7.0",
+    "@dxos/debug": "0.7.0",
+    "@dxos/echo-schema": "0.7.0",
+    "@dxos/echo-signals": "0.7.0",
+    "@dxos/invariant": "0.7.0",
+    "@dxos/log": "0.7.0",
+    "@dxos/util": "0.7.0"
   },
   "devDependencies": {
     "@phosphor-icons/react": "^2.1.5",
@@ -40,18 +40,18 @@
     "react": "~18.2.0",
     "react-dom": "~18.2.0",
     "vite": "5.4.7",
-    "@dxos/react-client": "0.6.14-staging.e15392e",
-    "@dxos/random": "0.6.14-staging.e15392e",
-    "@dxos/react-ui-theme": "0.6.14-staging.e15392e",
-    "@dxos/storybook-utils": "0.6.14-staging.e15392e",
-    "@dxos/react-ui": "0.6.14-staging.e15392e"
+    "@dxos/random": "0.7.0",
+    "@dxos/react-client": "0.7.0",
+    "@dxos/react-ui": "0.7.0",
+    "@dxos/react-ui-theme": "0.7.0",
+    "@dxos/storybook-utils": "0.7.0"
   },
   "peerDependencies": {
     "@phosphor-icons/react": "^2.1.5",
     "react": "~18.2.0",
     "react-dom": "~18.2.0",
-    "@dxos/react-ui": "0.6.14-staging.e15392e",
-    "@dxos/react-ui-theme": "0.6.14-staging.e15392e"
+    "@dxos/react-ui": "0.7.0",
+    "@dxos/react-ui-theme": "0.7.0"
   },
   "publishConfig": {
     "access": "public"

package/src/graph-builder.test.ts

@@ -5,7 +5,7 @@
 import { batch, signal } from '@preact/signals-core';
 import { describe, expect, test } from 'vitest';
 
-import { ACTION_TYPE } from './graph';
+import { ACTION_TYPE, ROOT_ID, ROOT_TYPE } from './graph';
 import { GraphBuilder, createExtension, memoize } from './graph-builder';
 import { type Node } from './node';
 
@@ -84,6 +84,44 @@ describe('GraphBuilder', () => {
       expect(count).to.equal(4);
       expect(memoizedCount).to.equal(1);
     });
+
+    test('resolving pickled graph', async () => {
+      const pickle =
+        '{"nodes":[{"id":"root","type":"dxos.org/type/GraphRoot","properties":{}},{"id":"test1","type":"test","properties":{"value":1}},{"id":"test2","type":"test","properties":{"value":2}}],"edges":{"root":["test1","test2"],"test1":["test2"],"test2":[]}}';
+      const builder = GraphBuilder.from(pickle);
+      const graph = builder.graph;
+
+      builder.addExtension(
+        createExtension({
+          id: 'resolver',
+          resolver: ({ id }) => {
+            if (id === ROOT_ID) {
+              return { id: ROOT_ID, type: ROOT_TYPE };
+            } else {
+              return { id, type: EXAMPLE_TYPE, data: id, properties: { value: parseInt(id.replace('test', '')) } };
+            }
+          },
+        }),
+      );
+
+      {
+        expect(graph.findNode('test1', false)).toBeDefined();
+        expect(graph.findNode('test1', false)?.data).to.equal(null);
+        expect(graph.findNode('test1', false)?.properties.value).to.equal(1);
+        expect(graph.findNode('test2', false)).toBeDefined();
+        expect(graph.findNode('test2', false)?.data).to.equal(null);
+        expect(graph.findNode('test2', false)?.properties.value).to.equal(2);
+      }
+
+      await builder.initialize();
+
+      {
+        expect(graph.findNode('test1', false)?.data).to.equal('test1');
+        expect(graph.findNode('test1', false)?.properties.value).to.equal(1);
+        expect(graph.findNode('test2', false)?.data).to.equal('test2');
+        expect(graph.findNode('test2', false)?.properties.value).to.equal(2);
+      }
+    });
   });
 
   describe('connector', () => {

package/src/graph-builder.ts

@@ -10,7 +10,7 @@ import { invariant } from '@dxos/invariant';
 import { log } from '@dxos/log';
 import { isNode, type MaybePromise, nonNullable } from '@dxos/util';
 
-import { ACTION_GROUP_TYPE, ACTION_TYPE, Graph } from './graph';
+import { ACTION_GROUP_TYPE, ACTION_TYPE, Graph, type GraphParams } from './graph';
 import { type Relation, type NodeArg, type Node, type ActionData, actionGroupSymbol } from './node';
 
 /**
@@ -192,14 +192,32 @@ export class GraphBuilder {
   private readonly _nodeChanged: Record<string, Signal<{}>> = {};
   private _graph: Graph;
 
-  constructor() {
+  constructor(params: Pick<GraphParams, 'nodes' | 'edges'> = {}) {
     this._graph = new Graph({
+      ...params,
       onInitialNode: (id) => this._onInitialNode(id),
       onInitialNodes: (node, relation, type) => this._onInitialNodes(node, relation, type),
       onRemoveNode: (id) => this._onRemoveNode(id),
     });
   }
 
+  static from(pickle?: string) {
+    if (!pickle) {
+      return new GraphBuilder();
+    }
+
+    const { nodes, edges } = JSON.parse(pickle);
+    return new GraphBuilder({ nodes, edges });
+  }
+
+  /**
+   * If graph is being restored from a pickle, the data will be null.
+   * Initialize the data of each node by calling resolvers.
+   */
+  async initialize() {
+    return Promise.all(Object.keys(this._graph._nodes).map((id) => this._onInitialNode(id)));
+  }
+
   get graph() {
     return this._graph;
   }

package/src/graph.test.ts

@@ -249,6 +249,13 @@ describe('Graph', () => {
     });
   });
 
+  test('pickle', () => {
+    const pickle =
+      '{"nodes":[{"id":"root","type":"dxos.org/type/GraphRoot","properties":{}},{"id":"test1","type":"test","properties":{"value":1}},{"id":"test2","type":"test","properties":{"value":2}}],"edges":{"root":["test1","test2"],"test1":["test2"],"test2":[]}}';
+    const graph = Graph.from(pickle);
+    expect(graph.pickle()).to.equal(pickle);
+  });
+
   test('waitForNode', async () => {
     const graph = new Graph();
     const promise = graph.waitForNode('test1');

package/src/graph.ts

@@ -7,9 +7,10 @@ import { batch, effect, untracked } from '@preact/signals-core';
 import { asyncTimeout, Trigger } from '@dxos/async';
 import { type ReactiveObject, create } from '@dxos/echo-schema';
 import { invariant } from '@dxos/invariant';
+import { log } from '@dxos/log';
 import { nonNullable } from '@dxos/util';
 
-import { type Relation, type Node, type NodeArg, type NodeFilter, isActionLike } from './node';
+import { type Relation, type Node, type NodeArg, type NodeFilter, isActionLike, actionGroupSymbol } from './node';
 
 const graphSymbol = Symbol('graph');
 type DeepWriteable<T> = { -readonly [K in keyof T]: DeepWriteable<T[K]> };
@@ -64,6 +65,15 @@ export type GraphTraversalOptions = {
   expansion?: boolean;
 };
 
+export type GraphParams = {
+  // TODO(wittjosiah): Make data optional instead of omitting.
+  nodes?: Omit<Node, 'data'>[];
+  edges?: Record<string, string[]>;
+  onInitialNode?: Graph['_onInitialNode'];
+  onInitialNodes?: Graph['_onInitialNodes'];
+  onRemoveNode?: Graph['_onRemoveNode'];
+};
+
 /**
  * The Graph represents the structure of the application constructed via plugins.
  */
@@ -85,20 +95,38 @@ export class Graph {
    */
   readonly _edges: Record<string, ReactiveObject<{ inbound: string[]; outbound: string[] }>> = {};
 
-  constructor({
-    onInitialNode,
-    onInitialNodes,
-    onRemoveNode,
-  }: {
-    onInitialNode?: Graph['_onInitialNode'];
-    onInitialNodes?: Graph['_onInitialNodes'];
-    onRemoveNode?: Graph['_onRemoveNode'];
-  } = {}) {
+  constructor({ nodes, edges, onInitialNode, onInitialNodes, onRemoveNode }: GraphParams = {}) {
+    this._nodes[ROOT_ID] = this._constructNode({ id: ROOT_ID, type: ROOT_TYPE, properties: {}, data: null });
+    if (nodes) {
+      nodes.forEach((node) => {
+        if (node.type === ACTION_TYPE) {
+          this._addNode({ ...node, data: () => log.warn('Pickled action invocation') });
+        } else if (node.type === ACTION_GROUP_TYPE) {
+          this._addNode({ ...node, data: actionGroupSymbol });
+        } else {
+          this._addNode(node);
+        }
+      });
+    }
+
+    this._edges[ROOT_ID] = create({ inbound: [], outbound: [] });
+    if (edges) {
+      Object.entries(edges).forEach(([source, edges]) => {
+        edges.forEach((target) => {
+          this._addEdge({ source, target });
+        });
+        this._sortEdges(source, 'outbound', edges);
+      });
+    }
+
     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: [] });
+  }
+
+  static from(pickle: string, options: Omit<GraphParams, 'nodes' | 'edges'> = {}) {
+    const { nodes, edges } = JSON.parse(pickle);
+    return new Graph({ nodes, edges, ...options });
   }
 
   /**
@@ -138,6 +166,24 @@ export class Graph {
     return toJSON(root);
   }
 
+  pickle() {
+    const nodes = Object.values(this._nodes).map((node) => {
+      return {
+        id: node.id,
+        type: node.type,
+        properties: node.properties,
+      };
+    });
+
+    const edges = Object.fromEntries(
+      Object.entries(this._edges)
+        .map(([id, { outbound }]): [string, string[]] => [id, outbound])
+        .toSorted(([a], [b]) => a.localeCompare(b)),
+    );
+
+    return JSON.stringify({ nodes, edges });
+  }
+
   /**
    * Find the node with the given id in the graph.
    *
@@ -294,6 +340,29 @@ export class Graph {
     return found;
   }
 
+  /**
+   * Wait for the path between two nodes in the graph to be established.
+   */
+  async waitForPath(
+    params: { source?: string; target: string },
+    { timeout = 5_000, interval = 500 }: { timeout?: number; interval?: number } = {},
+  ) {
+    const path = this.getPath(params);
+    if (path) {
+      return path;
+    }
+
+    const trigger = new Trigger<string[]>();
+    const i = setInterval(() => {
+      const path = this.getPath(params);
+      if (path) {
+        trigger.wake(path);
+      }
+    }, interval);
+
+    return trigger.wait({ timeout }).finally(() => clearInterval(i));
+  }
+
   /**
    * Add nodes to the graph.
    *