How ssut/nestjs-sqs works
Project type and purpose
• This is a NestJS module library whose purpose is to simplify working with AWS SQS queues inside a Nest application.
• It provides decorator-based message handlers (consumers) and a service for sending messages (producers), built on top of the bbc/sqs-consumer and bbc/sqs-producer packages.
File structure
• lib/ contains the core implementation:
– sqs.module.ts – defines the Nest module and handles dynamic registration (register() / registerAsync()).
– sqs.service.ts – exposes send(name, message) and manages producer instances.
– sqs.decorators.ts – contains @SqsMessageHandler() and event-handler decorators.
– sqs.constants.ts & sqs.types.ts – configuration keys and type definitions.
• e2e/ contains an end-to-end test demonstrating module usage.
• Root config and CI/CD workflows manage linting, testing, publishing, and ElasticMQ setup.
Extract insights from the README
• The module uses AWS SQS or ElasticMQ under the hood.
• Consumers are long-running processes that poll SQS and invoke decorated methods on your Nest providers.
• Producers send messages via the SqsService to any named queue.
Main components
a. Nest Application
– The consumer of this library.
– Imports SqsModule in its root or feature module.
b. SqsModule
– Configures producers and consumers.
– Registers SqsService and sets up sqs-consumer clients.
c. SqsService
– Holds a registry of named producer instances.
– Uses bbc/sqs-producer to send messages to SQS.
d. Decorated Providers
– Any NestJS @Injectable() classes with @SqsMessageHandler() or @SqsConsumerEventHandler() decorators.
– Act as message callbacks.
e. bbc/sqs-consumer
– Polls AWS SQS queue(s).
– Routes incoming messages into Nest via the decorated methods.
f. AWS SQS / ElasticMQ
– The external queue service.
– Receives messages from producers; delivers messages to consumers.
g. bbc/sqs-producer
– Sends messages into AWS SQS.
Relationships and data flows
– Startup: Nest’s DI container loads SqsModule → configures consumer loops via bbc/sqs-consumer → binds decorated handlers.
– Message production: Nest component calls SqsService.send() → bbc/sqs-producer pushes the message to AWS SQS.
– Message consumption: bbc/sqs-consumer polls AWS SQS → on message received it invokes the corresponding @SqsMessageHandler in your provider.
– Error events: Consumer errors are emitted and routed to methods decorated with @SqsConsumerEventHandler.
Architectural patterns and design principles
• Modular design: NestJS module encapsulates SQS logic.
• Decorator pattern: Simplifies binding SQS events to handler methods.
• Dependency injection: Clean separation—your code only depends on SqsService and decorators, not the underlying SQS client.
• Adapter pattern: Wraps bbc/sqs-consumer / bbc/sqs-producer to fit Nest’s lifecycle.
Elements
• From NestApp → SqsModule (import)
• From SqsService → bbc/sqs-producer → AWS SQS
• From AWS SQS → bbc/sqs-consumer → Decorated Providers
• Blue rectangles for internal modules or classes (SqsModule, SqsService, Decorators).
• Green rectangles for third‐party libraries (bbc/sqs-producer, bbc/sqs-consumer).
– Annotations: note async registration options, batch vs. single‐message handling, and event hooks (e.g., processing_error).