@emmett-community/emmett-google-pubsub 0.1.0

package/dist/index.mjs

@@ -0,0 +1,778 @@
+import { randomUUID } from 'crypto';
+import { EmmettError } from '@event-driven-io/emmett';
+
+// src/messageBus/serialization.ts
+function transformDatesToMarkers(obj) {
+  if (obj instanceof Date) {
+    return {
+      __type: "Date",
+      value: obj.toISOString()
+    };
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(transformDatesToMarkers);
+  }
+  if (obj !== null && typeof obj === "object") {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+      result[key] = transformDatesToMarkers(value);
+    }
+    return result;
+  }
+  return obj;
+}
+function isDateMarker(value) {
+  return typeof value === "object" && value !== null && "__type" in value && value.__type === "Date" && "value" in value && typeof value.value === "string";
+}
+function dateReviver(_key, value) {
+  if (isDateMarker(value)) {
+    return new Date(value.value);
+  }
+  return value;
+}
+function getMessageKind(message) {
+  const typeStr = message.type.toLowerCase();
+  return typeStr.includes("command") ? "command" : "event";
+}
+function serialize(message) {
+  const envelope = {
+    type: message.type,
+    kind: getMessageKind(message),
+    data: transformDatesToMarkers(message.data),
+    metadata: "metadata" in message ? transformDatesToMarkers(message.metadata) : void 0,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    messageId: randomUUID()
+  };
+  const json = JSON.stringify(envelope);
+  return Buffer.from(json);
+}
+function deserialize(buffer) {
+  try {
+    const json = buffer.toString("utf-8");
+    const envelope = JSON.parse(json, dateReviver);
+    const message = {
+      type: envelope.type,
+      data: envelope.data,
+      ...envelope.metadata ? { metadata: envelope.metadata } : {}
+    };
+    return message;
+  } catch (error) {
+    throw new Error(
+      `Failed to deserialize message: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+function attachMessageId(message, messageId) {
+  return {
+    ...message,
+    __messageId: messageId
+  };
+}
+function extractMessageId(message) {
+  return "__messageId" in message ? message.__messageId : void 0;
+}
+
+// src/messageBus/topicManager.ts
+function getCommandTopicName(commandType, prefix = "emmett") {
+  return `${prefix}-cmd-${commandType}`;
+}
+function getEventTopicName(eventType, prefix = "emmett") {
+  return `${prefix}-evt-${eventType}`;
+}
+function getCommandSubscriptionName(commandType, instanceId, prefix = "emmett") {
+  return `${prefix}-cmd-${commandType}-${instanceId}`;
+}
+function getEventSubscriptionName(eventType, subscriptionId, prefix = "emmett") {
+  return `${prefix}-evt-${eventType}-${subscriptionId}`;
+}
+async function getOrCreateTopic(pubsub, topicName) {
+  const topic = pubsub.topic(topicName);
+  try {
+    const [exists] = await topic.exists();
+    if (!exists) {
+      try {
+        await topic.create();
+      } catch (createError) {
+        if (createError.code !== 6) {
+          throw createError;
+        }
+      }
+    }
+    return topic;
+  } catch (error) {
+    throw new Error(
+      `Failed to get or create topic ${topicName}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+async function getOrCreateSubscription(topic, subscriptionName, options) {
+  const subscription = topic.subscription(subscriptionName);
+  try {
+    const [exists] = await subscription.exists();
+    if (!exists) {
+      const config = {
+        ...options?.ackDeadlineSeconds && {
+          ackDeadlineSeconds: options.ackDeadlineSeconds
+        },
+        ...options?.retryPolicy && {
+          retryPolicy: {
+            ...options.retryPolicy.minimumBackoff && {
+              minimumBackoff: options.retryPolicy.minimumBackoff
+            },
+            ...options.retryPolicy.maximumBackoff && {
+              maximumBackoff: options.retryPolicy.maximumBackoff
+            }
+          }
+        },
+        ...options?.deadLetterPolicy && {
+          deadLetterPolicy: {
+            ...options.deadLetterPolicy.deadLetterTopic && {
+              deadLetterTopic: options.deadLetterPolicy.deadLetterTopic
+            },
+            ...options.deadLetterPolicy.maxDeliveryAttempts && {
+              maxDeliveryAttempts: options.deadLetterPolicy.maxDeliveryAttempts
+            }
+          }
+        }
+      };
+      try {
+        await subscription.create(config);
+      } catch (createError) {
+        if (createError.code !== 6) {
+          throw createError;
+        }
+      }
+    }
+    return subscription;
+  } catch (error) {
+    throw new Error(
+      `Failed to get or create subscription ${subscriptionName}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+async function deleteSubscription(subscription) {
+  try {
+    const [exists] = await subscription.exists();
+    if (exists) {
+      await subscription.delete();
+    }
+  } catch (error) {
+    console.warn(
+      `Failed to delete subscription: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+async function deleteSubscriptions(subscriptions) {
+  await Promise.all(subscriptions.map((sub) => deleteSubscription(sub)));
+}
+function generateUUID() {
+  return randomUUID();
+}
+function assertNotEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${name} must be a non-empty string`);
+  }
+}
+function assertPositiveNumber(value, name) {
+  if (typeof value !== "number" || value <= 0 || Number.isNaN(value)) {
+    throw new Error(`${name} must be a positive number`);
+  }
+}
+
+// src/messageBus/scheduler.ts
+function calculateScheduledTime(options) {
+  if (!options) {
+    return /* @__PURE__ */ new Date();
+  }
+  if ("afterInMs" in options) {
+    const now = /* @__PURE__ */ new Date();
+    return new Date(now.getTime() + options.afterInMs);
+  }
+  if ("at" in options) {
+    return options.at;
+  }
+  return /* @__PURE__ */ new Date();
+}
+function filterReadyMessages(pending, now) {
+  return pending.filter((msg) => msg.scheduledAt <= now);
+}
+var MessageScheduler = class {
+  pendingMessages = [];
+  useEmulator;
+  pubsub;
+  topicPrefix;
+  scheduledTopic;
+  constructor(config) {
+    this.useEmulator = config.useEmulator;
+    this.pubsub = config.pubsub;
+    this.scheduledTopic = config.scheduledTopic;
+    this.topicPrefix = config.topicPrefix ?? "emmett";
+  }
+  /**
+   * Schedule a message for future delivery
+   *
+   * In production mode: Publishes to PubSub with publishTime attribute
+   * In emulator mode: Stores in memory for later dequeue (emulator doesn't support scheduling)
+   *
+   * @param message - The message to schedule
+   * @param options - When to deliver the message
+   */
+  async schedule(message, options) {
+    const scheduledAt = calculateScheduledTime(options);
+    if (this.useEmulator) {
+      this.pendingMessages.push({
+        message,
+        options,
+        scheduledAt
+      });
+    } else {
+      await this.publishScheduledMessage(message, scheduledAt);
+    }
+  }
+  /**
+   * Dequeue ready scheduled messages (emulator mode only)
+   *
+   * Returns messages whose scheduled time has passed and removes them from pending queue
+   *
+   * @returns Array of scheduled messages ready for delivery
+   */
+  dequeue() {
+    if (!this.useEmulator) {
+      return [];
+    }
+    const now = /* @__PURE__ */ new Date();
+    const ready = filterReadyMessages(this.pendingMessages, now);
+    this.pendingMessages = this.pendingMessages.filter(
+      (msg) => msg.scheduledAt > now
+    );
+    return ready.map((info) => ({
+      message: info.message,
+      options: info.options
+    }));
+  }
+  /**
+   * Publish a scheduled message to PubSub (production mode)
+   *
+   * @param message - The message to publish
+   * @param scheduledAt - When the message should be delivered
+   */
+  async publishScheduledMessage(message, scheduledAt) {
+    try {
+      if (!this.scheduledTopic) {
+        const topicName = `${this.topicPrefix}-scheduled-messages`;
+        this.scheduledTopic = this.pubsub.topic(topicName);
+        const [exists] = await this.scheduledTopic.exists();
+        if (!exists) {
+          await this.scheduledTopic.create();
+        }
+      }
+      const buffer = serialize(message);
+      await this.scheduledTopic.publishMessage({
+        data: buffer,
+        attributes: {
+          messageType: message.type,
+          publishTime: scheduledAt.toISOString()
+        }
+      });
+    } catch (error) {
+      throw new Error(
+        `Failed to publish scheduled message ${message.type}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  /**
+   * Get count of pending scheduled messages (emulator mode only)
+   *
+   * @returns Number of pending scheduled messages
+   */
+  getPendingCount() {
+    return this.useEmulator ? this.pendingMessages.length : 0;
+  }
+  /**
+   * Clear all pending scheduled messages (emulator mode only, useful for testing)
+   */
+  clearPending() {
+    if (this.useEmulator) {
+      this.pendingMessages = [];
+    }
+  }
+};
+function shouldRetry(error) {
+  if (!(error instanceof Error)) {
+    return true;
+  }
+  const errorMessage = error.message.toLowerCase();
+  if (errorMessage.includes("network") || errorMessage.includes("timeout") || errorMessage.includes("econnrefused") || errorMessage.includes("enotfound") || errorMessage.includes("unavailable")) {
+    return true;
+  }
+  if (error instanceof EmmettError) {
+    return false;
+  }
+  if (errorMessage.includes("validation") || errorMessage.includes("invalid") || errorMessage.includes("not found") || errorMessage.includes("already exists")) {
+    return false;
+  }
+  return true;
+}
+async function handleCommandMessage(message, handlers, commandType) {
+  try {
+    const commandHandlers = handlers.get(commandType);
+    if (!commandHandlers || commandHandlers.length === 0) {
+      throw new EmmettError(
+        `No handler registered for command ${commandType}!`
+      );
+    }
+    if (commandHandlers.length > 1) {
+      throw new EmmettError(
+        `Multiple handlers registered for command ${commandType}. Commands must have exactly one handler.`
+      );
+    }
+    const command = deserialize(message.data);
+    const handler = commandHandlers[0];
+    await handler(command);
+    return "ack";
+  } catch (error) {
+    console.error(
+      `Error handling command ${commandType}:`,
+      error instanceof Error ? error.message : String(error)
+    );
+    if (shouldRetry(error)) {
+      console.info(
+        `Nacking command ${commandType} for retry (delivery attempt: ${message.deliveryAttempt})`
+      );
+      return "nack";
+    } else {
+      console.warn(
+        `Acking command ${commandType} despite error (permanent failure)`
+      );
+      return "ack";
+    }
+  }
+}
+async function handleEventMessage(message, handlers, eventType) {
+  try {
+    const eventHandlers = handlers.get(eventType);
+    if (!eventHandlers || eventHandlers.length === 0) {
+      console.debug(`No handlers registered for event ${eventType}, skipping`);
+      return "ack";
+    }
+    const event = deserialize(message.data);
+    for (const handler of eventHandlers) {
+      try {
+        await handler(event);
+      } catch (error) {
+        console.error(
+          `Error in event handler for ${eventType}:`,
+          error instanceof Error ? error.message : String(error)
+        );
+        if (shouldRetry(error)) {
+          console.info(
+            `Nacking event ${eventType} for retry due to handler failure (delivery attempt: ${message.deliveryAttempt})`
+          );
+          return "nack";
+        }
+        console.warn(
+          `Continuing event ${eventType} processing despite handler error (permanent failure)`
+        );
+      }
+    }
+    return "ack";
+  } catch (error) {
+    console.error(
+      `Error handling event ${eventType}:`,
+      error instanceof Error ? error.message : String(error)
+    );
+    if (shouldRetry(error)) {
+      return "nack";
+    } else {
+      return "ack";
+    }
+  }
+}
+function createMessageListener(subscription, messageType, kind, handlers) {
+  subscription.on("message", async (message) => {
+    try {
+      const result = kind === "command" ? await handleCommandMessage(message, handlers, messageType) : await handleEventMessage(message, handlers, messageType);
+      if (result === "ack") {
+        message.ack();
+      } else {
+        message.nack();
+      }
+    } catch (error) {
+      console.error(
+        `Unexpected error in message listener for ${messageType}:`,
+        error instanceof Error ? error.message : String(error)
+      );
+      message.nack();
+    }
+  });
+  subscription.on("error", (error) => {
+    console.error(
+      `Subscription error for ${messageType}:`,
+      error instanceof Error ? error.message : String(error)
+    );
+  });
+}
+function determineMessageKindFallback(messageType) {
+  const typeStr = messageType.toLowerCase();
+  return typeStr.includes("command") ? "command" : "event";
+}
+function getPubSubMessageBus(config) {
+  const instanceId = config.instanceId ?? generateUUID();
+  const topicPrefix = config.topicPrefix ?? "emmett";
+  const autoCreateResources = config.autoCreateResources ?? true;
+  const cleanupOnClose = config.cleanupOnClose ?? false;
+  const closePubSubClient = config.closePubSubClient;
+  const handlers = /* @__PURE__ */ new Map();
+  const subscriptionHandlers = /* @__PURE__ */ new Map();
+  const eventSubscriptionIds = /* @__PURE__ */ new Map();
+  const commandTypes = /* @__PURE__ */ new Set();
+  const eventTypes = /* @__PURE__ */ new Set();
+  const subscriptions = [];
+  const scheduler = new MessageScheduler({
+    useEmulator: config.useEmulator ?? false,
+    pubsub: config.pubsub,
+    topicPrefix
+  });
+  let started = false;
+  function determineMessageKind(messageType) {
+    if (commandTypes.has(messageType)) {
+      return "command";
+    }
+    if (eventTypes.has(messageType)) {
+      return "event";
+    }
+    return determineMessageKindFallback(messageType);
+  }
+  async function createSubscriptionForType(messageType, kind, subscriptionId) {
+    const topicName = kind === "command" ? getCommandTopicName(messageType, topicPrefix) : getEventTopicName(messageType, topicPrefix);
+    const topic = await getOrCreateTopic(config.pubsub, topicName);
+    const subName = kind === "command" ? getCommandSubscriptionName(messageType, instanceId, topicPrefix) : getEventSubscriptionName(
+      messageType,
+      subscriptionId ?? instanceId,
+      topicPrefix
+    );
+    const subscription = await getOrCreateSubscription(
+      topic,
+      subName,
+      config.subscriptionOptions
+    );
+    if (kind === "event" && subscriptionId) {
+      const handler = subscriptionHandlers.get(subscriptionId);
+      if (handler) {
+        const singleHandlerMap = /* @__PURE__ */ new Map();
+        singleHandlerMap.set(messageType, [handler]);
+        createMessageListener(subscription, messageType, kind, singleHandlerMap);
+      }
+    } else {
+      createMessageListener(subscription, messageType, kind, handlers);
+    }
+    subscriptions.push({
+      topic,
+      subscription,
+      messageType,
+      kind
+    });
+  }
+  async function publishMessage(message, kind) {
+    const topicName = kind === "command" ? getCommandTopicName(message.type, topicPrefix) : getEventTopicName(message.type, topicPrefix);
+    try {
+      const topic = config.pubsub.topic(topicName);
+      if (!autoCreateResources) {
+        const [exists] = await topic.exists();
+        if (!exists) {
+          throw new Error(
+            `Topic ${topicName} does not exist and autoCreateResources is disabled`
+          );
+        }
+      } else {
+        const [exists] = await topic.exists();
+        if (!exists) {
+          await topic.create();
+        }
+      }
+      const buffer = serialize(message);
+      await topic.publishMessage({
+        data: buffer,
+        attributes: {
+          messageType: message.type,
+          messageKind: kind
+        }
+      });
+    } catch (error) {
+      throw new Error(
+        `Failed to publish ${kind} ${message.type} to topic ${topicName}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  return {
+    // ===== MessageBus Interface =====
+    /**
+     * Send a command to the message bus
+     *
+     * Commands are routed to exactly one handler via PubSub topics
+     *
+     * @param command - The command to send
+     */
+    async send(command) {
+      await publishMessage(command, "command");
+    },
+    /**
+     * Publish an event to the message bus
+     *
+     * Events are delivered to all registered subscribers via PubSub topics
+     *
+     * @param event - The event to publish
+     */
+    async publish(event) {
+      await publishMessage(event, "event");
+    },
+    /**
+     * Schedule a message for future delivery
+     *
+     * In production mode: Uses PubSub native scheduling
+     * In emulator mode: Stores in memory (emulator doesn't support scheduling)
+     *
+     * @param message - The message to schedule
+     * @param when - When to deliver the message (afterInMs or at)
+     */
+    schedule(message, when) {
+      scheduler.schedule(message, when);
+    },
+    // ===== CommandProcessor Interface =====
+    /**
+     * Register a command handler
+     *
+     * Commands must have exactly one handler. Attempting to register multiple
+     * handlers for the same command will throw an EmmettError.
+     *
+     * @param commandHandler - The handler function
+     * @param commandTypes - Command types this handler processes
+     * @throws EmmettError if a handler is already registered for any command type
+     *
+     * @example
+     * ```typescript
+     * messageBus.handle(
+     *   async (command: AddProductItemCommand) => {
+     *     // Handle command
+     *   },
+     *   'AddProductItem'
+     * );
+     * ```
+     */
+    handle(commandHandler, ...commandTypeNames) {
+      for (const commandType of commandTypeNames) {
+        if (handlers.has(commandType)) {
+          throw new EmmettError(
+            `Handler already registered for command ${commandType}. Commands must have exactly one handler.`
+          );
+        }
+        commandTypes.add(commandType);
+        handlers.set(commandType, [
+          commandHandler
+        ]);
+        if (started) {
+          createSubscriptionForType(commandType, "command").catch((error) => {
+            console.error(
+              `Failed to create subscription for command ${commandType}:`,
+              error instanceof Error ? error.message : String(error)
+            );
+          });
+        }
+      }
+    },
+    // ===== EventSubscription Interface =====
+    /**
+     * Subscribe to events
+     *
+     * Events can have multiple subscribers. Each subscription gets its own
+     * PubSub subscription to ensure all handlers receive all events.
+     *
+     * @param eventHandler - The handler function
+     * @param eventTypes - Event types to subscribe to
+     *
+     * @example
+     * ```typescript
+     * messageBus.subscribe(
+     *   async (event: ProductItemAddedEvent) => {
+     *     // Handle event
+     *   },
+     *   'ProductItemAdded'
+     * );
+     * ```
+     */
+    subscribe(eventHandler, ...eventTypeNames) {
+      for (const eventType of eventTypeNames) {
+        eventTypes.add(eventType);
+        const subscriptionId = generateUUID();
+        subscriptionHandlers.set(
+          subscriptionId,
+          eventHandler
+        );
+        const existing = handlers.get(eventType) ?? [];
+        handlers.set(eventType, [
+          ...existing,
+          eventHandler
+        ]);
+        const existingIds = eventSubscriptionIds.get(eventType) ?? [];
+        eventSubscriptionIds.set(eventType, [...existingIds, subscriptionId]);
+        if (started) {
+          createSubscriptionForType(eventType, "event", subscriptionId).catch(
+            (error) => {
+              console.error(
+                `Failed to create subscription for event ${eventType}:`,
+                error instanceof Error ? error.message : String(error)
+              );
+            }
+          );
+        }
+      }
+    },
+    // ===== ScheduledMessageProcessor Interface =====
+    /**
+     * Dequeue scheduled messages that are ready for delivery
+     *
+     * Only used in emulator mode. In production, PubSub handles scheduling.
+     *
+     * @returns Array of scheduled messages ready for delivery
+     *
+     * @example
+     * ```typescript
+     * // In emulator mode, periodically call dequeue
+     * setInterval(() => {
+     *   const ready = messageBus.dequeue();
+     *   for (const { message } of ready) {
+     *     // Process message
+     *   }
+     * }, 1000);
+     * ```
+     */
+    dequeue() {
+      return scheduler.dequeue();
+    },
+    // ===== PubSubMessageBusLifecycle Interface =====
+    /**
+     * Start the message bus
+     *
+     * Creates topics and subscriptions for all registered handlers and begins
+     * listening for messages.
+     *
+     * This method is idempotent - calling it multiple times is safe.
+     *
+     * @throws Error if topic/subscription creation fails
+     *
+     * @example
+     * ```typescript
+     * // Register all handlers first
+     * messageBus.handle(commandHandler, 'MyCommand');
+     * messageBus.subscribe(eventHandler, 'MyEvent');
+     *
+     * // Then start
+     * await messageBus.start();
+     * ```
+     */
+    async start() {
+      if (started) {
+        console.debug("Message bus already started, skipping");
+        return;
+      }
+      console.info("Starting PubSub message bus...");
+      try {
+        const subscriptionPromises = [];
+        for (const [messageType] of handlers.entries()) {
+          const kind = determineMessageKind(messageType);
+          if (kind === "command") {
+            subscriptionPromises.push(
+              createSubscriptionForType(messageType, "command")
+            );
+          } else {
+            const subIds = eventSubscriptionIds.get(messageType) ?? [
+              instanceId
+            ];
+            for (const subId of subIds) {
+              subscriptionPromises.push(
+                createSubscriptionForType(messageType, "event", subId)
+              );
+            }
+          }
+        }
+        await Promise.all(subscriptionPromises);
+        started = true;
+        console.info(
+          `PubSub message bus started with ${subscriptions.length} subscription(s)`
+        );
+      } catch (error) {
+        throw new Error(
+          `Failed to start message bus: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    },
+    /**
+     * Close the message bus gracefully
+     *
+     * Stops accepting new messages, waits for in-flight messages to complete,
+     * optionally cleans up subscriptions, and closes the PubSub client.
+     *
+     * @throws Error if cleanup fails
+     *
+     * @example
+     * ```typescript
+     * // Graceful shutdown
+     * process.on('SIGTERM', async () => {
+     *   await messageBus.close();
+     *   process.exit(0);
+     * });
+     * ```
+     */
+    async close() {
+      console.info("Closing PubSub message bus...");
+      try {
+        if (started) {
+          for (const { subscription } of subscriptions) {
+            subscription.removeAllListeners("message");
+            subscription.removeAllListeners("error");
+          }
+          const timeout = 3e4;
+          const waitStart = Date.now();
+          const closePromises = subscriptions.map(
+            ({ subscription }) => subscription.close()
+          );
+          await Promise.race([
+            Promise.all(closePromises),
+            new Promise((resolve) => setTimeout(resolve, timeout))
+          ]);
+          const waitTime = Date.now() - waitStart;
+          if (waitTime >= timeout) {
+            console.warn(
+              `Timeout waiting for in-flight messages after ${timeout}ms`
+            );
+          }
+          if (cleanupOnClose) {
+            console.info("Cleaning up subscriptions...");
+            await deleteSubscriptions(subscriptions.map((s) => s.subscription));
+          }
+          started = false;
+        }
+        if (closePubSubClient !== false) {
+          await config.pubsub.close();
+        }
+        console.info("PubSub message bus closed");
+      } catch (error) {
+        throw new Error(
+          `Failed to close message bus: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    },
+    /**
+     * Check if the message bus is started
+     *
+     * @returns true if the message bus is started and ready to process messages
+     */
+    isStarted() {
+      return started;
+    }
+  };
+}
+
+export { MessageScheduler, assertNotEmptyString, assertPositiveNumber, attachMessageId, calculateScheduledTime, createMessageListener, deleteSubscription, deleteSubscriptions, deserialize, extractMessageId, filterReadyMessages, generateUUID, getCommandSubscriptionName, getCommandTopicName, getEventSubscriptionName, getEventTopicName, getOrCreateSubscription, getOrCreateTopic, getPubSubMessageBus, handleCommandMessage, handleEventMessage, serialize, shouldRetry };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map