@dxos/graph 0.7.5-main.e9bb01b → 0.7.5-staging.2ff1350

package/src/types.ts

@@ -3,11 +3,7 @@
 //
 
 import { S } from '@dxos/echo-schema';
-
-// Prior art:
-// - https://graphology.github.io (TS, tree-shakable, multiple packages for extensions)
-// - https://github.com/dagrejs/graphlib (mature, extensive)
-// - https://github.com/avoidwork/tiny-graph
+import { type Specialize } from '@dxos/util';
 
 export const BaseGraphNode = S.Struct({
   id: S.String,
@@ -15,28 +11,51 @@ export const BaseGraphNode = S.Struct({
   data: S.optional(S.Any),
 });
 
+/** Raw base type. */
 export type BaseGraphNode = S.Schema.Type<typeof BaseGraphNode>;
-export type GraphNode<Data extends object | void = void> = BaseGraphNode & { data: Data };
+/** 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,
-  data: S.optional(S.Any),
 });
 
+/** Raw base type. */
 export type BaseGraphEdge = S.Schema.Type<typeof BaseGraphEdge>;
-export type GraphEdge<Data extends object | void = void> = BaseGraphEdge & { data: Data };
+
+/** 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>;
+}
 
 /**
- * Generic graph abstraction.
+ * 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({
-  nodes: S.mutable(S.Array(BaseGraphNode)),
+  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>;
-
-export const emptyGraph: Graph = { nodes: [], edges: [] };

package/src/util.ts

@@ -2,16 +2,68 @@
 // Copyright 2024 DXOS.org
 //
 
-// TODO(burdon): GraphBuilder.
-
-// TODO(burdon): Move to @dxos/live-object?
-export const removeElements = <T>(array: T[], predicate: (element: T, index: number) => boolean): T[] => {
-  const deleted: T[] = [];
-  for (let i = array.length - 1; i >= 0; i--) {
-    if (predicate(array[i], i)) {
-      deleted.push(...array.splice(i, 1));
+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 deleted;
+  return graph;
 };

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

@@ -1,16 +0,0 @@
-import { type ReactiveEchoObject } from '@dxos/echo-db';
-import { GraphModel } from './graph';
-import { type GraphNode } from './types';
-type Edge = {
-    source: string;
-    target: string;
-    relation: string;
-};
-export declare const createEdgeId: ({ source, target, relation }: Edge) => string;
-export declare const parseEdgeId: (id: string) => Edge;
-/**
- * Maps an ECHO object graph onto a layout graph.
- */
-export declare const createGraph: (objects: ReactiveEchoObject<any>[]) => GraphModel<GraphNode<ReactiveEchoObject<any>>>;
-export {};
-//# sourceMappingURL=buidler.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"buidler.d.ts","sourceRoot":"","sources":["../../../src/buidler.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAOxD,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AAGzC,KAAK,IAAI,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjE,eAAO,MAAM,YAAY,iCAAkC,IAAI,WAAsC,CAAC;AAEtG,eAAO,MAAM,WAAW,OAAQ,MAAM,KAAG,IAIxC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,YAAa,kBAAkB,CAAC,GAAG,CAAC,EAAE,KAAG,UAAU,CAAC,SAAS,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAiC7G,CAAC"}

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

@@ -1,30 +0,0 @@
-import { Graph, type GraphNode, type GraphEdge } from './types';
-/**
- * Typed reactive object graph.
- */
-export declare class ReadonlyGraphModel<Node extends GraphNode = any, Edge extends GraphEdge = any> {
-    protected readonly _graph: Graph;
-    constructor({ nodes, edges }?: Partial<Graph>);
-    toJSON(): any;
-    get graph(): Graph;
-    get nodes(): Node[];
-    get edges(): Edge[];
-    getNode(id: string): Node | undefined;
-    getNodes({ type }: Partial<Node>): Node[];
-    getEdge(id: string): Edge | undefined;
-    getEdges({ type, source, target }: Partial<Edge>): Edge[];
-}
-export declare class GraphModel<Node extends GraphNode = any, Edge extends GraphEdge = any> extends ReadonlyGraphModel<Node, Edge> {
-    clear(): this;
-    addGraph(graph: GraphModel<Node, Edge>): this;
-    addGraphs(graphs: GraphModel<Node, Edge>[]): this;
-    addNode(node: Node): this;
-    addNodes(nodes: Node[]): this;
-    addEdge(edge: Edge): this;
-    addEdges(edges: Edge[]): this;
-    removeNode(id: string): GraphModel<Node, Edge>;
-    removeNodes(ids: string[]): GraphModel<Node, Edge>;
-    removeEdge(id: string): GraphModel<Node, Edge>;
-    removeEdges(ids: string[]): GraphModel<Node, Edge>;
-}
-//# sourceMappingURL=graph.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../src/graph.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,EAAE,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AAKhE;;GAEG;AACH,qBAAa,kBAAkB,CAAC,IAAI,SAAS,SAAS,GAAG,GAAG,EAAE,IAAI,SAAS,SAAS,GAAG,GAAG;IACxF,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;gBAErB,EAAE,KAAU,EAAE,KAAU,EAAE,GAAE,OAAO,CAAC,KAAK,CAAM;IAI3D,MAAM;IAON,IAAI,KAAK,IAAI,KAAK,CAEjB;IAED,IAAI,KAAK,IAAI,IAAI,EAAE,CAElB;IAED,IAAI,KAAK,IAAI,IAAI,EAAE,CAElB;IAED,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAIrC,QAAQ,CAAC,EAAE,IAAI,EAAE,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE;IAIzC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAIrC,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE;CAM1D;AAED,qBAAa,UAAU,CAAC,IAAI,SAAS,SAAS,GAAG,GAAG,EAAE,IAAI,SAAS,SAAS,GAAG,GAAG,CAAE,SAAQ,kBAAkB,CAC5G,IAAI,EACJ,IAAI,CACL;IACC,KAAK,IAAI,IAAI;IAMb,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,IAAI;IAM7C,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,GAAG,IAAI;IAQjD,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAKzB,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI;IAK7B,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAKzB,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI;IAO7B,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC;IAM9C,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC;IAKlD,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC;IAK9C,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC;CAInD"}

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

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=graph.test.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"graph.test.d.ts","sourceRoot":"","sources":["../../../src/graph.test.ts"],"names":[],"mappings":""}

package/src/buidler.ts

@@ -1,62 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import { type ReactiveEchoObject } from '@dxos/echo-db';
-import { FormatEnum } from '@dxos/echo-schema';
-import { invariant } from '@dxos/invariant';
-import { getSchema } from '@dxos/live-object';
-import { log } from '@dxos/log';
-import { getSchemaProperties } from '@dxos/schema';
-
-import { GraphModel } from './graph';
-import { type GraphNode } from './types';
-
-// NOTE: The `relation` is different from the `type`.
-type Edge = { source: string; target: string; relation: string };
-
-export const createEdgeId = ({ source, target, relation }: Edge) => `${source}-${relation}-${target}`;
-
-export const parseEdgeId = (id: string): Edge => {
-  const [source, relation, target] = id.split('-');
-  invariant(source && target && relation);
-  return { source, relation, target };
-};
-
-/**
- * Maps an ECHO object graph onto a layout graph.
- */
-export const createGraph = (objects: ReactiveEchoObject<any>[]): GraphModel<GraphNode<ReactiveEchoObject<any>>> => {
-  const graph = new GraphModel<GraphNode<ReactiveEchoObject<any>>>();
-
-  // 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;
-};

package/src/graph.test.ts

@@ -1,56 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import { describe, test } from 'vitest';
-
-import { createEdgeId } from './buidler';
-import { GraphModel } from './graph';
-import { type GraphNode } from './types';
-
-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);
-  });
-
-  test('add and remove subgraphs', ({ expect }) => {
-    const graph = new GraphModel<GraphNode<TestData>>()
-      .addNode({ id: 'node-1', data: { value: 'test' } })
-      .addNode({ id: 'node-2', data: { value: 'test' } })
-      .addNode({ id: 'node-3', data: { value: 'test' } })
-      .addEdge({
-        id: createEdgeId({ source: 'node-1', target: 'node-2', relation: 'test' }),
-        source: 'node-1',
-        target: 'node-2',
-      })
-      .addEdge({
-        id: createEdgeId({ source: 'node-2', target: 'node-3', relation: 'test' }),
-        source: 'node-2',
-        target: 'node-3',
-      });
-    expect(graph.nodes).to.have.length(3);
-    expect(graph.edges).to.have.length(2);
-    const pre = graph.toJSON();
-
-    const node: GraphNode<TestData> = graph.getNode('node-2')!;
-    expect(node).to.exist;
-
-    const removed = graph.removeNode('node-2');
-    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);
-  });
-});

package/src/graph.ts

@@ -1,127 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import { create } from '@dxos/live-object';
-
-import { Graph, type GraphNode, type GraphEdge } from './types';
-import { removeElements } from './util';
-
-// TODO(burdon): Traversal/visitor.
-
-/**
- * Typed reactive object graph.
- */
-export class ReadonlyGraphModel<Node extends GraphNode = any, Edge extends GraphEdge = any> {
-  protected readonly _graph: Graph;
-
-  constructor({ nodes = [], edges = [] }: Partial<Graph> = {}) {
-    this._graph = create(Graph, { nodes, edges });
-  }
-
-  toJSON() {
-    // Sort to enable stable comparisons.
-    this._graph.nodes.sort(({ id: a }, { id: b }) => a.localeCompare(b));
-    this._graph.edges.sort(({ id: a }, { id: b }) => a.localeCompare(b));
-    return JSON.parse(JSON.stringify(this._graph));
-  }
-
-  get graph(): Graph {
-    return this._graph;
-  }
-
-  get nodes(): Node[] {
-    return this._graph.nodes as Node[];
-  }
-
-  get edges(): Edge[] {
-    return this._graph.edges as Edge[];
-  }
-
-  getNode(id: string): Node | undefined {
-    return this.nodes.find((node) => node.id === id);
-  }
-
-  getNodes({ type }: Partial<Node>): Node[] {
-    return this.nodes.filter((node) => !type || type === node.type);
-  }
-
-  getEdge(id: string): Edge | undefined {
-    return this.edges.find((edge) => edge.id === id);
-  }
-
-  getEdges({ type, source, target }: Partial<Edge>): Edge[] {
-    return this.edges.filter(
-      (edge) =>
-        (!type || type === edge.type) && (!source || source === edge.source) && (!target || target === edge.target),
-    );
-  }
-}
-
-export class GraphModel<Node extends GraphNode = any, Edge extends GraphEdge = any> extends ReadonlyGraphModel<
-  Node,
-  Edge
-> {
-  clear(): this {
-    this._graph.nodes.length = 0;
-    this._graph.edges.length = 0;
-    return this;
-  }
-
-  addGraph(graph: GraphModel<Node, Edge>): this {
-    this.addNodes(graph.nodes);
-    this.addEdges(graph.edges);
-    return this;
-  }
-
-  addGraphs(graphs: GraphModel<Node, Edge>[]): this {
-    graphs.forEach((graph) => {
-      this.addNodes(graph.nodes);
-      this.addEdges(graph.edges);
-    });
-    return this;
-  }
-
-  addNode(node: Node): this {
-    this._graph.nodes.push(node);
-    return this;
-  }
-
-  addNodes(nodes: Node[]): this {
-    nodes.forEach((node) => this.addNode(node));
-    return this;
-  }
-
-  addEdge(edge: Edge): this {
-    this._graph.edges.push(edge);
-    return this;
-  }
-
-  addEdges(edges: Edge[]): this {
-    edges.forEach((edge) => this.addEdge(edge));
-    return this;
-  }
-
-  // TODO(burdon): Return graph.
-
-  removeNode(id: string): GraphModel<Node, Edge> {
-    const nodes = removeElements(this._graph.nodes, (node) => node.id === id);
-    const edges = removeElements(this._graph.edges, (edge) => edge.source === id || edge.target === id);
-    return new GraphModel<Node, Edge>({ nodes, edges });
-  }
-
-  removeNodes(ids: string[]): GraphModel<Node, Edge> {
-    const graphs = ids.map((id) => this.removeNode(id));
-    return new GraphModel<Node, Edge>().addGraphs(graphs);
-  }
-
-  removeEdge(id: string): GraphModel<Node, Edge> {
-    const edges = removeElements(this._graph.edges, (edge) => edge.id === id);
-    return new GraphModel<Node, Edge>({ edges });
-  }
-
-  removeEdges(ids: string[]): GraphModel<Node, Edge> {
-    const graphs = ids.map((id) => this.removeEdge(id));
-    return new GraphModel<Node, Edge>().addGraphs(graphs);
-  }
-}