Skip to main content

JetstreamModuleOptions

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

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:288

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:205

Broadcast event stream/consumer overrides.

codec?​

optional codec?: Codec

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

Global message codec.

Default​

JsonCodec

connectionOptions?​

optional connectionOptions?: Partial<ConnectionOptions>

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

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:199

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:263

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:202

Workqueue event stream/consumer overrides.

hooks?​

optional hooks?: Partial<TransportHooks>

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

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

metadata?​

optional metadata?: MetadataRegistryOptions

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

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

metrics?​

optional metrics?: MetricsOption

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

Built-in Prometheus metrics.

Pass true to enable with defaults, or a MetricsConfig object for full control (custom registry, prefix, labels, polling, buckets). When omitted or false, the metrics module is not registered and prom-client is not imported — zero overhead.

Requires prom-client peer dependency to be installed when enabled. The service writes to prom-client's global register by default, making integration with @willsoto/nestjs-prometheus (or any prom-client-based /metrics exporter) work without coordination.

See​

MetricsConfig

Example​

JetstreamModule.forRoot({
  name: 'orders',
  servers: ['nats://localhost:4222'],
  metrics: true,
})

name​

name: string

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

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

ordered?​

optional ordered?: OrderedEventOverrides

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

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?: boolean | OtelOptions

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

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.

Accepts a full OtelOptions object, or the boolean shorthand true (== defaults) / false (== { enabled: false }).

See​

OtelOptions

rpc?​

optional rpc?: RpcConfig

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

RPC transport mode and configuration.

Default​

{ mode: 'core' }

servers​

servers: string[]

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

NATS server URLs.

shutdownTimeout?​

optional shutdownTimeout?: number

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

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:245

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