@eventcatalog/core 5.0.0-beta.8 → 5.0.0

package/dist/utils/license-status.d.cts

@@ -17,8 +17,8 @@ declare const getLicenseAnalytics: (license?: LicenseStatus, tsd?: unknown) => {
 };
 type Row = [label: string, value: string];
 /**
- * What the license box says: a headline, the facts as aligned rows ("Licensed to  acme"), and links on their own
- * rows, so it can be read at a glance. `text` is the box's content without colours.
+ * What the license box says: a headline, the facts as aligned rows ("Licensed to  acme"), links on their own
+ * rows, and an optional note at the end, so it can be read at a glance. `text` is the box's content without colours.
  */
 type LicenseStatusMessage = {
     title: string;
@@ -26,6 +26,7 @@ type LicenseStatusMessage = {
     headline: string;
     rows: Row[];
     links: Row[];
+    note?: string[];
     text: string;
 };
 /**

package/dist/utils/license-status.d.ts

@@ -17,8 +17,8 @@ declare const getLicenseAnalytics: (license?: LicenseStatus, tsd?: unknown) => {
 };
 type Row = [label: string, value: string];
 /**
- * What the license box says: a headline, the facts as aligned rows ("Licensed to  acme"), and links on their own
- * rows, so it can be read at a glance. `text` is the box's content without colours.
+ * What the license box says: a headline, the facts as aligned rows ("Licensed to  acme"), links on their own
+ * rows, and an optional note at the end, so it can be read at a glance. `text` is the box's content without colours.
  */
 type LicenseStatusMessage = {
     title: string;
@@ -26,6 +26,7 @@ type LicenseStatusMessage = {
     headline: string;
     rows: Row[];
     links: Row[];
+    note?: string[];
     text: string;
 };
 /**

package/dist/utils/license-status.js

@@ -3,7 +3,7 @@ import {
   getLicenseStatus,
   getLicenseStatusMessage,
   printLicenseStatus
-} from "../chunk-AWOO63ME.js";
+} from "../chunk-AD7CL772.js";
 export {
   getLicenseAnalytics,
   getLicenseStatus,

package/eventcatalog/astro.config.mjs

@@ -27,6 +27,7 @@ import expressiveCode from 'astro-expressive-code';
 // preprocessors and the rehype plugin below load those same package defaults.
 import expressiveCodeConfig from './ec.config.mjs';
 import ecstudioWatcher from './integrations/ecstudio-watcher.mjs';
+import storage from './integrations/storage.mjs';
 import studioServer from './integrations/studio-server.mjs';
 import eventCatalogIntegration from './src/features/integrations/eventcatalog-features.ts';
 import eventCatalogRuntime, { getDevServerFileSystem, packageDirectory } from './integrations/eventcatalog-runtime.mjs';
@@ -34,6 +35,8 @@ import config from './src/utils/eventcatalog-config/source.ts';
 import preprocessExpressiveCodeConfig from './integrations/expressive-code-config.mjs';
 import catalogAssets from './integrations/catalog-assets.mjs';
 import runtimeDependencies from './integrations/runtime-dependencies.mjs';
+import stableDependencyOrder from './integrations/stable-dependency-order.mjs';
+import skipStartupReload from './integrations/skip-startup-reload.mjs';
 import { getRuntimePaths } from './integrations/runtime-paths.mjs';
 import { collectClientDependencies } from './integrations/client-dependencies.mjs';
 
@@ -114,6 +117,11 @@ export default defineConfig({
 
   // just turn this off for all users (for now...)
   devToolbar: { enabled: false },
+  build: {
+    // Render several pages at once: pages wait on file reads and graph layouts, and a 640-event
+    // catalog built in ~40s rather than ~70s, with the same pages and less memory.
+    concurrency: 4,
+  },
 
   // Unused resource types are valid. Astro otherwise warns on every getCollection()
   // call for those empty collections ("check your content config file for errors").
@@ -140,6 +148,8 @@ export default defineConfig({
     catalogAssets({ projectDirectory, generatedDirectory: join(runtimeDirectory, 'public') }),
     effectiveOutput !== 'server' && compress && (await loadAstroCompressIntegration(projectDirectory)),
     ecstudioWatcher(),
+    // Before Studio: its database is opened and migrated first
+    storage(),
     studioServer(),
     eventCatalogIntegration(),
     linkValidation(config.linkValidation),
@@ -163,6 +173,8 @@ export default defineConfig({
     },
     plugins: [
       runtimeDependencies(),
+      stableDependencyOrder(),
+      skipStartupReload(),
       tailwindcss(),
       ...(await eventCatalogLikeC4(projectDirectory)),
       ...(config.trailingSlash === true ? [astroTrailingSlashEndpointFix()] : []),
@@ -221,7 +233,15 @@ export default defineConfig({
     },
     optimizeDeps: {
       exclude: [],
-      include: collectClientDependencies(),
+      include: [
+        ...collectClientDependencies(),
+        // <ClientRouter /> imports these from a virtual module the dependency scan can't follow,
+        // so without them every cold start re-bundles on the first page and reloads it
+        'astro/virtual-modules/transitions-events.js',
+        'astro/virtual-modules/transitions-router.js',
+        'astro/virtual-modules/transitions-swap-functions.js',
+        'astro/virtual-modules/transitions-types.js',
+      ],
     },
   },
 });

package/eventcatalog/integrations/config-loader.mjs

@@ -1,8 +1,8 @@
-import { readFile, rm, copyFile, mkdtemp, symlink } from 'node:fs/promises';
+import { readFile, rm } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { tmpdir } from 'node:os';
+import { register } from 'node:module';
 
 export async function cleanup(projectDirectory) {
   const filePath = path.join(projectDirectory, 'eventcatalog.config.mjs');
@@ -11,75 +11,73 @@ export async function cleanup(projectDirectory) {
   }
 }
 
-const findNodeModulesDirectory = (directory) => {
-  let currentDirectory = directory;
-
-  while (true) {
-    const nodeModulesDirectory = path.join(currentDirectory, 'node_modules');
-
-    if (existsSync(nodeModulesDirectory)) {
-      return nodeModulesDirectory;
-    }
-
-    const parentDirectory = path.dirname(currentDirectory);
-
-    if (parentDirectory === currentDirectory) {
-      return undefined;
-    }
-
-    currentDirectory = parentDirectory;
-  }
+let hidesConfigModuleTypeWarning = false;
+let loads = 0;
+
+/**
+ * Node loads an eventcatalog.config.js that uses import/export as an ES module even when the catalog's
+ * package.json has no "type": "module" (a new catalog's doesn't), and warns that it had to detect it.
+ * That warning, for the config file only, is hidden: the catalog doesn't need to change anything.
+ */
+const hideConfigModuleTypeWarning = () => {
+  if (hidesConfigModuleTypeWarning) return;
+  hidesConfigModuleTypeWarning = true;
+
+  const emitWarning = process.emitWarning;
+  process.emitWarning = function (warning, ...args) {
+    const code = typeof args[0] === 'object' ? args[0]?.code : args[1];
+    const message = typeof warning === 'string' ? warning : warning?.message;
+    if (code === 'MODULE_TYPELESS_PACKAGE_JSON' && message?.includes('eventcatalog.config.js')) return;
+    return emitWarning.call(this, warning, ...args);
+  };
 };
 
-const linkNodeModulesIntoTempDirectory = async ({ projectDirectory, tempDir }) => {
-  const nodeModulesDirectory = findNodeModulesDirectory(projectDirectory);
-
-  if (!nodeModulesDirectory) {
-    return;
-  }
-
-  await symlink(nodeModulesDirectory, path.join(tempDir, 'node_modules'), 'dir');
+// Marks a config URL Node should load as an ES module, whatever the catalog's package.json says
+const AS_MODULE_QUERY = 'eventcatalog-config-as-module';
+let loadsMarkedConfigsAsModules = false;
+
+/**
+ * Node won't load a config written with import/export in a catalog whose package.json has
+ * "type": "commonjs". A loader hook loads that config file (and only it) as an ES module.
+ */
+const loadMarkedConfigsAsModules = () => {
+  if (loadsMarkedConfigsAsModules) return;
+  loadsMarkedConfigsAsModules = true;
+  const hook = `export async function load(url, context, nextLoad) {
+    return nextLoad(url, url.includes('${AS_MODULE_QUERY}=') ? { ...context, format: 'module' } : context);
+  }`;
+  register(`data:text/javascript,${encodeURIComponent(hook)}`);
 };
 
-const createTemporaryConfigDirectory = async (projectDirectory) => {
-  const nodeModulesDirectory = findNodeModulesDirectory(projectDirectory);
-
-  if (nodeModulesDirectory) {
-    return mkdtemp(path.join(nodeModulesDirectory, '.eventcatalog-config-'));
+/**
+ * Loads the catalog's eventcatalog.config.js from where it is, so paths it builds from its own location
+ * (`import.meta.url`, `import.meta.dirname`) and its relative imports point into the catalog. It was
+ * loaded from a copy in a temporary folder before, which broke them (e.g. the paths to a generator's specs).
+ */
+const isCommonJSPackage = async (projectDirectory) => {
+  try {
+    const packageJson = JSON.parse(await readFile(path.join(projectDirectory, 'package.json'), 'utf-8'));
+    return packageJson?.type === 'commonjs';
+  } catch {
+    return false;
   }
-
-  const tempDir = await mkdtemp(path.join(tmpdir(), 'eventcatalog-config-'));
-  await linkNodeModulesIntoTempDirectory({ projectDirectory, tempDir });
-  return tempDir;
 };
 
 export const getEventCatalogConfigFile = async (projectDirectory) => {
-  let tempDir;
-
   try {
-    let configFilePath = path.join(projectDirectory, 'eventcatalog.config.js');
-
-    const filePath = path.join(projectDirectory, 'package.json');
-    const packageJson = JSON.parse(await readFile(filePath, 'utf-8'));
+    hideConfigModuleTypeWarning();
+    // A catalog's config is an ES module, as it always was (with "type": "commonjs" it was loaded from an .mjs copy)
+    const asModule = await isCommonJSPackage(projectDirectory);
+    if (asModule) loadMarkedConfigsAsModules();
 
-    if (packageJson?.type !== 'module') {
-      // Importing CommonJS config via ESM import requires an .mjs file.
-      // Keep this temp copy outside the project directory so Astro/Vite
-      // file watchers do not trigger a dev-server restart during startup.
-      tempDir = await createTemporaryConfigDirectory(projectDirectory);
-      configFilePath = path.join(tempDir, 'eventcatalog.config.mjs');
-      await copyFile(path.join(projectDirectory, 'eventcatalog.config.js'), configFilePath);
-    }
-
-    const configFileURL = `${pathToFileURL(configFilePath).href}?t=${Date.now()}`;
-    const config = await import(/* @vite-ignore */ configFileURL);
+    const configFileURL = pathToFileURL(path.join(projectDirectory, 'eventcatalog.config.js')).href;
+    // A new URL each time, so a changed config is loaded again (not `?t=`: Vite drops it as its own timestamp)
+    const query = `${asModule ? AS_MODULE_QUERY : 'loaded'}=${Date.now()}-${loads++}`;
+    const config = await import(/* @vite-ignore */ `${configFileURL}?${query}`);
 
     return config.default;
   } finally {
+    // Earlier versions loaded a copy from eventcatalog.config.mjs in the catalog: remove one left behind
     await cleanup(projectDirectory);
-
-    if (tempDir) {
-      await rm(tempDir, { recursive: true, force: true });
-    }
   }
 };

package/eventcatalog/integrations/skip-startup-reload.mjs

@@ -0,0 +1,31 @@
+// Astro writes its content data store as the dev server starts, which sends the browser a
+// full reload. With no browser connected yet, Vite holds that reload and hands it to the
+// first page that connects, so the first page opened after every start loaded twice.
+// A reload sent before any page has been served has nothing to refresh (a tab left open
+// from the previous run reloads itself when it reconnects), so drop those. Once a page has
+// been requested, reloads pass through as usual.
+
+const isFullReload = (payload) => typeof payload === 'object' && payload?.type === 'full-reload';
+
+export default function skipStartupReload() {
+  return {
+    name: 'eventcatalog:skip-startup-reload',
+    apply: 'serve',
+    configureServer(server) {
+      let pageRequested = false;
+      server.middlewares.use((req, _res, next) => {
+        // Browser navigations ask for HTML; the CLI's prewarm request doesn't
+        if (!pageRequested && req.headers.accept?.includes('text/html')) pageRequested = true;
+        next();
+      });
+
+      for (const channel of new Set([server.ws, server.environments?.client?.hot].filter(Boolean))) {
+        const send = channel.send.bind(channel);
+        channel.send = (...args) => {
+          if (!pageRequested && isFullReload(args[0])) return;
+          return send(...args);
+        };
+      }
+    },
+  };
+}

package/eventcatalog/integrations/stable-dependency-order.mjs

@@ -0,0 +1,29 @@
+// Astro crawls framework packages with vitefu, which looks them up concurrently and lists
+// each one in `resolve.external` / `resolve.noExternal` as its lookup finishes, so the
+// order changes from one start to the next. Vite hashes these lists unsorted to decide
+// whether its pre-bundled dependencies are still valid, so every `eventcatalog dev` saw a
+// "changed" config and re-bundled all of them. Only membership matters in these lists, so
+// sorting them keeps the hash (and the dependency cache) stable across starts.
+
+const byName = (a, b) => {
+  const left = String(a);
+  const right = String(b);
+  return left < right ? -1 : left > right ? 1 : 0;
+};
+
+const sortResolveLists = (resolve) => {
+  if (Array.isArray(resolve?.external)) resolve.external.sort(byName);
+  if (Array.isArray(resolve?.noExternal)) resolve.noExternal.sort(byName);
+};
+
+export default function stableDependencyOrder() {
+  return {
+    name: 'eventcatalog:stable-dependency-order',
+    apply: 'serve',
+    configResolved(config) {
+      sortResolveLists(config.resolve);
+      sortResolveLists(config.ssr);
+      for (const environment of Object.values(config.environments ?? {})) sortResolveLists(environment.resolve);
+    },
+  };
+}

package/eventcatalog/integrations/storage.mjs

@@ -0,0 +1,20 @@
+import { startStorage } from '../src/features/storage/database.ts';
+
+// The state EventCatalog keeps (`storage` in eventcatalog.config.js): as the dev server starts, its database is opened
+// and brought up to date (migrated), whether or not a feature that uses it is opened. `eventcatalog start` does the
+// same through /_eventcatalog/start.
+export default function storage() {
+  return {
+    name: 'eventcatalog-storage',
+    hooks: {
+      'astro:server:setup': async ({ logger }) => {
+        try {
+          const file = await startStorage();
+          if (file) logger.info(`Database ready (${file})`);
+        } catch (error) {
+          logger.error(`Could not open the database: ${error.message}`);
+        }
+      },
+    },
+  };
+}

package/eventcatalog/integrations/studio-server.mjs

@@ -1,4 +1,5 @@
 import { getStudioRuntime } from '../src/features/studio/server/runtime.ts';
+import { isDatabaseTooNew } from '../src/features/storage/migrations.ts';
 import config from '../src/utils/eventcatalog-config/source.ts';
 import { isCanvasEnabled } from '../src/utils/feature.ts';
 
@@ -14,8 +15,10 @@ export default function studioServer() {
         const projectDirectory = process.env.PROJECT_DIR || process.cwd();
         // Canvases are loaded from storage before anyone can open one
         try {
-          await runtime.useStorage(config.studio?.storage, projectDirectory);
+          await runtime.useStorage(config.storage, projectDirectory);
         } catch (error) {
+          // Not kept in memory instead (changes would quietly stop being saved): Studio's pages say why
+          if (isDatabaseTooNew(error)) return logger.error(`Studio isn't available: ${error.message}`);
           logger.error(`Could not use the Studio storage configured, keeping canvases in memory: ${error.message}`);
           await runtime.useStorage({ type: 'memory' }, projectDirectory);
         }

package/eventcatalog/src/components/CatalogGraph/CatalogForceGraph.tsx

@@ -170,6 +170,16 @@ const nodeRadius = (degree: number, isHub = false) =>
 /** Above this node count, expensive extras (collision force) are disabled. */
 const LARGE_GRAPH_NODE_COUNT = 1500;
 
+/**
+ * The first layout settles before it paints instead of animating into place for ~5s: ticks
+ * run in short slices across frames (no long tasks) until it settles, ~40ms of work for 100
+ * nodes. Big catalogs stop once ticking has taken the work limit, paint past their largest
+ * moves and animate the rest. The limit counts ticking time, not elapsed time, so a page busy
+ * hydrating other islands doesn't cut the settle short.
+ */
+const INITIAL_SETTLE_SLICE_MS = 12;
+const INITIAL_SETTLE_WORK_LIMIT_MS = 400;
+
 /** Sprite resolution for node icons (drawn scaled-down, so keep it crisp) */
 const ICON_SPRITE_SIZE = 64;
 
@@ -617,6 +627,10 @@ const CatalogForceGraph = ({
     // normal-sized, whatever the lens's usual hubs are
     const isHub = (d: SimNode) => (focusKey ? d.key === focusKey : hubs.has(d.collection));
 
+    // Later layouts (lens, focus and filter changes) animate from the previous positions
+    const isFirstLayout = positionsRef.current.size === 0;
+    // Nothing paints until the first layout has settled (see INITIAL_SETTLE_SLICE_MS)
+    let settling = isFirstLayout;
     const visibleNodes: SimNode[] = viewNodes
       .filter((n) => !hiddenCollections.has(n.collection))
       .map((n) => ({ ...n, degree: 0, ...positionsRef.current.get(n.key) }));
@@ -734,6 +748,7 @@ const CatalogForceGraph = ({
     };
 
     const draw = () => {
+      if (settling) return;
       context.save();
       context.setTransform(devicePixelRatio, 0, 0, devicePixelRatio, 0, 0);
       context.clearRect(0, 0, width, height);
@@ -1014,6 +1029,29 @@ const CatalogForceGraph = ({
       );
     }
 
+    // Settle the first layout before it paints rather than animating it into place
+    let settleFrame: number | undefined;
+    if (isFirstLayout) {
+      simulation.stop();
+      let workLeft = INITIAL_SETTLE_WORK_LIMIT_MS;
+      const settle = () => {
+        const sliceStart = performance.now();
+        const sliceEnd = sliceStart + Math.min(INITIAL_SETTLE_SLICE_MS, workLeft);
+        while (simulation.alpha() > simulation.alphaMin() && performance.now() < sliceEnd) simulation.tick();
+        workLeft -= performance.now() - sliceStart;
+        if (simulation.alpha() > simulation.alphaMin() && workLeft > 0) {
+          settleFrame = requestAnimationFrame(settle);
+          return;
+        }
+        settling = false;
+        // Settled: paint it as is (restarting would run one tick more than the animated
+        // layout). Otherwise paint and animate whatever is left.
+        if (simulation.alpha() <= simulation.alphaMin()) fitToView();
+        else simulation.restart();
+      };
+      settleFrame = requestAnimationFrame(settle);
+    }
+
     const findNode = (canvasX: number, canvasY: number): SimNode | null => {
       if (Number.isNaN(canvasX) || Number.isNaN(canvasY)) return null;
       const x = transform.invertX(canvasX);
@@ -1219,6 +1257,7 @@ const CatalogForceGraph = ({
       for (const node of visibleNodes) {
         if (node.x !== undefined && node.y !== undefined) positionsRef.current.set(node.key, { x: node.x, y: node.y });
       }
+      if (settleFrame !== undefined) cancelAnimationFrame(settleFrame);
       simulation.stop();
       // The tooltip outlives this effect — never leave it showing stale content
       tooltip.style.opacity = '0';

package/eventcatalog/src/components/ChatPanel/ChatPanel.tsx

@@ -29,6 +29,8 @@ const CHAT_PANEL_STYLES = `
   }
   .ec-chat-surface { font-weight: 400; }
   .ec-chat-avatar { background: rgb(var(--ec-accent) / .06); animation: ec-chat-breathe 5s ease-in-out infinite; }
+  /* The closed panel stays on the page (off screen): a running animation there still costs every frame */
+  .ec-chat-surface[aria-hidden='true'] .ec-chat-avatar { animation-play-state: paused; }
   .ec-chat-suggestion { width: fit-content; max-width: 100%; transition: background 180ms, transform 180ms; }
   .ec-chat-suggestion:hover { transform: translateX(3px); }
   .ec-chat-message { animation: fadeInUp 280ms ease-out both; }