@eventcatalog/core 5.0.0-beta.2 → 5.0.0-beta.20

package/eventcatalog/src/utils/collections/channels.ts

@@ -1,6 +1,13 @@
 import { getCollection } from 'astro:content';
 import type { CollectionEntry } from 'astro:content';
-import { getItemsFromCollectionByIdAndSemverOrLatest, createVersionedMap, satisfies } from './util';
+import {
+  getItemsFromCollectionByIdAndSemverOrLatest,
+  createVersionedMap,
+  findInMap,
+  getVersionedMap,
+  satisfies,
+  uniqueResources,
+} from './util';
 import type { CollectionMessageTypes } from '@types';
 
 const CACHE_ENABLED = process.env.DISABLE_EVENTCATALOG_CACHE !== 'true';
@@ -195,3 +202,51 @@ export const getChannelChain = (
   }
   return [];
 };
+
+/**
+ * What a channel connects: the services and agents that send to it (`sends[].to`) or receive
+ * from it (`receives[].from`), and the messages that travel through it, from those pointers or
+ * from messages that list the channel (`data.messages` from getChannels). Pass raw entries:
+ * hydration resolves sends/receives to messages and drops the channel pointers. Pointers
+ * without a version mean the latest channel or message.
+ */
+export const getChannelConnections = (
+  channel: Channel,
+  catalog: {
+    endpoints: Array<CollectionEntry<'services'> | CollectionEntry<'agents'>>;
+    channels: Channel[];
+    messages: CollectionEntry<CollectionMessageTypes>[];
+  }
+) => {
+  const channelMap = getVersionedMap(catalog.channels);
+  const messageMap = getVersionedMap(catalog.messages);
+  const isThisChannel = (pointer: { id: string; version?: string }) => {
+    const match = findInMap(channelMap, pointer.id, pointer.version);
+    return match?.data.id === channel.data.id && match?.data.version === channel.data.version;
+  };
+
+  const producers: Array<CollectionEntry<'services'> | CollectionEntry<'agents'>> = [];
+  const consumers: Array<CollectionEntry<'services'> | CollectionEntry<'agents'>> = [];
+  const messages: CollectionEntry<CollectionMessageTypes>[] = [];
+  const addMessage = (pointer: { id: string; version?: string }) => {
+    const message = findInMap(messageMap, pointer.id, pointer.version);
+    if (message) messages.push(message);
+  };
+
+  for (const endpoint of catalog.endpoints) {
+    for (const send of (endpoint.data.sends || []) as any[]) {
+      if (!(send.to || []).some(isThisChannel)) continue;
+      producers.push(endpoint);
+      addMessage(send);
+    }
+    for (const receive of (endpoint.data.receives || []) as any[]) {
+      if (!(receive.from || []).some(isThisChannel)) continue;
+      consumers.push(endpoint);
+      addMessage(receive);
+    }
+  }
+
+  for (const message of (channel.data as any).messages || []) addMessage(message);
+
+  return { producers: uniqueResources(producers), consumers: uniqueResources(consumers), messages: uniqueResources(messages) };
+};

package/eventcatalog/src/utils/collections/flows.ts

@@ -1,6 +1,6 @@
 import { getCollection } from 'astro:content';
 import type { CollectionEntry } from 'astro:content';
-import { createVersionedMap, findInMap } from '@utils/collections/util';
+import { createVersionedMap, findInMap, getVersionedMap, uniqueResources } from '@utils/collections/util';
 import { getDomains } from './domains';
 import { getServices } from './services';
 import { getAgents } from './agents';
@@ -147,6 +147,55 @@ export const getFlowsNotInAnyResource = async (): Promise<Flow[]> => {
   return flowsNotInAnyResource;
 };
 
+/**
+ * Finds the flows with a step that points at the service. A step without a version points
+ * at the latest service version, so `services` must include every version.
+ */
+export const getFlowsWithServiceStep = (
+  service: CollectionEntry<'services'>,
+  flows: Flow[],
+  services: CollectionEntry<'services'>[]
+): Flow[] => {
+  const serviceMap = getVersionedMap(services);
+  return flows.filter((flow) =>
+    (flow.data.steps || []).some((step: any) => {
+      if (!step.service) return false;
+      const match = findInMap(serviceMap, step.service.id, step.service.version);
+      return match?.data.id === service.data.id && match?.data.version === service.data.version;
+    })
+  );
+};
+
+/** A catalog entry a flow step points at (a service, message, agent, data store, data product or flow). */
+type FlowStepResource = { collection: string; data: { id: string; version: string; [key: string]: any } };
+
+/**
+ * The catalog resources a flow's steps point at, each listed once in step order: messages,
+ * services, agents, data stores, data products and sub-flows (the same steps the flow's
+ * sidebar lists). Expects steps as getFlows returns them, where messages, agents, data stores
+ * and data products are already resolved; services and sub-flows are resolved here, with a
+ * pointer without a version meaning the latest.
+ */
+export const getFlowStepResources = (
+  flow: Flow,
+  catalog: { services: CollectionEntry<'services'>[]; flows: Flow[] }
+): FlowStepResource[] => {
+  const serviceMap = getVersionedMap(catalog.services);
+  const flowMap = getVersionedMap(catalog.flows);
+  const resources: FlowStepResource[] = [];
+
+  for (const step of (flow.data.steps || []) as any[]) {
+    const resource = step.service
+      ? findInMap(serviceMap, step.service.id, step.service.version)
+      : step.flow
+        ? findInMap(flowMap, step.flow.id, step.flow.version)
+        : [step.message, step.agent, step.container, step.dataProduct].find(Array.isArray)?.[0];
+    if (resource?.data) resources.push(resource);
+  }
+
+  return uniqueResources(resources);
+};
+
 /** A flow that includes a message in one of its steps, reduced to what the schema pages display. */
 export interface FlowReference {
   id: string;

package/eventcatalog/src/utils/collections/message-connections.ts

@@ -0,0 +1,60 @@
+import type { CollectionEntry } from 'astro:content';
+import type { CollectionMessageTypes } from '@types';
+import { findInMap, getVersionedMap, uniqueResources } from './util';
+import { getTriggeredByOfMessage, getTriggersOfMessage, messageMatchesPointer, type MessageReceiver } from './message-triggers';
+
+type Message = CollectionEntry<CollectionMessageTypes>;
+type Pointer = { id: string; version?: string };
+
+/**
+ * What a message connects to, beyond the producers and consumers getEvents/getCommands/getQueries
+ * already attach: the channels it travels on (its own `channels`, and the `to`/`from` channels of
+ * services, agents and domains that send or receive it), the flows with a step for it, and the
+ * messages it triggers or is triggered by. Receivers must be raw collection entries, because
+ * hydration drops the channel and trigger pointers on sends/receives.
+ */
+export const getMessageConnections = (
+  message: Message,
+  catalog: {
+    receivers: MessageReceiver[];
+    messages: Message[];
+    channels: CollectionEntry<'channels'>[];
+    flows: CollectionEntry<'flows'>[];
+  }
+) => {
+  const channelMap = getVersionedMap(catalog.channels);
+  const resolveChannels = (pointers: Pointer[] = []) =>
+    pointers.map((pointer) => findInMap(channelMap, pointer.id, pointer.version)).filter((channel) => !!channel);
+
+  const channels = [...resolveChannels((message.data as any).channels)];
+  for (const receiver of catalog.receivers) {
+    for (const send of ((receiver.data as any).sends || []) as Array<Pointer & { to?: Pointer[] }>) {
+      if (messageMatchesPointer(message, send)) channels.push(...resolveChannels(send.to));
+    }
+    for (const receive of ((receiver.data as any).receives || []) as Array<Pointer & { from?: Pointer[] }>) {
+      if (messageMatchesPointer(message, receive)) channels.push(...resolveChannels(receive.from));
+    }
+  }
+
+  const flows = catalog.flows.filter((flow) =>
+    ((flow.data.steps || []) as any[]).some((step) => {
+      const stepMessage = Array.isArray(step.message) ? step.message[0] : undefined;
+      return (
+        stepMessage?.collection === message.collection &&
+        stepMessage?.data.id === message.data.id &&
+        stepMessage?.data.version === message.data.version
+      );
+    })
+  );
+
+  return {
+    channels: uniqueResources(channels as CollectionEntry<'channels'>[]),
+    flows: uniqueResources(flows),
+    triggers: uniqueResources(
+      getTriggersOfMessage(catalog.receivers, message, catalog.messages).map((trigger) => trigger.message)
+    ),
+    triggeredBy: uniqueResources(
+      getTriggeredByOfMessage(catalog.receivers, message, catalog.messages).map((trigger) => trigger.message)
+    ),
+  };
+};

package/eventcatalog/src/utils/collections/message-triggers.ts

@@ -23,7 +23,8 @@ export interface MessageTrigger {
   condition?: string;
 }
 
-const messageMatchesPointer = (message: Message, pointer: { id: string; version?: string }) => {
+/** Whether a pointer points at the message; a pointer without a version (or `latest`) means the latest version. */
+export const messageMatchesPointer = (message: Message, pointer: { id: string; version?: string }) => {
   if (pointer.id !== message.data.id) return false;
 
   if (!pointer.version || pointer.version === 'latest') {

package/eventcatalog/src/utils/collections/resource-owners.ts

@@ -0,0 +1,193 @@
+import { getCollection, type CollectionEntry, type CollectionKey } from 'astro:content';
+import { getAdrs, getAdrsForResource } from './adrs';
+import { getChannelConnections, getChannels } from './channels';
+import { getCommands } from './commands';
+import { getDomains } from './domains';
+import { getEvents } from './events';
+import { getFlows, getFlowStepResources, getFlowsWithServiceStep } from './flows';
+import { getMessageConnections } from './message-connections';
+import { getQueries } from './queries';
+import { hasResources, type RelatedResources, type ResourceOwner, type ResourceOwnerCollection } from './resources';
+import { getServices } from './services';
+import { getSystems } from './systems';
+
+// Loads the owners of Resources pages (domains, systems, services, flows, channels and messages)
+// with the resources that point at them attached. Shared by the Resources pages, the sidebar's
+// Resources links and the old /architecture redirects, so all three agree on which owners have
+// a Resources page.
+
+export const RESOURCE_OWNER_COLLECTIONS: ResourceOwnerCollection[] = [
+  'domains',
+  'systems',
+  'services',
+  'flows',
+  'channels',
+  'events',
+  'commands',
+  'queries',
+];
+
+export const loadResourceOwners = async (type: ResourceOwnerCollection): Promise<ResourceOwner[]> => {
+  switch (type) {
+    case 'systems':
+      return getSystems();
+    case 'services':
+      return getServices();
+    case 'flows':
+      return getFlows();
+    case 'channels':
+      return getChannels();
+    case 'events':
+      return getEvents();
+    case 'commands':
+      return getCommands();
+    case 'queries':
+      return getQueries();
+    case 'domains':
+      return getDomains({ includeServicesInSubdomains: false });
+  }
+};
+
+const once = <T>(load: () => Promise<T>) => {
+  let loaded: Promise<T> | undefined;
+  return () => (loaded ??= load());
+};
+
+const isCurrentVersion = (entry: { data: { hidden?: boolean }; filePath?: string }) =>
+  entry.data.hidden !== true && !entry.filePath?.includes('versioned');
+
+// Owners come from their own collection's loader, so an owner of a type is that collection's entry.
+const asEntry = <C extends CollectionKey>(owner: ResourceOwner) => owner as unknown as CollectionEntry<C>;
+
+/**
+ * What the related-resource lookups read. Each part loads the first time it is needed and is
+ * then shared, so working out every owner of a type, or every type, reads the catalog once.
+ */
+export const createResourcesCatalog = () => {
+  const catalog = {
+    adrs: once(() => getAdrs({ getAllVersions: false })),
+    services: once(() => getServices()),
+    allFlows: once(() => getFlows()),
+    currentFlows: once(() => getFlows({ getAllVersions: false })),
+    rawChannels: once(() => getCollection('channels')),
+    rawMessages: once(async () => [
+      ...(await getCollection('events')),
+      ...(await getCollection('commands')),
+      ...(await getCollection('queries')),
+    ]),
+    messages: once(async () => [...(await getEvents()), ...(await getCommands()), ...(await getQueries())]),
+    // Raw entries keep the channel and trigger pointers on sends/receives that hydration drops.
+    // Like the sidebar, channels use the current services and agents and triggers use every version.
+    currentEndpoints: once(async () =>
+      [...(await getCollection('services')), ...(await getCollection('agents'))].filter(isCurrentVersion)
+    ),
+    receivers: once(async () => [
+      ...(await getCollection('services')),
+      ...(await getCollection('agents')),
+      ...(await getCollection('domains')),
+    ]),
+  };
+  return catalog;
+};
+
+export type ResourcesCatalog = ReturnType<typeof createResourcesCatalog>;
+
+type Relate = (owner: ResourceOwner) => RelatedResources;
+
+// Loads what a type's lookups need, then returns a function that works out one owner's related resources.
+const relatedResourcesFor = async (type: ResourceOwnerCollection, catalog: ResourcesCatalog): Promise<Relate> => {
+  const adrs = await catalog.adrs();
+  const adrsFor = (owner: ResourceOwner) => getAdrsForResource(asEntry<ResourceOwnerCollection>(owner), adrs);
+
+  switch (type) {
+    case 'services': {
+      const [flows, services] = await Promise.all([catalog.currentFlows(), catalog.services()]);
+      return (owner) => ({
+        adrs: adrsFor(owner),
+        stepFlows: getFlowsWithServiceStep(asEntry<'services'>(owner), flows, services),
+      });
+    }
+    case 'flows': {
+      const [services, flows] = await Promise.all([catalog.services(), catalog.allFlows()]);
+      return (owner) => ({
+        adrs: adrsFor(owner),
+        stepResources: getFlowStepResources(asEntry<'flows'>(owner), { services, flows }),
+      });
+    }
+    case 'channels': {
+      const [endpoints, channels, messages] = await Promise.all([
+        catalog.currentEndpoints(),
+        catalog.rawChannels(),
+        catalog.rawMessages(),
+      ]);
+      return (owner) => {
+        const {
+          producers,
+          consumers,
+          messages: channelMessages,
+        } = getChannelConnections(asEntry<'channels'>(owner), { endpoints, channels, messages });
+        return { adrs: adrsFor(owner), channelProducers: producers, channelConsumers: consumers, channelMessages };
+      };
+    }
+    case 'events':
+    case 'commands':
+    case 'queries': {
+      const [receivers, messages, channels, flows] = await Promise.all([
+        catalog.receivers(),
+        catalog.messages(),
+        catalog.rawChannels(),
+        catalog.currentFlows(),
+      ]);
+      return (owner) => {
+        const connections = getMessageConnections(asEntry<'events' | 'commands' | 'queries'>(owner), {
+          receivers,
+          messages,
+          channels,
+          flows,
+        });
+        return {
+          adrs: adrsFor(owner),
+          messageChannels: connections.channels,
+          messageFlows: connections.flows,
+          messageTriggers: connections.triggers,
+          messageTriggeredBy: connections.triggeredBy,
+        };
+      };
+    }
+    default:
+      return (owner) => ({ adrs: adrsFor(owner) });
+  }
+};
+
+/** Every owner of the type with a Resources page, with its related resources attached. */
+export const getOwnersWithResources = async (type: ResourceOwnerCollection, catalog = createResourcesCatalog()) => {
+  const [owners, relate] = await Promise.all([loadResourceOwners(type), relatedResourcesFor(type, catalog)]);
+  return owners.map((owner) => ({ ...owner, ...relate(owner) })).filter((owner) => hasResources(owner, type));
+};
+
+/** One owner with its related resources, or null when it does not exist or has no Resources page. Only that owner's lookups run. */
+export const findOwnerWithResources = async (
+  type: ResourceOwnerCollection,
+  id: string,
+  version: string,
+  catalog = createResourcesCatalog()
+): Promise<ResourceOwner | null> => {
+  const owner = (await loadResourceOwners(type)).find(
+    (candidate) => candidate.data.id === id && candidate.data.version === version
+  );
+  if (!owner) return null;
+  const withRelated = { ...owner, ...(await relatedResourcesFor(type, catalog))(owner) };
+  return hasResources(withRelated, type) ? withRelated : null;
+};
+
+/** `collection:id:version` of every owner with a Resources page, for links to those pages. */
+export const getResourcesPageKeys = async (catalog = createResourcesCatalog()) => {
+  const keys = new Set<string>();
+  // One type at a time; the shared catalog means each part is still read only once.
+  for (const type of RESOURCE_OWNER_COLLECTIONS) {
+    for (const owner of await getOwnersWithResources(type, catalog)) {
+      keys.add(`${type}:${owner.data.id}:${owner.data.version}`);
+    }
+  }
+  return keys;
+};