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

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;
+};

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

@@ -0,0 +1,310 @@
+import { collectionToResourceMap, resourceKey, uniqueResources } from '@utils/collections/util';
+
+// What the Resources pages show: which resources each owner (domain, system, service, flow,
+// channel or message) lists, how each relates to the owner, and the links for each row.
+// Loading owners and their related resources lives in ./resource-owners.
+
+/** The kinds of resource a Resources page can list. */
+export type ResourceCollection =
+  | 'domains'
+  | 'systems'
+  | 'agents'
+  | 'services'
+  | 'flows'
+  | 'entities'
+  | 'data-products'
+  | 'containers'
+  | 'events'
+  | 'commands'
+  | 'queries'
+  | 'channels'
+  | 'adrs';
+
+/** How a resource relates to the page's owner: which way a message flows, how a data store is used, or how it belongs to the owner. */
+export type ResourceRelationship =
+  | 'receives'
+  | 'sends'
+  | 'sends-and-receives'
+  | 'reads'
+  | 'writes'
+  | 'reads-and-writes'
+  | 'contains'
+  | 'owns'
+  | 'appears-in'
+  | 'governed-by'
+  | 'includes'
+  | 'transports'
+  | 'produces-messages'
+  | 'receives-messages'
+  | 'produces-and-receives-messages'
+  | 'produces'
+  | 'consumes'
+  | 'produces-and-consumes'
+  | 'triggers'
+  | 'triggered-by'
+  | 'triggers-and-triggered-by';
+
+/** Any catalog entry a Resources page reads: a collection entry, possibly hydrated with extra fields. */
+export type ResourceEntry = {
+  collection: string;
+  data: { id: string; version: string; name?: string; summary?: string; [key: string]: any };
+  [key: string]: any;
+};
+
+export type ResourceOwnerCollection = 'systems' | 'domains' | 'services' | 'flows' | 'channels' | MessageOwnerCollection;
+type MessageOwnerCollection = 'events' | 'commands' | 'queries';
+const isMessageOwner = (collection: ResourceOwnerCollection): collection is MessageOwnerCollection =>
+  collection === 'events' || collection === 'commands' || collection === 'queries';
+
+/** Resources that point at the owner, rather than being listed in the owner's own frontmatter. */
+export interface RelatedResources {
+  /** Decision records whose `appliesTo` includes the owner. */
+  adrs?: ResourceEntry[];
+  /** Flows with a step that points at the owner (services only). */
+  stepFlows?: ResourceEntry[];
+  /** The resources a flow's steps point at (flows only). */
+  stepResources?: ResourceEntry[];
+  /** Services and agents that send to the channel, those that receive from it, and the messages on it (channels only). */
+  channelProducers?: ResourceEntry[];
+  channelConsumers?: ResourceEntry[];
+  channelMessages?: ResourceEntry[];
+  /** The channels, flows and messages a message connects to (messages only; its producers and consumers are on `data`). */
+  messageChannels?: ResourceEntry[];
+  messageFlows?: ResourceEntry[];
+  messageTriggers?: ResourceEntry[];
+  messageTriggeredBy?: ResourceEntry[];
+}
+
+/** A resource owner as the Resources page receives it: the collection entry with its related resources attached. */
+export type ResourceOwner = ResourceEntry & RelatedResources;
+
+export interface ResourceGroup {
+  collection: ResourceCollection;
+  items: ResourceEntry[];
+}
+
+const getMessages = (data: any) =>
+  uniqueResources([...(data.sends || []), ...(data.receives || [])].filter((message) => message?.collection));
+
+const messageGroups = (messages: any[]): ResourceGroup[] => [
+  { collection: 'events', items: messages.filter((message) => message.collection === 'events') },
+  { collection: 'commands', items: messages.filter((message) => message.collection === 'commands') },
+  { collection: 'queries', items: messages.filter((message) => message.collection === 'queries') },
+];
+
+// The collections a flow step can point at, in the order the page groups them.
+const FLOW_STEP_COLLECTIONS: ResourceCollection[] = [
+  'services',
+  'agents',
+  'flows',
+  'containers',
+  'data-products',
+  'events',
+  'commands',
+  'queries',
+];
+
+export const getResourceGroups = (
+  data: any,
+  ownerCollection: ResourceOwnerCollection,
+  related: RelatedResources = {}
+): ResourceGroup[] => {
+  const adrGroup: ResourceGroup = { collection: 'adrs', items: related.adrs || [] };
+
+  // A message's resources are what produces or consumes it, the channels it travels on, the
+  // flows it appears in, and the messages it triggers or is triggered by.
+  if (isMessageOwner(ownerCollection)) {
+    const endpoints = uniqueResources([...(data.producers || []), ...(data.consumers || [])]);
+    const endpointGroup = (collection: ResourceCollection): ResourceGroup => ({
+      collection,
+      items: endpoints.filter((endpoint) => endpoint.collection === collection),
+    });
+    return [
+      endpointGroup('services'),
+      endpointGroup('agents'),
+      endpointGroup('data-products'),
+      { collection: 'channels', items: related.messageChannels || [] },
+      { collection: 'flows', items: related.messageFlows || [] },
+      ...messageGroups(uniqueResources([...(related.messageTriggers || []), ...(related.messageTriggeredBy || [])])),
+      adrGroup,
+    ];
+  }
+
+  // A channel's resources are the services and agents that send to or receive from it, and the messages on it.
+  if (ownerCollection === 'channels') {
+    const endpoints = uniqueResources([...(related.channelProducers || []), ...(related.channelConsumers || [])]);
+    return [
+      { collection: 'services', items: endpoints.filter((endpoint) => endpoint.collection === 'services') },
+      { collection: 'agents', items: endpoints.filter((endpoint) => endpoint.collection === 'agents') },
+      ...messageGroups(related.channelMessages || []),
+      adrGroup,
+    ];
+  }
+
+  // A flow's resources are what its steps point at.
+  if (ownerCollection === 'flows') {
+    const stepResources = related.stepResources || [];
+    return [
+      ...FLOW_STEP_COLLECTIONS.map((collection) => ({
+        collection,
+        items: stepResources.filter((resource) => resource.collection === collection),
+      })),
+      adrGroup,
+    ];
+  }
+
+  // A service's resources are what it uses: the messages it sends and receives, its
+  // entities, the data stores it reads from or writes to, and the flows it appears in.
+  if (ownerCollection === 'services') {
+    return [
+      { collection: 'flows', items: uniqueResources([...(data.flows || []), ...(related.stepFlows || [])]) },
+      { collection: 'entities', items: data.entities || [] },
+      { collection: 'containers', items: uniqueResources([...(data.writesTo || []), ...(data.readsFrom || [])]) },
+      ...messageGroups(getMessages(data)),
+      adrGroup,
+    ];
+  }
+
+  const domainOnlyGroups: ResourceGroup[] =
+    ownerCollection === 'domains'
+      ? [
+          { collection: 'domains', items: data.domains || [] },
+          { collection: 'systems', items: data.systems || [] },
+          { collection: 'agents', items: data.agents || [] },
+          { collection: 'data-products', items: data['data-products'] || [] },
+        ]
+      : [];
+
+  return [
+    ...domainOnlyGroups,
+    { collection: 'services', items: data.services || [] },
+    { collection: 'flows', items: data.flows || [] },
+    { collection: 'entities', items: data.entities || [] },
+    { collection: 'containers', items: data.containers || [] },
+    ...messageGroups(ownerCollection === 'domains' ? getMessages(data) : []),
+    adrGroup,
+  ];
+};
+
+// The page loader attaches the RelatedResources fields to the owner (see _index.data.ts).
+export const hasResources = (owner: any, ownerCollection: ResourceOwnerCollection): boolean =>
+  getResourceGroups(owner?.data ?? {}, ownerCollection, owner ?? {}).some(({ items }) => items.length > 0);
+
+const includesResource = (resources: any[] | undefined, item: any) =>
+  (resources || []).some((resource) => resource?.data && resourceKey(resource) === resourceKey(item));
+
+/**
+ * How a resource relates to the page's owner: which way a message flows, how a data store
+ * is used, or whether the owner contains, owns or appears in it.
+ */
+export const getResourceRelationship = (
+  data: any,
+  ownerCollection: ResourceOwnerCollection,
+  collection: ResourceCollection,
+  item: any,
+  related: RelatedResources = {}
+): ResourceRelationship | undefined => {
+  if (collection === 'adrs') return 'governed-by';
+  if (ownerCollection === 'flows') return 'includes';
+  if (isMessageOwner(ownerCollection)) {
+    if (collection === 'channels') return 'transports';
+    if (collection === 'flows') return 'appears-in';
+    if (collection === 'events' || collection === 'commands' || collection === 'queries') {
+      const triggers = includesResource(related.messageTriggers, item);
+      const triggeredBy = includesResource(related.messageTriggeredBy, item);
+      if (triggers && triggeredBy) return 'triggers-and-triggered-by';
+      if (triggers) return 'triggers';
+      if (triggeredBy) return 'triggered-by';
+      return undefined;
+    }
+    const produces = includesResource(data.producers, item);
+    const consumes = includesResource(data.consumers, item);
+    if (produces && consumes) return 'produces-and-consumes';
+    if (produces) return 'produces';
+    if (consumes) return 'consumes';
+    return undefined;
+  }
+  // A channel transports messages; services and agents produce messages onto it or receive them from it.
+  if (ownerCollection === 'channels') {
+    if (collection !== 'services' && collection !== 'agents') return 'transports';
+    const produces = includesResource(related.channelProducers, item);
+    const receives = includesResource(related.channelConsumers, item);
+    if (produces && receives) return 'produces-and-receives-messages';
+    if (produces) return 'produces-messages';
+    if (receives) return 'receives-messages';
+    return undefined;
+  }
+  if (collection === 'events' || collection === 'commands' || collection === 'queries') {
+    const sends = includesResource(data.sends, item);
+    const receives = includesResource(data.receives, item);
+    if (sends && receives) return 'sends-and-receives';
+    if (sends) return 'sends';
+    if (receives) return 'receives';
+    return undefined;
+  }
+  if (collection === 'entities') return 'owns';
+  if (ownerCollection === 'services') {
+    if (collection === 'flows') return 'appears-in';
+    if (collection === 'containers') {
+      const writes = includesResource(data.writesTo, item);
+      const reads = includesResource(data.readsFrom, item);
+      if (writes && reads) return 'reads-and-writes';
+      if (writes) return 'writes';
+      if (reads) return 'reads';
+    }
+    return undefined;
+  }
+  // Everything else on a domain or system page is part of it.
+  return 'contains';
+};
+
+/**
+ * The schema page for a resource, matching the sidebar's Schema link: messages with an entry
+ * in the schemas collection (keyed `collection:id:version`), and data products with an output
+ * contract. Undefined for everything else.
+ */
+export const getSchemaPath = (collection: ResourceCollection, item: any, schemaKeys: Set<string>) => {
+  const { id, version } = item.data;
+  if (collection === 'events' || collection === 'commands' || collection === 'queries') {
+    return schemaKeys.has(`${collection}:${id}:${version}`) ? `/schemas/${collection}/${id}/${version}` : undefined;
+  }
+  if (collection === 'data-products') {
+    const contract = (item.data.outputs || []).find((output: any) => output.contract)?.contract;
+    return contract ? `/schemas/data-products/${id}/${version}?contract=${encodeURIComponent(contract.path)}` : undefined;
+  }
+  return undefined;
+};
+
+export const getDocsPath = (collection: ResourceCollection, item: any) =>
+  `/docs/${collection}/${item.data.id}/${item.data.version}`;
+
+// Collections the visualiser has a page for (domains and systems through their own routes).
+// Entities and decision records have none.
+const VISUALISER_COLLECTIONS = new Set<ResourceCollection>([
+  'domains',
+  'systems',
+  'agents',
+  'services',
+  'flows',
+  'containers',
+  'channels',
+  'data-products',
+  'events',
+  'commands',
+  'queries',
+]);
+
+/** The resource's visualiser page, unless the visualiser is off, has no page for it, or the resource opts out. */
+export const getVisualiserPath = (collection: ResourceCollection, item: any, visualiserEnabled: boolean) => {
+  if (!visualiserEnabled || !VISUALISER_COLLECTIONS.has(collection) || item.data.visualiser === false) return undefined;
+  return `/visualiser/${collection}/${item.data.id}/${item.data.version}`;
+};
+
+/** Same key and badge as the favorite button on the resource's docs page. */
+export const getFavorite = (collection: ResourceCollection, item: any) => {
+  const resourceType = collectionToResourceMap[collection];
+  return {
+    nodeKey: `${resourceType}:${item.data.id}:${item.data.version}`,
+    badge: resourceType.charAt(0).toUpperCase() + resourceType.slice(1),
+  };
+};

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

@@ -291,6 +291,37 @@ export const createVersionedMap = <T extends { data: { id: string; version?: str
   return map;
 };
 
+const versionedMapCache = new WeakMap<object, Map<string, any[]>>();
+
+/**
+ * createVersionedMap, built once per list. Use it in helpers that search the same list once per
+ * resource, so a catalog-wide pass does not rebuild the map every time.
+ */
+export const getVersionedMap = <T extends { data: { id: string; version?: string } }>(items: T[]): Map<string, T[]> => {
+  let map = versionedMapCache.get(items);
+  if (!map) {
+    map = createVersionedMap(items);
+    versionedMapCache.set(items, map);
+  }
+  return map as Map<string, T[]>;
+};
+
+type KeyedResource = { collection: string; data: { id: string; version?: string } };
+
+/** Identifies a resource across collections: a service and an agent can share an id and version. */
+export const resourceKey = (resource: KeyedResource) => `${resource.collection}:${resource.data.id}:${resource.data.version}`;
+
+/** The resources without repeats (by collection, id and version), keeping the first of each in order. */
+export const uniqueResources = <T extends KeyedResource>(resources: T[]): T[] => {
+  const seen = new Map<string, T>();
+  for (const resource of resources) {
+    if (!resource?.data?.id) continue;
+    const key = resourceKey(resource);
+    if (!seen.has(key)) seen.set(key, resource);
+  }
+  return [...seen.values()];
+};
+
 // Merge as many given maps as you want
 export const mergeMaps = <T>(...maps: Map<string, T[]>[]): Map<string, T[]> => {
   return maps.reduce((acc, map) => {

package/package.json

@@ -7,7 +7,7 @@
   },
   "license": "BUSL-1.1",
   "type": "module",
-  "version": "5.0.0-beta.2",
+  "version": "5.0.0-beta.3",
   "publishConfig": {
     "access": "public"
   },
@@ -54,7 +54,7 @@
     "@astrojs/rss": "^4.0.19",
     "@asyncapi/avro-schema-parser": "3.0.24",
     "@asyncapi/parser": "^3.6.0",
-    "@asyncapi/react-component": "3.1.0",
+    "@asyncapi/react-component": "3.2.1",
     "@auth/core": "^0.41.3",
     "@eventcatalog/license": "^0.0.9",
     "@fontsource/inter": "^5.2.5",
@@ -111,8 +111,8 @@
     "parse5": "^7.3.0",
     "picocolors": "^1.1.1",
     "picomatch": "^4.0.4",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
     "react-markdown": "^10.1.0",
     "react-syntax-highlighter": "^16.1.1",
     "recast": "^0.23.11",
@@ -135,8 +135,8 @@
     "uuid": "^11.1.1",
     "zod": "^4.3.6",
     "@eventcatalog/linter": "1.2.0-beta.0",
-    "@eventcatalog/visualiser": "^5.0.0-beta.1",
-    "@eventcatalog/sdk": "2.30.0-beta.0"
+    "@eventcatalog/sdk": "2.30.0-beta.0",
+    "@eventcatalog/visualiser": "^5.0.0-beta.2"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.10",