Skip to main content

JetstreamModuleOptions

Defined in: src/interfaces/options.interface.ts:174

Root module configuration for JetstreamModule.forRoot().

Minimal usage requires only name and servers. All other fields have production-ready defaults.

Properties​

allowDestructiveMigration?​

optional allowDestructiveMigration?: boolean

Defined in: src/interfaces/options.interface.ts:287

Allow destructive stream migration when immutable config changes are detected.

When true, the transport will recreate streams (via blue-green sourcing) if immutable properties like storage differ from the running stream. Messages are preserved during migration.

retention is NOT migratable — it is controlled by the transport (Workqueue for events, Limits for broadcast/ordered) and a mismatch is always treated as an error regardless of this flag.

When false (default), immutable conflicts are logged as warnings and the stream continues with its existing configuration.

Default​

false

broadcast?​

optional broadcast?: StreamConsumerOverrides

Defined in: src/interfaces/options.interface.ts:204

Broadcast event stream/consumer overrides.

codec?​

optional codec?: Codec

Defined in: src/interfaces/options.interface.ts:185

Global message codec.

Default​

JsonCodec

connectionOptions?​

optional connectionOptions?: Partial<ConnectionOptions>

Defined in: src/interfaces/options.interface.ts:309

Raw NATS ConnectionOptions pass-through for advanced connection config. Allows setting tls, auth, reconnect behavior, maxReconnectAttempts, etc. Merged with name and servers — those take precedence.

consumer?​

optional consumer?: boolean

Defined in: src/interfaces/options.interface.ts:198

Enable consumer infrastructure (streams, consumers, message routing). Set to false for publisher-only services (e.g., API gateways).

Default​

true

dlq?​

optional dlq?: object

Defined in: src/interfaces/options.interface.ts:262

Dead-letter queue (DLQ) configuration. DLQ is a separate stream used to store messages that have exhausted all delivery attempts.

stream?​

optional stream?: Partial<Omit<StreamConfig, "retention">>

Example​

JetstreamModule.forRootAsync({
  name: 'my-service',
  servers: ['nats://localhost:4222'],
  dlq: {
    stream: {
      max_age: toNanos(30, 'days'),
    },
  },
})

events?​

optional events?: StreamConsumerOverrides

Defined in: src/interfaces/options.interface.ts:201

Workqueue event stream/consumer overrides.

hooks?​

optional hooks?: Partial<TransportHooks>

Defined in: src/interfaces/options.interface.ts:220

Transport lifecycle hook handlers. Unset hooks are silently ignored — no default logging.

metadata?​

optional metadata?: MetadataRegistryOptions

Defined in: src/interfaces/options.interface.ts:302

Handler metadata KV registry configuration.

When any handler has meta in its @EventPattern / @MessagePattern extras, the transport writes metadata to a NATS KV bucket at startup. External services (API gateways, dashboards, CLI tools) can read or watch the bucket for dynamic service discovery.

Auto-enabled when any handler has meta. Set to customize bucket name, replicas, or TTL.

See​

MetadataRegistryOptions

name​

name: string

Defined in: src/interfaces/options.interface.ts:176

Service name. Used for stream/consumer/subject naming.

ordered?​

optional ordered?: OrderedEventOverrides

Defined in: src/interfaces/options.interface.ts:214

Ordered event consumer configuration.

Ordered events use a separate stream with Limits retention and deliver messages in strict sequential order. Use ordered: prefix when publishing.

See​

OrderedEventOverrides

otel?​

optional otel?: OtelOptions

Defined in: src/interfaces/options.interface.ts:320

OpenTelemetry integration. When omitted, sensible defaults are applied: tracing is enabled, default trace kinds are emitted, only standard correlation headers are captured. If no OTel SDK is registered in the consuming application, all tracer calls are no-ops — there is no runtime cost.

See​

OtelOptions

rpc?​

optional rpc?: RpcConfig

Defined in: src/interfaces/options.interface.ts:191

RPC transport mode and configuration.

Default​

{ mode: 'core' }

servers​

servers: string[]

Defined in: src/interfaces/options.interface.ts:179

NATS server URLs.

shutdownTimeout?​

optional shutdownTimeout?: number

Defined in: src/interfaces/options.interface.ts:269

Graceful shutdown timeout in ms. Handlers exceeding this are abandoned.

Default​

10_000

Methods​

onDeadLetter()?​

optional onDeadLetter(info): Promise<void>

Defined in: src/interfaces/options.interface.ts:244

Async callback invoked when an event message exhausts all delivery attempts. Called before msg.term(). If it throws, the message is nak'd for retry.

Use this to persist dead letters to an external store (DB, S3, another queue). The NATS connection is available via JETSTREAM_CONNECTION token in forRootAsync.

Parameters​

info​

DeadLetterInfo

Returns​

Promise<void>

Example​

JetstreamModule.forRootAsync({
  name: 'my-service',
  imports: [DlqModule],
  inject: [DlqService, JETSTREAM_CONNECTION],
  useFactory: (dlqService, connection) => ({
    servers: ['nats://localhost:4222'],
    onDeadLetter: async (info) => {
      await dlqService.persist(info);
    },
  }),
})