@horizon-republic/nestjs-jetstream 2.5.0 → 2.6.1

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { ModuleMetadata, FactoryProvider, Type, Logger, OnApplicationShutdown, DynamicModule } from '@nestjs/common';
-import { MsgHdrs, StreamConfig, ConsumerConfig, DeliverPolicy, ReplayPolicy, ConnectionOptions, NatsConnection, Status, JetStreamManager, ConsumerInfo, JsMsg, Msg } from 'nats';
+import { MsgHdrs, StreamConfig, ConsumerConfig, ConsumeOptions, DeliverPolicy, ReplayPolicy, ConnectionOptions, NatsConnection, Status, JetStreamManager, JetStreamClient, ConsumerInfo, JsMsg, Msg } from 'nats';
 import { MessageHandler, Server, CustomTransportStrategy, ClientProxy, ReadPacket, WritePacket, BaseRpcContext } from '@nestjs/microservices';
 import { Observable } from 'rxjs';
 
@@ -31,6 +31,11 @@ interface Codec {
     decode(data: Uint8Array): unknown;
 }
 
+/** Discriminates the kind of message routed through the transport. */
+declare enum MessageKind {
+    Event = "event",
+    Rpc = "rpc"
+}
 declare enum TransportEvent {
     Connect = "connect",
     Disconnect = "disconnect",
@@ -71,7 +76,7 @@ interface TransportHooks {
     /** Fired when an RPC handler exceeds its timeout. */
     [TransportEvent.RpcTimeout](subject: string, correlationId: string): void;
     /** Fired after a message is successfully routed to its handler. */
-    [TransportEvent.MessageRouted](subject: string, kind: 'rpc' | 'event'): void;
+    [TransportEvent.MessageRouted](subject: string, kind: MessageKind): void;
     /** Fired at the start of the graceful shutdown sequence. */
     [TransportEvent.ShutdownStart](): void;
     /** Fired after graceful shutdown completes. */
@@ -101,6 +106,16 @@ interface DeadLetterInfo {
     timestamp: string;
 }
 
+/** Health status returned by the JetStream health indicator. */
+interface JetstreamHealthStatus {
+    /** Whether the NATS connection is alive. */
+    connected: boolean;
+    /** NATS server URL, or `null` if not connected. */
+    server: string | null;
+    /** Round-trip latency in ms, or `null` if disconnected. */
+    latency: number | null;
+}
+
 /**
  * RPC transport configuration.
  *
@@ -123,11 +138,50 @@ type RpcConfig = {
     stream?: Partial<StreamConfig>;
     /** Raw NATS ConsumerConfig overrides for the command consumer. */
     consumer?: Partial<ConsumerConfig>;
+    /** Options passed to the nats.js `consumer.consume()` call for the command consumer. */
+    consume?: Partial<ConsumeOptions>;
+    /** Maximum number of concurrent RPC handler executions. */
+    concurrency?: number;
+    /**
+     * Auto-extend ack deadline via `msg.working()` during RPC handler execution.
+     * The RPC handler timeout (`setTimeout` + `msg.term()`) still acts as the hard cap.
+     */
+    ackExtension?: boolean | number;
 };
 /** Overrides for JetStream stream and consumer configuration. */
 interface StreamConsumerOverrides {
     stream?: Partial<StreamConfig>;
     consumer?: Partial<ConsumerConfig>;
+    /**
+     * Options passed to the nats.js `consumer.consume()` call.
+     * Controls prefetch buffer size, idle heartbeat interval, and auto-refill thresholds.
+     *
+     * nats.js supports two consumption modes (message-based and byte-based).
+     * Do not mix `max_bytes`/`threshold_bytes` with `threshold_messages` —
+     * use one mode or the other.
+     *
+     * @see https://github.com/nats-io/nats.js — ConsumeOptions
+     */
+    consume?: Partial<ConsumeOptions>;
+    /**
+     * Maximum number of concurrent handler executions (RxJS `mergeMap` limit).
+     *
+     * Default: `undefined` (unlimited — naturally bounded by `max_ack_pending`).
+     * Set this to protect downstream systems from overload.
+     *
+     * **Important:** if `concurrency < max_ack_pending`, messages buffer in RxJS
+     * while their NATS ack timer ticks. Increase `ack_wait` proportionally to
+     * prevent unnecessary redeliveries.
+     */
+    concurrency?: number;
+    /**
+     * Auto-extend the NATS ack deadline via `msg.working()` during handler execution.
+     *
+     * - `false` (default): disabled — NATS redelivers after `ack_wait` if not acked.
+     * - `true`: auto-extend at `ack_wait / 2` interval (calculated from consumer config).
+     * - `number`: explicit extension interval in milliseconds.
+     */
+    ackExtension?: boolean | number;
 }
 /**
  * Configuration for ordered event consumers.
@@ -281,12 +335,17 @@ type JetstreamModuleAsyncOptions = {
 /**
  * Identifies a JetStream stream/consumer kind.
  *
- * - `'ev'` — Workqueue events (at-least-once delivery to one consumer).
- * - `'cmd'` — RPC commands (JetStream mode only).
- * - `'broadcast'` — Broadcast events (fan-out to all consumers).
- * - `'ordered'` — Ordered events (strict sequential delivery, Limits retention).
+ * - `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).
  */
-type StreamKind = 'ev' | 'cmd' | 'broadcast' | 'ordered';
+declare enum StreamKind {
+    Event = "ev",
+    Command = "cmd",
+    Broadcast = "broadcast",
+    Ordered = "ordered"
+}
 
 /** @internal Grouped pattern lists by stream kind, used for stream/consumer setup. */
 interface PatternsByKind {
@@ -299,6 +358,33 @@ interface PatternsByKind {
     /** Ordered event patterns (strict sequential delivery). */
     ordered: string[];
 }
+/** Options for configuring event/broadcast processing behavior. */
+interface EventProcessingConfig {
+    events?: {
+        concurrency?: number;
+        ackExtension?: boolean | number;
+    };
+    broadcast?: {
+        concurrency?: number;
+        ackExtension?: boolean | number;
+    };
+}
+/** Options for dead letter queue handling. */
+interface DeadLetterConfig {
+    /**
+     * Map of stream name -> max_deliver value.
+     * Used to detect when a message from a given stream has exhausted all delivery attempts.
+     */
+    maxDeliverByStream: Map<string, number>;
+    /** Async callback invoked when a message exhausts all deliveries. */
+    onDeadLetter(info: DeadLetterInfo): Promise<void>;
+}
+/** Options for configuring RPC processing behavior. */
+interface RpcRouterOptions {
+    timeout?: number;
+    concurrency?: number;
+    ackExtension?: boolean | number;
+}
 
 /**
  * Central event bus for transport lifecycle notifications.
@@ -352,6 +438,7 @@ declare class ConnectionProvider {
     private readonly logger;
     private connection;
     private connectionPromise;
+    private jsClient;
     private jsmInstance;
     private jsmPromise;
     constructor(options: JetstreamModuleOptions, eventBus: EventBus);
@@ -367,6 +454,16 @@ declare class ConnectionProvider {
      * @returns The JetStreamManager for stream/consumer administration.
      */
     getJetStreamManager(): Promise<JetStreamManager>;
+    /**
+     * Get a cached JetStream client.
+     *
+     * Invalidated automatically on reconnect and shutdown so consumers always
+     * operate against the live connection.
+     *
+     * @returns The cached JetStreamClient.
+     * @throws Error if the connection has not been established yet.
+     */
+    getJetStreamClient(): JetStreamClient;
     /** Direct access to the raw NATS connection, or `null` if not yet connected. */
     get unwrap(): NatsConnection | null;
     /**
@@ -393,6 +490,7 @@ declare class PatternRegistry {
     private readonly options;
     private readonly logger;
     private readonly registry;
+    private cachedPatterns;
     constructor(options: JetstreamModuleOptions);
     /**
      * Register all handlers from the NestJS strategy.
@@ -404,21 +502,17 @@ declare class PatternRegistry {
     getHandler(subject: string): MessageHandler | null;
     /** Get all registered broadcast patterns (for consumer filter_subject setup). */
     getBroadcastPatterns(): string[];
-    /** Check if any broadcast handlers are registered. */
     hasBroadcastHandlers(): boolean;
-    /** Check if any RPC (command) handlers are registered. */
     hasRpcHandlers(): boolean;
-    /** Check if any workqueue event handlers are registered. */
     hasEventHandlers(): boolean;
-    /** Check if any ordered event handlers are registered. */
     hasOrderedHandlers(): boolean;
     /** Get fully-qualified NATS subjects for ordered handlers. */
     getOrderedSubjects(): string[];
-    /** Get patterns grouped by kind. */
+    /** Get patterns grouped by kind (cached after registration). */
     getPatternsByKind(): PatternsByKind;
     /** Normalize a full NATS subject back to the user-facing pattern. */
     normalizeSubject(subject: string): string;
-    /** Log a summary of all registered handlers. */
+    private buildPatternsByKind;
     private logSummary;
 }
 
@@ -485,16 +579,6 @@ declare class StreamProvider {
     private getOverrides;
 }
 
-/** Options for dead letter queue handling. */
-interface DeadLetterConfig {
-    /**
-     * Map of stream name -> max_deliver value.
-     * Used to detect when a message from a given stream has exhausted all delivery attempts.
-     */
-    maxDeliverByStream: Map<string, number>;
-    /** Async callback invoked when a message exhausts all deliveries. */
-    onDeadLetter(info: DeadLetterInfo): Promise<void>;
-}
 /**
  * Routes incoming event messages (workqueue, broadcast, and ordered) to NestJS handlers.
  *
@@ -511,9 +595,11 @@ declare class EventRouter {
     private readonly codec;
     private readonly eventBus;
     private readonly deadLetterConfig?;
+    private readonly processingConfig?;
+    private readonly ackWaitMap?;
     private readonly logger;
     private readonly subscriptions;
-    constructor(messageProvider: MessageProvider, patternRegistry: PatternRegistry, codec: Codec, eventBus: EventBus, deadLetterConfig?: DeadLetterConfig | undefined);
+    constructor(messageProvider: MessageProvider, patternRegistry: PatternRegistry, codec: Codec, eventBus: EventBus, deadLetterConfig?: DeadLetterConfig | undefined, processingConfig?: EventProcessingConfig | undefined, ackWaitMap?: Map<StreamKind, number> | undefined);
     /**
      * Update the max_deliver thresholds from actual NATS consumer configs.
      * Called after consumers are ensured so the DLQ map reflects reality.
@@ -525,12 +611,16 @@ declare class EventRouter {
     destroy(): void;
     /** Subscribe to a message stream and route each message. */
     private subscribeToStream;
+    private getConcurrency;
+    private getAckExtensionConfig;
     /** Handle a single event message: decode -> execute handler -> ack/nak. */
     private handle;
-    /** Execute handler, then ack on success or nak/dead-letter on failure. */
-    private executeHandler;
     /** Handle an ordered message: decode -> execute handler -> no ack/nak. */
     private handleOrdered;
+    /** Resolve handler, decode payload, and build context. Returns null on failure. */
+    private decodeMessage;
+    /** Execute handler, then ack on success or nak/dead-letter on failure. */
+    private executeHandler;
     /** Check if the message has exhausted all delivery attempts. */
     private isDeadLetter;
     /** Handle a dead letter: invoke callback, then term or nak based on result. */
@@ -555,10 +645,16 @@ declare class RpcRouter {
     private readonly connection;
     private readonly codec;
     private readonly eventBus;
+    private readonly rpcOptions?;
+    private readonly ackWaitMap?;
     private readonly logger;
     private readonly timeout;
+    private readonly concurrency;
+    private resolvedAckExtensionInterval;
     private subscription;
-    constructor(messageProvider: MessageProvider, patternRegistry: PatternRegistry, connection: ConnectionProvider, codec: Codec, eventBus: EventBus, timeout?: number);
+    constructor(messageProvider: MessageProvider, patternRegistry: PatternRegistry, connection: ConnectionProvider, codec: Codec, eventBus: EventBus, rpcOptions?: RpcRouterOptions | undefined, ackWaitMap?: Map<StreamKind, number> | undefined);
+    /** Lazily resolve the ack extension interval (needs ackWaitMap populated at runtime). */
+    private get ackExtensionInterval();
     /** Start routing command messages to handlers. */
     start(): void;
     /** Stop routing and unsubscribe. */
@@ -612,6 +708,7 @@ declare class ConsumerProvider {
 declare class MessageProvider {
     private readonly connection;
     private readonly eventBus;
+    private readonly consumeOptionsMap;
     private readonly logger;
     private readonly activeIterators;
     private orderedReadyResolve;
@@ -621,7 +718,7 @@ declare class MessageProvider {
     private commandMessages$;
     private broadcastMessages$;
     private orderedMessages$;
-    constructor(connection: ConnectionProvider, eventBus: EventBus);
+    constructor(connection: ConnectionProvider, eventBus: EventBus, consumeOptionsMap?: Map<StreamKind, Partial<ConsumeOptions>>);
     /** Observable stream of workqueue event messages. */
     get events$(): Observable<JsMsg>;
     /** Observable stream of RPC command messages (jetstream mode). */
@@ -645,6 +742,7 @@ declare class MessageProvider {
      *
      * @param streamName - JetStream stream to consume from.
      * @param filterSubjects - NATS subjects to filter on.
+     * @param orderedConfig - Optional overrides for ordered consumer options.
      */
     startOrdered(streamName: string, filterSubjects: string[], orderedConfig?: OrderedEventOverrides): Promise<void>;
     /** Stop all consumer flows and reinitialize subjects for potential restart. */
@@ -655,8 +753,12 @@ declare class MessageProvider {
     private consumeOnce;
     /** Get the target subject for a consumer kind. */
     private getTargetSubject;
+    /** Monitor heartbeats and restart the consumer iterator on prolonged silence. */
+    private monitorConsumerHealth;
     /** Create a self-healing ordered consumer flow. */
     private createOrderedFlow;
+    /** Shared self-healing flow: defer -> retry with exponential backoff on error/completion. */
+    private createSelfHealingFlow;
     /** Single iteration: create ordered consumer -> iterate messages. */
     private consumeOrderedOnce;
 }
@@ -682,10 +784,11 @@ declare class JetstreamStrategy extends Server implements CustomTransportStrateg
     private readonly eventRouter;
     private readonly rpcRouter;
     private readonly coreRpcServer;
+    private readonly ackWaitMap;
     readonly transportId: symbol;
     private readonly listeners;
     private started;
-    constructor(options: JetstreamModuleOptions, connection: ConnectionProvider, patternRegistry: PatternRegistry, streamProvider: StreamProvider, consumerProvider: ConsumerProvider, messageProvider: MessageProvider, eventRouter: EventRouter, rpcRouter: RpcRouter, coreRpcServer: CoreRpcServer);
+    constructor(options: JetstreamModuleOptions, connection: ConnectionProvider, patternRegistry: PatternRegistry, streamProvider: StreamProvider, consumerProvider: ConsumerProvider, messageProvider: MessageProvider, eventRouter: EventRouter, rpcRouter: RpcRouter, coreRpcServer: CoreRpcServer, ackWaitMap?: Map<StreamKind, number>);
     /**
      * Start the transport: register handlers, create infrastructure, begin consumption.
      *
@@ -709,16 +812,18 @@ declare class JetstreamStrategy extends Server implements CustomTransportStrateg
     unwrap<T>(): T;
     /** Access the pattern registry (for module-level introspection). */
     getPatternRegistry(): PatternRegistry;
-    /** Determine which JetStream streams are needed. */
-    private resolveStreamKinds;
-    /** Determine which stream kinds need durable consumers (ordered consumers are ephemeral). */
-    private resolveDurableConsumerKinds;
+    /** Determine which streams and durable consumers are needed. */
+    private resolveRequiredKinds;
+    /** Populate the shared ack_wait map from actual NATS consumer configs. */
+    private populateAckWaitMap;
     /** Build max_deliver map from actual NATS consumer configs (not options). */
     private buildMaxDeliverMap;
-    private isCoreRpcMode;
-    private isJetStreamRpcMode;
 }
 
+/** Minimal interface for anything that can be stopped during shutdown. */
+interface Stoppable {
+    close(): void;
+}
 /**
  * Orchestrates graceful transport shutdown.
  *
@@ -738,9 +843,9 @@ declare class ShutdownManager {
     /**
      * Execute the full shutdown sequence.
      *
-     * @param strategy Optional strategy to close (stops consumers and subscriptions).
+     * @param strategy Optional stoppable to close (stops consumers and subscriptions).
      */
-    shutdown(strategy?: JetstreamStrategy): Promise<void>;
+    shutdown(strategy?: Stoppable): Promise<void>;
 }
 
 /**
@@ -841,6 +946,8 @@ declare class JetstreamClient extends ClientProxy {
     private readonly logger;
     /** Target service name this client sends messages to. */
     private readonly targetName;
+    /** Pre-cached caller name derived from rootOptions.name, computed once in constructor. */
+    private readonly callerName;
     /** Shared inbox for JetStream-mode RPC responses. */
     private inbox;
     private inboxSubscription;
@@ -900,8 +1007,6 @@ declare class JetstreamClient extends ClientProxy {
     private buildHeaders;
     /** Extract data, headers, and timeout from raw packet data or JetstreamRecord. */
     private extractRecordData;
-    private isCoreRpcMode;
-    private isJetStreamRpcMode;
     private getRpcTimeout;
 }
 
@@ -1073,17 +1178,6 @@ declare class RpcContext extends BaseRpcContext<[NatsMessage]> {
     };
 }
 
-/**
- * Health status returned by {@link JetstreamHealthIndicator.check}.
- */
-interface JetstreamHealthStatus {
-    /** Whether the NATS connection is alive. */
-    connected: boolean;
-    /** NATS server URL, or `null` if not connected. */
-    server: string | null;
-    /** Round-trip latency in ms, or `null` if disconnected. */
-    latency: number | null;
-}
 /**
  * Health indicator result compatible with @nestjs/terminus.
  *
@@ -1184,5 +1278,19 @@ declare enum JetstreamHeader {
     /** Set to `'true'` on error responses so the client can distinguish success from failure. */
     Error = "x-error"
 }
+/**
+ * Prefixes used in event patterns to route to specific stream types.
+ * Applied by the user when emitting events (e.g. `client.emit('broadcast:config.updated', data)`).
+ */
+declare enum PatternPrefix {
+    /** Route to the shared broadcast stream. */
+    Broadcast = "broadcast:",
+    /** Route to the ordered stream. */
+    Ordered = "ordered:"
+}
+/** Check if the RPC config specifies JetStream mode. */
+declare const isJetStreamRpcMode: (rpc: RpcConfig | undefined) => boolean;
+/** Check if the RPC config specifies Core mode (default). */
+declare const isCoreRpcMode: (rpc: RpcConfig | undefined) => boolean;
 
-export { type Codec, type DeadLetterInfo, EventBus, JETSTREAM_CODEC, JETSTREAM_CONNECTION, JETSTREAM_EVENT_BUS, JETSTREAM_OPTIONS, JetstreamClient, type JetstreamFeatureOptions, JetstreamHeader, JetstreamHealthIndicator, type JetstreamHealthStatus, JetstreamModule, type JetstreamModuleAsyncOptions, type JetstreamModuleOptions, JetstreamRecord, JetstreamRecordBuilder, JetstreamStrategy, JsonCodec, type OrderedEventOverrides, type RpcConfig, RpcContext, type StreamConsumerOverrides, TransportEvent, type TransportHooks, getClientToken, toNanos };
+export { type Codec, type DeadLetterInfo, EventBus, JETSTREAM_CODEC, JETSTREAM_CONNECTION, JETSTREAM_EVENT_BUS, JETSTREAM_OPTIONS, JetstreamClient, type JetstreamFeatureOptions, JetstreamHeader, JetstreamHealthIndicator, type JetstreamHealthStatus, JetstreamModule, type JetstreamModuleAsyncOptions, type JetstreamModuleOptions, JetstreamRecord, JetstreamRecordBuilder, JetstreamStrategy, JsonCodec, MessageKind, type OrderedEventOverrides, PatternPrefix, type RpcConfig, RpcContext, type StreamConsumerOverrides, StreamKind, TransportEvent, type TransportHooks, getClientToken, isCoreRpcMode, isJetStreamRpcMode, toNanos };