@horizon-republic/nestjs-jetstream 2.5.1 → 2.7.0

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.
@@ -330,6 +416,12 @@ declare class EventBus {
      * @param args - Arguments matching the hook signature for this event.
      */
     emit<K extends keyof TransportHooks>(event: K, ...args: Parameters<TransportHooks[K]>): void;
+    /**
+     * Hot-path optimized emit for MessageRouted events.
+     * Avoids rest/spread overhead of the generic `emit()`.
+     */
+    emitMessageRouted(subject: string, kind: MessageKind): void;
+    private callHook;
 }
 
 /**
@@ -352,6 +444,7 @@ declare class ConnectionProvider {
     private readonly logger;
     private connection;
     private connectionPromise;
+    private jsClient;
     private jsmInstance;
     private jsmPromise;
     constructor(options: JetstreamModuleOptions, eventBus: EventBus);
@@ -367,6 +460,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 +496,11 @@ declare class PatternRegistry {
     private readonly options;
     private readonly logger;
     private readonly registry;
+    private cachedPatterns;
+    private _hasEvents;
+    private _hasCommands;
+    private _hasBroadcasts;
+    private _hasOrdered;
     constructor(options: JetstreamModuleOptions);
     /**
      * Register all handlers from the NestJS strategy.
@@ -404,21 +512,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 +589,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 +605,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 +621,16 @@ declare class EventRouter {
     destroy(): void;
     /** Subscribe to a message stream and route each message. */
     private subscribeToStream;
-    /** Handle a single event message: decode -> execute handler -> ack/nak. */
-    private handle;
+    private getConcurrency;
+    private getAckExtensionConfig;
+    /** Handle a single event message with error isolation. */
+    private handleSafe;
+    /** Handle an ordered message with error isolation. */
+    private handleOrderedSafe;
+    /** 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;
-    /** Handle an ordered message: decode -> execute handler -> no ack/nak. */
-    private handleOrdered;
     /** 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,16 +655,23 @@ 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);
+    private cachedNc;
+    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;
+    start(): Promise<void>;
     /** Stop routing and unsubscribe. */
     destroy(): void;
-    /** Handle a single RPC command message. */
-    private handle;
+    /** Handle a single RPC command message with error isolation. */
+    private handleSafe;
     /** Execute handler, publish response, settle message. */
     private executeHandler;
 }
@@ -612,6 +719,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 +729,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 +753,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 +764,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 +795,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 +823,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 +854,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 +957,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 +1018,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;
 }
 
@@ -1032,19 +1148,33 @@ type NatsMessage = JsMsg | Msg;
  * Execution context for RPC and event handlers.
  *
  * Provides convenient accessors for the NATS message, subject,
- * and headers without needing to interact with the raw message directly.
+ * headers, and JetStream metadata without needing to interact
+ * with the raw message directly.
+ *
+ * Handlers can also control message settlement via {@link retry}
+ * and {@link terminate} instead of throwing errors.
  *
  * @example
  * ```typescript
- * @MessagePattern('get.user')
- * getUser(data: GetUserDto, @Ctx() ctx: RpcContext) {
- *   const traceId = ctx.getHeader('x-trace-id');
- *   const subject = ctx.getSubject();
- *   return this.userService.findOne(data.id);
+ * @EventPattern('order.process')
+ * async handle(@Payload() data: OrderDto, @Ctx() ctx: RpcContext) {
+ *   if (ctx.getDeliveryCount()! >= 3) {
+ *     ctx.terminate('Max business retries exceeded');
+ *     return;
+ *   }
+ *   if (!this.isReady()) {
+ *     ctx.retry({ delay: 5000 });
+ *     return;
+ *   }
+ *   await this.process(data);
  * }
  * ```
  */
 declare class RpcContext extends BaseRpcContext<[NatsMessage]> {
+    private _shouldRetry;
+    private _retryDelay;
+    private _shouldTerminate;
+    private _terminateReason;
     /**
      * Get the underlying NATS message.
      *
@@ -1071,19 +1201,52 @@ declare class RpcContext extends BaseRpcContext<[NatsMessage]> {
     isJetStream(): this is RpcContext & {
         getMessage(): JsMsg;
     };
+    /** How many times this message has been delivered. */
+    getDeliveryCount(): number | undefined;
+    /** The JetStream stream this message belongs to. */
+    getStream(): string | undefined;
+    /** The stream sequence number. */
+    getSequence(): number | undefined;
+    /** The message timestamp as a `Date` (derived from `info.timestampNanos`). */
+    getTimestamp(): Date | undefined;
+    /** The name of the service that published this message (from `x-caller-name` header). */
+    getCallerName(): string | undefined;
+    /**
+     * Signal the transport to retry (nak) this message instead of acknowledging it.
+     *
+     * Use for business-level retries without throwing errors.
+     * Only affects JetStream event handlers (workqueue/broadcast).
+     *
+     * @param opts - Optional delay in ms before redelivery.
+     * @throws Error if {@link terminate} was already called.
+     */
+    retry(opts?: {
+        delayMs?: number;
+    }): void;
+    /**
+     * Signal the transport to permanently reject (term) this message.
+     *
+     * Use when a message is no longer relevant and should not be retried or sent to DLQ.
+     * Only affects JetStream event handlers (workqueue/broadcast).
+     *
+     * @param reason - Optional reason for termination (logged by NATS).
+     * @throws Error if {@link retry} was already called.
+     */
+    terminate(reason?: string): void;
+    /** Narrow to JsMsg or return null for Core messages. Used by metadata getters. */
+    private asJetStream;
+    /** Ensure the message is JetStream — settlement actions are not available for Core NATS. */
+    private assertJetStream;
+    /** @internal */
+    get shouldRetry(): boolean;
+    /** @internal */
+    get retryDelay(): number | undefined;
+    /** @internal */
+    get shouldTerminate(): boolean;
+    /** @internal */
+    get terminateReason(): string | undefined;
 }
 
-/**
- * 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 +1347,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 };