@dxos/app-graph 0.6.11-staging.e6894a4 → 0.6.12-main.5cc132e

package/dist/lib/node-esm/index.mjs

@@ -0,0 +1,806 @@
+// packages/sdk/app-graph/src/graph.ts
+import { batch, effect, untracked } from "@preact/signals-core";
+import { asyncTimeout, Trigger } from "@dxos/async";
+import { create } from "@dxos/echo-schema";
+import { invariant } from "@dxos/invariant";
+import { nonNullable } from "@dxos/util";
+
+// packages/sdk/app-graph/src/node.ts
+var isGraphNode = (data) => data && typeof data === "object" && "id" in data && "properties" in data && data.properties ? typeof data.properties === "object" && "data" in data : false;
+var isAction = (data) => isGraphNode(data) ? typeof data.data === "function" : false;
+var actionGroupSymbol = Symbol("ActionGroup");
+var isActionGroup = (data) => isGraphNode(data) ? data.data === actionGroupSymbol : false;
+var isActionLike = (data) => isAction(data) || isActionGroup(data);
+
+// packages/sdk/app-graph/src/graph.ts
+var __dxlog_file = "/home/runner/work/dxos/dxos/packages/sdk/app-graph/src/graph.ts";
+var graphSymbol = Symbol("graph");
+var getGraph = (node) => {
+  const graph = node[graphSymbol];
+  invariant(graph, "Node is not associated with a graph.", {
+    F: __dxlog_file,
+    L: 20,
+    S: void 0,
+    A: [
+      "graph",
+      "'Node is not associated with a graph.'"
+    ]
+  });
+  return graph;
+};
+var ROOT_ID = "root";
+var ROOT_TYPE = "dxos.org/type/GraphRoot";
+var ACTION_TYPE = "dxos.org/type/GraphAction";
+var ACTION_GROUP_TYPE = "dxos.org/type/GraphActionGroup";
+var DEFAULT_FILTER = (node) => untracked(() => !isActionLike(node));
+var Graph = class {
+  constructor({ onInitialNode, onInitialNodes, onRemoveNode } = {}) {
+    this._waitingForNodes = {};
+    this._initialized = {};
+    /**
+    * @internal
+    */
+    this._nodes = {};
+    /**
+    * @internal
+    */
+    this._edges = {};
+    this._constructNode = (node) => {
+      return create({
+        ...node,
+        [graphSymbol]: this
+      });
+    };
+    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: []
+    });
+  }
+  /**
+  * Alias for `findNode('root')`.
+  */
+  get root() {
+    return this.findNode(ROOT_ID);
+  }
+  /**
+  * Convert the graph to a JSON object.
+  */
+  toJSON({ id = ROOT_ID, maxLength = 32 } = {}) {
+    const toJSON = (node, seen = []) => {
+      const nodes = this.nodes(node);
+      const obj = {
+        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;
+      }
+      if (nodes.length) {
+        obj.nodes = nodes.map((n) => {
+          const nextSeen = [
+            ...seen,
+            node.id
+          ];
+          return nextSeen.includes(n.id) ? void 0 : toJSON(n, nextSeen);
+        }).filter(nonNullable);
+      }
+      return obj;
+    };
+    const root = this.findNode(id);
+    invariant(root, `Node not found: ${id}`, {
+      F: __dxlog_file,
+      L: 137,
+      S: this,
+      A: [
+        "root",
+        "`Node not found: ${id}`"
+      ]
+    });
+    return toJSON(root);
+  }
+  /**
+  * 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) {
+    const existingNode = this._nodes[id];
+    if (!existingNode) {
+      void this._onInitialNode?.(id);
+    }
+    return existingNode;
+  }
+  /**
+  * 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.
+  */
+  async waitForNode(id, timeout) {
+    const trigger = this._waitingForNodes[id] ?? (this._waitingForNodes[id] = new Trigger());
+    const node = this.findNode(id);
+    if (node) {
+      delete this._waitingForNodes[id];
+      return node;
+    }
+    if (timeout === void 0) {
+      return trigger.wait();
+    } else {
+      return asyncTimeout(trigger.wait(), timeout, `Node not found: ${id}`);
+    }
+  }
+  /**
+  * Nodes that this node is connected to in default order.
+  */
+  nodes(node, options = {}) {
+    const { relation, expansion, filter = DEFAULT_FILTER, type } = options;
+    const nodes = this._getNodes({
+      node,
+      relation,
+      expansion,
+      type
+    });
+    return nodes.filter((n) => filter(n, node));
+  }
+  /**
+  * Edges that this node is connected to in default order.
+  */
+  edges(node, { relation = "outbound" } = {}) {
+    return this._edges[node.id]?.[relation] ?? [];
+  }
+  /**
+  * Actions or action groups that this node is connected to in default order.
+  */
+  actions(node, { expansion } = {}) {
+    return [
+      ...this._getNodes({
+        node,
+        expansion,
+        type: ACTION_GROUP_TYPE
+      }),
+      ...this._getNodes({
+        node,
+        expansion,
+        type: ACTION_TYPE
+      })
+    ];
+  }
+  async expand(node, relation = "outbound", type) {
+    const key = this._key(node, relation, type);
+    const initialized = this._initialized[key];
+    if (!initialized && this._onInitialNodes) {
+      await this._onInitialNodes(node, relation, type);
+      this._initialized[key] = true;
+    }
+  }
+  _key(node, relation, type) {
+    return `${node.id}-${relation}-${type}`;
+  }
+  /**
+  * 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", expansion }, path = []) {
+    if (path.includes(node.id)) {
+      return;
+    }
+    const shouldContinue = visitor(node, [
+      ...path,
+      node.id
+    ]);
+    if (shouldContinue === false) {
+      return;
+    }
+    Object.values(this._getNodes({
+      node,
+      relation,
+      expansion
+    })).forEach((child) => this.traverse({
+      node: child,
+      relation,
+      visitor,
+      expansion
+    }, [
+      ...path,
+      node.id
+    ]));
+  }
+  /**
+  * 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", expansion }, currentPath = []) {
+    return effect(() => {
+      const path = [
+        ...currentPath,
+        node.id
+      ];
+      const result = visitor(node, path);
+      if (result === false) {
+        return;
+      }
+      const nodes = this._getNodes({
+        node,
+        relation,
+        expansion
+      });
+      const nodeSubscriptions = nodes.map((n) => this.subscribeTraverse({
+        node: n,
+        visitor,
+        expansion
+      }, path));
+      return () => {
+        nodeSubscriptions.forEach((unsubscribe) => unsubscribe());
+      };
+    });
+  }
+  /**
+  * Get the path between two nodes in the graph.
+  */
+  getPath({ source = "root", target }) {
+    const start = this.findNode(source);
+    if (!start) {
+      return void 0;
+    }
+    let found;
+    this.traverse({
+      node: start,
+      visitor: (node, path) => {
+        if (found) {
+          return false;
+        }
+        if (node.id === target) {
+          found = path;
+        }
+      }
+    });
+    return found;
+  }
+  /**
+  * Add nodes to the graph.
+  *
+  * @internal
+  */
+  _addNodes(nodes) {
+    return batch(() => nodes.map((node) => this._addNode(node)));
+  }
+  _addNode({ nodes, edges, ..._node }) {
+    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];
+      }
+      if (nodes) {
+        nodes.forEach((subNode) => {
+          this._addNode(subNode);
+          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
+        }));
+      }
+      return node;
+    });
+  }
+  /**
+  * Remove nodes from the graph.
+  *
+  * @param ids 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, edges = false) {
+    batch(() => ids.forEach((id) => this._removeNode(id, edges)));
+  }
+  _removeNode(id, edges = false) {
+    untracked(() => {
+      const node = this.findNode(id);
+      if (!node) {
+        return;
+      }
+      if (edges) {
+        this._getNodes({
+          node
+        }).forEach((node2) => {
+          this._removeEdge({
+            source: id,
+            target: node2.id
+          });
+        });
+        this._getNodes({
+          node,
+          relation: "inbound"
+        }).forEach((node2) => {
+          this._removeEdge({
+            source: node2.id,
+            target: id
+          });
+        });
+        delete this._edges[id];
+      }
+      delete this._nodes[id];
+      Object.keys(this._initialized).filter((key) => key.startsWith(id)).forEach((key) => {
+        delete this._initialized[key];
+      });
+      void this._onRemoveNode?.(id);
+    });
+  }
+  /**
+  * Add edges to the graph.
+  *
+  * @internal
+  */
+  _addEdges(edges) {
+    batch(() => edges.forEach((edge) => this._addEdge(edge)));
+  }
+  _addEdge({ source, target }) {
+    untracked(() => {
+      if (!this._edges[source]) {
+        this._edges[source] = create({
+          inbound: [],
+          outbound: []
+        });
+      }
+      if (!this._edges[target]) {
+        this._edges[target] = create({
+          inbound: [],
+          outbound: []
+        });
+      }
+      const sourceEdges = this._edges[source];
+      if (!sourceEdges.outbound.includes(target)) {
+        sourceEdges.outbound.push(target);
+      }
+      const targetEdges = this._edges[target];
+      if (!targetEdges.inbound.includes(source)) {
+        targetEdges.inbound.push(source);
+      }
+    });
+  }
+  /**
+  * Remove edges from the graph.
+  * @internal
+  */
+  _removeEdges(edges, removeOrphans = false) {
+    batch(() => edges.forEach((edge) => this._removeEdge(edge, removeOrphans)));
+  }
+  _removeEdge({ source, target }, removeOrphans = false) {
+    untracked(() => {
+      batch(() => {
+        const outboundIndex = this._edges[source]?.outbound.findIndex((id) => id === target);
+        if (outboundIndex !== void 0 && outboundIndex !== -1) {
+          this._edges[source].outbound.splice(outboundIndex, 1);
+        }
+        const inboundIndex = this._edges[target]?.inbound.findIndex((id) => id === source);
+        if (inboundIndex !== void 0 && inboundIndex !== -1) {
+          this._edges[target].inbound.splice(inboundIndex, 1);
+        }
+        if (removeOrphans) {
+          if (this._edges[source]?.outbound.length === 0 && this._edges[source]?.inbound.length === 0 && source !== ROOT_ID) {
+            this._removeNode(source, true);
+          }
+          if (this._edges[target]?.outbound.length === 0 && this._edges[target]?.inbound.length === 0 && target !== ROOT_ID) {
+            this._removeNode(target, true);
+          }
+        }
+      });
+    });
+  }
+  /**
+  * 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 relation The relation of the edges from the node to sort.
+  * @param edges The ordered list of edges.
+  * @ignore
+  */
+  _sortEdges(nodeId, relation, edges) {
+    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
+          ]);
+        }
+      });
+    });
+  }
+  _getNodes({ node, relation = "outbound", type, expansion }) {
+    if (expansion) {
+      void this.expand(node, relation, type);
+    }
+    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);
+    }
+  }
+};
+
+// packages/sdk/app-graph/src/graph-builder.ts
+import { effect as effect2, signal } from "@preact/signals-core";
+import { create as create2 } from "@dxos/echo-schema";
+import { invariant as invariant2 } from "@dxos/invariant";
+import { log } from "@dxos/log";
+import { isNode, nonNullable as nonNullable2 } from "@dxos/util";
+var __dxlog_file2 = "/home/runner/work/dxos/dxos/packages/sdk/app-graph/src/graph-builder.ts";
+var createExtension = (extension) => {
+  const { id, resolver, connector, actions, actionGroups, ...rest } = extension;
+  const getId = (key) => `${id}/${key}`;
+  return [
+    resolver ? {
+      id: getId("resolver"),
+      resolver
+    } : void 0,
+    connector ? {
+      ...rest,
+      id: getId("connector"),
+      connector
+    } : void 0,
+    actionGroups ? {
+      ...rest,
+      id: getId("actionGroups"),
+      type: ACTION_GROUP_TYPE,
+      relation: "outbound",
+      connector: ({ node }) => actionGroups({
+        node
+      })?.map((arg) => ({
+        ...arg,
+        data: actionGroupSymbol,
+        type: ACTION_GROUP_TYPE
+      }))
+    } : void 0,
+    actions ? {
+      ...rest,
+      id: getId("actions"),
+      type: ACTION_TYPE,
+      relation: "outbound",
+      connector: ({ node }) => actions({
+        node
+      })?.map((arg) => ({
+        ...arg,
+        type: ACTION_TYPE
+      }))
+    } : void 0
+  ].filter(nonNullable2);
+};
+var Dispatcher = class {
+  constructor() {
+    this.stateIndex = 0;
+    this.state = {};
+    this.cleanup = [];
+  }
+};
+var BuilderInternal = class {
+};
+var memoize = (fn, key = "result") => {
+  const dispatcher = BuilderInternal.currentDispatcher;
+  invariant2(dispatcher?.currentExtension, "memoize must be called within an extension", {
+    F: __dxlog_file2,
+    L: 129,
+    S: void 0,
+    A: [
+      "dispatcher?.currentExtension",
+      "'memoize must be called within an extension'"
+    ]
+  });
+  const all = dispatcher.state[dispatcher.currentExtension][dispatcher.stateIndex] ?? {};
+  const current = all[key];
+  const result = current ? current.result : fn();
+  dispatcher.state[dispatcher.currentExtension][dispatcher.stateIndex] = {
+    ...all,
+    [key]: {
+      result
+    }
+  };
+  dispatcher.stateIndex++;
+  return result;
+};
+var cleanup = (fn) => {
+  memoize(() => {
+    const dispatcher = BuilderInternal.currentDispatcher;
+    invariant2(dispatcher, "cleanup must be called within an extension", {
+      F: __dxlog_file2,
+      L: 144,
+      S: void 0,
+      A: [
+        "dispatcher",
+        "'cleanup must be called within an extension'"
+      ]
+    });
+    dispatcher.cleanup.push(fn);
+  });
+};
+var toSignal = (subscribe, get, key) => {
+  const thisSignal = memoize(() => {
+    return signal(get());
+  }, key);
+  const unsubscribe = memoize(() => {
+    return subscribe(() => thisSignal.value = get());
+  }, key);
+  cleanup(() => {
+    unsubscribe();
+  });
+  return thisSignal.value;
+};
+var GraphBuilder = class {
+  constructor() {
+    this._dispatcher = new Dispatcher();
+    this._extensions = create2({});
+    this._resolverSubscriptions = /* @__PURE__ */ new Map();
+    this._connectorSubscriptions = /* @__PURE__ */ new Map();
+    this._nodeChanged = {};
+    this._graph = new Graph({
+      onInitialNode: (id) => this._onInitialNode(id),
+      onInitialNodes: (node, relation, type) => this._onInitialNodes(node, relation, type),
+      onRemoveNode: (id) => this._onRemoveNode(id)
+    });
+  }
+  get graph() {
+    return this._graph;
+  }
+  /**
+  * Register a node builder which will be called in order to construct the graph.
+  */
+  addExtension(extension) {
+    if (Array.isArray(extension)) {
+      extension.forEach((ext) => this.addExtension(ext));
+      return this;
+    }
+    this._dispatcher.state[extension.id] = [];
+    this._extensions[extension.id] = extension;
+    return this;
+  }
+  /**
+  * Remove a node builder from the graph builder.
+  */
+  removeExtension(id) {
+    delete this._extensions[id];
+    return this;
+  }
+  destroy() {
+    this._dispatcher.cleanup.forEach((fn) => fn());
+    this._resolverSubscriptions.forEach((unsubscribe) => unsubscribe());
+    this._connectorSubscriptions.forEach((unsubscribe) => unsubscribe());
+    this._resolverSubscriptions.clear();
+    this._connectorSubscriptions.clear();
+  }
+  /**
+  * A graph traversal using just the connector extensions, without subscribing to any signals or persisting any nodes.
+  */
+  async explore({ node = this._graph.root, relation = "outbound", visitor }, path = []) {
+    if (path.includes(node.id)) {
+      return;
+    }
+    if (!isNode()) {
+      const { yieldOrContinue } = await import("main-thread-scheduling");
+      await yieldOrContinue("idle");
+    }
+    const shouldContinue = await visitor(node, [
+      ...path,
+      node.id
+    ]);
+    if (shouldContinue === false) {
+      return;
+    }
+    const nodes = Object.values(this._extensions).filter((extension) => relation === (extension.relation ?? "outbound")).filter((extension) => !extension.filter || extension.filter(node)).flatMap((extension) => {
+      this._dispatcher.currentExtension = extension.id;
+      this._dispatcher.stateIndex = 0;
+      BuilderInternal.currentDispatcher = this._dispatcher;
+      const result = extension.connector?.({
+        node
+      }) ?? [];
+      BuilderInternal.currentDispatcher = void 0;
+      return result;
+    }).map((arg) => ({
+      id: arg.id,
+      type: arg.type,
+      data: arg.data ?? null,
+      properties: arg.properties ?? {}
+    }));
+    await Promise.all(nodes.map((n) => this.explore({
+      node: n,
+      relation,
+      visitor
+    }, [
+      ...path,
+      node.id
+    ])));
+  }
+  async _onInitialNode(nodeId) {
+    this._nodeChanged[nodeId] = this._nodeChanged[nodeId] ?? signal({});
+    this._resolverSubscriptions.set(nodeId, effect2(() => {
+      for (const { id, resolver } of Object.values(this._extensions)) {
+        if (!resolver) {
+          continue;
+        }
+        this._dispatcher.currentExtension = id;
+        this._dispatcher.stateIndex = 0;
+        BuilderInternal.currentDispatcher = this._dispatcher;
+        let node;
+        try {
+          node = resolver({
+            id: nodeId
+          });
+        } catch (err) {
+          log.catch(err, {
+            extension: id
+          }, {
+            F: __dxlog_file2,
+            L: 300,
+            S: this,
+            C: (f, a) => f(...a)
+          });
+          log.error(`Previous error occurred in extension: ${id}`, void 0, {
+            F: __dxlog_file2,
+            L: 301,
+            S: this,
+            C: (f, a) => f(...a)
+          });
+        } finally {
+          BuilderInternal.currentDispatcher = void 0;
+        }
+        if (node) {
+          this.graph._addNodes([
+            node
+          ]);
+          if (this._nodeChanged[node.id]) {
+            this._nodeChanged[node.id].value = {};
+          }
+          break;
+        }
+      }
+    }));
+  }
+  async _onInitialNodes(node, nodesRelation, nodesType) {
+    this._nodeChanged[node.id] = this._nodeChanged[node.id] ?? signal({});
+    let first = true;
+    let previous = [];
+    this._connectorSubscriptions.set(node.id, effect2(() => {
+      if (!first && !this._connectorSubscriptions.has(node.id)) {
+        return;
+      }
+      first = false;
+      Object.keys(this._extensions);
+      this._nodeChanged[node.id].value;
+      const nodes = [];
+      for (const { id, connector, filter, type, relation = "outbound" } of Object.values(this._extensions)) {
+        if (!connector || relation !== nodesRelation || nodesType && type !== nodesType || filter && !filter(node)) {
+          continue;
+        }
+        this._dispatcher.currentExtension = id;
+        this._dispatcher.stateIndex = 0;
+        BuilderInternal.currentDispatcher = this._dispatcher;
+        try {
+          nodes.push(...connector({
+            node
+          }) ?? []);
+        } catch (err) {
+          log.catch(err, {
+            extension: id
+          }, {
+            F: __dxlog_file2,
+            L: 355,
+            S: this,
+            C: (f, a) => f(...a)
+          });
+          log.error(`Previous error occurred in extension: ${id}`, void 0, {
+            F: __dxlog_file2,
+            L: 356,
+            S: this,
+            C: (f, a) => f(...a)
+          });
+        } finally {
+          BuilderInternal.currentDispatcher = void 0;
+        }
+      }
+      const ids = nodes.map((n) => n.id);
+      const removed = previous.filter((id) => !ids.includes(id));
+      previous = ids;
+      this.graph._removeEdges(removed.map((target) => ({
+        source: node.id,
+        target
+      })), true);
+      this.graph._addNodes(nodes);
+      this.graph._addEdges(nodes.map(({ id }) => nodesRelation === "outbound" ? {
+        source: node.id,
+        target: id
+      } : {
+        source: id,
+        target: node.id
+      }));
+      this.graph._sortEdges(node.id, nodesRelation, nodes.map(({ id }) => id));
+      nodes.forEach((n) => {
+        if (this._nodeChanged[n.id]) {
+          this._nodeChanged[n.id].value = {};
+        }
+      });
+    }));
+  }
+  async _onRemoveNode(nodeId) {
+    this._resolverSubscriptions.get(nodeId)?.();
+    this._connectorSubscriptions.get(nodeId)?.();
+    this._resolverSubscriptions.delete(nodeId);
+    this._connectorSubscriptions.delete(nodeId);
+  }
+};
+export {
+  ACTION_GROUP_TYPE,
+  ACTION_TYPE,
+  Graph,
+  GraphBuilder,
+  ROOT_ID,
+  ROOT_TYPE,
+  actionGroupSymbol,
+  cleanup,
+  createExtension,
+  getGraph,
+  isAction,
+  isActionGroup,
+  isActionLike,
+  isGraphNode,
+  memoize,
+  toSignal
+};
+//# sourceMappingURL=index.mjs.map