@emmett-community/emmett-google-pubsub 0.1.0 → 0.3.0

package/README.md

@@ -2,20 +2,18 @@
 
 Google Cloud Pub/Sub message bus implementation for [Emmett](https://event-driven-io.github.io/emmett/), the Node.js event sourcing framework.
 
-[![npm version](https://img.shields.io/npm/v/@emmett-community/emmett-google-pubsub.svg)](https://www.npmjs.com/package/@emmett-community/emmett-google-pubsub)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://img.shields.io/npm/v/@emmett-community/emmett-google-pubsub.svg)](https://www.npmjs.com/package/@emmett-community/emmett-google-pubsub) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ## Features
 
-- **Distributed Message Bus** - Scale command/event handling across multiple instances
-- **Type-Safe** - Full TypeScript support with comprehensive types
-- **Automatic Topic Management** - Auto-creates topics and subscriptions
-- **Message Scheduling** - Schedule commands/events for future execution
-- **Error Handling** - Built-in retry logic and dead letter queue support
-- **Emulator Support** - Local development with PubSub emulator
-- **Testing Utilities** - Helper functions for easy testing
-- **Emmett Compatible** - Drop-in replacement for in-memory message bus
-- **Producer-Only Mode** - Use without starting consumers
+- ✅ **Distributed Message Bus** - Scale command/event handling across multiple instances
+- ✅ **Type-Safe** - Full TypeScript support with comprehensive types
+- ✅ **Automatic Topic Management** - Auto-creates topics and subscriptions
+- ✅ **Message Scheduling** - Schedule commands/events for future execution
+- ✅ **Error Handling** - Built-in retry logic and dead letter queue support
+- ✅ **Emulator Support** - Local development with PubSub emulator
+- ✅ **Emmett Compatible** - Drop-in replacement for in-memory message bus
+- ✅ **Producer-Only Mode** - Use without starting consumers
 
 ## Installation
 
@@ -23,6 +21,10 @@ Google Cloud Pub/Sub message bus implementation for [Emmett](https://event-drive
 npm install @emmett-community/emmett-google-pubsub @google-cloud/pubsub
 ```
 
+### Peer Dependencies
+
+- `@event-driven-io/emmett` ^0.39.0
+
 ## Quick Start
 
 ```typescript
@@ -259,20 +261,21 @@ describe('My Tests', () => {
 ### Running Tests
 
 ```bash
-# Start PubSub emulator
-gcloud beta emulators pubsub start --project=test-project
+# Unit tests
+npm run test:unit
 
-# Or use Docker
-docker run -p 8085:8085 gcr.io/google.com/cloudsdktool/google-cloud-cli:emulators \
-  gcloud beta emulators pubsub start --host-port=0.0.0.0:8085
+# Integration tests (in-memory)
+npm run test:int
 
-# Set environment variable
-export PUBSUB_EMULATOR_HOST=localhost:8085
+# E2E tests (PubSub emulator via Testcontainers, requires Docker)
+npm run test:e2e
 
-# Run tests
+# All tests
 npm test
 ```
 
+E2E tests start the emulator automatically via Testcontainers.
+
 ## Examples
 
 ### Complete Shopping Cart Example
@@ -375,6 +378,65 @@ JavaScript `Date` objects are preserved through serialization:
 
 See [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) for design decisions.
 
+## Observability
+
+The package supports optional observability through structured logging and OpenTelemetry tracing.
+
+### Logging
+
+Logging is opt-in and completely silent by default. To enable logging, provide a logger that implements the canonical `(context, message)` contract:
+
+```typescript
+const messageBus = getPubSubMessageBus({
+  pubsub,
+  observability: {
+    logger: {
+      debug: (context, message) => console.debug(message, context),
+      info: (context, message) => console.info(message, context),
+      warn: (context, message) => console.warn(message, context),
+      error: (context, message) => console.error(message, context),
+    },
+  },
+});
+```
+
+**Logger Contract:**
+
+The logger MUST implement the canonical `(context, message)` contract:
+
+- `context`: Structured data as `Record<string, unknown>` (first parameter)
+- `message`: Human-readable log message (second parameter, optional)
+
+Pino is natively compatible. For Winston, use an adapter.
+
+**Log Levels:**
+
+- `info` - Lifecycle events (start, stop)
+- `debug` - External I/O operations (publish, subscribe)
+- `warn` - Recoverable failures (timeouts, retries)
+- `error` - Failures (with Error objects in `{ err: error }` format)
+
+### Tracing (OpenTelemetry)
+
+The package creates OpenTelemetry spans for key operations. Tracing is passive - the `@opentelemetry/api` is a no-op by default.
+
+To enable tracing, configure OpenTelemetry in your application:
+
+```typescript
+import { NodeSDK } from '@opentelemetry/sdk-node';
+const sdk = new NodeSDK({ /* config */ });
+sdk.start();
+
+// Spans from emmett-google-pubsub are now captured
+const messageBus = getPubSubMessageBus({ pubsub });
+```
+
+**Notes:**
+
+- The package never initializes OpenTelemetry
+- No tracing flags needed - spans are always created (no-op if SDK not initialized)
+- Message types and payloads are never included in spans or logs
+
 ## Compatibility
 
 - **Node.js**: >= 18.0.0
@@ -406,9 +468,12 @@ npm test
 # Run unit tests only
 npm run test:unit
 
-# Run integration tests (requires emulator)
+# Run integration tests (in-memory)
 npm run test:int
 
+# Run E2E tests (requires Docker)
+npm run test:e2e
+
 # Lint
 npm run lint
 
@@ -420,19 +485,18 @@ npm run format
 
 MIT
 
-## Resources
+## Related Packages
 
-- [Emmett Documentation](https://event-driven-io.github.io/emmett/)
-- [Google Cloud Pub/Sub Docs](https://cloud.google.com/pubsub/docs)
-- [GitHub Repository](https://github.com/emmett-community/emmett-google-pubsub)
+- [@event-driven-io/emmett](https://github.com/event-driven-io/emmett) - Core Emmett framework
+- [@emmett-community/emmett-google-firestore](https://github.com/emmett-community/emmett-google-firestore) - Firestore event store
+- [@emmett-community/emmett-google-realtime-db](https://github.com/emmett-community/emmett-google-realtime-db) - Realtime Database inline projections
+- [@event-driven-io/emmett-mongodb](https://github.com/event-driven-io/emmett/tree/main/src/packages/emmett-mongodb) - MongoDB event store
 
 ## Support
 
-- **Issues**: [GitHub Issues](https://github.com/emmett-community/emmett-google-pubsub/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/emmett-community/emmett-google-pubsub/discussions)
-- **Emmett Discord**: [Join Discord](https://discord.gg/fTpqUTMmVa)
+- [GitHub Issues](https://github.com/emmett-community/emmett-google-pubsub/issues)
+- [Emmett Documentation](https://event-driven-io.github.io/emmett/)
 
-## Acknowledgments
+---
 
-- Built for the [Emmett](https://event-driven-io.github.io/emmett/) framework by [Oskar Dudycz](https://github.com/oskardudycz)
-- Part of the [Emmett Community](https://github.com/emmett-community)
+Made with ❤️ by the Emmett Community

package/dist/index.d.mts

@@ -1,6 +1,45 @@
 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';
 
+/**
+ * Canonical Logger contract for the Emmett ecosystem.
+ *
+ * DO NOT MODIFY this interface without updating ALL packages in the ecosystem.
+ *
+ * This package defines the canonical Logger interface.
+ * Implementations (Pino, Winston, etc.) MUST adapt to this contract.
+ * This contract MUST NOT adapt to any specific implementation.
+ *
+ * Semantic Rules:
+ * - context (first parameter): ALWAYS structured data as Record<string, unknown>
+ * - message (second parameter): ALWAYS the human-readable log message
+ * - The order is NEVER inverted
+ * - The (message, data) form is NOT valid for this contract
+ * - Error objects MUST use the 'err' key (frozen semantic)
+ *
+ * @example
+ * ```typescript
+ * // Pino - native compatibility
+ * import pino from 'pino';
+ * const logger = pino();
+ * // logger.info({ orderId }, 'Order created') matches our contract
+ * ```
+ */
+interface Logger {
+    debug(context: Record<string, unknown>, message?: string): void;
+    info(context: Record<string, unknown>, message?: string): void;
+    warn(context: Record<string, unknown>, message?: string): void;
+    error(context: Record<string, unknown>, message?: string): void;
+}
+/**
+ * Observability configuration options.
+ */
+interface ObservabilityOptions {
+    /**
+     * Optional logger instance. When not provided, the library operates silently.
+     */
+    logger?: Logger;
+}
 /**
  * Configuration for PubSub MessageBus
  */
@@ -43,6 +82,11 @@ interface PubSubMessageBusConfig {
      * @default true
      */
     closePubSubClient?: boolean;
+    /**
+     * Observability options (logging).
+     * If not provided, the package remains silent.
+     */
+    observability?: ObservabilityOptions;
 }
 /**
  * Subscription configuration options
@@ -217,14 +261,16 @@ declare function getOrCreateSubscription(topic: Topic, subscriptionName: string,
  * Delete a subscription
  *
  * @param subscription - The subscription to delete
+ * @param logger - Optional logger for observability
  */
-declare function deleteSubscription(subscription: Subscription): Promise<void>;
+declare function deleteSubscription(subscription: Subscription, logger?: Logger): Promise<void>;
 /**
  * Delete multiple subscriptions
  *
  * @param subscriptions - Array of subscriptions to delete
+ * @param logger - Optional logger for observability
  */
-declare function deleteSubscriptions(subscriptions: Subscription[]): Promise<void>;
+declare function deleteSubscriptions(subscriptions: Subscription[], logger?: Logger): Promise<void>;
 
 /**
  * Generate a random UUID
@@ -351,18 +397,20 @@ declare function shouldRetry(error: unknown): boolean;
  * @param message - The PubSub message
  * @param handlers - Map of message type to handlers
  * @param commandType - The command type being processed
+ * @param logger - Optional logger for observability
  * @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'>;
+declare function handleCommandMessage(message: Message$1, handlers: Map<string, SingleRawMessageHandlerWithoutContext<AnyMessage>[]>, commandType: string, logger?: Logger): 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
+ * @param logger - Optional logger for observability
  * @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'>;
+declare function handleEventMessage(message: Message$1, handlers: Map<string, SingleRawMessageHandlerWithoutContext<AnyMessage>[]>, eventType: string, logger?: Logger): Promise<'ack' | 'nack'>;
 /**
  * Create a message listener for a PubSub subscription
  *
@@ -370,8 +418,9 @@ declare function handleEventMessage(message: Message$1, handlers: Map<string, Si
  * @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
+ * @param logger - Optional logger for observability
  */
-declare function createMessageListener(subscription: Subscription, messageType: string, kind: 'command' | 'event', handlers: Map<string, SingleRawMessageHandlerWithoutContext<AnyMessage>[]>): void;
+declare function createMessageListener(subscription: Subscription, messageType: string, kind: 'command' | 'event', handlers: Map<string, SingleRawMessageHandlerWithoutContext<AnyMessage>[]>, logger?: Logger): void;
 
 /**
  * Create a Google Cloud Pub/Sub based message bus for Emmett
@@ -410,4 +459,4 @@ declare function createMessageListener(subscription: Subscription, messageType:
  */
 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 };
+export { type HandlerRegistration, type Logger, MessageScheduler, type ObservabilityOptions, 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 };

package/dist/index.d.ts

@@ -1,6 +1,45 @@
 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';
 
+/**
+ * Canonical Logger contract for the Emmett ecosystem.
+ *
+ * DO NOT MODIFY this interface without updating ALL packages in the ecosystem.
+ *
+ * This package defines the canonical Logger interface.
+ * Implementations (Pino, Winston, etc.) MUST adapt to this contract.
+ * This contract MUST NOT adapt to any specific implementation.
+ *
+ * Semantic Rules:
+ * - context (first parameter): ALWAYS structured data as Record<string, unknown>
+ * - message (second parameter): ALWAYS the human-readable log message
+ * - The order is NEVER inverted
+ * - The (message, data) form is NOT valid for this contract
+ * - Error objects MUST use the 'err' key (frozen semantic)
+ *
+ * @example
+ * ```typescript
+ * // Pino - native compatibility
+ * import pino from 'pino';
+ * const logger = pino();
+ * // logger.info({ orderId }, 'Order created') matches our contract
+ * ```
+ */
+interface Logger {
+    debug(context: Record<string, unknown>, message?: string): void;
+    info(context: Record<string, unknown>, message?: string): void;
+    warn(context: Record<string, unknown>, message?: string): void;
+    error(context: Record<string, unknown>, message?: string): void;
+}
+/**
+ * Observability configuration options.
+ */
+interface ObservabilityOptions {
+    /**
+     * Optional logger instance. When not provided, the library operates silently.
+     */
+    logger?: Logger;
+}
 /**
  * Configuration for PubSub MessageBus
  */
@@ -43,6 +82,11 @@ interface PubSubMessageBusConfig {
      * @default true
      */
     closePubSubClient?: boolean;
+    /**
+     * Observability options (logging).
+     * If not provided, the package remains silent.
+     */
+    observability?: ObservabilityOptions;
 }
 /**
  * Subscription configuration options
@@ -217,14 +261,16 @@ declare function getOrCreateSubscription(topic: Topic, subscriptionName: string,
  * Delete a subscription
  *
  * @param subscription - The subscription to delete
+ * @param logger - Optional logger for observability
  */
-declare function deleteSubscription(subscription: Subscription): Promise<void>;
+declare function deleteSubscription(subscription: Subscription, logger?: Logger): Promise<void>;
 /**
  * Delete multiple subscriptions
  *
  * @param subscriptions - Array of subscriptions to delete
+ * @param logger - Optional logger for observability
  */
-declare function deleteSubscriptions(subscriptions: Subscription[]): Promise<void>;
+declare function deleteSubscriptions(subscriptions: Subscription[], logger?: Logger): Promise<void>;
 
 /**
  * Generate a random UUID
@@ -351,18 +397,20 @@ declare function shouldRetry(error: unknown): boolean;
  * @param message - The PubSub message
  * @param handlers - Map of message type to handlers
  * @param commandType - The command type being processed
+ * @param logger - Optional logger for observability
  * @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'>;
+declare function handleCommandMessage(message: Message$1, handlers: Map<string, SingleRawMessageHandlerWithoutContext<AnyMessage>[]>, commandType: string, logger?: Logger): 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
+ * @param logger - Optional logger for observability
  * @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'>;
+declare function handleEventMessage(message: Message$1, handlers: Map<string, SingleRawMessageHandlerWithoutContext<AnyMessage>[]>, eventType: string, logger?: Logger): Promise<'ack' | 'nack'>;
 /**
  * Create a message listener for a PubSub subscription
  *
@@ -370,8 +418,9 @@ declare function handleEventMessage(message: Message$1, handlers: Map<string, Si
  * @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
+ * @param logger - Optional logger for observability
  */
-declare function createMessageListener(subscription: Subscription, messageType: string, kind: 'command' | 'event', handlers: Map<string, SingleRawMessageHandlerWithoutContext<AnyMessage>[]>): void;
+declare function createMessageListener(subscription: Subscription, messageType: string, kind: 'command' | 'event', handlers: Map<string, SingleRawMessageHandlerWithoutContext<AnyMessage>[]>, logger?: Logger): void;
 
 /**
  * Create a Google Cloud Pub/Sub based message bus for Emmett
@@ -410,4 +459,4 @@ declare function createMessageListener(subscription: Subscription, messageType:
  */
 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 };
+export { type HandlerRegistration, type Logger, MessageScheduler, type ObservabilityOptions, 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 };