Skip to main content

JetstreamModuleOptions

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

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

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

Broadcast event stream/consumer overrides.

codec?​

optional codec?: Codec

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

Global message codec.

Default​

JsonCodec

connectionOptions?​

optional connectionOptions?: Partial<ConnectionOptions>

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

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

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

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

management?​

optional management?: EntityManagement

Provisioning control for the DLQ stream. Falls back to provisioning.management.

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

Workqueue event stream/consumer overrides.

hooks?​

optional hooks?: Partial<TransportHooks>

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

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

metadata?​

optional metadata?: MetadataRegistryOptions

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

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

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, so there is 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:232

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

ordered?​

optional ordered?: OrderedEventOverrides

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

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

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 with no runtime cost.

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

See​

OtelOptions

provisioning?​

optional provisioning?: ProvisioningOptions

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

Provisioning behavior.

rpc?​

optional rpc?: RpcConfig

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

RPC transport mode and configuration.

Default​

{ mode: 'core' }

servers​

servers: string[]

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

NATS server URLs.

shutdownTimeout?​

optional shutdownTimeout?: number

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

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

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