@gomessaging/messaging 0.0.1

package/src/cloudevents.ts

@@ -0,0 +1,166 @@
+// MIT License
+// Copyright (c) 2026 sparetimecoders
+
+import type { DeliveryInfo, Headers, Metadata } from "./types.js";
+
+/** CloudEvents attribute header keys for binary content mode (canonical "ce-" prefix). */
+export const CESpecVersion = "ce-specversion";
+export const CEType = "ce-type";
+export const CESource = "ce-source";
+export const CEID = "ce-id";
+export const CETime = "ce-time";
+export const CESpecVersionValue = "1.0";
+
+/** Optional CE attributes */
+export const CEDataContentType = "ce-datacontenttype";
+export const CESubject = "ce-subject";
+export const CEDataSchema = "ce-dataschema";
+
+/** Extension attribute for correlation */
+export const CECorrelationID = "ce-correlationid";
+
+/** Bare CE attribute names (without prefix). */
+export const CEAttrSpecVersion = "specversion";
+export const CEAttrType = "type";
+export const CEAttrSource = "source";
+export const CEAttrID = "id";
+export const CEAttrTime = "time";
+export const CEAttrDataContentType = "datacontenttype";
+export const CEAttrSubject = "subject";
+export const CEAttrCorrelationID = "correlationid";
+
+/** CERequiredAttributes lists header keys required by CE 1.0. */
+export const CERequiredAttributes = [
+  CESpecVersion,
+  CEType,
+  CESource,
+  CEID,
+  CETime,
+];
+
+/**
+ * AMQPCEHeaderKey returns the AMQP application-properties key for a bare
+ * CloudEvents attribute name, using the "cloudEvents:" prefix per the
+ * CloudEvents AMQP Protocol Binding specification.
+ * Example: AMQPCEHeaderKey("specversion") -> "cloudEvents:specversion"
+ */
+export function AMQPCEHeaderKey(attr: string): string {
+  return "cloudEvents:" + attr;
+}
+
+/**
+ * NormalizeCEHeaders rewrites incoming transport headers so that all
+ * CloudEvents attributes use the canonical "ce-" prefix. This allows
+ * consumers to accept messages with any known prefix variant:
+ *   - "cloudEvents:specversion" -> "ce-specversion"
+ *   - "cloudEvents_specversion" -> "ce-specversion"  (JMS compat)
+ *   - "ce-specversion" -> unchanged
+ *
+ * Non-CE headers are preserved unchanged. A new object is returned.
+ */
+export function normalizeCEHeaders(h: Headers): Headers {
+  const out: Headers = {};
+  for (const [k, v] of Object.entries(h)) {
+    if (k.startsWith("cloudEvents:")) {
+      out["ce-" + k.slice("cloudEvents:".length)] = v;
+    } else if (k.startsWith("cloudEvents_")) {
+      out["ce-" + k.slice("cloudEvents_".length)] = v;
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+/**
+ * HasCEHeaders reports whether h contains at least one CE required attribute,
+ * checking for "ce-", "cloudEvents:", and "cloudEvents_" prefixes.
+ * Use this to distinguish legacy (pre-CloudEvents) messages from malformed CE messages.
+ */
+export function hasCEHeaders(h: Headers): boolean {
+  for (const key of Object.keys(h)) {
+    if (
+      key.startsWith("ce-") ||
+      key.startsWith("cloudEvents:") ||
+      key.startsWith("cloudEvents_")
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * EnrichLegacyMetadata populates empty Metadata fields with synthetic
+ * CloudEvents attributes derived from transport delivery information.
+ *
+ * Fields set when empty: id (randomUUID), timestamp (now), type (from key),
+ * source (from source), dataContentType ("application/json"), specVersion ("1.0").
+ *
+ * Fields NOT set: correlationId, subject (cannot be inferred).
+ * Any non-empty fields in m are preserved (not overwritten).
+ * Returns a new Metadata object; the input is not mutated.
+ */
+export function enrichLegacyMetadata(
+  m: Metadata,
+  info: DeliveryInfo,
+): Metadata {
+  return {
+    ...m,
+    id: m.id || crypto.randomUUID(),
+    timestamp: m.timestamp || new Date().toISOString(),
+    type: m.type || info.key,
+    source: m.source || info.source,
+    dataContentType: m.dataContentType || "application/json",
+    specVersion: m.specVersion || CESpecVersionValue,
+  };
+}
+
+/** RFC 3339 regex for timestamp validation. */
+const RFC3339_RE =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+
+function headerString(h: Headers, key: string): string {
+  const v = h[key];
+  if (typeof v === "string") {
+    return v;
+  }
+  return "";
+}
+
+/**
+ * MetadataFromHeaders extracts CloudEvents metadata from message headers
+ * into a Metadata struct. Invalid (non-RFC3339) timestamps return empty string.
+ */
+export function metadataFromHeaders(h: Headers): Metadata {
+  const timeStr = headerString(h, CETime);
+  return {
+    id: headerString(h, CEID),
+    source: headerString(h, CESource),
+    type: headerString(h, CEType),
+    subject: headerString(h, CESubject),
+    dataContentType: headerString(h, CEDataContentType),
+    specVersion: headerString(h, CESpecVersion),
+    correlationId: headerString(h, CECorrelationID),
+    timestamp: RFC3339_RE.test(timeStr) ? timeStr : "",
+  };
+}
+
+/**
+ * ValidateCEHeaders checks that all required CloudEvents 1.0 attributes
+ * are present and are strings. Returns a list of warnings for any
+ * missing or non-string attributes.
+ */
+export function validateCEHeaders(h: Headers): string[] {
+  const warnings: string[] = [];
+  for (const key of CERequiredAttributes) {
+    if (!(key in h)) {
+      warnings.push(`missing required attribute "${key}"`);
+      continue;
+    }
+    if (typeof h[key] !== "string") {
+      warnings.push(`attribute "${key}" is not a string`);
+    }
+  }
+  return warnings;
+}

package/src/index.ts

@@ -0,0 +1,86 @@
+// MIT License
+// Copyright (c) 2026 sparetimecoders
+
+// Types
+export type {
+  Transport,
+  EndpointDirection,
+  ExchangeKind,
+  Pattern,
+  Headers,
+  Metadata,
+  DeliveryInfo,
+  ConsumableEvent,
+  Endpoint,
+  Topology,
+  EventHandler,
+  RequestResponseEventHandler,
+  NotificationSource,
+  Notification,
+  ErrorNotification,
+  NotificationHandler,
+  ErrorNotificationHandler,
+} from "./types.js";
+export { ErrParseJSON } from "./types.js";
+
+// Naming
+export {
+  DefaultEventExchangeName,
+  KindTopic,
+  KindDirect,
+  KindHeaders,
+  topicExchangeName,
+  serviceEventQueueName,
+  serviceRequestExchangeName,
+  serviceResponseExchangeName,
+  serviceRequestQueueName,
+  serviceResponseQueueName,
+  natsStreamName,
+  natsSubject,
+  translateWildcard,
+} from "./naming.js";
+
+// CloudEvents
+export {
+  CESpecVersion,
+  CEType,
+  CESource,
+  CEID,
+  CETime,
+  CESpecVersionValue,
+  CEDataContentType,
+  CESubject,
+  CEDataSchema,
+  CECorrelationID,
+  CEAttrSpecVersion,
+  CEAttrType,
+  CEAttrSource,
+  CEAttrID,
+  CEAttrTime,
+  CEAttrDataContentType,
+  CEAttrSubject,
+  CEAttrCorrelationID,
+  CERequiredAttributes,
+  AMQPCEHeaderKey,
+  normalizeCEHeaders,
+  hasCEHeaders,
+  enrichLegacyMetadata,
+  metadataFromHeaders,
+  validateCEHeaders,
+} from "./cloudevents.js";
+
+// Routing
+export { matchRoutingKey, routingKeyOverlaps } from "./routing.js";
+
+// Validation
+export { validate, validateTopologies } from "./validate.js";
+
+// Visualization
+export { mermaid } from "./visualize.js";
+
+// Topology (re-exports)
+export {} from "./topology.js";
+
+// Metrics
+export type { MetricsRecorder, RoutingKeyMapper, MetricsOptions } from "./metrics.js";
+export { mapRoutingKey } from "./metrics.js";

package/src/metrics.ts

@@ -0,0 +1,58 @@
+// MIT License
+// Copyright (c) 2026 sparetimecoders
+
+/**
+ * Pluggable metrics interface for messaging adapters.
+ *
+ * Users wire this to any metrics backend (prom-client, OpenTelemetry,
+ * StatsD, etc.) by implementing MetricsRecorder and passing it to
+ * ConnectionOptions.
+ */
+
+/** Records messaging metrics. Implement this interface to wire any metrics backend. */
+export interface MetricsRecorder {
+  /** An event was received from the broker. */
+  eventReceived(queue: string, routingKey: string): void;
+
+  /** An event was received but no handler matched its routing key. */
+  eventWithoutHandler(queue: string, routingKey: string): void;
+
+  /** An event could not be parsed (invalid JSON). */
+  eventNotParsable(queue: string, routingKey: string): void;
+
+  /** An event was acknowledged (successfully processed). */
+  eventAck(queue: string, routingKey: string, durationMs: number): void;
+
+  /** An event was negatively acknowledged (handler failed). */
+  eventNack(queue: string, routingKey: string, durationMs: number): void;
+
+  /** A message was published successfully. */
+  publishSucceed(exchange: string, routingKey: string, durationMs: number): void;
+
+  /** A message failed to publish. */
+  publishFailed(exchange: string, routingKey: string, durationMs: number): void;
+}
+
+/**
+ * Maps a routing key before it is passed to metrics.
+ * Use this to normalize or redact dynamic segments (e.g. UUIDs)
+ * to prevent unbounded label cardinality.
+ */
+export type RoutingKeyMapper = (key: string) => string;
+
+/** Options for configuring metrics behavior. */
+export interface MetricsOptions {
+  routingKeyMapper?: RoutingKeyMapper;
+}
+
+/**
+ * Apply a routing key mapper, defaulting to identity.
+ * Empty mapped values are replaced with "unknown".
+ */
+export function mapRoutingKey(
+  key: string,
+  mapper?: RoutingKeyMapper,
+): string {
+  const mapped = mapper ? mapper(key) : key;
+  return mapped === "" ? "unknown" : mapped;
+}

package/src/naming.ts

@@ -0,0 +1,94 @@
+// MIT License
+// Copyright (c) 2026 sparetimecoders
+
+/** DefaultEventExchangeName is the default exchange name used for event streaming. */
+export const DefaultEventExchangeName = "events";
+
+/** Exchange kind constants matching AMQP exchange types. */
+export const KindTopic = "topic";
+export const KindDirect = "direct";
+export const KindHeaders = "headers";
+
+/**
+ * TopicExchangeName returns the topic exchange name for the given name.
+ * Format: `<name>.topic.exchange`
+ */
+export function topicExchangeName(name: string): string {
+  return `${name}.${KindTopic}.exchange`;
+}
+
+/**
+ * ServiceEventQueueName returns the durable event queue name for a service.
+ * Format: `<exchangeName>.queue.<service>`
+ */
+export function serviceEventQueueName(
+  exchangeName: string,
+  service: string,
+): string {
+  return `${exchangeName}.queue.${service}`;
+}
+
+/**
+ * ServiceRequestExchangeName returns the direct exchange name for requests to a service.
+ * Format: `<service>.direct.exchange.request`
+ */
+export function serviceRequestExchangeName(service: string): string {
+  return `${service}.${KindDirect}.exchange.request`;
+}
+
+/**
+ * ServiceResponseExchangeName returns the headers exchange name for responses from a service.
+ * Format: `<service>.headers.exchange.response`
+ */
+export function serviceResponseExchangeName(service: string): string {
+  return `${service}.${KindHeaders}.exchange.response`;
+}
+
+/**
+ * ServiceRequestQueueName returns the queue name for requests to a service.
+ * Format: `<service>.direct.exchange.request.queue`
+ */
+export function serviceRequestQueueName(service: string): string {
+  return `${serviceRequestExchangeName(service)}.queue`;
+}
+
+/**
+ * ServiceResponseQueueName returns the queue name for responses from targetService to serviceName.
+ * Format: `<targetService>.headers.exchange.response.queue.<serviceName>`
+ */
+export function serviceResponseQueueName(
+  targetService: string,
+  serviceName: string,
+): string {
+  return `${serviceResponseExchangeName(targetService)}.queue.${serviceName}`;
+}
+
+/**
+ * NATSStreamName extracts the base stream name from a logical name.
+ * If the name follows the AMQP convention `<name>.topic.exchange`, the prefix is extracted.
+ * Otherwise the name is returned as-is.
+ */
+export function natsStreamName(name: string): string {
+  const suffix = ".topic.exchange";
+  if (name.endsWith(suffix)) {
+    return name.slice(0, -suffix.length);
+  }
+  return name;
+}
+
+/**
+ * NATSSubject builds a NATS subject from a stream name and routing key.
+ * Format: `<stream>.<routingKey>`
+ */
+export function natsSubject(stream: string, routingKey: string): string {
+  return `${stream}.${routingKey}`;
+}
+
+/**
+ * TranslateWildcard converts AMQP-style wildcards to NATS-style wildcards.
+ * AMQP "#" (multi-level) -> NATS ">" (multi-level)
+ * AMQP "*" (single-level) stays "*" in NATS.
+ */
+export function translateWildcard(routingKey: string): string {
+  return routingKey.replaceAll("#", ">");
+}

package/src/routing.ts

@@ -0,0 +1,39 @@
+// 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: string): string {
+  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: string, routingKey: string): boolean {
+  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: string, p2: string): boolean {
+  if (p1 === p2) return true;
+  if (matchRoutingKey(p1, p2)) return true;
+  if (matchRoutingKey(p2, p1)) return true;
+  return false;
+}

package/src/topology.ts

@@ -0,0 +1,13 @@
+// MIT License
+// Copyright (c) 2026 sparetimecoders
+
+// Re-export topology-related types from types.ts.
+// This module serves as the canonical import path for topology types.
+export type {
+  Transport,
+  EndpointDirection,
+  ExchangeKind,
+  Pattern,
+  Endpoint,
+  Topology,
+} from "./types.js";

package/src/types.ts

@@ -0,0 +1,101 @@
+// MIT License
+// Copyright (c) 2026 sparetimecoders
+
+/** 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 const ErrParseJSON = "failed to parse";