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

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

@@ -0,0 +1,107 @@
+import { inspectCustom } from '@dxos/debug';
+import { type MakeOptional } from '@dxos/util';
+import { type Graph, type GraphNode, type GraphEdge, type BaseGraphNode, type BaseGraphEdge } from './types';
+/**
+ * Wrapper class contains reactive nodes and edges.
+ */
+export declare class ReadonlyGraphModel<Node extends BaseGraphNode = BaseGraphNode, Edge extends BaseGraphEdge = BaseGraphEdge> {
+    protected readonly _graph: Graph;
+    /**
+     * NOTE: Pass in simple Graph or ReactiveObject.
+     */
+    constructor(graph?: Graph);
+    [inspectCustom](): {
+        id: string | undefined;
+        nodes: ({
+            readonly id: string;
+            readonly type?: string | undefined;
+            readonly data?: any;
+        } & {
+            readonly [x: string]: any;
+        })[];
+        edges: {
+            readonly id: string;
+            readonly type?: string | undefined;
+            readonly data?: any;
+            readonly source: string;
+            readonly target: string;
+        }[];
+    };
+    /**
+     * Return stable sorted JSON representation of graph.
+     */
+    toJSON(): {
+        id: string | undefined;
+        nodes: ({
+            readonly id: string;
+            readonly type?: string | undefined;
+            readonly data?: any;
+        } & {
+            readonly [x: string]: any;
+        })[];
+        edges: {
+            readonly id: string;
+            readonly type?: string | undefined;
+            readonly data?: any;
+            readonly source: string;
+            readonly target: string;
+        }[];
+    };
+    get graph(): Graph;
+    get nodes(): Node[];
+    get edges(): Edge[];
+    findNode(id: string): Node | undefined;
+    getNode(id: string): Node;
+    filterNodes({ type }?: Partial<GraphNode>): Node[];
+    findEdge(id: string): Edge | undefined;
+    getEdge(id: string): Edge;
+    filterEdges({ type, source, target }?: Partial<GraphEdge>): Edge[];
+    traverse(root: Node): Node[];
+    private _traverse;
+}
+/**
+ * Typed wrapper.
+ */
+export declare 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;
+    addGraph(graph: Model): this;
+    addGraphs(graphs: Model[]): this;
+    addNode(node: Node): Node;
+    addNodes(nodes: Node[]): Node[];
+    addEdge(edge: MakeOptional<Edge, 'id'>): Edge;
+    addEdges(edges: Edge[]): Edge[];
+    removeNode(id: string): Model;
+    removeNodes(ids: string[]): Model;
+    removeEdge(id: string): Model;
+    removeEdges(ids: string[]): Model;
+}
+/**
+ * Chainable wrapper
+ */
+export declare abstract class AbstractGraphBuilder<Node extends BaseGraphNode, Edge extends BaseGraphEdge, Model extends GraphModel<Node, Edge>> {
+    protected readonly _model: Model;
+    constructor(_model: Model);
+    get model(): Model;
+    call(cb: (builder: this) => void): this;
+    getNode(id: string): Node;
+    addNode(node: Node): this;
+    addEdge(edge: MakeOptional<Edge, 'id'>): this;
+    addNodes(nodes: Node[]): this;
+    addEdges(edges: Edge[]): this;
+}
+export declare class GraphModel<Node extends BaseGraphNode = BaseGraphNode, Edge extends BaseGraphEdge = BaseGraphEdge> extends AbstractGraphModel<Node, Edge, GraphModel<Node, Edge>, GraphBuilder<Node, Edge>> {
+    get builder(): GraphBuilder<Node, Edge>;
+    copy(graph?: Partial<Graph>): GraphModel<Node, Edge>;
+}
+export declare class GraphBuilder<Node extends BaseGraphNode = BaseGraphNode, Edge extends BaseGraphEdge = BaseGraphEdge> extends AbstractGraphBuilder<Node, Edge, GraphModel<Node, Edge>> {
+    call(cb: (builder: this) => void): this;
+}
+//# sourceMappingURL=model.d.ts.map

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

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

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

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

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

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

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

@@ -1,41 +1,59 @@
 import { S } from '@dxos/echo-schema';
+import { type Specialize } from '@dxos/util';
 export declare const BaseGraphNode: S.Struct<{
     id: typeof S.String;
     type: S.optional<typeof S.String>;
     data: S.optional<typeof S.Any>;
 }>;
+/** Raw base type. */
 export type BaseGraphNode = S.Schema.Type<typeof BaseGraphNode>;
-export type GraphNode<Data extends object | void = void> = 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 {
+    type Optional<T = any> = GraphNode<T, true>;
+}
 export declare const BaseGraphEdge: S.Struct<{
     id: typeof S.String;
     type: S.optional<typeof S.String>;
+    data: S.optional<typeof S.Any>;
     source: typeof S.String;
     target: typeof S.String;
-    data: S.optional<typeof S.Any>;
 }>;
+/** Raw base type. */
 export type BaseGraphEdge = S.Schema.Type<typeof BaseGraphEdge>;
-export type GraphEdge<Data extends object | void = void> = 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 {
+    type Optional<T = any> = GraphEdge<T, true>;
+}
 /**
- * Generic graph abstraction.
+ * Generic graph.
  */
 export declare const Graph: S.Struct<{
-    nodes: S.mutable<S.Array$<S.Struct<{
+    id: S.optional<typeof S.String>;
+    nodes: S.mutable<S.Array$<S.extend<S.Struct<{
         id: typeof S.String;
         type: S.optional<typeof S.String>;
         data: S.optional<typeof S.Any>;
-    }>>>;
+    }>, S.TypeLiteral<{}, readonly [{
+        readonly key: typeof S.String;
+        readonly value: typeof S.Any;
+    }]>>>>;
     edges: S.mutable<S.Array$<S.Struct<{
         id: typeof S.String;
         type: S.optional<typeof S.String>;
+        data: S.optional<typeof S.Any>;
         source: typeof S.String;
         target: typeof S.String;
-        data: S.optional<typeof S.Any>;
     }>>>;
 }>;
 export type Graph = S.Schema.Type<typeof Graph>;
-export declare const emptyGraph: Graph;
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAC;AAOtC,eAAO,MAAM,aAAa;;;;EAIxB,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,aAAa,CAAC,CAAC;AAChE,MAAM,MAAM,SAAS,CAAC,IAAI,SAAS,MAAM,GAAG,IAAI,GAAG,IAAI,IAAI,aAAa,GAAG;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC;AAE1F,eAAO,MAAM,aAAa;;;;;;EAMxB,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,aAAa,CAAC,CAAC;AAChE,MAAM,MAAM,SAAS,CAAC,IAAI,SAAS,MAAM,GAAG,IAAI,GAAG,IAAI,IAAI,aAAa,GAAG;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC;AAE1F;;GAEG;AACH,eAAO,MAAM,KAAK;;;;;;;;;;;;;EAGhB,CAAC;AAEH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,KAAK,CAAC,CAAC;AAEhD,eAAO,MAAM,UAAU,EAAE,KAAgC,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAC;AACtC,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,eAAO,MAAM,aAAa;;;;EAIxB,CAAC;AAEH,qBAAqB;AACrB,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,aAAa,CAAC,CAAC;AAChE,uBAAuB;AACvB,MAAM,MAAM,SAAS,CAAC,IAAI,GAAG,GAAG,EAAE,QAAQ,SAAS,OAAO,GAAG,KAAK,IAAI,UAAU,CAC9E,aAAa,EACb,QAAQ,SAAS,IAAI,GAAG;IAAE,IAAI,CAAC,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CACzD,CAAC;AAEF,MAAM,CAAC,OAAO,WAAW,SAAS,CAAC;IACjC,KAAY,QAAQ,CAAC,CAAC,GAAG,GAAG,IAAI,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;CACpD;AAED,eAAO,MAAM,aAAa;;;;;;EAMxB,CAAC;AAEH,qBAAqB;AACrB,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,aAAa,CAAC,CAAC;AAEhE,uBAAuB;AACvB,MAAM,MAAM,SAAS,CAAC,IAAI,GAAG,GAAG,EAAE,QAAQ,SAAS,OAAO,GAAG,KAAK,IAAI,UAAU,CAC9E,aAAa,EACb,QAAQ,SAAS,IAAI,GAAG;IAAE,IAAI,CAAC,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CACzD,CAAC;AAEF,MAAM,CAAC,OAAO,WAAW,SAAS,CAAC;IACjC,KAAY,QAAQ,CAAC,CAAC,GAAG,GAAG,IAAI,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;CACpD;AAOD;;GAEG;AACH,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;EAIhB,CAAC;AAEH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,KAAK,CAAC,CAAC"}

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

@@ -1,2 +1,17 @@
-export declare const removeElements: <T>(array: T[], predicate: (element: T, index: number) => boolean) => T[];
+import { type ReactiveEchoObject } from '@dxos/echo-db';
+import { GraphModel } from './model';
+import { type GraphNode } from './types';
+type EdgeMeta = {
+    source: string;
+    target: string;
+    relation?: string;
+};
+export declare const createEdgeId: ({ source, target, relation }: EdgeMeta) => string;
+export declare const parseEdgeId: (id: string) => EdgeMeta;
+/**
+ * Creates a new reactive graph from a set of ECHO objects.
+ * References are mapped onto graph edges.
+ */
+export declare const createGraph: (objects: ReactiveEchoObject<any>[]) => GraphModel<GraphNode<ReactiveEchoObject<any>>>;
+export {};
 //# sourceMappingURL=util.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../../../src/util.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,KAAG,CAAC,EASlG,CAAC"}
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../../../src/util.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAOxD,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAS,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AAKhD,KAAK,QAAQ,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtE,eAAO,MAAM,YAAY,iCAAkC,QAAQ,WAIlE,CAAC;AAEF,eAAO,MAAM,WAAW,OAAQ,MAAM,KAAG,QAIxC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,WAAW,YAAa,kBAAkB,CAAC,GAAG,CAAC,EAAE,KAAG,UAAU,CAAC,SAAS,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAiC7G,CAAC"}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@dxos/graph",
-  "version": "0.7.5-main.ff8607b",
+  "version": "0.7.5-staging.2ff1350",
   "description": "Low-level graph API",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
   "license": "MIT",
   "author": "DXOS.org",
   "sideEffects": true,
+  "type": "module",
   "exports": {
     ".": {
       "types": "./dist/types/src/index.d.ts",
@@ -32,27 +33,24 @@
   "dependencies": {
     "@effect/schema": "^0.75.5",
     "@preact/signals-core": "^1.6.0",
-    "graphology": "^0.25.4",
-    "graphology-shortest-path": "^2.1.0",
-    "graphology-types": "^0.24.8",
     "lodash.defaultsdeep": "^4.6.1",
-    "@dxos/debug": "0.7.5-main.ff8607b",
-    "@dxos/async": "0.7.5-main.ff8607b",
-    "@dxos/echo-db": "0.7.5-main.ff8607b",
-    "@dxos/echo-schema": "0.7.5-main.ff8607b",
-    "@dxos/live-object": "0.7.5-main.ff8607b",
-    "@dxos/log": "0.7.5-main.ff8607b",
-    "@dxos/invariant": "0.7.5-main.ff8607b",
-    "@dxos/schema": "0.7.5-main.ff8607b",
-    "@dxos/util": "0.7.5-main.ff8607b"
+    "@dxos/async": "0.7.5-staging.2ff1350",
+    "@dxos/debug": "0.7.5-staging.2ff1350",
+    "@dxos/echo-db": "0.7.5-staging.2ff1350",
+    "@dxos/echo-schema": "0.7.5-staging.2ff1350",
+    "@dxos/live-object": "0.7.5-staging.2ff1350",
+    "@dxos/log": "0.7.5-staging.2ff1350",
+    "@dxos/schema": "0.7.5-staging.2ff1350",
+    "@dxos/invariant": "0.7.5-staging.2ff1350",
+    "@dxos/util": "0.7.5-staging.2ff1350"
   },
   "devDependencies": {
     "@antv/graphlib": "^2.0.4",
     "@antv/layout": "^1.2.13",
     "@types/lodash.defaultsdeep": "^4.6.6",
-    "@dxos/echo-db": "0.7.5-main.ff8607b",
-    "@dxos/random": "0.7.5-main.ff8607b",
-    "@dxos/echo-schema": "0.7.5-main.ff8607b"
+    "@dxos/echo-schema": "0.7.5-staging.2ff1350",
+    "@dxos/echo-db": "0.7.5-staging.2ff1350",
+    "@dxos/random": "0.7.5-staging.2ff1350"
   },
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -2,6 +2,6 @@
 // Copyright 2023 DXOS.org
 //
 
-export * from './buidler';
-export * from './graph';
+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;
+  }
+}