@emmett-community/emmett-google-pubsub 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,413 @@
+import { PubSub, Topic, Subscription, Message as Message$1 } from '@google-cloud/pubsub';
+import { Message, SingleMessageHandler, Command, Event, SingleRawMessageHandlerWithoutContext, AnyMessage, MessageBus, EventSubscription, CommandProcessor, ScheduledMessageProcessor } from '@event-driven-io/emmett';
+
+/**
+ * Configuration for PubSub MessageBus
+ */
+interface PubSubMessageBusConfig {
+    /**
+     * Google Cloud PubSub client instance
+     */
+    pubsub: PubSub;
+    /**
+     * Instance identifier for subscriptions (auto-generated if not provided)
+     */
+    instanceId?: string;
+    /**
+     * Topic/subscription name prefix
+     * @default "emmett"
+     */
+    topicPrefix?: string;
+    /**
+     * Enable emulator mode (disables Cloud Scheduler features)
+     * @default false
+     */
+    useEmulator?: boolean;
+    /**
+     * Subscription configuration options
+     */
+    subscriptionOptions?: SubscriptionOptions;
+    /**
+     * Auto-create topics/subscriptions
+     * @default true
+     */
+    autoCreateResources?: boolean;
+    /**
+     * Cleanup subscriptions on close
+     * @default false
+     */
+    cleanupOnClose?: boolean;
+    /**
+     * Close the PubSub client on close
+     * Set to false if you want to reuse the client (e.g., in tests)
+     * @default true
+     */
+    closePubSubClient?: boolean;
+}
+/**
+ * Subscription configuration options
+ */
+interface SubscriptionOptions {
+    /**
+     * Acknowledgment deadline in seconds
+     * @default 60
+     */
+    ackDeadlineSeconds?: number;
+    /**
+     * Retry policy for failed messages
+     */
+    retryPolicy?: {
+        minimumBackoff?: {
+            seconds: number;
+        };
+        maximumBackoff?: {
+            seconds: number;
+        };
+    };
+    /**
+     * Dead letter policy
+     */
+    deadLetterPolicy?: {
+        deadLetterTopic?: string;
+        maxDeliveryAttempts?: number;
+    };
+}
+/**
+ * Message envelope for PubSub transport
+ */
+interface PubSubMessageEnvelope {
+    /**
+     * Message type (e.g., "AddProductItem")
+     */
+    type: string;
+    /**
+     * Message kind (command or event)
+     */
+    kind: 'command' | 'event';
+    /**
+     * Serialized message data
+     */
+    data: unknown;
+    /**
+     * Serialized message metadata
+     */
+    metadata?: unknown;
+    /**
+     * ISO 8601 timestamp
+     */
+    timestamp: string;
+    /**
+     * UUID for idempotency
+     */
+    messageId: string;
+}
+/**
+ * Internal handler registration
+ */
+interface HandlerRegistration<T extends Message = Message> {
+    id: string;
+    handler: SingleMessageHandler<T>;
+}
+/**
+ * Subscription information
+ */
+interface SubscriptionInfo {
+    topic: Topic;
+    subscription: Subscription;
+    messageType: string;
+    kind: 'command' | 'event';
+}
+/**
+ * Scheduled message with timing information
+ */
+interface ScheduledMessageInfo {
+    message: Message;
+    options?: {
+        afterInMs: number;
+    } | {
+        at: Date;
+    };
+    scheduledAt: Date;
+}
+/**
+ * PubSub message bus lifecycle
+ */
+interface PubSubMessageBusLifecycle {
+    /**
+     * Start the message bus (create topics/subscriptions and start listening)
+     */
+    start(): Promise<void>;
+    /**
+     * Close the message bus gracefully
+     */
+    close(): Promise<void>;
+    /**
+     * Check if the message bus is started
+     */
+    isStarted(): boolean;
+}
+
+/**
+ * Serialize a Command or Event to a Buffer for PubSub transport
+ *
+ * @param message - The message to serialize
+ * @returns Buffer containing the serialized message envelope
+ */
+declare function serialize(message: Command | Event): Buffer;
+/**
+ * Deserialize a Buffer from PubSub into a Command or Event
+ *
+ * @param buffer - The buffer containing the serialized message
+ * @returns The deserialized message
+ * @throws Error if the buffer cannot be deserialized
+ */
+declare function deserialize<T extends Command | Event>(buffer: Buffer): T;
+/**
+ * Attach a message ID to a message for idempotency tracking
+ *
+ * @param message - The message to attach ID to
+ * @param messageId - The message ID
+ * @returns The message with the ID attached
+ */
+declare function attachMessageId<T extends Message>(message: T, messageId: string): T & {
+    __messageId: string;
+};
+/**
+ * Extract message ID from a message
+ *
+ * @param message - The message to extract ID from
+ * @returns The message ID if present, undefined otherwise
+ */
+declare function extractMessageId(message: Message): string | undefined;
+
+/**
+ * Get command topic name
+ */
+declare function getCommandTopicName(commandType: string, prefix?: string): string;
+/**
+ * Get event topic name
+ */
+declare function getEventTopicName(eventType: string, prefix?: string): string;
+/**
+ * Get command subscription name
+ */
+declare function getCommandSubscriptionName(commandType: string, instanceId: string, prefix?: string): string;
+/**
+ * Get event subscription name
+ */
+declare function getEventSubscriptionName(eventType: string, subscriptionId: string, prefix?: string): string;
+/**
+ * Get or create a topic
+ *
+ * @param pubsub - PubSub client
+ * @param topicName - Name of the topic
+ * @returns The topic instance
+ */
+declare function getOrCreateTopic(pubsub: PubSub, topicName: string): Promise<Topic>;
+/**
+ * Get or create a subscription
+ *
+ * @param topic - The topic to subscribe to
+ * @param subscriptionName - Name of the subscription
+ * @param options - Subscription options
+ * @returns The subscription instance
+ */
+declare function getOrCreateSubscription(topic: Topic, subscriptionName: string, options?: SubscriptionOptions): Promise<Subscription>;
+/**
+ * Delete a subscription
+ *
+ * @param subscription - The subscription to delete
+ */
+declare function deleteSubscription(subscription: Subscription): Promise<void>;
+/**
+ * Delete multiple subscriptions
+ *
+ * @param subscriptions - Array of subscriptions to delete
+ */
+declare function deleteSubscriptions(subscriptions: Subscription[]): Promise<void>;
+
+/**
+ * Generate a random UUID
+ */
+declare function generateUUID(): string;
+/**
+ * Validate that a string is not empty
+ */
+declare function assertNotEmptyString(value: unknown, name: string): asserts value is string;
+/**
+ * Validate that a number is positive
+ */
+declare function assertPositiveNumber(value: unknown, name: string): asserts value is number;
+
+/**
+ * Schedule options for messages
+ */
+type ScheduleOptions = {
+    afterInMs: number;
+} | {
+    at: Date;
+};
+/**
+ * Scheduled message returned from dequeue
+ */
+interface ScheduledMessage {
+    message: Message;
+    options?: ScheduleOptions;
+}
+/**
+ * Scheduler configuration
+ */
+interface SchedulerConfig {
+    /**
+     * Whether running in emulator mode
+     */
+    useEmulator: boolean;
+    /**
+     * PubSub client instance
+     */
+    pubsub: PubSub;
+    /**
+     * Topic for scheduled messages (optional, created if needed)
+     */
+    scheduledTopic?: Topic;
+    /**
+     * Topic prefix for naming
+     * @default "emmett"
+     */
+    topicPrefix?: string;
+}
+/**
+ * Calculate scheduled time from options
+ *
+ * @param options - Schedule options (afterInMs or at)
+ * @returns The calculated scheduled time
+ */
+declare function calculateScheduledTime(options?: ScheduleOptions): Date;
+/**
+ * Filter messages that are ready for delivery
+ *
+ * @param pending - Array of pending scheduled messages
+ * @param now - Current time
+ * @returns Messages ready for delivery
+ */
+declare function filterReadyMessages(pending: ScheduledMessageInfo[], now: Date): ScheduledMessageInfo[];
+/**
+ * Message scheduler with dual mode support (production/emulator)
+ */
+declare class MessageScheduler {
+    private pendingMessages;
+    private readonly useEmulator;
+    private readonly pubsub;
+    private readonly topicPrefix;
+    private scheduledTopic?;
+    constructor(config: SchedulerConfig);
+    /**
+     * 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
+     */
+    schedule(message: Message, options?: ScheduleOptions): Promise<void>;
+    /**
+     * 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(): ScheduledMessage[];
+    /**
+     * Publish a scheduled message to PubSub (production mode)
+     *
+     * @param message - The message to publish
+     * @param scheduledAt - When the message should be delivered
+     */
+    private publishScheduledMessage;
+    /**
+     * Get count of pending scheduled messages (emulator mode only)
+     *
+     * @returns Number of pending scheduled messages
+     */
+    getPendingCount(): number;
+    /**
+     * Clear all pending scheduled messages (emulator mode only, useful for testing)
+     */
+    clearPending(): void;
+}
+
+/**
+ * Determine if an error should trigger a retry (nack) or be considered permanent (ack)
+ *
+ * @param error - The error to classify
+ * @returns true if the error is retriable (should nack), false if permanent (should ack)
+ */
+declare function shouldRetry(error: unknown): boolean;
+/**
+ * Process an incoming command message from PubSub
+ *
+ * @param message - The PubSub message
+ * @param handlers - Map of message type to handlers
+ * @param commandType - The command type being processed
+ * @returns 'ack' if successful or permanent failure, 'nack' if retriable failure
+ */
+declare function handleCommandMessage(message: Message$1, handlers: Map<string, SingleRawMessageHandlerWithoutContext<AnyMessage>[]>, commandType: string): Promise<'ack' | 'nack'>;
+/**
+ * Process an incoming event message from PubSub
+ *
+ * @param message - The PubSub message
+ * @param handlers - Map of message type to handlers
+ * @param eventType - The event type being processed
+ * @returns 'ack' if all handlers successful or permanent failure, 'nack' if retriable failure
+ */
+declare function handleEventMessage(message: Message$1, handlers: Map<string, SingleRawMessageHandlerWithoutContext<AnyMessage>[]>, eventType: string): Promise<'ack' | 'nack'>;
+/**
+ * Create a message listener for a PubSub subscription
+ *
+ * @param subscription - The PubSub subscription to listen on
+ * @param messageType - The message type (command or event type)
+ * @param kind - Whether this is a command or event
+ * @param handlers - Map of message type to handlers
+ */
+declare function createMessageListener(subscription: Subscription, messageType: string, kind: 'command' | 'event', handlers: Map<string, SingleRawMessageHandlerWithoutContext<AnyMessage>[]>): void;
+
+/**
+ * Create a Google Cloud Pub/Sub based message bus for Emmett
+ *
+ * @param config - Configuration for the PubSub message bus
+ * @returns A message bus implementation using Google Cloud Pub/Sub
+ *
+ * @example
+ * ```typescript
+ * import { PubSub } from '@google-cloud/pubsub';
+ * import { getPubSubMessageBus } from '@emmett-community/emmett-google-pubsub';
+ *
+ * const pubsub = new PubSub({ projectId: 'my-project' });
+ * const messageBus = getPubSubMessageBus({ pubsub });
+ *
+ * // Register handlers
+ * messageBus.handle(async (command) => {
+ *   // Handle command
+ * }, 'MyCommand');
+ *
+ * // Subscribe to events
+ * messageBus.subscribe(async (event) => {
+ *   // Handle event
+ * }, 'MyEvent');
+ *
+ * // Start the message bus
+ * await messageBus.start();
+ *
+ * // Send commands and publish events
+ * await messageBus.send({ type: 'MyCommand', data: { ... } });
+ * await messageBus.publish({ type: 'MyEvent', data: { ... } });
+ *
+ * // Close gracefully
+ * await messageBus.close();
+ * ```
+ */
+declare function getPubSubMessageBus(config: PubSubMessageBusConfig): MessageBus & EventSubscription & CommandProcessor & ScheduledMessageProcessor & PubSubMessageBusLifecycle;
+
+export { type HandlerRegistration, MessageScheduler, type PubSubMessageBusConfig, type PubSubMessageBusLifecycle, type PubSubMessageEnvelope, type ScheduleOptions, type ScheduledMessage, type ScheduledMessageInfo, type SchedulerConfig, type SubscriptionInfo, type SubscriptionOptions, assertNotEmptyString, assertPositiveNumber, attachMessageId, calculateScheduledTime, createMessageListener, deleteSubscription, deleteSubscriptions, deserialize, extractMessageId, filterReadyMessages, generateUUID, getCommandSubscriptionName, getCommandTopicName, getEventSubscriptionName, getEventTopicName, getOrCreateSubscription, getOrCreateTopic, getPubSubMessageBus, handleCommandMessage, handleEventMessage, serialize, shouldRetry };