@dxos/graph 0.7.5-feature-compute.4d9d99a

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@dxos/graph",
+  "version": "0.7.5-feature-compute.4d9d99a",
+  "description": "Low-level graph API",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "license": "MIT",
+  "author": "DXOS.org",
+  "sideEffects": true,
+  "exports": {
+    ".": {
+      "types": "./dist/types/src/index.d.ts",
+      "browser": "./dist/lib/browser/index.mjs",
+      "node": "./dist/lib/node-esm/index.mjs"
+    }
+  },
+  "types": "dist/types/src/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "meta": [
+        "dist/types/src/meta.d.ts"
+      ],
+      "types": [
+        "dist/types/src/types/index.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@effect/schema": "^0.75.5",
+    "@preact/signals-core": "^1.6.0",
+    "lodash.defaultsdeep": "^4.6.1",
+    "@dxos/async": "0.7.5-feature-compute.4d9d99a",
+    "@dxos/echo-schema": "0.7.5-feature-compute.4d9d99a",
+    "@dxos/debug": "0.7.5-feature-compute.4d9d99a",
+    "@dxos/live-object": "0.7.5-feature-compute.4d9d99a",
+    "@dxos/echo-db": "0.7.5-feature-compute.4d9d99a",
+    "@dxos/node-std": "0.7.5-feature-compute.4d9d99a",
+    "@dxos/log": "0.7.5-feature-compute.4d9d99a",
+    "@dxos/schema": "0.7.5-feature-compute.4d9d99a",
+    "@dxos/invariant": "0.7.5-feature-compute.4d9d99a",
+    "@dxos/util": "0.7.5-feature-compute.4d9d99a"
+  },
+  "devDependencies": {
+    "@antv/graphlib": "^2.0.4",
+    "@antv/layout": "^1.2.13",
+    "@types/lodash.defaultsdeep": "^4.6.6",
+    "@dxos/echo-db": "0.7.5-feature-compute.4d9d99a",
+    "@dxos/random": "0.7.5-feature-compute.4d9d99a",
+    "@dxos/echo-schema": "0.7.5-feature-compute.4d9d99a"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './model';
+export * from './types';
+export * from './util';

package/src/model.test.ts

@@ -0,0 +1,120 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { S } from '@dxos/echo-schema';
+
+import { GraphModel } from './model';
+import { BaseGraphNode, type GraphNode } from './types';
+
+const TestNode = S.extend(
+  BaseGraphNode,
+  S.Struct({
+    value: S.String,
+  }),
+);
+
+type TestNode = S.Schema.Type<typeof TestNode>;
+
+type TestData = { value: string };
+
+describe('Graph', () => {
+  test('empty', ({ expect }) => {
+    const graph = new GraphModel();
+    expect(graph.nodes).to.have.length(0);
+    expect(graph.edges).to.have.length(0);
+    expect(graph.toJSON()).to.deep.eq({ nodes: [], edges: [] });
+  });
+
+  test('extended', ({ expect }) => {
+    const graph = new GraphModel<TestNode>();
+    const node = graph.addNode({ id: 'test', value: 'test' });
+    expect(node.value.length).to.eq(4);
+  });
+
+  test('optional', ({ expect }) => {
+    {
+      const graph = new GraphModel<GraphNode<string>>();
+      const node = graph.addNode({ id: 'test', data: 'test' });
+      expect(node.data.length).to.eq(4);
+    }
+
+    {
+      const graph = new GraphModel<GraphNode.Optional<string>>();
+      const node = graph.addNode({ id: 'test' });
+      expect(node.data?.length).to.be.undefined;
+    }
+  });
+
+  test('add and remove subgraphs', ({ expect }) => {
+    const graph = new GraphModel<GraphNode<TestData>>();
+    graph.builder
+      .addNode({ id: 'node1', data: { value: 'test' } })
+      .addNode({ id: 'node2', data: { value: 'test' } })
+      .addNode({ id: 'node3', data: { value: 'test' } })
+      .addEdge({ source: 'node1', target: 'node2' })
+      .addEdge({ source: 'node2', target: 'node3' });
+    expect(graph.nodes).to.have.length(3);
+    expect(graph.edges).to.have.length(2);
+    const pre = graph.toJSON();
+
+    const node = graph.findNode('node2');
+    expect(node).to.exist;
+
+    const removed = graph.removeNode('node2');
+    expect(removed.nodes).to.have.length(1);
+    expect(removed.edges).to.have.length(2);
+    expect(graph.nodes).to.have.length(2);
+    expect(graph.edges).to.have.length(0);
+
+    graph.addGraph(removed);
+    const post = graph.toJSON();
+    expect(pre).to.deep.eq(post);
+
+    graph.clear();
+    expect(graph.nodes).to.have.length(0);
+    expect(graph.edges).to.have.length(0);
+  });
+
+  test('traverse', ({ expect }) => {
+    const graph = new GraphModel();
+    graph.builder
+      .addNode({ id: 'a' })
+      .addNode({ id: 'b' })
+      .addNode({ id: 'c' })
+      .addNode({ id: 'd' })
+      .addNode({ id: 'e' })
+      .addNode({ id: 'f' })
+      .addNode({ id: 'g' })
+      .addNode({ id: 'h' })
+      // Sub-graph 1.
+      .addEdge({ source: 'a', target: 'b' })
+      .addEdge({ source: 'a', target: 'c' })
+      .addEdge({ source: 'c', target: 'd' })
+      .addEdge({ source: 'd', target: 'e' })
+      .addEdge({ source: 'd', target: 'a' })
+      // Sub-graph 2.
+      .addEdge({ source: 'f', target: 'g' })
+      .addEdge({ source: 'g', target: 'h' });
+
+    const count = graph.nodes.length;
+
+    {
+      // Sub-graph 1.
+      const nodes = graph.traverse(graph.getNode('a'));
+      expect(nodes).to.have.length(5);
+    }
+
+    {
+      // Sub-graph 2.
+      const nodes = graph.traverse(graph.getNode('f'));
+      expect(nodes).to.have.length(3);
+
+      // Remove sub-graph.
+      graph.removeNodes(nodes.map((node) => node.id));
+      expect(graph.nodes).to.have.length(count - 3);
+    }
+  });
+});

package/src/model.ts

@@ -0,0 +1,266 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { inspectCustom } from '@dxos/debug';
+import { failedInvariant, invariant } from '@dxos/invariant';
+import { getSnapshot } from '@dxos/live-object';
+import { type MakeOptional, isNotFalsy, removeBy, stripUndefined } from '@dxos/util';
+
+import { type Graph, type GraphNode, type GraphEdge, type BaseGraphNode, type BaseGraphEdge } from './types';
+import { createEdgeId } from './util';
+
+/**
+ * Wrapper class contains reactive nodes and edges.
+ */
+export class ReadonlyGraphModel<
+  Node extends BaseGraphNode = BaseGraphNode,
+  Edge extends BaseGraphEdge = BaseGraphEdge,
+> {
+  protected readonly _graph: Graph;
+
+  /**
+   * NOTE: Pass in simple Graph or ReactiveObject.
+   */
+  constructor(graph?: Graph) {
+    this._graph = graph ?? { nodes: [], edges: [] };
+  }
+
+  [inspectCustom]() {
+    return this.toJSON();
+  }
+
+  /**
+   * Return stable sorted JSON representation of graph.
+   */
+  // TODO(burdon): Create separate toJson method with computed signal.
+  toJSON() {
+    const { id, nodes, edges } = getSnapshot(this._graph);
+    nodes.sort(({ id: a }, { id: b }) => a.localeCompare(b));
+    edges.sort(({ id: a }, { id: b }) => a.localeCompare(b));
+    return stripUndefined({ id, nodes, edges });
+  }
+
+  get graph(): Graph {
+    return this._graph;
+  }
+
+  get nodes(): Node[] {
+    return this._graph.nodes as Node[];
+  }
+
+  get edges(): Edge[] {
+    return this._graph.edges as Edge[];
+  }
+
+  //
+  // Nodes
+  //
+
+  findNode(id: string): Node | undefined {
+    return this.nodes.find((node) => node.id === id);
+  }
+
+  getNode(id: string): Node {
+    return this.findNode(id) ?? failedInvariant();
+  }
+
+  filterNodes({ type }: Partial<GraphNode> = {}): Node[] {
+    return this.nodes.filter((node) => !type || type === node.type);
+  }
+
+  //
+  // Edges
+  //
+
+  findEdge(id: string): Edge | undefined {
+    return this.edges.find((edge) => edge.id === id);
+  }
+
+  getEdge(id: string): Edge {
+    return this.findEdge(id) ?? failedInvariant();
+  }
+
+  filterEdges({ type, source, target }: Partial<GraphEdge> = {}): Edge[] {
+    return this.edges.filter(
+      (edge) =>
+        (!type || type === edge.type) && (!source || source === edge.source) && (!target || target === edge.target),
+    );
+  }
+
+  //
+  // Traverse
+  //
+
+  traverse(root: Node): Node[] {
+    return this._traverse(root);
+  }
+
+  private _traverse(root: Node, visited: Set<string> = new Set()): Node[] {
+    if (visited.has(root.id)) {
+      return [];
+    }
+
+    visited.add(root.id);
+    const targets = this.filterEdges({ source: root.id })
+      .map((edge) => this.getNode(edge.target))
+      .filter(isNotFalsy);
+
+    return [root, ...targets.flatMap((target) => this._traverse(target, visited))];
+  }
+}
+
+/**
+ * Typed wrapper.
+ */
+export abstract class AbstractGraphModel<
+  Node extends BaseGraphNode,
+  Edge extends BaseGraphEdge,
+  Model extends AbstractGraphModel<Node, Edge, Model, Builder>,
+  Builder extends AbstractGraphBuilder<Node, Edge, Model>,
+> extends ReadonlyGraphModel<Node, Edge> {
+  /**
+   * Allows chaining.
+   */
+  abstract get builder(): Builder;
+
+  /**
+   * Shallow copy of provided graph.
+   */
+  abstract copy(graph?: Partial<Graph>): Model;
+
+  clear(): this {
+    this._graph.nodes.length = 0;
+    this._graph.edges.length = 0;
+    return this;
+  }
+
+  addGraph(graph: Model): this {
+    this.addNodes(graph.nodes);
+    this.addEdges(graph.edges);
+    return this;
+  }
+
+  addGraphs(graphs: Model[]): this {
+    graphs.forEach((graph) => {
+      this.addNodes(graph.nodes);
+      this.addEdges(graph.edges);
+    });
+    return this;
+  }
+
+  addNode(node: Node): Node {
+    invariant(node.id, 'ID is required');
+    invariant(!this.findNode(node.id), `node already exists: ${node.id}`);
+    this._graph.nodes.push(node);
+    return node;
+  }
+
+  addNodes(nodes: Node[]): Node[] {
+    return nodes.map((node) => this.addNode(node));
+  }
+
+  addEdge(edge: MakeOptional<Edge, 'id'>): Edge {
+    invariant(edge.source);
+    invariant(edge.target);
+    if (!edge.id) {
+      // TODO(burdon): Generate random id.
+      edge = { id: createEdgeId(edge), ...edge };
+    }
+    invariant(!this.findNode(edge.id!));
+    this._graph.edges.push(edge as Edge);
+    return edge as Edge;
+  }
+
+  addEdges(edges: Edge[]): Edge[] {
+    return edges.map((edge) => this.addEdge(edge));
+  }
+
+  removeNode(id: string): Model {
+    const nodes = removeBy<Node>(this._graph.nodes as Node[], (node) => node.id === id);
+    const edges = removeBy<Edge>(this._graph.edges as Edge[], (edge) => edge.source === id || edge.target === id);
+    return this.copy({ nodes, edges });
+  }
+
+  removeNodes(ids: string[]): Model {
+    const graphs = ids.map((id) => this.removeNode(id));
+    return this.copy().addGraphs(graphs);
+  }
+
+  removeEdge(id: string): Model {
+    const edges = removeBy<Edge>(this._graph.edges as Edge[], (edge) => edge.id === id);
+    return this.copy({ nodes: [], edges });
+  }
+
+  removeEdges(ids: string[]): Model {
+    const graphs = ids.map((id) => this.removeEdge(id));
+    return this.copy().addGraphs(graphs);
+  }
+}
+
+/**
+ * Chainable wrapper
+ */
+export abstract class AbstractGraphBuilder<
+  Node extends BaseGraphNode,
+  Edge extends BaseGraphEdge,
+  Model extends GraphModel<Node, Edge>,
+> {
+  constructor(protected readonly _model: Model) {}
+
+  get model(): Model {
+    return this._model;
+  }
+
+  call(cb: (builder: this) => void): this {
+    cb(this);
+    return this;
+  }
+
+  getNode(id: string): Node {
+    return this.model.getNode(id);
+  }
+
+  addNode(node: Node): this {
+    this._model.addNode(node);
+    return this;
+  }
+
+  addEdge(edge: MakeOptional<Edge, 'id'>): this {
+    this._model.addEdge(edge);
+    return this;
+  }
+
+  addNodes(nodes: Node[]): this {
+    this._model.addNodes(nodes);
+    return this;
+  }
+
+  addEdges(edges: Edge[]): this {
+    this._model.addEdges(edges);
+    return this;
+  }
+}
+
+export class GraphModel<
+  Node extends BaseGraphNode = BaseGraphNode,
+  Edge extends BaseGraphEdge = BaseGraphEdge,
+> extends AbstractGraphModel<Node, Edge, GraphModel<Node, Edge>, GraphBuilder<Node, Edge>> {
+  override get builder() {
+    return new GraphBuilder<Node, Edge>(this);
+  }
+
+  override copy(graph?: Partial<Graph>) {
+    return new GraphModel<Node, Edge>({ nodes: graph?.nodes ?? [], edges: graph?.edges ?? [] });
+  }
+}
+
+export class GraphBuilder<
+  Node extends BaseGraphNode = BaseGraphNode,
+  Edge extends BaseGraphEdge = BaseGraphEdge,
+> extends AbstractGraphBuilder<Node, Edge, GraphModel<Node, Edge>> {
+  override call(cb: (builder: this) => void) {
+    cb(this);
+    return this;
+  }
+}

package/src/types.ts

@@ -0,0 +1,61 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { S } from '@dxos/echo-schema';
+import { type Specialize } from '@dxos/util';
+
+export const BaseGraphNode = S.Struct({
+  id: S.String,
+  type: S.optional(S.String),
+  data: S.optional(S.Any),
+});
+
+/** Raw base type. */
+export type BaseGraphNode = S.Schema.Type<typeof BaseGraphNode>;
+/** Typed node data. */
+export type GraphNode<Data = any, Optional extends boolean = false> = Specialize<
+  BaseGraphNode,
+  Optional extends true ? { data?: Data } : { data: Data }
+>;
+
+export declare namespace GraphNode {
+  export type Optional<T = any> = GraphNode<T, true>;
+}
+
+export const BaseGraphEdge = S.Struct({
+  id: S.String,
+  type: S.optional(S.String),
+  data: S.optional(S.Any),
+  source: S.String,
+  target: S.String,
+});
+
+/** Raw base type. */
+export type BaseGraphEdge = S.Schema.Type<typeof BaseGraphEdge>;
+
+/** Typed edge data. */
+export type GraphEdge<Data = any, Optional extends boolean = false> = Specialize<
+  BaseGraphEdge,
+  Optional extends true ? { data?: Data } : { data: Data }
+>;
+
+export declare namespace GraphEdge {
+  export type Optional<T = any> = GraphEdge<T, true>;
+}
+
+/**
+ * Allows any additional properties on graph nodes.
+ */
+const ExtendableBaseGraphNode = S.extend(BaseGraphNode, S.Struct({}, { key: S.String, value: S.Any }));
+
+/**
+ * Generic graph.
+ */
+export const Graph = S.Struct({
+  id: S.optional(S.String),
+  nodes: S.mutable(S.Array(ExtendableBaseGraphNode)),
+  edges: S.mutable(S.Array(BaseGraphEdge)),
+});
+
+export type Graph = S.Schema.Type<typeof Graph>;

package/src/util.ts

@@ -0,0 +1,69 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type ReactiveEchoObject } from '@dxos/echo-db';
+import { FormatEnum } from '@dxos/echo-schema';
+import { invariant } from '@dxos/invariant';
+import { getSchema, create } from '@dxos/live-object';
+import { log } from '@dxos/log';
+import { getSchemaProperties } from '@dxos/schema';
+
+import { GraphModel } from './model';
+import { Graph, type GraphNode } from './types';
+
+const KEY_REGEX = /\w+/;
+
+// NOTE: The `relation` is different from the `type`.
+type EdgeMeta = { source: string; target: string; relation?: string };
+
+export const createEdgeId = ({ source, target, relation }: EdgeMeta) => {
+  invariant(source.match(KEY_REGEX), `invalid source: ${source}`);
+  invariant(target.match(KEY_REGEX), `invalid target: ${target}`);
+  return [source, relation, target].join('_');
+};
+
+export const parseEdgeId = (id: string): EdgeMeta => {
+  const [source, relation, target] = id.split('_');
+  invariant(source.length && target.length);
+  return { source, relation: relation.length ? relation : undefined, target };
+};
+
+/**
+ * Creates a new reactive graph from a set of ECHO objects.
+ * References are mapped onto graph edges.
+ */
+export const createGraph = (objects: ReactiveEchoObject<any>[]): GraphModel<GraphNode<ReactiveEchoObject<any>>> => {
+  const graph = new GraphModel<GraphNode<ReactiveEchoObject<any>>>(create(Graph, { nodes: [], edges: [] }));
+
+  // Map objects.
+  objects.forEach((object) => {
+    graph.addNode({ id: object.id, type: object.typename, data: object });
+  });
+
+  // Find references.
+  objects.forEach((object) => {
+    const schema = getSchema(object);
+    if (!schema) {
+      log.info('no schema for object', { id: object.id.slice(0, 8) });
+      return;
+    }
+
+    // Parse schema to follow referenced objects.
+    for (const prop of getSchemaProperties(schema.ast, object)) {
+      if (prop.format === FormatEnum.Ref) {
+        const source = object;
+        const target = object[prop.name]?.target;
+        if (target) {
+          graph.addEdge({
+            id: createEdgeId({ source: source.id, target: target.id, relation: String(prop.name) }),
+            source: source.id,
+            target: target.id,
+          });
+        }
+      }
+    }
+  });
+
+  return graph;
+};