Skip to main content

JetstreamModuleOptions

@horizon-republic/nestjs-jetstream

@horizon-republic/nestjs-jetstream / JetstreamModuleOptions

JetstreamModuleOptions

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

Root module configuration for JetstreamModule.forRoot().

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

Properties​

broadcast?​

optional broadcast?: StreamConsumerOverrides

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

Broadcast event stream/consumer overrides.

codec?​

optional codec?: Codec

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

Global message codec.

Default​

JsonCodec

connectionOptions?​

optional connectionOptions?: Partial<ConnectionOptions>

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

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.

connections?​

optional connections?: Record<string, JetstreamConnectionOptions>

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

Named connections. Multi-connection form.

Mutually exclusive with JetstreamModuleOptions.servers. Each entry inherits every root-level field it does not set.

defaultConnection?​

optional defaultConnection?: string

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

Which connection unqualified handlers and clients bind to.

Optional when the connections map has a default key; required otherwise.

dlq?​

optional dlq?: boolean | DlqOptions

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

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

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

Workqueue event stream/consumer overrides.

hooks?​

optional hooks?: Partial<TransportHooks>

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

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

metadata?​

optional metadata?: MetadataRegistryOptions

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

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 to discover services at runtime.

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

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 no Prometheus client is imported, so there is zero overhead.

Requires @prometheus-io/client or prom-client to be installed when enabled. The service writes to that package's global register by default, so @willsoto/nestjs-prometheus and other /metrics exporters work without coordination. With both installed, register is required.

See​

MetricsConfig

Example​

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

name​

name: string

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

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

ordered?​

optional ordered?: OrderedEventOverrides

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

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

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

Provisioning behavior.

publisherOnly?​

optional publisherOnly?: boolean

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

Skip all consumer infrastructure: no streams, no consumers, no message routing. For services that only publish, such as an API gateway.

Named apart from the consumer block inside events and friends, which carries a raw NATS ConsumerConfig and means something else entirely.

Default​

false

rpc?​

optional rpc?: RpcConfig

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

RPC transport mode and configuration.

Default​

{ mode: 'core' }

schedule?​

optional schedule?: StreamConsumerOverrides

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

Schedule stream/consumer overrides. The stream exists only when a handler declares schedule in its @EventPattern extras.

servers?​

optional servers?: string[]

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

NATS server URLs. Single-connection form.

Mutually exclusive with JetstreamModuleOptions.connections.

shutdownTimeout?​

optional shutdownTimeout?: number

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

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

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