@gomessaging/messaging 0.0.1

package/dist/routing.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Returns true if routingKey matches the binding pattern.
+ * Supports AMQP/NATS wildcard syntax: `*` matches one word, `#` matches zero or more.
+ */
+export declare function matchRoutingKey(pattern: string, routingKey: string): boolean;
+/**
+ * Returns true if two binding patterns could match the same routing key.
+ */
+export declare function routingKeyOverlaps(p1: string, p2: string): boolean;
+//# sourceMappingURL=routing.d.ts.map

package/dist/routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../src/routing.ts"],"names":[],"mappings":"AAkBA;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAM5E;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAKlE"}

package/dist/routing.js

@@ -0,0 +1,41 @@
+// MIT License
+// Copyright (c) 2026 sparetimecoders
+/**
+ * Converts an AMQP/NATS binding pattern to a regular expression string.
+ *
+ * - `.` is escaped to `\.`
+ * - `*` matches a single word: `[^.]*`
+ * - `#` matches zero or more words: `.*`
+ */
+function routingKeyToRegex(pattern) {
+    const escaped = pattern
+        .replaceAll(".", "\\.")
+        .replaceAll("*", "[^.]*")
+        .replaceAll("#", ".*");
+    return `^${escaped}$`;
+}
+/**
+ * Returns true if routingKey matches the binding pattern.
+ * Supports AMQP/NATS wildcard syntax: `*` matches one word, `#` matches zero or more.
+ */
+export function matchRoutingKey(pattern, routingKey) {
+    try {
+        return new RegExp(routingKeyToRegex(pattern)).test(routingKey);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Returns true if two binding patterns could match the same routing key.
+ */
+export function routingKeyOverlaps(p1, p2) {
+    if (p1 === p2)
+        return true;
+    if (matchRoutingKey(p1, p2))
+        return true;
+    if (matchRoutingKey(p2, p1))
+        return true;
+    return false;
+}
+//# sourceMappingURL=routing.js.map

package/dist/routing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.js","sourceRoot":"","sources":["../src/routing.ts"],"names":[],"mappings":"AAAA,cAAc;AACd,qCAAqC;AAErC;;;;;;GAMG;AACH,SAAS,iBAAiB,CAAC,OAAe;IACxC,MAAM,OAAO,GAAG,OAAO;SACpB,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC;SACtB,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC;SACxB,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACzB,OAAO,IAAI,OAAO,GAAG,CAAC;AACxB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe,EAAE,UAAkB;IACjE,IAAI,CAAC;QACH,OAAO,IAAI,MAAM,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,EAAU,EAAE,EAAU;IACvD,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC3B,IAAI,eAAe,CAAC,EAAE,EAAE,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,IAAI,eAAe,CAAC,EAAE,EAAE,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/topology.d.ts

@@ -0,0 +1,2 @@
+export type { Transport, EndpointDirection, ExchangeKind, Pattern, Endpoint, Topology, } from "./types.js";
+//# sourceMappingURL=topology.d.ts.map

package/dist/topology.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topology.d.ts","sourceRoot":"","sources":["../src/topology.ts"],"names":[],"mappings":"AAKA,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,YAAY,EACZ,OAAO,EACP,QAAQ,EACR,QAAQ,GACT,MAAM,YAAY,CAAC"}

package/dist/topology.js

@@ -0,0 +1,4 @@
+// MIT License
+// Copyright (c) 2026 sparetimecoders
+export {};
+//# sourceMappingURL=topology.js.map

package/dist/topology.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topology.js","sourceRoot":"","sources":["../src/topology.ts"],"names":[],"mappings":"AAAA,cAAc;AACd,qCAAqC"}

package/dist/types.d.ts

@@ -0,0 +1,73 @@
+/** Transport identifies the messaging transport implementation. */
+export type Transport = "amqp" | "nats";
+/** EndpointDirection indicates whether an endpoint publishes or consumes messages. */
+export type EndpointDirection = "publish" | "consume";
+/** ExchangeKind represents the type of an exchange. */
+export type ExchangeKind = "topic" | "direct" | "headers";
+/** Pattern identifies the communication pattern an endpoint participates in. */
+export type Pattern = "event-stream" | "custom-stream" | "service-request" | "service-response" | "queue-publish";
+/** Headers represent all meta-data for the message. */
+export type Headers = Record<string, unknown>;
+/** Metadata holds the metadata of an event. */
+export interface Metadata {
+    id: string;
+    correlationId: string;
+    timestamp: string;
+    source: string;
+    type: string;
+    subject: string;
+    dataContentType: string;
+    specVersion: string;
+}
+/** DeliveryInfo holds transport-agnostic delivery metadata. */
+export interface DeliveryInfo {
+    destination: string;
+    source: string;
+    key: string;
+    headers: Headers;
+}
+/** ConsumableEvent represents an event that can be consumed. */
+export interface ConsumableEvent<T> extends Metadata {
+    deliveryInfo: DeliveryInfo;
+    payload: T;
+}
+/** Endpoint describes a single exchange/queue/binding that a service declares. */
+export interface Endpoint {
+    direction: EndpointDirection;
+    pattern: Pattern;
+    exchangeName: string;
+    exchangeKind: ExchangeKind;
+    queueName?: string;
+    routingKey?: string;
+    messageType?: string;
+    ephemeral?: boolean;
+}
+/** Topology describes the full messaging topology declared by a single service. */
+export interface Topology {
+    transport?: Transport;
+    serviceName: string;
+    endpoints: Endpoint[];
+}
+/** EventHandler is a function that handles events of a specific type. */
+export type EventHandler<T> = (event: ConsumableEvent<T>) => Promise<void>;
+/** RequestResponseEventHandler handles events and returns a response. */
+export type RequestResponseEventHandler<T, R> = (event: ConsumableEvent<T>) => Promise<R>;
+/** NotificationSource identifies the origin of a notification. */
+export type NotificationSource = "CONSUMER";
+/** Notification represents a successful event processing notification. */
+export interface Notification {
+    deliveryInfo: DeliveryInfo;
+    durationMs: number;
+    source: NotificationSource;
+}
+/** ErrorNotification represents a failed event processing notification. */
+export interface ErrorNotification extends Notification {
+    error: Error;
+}
+/** NotificationHandler is called after successful event processing. */
+export type NotificationHandler = (n: Notification) => void;
+/** ErrorNotificationHandler is called after failed event processing. */
+export type ErrorNotificationHandler = (n: ErrorNotification) => void;
+/** ErrParseJSON sentinel error message. */
+export declare const ErrParseJSON = "failed to parse";
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA,mEAAmE;AACnE,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAExC,sFAAsF;AACtF,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,SAAS,CAAC;AAEtD,uDAAuD;AACvD,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE1D,gFAAgF;AAChF,MAAM,MAAM,OAAO,GACf,cAAc,GACd,eAAe,GACf,iBAAiB,GACjB,kBAAkB,GAClB,eAAe,CAAC;AAEpB,uDAAuD;AACvD,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE9C,+CAA+C;AAC/C,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,+DAA+D;AAC/D,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,gEAAgE;AAChE,MAAM,WAAW,eAAe,CAAC,CAAC,CAAE,SAAQ,QAAQ;IAClD,YAAY,EAAE,YAAY,CAAC;IAC3B,OAAO,EAAE,CAAC,CAAC;CACZ;AAED,kFAAkF;AAClF,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,YAAY,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,mFAAmF;AACnF,MAAM,WAAW,QAAQ;IACvB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,QAAQ,EAAE,CAAC;CACvB;AAED,yEAAyE;AACzE,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAC5B,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,KACtB,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB,yEAAyE;AACzE,MAAM,MAAM,2BAA2B,CAAC,CAAC,EAAE,CAAC,IAAI,CAC9C,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,KACtB,OAAO,CAAC,CAAC,CAAC,CAAC;AAEhB,kEAAkE;AAClE,MAAM,MAAM,kBAAkB,GAAG,UAAU,CAAC;AAE5C,0EAA0E;AAC1E,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,YAAY,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,kBAAkB,CAAC;CAC5B;AAED,2EAA2E;AAC3E,MAAM,WAAW,iBAAkB,SAAQ,YAAY;IACrD,KAAK,EAAE,KAAK,CAAC;CACd;AAED,uEAAuE;AACvE,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,CAAC;AAE5D,wEAAwE;AACxE,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,EAAE,iBAAiB,KAAK,IAAI,CAAC;AAEtE,2CAA2C;AAC3C,eAAO,MAAM,YAAY,oBAAoB,CAAC"}

package/dist/types.js

@@ -0,0 +1,5 @@
+// MIT License
+// Copyright (c) 2026 sparetimecoders
+/** ErrParseJSON sentinel error message. */
+export const ErrParseJSON = "failed to parse";
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,cAAc;AACd,qCAAqC;AAkGrC,2CAA2C;AAC3C,MAAM,CAAC,MAAM,YAAY,GAAG,iBAAiB,CAAC"}

package/dist/validate.d.ts

@@ -0,0 +1,12 @@
+import type { Topology } 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 declare function validate(t: Topology): string | null;
+/**
+ * ValidateTopologies checks cross-service consistency across multiple topologies.
+ * Returns null if valid, or an error message string if invalid.
+ */
+export declare function validateTopologies(topologies: Topology[]): string | null;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAY,QAAQ,EAAa,MAAM,YAAY,CAAC;AAEhE;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CA2CnD;AA+DD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,QAAQ,EAAE,GAAG,MAAM,GAAG,IAAI,CA2BxE"}

package/dist/validate.js

@@ -0,0 +1,138 @@
+// MIT License
+// Copyright (c) 2026 sparetimecoders
+/**
+ * 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) {
+    if (!t.serviceName) {
+        return "service name must not be empty";
+    }
+    const errs = [];
+    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, ep, index) {
+    switch (transport) {
+        case "amqp":
+            return validateAMQPExchangeName(ep, index);
+        case "nats":
+            return validateNATSExchangeName(ep, index);
+        default:
+            return null;
+    }
+}
+function validateAMQPExchangeName(ep, index) {
+    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, index) {
+    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) {
+    const errs = [];
+    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();
+    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) {
+    const errs = [];
+    // Build a set of all published routing keys per exchange.
+    const published = new Map(); // "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;
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"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"}

package/dist/visualize.d.ts

@@ -0,0 +1,10 @@
+import type { Topology } from "./types.js";
+/**
+ * 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 declare function mermaid(topologies: Topology[]): string;
+//# sourceMappingURL=visualize.d.ts.map

package/dist/visualize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visualize.d.ts","sourceRoot":"","sources":["../src/visualize.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAgB,QAAQ,EAAE,MAAM,YAAY,CAAC;AAoCzD;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,UAAU,EAAE,QAAQ,EAAE,GAAG,MAAM,CAwHtD"}

package/dist/visualize.js

@@ -0,0 +1,134 @@
+// MIT License
+// Copyright (c) 2026 sparetimecoders
+function sanitizeID(name) {
+    return name.replace(/[^a-zA-Z0-9_]/g, "_");
+}
+function exchangeNode(id, name, kind, indent) {
+    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) {
+    const services = new Set();
+    const exchanges = new Map();
+    const edges = [];
+    const transports = new Set();
+    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, name) => {
+        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;
+}
+//# sourceMappingURL=visualize.js.map

package/dist/visualize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visualize.js","sourceRoot":"","sources":["../src/visualize.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@gomessaging/messaging",
+  "version": "0.0.1",
+  "description": "Messaging specification and shared types for the gomessaging libraries",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/messaging/messaging.git",
+    "directory": "typescript"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}