Skip to main content

TransportHooks

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

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.

Example​

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

Methods​

connect()​

connect(server): void

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

Fired when NATS connection is established.

Parameters​

server​

string

Returns​

void

consumerRecovered()​

consumerRecovered(label, attempts): void

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

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.

Returns​

void

deadLetter()​

deadLetter(info): void

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

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

Parameters​

info​

DeadLetterInfo

Returns​

void

disconnect()​

disconnect(): void

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

Fired when NATS connection is lost.

Returns​

void

error()​

error(error, context?): void

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

Fired on any transport-level error.

Parameters​

error​

Error

context?​

string

Returns​

void

handlerCompleted()​

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

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

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.

Returns​

void

messageRouted()​

messageRouted(subject, kind): void

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

Fired after a message is successfully routed to its handler.

Parameters​

subject​

string

kind​

MessageKind

Returns​

void

published()​

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

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

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.

Returns​

void

reconnect()​

reconnect(server): void

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

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

Parameters​

server​

string

Returns​

void

rpcCompleted()​

rpcCompleted(subject, durationMs, status): void

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

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.

Returns​

void

rpcTimeout()​

rpcTimeout(subject, correlationId): void

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

Fired when an RPC handler exceeds its timeout.

Parameters​

subject​

string

correlationId​

string

Returns​

void

shutdownComplete()​

shutdownComplete(): void

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

Fired after graceful shutdown completes.

Returns​

void

shutdownStart()​

shutdownStart(): void

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

Fired at the start of the graceful shutdown sequence.

Returns​

void