@horizon-republic/nestjs-jetstream 2.10.0 → 2.11.0

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { Logger, ModuleMetadata, FactoryProvider, Type, OnApplicationShutdown, DynamicModule } from '@nestjs/common';
 import { MsgHdrs, NatsConnection, Status, ConnectionOptions, Msg } from '@nats-io/transport-node';
 import { JetStreamManager, JetStreamClient, StreamConfig, ConsumerConfig, ConsumeOptions, DeliverPolicy, ReplayPolicy, ConsumerInfo, JsMsg } from '@nats-io/jetstream';
+import { Registry } from 'prom-client';
 import { Span } from '@opentelemetry/api';
 import { ClientProxy, ReadPacket, WritePacket, MessageHandler, Server, CustomTransportStrategy, BaseRpcContext } from '@nestjs/microservices';
 import { Observable } from 'rxjs';
@@ -33,11 +34,47 @@ interface Codec {
     decode(data: Uint8Array): unknown;
 }
 
+/**
+ * Identifies a JetStream stream/consumer kind.
+ *
+ * - `Event`     — Workqueue events (at-least-once delivery to one consumer).
+ * - `Command`   — RPC commands (JetStream mode only).
+ * - `Broadcast` — Broadcast events (fan-out to all consumers).
+ * - `Ordered`   — Ordered events (strict sequential delivery, Limits retention).
+ */
+declare enum StreamKind {
+    Event = "ev",
+    Command = "cmd",
+    Broadcast = "broadcast",
+    Ordered = "ordered"
+}
+/**
+ * Subset of {@link StreamKind} used for direct subject building.
+ *
+ * Excludes `Broadcast` because broadcast subjects use a different
+ * naming convention (`broadcast.{pattern}` instead of `{service}.{kind}.{pattern}`).
+ */
+type SubjectKind = Exclude<StreamKind, StreamKind.Broadcast>;
+
 /** Discriminates the kind of message routed through the transport. */
 declare enum MessageKind {
     Event = "event",
     Rpc = "rpc"
 }
+/** Outcome of a handler invocation, used as a label on processing metrics. */
+type HandlerStatus = 'success' | 'error' | 'retried' | 'terminated';
+/**
+ * Outcome of a client publish (event emit or RPC publish leg). Outbound
+ * operations either acknowledge cleanly or surface a transport error — there
+ * is no retried/terminated dimension at the publish boundary.
+ */
+type PublishStatus = 'success' | 'error';
+/**
+ * Outcome of a full RPC round-trip from the caller's perspective. Adds the
+ * `timeout` dimension on top of {@link PublishStatus} so percentile analysis
+ * can distinguish slow successes from deadline-exceeded calls.
+ */
+type RpcOutcomeStatus = 'success' | 'error' | 'timeout';
 declare enum TransportEvent {
     Connect = "connect",
     Disconnect = "disconnect",
@@ -47,7 +84,11 @@ declare enum TransportEvent {
     MessageRouted = "messageRouted",
     ShutdownStart = "shutdownStart",
     ShutdownComplete = "shutdownComplete",
-    DeadLetter = "deadLetter"
+    DeadLetter = "deadLetter",
+    ConsumerRecovered = "consumerRecovered",
+    HandlerCompleted = "handlerCompleted",
+    Published = "published",
+    RpcCompleted = "rpcCompleted"
 }
 /**
  * Hook callbacks for transport lifecycle and operational events.
@@ -85,7 +126,59 @@ interface TransportHooks {
     [TransportEvent.ShutdownComplete](): void;
     /** Fired when a message exhausts all delivery attempts (dead letter). */
     [TransportEvent.DeadLetter](info: DeadLetterInfo): void;
+    /**
+     * 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.
+     *
+     * @param label   Stream kind label (`event`, `broadcast`, `ordered`, etc.)
+     *                or consumer name passed to `createSelfHealingFlow`.
+     * @param attempts How many consecutive failed attempts preceded the recovery.
+     */
+    [TransportEvent.ConsumerRecovered](label: string, attempts: number): void;
+    /**
+     * 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.
+     *
+     * @param subject  The declared NATS pattern (from `@EventPattern` / `@MessagePattern`).
+     * @param kind     Stream kind: `Event`, `Command`, `Broadcast`, `Ordered`.
+     * @param durationMs Wall-clock time in milliseconds from handler entry to settlement.
+     * @param status   Outcome: `success`, `error`, `retried`, or `terminated`.
+     */
+    [TransportEvent.HandlerCompleted](subject: string, kind: StreamKind, durationMs: number, status: HandlerStatus): void;
+    /**
+     * Fired after every client-side publish (event emit or RPC publish leg)
+     * completes, regardless of outcome.
+     *
+     * @param subject  Declared user pattern (e.g. `orders.created`) — bounded
+     *                 by handler registration, safe for high-cardinality labels.
+     * @param kind     Stream kind the publish targets: `Event`, `Broadcast`,
+     *                 `Ordered`, or `Command` (RPC publish leg).
+     * @param durationMs Wall-clock time from publish initiation to ack/error.
+     * @param status   `success` when the publish acked, `error` otherwise.
+     */
+    [TransportEvent.Published](subject: string, kind: StreamKind, durationMs: number, status: PublishStatus): void;
+    /**
+     * 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 {@link Published} which only covers the publish leg.
+     *
+     * @param subject  Declared command pattern (e.g. `orders.get`).
+     * @param durationMs Wall-clock time from request initiation to settlement.
+     * @param status   `success` for a successful reply, `error` for transport/
+     *                 handler errors, `timeout` when the deadline expired.
+     */
+    [TransportEvent.RpcCompleted](subject: string, durationMs: number, status: RpcOutcomeStatus): void;
 }
+/**
+ * Internal subscriber for a transport event. Multiple subscribers may be
+ * registered per event via `EventBus.subscribe()` — used by built-in
+ * observers (e.g. metrics) without overriding the user-provided hook.
+ */
+type TransportEventSubscriber<K extends keyof TransportHooks> = (...args: Parameters<TransportHooks[K]>) => unknown;
 /**
  * Context passed to the onDeadLetter callback when a message exhausts all delivery attempts.
  */
@@ -118,6 +211,49 @@ interface JetstreamHealthStatus {
     latency: number | null;
 }
 
+/**
+ * Labels (in seconds) for histogram bucket configuration.
+ * Override defaults via `JetstreamModuleOptions.metrics.buckets`.
+ */
+interface HistogramBuckets {
+    /** Buckets for `jetstream_handler_duration_seconds`. */
+    handlerDuration?: number[];
+    /** Buckets for `jetstream_publish_duration_seconds`. */
+    publishDuration?: number[];
+    /** Buckets for `jetstream_rpc_duration_seconds`. */
+    rpcDuration?: number[];
+}
+/**
+ * Configuration for built-in Prometheus metrics. All fields are optional;
+ * sensible production defaults are applied when missing.
+ */
+interface MetricsConfig {
+    /**
+     * `prom-client` registry to write metrics into. Defaults to the global
+     * `register` from `prom-client`, which is also what
+     * `@willsoto/nestjs-prometheus` exposes via `/metrics`.
+     */
+    register?: Registry;
+    /** Metric name prefix. Defaults to `'jetstream_'`. */
+    prefix?: string;
+    /** Labels merged into every metric. Useful for service/env tagging. */
+    defaultLabels?: Record<string, string>;
+    /**
+     * Polling interval (ms) for gauge metrics that query `JetStreamManager`
+     * (consumer pending, stream messages, etc.). Default `15_000`.
+     * Set to `0` to disable polling — counter/histogram metrics still update
+     * via the event bus.
+     */
+    pollInterval?: number;
+    /** Override default histogram buckets. */
+    buckets?: HistogramBuckets;
+}
+/**
+ * Shorthand for `MetricsConfig`. Pass `true` to enable with all defaults,
+ * `false` (or omit) to disable entirely.
+ */
+type MetricsOption = boolean | MetricsConfig;
+
 /**
  * Instrumentation scope name reported on every span the library emits.
  * Matches the npm package name — the convention used by
@@ -188,31 +324,27 @@ declare const DEFAULT_TRACES: readonly JetstreamTrace[];
 /**
  * Central event bus for transport lifecycle notifications.
  *
- * Dispatches events to user-provided hooks. Events without a
- * registered hook are silently ignored — no default logging.
+ * Two emission paths:
+ *  - User hooks registered via `forRoot({ hooks })` — at most one per event.
+ *  - Internal subscribers added via `subscribe()` — many per event, used by
+ *    metrics and other built-in observers.
  *
- * @example
- * ```typescript
- * const bus = new EventBus(logger, {
- *   [TransportEvent.Error]: (err) => sentry.captureException(err),
- * });
- *
- * bus.emit(TransportEvent.Error, new Error('timeout'), 'rpc-router');
- * // → calls sentry
- *
- * bus.emit(TransportEvent.Connect, 'nats://localhost:4222');
- * // → no-op (no hook registered)
- * ```
+ * Both fire on every `emit()` call. Subscriber failures are isolated and
+ * logged; they do not block other subscribers or the user hook.
  */
 declare class EventBus {
     private readonly hooks;
     private readonly logger;
+    private readonly subscribers;
     constructor(logger: Logger, hooks?: Partial<TransportHooks>);
     /**
-     * Emit a lifecycle event. Dispatches to custom hook if registered, otherwise no-op.
-     *
-     * @param event - The {@link TransportEvent} to emit.
-     * @param args - Arguments matching the hook signature for this event.
+     * Subscribe to a transport event. Used by built-in observers (e.g. metrics).
+     * Multiple subscribers per event are supported; each is called independently.
+     */
+    subscribe<K extends keyof TransportHooks>(event: K, handler: TransportEventSubscriber<K>): void;
+    /**
+     * Emit a lifecycle event. Dispatches to all internal subscribers and the
+     * registered user hook (if any).
      */
     emit<K extends keyof TransportHooks>(event: K, ...args: Parameters<TransportHooks[K]>): void;
     /**
@@ -221,12 +353,12 @@ declare class EventBus {
      */
     emitMessageRouted(subject: string, kind: MessageKind): void;
     /**
-     * Check whether a hook is registered for the given event.
-     *
-     * Used by the routing hot path to elide the emit call entirely when the
-     * transport owner did not register a listener.
+     * Check whether any listener (user hook or internal subscriber) is registered
+     * for the given event. Used by routing hot path to elide the emit call when
+     * no one is listening.
      */
     hasHook(event: keyof TransportHooks): boolean;
+    private dispatch;
     private callHook;
 }
 
@@ -391,6 +523,8 @@ declare class JetstreamClient extends ClientProxy {
     private publishCoreRpc;
     /** JetStream mode: publish to stream + wait for inbox response. */
     private publishJetStreamRpc;
+    private reportPublished;
+    private reportRpcCompleted;
     /** Fail-fast all pending JetStream RPC callbacks on connection loss. */
     private handleDisconnect;
     /** Reject all pending RPC callbacks, clear timeouts, and tear down inbox. */
@@ -1069,6 +1203,30 @@ interface JetstreamModuleOptions {
      * Merged with `name` and `servers` — those take precedence.
      */
     connectionOptions?: Partial<ConnectionOptions>;
+    /**
+     * Built-in Prometheus metrics.
+     *
+     * Pass `true` to enable with defaults, or a {@link 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
+     * ```typescript
+     * JetstreamModule.forRoot({
+     *   name: 'orders',
+     *   servers: ['nats://localhost:4222'],
+     *   metrics: true,
+     * })
+     * ```
+     */
+    metrics?: MetricsOption;
     /**
      * OpenTelemetry integration. When omitted, sensible defaults are applied:
      * tracing is enabled, default trace kinds are emitted, only standard
@@ -1100,6 +1258,15 @@ type JetstreamModuleAsyncOptions = {
     name: string;
     /** Additional module imports (e.g., ConfigModule). */
     imports?: ModuleMetadata['imports'];
+    /**
+     * Built-in Prometheus metrics. Specified at the async-options level (parallel
+     * to {@link name}) because module composition is decided synchronously before
+     * the async factory runs. Use `true` for defaults, a {@link MetricsConfig}
+     * object for full control, or omit/`false` to disable entirely.
+     *
+     * @see JetstreamModuleOptions.metrics
+     */
+    metrics?: MetricsOption;
 } & ({
     useFactory(...args: unknown[]): Promise<Omit<JetstreamModuleOptions, 'name'>> | Omit<JetstreamModuleOptions, 'name'>;
     inject?: FactoryProvider['inject'];
@@ -1117,28 +1284,6 @@ type JetstreamModuleAsyncOptions = {
     useExisting?: never;
 });
 
-/**
- * Identifies a JetStream stream/consumer kind.
- *
- * - `Event`     — Workqueue events (at-least-once delivery to one consumer).
- * - `Command`   — RPC commands (JetStream mode only).
- * - `Broadcast` — Broadcast events (fan-out to all consumers).
- * - `Ordered`   — Ordered events (strict sequential delivery, Limits retention).
- */
-declare enum StreamKind {
-    Event = "ev",
-    Command = "cmd",
-    Broadcast = "broadcast",
-    Ordered = "ordered"
-}
-/**
- * Subset of {@link StreamKind} used for direct subject building.
- *
- * Excludes `Broadcast` because broadcast subjects use a different
- * naming convention (`broadcast.{pattern}` instead of `{service}.{kind}.{pattern}`).
- */
-type SubjectKind = Exclude<StreamKind, StreamKind.Broadcast>;
-
 /** Options for one-shot delayed delivery via NATS 2.12 message scheduling. */
 interface ScheduleRecordOptions {
     /** When to deliver the message. Must be in the future. */
@@ -1211,6 +1356,17 @@ declare class PatternRegistry {
     registerHandlers(handlers: Map<string, MessageHandler>): void;
     /** Find handler for a full NATS subject. */
     getHandler(subject: string): MessageHandler | null;
+    /**
+     * Resolve the declared pattern and {@link StreamKind} for a full NATS subject.
+     *
+     * Returns `null` when the subject is not registered. The declared pattern is
+     * the value the user passed to `@EventPattern`/`@MessagePattern` — stable and
+     * bounded, suitable for use as a Prometheus label without cardinality risk.
+     */
+    resolveDeclared(subject: string): {
+        pattern: string;
+        kind: StreamKind;
+    } | null;
     /** Get all registered broadcast patterns (for consumer filter_subject setup). */
     getBroadcastPatterns(): string[];
     hasBroadcastHandlers(): boolean;
@@ -1262,6 +1418,7 @@ declare class CoreRpcServer {
     stop(): void;
     /** Handle an incoming Core NATS request. */
     private handleRequest;
+    private reportHandlerCompleted;
     /** Send an error response back to the caller with x-error header. */
     private respondWithError;
 }
@@ -1660,6 +1817,18 @@ declare class JetstreamStrategy extends Server implements CustomTransportStrateg
     listen(callback: () => void): Promise<void>;
     /** Stop all consumers, routers, subscriptions, and metadata heartbeat. Called during shutdown. */
     close(): void;
+    /**
+     * Override NestJS `Server.addHandler` to fail-fast on duplicate pattern registration.
+     *
+     * The base class silently overwrites duplicate RPC handlers (last wins) and appends
+     * duplicate event handlers to a linked list. Both behaviors are hazardous in a
+     * JetStream context: silent overwrite drops a handler the user wrote, and double
+     * event dispatch double-acks/double-processes the same JetStream message.
+     *
+     * We treat any pattern collision as a fatal misconfiguration so it surfaces at
+     * bootstrap instead of in production traffic.
+     */
+    addHandler(pattern: unknown, callback: MessageHandler, isEventHandler?: boolean, extras?: Record<string, unknown>): void;
     /**
      * Register event listener (required by Server base class).
      *