@eventcatalog/core 5.0.0-beta.3 → 5.0.0-beta.30

package/eventcatalog/src/features/studio/catalog-resources.ts

@@ -0,0 +1,155 @@
+import { getDomains } from '@utils/collections/domains';
+import { getSystems } from '@utils/collections/systems';
+import { getServices } from '@utils/collections/services';
+import { getEvents } from '@utils/collections/events';
+import { getCommands } from '@utils/collections/commands';
+import { getQueries } from '@utils/collections/queries';
+import { getChannels } from '@utils/collections/channels';
+import { getContainers } from '@utils/collections/containers';
+import { buildUrl } from '@utils/url-builder';
+
+/** A catalog resource that can be dropped onto the canvas (latest version only) */
+export type CatalogResource = {
+  /** `${collection}:${id}`, stored on the canvas node so relationships can be found */
+  key: string;
+  collection: string;
+  id: string;
+  version: string;
+  name: string;
+  summary?: string;
+  url: string;
+  node: { type: string; data: Record<string, unknown> };
+};
+
+/** A relationship between two catalog resources, by key */
+export type CatalogRelation = { source: string; target: string; label?: string };
+
+const keyOf = (collection: string, id: string) => `${collection}:${id}`;
+
+/** The collection helpers hydrate references (e.g. a domain's services) into entries; their types describe references */
+type HydratedEntry = { data: { id: string } };
+const isHydratedEntry = (value: unknown): value is HydratedEntry => {
+  if (typeof value !== 'object' || value === null || !('data' in value)) return false;
+  const { data } = value;
+  return typeof data === 'object' && data !== null && 'id' in data && typeof data.id === 'string';
+};
+const entries = (value: unknown): HydratedEntry[] => (Array.isArray(value) ? value.filter(isHydratedEntry) : []);
+const idsOf = (value: unknown) => entries(value).map((entry) => entry.data.id);
+
+const toResource = (
+  collection: string,
+  entry: { data: { id: string; version: string; name?: string; summary?: string } },
+  node: CatalogResource['node']
+): CatalogResource => ({
+  key: keyOf(collection, entry.data.id),
+  collection,
+  id: entry.data.id,
+  version: entry.data.version,
+  name: entry.data.name ?? entry.data.id,
+  summary: entry.data.summary,
+  url: buildUrl(`/docs/${collection}/${entry.data.id}/${entry.data.version}`),
+  node,
+});
+
+// Visualiser node data needs plain fields (not collection entries)
+const basics = ({ data }: { data: { id: string; version: string; name?: string; summary?: string } }) => ({
+  id: data.id,
+  version: data.version,
+  name: data.name ?? data.id,
+  summary: data.summary ?? '',
+});
+
+export const getCatalogResources = async (): Promise<{ resources: CatalogResource[]; relations: CatalogRelation[] }> => {
+  const [domains, systems, services, events, commands, queries, channels, containers] = await Promise.all([
+    getDomains({ getAllVersions: false }),
+    getSystems({ getAllVersions: false }),
+    getServices({ getAllVersions: false }),
+    getEvents({ getAllVersions: false, hydrateServices: false }),
+    getCommands({ getAllVersions: false, hydrateServices: false }),
+    getQueries({ getAllVersions: false, hydrateServices: false }),
+    getChannels({ getAllVersions: false }),
+    getContainers({ getAllVersions: false }),
+  ]);
+
+  const messages = [
+    ...events.map((entry) => ({ entry, collection: 'events', type: 'event' })),
+    ...commands.map((entry) => ({ entry, collection: 'commands', type: 'command' })),
+    ...queries.map((entry) => ({ entry, collection: 'queries', type: 'query' })),
+  ];
+  const messageCollection = new Map(messages.map(({ entry, collection }) => [entry.data.id, collection]));
+
+  const resources: CatalogResource[] = [
+    ...domains.map((domain) =>
+      toResource('domains', domain, {
+        type: 'context-domain',
+        data: {
+          mode: 'full',
+          navigable: false,
+          domain: basics(domain),
+          systemsCount: idsOf(domain.data.systems).length,
+          servicesCount: idsOf(domain.data.services).length,
+          entitiesCount: idsOf(domain.data.entities).length,
+        },
+      })
+    ),
+    ...systems.map((system) =>
+      toResource('systems', system, {
+        type: 'system',
+        data: {
+          mode: 'full',
+          navigable: false,
+          system: { ...basics(system), scope: system.data.scope },
+          servicesCount: idsOf(system.data.services).length,
+          containersCount: idsOf(system.data.containers).length,
+        },
+      })
+    ),
+    ...services.map((service) =>
+      toResource('services', service, { type: 'service', data: { mode: 'full', service: basics(service) } })
+    ),
+    ...messages.map(({ entry, collection, type }) =>
+      toResource(collection, entry, { type, data: { mode: 'full', message: basics(entry) } })
+    ),
+    ...channels.map((channel) =>
+      toResource('channels', channel, {
+        type: 'channel',
+        data: { mode: 'full', channel: { ...basics(channel), protocols: channel.data.protocols ?? [] } },
+      })
+    ),
+    ...containers.map((container) =>
+      toResource('containers', container, {
+        type: 'data',
+        data: { mode: 'full', data: { ...basics(container), container_type: container.data.container_type } },
+      })
+    ),
+  ];
+
+  const relations: CatalogRelation[] = [];
+  const relate = (source: string, target: string, label?: string) => relations.push({ source, target, label });
+
+  for (const domain of domains) {
+    for (const id of idsOf(domain.data.systems)) relate(keyOf('domains', domain.data.id), keyOf('systems', id), 'contains');
+    for (const id of idsOf(domain.data.services)) relate(keyOf('domains', domain.data.id), keyOf('services', id), 'contains');
+  }
+  for (const system of systems) {
+    for (const id of idsOf(system.data.services)) relate(keyOf('systems', system.data.id), keyOf('services', id), 'contains');
+  }
+  for (const service of services) {
+    const serviceKey = keyOf('services', service.data.id);
+    for (const id of idsOf(service.data.sends)) {
+      const collection = messageCollection.get(id);
+      if (collection) relate(serviceKey, keyOf(collection, id));
+    }
+    for (const id of idsOf(service.data.receives)) {
+      const collection = messageCollection.get(id);
+      if (collection) relate(keyOf(collection, id), serviceKey);
+    }
+    // A data store it both writes to and reads from is one connection (like the visualiser), not two on top of each other
+    const reads = new Set(idsOf(service.data.readsFrom));
+    const writes = new Set(idsOf(service.data.writesTo));
+    for (const id of writes) relate(serviceKey, keyOf('containers', id), reads.has(id) ? 'reads and writes' : undefined);
+    for (const id of reads) if (!writes.has(id)) relate(keyOf('containers', id), serviceKey);
+  }
+
+  return { resources, relations };
+};

package/eventcatalog/src/features/studio/catalog.ts

@@ -0,0 +1,173 @@
+import type { Edge, Node } from '@xyflow/react';
+import type { CatalogRelation, CatalogResource } from './catalog-resources';
+import { buildNode, createEdge, layoutGraph, withGroupSizes, GROUP_TYPES, isGroupType } from '@eventcatalog/visualiser/studio';
+
+/**
+ * Catalog resources on a canvas: the node for a resource, its connections to related resources already there,
+ * and domains and systems as containers with what they hold in the catalog.
+ */
+
+export type CatalogLink = { key: string; url: string; version: string };
+
+/** The node data for a resource, tagged with the catalog resource it came from */
+export const catalogNodeData = (resource: CatalogResource) => ({
+  ...resource.node.data,
+  catalog: { key: resource.key, url: resource.url, version: resource.version } satisfies CatalogLink,
+});
+
+export const getCatalogLink = (node: Pick<Node, 'data'>) => node.data?.catalog as CatalogLink | undefined;
+
+export const indexRelations = (relations: CatalogRelation[]) => {
+  const byKey = new Map<string, CatalogRelation[]>();
+  for (const relation of relations) {
+    for (const key of [relation.source, relation.target]) byKey.set(key, [...(byKey.get(key) ?? []), relation]);
+  }
+  return byKey;
+};
+
+/**
+ * Edges from a newly dropped resource to the related resources already on the canvas. A container doesn't get
+ * "contains" edges: what it contains sits inside it.
+ */
+export const getRelatedEdges = (
+  resource: CatalogResource,
+  nodeId: string,
+  existing: Node[],
+  relationsByKey: Map<string, CatalogRelation[]>,
+  nodeType = resource.node.type
+): Edge[] => {
+  const edges: Edge[] = [];
+  for (const relation of relationsByKey.get(resource.key) ?? []) {
+    const isSource = relation.source === resource.key;
+    const otherKey = isSource ? relation.target : relation.source;
+
+    for (const other of existing.filter((node) => getCatalogLink(node)?.key === otherKey)) {
+      if (relation.label === 'contains' && (isGroupType(nodeType) || isGroupType(other.type))) continue;
+      const [source, target] = isSource ? [{ id: nodeId, type: nodeType }, other] : [other, { id: nodeId, type: nodeType }];
+      const edge = createEdge(
+        { source: source.id, target: target.id, sourceHandle: null, targetHandle: null },
+        source.type,
+        target.type
+      );
+      edges.push(relation.label ? { ...edge, label: relation.label } : edge);
+    }
+  }
+  return edges;
+};
+
+// ---- Domains and systems as containers ----
+
+export const canBeContainer = (resource: CatalogResource) =>
+  resource.collection === 'domains' || resource.collection === 'systems';
+
+export const containerTypeFor = (resource: CatalogResource) =>
+  resource.collection === 'domains' ? GROUP_TYPES.domain : GROUP_TYPES.system;
+
+/** A container's data: the domain or system it stands for (an external system marked as one), and where it is in the catalog */
+export const catalogGroupData = (resource: CatalogResource) => {
+  const key = resource.collection === 'domains' ? 'domain' : 'system';
+  const { scope } = (resource.node.data[key] ?? {}) as { scope?: string };
+  return {
+    [key]: {
+      id: resource.id,
+      name: resource.name,
+      version: resource.version,
+      summary: resource.summary,
+      ...(scope && { scope }),
+    },
+    catalog: { key: resource.key, url: resource.url, version: resource.version } satisfies CatalogLink,
+  };
+};
+
+/** What a domain or system contains in the catalog: a domain's systems and services, a system's services */
+export const getContents = (
+  resource: CatalogResource,
+  catalog: { resourcesByKey: Map<string, CatalogResource>; relationsByKey: Map<string, CatalogRelation[]> }
+) =>
+  (catalog.relationsByKey.get(resource.key) ?? [])
+    .filter((relation) => relation.source === resource.key && relation.label === 'contains')
+    .map((relation) => catalog.resourcesByKey.get(relation.target))
+    .filter((child): child is CatalogResource => !!child);
+
+/** A domain or system as an (empty) container, centred on a point */
+export const buildContainer = (resource: CatalogResource, center: { x: number; y: number }): Node =>
+  buildNode(containerTypeFor(resource), catalogGroupData(resource), center);
+
+/**
+ * A domain or system as a container with everything it holds in the catalog: its systems (as containers too)
+ * and services, and the messages and data stores of those services, so every level of detail (L1 to L3) has
+ * something to show. Laid out with the visualiser's layout and centred on a point, with the connections between
+ * them and to related resources already on the canvas. Resources already on the canvas aren't added again.
+ */
+export const buildContainerWithContents = async (
+  resource: CatalogResource,
+  center: { x: number; y: number },
+  catalog: { resourcesByKey: Map<string, CatalogResource>; relationsByKey: Map<string, CatalogRelation[]> },
+  existing: Node[]
+): Promise<{ nodes: Node[]; edges: Edge[] }> => {
+  const onCanvas = new Set(existing.map((node) => getCatalogLink(node)?.key).filter(Boolean));
+  const root = buildContainer(resource, { x: 0, y: 0 });
+  const nodes: Node[] = [root];
+  const added = (key: string) => onCanvas.has(key) || nodes.some((node) => getCatalogLink(node)?.key === key);
+  const services: { resource: CatalogResource; parentId: string }[] = [];
+
+  // Its systems (as containers, with their services) and services
+  const fill = (parent: CatalogResource, parentId: string) => {
+    for (const child of getContents(parent, catalog)) {
+      if (added(child.key)) continue;
+      if (canBeContainer(child)) {
+        const container = { ...buildContainer(child, { x: 0, y: 0 }), parentId };
+        nodes.push(container);
+        fill(child, container.id);
+      } else {
+        nodes.push({ ...buildNode(child.node.type, catalogNodeData(child), { x: 0, y: 0 }), parentId });
+        if (child.collection === 'services') services.push({ resource: child, parentId });
+      }
+    }
+  };
+  fill(resource, root.id);
+
+  // The messages its services send and receive (in the domain or system dropped), and their data stores (next to them)
+  for (const service of services) {
+    for (const relation of catalog.relationsByKey.get(service.resource.key) ?? []) {
+      if (relation.label === 'contains') continue;
+      const other = catalog.resourcesByKey.get(relation.source === service.resource.key ? relation.target : relation.source);
+      if (!other || added(other.key) || canBeContainer(other) || other.collection === 'services') continue;
+      const parentId = other.collection === 'containers' ? service.parentId : root.id;
+      nodes.push({ ...buildNode(other.node.type, catalogNodeData(other), { x: 0, y: 0 }), parentId });
+    }
+  }
+
+  if (nodes.length === 1) return { nodes: [buildContainer(resource, center)], edges: [] };
+
+  // Connections between them, and to related resources already on the canvas
+  const inside: Edge[] = [];
+  const outside: Edge[] = [];
+  const placed = [...existing];
+  for (const node of nodes) {
+    const link = getCatalogLink(node);
+    const related = link && catalog.resourcesByKey.get(link.key);
+    if (related) {
+      for (const edge of getRelatedEdges(related, node.id, placed, catalog.relationsByKey, node.type)) {
+        (existing.some((other) => other.id === edge.source || other.id === edge.target) ? outside : inside).push(edge);
+      }
+    }
+    placed.push(node);
+  }
+
+  // Laid out with its connections; containers are sized to fit what's in them
+  const laidOut = withGroupSizes((await layoutGraph(nodes, inside)).nodes);
+  const top = laidOut.find((node) => node.id === root.id)!;
+  const offset = { x: center.x - (top.width ?? 0) / 2 - top.position.x, y: center.y - (top.height ?? 0) / 2 - top.position.y };
+  return {
+    nodes: laidOut.map((node) => {
+      const original = nodes.find((candidate) => candidate.id === node.id)!;
+      return {
+        ...original,
+        position: node.parentId ? node.position : { x: node.position.x + offset.x, y: node.position.y + offset.y },
+        ...(isGroupType(node.type) && { width: node.width, height: node.height }),
+      };
+    }),
+    edges: [...inside, ...outside],
+  };
+};