@gomessaging/messaging 0.0.1

package/src/validate.ts

@@ -0,0 +1,183 @@
+// MIT License
+// Copyright (c) 2026 sparetimecoders
+
+import type { Endpoint, Topology, Transport } from "./types.js";
+
+/**
+ * Validate checks a single service's topology for internal consistency.
+ * Returns null if valid, or an error message string if invalid.
+ */
+export function validate(t: Topology): string | null {
+  if (!t.serviceName) {
+    return "service name must not be empty";
+  }
+
+  const errs: string[] = [];
+
+  for (let i = 0; i < (t.endpoints ?? []).length; i++) {
+    const ep = t.endpoints[i];
+
+    if (!ep.exchangeName) {
+      errs.push(`endpoint[${i}]: exchange name must not be empty`);
+    }
+
+    if (ep.direction === "consume" && !ep.queueName && !ep.ephemeral) {
+      errs.push(
+        `endpoint[${i}]: consume endpoint must have a queue name`,
+      );
+    }
+
+    if (!ep.routingKey && ep.exchangeKind !== "headers") {
+      errs.push(
+        `endpoint[${i}]: routing key must not be empty for ${ep.exchangeKind} exchange`,
+      );
+    }
+
+    if (ep.routingKey && ep.routingKey.includes(">")) {
+      errs.push(
+        `endpoint[${i}]: routing key must not contain '>' (use '#' for multi-level wildcard)`,
+      );
+    }
+
+    const transportErr = validateExchangeNameForTransport(
+      t.transport,
+      ep,
+      i,
+    );
+    if (transportErr) {
+      errs.push(transportErr);
+    }
+  }
+
+  return errs.length > 0 ? errs.join("\n") : null;
+}
+
+function validateExchangeNameForTransport(
+  transport: Transport | undefined,
+  ep: Endpoint,
+  index: number,
+): string | null {
+  switch (transport) {
+    case "amqp":
+      return validateAMQPExchangeName(ep, index);
+    case "nats":
+      return validateNATSExchangeName(ep, index);
+    default:
+      return null;
+  }
+}
+
+function validateAMQPExchangeName(
+  ep: Endpoint,
+  index: number,
+): string | null {
+  const name = ep.exchangeName;
+  switch (ep.exchangeKind) {
+    case "topic":
+      if (!name.endsWith(".topic.exchange")) {
+        return `endpoint[${index}]: topic exchange "${name}" must end with .topic.exchange`;
+      }
+      break;
+    case "direct":
+      if (!name.endsWith(".direct.exchange.request")) {
+        return `endpoint[${index}]: direct exchange "${name}" must end with .direct.exchange.request`;
+      }
+      break;
+    case "headers":
+      if (!name.endsWith(".headers.exchange.response")) {
+        return `endpoint[${index}]: headers exchange "${name}" must end with .headers.exchange.response`;
+      }
+      break;
+  }
+  return null;
+}
+
+function validateNATSExchangeName(
+  ep: Endpoint,
+  index: number,
+): string | null {
+  const name = ep.exchangeName;
+  const amqpSuffixes = [
+    ".topic.exchange",
+    ".direct.exchange.request",
+    ".headers.exchange.response",
+  ];
+  for (const suffix of amqpSuffixes) {
+    if (name.endsWith(suffix)) {
+      return `endpoint[${index}]: NATS exchange "${name}" must not use AMQP suffix "${suffix}"`;
+    }
+  }
+  if (/[\s]/.test(name)) {
+    return `endpoint[${index}]: NATS exchange "${name}" must not contain whitespace`;
+  }
+  return null;
+}
+
+/**
+ * ValidateTopologies checks cross-service consistency across multiple topologies.
+ * Returns null if valid, or an error message string if invalid.
+ */
+export function validateTopologies(topologies: Topology[]): string | null {
+  const errs: string[] = [];
+
+  for (const t of topologies) {
+    const err = validate(t);
+    if (err) {
+      errs.push(`service "${t.serviceName}": ${err}`);
+    }
+  }
+
+  // Group topologies by transport for cross-validation.
+  const groups = new Map<string, Topology[]>();
+  for (const t of topologies) {
+    const key = t.transport ?? "";
+    const group = groups.get(key) ?? [];
+    group.push(t);
+    groups.set(key, group);
+  }
+
+  for (const group of groups.values()) {
+    const err = crossValidateGroup(group);
+    if (err) {
+      errs.push(err);
+    }
+  }
+
+  return errs.length > 0 ? errs.join("\n") : null;
+}
+
+function crossValidateGroup(topologies: Topology[]): string | null {
+  const errs: string[] = [];
+
+  // Build a set of all published routing keys per exchange.
+  const published = new Map<string, string>(); // "exchange|routingKey" -> service name
+  for (const t of topologies) {
+    for (const ep of t.endpoints ?? []) {
+      if (ep.direction === "publish" && ep.routingKey) {
+        published.set(
+          `${ep.exchangeName}|${ep.routingKey}`,
+          t.serviceName,
+        );
+      }
+    }
+  }
+
+  // Check that each consumer has a matching publisher.
+  for (const t of topologies) {
+    for (const ep of t.endpoints ?? []) {
+      if (ep.direction !== "consume") continue;
+      if (!ep.routingKey) continue;
+      // Skip wildcard consumers.
+      if (/[#*>]/.test(ep.routingKey)) continue;
+
+      const key = `${ep.exchangeName}|${ep.routingKey}`;
+      if (!published.has(key)) {
+        errs.push(
+          `service "${t.serviceName}" consumes "${ep.routingKey}" on exchange "${ep.exchangeName}" but no service publishes it`,
+        );
+      }
+    }
+  }
+
+  return errs.length > 0 ? errs.join("\n") : null;
+}

package/src/visualize.ts

@@ -0,0 +1,167 @@
+// MIT License
+// Copyright (c) 2026 sparetimecoders
+
+import type { ExchangeKind, Topology } from "./types.js";
+
+interface ExchangeEntry {
+  kind: ExchangeKind;
+  transport: string;
+}
+
+interface Edge {
+  from: string;
+  to: string;
+  label: string;
+  style: string; // "-->" or "-.->"
+  transport: string;
+}
+
+function sanitizeID(name: string): string {
+  return name.replace(/[^a-zA-Z0-9_]/g, "_");
+}
+
+function exchangeNode(
+  id: string,
+  name: string,
+  kind: ExchangeKind,
+  indent: string,
+): string {
+  switch (kind) {
+    case "topic":
+      return `${indent}${id}{{"${name}"}}\n`;
+    case "headers":
+      return `${indent}${id}(("${name}"))\n`;
+    case "direct":
+    default:
+      return `${indent}${id}["${name}"]\n`;
+  }
+}
+
+/**
+ * Generates a Mermaid flowchart diagram from one or more topologies.
+ * The diagram shows services as rectangle nodes, exchanges as shaped nodes
+ * (based on exchange kind), and edges for publish/consume relationships.
+ * When topologies use multiple transports, exchanges are grouped into
+ * subgraphs by transport (e.g. AMQP, NATS).
+ */
+export function mermaid(topologies: Topology[]): string {
+  const services = new Set<string>();
+  const exchanges = new Map<string, ExchangeEntry>();
+  const edges: Edge[] = [];
+  const transports = new Set<string>();
+
+  for (const t of topologies) {
+    if (!t.serviceName) continue;
+    services.add(t.serviceName);
+    if (t.transport) {
+      transports.add(t.transport);
+    }
+
+    for (const ep of t.endpoints) {
+      if (!ep.exchangeName) continue;
+      exchanges.set(ep.exchangeName, {
+        kind: ep.exchangeKind,
+        transport: t.transport ?? "",
+      });
+
+      const arrow = ep.pattern === "service-response" ? "-.->" : "-->";
+
+      if (ep.direction === "publish") {
+        edges.push({
+          from: t.serviceName,
+          to: ep.exchangeName,
+          label: ep.routingKey ?? "",
+          style: arrow,
+          transport: t.transport ?? "",
+        });
+      } else if (ep.direction === "consume") {
+        edges.push({
+          from: ep.exchangeName,
+          to: t.serviceName,
+          label: ep.routingKey ?? "",
+          style: arrow,
+          transport: t.transport ?? "",
+        });
+      }
+    }
+  }
+
+  const useSubgraphs = transports.size > 1;
+
+  const exchID = (transport: string, name: string): string => {
+    if (useSubgraphs) {
+      return sanitizeID(`${transport}_${name}`);
+    }
+    return sanitizeID(name);
+  };
+
+  let out = "graph LR\n";
+
+  // Service nodes (sorted)
+  const sortedServices = [...services].sort();
+  for (const svc of sortedServices) {
+    out += `    ${sanitizeID(svc)}["${svc}"]\n`;
+  }
+
+  const sortedExchangeNames = [...exchanges.keys()].sort();
+
+  if (useSubgraphs) {
+    // Group exchanges by transport into subgraphs
+    const sortedTransports = [...transports].sort();
+    for (const tr of sortedTransports) {
+      out += `    subgraph ${tr.toUpperCase()}\n`;
+      for (const name of sortedExchangeNames) {
+        const entry = exchanges.get(name)!;
+        if (entry.transport !== tr) continue;
+        out += exchangeNode(exchID(tr, name), name, entry.kind, "        ");
+      }
+      out += "    end\n";
+    }
+  } else {
+    // Single transport or no transport — flat list (backward compatible)
+    for (const name of sortedExchangeNames) {
+      const entry = exchanges.get(name)!;
+      out += exchangeNode(
+        exchID(entry.transport, name),
+        name,
+        entry.kind,
+        "    ",
+      );
+    }
+  }
+
+  // Edges (sorted by from/to/label for deterministic output)
+  edges.sort((a, b) => {
+    if (a.from !== b.from) return a.from < b.from ? -1 : 1;
+    if (a.to !== b.to) return a.to < b.to ? -1 : 1;
+    return a.label < b.label ? -1 : a.label > b.label ? 1 : 0;
+  });
+
+  for (const e of edges) {
+    const fromID = services.has(e.from)
+      ? sanitizeID(e.from)
+      : exchID(e.transport, e.from);
+    const toID = services.has(e.to)
+      ? sanitizeID(e.to)
+      : exchID(e.transport, e.to);
+    if (e.label) {
+      out += `    ${fromID} ${e.style}|"${e.label}"| ${toID}\n`;
+    } else {
+      out += `    ${fromID} ${e.style} ${toID}\n`;
+    }
+  }
+
+  // Style declarations
+  if (sortedServices.length > 0) {
+    const ids = sortedServices.map(sanitizeID).join(",");
+    out += `    style ${ids} fill:#f9f,stroke:#333\n`;
+  }
+  if (sortedExchangeNames.length > 0) {
+    const ids = sortedExchangeNames
+      .map((name) => exchID(exchanges.get(name)!.transport, name))
+      .join(",");
+    out += `    style ${ids} fill:#bbf,stroke:#333\n`;
+  }
+
+  return out;
+}