nestjs-jetstream

A NATS JetStream transport for NestJS microservices.
Same @EventPattern and @MessagePattern decorators, with durability,
bounded retries, dead-letter queues and OpenTelemetry tracing underneath.

Documentation · Quick start · Header contract · Examples

---

The problem

NestJS includes a built-in NATS transport that is fire-and-forget. A pod restart loses whatever was in flight, a handler that throws is never retried, and when something goes wrong in production there is nothing to look at.

The swap

Same decorators, same client.emit(). One module import changes underneath.

// app.module.ts
@Module({
  imports: [JetstreamModule.forRoot({ servers: ['nats://localhost:4222'] })],
})
export class AppModule {}

// orders.controller.ts
@Controller()
export class OrdersController {
  @EventPattern('orders.created')
  async onCreated(@Payload() order: Order) {
    await this.billing.charge(order); // throws → nak → redelivered with backoff
  }
}

The transport acknowledges an event only after its handler resolves. A throw is a with exponential backoff. Exhausted retries go to a typed dead-letter queue with the original headers intact. A header rides through every hop.