PubSub Service API

Decorator-driven Pub/Sub message handling framework for NestJS.

What It Does

The PubSub Service API provides a decorator-based framework for building Pub/Sub microservices in NestJS. It automatically discovers topic subscriptions, registers handlers, and manages message parsing and acknowledgment with zero boilerplate code.

Key Capabilities

• Decorator-Based: Define subscriptions with @Subscription() decorator
• Automatic Discovery: NestJS Discovery service finds all handlers
• Message Parsing: Automatic pubsub message parsing
• Error Handling: Silent error logging for failed handlers
• Message Acknowledgment: Auto-ack before processing
• Type Safety: Full TypeScript support
• Dependency Injection: Handlers are NestJS services

Main Components

Decorators

@TopicHandler()

@TopicHandler()
class MyTopicService {
  // Handler methods here
}

Marks class as topic handler (makes it Injectable).

@Subscription(topicName)

@Subscription('user-created')
handleUserCreated(event: UserCreatedEvent) {
  // Process event
}

Registers method as handler for specific topic.

@PubsubModule()

@PubsubModule({topicHandlers: [MyTopicService]})
export class AppModule {}

Registers topic handlers in NestJS module.

Bootstrap Function

bootstrapPubsub(AppModule)

Initializes application, discovers subscriptions, registers handlers.

Usage Pattern

@TopicHandler()
class NotificationService {
  @Subscription('sub-user-registered')
  async sendWelcomeEmail(event: Event<User>) {
    const {item} = event
    await this.emailService.send(item.email, 'Welcome!')
  }
 
  @Subscription('sub-order-completed')
  async sendReceipt(event: Event<Order>) {
    // Send receipt
  }
}
 
@PubsubModule({topicHandlers: [NotificationService]})
export class AppModule {}
 
bootstrapPubsub(AppModule)

Common Use Cases

• Event-driven microservices
• Async message processing
• Topic-based workflows
• Decoupled service communication
• Real-time event handling

What Customers Don’t Have to Build

• Topic subscription management
• Message parsing logic
• Handler discovery and registration
• Message acknowledgment
• Error handling wrappers
• Bootstrap orchestration
• NestJS module configuration
• PubSubSubscriptionManager integration