NestJS NATS JetStream Transport

A NestJS microservice transport for NATS JetStream, providing seamless integration between NestJS microservices and NATS JetStream, a persistent streaming system built on top of NATS.

Installation

``bash
npm install @initbit/nestjs-jetstream @nestjs/microservices nats
`

Overview

This package provides a custom transport strategy for NestJS applications to communicate using NATS JetStream. It integrates with NestJS's microservices architecture and supports both message patterns (request-response) and event patterns (publish-subscribe).

Key Features

- Connect to NATS JetStream with configurable options
- Create and manage streams and consumers
- Multi-stream support with pattern-based routing
- Consumer caching for improved efficiency and resource usage
- Handle JetStream messages with acknowledgments
- Support for request-response patterns
- Support for event-based patterns
- Queue group support
- Configurable consumer options
- Proper connection management with reconnection handling
- Support for multiple server addresses for high availability
- Graceful shutdown and connection draining
- Advanced consumer configuration options (DeliverPolicy, AckPolicy, etc.)
- Direct access to NATS API through NatsContext
- Enhanced logging integration with NestJS application logger
- Server-side consumer filtering via filter_subject / filter_subjects for durable consumers

Note: this transport no longer creates a plain nc.subscribe(pattern, ...) fallback for event patterns. Consumers are expected to be JetStream consumers (server-side) and publishers should send events using JetStream (e.g., js.publish(...)) to ensure proper JetStream semantics (durable storage, acknowledgments, redelivery, etc.). For quick CLI testing you can still publish using the JetStream API (or configure a small dev-only fallback), but the library's default behavior is JetStream-first.
*

Usage

$3

You can register the module in two ways:

#### Static Registration

`typescript
import { Module } from '@nestjs/common';
import { NatsJetStreamModule } from '@initbit/nestjs-jetstream';

@Module({
imports: [
NatsJetStreamModule.register({
connection: {
servers: ['nats://localhost:4222']
},
// Stream configuration with name, description and subjects
stream: {
name: 'my-stream', // Stream name should be part of stream options
description: 'My stream for processing orders',
subjects: ['orders.*', 'users.events']
},
// Consumer configuration with name and other options
consumerOptions: {
name: 'my-consumer', // Consumer name should be part of consumer options
durable: true, // Set to false for ephemeral consumers
max_deliver: 10, // Maximum delivery attempts
ack_wait: 30_000_000_000 // 30 seconds in nanoseconds
},
// Queue group for load balancing
queue: 'processing-group'
})
]
})
export class AppModule {}
`

#### Multi-Stream Registration

`typescript
import { Module } from '@nestjs/common';
import { NatsJetStreamModule } from '@initbit/nestjs-jetstream';

@Module({
imports: [
NatsJetStreamModule.register({
connection: {
servers: ['nats://localhost:4222']
},
// Multi-stream configuration
multiStream: {
streams: [
{
name: 'orders-stream',
description: 'Stream for order processing',
subjects: ['orders.*']
},
{
name: 'users-stream',
description: 'Stream for user events',
subjects: ['users.*']
}
],
defaultStream: 'orders-stream',
// Map specific patterns to streams
patternToStream: new Map([
['orders.created', 'orders-stream'],
['users.registered', 'users-stream']
]),
// Consumer configuration per stream
streamConsumers: new Map([
['orders-stream', {
name: 'orders-consumer',
durable: true,
max_deliver: 5,
// Server-side filter: only receive these subjects for this consumer
filter_subjects: ['orders.created']
}],
['users-stream', {
name: 'users-consumer',
durable: true,
max_deliver: 3,
filter_subjects: ['users.registered']
}]
]),
// Register streams asynchronously for better performance
asyncRegistration: true
}
})
]
})
export class AppModule {}
`

#### Async Registration

`typescript
import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { NatsJetStreamModule } from '@initbit/nestjs-jetstream';

@Module({
imports: [
ConfigModule.forRoot(),
NatsJetStreamModule.registerAsync({
imports: [ConfigModule],
inject: [ConfigService],
useFactory: (configService: ConfigService) => ({
connection: {
servers: [configService.get('NATS_URL') || 'nats://localhost:4222']
},
// Stream configuration with name, description and subjects
stream: {
name: configService.get('NATS_STREAM') || 'my-stream',
description: configService.get('NATS_STREAM_DESCRIPTION') || 'My stream for processing events',
subjects: configService.get('NATS_STREAM_SUBJECTS') || ['events.', 'notifications.']
},
// Consumer configuration with name and other options
consumerOptions: {
name: configService.get('NATS_CONSUMER') || 'my-consumer',
durable: configService.get('NATS_CONSUMER_DURABLE') === 'true',
max_deliver: configService.get('NATS_MAX_DELIVER') || 10,
ack_wait: configService.get('NATS_ACK_WAIT_NS') || 30_000_000_000 // 30 seconds in nanoseconds
},
// Queue group for load balancing
queue: configService.get('NATS_QUEUE')
})
})
]
})
export class AppModule {}
`

$3

`typescript
import { NestFactory } from '@nestjs/core';
import { JetStream, JETSTREAM_TRANSPORT } from '@initbit/nestjs-jetstream';
import { AppModule } from './app.module';

async function bootstrap() {
const app = await NestFactory.create(AppModule);

// Get the JetStream transport from the module
const transport = app.get(JETSTREAM_TRANSPORT);

// Create a microservice with the transport
app.connectMicroservice({
strategy: transport
});

// Start the microservice
await app.startAllMicroservices();
await app.listen(3000);
}
bootstrap();
`

$3

`typescript
import { Controller } from '@nestjs/common';
import { EventPattern, MessagePattern } from '@nestjs/microservices';

@Controller()
export class AppController {
// Handle request-response patterns
@MessagePattern('get.user')
getUser(data: { id: string }) {
return { id: data.id, name: 'John Doe' };
}

// Handle event-based patterns
@EventPattern('user.created')
handleUserCreated(data: any) {
console.log('User created:', data);
}

// Handle multi-stream patterns
@EventPattern('orders.created')
handleOrderCreated(data: any) {
console.log('Order created:', data);
}

@EventPattern('users.registered')
handleUserRegistered(data: any) {
console.log('User registered:', data);
}
}
`

$3

`typescript
import { Injectable } from '@nestjs/common';
import { NatsClient, JETSTREAM_CLIENT } from '@initbit/nestjs-jetstream';
import { Inject } from '@nestjs/common';

@Injectable()
export class AppService {
constructor(
@Inject(JETSTREAM_CLIENT)
private readonly client: NatsClient
) {}

// Send a request and get a response
async getUser(id: string) {
return this.client.send('get.user', { id });
}

// Emit an event (no response)
async createUser(user: any) {
return this.client.emit('user.created', user);
}
}
`

$3

The transport provides a flexible message mapping system that allows you to control how incoming NATS messages are mapped to NestJS handlers. You can choose between two default mappers or provide your own custom mapper function.

#### Default Mappers

- subject (default): This mapper uses the NATS message subject as the handler key. The entire decoded message data is passed as the handler payload.
- envelope: This mapper assumes the message is in a specific envelope format with a type property. It uses the type property as the handler key and the payload property as the handler payload.

You can select the default mapper using the defaultMapper option:

`typescript
NatsJetStreamModule.register({
// ... other options
defaultMapper: 'envelope'
})
`

#### Custom Mapper Function

For more advanced scenarios, you can provide a custom mapper function. This function takes the NATS message (JsMsg) and the decoded data as input and should return an object with handlerKey and data properties.

`typescript
import { JsMsg } from 'nats';
import { JetStreamMapper } from '@initbit/nestjs-jetstream';

const customMapper: JetStreamMapper = (msg: JsMsg, decoded: unknown) => {
// Your custom logic to determine the handler key and data
if ((decoded as any).eventType) {
return {
handlerKey: (decoded as any).eventType,
data: (decoded as any).eventData,
ctxExtras: (decoded as any).meta,
};
}
return { handlerKey: msg.subject, data: decoded };
};

@Module({
imports: [
NatsJetStreamModule.register({
// ... other options
mapper: customMapper,
}),
],
})
export class AppModule {}
`

$3

The JetStream transport supports advanced consumer configuration options:

`typescript
import { Module } from '@nestjs/common';
import { NatsJetStreamModule } from '@initbit/nestjs-jetstream';
import { DeliverPolicy, AckPolicy } from 'nats';

@Module({
imports: [
NatsJetStreamModule.register({
connection: {
servers: ['nats://localhost:4222']
},
// Stream configuration
stream: {
name: 'my-stream',
subjects: ['orders.', 'users.'] // Define subjects for the stream
},
// Advanced consumer configuration
consumerOptions: {
name: 'my-consumer',
deliver_policy: DeliverPolicy.New,
ack_policy: AckPolicy.Explicit,
ack_wait: 30_000_000_000, // 30 seconds in nanoseconds
filter_subject: 'orders.created',
// Or use multiple filter subjects
filter_subjects: ['orders.created', 'orders.updated'],
// Additional consumer options
max_deliver: 10,
max_ack_pending: 100
}
})
]
})
export class AppModule {}
`

$3

Version 1.3.1 introduces additional consumer configuration options for production-grade deployments:

`typescript
import { Module } from '@nestjs/common';
import { NatsJetStreamModule } from '@initbit/nestjs-jetstream';
import { DeliverPolicy, AckPolicy, ReplayPolicy } from 'nats';

@Module({
imports: [
NatsJetStreamModule.register({
connection: {
servers: ['nats://localhost:4222']
},
stream: {
name: 'ticket-stream',
subjects: ['ticket.events.', 'ticket.commands.']
},
consumerOptions: {
// Separate consumer name from durable name (v1.3.1)
name: 'ticket-processor-consumer',
durable: true,

// Control replay behavior (v1.3.1)
replay_policy: ReplayPolicy.Instant, // or ReplayPolicy.Original

// Standard consumer options
deliver_policy: DeliverPolicy.All,
ack_policy: AckPolicy.Explicit,
ack_wait: 30_000_000_000, // 30 seconds

// Enhanced configuration (v1.3.1)
max_waiting: 512, // Max waiting pulls
backoff: [1, 2, 5, 10, 30, 60, 120, 300], // Backoff in seconds
inactive_threshold: 300_000_000_000, // 5 minutes in nanoseconds
num_replicas: 3, // For high availability
mem_storage: true, // Use memory storage
sample_freq: '10%', // Sample 10% of messages

// Filter configuration
filter_subject: 'ticket.events.*',
max_deliver: 3,
max_ack_pending: 100
}
})
]
})
export class AppModule {}
`

$3

The following example shows a full NestJS module registration that configures two streams and durable consumers for each stream. It also includes a minimal controller that demonstrates how to handle messages coming from durable consumers and use NatsContext to ack() / nack() / term() messages.

`typescript
import { Module, Injectable, Controller } from '@nestjs/common';
import { NatsJetStreamModule, NatsClient, JETSTREAM_CLIENT, ConsumerHealthService, NatsContext } from '@initbit/nestjs-jetstream';
import { EventPattern, Ctx } from '@nestjs/microservices';
import { DeliverPolicy, AckPolicy } from 'nats';

@Module({
imports: [
NatsJetStreamModule.register({
connection: { servers: ['nats://localhost:4222'] },

// Configure multi-stream topology
multiStream: {
streams: [
{
name: 'orders-stream',
description: 'Stream for order events',
subjects: ['orders.*']
},
{
name: 'users-stream',
description: 'Stream for user events',
subjects: ['users.*']
}
],

// map specific patterns to streams
patternToStream: new Map([
['orders.created', 'orders-stream'],
['orders.updated', 'orders-stream'],
['users.registered', 'users-stream']
]),

// define durable consumers per-stream
streamConsumers: new Map([
['orders-stream', {
name: 'orders-durable-consumer',
durable: true,
// high-throughput friendly defaults
ack_wait: 30_000_000_000, // 30s in ns
deliver_policy: DeliverPolicy.New,
ack_policy: AckPolicy.Explicit,
max_deliver: 10,
max_ack_pending: 500,
// Server-side filter subjects for this durable consumer
filter_subjects: ['orders.created']
}],
['users-stream', {
name: 'users-durable-consumer',
durable: true,
ack_wait: 30_000_000_000,
deliver_policy: DeliverPolicy.All,
ack_policy: AckPolicy.Explicit,
max_deliver: 5,
max_ack_pending: 200,
filter_subjects: ['users.registered']
}]
])
},

// optional: provide an application name used for naming when needed
appName: 'my-app'
})
]
})
export class AppModule {}

// Controller that handles events routed to streams above
@Controller()
export class EventsController {
// An order created event will be routed to the orders-stream and handled by this method
@EventPattern('orders.created')
async handleOrderCreated(data: any, @Ctx() ctx: NatsContext) {
try {
// Business logic
console.log('Processing order.created:', data);

// Acknowledge on success (durable consumer)
if (ctx.isJetStream()) ctx.ack();
} catch (err: any) {
// For retryable errors, negative-ack; for terminal errors, terminate
if (ctx.isJetStream()) {
if (err && err.retryable) ctx.nack();
else ctx.term();
}
throw err;
}
}

@EventPattern('users.registered')
async handleUserRegistered(data: any, @Ctx() ctx: NatsContext) {
try {
console.log('Processing users.registered:', data);
if (ctx.isJetStream()) ctx.ack();
} catch (err: any) {
if (ctx.isJetStream()) {
if (err && err.retryable) ctx.nack();
else ctx.term();
}
throw err;
}
}
}
`

Notes and best-practices for durable consumers

- Use durable consumers when you need at-least-once processing and stable consumer state across restarts. Durable consumers keep track of the last acknowledged sequence.
- Configure ack_wait in nanoseconds (the NATS JetStream API expects nanoseconds) — in the example above we use 30_000_000_000 to represent 30 seconds.
- max_deliver controls how many times a message will be redelivered on failures; set it according to your retry strategy.
- max_ack_pending allows you to tune how many un-acked messages can be outstanding — useful for throughput tuning.
- When using envelope-based messages, the module will still map patterns to the configured streams via patternToStream.

Querying consumer health

If you need to monitor durable consumers, inject ConsumerHealthService (exported by the module) and subscribe to health updates:

`typescript
@Injectable()
export class DurableConsumerMonitor {
constructor(private readonly consumerHealthService: ConsumerHealthService) {
// subscribe to updates
this.consumerHealthService.onHealthUpdate(this.onUpdate.bind(this));
}

onUpdate(health: any) {
// react to unhealthy consumers (alerts, metrics, scaling)
if (health.status !== 'active') {
console.warn('Consumer unhealthy', health);
}
}
}
`

Configuration Options

The NatsJetStreamOptions interface provides the following configuration options:

$3


- connection: NATS connection options
- codec: NATS codec for encoding and decoding messages
- consumer: Function to configure JetStream consumer options
- queue: Queue group name for NATS queue subscriptions
- logger: Logger service to use for logging

$3

- mapper: Custom mapper function for incoming messages (see Custom Message Mapping)
- defaultMapper: Default mapper to use if no custom mapper is provided. Can be 'subject' (default) or 'envelope'

$3

- stream: Configuration options for the NATS stream
- name: Name of the stream (replaces top-level streamName)
- description: Description of the stream
- subjects: Array of subjects associated with the stream (if not provided, defaults to ['*', '>'])

$3

- multiStream: Configuration for multiple streams
- streams: Array of stream configurations
- defaultStream: Default stream name for backward compatibility
- patternToStream: Mapping of event patterns to specific streams
- streamConsumers: Consumer configuration per stream
- asyncRegistration: Whether to register streams asynchronously

$3

- consumerOptions: Configuration options for the NATS consumer
- name: Name of the consumer (separate from and replaces durable_name)
- durable: Whether this consumer should be durable (if false, name will be ignored)
- deliver_policy: Delivery policy for the consumer (e.g., DeliverPolicy.All, DeliverPolicy.New)
- ack_policy: Acknowledgment policy for the consumer (e.g., AckPolicy.Explicit, AckPolicy.None)
- ack_wait: How long to wait for an acknowledgment (in nanoseconds)
- replay_policy: How to replay messages (e.g., ReplayPolicy.Original, ReplayPolicy.Instant) New in v1.3.1
- filter_subject: A single subject to filter messages from the stream
- filter_subjects: Multiple subjects to filter messages from the stream
- max_waiting: Maximum number of waiting pulls New in v1.3.1
- backoff: Backoff intervals for retries (array of seconds) New in v1.3.1
- inactive_threshold: Threshold for marking consumer as inactive (in nanoseconds) New in v1.3.1
- num_replicas: Number of replicas New in v1.3.1
- mem_storage: Use memory storage flag New in v1.3.1
- sample_freq: Sampling frequency New in v1.3.1
- Plus any other properties from the NATS ConsumerConfig interface (max_deliver, max_ack_pending, etc.)

$3

- appName: Application name for consumer naming (defaults to 'nestjs-app')

$3

- streamName: DEPRECATED - JetStream stream name (use stream.name instead)
- durableName: DEPRECATED - JetStream durable consumer name (use consumerOptions.name instead)
- deliverPolicy: DEPRECATED - Delivery policy for the consumer (use consumerOptions.deliver_policy instead)
- ackPolicy: DEPRECATED - Acknowledgment policy for the consumer (use consumerOptions.ack_policy instead)
- ackWait: DEPRECATED - How long to wait for an acknowledgment in seconds (use consumerOptions.ack_wait in nanoseconds instead)
- filterSubject: DEPRECATED - A single subject to filter messages (use consumerOptions.filter_subject instead)
- filterSubjects: DEPRECATED - Multiple subjects to filter messages (use consumerOptions.filter_subjects instead)

> Important: These legacy options are now officially deprecated and will be removed in the next major release. Please migrate to the recommended structured options as soon as possible.

Technical Requirements

- Compatible with NestJS versions 9, 10, and 11
- Requires Node.js version 18 or higher
- Uses NATS client library version 2.x
- TypeScript support for type safety

Future Roadmap

The following improvements are planned for future releases:

$3

- Fix critical bugs in the codebase
- Address inconsistencies in the API
- Improve basic documentation

$3

- Implement missing features
- Enhance error handling
- Improve type definitions
- Increase test coverage

$3

- Optimize performance for high-throughput scenarios
- Enhance developer experience with better APIs
- Add comprehensive documentation

$3

- Implement plugin system
- Add middleware support
- Create additional utilities and helpers

Recent Improvements

The following improvements have been implemented in recent releases:

$3

- Separate Consumer Names: Consumer name field is now separate from durable_name for better identification and management
- Advanced Consumer Options: Added support for additional consumer configuration:
- max_waiting: Maximum number of waiting pulls for better flow control
- backoff: Configurable backoff intervals for retries (array of seconds)
- replay_policy: Control how messages are replayed (Original, Instant, etc.)
- inactive_threshold: Threshold for marking consumer as inactive
- num_replicas: Number of replicas for high availability
- mem_storage: Memory storage option for performance optimization
- sample_freq: Sampling frequency for monitoring
- Durable Consumer Optimization: Removed unnecessary deliver_subject for durable consumers, improving efficiency
- Backward Compatibility: All legacy configuration options remain supported during migration period

$3

- High-Throughput Message Processing: Optimized message handling for better performance in high-load scenarios
- Enhanced Connection Management: Improved connection handling with better error recovery and resource cleanup
- Optimized Consumer Management: More efficient consumer creation and subscription handling
- Consumer Health Monitoring: New tools to monitor and report on consumer health metrics
- Developer-Friendly APIs: Intuitive interfaces for working with streams and consumers
- Comprehensive Error Handling: Better error messages and recovery strategies

$3

- Bug Fix: Fixed potential infinite loop in handleStatusUpdates method
- Memory Leak Prevention: Added proper termination conditions for status update loop
- Error Handling: Improved error handling with try/catch/finally blocks
- Connection Monitoring: Added connection state monitoring to properly end status updates

$3

- New Feature: Support for multiple streams with pattern-based routing
- StreamManager: Dedicated class for managing multiple streams and their consumers
- Pattern Mapping: Map specific event patterns to dedicated streams
- Per-Stream Consumers: Configure different consumer settings for each stream
- Async Registration: Option to register streams asynchronously for better performance
- Backward Compatibility: Maintains compatibility with single-stream configurations

$3

- Performance Improvement: Consumer caching to reuse consumers with the same inbox or deliver_subject
- Resource Efficiency: Reduces resource usage by sharing consumers across multiple event patterns
- Durable Consumer Support: Proper handling of durable consumers with cache key including durable name
- Stream-Pattern Mapping: Efficient consumer reuse based on stream name and pattern combinations

$3

- Structured Options: New structured stream and consumerOptions configuration objects
- Multi-Stream Configuration: New multiStream option for complex multi-stream setups
- Application Naming: appName option for better consumer naming and identification
- Improved Type Safety: Better TypeScript interfaces and type definitions

$3

- Legacy registration options have been officially deprecated and will be removed in the next major release
- This includes: streamName, durableName, deliverPolicy, ackPolicy, ackWait, filterSubject, and filterSubjects
- Users should migrate to the structured options (stream and consumerOptions) as soon as possible
- The library will continue to support legacy options until the next major release for backward compatibility

$3

- The package now properly integrates with NestJS application logger
- When configured with app.useLogger(app.get(Logger)), the transport will use the application's logger
- Logger can be provided via the options object: NatsJetStreamModule.register({ logger: yourLogger })
- Both NatsClient and JetStream classes now accept a logger through their options

$3

- Improved event emission reliability with automatic reconnection
- Added retry logic with exponential backoff for failed event publications
- Specific handling for 503 errors (service unavailable) with reconnection attempts
- Better error reporting and logging for event dispatch issues

$3

- Fixed an issue where subject subscriptions were always prefixed with the stream name
- Event patterns like @EventPattern('domain.user.greet') now subscribe correctly without modification
- Stream configuration now uses wildcard subjects (*, >) to capture all patterns

$3

- When subscribing to subject patterns, the transport now stores a mapping between the subject and handler key if envelope mapping is selected
- This ensures that even if the type in an incoming message doesn't match a handler key directly, the transport can still find the correct handler based on the subscription subject
- This provides greater flexibility and backward compatibility for applications using envelope-based routing

$3

- Added support for custom message mapping through the mapper option
- Introduced defaultMapper option to choose between 'subject' (default) and 'envelope' mapping strategies
- Custom mappers allow complete control over how NATS messages are mapped to NestJS handlers
- Envelope mapper provides backward compatibility for message envelope patterns with type and payload properties
- Subject-to-handler mapping system ensures correct routing when using envelope mode with different subject patterns

$3

- Added logger option to NatsJetStreamOptions and NatsClientOptions interfaces
- Updated the module to properly inject and use the provided logger
- Added mapper and defaultMapper options for custom message mapping

Building

Run nx build nats-jetstream to build the library.

Running unit tests

Run nx test nats-jetstream` to execute the unit tests via Jest.

License

This package is open source and available under the MIT License.

Repository

This package is part of the nestjs-common-package monorepo. You can find the source code for this package in the packages/nats-jetstream directory.

Issues and Bug Reports

If you encounter any issues or bugs, please report them on our GitHub Issues page.

When reporting an issue, please include:
- A clear and descriptive title
- Steps to reproduce the issue
- Expected behavior
- Actual behavior
- Any relevant logs or error messages
- Your environment (Node.js version, NestJS version, etc.)