Skip to main content

TransportHooks

@horizon-republic/nestjs-jetstream

@horizon-republic/nestjs-jetstream / TransportHooks

TransportHooks

Defined in: src/interfaces/hooks.interface.ts:68

Hook callbacks for transport lifecycle and operational events.

Events without a registered hook are silently ignored. Register hooks via forRoot({ hooks: { ... } }) for monitoring, alerting, or custom observability integration.

Hooks are registered once and fire for every connection. Each callback receives the originating connection name as a trailing argument when more than one connection is configured, and nothing extra otherwise.

Example​

JetstreamModule.forRoot({
  hooks: {
    [TransportEvent.Error]: (error, context) => sentry.captureException(error),
    [TransportEvent.RpcTimeout]: (subject) => metrics.increment('rpc.timeout'),
  },
})

Methods​

connect()​

connect(server, connection?): void

Defined in: src/interfaces/hooks.interface.ts:70

Fired when NATS connection is established.

Parameters​

server​

string

connection?​

string

Returns​

void

consumerRecovered()​

consumerRecovered(label, attempts, connection?): void

Defined in: src/interfaces/hooks.interface.ts:105

Fired when a consumer's self-healing flow successfully recovers after one or more failed restart attempts. Useful for "service is back" alerts and to balance the noise from preceding error/restart logs.

Parameters​

label​

string

Stream kind label (event, broadcast, ordered, etc.) or consumer name passed to createSelfHealingFlow.

attempts​

number

How many consecutive failed attempts preceded the recovery.

connection?​

string

Returns​

void

deadLetter()​

deadLetter(info, connection?): void

Defined in: src/interfaces/hooks.interface.ts:94

Fired when a message exhausts all delivery attempts (dead letter).

Parameters​

info​

DeadLetterInfo

connection?​

string

Returns​

void

disconnect()​

disconnect(connection?): void

Defined in: src/interfaces/hooks.interface.ts:73

Fired when NATS connection is lost.

Parameters​

connection?​

string

Returns​

void

error()​

error(error, context?, connection?): void

Defined in: src/interfaces/hooks.interface.ts:79

Fired on any transport-level error.

Parameters​

error​

Error

context?​

string

connection?​

string

Returns​

void

handlerCompleted()​

handlerCompleted(subject, kind, durationMs, status, connection?): void

Defined in: src/interfaces/hooks.interface.ts:118

Fired immediately after a handler returns or throws.

Used by built-in metrics; users can register their own handler for latency tracking, slow-handler alerting, or custom observability.

Parameters​

subject​

string

The declared NATS pattern (from @EventPattern / @MessagePattern).

kind​

StreamKind

Stream kind: Event, Command, Broadcast, Ordered.

durationMs​

number

Wall-clock time in milliseconds from handler entry to settlement.

status​

HandlerStatus

Outcome: success, error, retried, or terminated.

connection?​

string

Returns​

void

messageRouted()​

messageRouted(subject, kind, connection?): void

Defined in: src/interfaces/hooks.interface.ts:85

Fired after a message is successfully routed to its handler.

Parameters​

subject​

string

kind​

MessageKind

connection?​

string

Returns​

void

published()​

published(subject, kind, durationMs, status, connection?): void

Defined in: src/interfaces/hooks.interface.ts:137

Fired after every client-side publish (event emit or RPC publish leg) completes, regardless of outcome.

Parameters​

subject​

string

Declared user pattern (e.g. orders.created), bounded by handler registration, safe for high-cardinality labels.

kind​

StreamKind

Stream kind the publish targets: Event, Broadcast, Ordered, or Command (RPC publish leg).

durationMs​

number

Wall-clock time from publish initiation to ack/error.

status​

PublishStatus

success when the publish acked, error otherwise.

connection?​

string

Returns​

void

reconnect()​

reconnect(server, connection?): void

Defined in: src/interfaces/hooks.interface.ts:76

Fired when NATS connection is re-established after a disconnect.

Parameters​

server​

string

connection?​

string

Returns​

void

rpcCompleted()​

rpcCompleted(subject, durationMs, status, connection?): void

Defined in: src/interfaces/hooks.interface.ts:156

Fired after an RPC round-trip completes from the caller's perspective: either a reply is received, the call errors out, or the deadline expires.

Distinct from Published which only covers the publish leg.

Parameters​

subject​

string

Declared command pattern (e.g. orders.get).

durationMs​

number

Wall-clock time from request initiation to settlement.

status​

RpcOutcomeStatus

success for a successful reply, error for transport/ handler errors, timeout when the deadline expired.

connection?​

string

Returns​

void

rpcTimeout()​

rpcTimeout(subject, correlationId, connection?): void

Defined in: src/interfaces/hooks.interface.ts:82

Fired when an RPC handler exceeds its timeout.

Parameters​

subject​

string

correlationId​

string

connection?​

string

Returns​

void

scheduleReconciled()​

scheduleReconciled(report, connection?): void

Defined in: src/interfaces/hooks.interface.ts:169

Fired once per connection at boot, after the declared schedules were written to the schedule stream.

Parameters​

report​

ScheduleReconcileReport

Handler patterns whose schedule was created, updated or left as it was.

connection?​

string

Returns​

void

shutdownComplete()​

shutdownComplete(connection?): void

Defined in: src/interfaces/hooks.interface.ts:91

Fired after graceful shutdown completes.

Parameters​

connection?​

string

Returns​

void

shutdownStart()​

shutdownStart(connection?): void

Defined in: src/interfaces/hooks.interface.ts:88

Fired at the start of the graceful shutdown sequence.

Parameters​

connection?​

string

Returns​

void