README.md

May 27, 2026 · View on GitHub

nestjs-jetstream

The NATS JetStream transport NestJS microservices need — durable, retried, traced — under the same @EventPattern and @MessagePattern decorators you already use.

Documentation · Quick Start · API Reference

Why this exists

NestJS' built-in NATS transport loses messages on pod restart, doesn't retry on failure, and gives you nothing to debug with. JetStream fixes all three — but wiring it into NestJS by hand is a project on its own.

This library is the swap. Same @EventPattern, same @MessagePattern, same client.emit(). Durability, retries, and tracing underneath.

What you get

At-least-once delivery — every event acked after the handler resolves; bounded retries with exponential backoff.
Broadcast — one message reaches every running pod via per-service durable consumers.
Ordered delivery — sequential per partition key without giving up horizontal scale.
RPC — Core for speed, JetStream for durability — same @MessagePattern either way.
DLQ — typed sink with original headers preserved after retries are exhausted.
Scheduled messages, per-message TTL, health checks, graceful shutdown — all the production levers.
OpenTelemetry-compatible — W3C traceparent propagated through every hop.

Install

npm i @horizon-republic/nestjs-jetstream

Quick Start

// 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);
  }
}

That's it. At-least-once. Retries on throw. Traced end-to-end.

The full configuration surface, every pattern, and the production checklist live in the documentation.

Quality

The transport is covered by an extensive test suite (unit and integration) — see the Codecov report above.

Runnable demos for most supported patterns live under examples/.