@eventcatalog/core 4.12.3 → 5.0.0-beta.0

package/eventcatalog/src/utils/node-graphs/layout-node-graph.ts

@@ -0,0 +1,28 @@
+import { hideMessageNodes, layoutWithElk } from '@eventcatalog/visualiser/layout';
+
+type Graph = { nodes: any[]; edges: any[] };
+
+/**
+ * Lays a node graph out for the visualiser (with ELK, left to right). Builders
+ * create their nodes and edges without positions and lay the finished graph
+ * out once with this. Nodes get top-left positions (`origin: [0, 0]`), groups
+ * (nodes with children) are sized to fit them, and edges get the route they're
+ * drawn along (`data.route`), with room for their labels.
+ */
+export const layoutNodeGraph = async <G extends Graph>(graph: G): Promise<G> => (await layoutWithElk(graph)) as unknown as G;
+
+/**
+ * Lays out the graphs of a levels page: level 1 (`overview`: domains, systems
+ * and their relationships), level 3 (the detailed graph, with messages and
+ * channels) and level 2 in between, the detailed graph with its messages and
+ * channels hidden (`hiddenMessages`), so the browser doesn't have to lay it out
+ * again. Without an overview there's no level 1.
+ */
+export const layoutLevels = async (detailed: Graph, overview?: Graph) => {
+  const [laidOut, laidOutOverview, hiddenMessages] = await Promise.all([
+    layoutNodeGraph(detailed),
+    overview && layoutNodeGraph(overview),
+    layoutNodeGraph(hideMessageNodes(detailed.nodes, detailed.edges)),
+  ]);
+  return { ...laidOut, overview: laidOutOverview, hiddenMessages };
+};

package/eventcatalog/src/utils/node-graphs/layout-persistence.ts

@@ -55,7 +55,7 @@ export async function loadSavedLayout(resourceKey: string): Promise<SavedLayout
 
 /**
  * Applies saved positions to nodes. Nodes with saved positions get them applied,
- * nodes without saved positions keep their Dagre-calculated positions.
+ * nodes without saved positions keep their laid out positions.
  */
 export function applyLayoutToNodes<T extends { id: string; position: { x: number; y: number } }>(
   nodes: T[],
@@ -63,7 +63,7 @@ export function applyLayoutToNodes<T extends { id: string; position: { x: number
 ): T[];
 export function applyLayoutToNodes(nodes: any[], savedLayout: SavedLayout | null): any[] {
   if (!savedLayout) {
-    return nodes; // No saved layout, use original Dagre positions
+    return nodes; // No saved layout, use the laid out positions
   }
 
   return nodes.map((node) => {
@@ -75,7 +75,7 @@ export function applyLayoutToNodes(nodes: any[], savedLayout: SavedLayout | null
         position: { x: savedPosition.x, y: savedPosition.y },
       };
     }
-    // Keep Dagre-calculated position for new/unmatched nodes
+    // Keep the laid out position for new/unmatched nodes
     return node;
   });
 }

package/eventcatalog/src/utils/node-graphs/message-node-graph.ts

@@ -2,8 +2,6 @@
 import { getEvents } from '@utils/collections/events';
 import { getCollection, type CollectionEntry } from 'astro:content';
 import {
-  calculatedNodes,
-  createDagreGraph,
   createEdge,
   generatedIdForEdge,
   generateIdForNode,
@@ -11,8 +9,8 @@ import {
   getEdgeLabelForMessageAsSource,
   getEdgeLabelForServiceAsTarget,
   versionMatches,
-  layoutDagreGraph,
 } from './utils/utils';
+import { layoutNodeGraph } from '@utils/node-graphs/layout-node-graph';
 import { MarkerType, type Node, type Edge } from '@xyflow/react';
 import {
   findMatchingNodes,
@@ -31,8 +29,6 @@ import {
   buildContextMenuForService,
   buildContextMenuForResource,
   getOperationFields,
-  DEFAULT_NODE_WIDTH,
-  DEFAULT_NODE_HEIGHT,
 } from './utils/utils';
 import { getConsumersOfMessage, getProducersOfMessage } from '@utils/collections/services';
 import {
@@ -44,16 +40,15 @@ import { getChannelChain, isChannelsConnected } from '@utils/collections/channel
 import { getChannels } from '@utils/collections/channels';
 import { getTriggeredByOfMessage, getTriggersOfMessage, type MessageReceiver } from '@utils/collections/message-triggers';
 
-type DagreGraph = any;
 type RoutableResource = CollectionEntry<'agents'> | CollectionEntry<'services'>;
 type ProducerConsumerResource = RoutableResource | CollectionEntry<'data-products'>;
 
 interface Props {
   id: string;
   version: string;
-  defaultFlow?: DagreGraph;
   mode?: 'simple' | 'full';
   channelRenderMode?: 'flat' | 'single';
+  layout?: boolean;
   collection?: CollectionEntry<CollectionMessageTypes>[];
   channels?: CollectionEntry<'channels'>[];
 }
@@ -216,15 +211,14 @@ export const createTriggerMessageNode = (
 const getNodesAndEdges = async ({
   id,
   version,
-  defaultFlow,
   mode = 'simple',
   channelRenderMode = 'flat',
   collection = [],
   channels = [],
+  layout = true,
 }: Props) => {
-  const flow = defaultFlow || createDagreGraph({ ranksep: 300, nodesep: 50 });
-  const nodes = [] as any,
-    edges = [] as any;
+  const nodes: any[] = [],
+    edges: any[] = [];
 
   const message = collection.find((message) => {
     return message.data.id === id && message.data.version === version;
@@ -297,7 +291,7 @@ const getNodesAndEdges = async ({
       sourcePosition: 'right',
       targetPosition: 'left',
       data: isDataProduct(producer) ? getDataProductNodeData(producer, mode) : getRoutableNodeData(producer, mode),
-      position: { x: 250, y: 0 },
+      position: { x: 0, y: 0 },
     });
     if (!isDataProduct(producer)) {
       appendAgentToolNodesAndEdges({ agent: producer, nodes, edges, mode });
@@ -684,54 +678,42 @@ const getNodesAndEdges = async ({
     appendEdge(relation.receiver, relation.message, getEdgeLabelForServiceAsTarget(relation.message), relation.message);
   }
 
-  nodes.forEach((node: any) => {
-    flow.setNode(node.id, { width: DEFAULT_NODE_WIDTH, height: DEFAULT_NODE_HEIGHT });
-  });
-
-  edges.forEach((edge: any) => {
-    flow.setEdge(edge.source, edge.target);
-  });
+  if (!layout) return { nodes, edges };
 
-  // Render the diagram in memory getting hte X and Y
-  layoutDagreGraph(flow);
-
-  return {
-    nodes: calculatedNodes(flow, nodes),
-    edges,
-  };
+  return layoutNodeGraph({ nodes, edges });
 };
 
 export const getNodesAndEdgesForQueries = async ({
   id,
   version,
-  defaultFlow,
   mode = 'simple',
   channelRenderMode = 'flat',
+  layout = true,
 }: Props) => {
   const [queries, channels] = await Promise.all([getQueries(), getChannels()]);
-  return getNodesAndEdges({ id, version, defaultFlow, mode, channelRenderMode, collection: queries, channels });
+  return getNodesAndEdges({ id, version, mode, channelRenderMode, collection: queries, channels, layout });
 };
 
 export const getNodesAndEdgesForCommands = async ({
   id,
   version,
-  defaultFlow,
   mode = 'simple',
   channelRenderMode = 'flat',
+  layout = true,
 }: Props) => {
   const [commands, channels] = await Promise.all([getCommands(), getChannels()]);
-  return getNodesAndEdges({ id, version, defaultFlow, mode, channelRenderMode, collection: commands, channels });
+  return getNodesAndEdges({ id, version, mode, channelRenderMode, collection: commands, channels, layout });
 };
 
 export const getNodesAndEdgesForEvents = async ({
   id,
   version,
-  defaultFlow,
   mode = 'simple',
   channelRenderMode = 'flat',
+  layout = true,
 }: Props) => {
   const [events, channels] = await Promise.all([getEvents(), getChannels()]);
-  return getNodesAndEdges({ id, version, defaultFlow, mode, channelRenderMode, collection: events, channels });
+  return getNodesAndEdges({ id, version, mode, channelRenderMode, collection: events, channels, layout });
 };
 
 export const getNodesAndEdgesForConsumedMessage = ({
@@ -756,7 +738,7 @@ export const getNodesAndEdgesForConsumedMessage = ({
   channelMap?: Map<string, CollectionEntry<'channels'>[]>;
 }) => {
   let nodes = [] as Node[],
-    edges = [] as any;
+    edges: any[] = [];
 
   // Use the provided map or create one if missing
   const map = channelMap || createVersionedMap(channels);
@@ -1092,7 +1074,7 @@ export const getNodesAndEdgesForProducedMessage = ({
   channelMap?: Map<string, CollectionEntry<'channels'>[]>;
 }) => {
   let nodes = [] as Node[],
-    edges = [] as any;
+    edges: any[] = [];
 
   // Use provided map or create one
   const map = channelMap || createVersionedMap(channels);

package/eventcatalog/src/utils/node-graphs/services-node-graph.ts

@@ -1,20 +1,16 @@
 import { getCollection, type CollectionEntry } from 'astro:content';
 import {
-  createDagreGraph,
   generateIdForNode,
   generatedIdForEdge,
-  calculatedNodes,
   createEdge,
   buildContextMenuForAgent,
   buildContextMenuForService,
   buildContextMenuForResource,
   versionMatches,
-  DEFAULT_NODE_WIDTH,
-  DEFAULT_NODE_HEIGHT,
   partitionMessagesByGroup,
   getOperationFields,
-  layoutDagreGraph,
 } from '@utils/node-graphs/utils/utils';
+import { layoutNodeGraph } from '@utils/node-graphs/layout-node-graph';
 
 const sanitizeGroupId = (name: string) => name.replace(/[^a-zA-Z0-9]/g, '-').toLowerCase();
 const sanitizeToolId = (name: string) =>
@@ -108,12 +104,9 @@ const precomputeGroupExpansion = (
   return { expandedNodes, expandedEdges };
 };
 
-type DagreGraph = any;
-
 interface Props {
   id: string;
   version: string;
-  defaultFlow?: DagreGraph;
   mode?: 'simple' | 'full';
   renderAllEdges?: boolean;
   channelRenderMode?: 'single' | 'flat';
@@ -172,7 +165,6 @@ const getReceivesMessageByMessageType = (messageType: string) => {
 
 export const getNodesAndEdges = async ({
   id,
-  defaultFlow,
   version,
   mode = 'simple',
   renderAllEdges = false,
@@ -181,7 +173,6 @@ export const getNodesAndEdges = async ({
   collection = 'services',
   layout = true,
 }: Props) => {
-  const flow = defaultFlow || createDagreGraph({ ranksep: 300, nodesep: 50 });
   let nodes = [] as any,
     edges = [] as any;
 
@@ -282,6 +273,7 @@ export const getNodesAndEdges = async ({
 
       nodes.push({
         id: groupNodeId,
+        position: { x: 0, y: 0 },
         sourcePosition: 'right',
         targetPosition: 'left',
         type: 'messageGroup',
@@ -345,6 +337,7 @@ export const getNodesAndEdges = async ({
   // The service itself
   nodes.push({
     id: generateIdForNode(service),
+    position: { x: 0, y: 0 },
     sourcePosition: 'right',
     targetPosition: 'left',
     data: {
@@ -358,6 +351,7 @@ export const getNodesAndEdges = async ({
   writesTo.forEach((writeTo) => {
     nodes.push({
       id: generateIdForNode(writeTo),
+      position: { x: 0, y: 0 },
       sourcePosition: 'right',
       targetPosition: 'left',
       data: {
@@ -398,6 +392,7 @@ export const getNodesAndEdges = async ({
 
       nodes.push({
         id: toolNodeId,
+        position: { x: 0, y: 0 },
         sourcePosition: 'right',
         targetPosition: 'left',
         data: {
@@ -447,6 +442,7 @@ export const getNodesAndEdges = async ({
   readsFrom.forEach((readFrom) => {
     nodes.push({
       id: generateIdForNode(readFrom),
+      position: { x: 0, y: 0 },
       sourcePosition: 'right',
       targetPosition: 'left',
       data: {
@@ -500,6 +496,7 @@ export const getNodesAndEdges = async ({
 
       nodes.push({
         id: groupNodeId,
+        position: { x: 0, y: 0 },
         sourcePosition: 'right',
         targetPosition: 'left',
         type: 'messageGroup',
@@ -626,19 +623,6 @@ export const getNodesAndEdges = async ({
 
   const uniqueNodes = Array.from(uniqueNodesById.values());
 
-  uniqueNodes.forEach((node: any) => {
-    flow.setNode(node.id, { width: DEFAULT_NODE_WIDTH, height: DEFAULT_NODE_HEIGHT });
-  });
-
-  edges.forEach((edge: any) => {
-    flow.setEdge(edge.source, edge.target);
-  });
-
-  if (layout) {
-    // Render the diagram in memory getting the X and Y
-    layoutDagreGraph(flow);
-  }
-
   // Find any duplicated edges, and merge them into one edge
   const uniqueEdgesById = new Map<string, any>();
   edges.forEach((edge: any) => {
@@ -661,8 +645,10 @@ export const getNodesAndEdges = async ({
   });
   const uniqueEdges = Array.from(uniqueEdgesById.values());
 
-  return {
-    nodes: calculatedNodes(flow, uniqueNodes),
+  const graph = {
+    nodes: uniqueNodes.map((node: any) => ({ ...node, position: node.position ?? { x: 0, y: 0 } })),
     edges: uniqueEdges,
   };
+
+  return layout ? await layoutNodeGraph(graph) : graph;
 };

package/eventcatalog/src/utils/node-graphs/system-context-node-graph.ts

@@ -1,32 +1,17 @@
 import { getCollection } from 'astro:content';
 import type { CollectionEntry } from 'astro:content';
-import {
-  createDagreGraph,
-  calculatedNodes,
-  createEdge,
-  generateIdForNode,
-  buildContextMenuForSystem,
-  DEFAULT_NODE_HEIGHT,
-  layoutDagreGraph,
-} from '@utils/node-graphs/utils/utils';
+import { createEdge, generateIdForNode, buildContextMenuForSystem } from '@utils/node-graphs/utils/utils';
+import { layoutNodeGraph } from '@utils/node-graphs/layout-node-graph';
 import { MarkerType } from '@xyflow/react';
 import { createVersionedMap, findInMap } from '@utils/collections/util';
 
-type DagreGraph = any;
-
 interface NodesAndEdgesProps {
   id: string;
   version: string;
-  defaultFlow?: DagreGraph;
   mode?: 'simple' | 'full';
   layout?: boolean;
 }
 
-// System nodes are wider than the default to fit the system name + summary comfortably.
-const SYSTEM_NODE_WIDTH = 270;
-// Actor nodes are narrower than systems — a compact pill with an icon + name.
-const ACTOR_NODE_WIDTH = 180;
-
 type SystemActor = {
   id: string;
   name?: string;
@@ -52,7 +37,6 @@ interface ContextGraphFromSeedsProps {
   seedSystems: CollectionEntry<'systems'>[];
   systemMap: Map<string, CollectionEntry<'systems'>[]>;
   serviceMap: Map<string, CollectionEntry<'services'>[]>;
-  defaultFlow?: DagreGraph;
   mode?: 'simple' | 'full';
   layout?: boolean;
 }
@@ -67,15 +51,13 @@ interface ContextGraphFromSeedsProps {
  * (relationships without a label are intentionally not drawn). Actors are rendered
  * inline and deduped across all systems.
  */
-const buildContextGraphFromSeeds = ({
+const buildContextGraphFromSeeds = async ({
   seedSystems,
   systemMap,
   serviceMap,
-  defaultFlow,
   mode = 'simple',
   layout = true,
 }: ContextGraphFromSeedsProps) => {
-  const flow = defaultFlow || createDagreGraph({ ranksep: 280, nodesep: 80, edgesep: 50 });
   const nodes = new Map<string, any>();
   const edges = new Map<string, any>();
 
@@ -89,8 +71,6 @@ const buildContextGraphFromSeeds = ({
     }, 0);
   };
 
-  // Actor node ids, tracked so they can be sized differently during layout.
-  const actorNodeIds = new Set<string>();
   // System node ids, tracked so we can detect reciprocal system-to-system
   // relationships and collapse them into a single double-headed edge.
   const systemNodeIds = new Set<string>();
@@ -118,7 +98,6 @@ const buildContextGraphFromSeeds = ({
     const nodeId = `actor-${actor.id}`;
     if (nodes.has(nodeId)) return nodeId;
 
-    actorNodeIds.add(nodeId);
     nodes.set(nodeId, {
       id: nodeId,
       type: 'context-actor',
@@ -292,30 +271,15 @@ const buildContextGraphFromSeeds = ({
     mergedEdgeKeys.add(reverseId);
   }
 
-  // Lay the graph out
-  nodes.forEach((node) =>
-    flow.setNode(node.id, {
-      width: actorNodeIds.has(node.id) ? ACTOR_NODE_WIDTH : SYSTEM_NODE_WIDTH,
-      height: DEFAULT_NODE_HEIGHT,
-    })
-  );
-  edges.forEach((edge) => flow.setEdge(edge.source, edge.target));
-
-  if (layout) {
-    layoutDagreGraph(flow);
-  }
-
-  return {
-    nodes: calculatedNodes(flow, Array.from(nodes.values())),
-    edges: [...edges.values()],
-  };
+  const graph = { nodes: [...nodes.values()], edges: [...edges.values()] };
+  return layout ? layoutNodeGraph(graph) : graph;
 };
 
 /**
  * Builds the System Diagram for a single system, seeding the traversal from
  * that system and walking its relationships and actors outward.
  */
-export const getNodesAndEdges = async ({ id, version, defaultFlow, mode = 'simple', layout = true }: NodesAndEdgesProps) => {
+export const getNodesAndEdges = async ({ id, version, mode = 'simple', layout = true }: NodesAndEdgesProps) => {
   const [allSystems, allServices] = await Promise.all([getCollection('systems'), getCollection('services')]);
   const systemMap = createVersionedMap(allSystems);
   const serviceMap = createVersionedMap(allServices);
@@ -327,7 +291,14 @@ export const getNodesAndEdges = async ({ id, version, defaultFlow, mode = 'simpl
     return { nodes: [], edges: [] };
   }
 
-  return buildContextGraphFromSeeds({ seedSystems: [rootSystem], systemMap, serviceMap, defaultFlow, mode, layout });
+  const graph = await buildContextGraphFromSeeds({ seedSystems: [rootSystem], systemMap, serviceMap, mode, layout });
+
+  // Mark the system being viewed, like other resource graphs do
+  const rootNodeId = generateIdForNode(rootSystem);
+  return {
+    ...graph,
+    nodes: graph.nodes.map((node: any) => (node.id === rootNodeId ? { ...node, data: { ...node.data, isFocused: true } } : node)),
+  };
 };
 
 /**
@@ -336,13 +307,7 @@ export const getNodesAndEdges = async ({ id, version, defaultFlow, mode = 'simpl
  * the domain's systems plus any related systems they point at (or that point at them),
  * with actors rendered inline — giving a single context view across the domain.
  */
-export const getNodesAndEdgesForDomainSystems = async ({
-  id,
-  version,
-  defaultFlow,
-  mode = 'simple',
-  layout = true,
-}: NodesAndEdgesProps) => {
+export const getNodesAndEdgesForDomainSystems = async ({ id, version, mode = 'simple', layout = true }: NodesAndEdgesProps) => {
   const [allDomains, allSystems, allServices] = await Promise.all([
     getCollection('domains'),
     getCollection('systems'),
@@ -367,11 +332,10 @@ export const getNodesAndEdgesForDomainSystems = async ({
     return { nodes: [], edges: [] };
   }
 
-  return buildContextGraphFromSeeds({ seedSystems, systemMap, serviceMap, defaultFlow, mode, layout });
+  return buildContextGraphFromSeeds({ seedSystems, systemMap, serviceMap, mode, layout });
 };
 
 interface AllSystemsProps {
-  defaultFlow?: DagreGraph;
   mode?: 'simple' | 'full';
   layout?: boolean;
 }
@@ -381,7 +345,7 @@ interface AllSystemsProps {
  * seed, so the traversal draws all systems, the relationships between them, and the
  * actors around them — a single map of how every system in the catalog relates.
  */
-export const getNodesAndEdgesForAllSystems = async ({ defaultFlow, mode = 'simple', layout = true }: AllSystemsProps = {}) => {
+export const getNodesAndEdgesForAllSystems = async ({ mode = 'simple', layout = true }: AllSystemsProps = {}) => {
   const [allSystems, allServices] = await Promise.all([getCollection('systems'), getCollection('services')]);
   const systemMap = createVersionedMap(allSystems);
   const serviceMap = createVersionedMap(allServices);
@@ -396,5 +360,5 @@ export const getNodesAndEdgesForAllSystems = async ({ defaultFlow, mode = 'simpl
     return { nodes: [], edges: [] };
   }
 
-  return buildContextGraphFromSeeds({ seedSystems, systemMap, serviceMap, defaultFlow, mode, layout });
+  return buildContextGraphFromSeeds({ seedSystems, systemMap, serviceMap, mode, layout });
 };

package/eventcatalog/src/utils/node-graphs/system-levels-node-graph.ts

@@ -0,0 +1,59 @@
+import { getNodesAndEdges as getSystemContextNodesAndEdges } from './system-context-node-graph';
+import { getNodesAndEdges as getSystemNodesAndEdges } from './systems-node-graph';
+import { layoutLevels } from '@utils/node-graphs/layout-node-graph';
+
+interface NodesAndEdgesProps {
+  id: string;
+  version: string;
+  mode?: 'simple' | 'full';
+  channelRenderMode?: 'single' | 'flat';
+}
+
+const CACHE_ENABLED = process.env.DISABLE_EVENTCATALOG_CACHE !== 'true';
+
+// Built once for each system version and options
+const levelsCache = new Map<string, ReturnType<typeof buildLevels>>();
+
+export const getNodesAndEdges = (props: NodesAndEdgesProps) => {
+  if (!CACHE_ENABLED) return buildLevels(props);
+  const { id, version, mode = 'simple', channelRenderMode } = props;
+  const key = [id, version, mode, channelRenderMode].join('/');
+  if (!levelsCache.has(key)) levelsCache.set(key, buildLevels(props));
+  return levelsCache.get(key)!;
+};
+
+/**
+ * A system's resource diagram shown inside its context diagram: the system's node
+ * is replaced by the expanded system group (services, data stores, messages...),
+ * and the system's relationships and actors connect to the group instead.
+ * Returns level 1 too (`overview`, the context diagram) and the graph without
+ * its messages and channels (`hiddenMessages`).
+ */
+const buildLevels = async ({ id, version, mode = 'simple', channelRenderMode }: NodesAndEdgesProps) => {
+  const [context, system] = await Promise.all([
+    getSystemContextNodesAndEdges({ id, version, mode, layout: false }),
+    getSystemNodesAndEdges({ id, version, mode, channelRenderMode, wrapInSystemGroup: true, layout: false }),
+  ]);
+
+  const group = system.nodes.find((node: any) => node.type === 'system-group');
+  const rootSystemNode = context.nodes.find((node: any) => node.data?.isFocused);
+  if (!group || !rootSystemNode) return layoutLevels(system, context);
+
+  const systemNodeIds = new Set(system.nodes.map((node: any) => node.id));
+  const contextNodes = context.nodes.filter((node: any) => node.id !== rootSystemNode.id && !systemNodeIds.has(node.id));
+  const toGroup = (nodeId: string) => (nodeId === rootSystemNode.id ? group.id : nodeId);
+  const contextEdges = context.edges.map((edge: any) => ({
+    ...edge,
+    id: `context-${edge.id}`,
+    source: toGroup(edge.source),
+    target: toGroup(edge.target),
+  }));
+
+  // Lay the context and the expanded system out together
+  const detailed = {
+    // Parent must come before its children in the array for React Flow
+    nodes: [group, ...contextNodes, ...system.nodes.filter((node: any) => node.id !== group.id)],
+    edges: [...system.edges, ...contextEdges],
+  };
+  return layoutLevels(detailed, context);
+};