@horizon-republic/nestjs-jetstream 2.6.1 → 2.7.0

package/README.md

@@ -1,11 +1,36 @@
+<div align="center">
+
 # @horizon-republic/nestjs-jetstream
 
-Ship reliable microservices with NATS JetStream and NestJS. Events, broadcast, ordered delivery, and RPC — with two lines of config.
+**Ship reliable microservices with NATS JetStream and NestJS.**
+Events, broadcast, ordered delivery, and RPC — with two lines of config.
 
 [![npm version](https://img.shields.io/npm/v/@horizon-republic/nestjs-jetstream.svg)](https://www.npmjs.com/package/@horizon-republic/nestjs-jetstream)
 [![codecov](https://codecov.io/github/HorizonRepublic/nestjs-jetstream/graph/badge.svg?token=40IPSWFMT4)](https://codecov.io/github/HorizonRepublic/nestjs-jetstream)
+[![CI](https://github.com/HorizonRepublic/nestjs-jetstream/actions/workflows/coverage.yml/badge.svg)](https://github.com/HorizonRepublic/nestjs-jetstream/actions)
+[![Documentation](https://img.shields.io/badge/docs-online-brightgreen.svg)](https://horizonrepublic.github.io/nestjs-jetstream/)
+
+[![Node.js](https://img.shields.io/node/v/@horizon-republic/nestjs-jetstream.svg)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Socket Badge](https://badge.socket.dev/npm/package/@horizon-republic/nestjs-jetstream)](https://socket.dev/npm/package/@horizon-republic/nestjs-jetstream)
+
+</div>
+
+---
+
+## Why this library?
+
+NestJS ships with a NATS transport, but it's fire-and-forget. Messages vanish if no one's listening. This library adds JetStream — so your messages **survive restarts**, **retry on failure**, and **replay for new consumers**.
+
+You keep writing `@EventPattern()` and `@MessagePattern()`. The library handles streams, consumers, and subjects automatically.
+
+## What's inside
+
+**Delivery modes** — workqueue (one consumer), broadcast (all consumers), ordered (sequential), and dual-mode RPC (Core or JetStream-backed).
+
+**Production-ready** — dead letter queue, health checks, graceful shutdown with drain, lifecycle hooks for observability.
+
+**Flexible** — pluggable codecs (JSON/MsgPack/Protobuf), per-stream configuration, publisher-only mode for API gateways.
 
 ## Quick Start
 
@@ -44,9 +69,13 @@ export class OrdersController {
 
 **[Read the full documentation →](https://horizonrepublic.github.io/nestjs-jetstream/)**
 
-- [Getting Started](https://horizonrepublic.github.io/nestjs-jetstream/docs/getting-started) — installation, module setup, first handler
-- [Guides](https://horizonrepublic.github.io/nestjs-jetstream/docs/guides/health-checks) — health checks, graceful shutdown, lifecycle hooks
-- [API Reference](https://horizonrepublic.github.io/nestjs-jetstream/docs/reference/api/) — full TypeDoc-generated API
+| Section | What you'll learn |
+|---------|-------------------|
+| [Getting Started](https://horizonrepublic.github.io/nestjs-jetstream/docs/getting-started/installation) | Installation, module setup, first handler |
+| [Messaging Patterns](https://horizonrepublic.github.io/nestjs-jetstream/docs/patterns/rpc) | RPC, Events, Broadcast, Ordered Events |
+| [Guides](https://horizonrepublic.github.io/nestjs-jetstream/docs/guides/record-builder) | Handler context, DLQ, health checks, performance tuning |
+| [Migration](https://horizonrepublic.github.io/nestjs-jetstream/docs/guides/migration) | From built-in NATS transport or between versions |
+| [API Reference](https://horizonrepublic.github.io/nestjs-jetstream/docs/reference/api/) | Full TypeDoc-generated API |
 
 ## Links
 

package/dist/index.cjs

@@ -830,6 +830,23 @@ var EventBus = class {
   emit(event, ...args) {
     const hook = this.hooks[event];
     if (!hook) return;
+    this.callHook(event, hook, ...args);
+  }
+  /**
+   * Hot-path optimized emit for MessageRouted events.
+   * Avoids rest/spread overhead of the generic `emit()`.
+   */
+  emitMessageRouted(subject, kind) {
+    const hook = this.hooks["messageRouted" /* MessageRouted */];
+    if (!hook) return;
+    this.callHook(
+      "messageRouted" /* MessageRouted */,
+      hook,
+      subject,
+      kind
+    );
+  }
+  callHook(event, hook, ...args) {
     try {
       const result = hook(...args);
       if (result && typeof result.catch === "function") {
@@ -959,7 +976,7 @@ var JetstreamStrategy = class extends import_microservices2.Server {
         this.eventRouter.start();
       }
       if (isJetStreamRpcMode(this.options.rpc) && this.patternRegistry.hasRpcHandlers()) {
-        this.rpcRouter.start();
+        await this.rpcRouter.start();
       }
     }
     if (isCoreRpcMode(this.options.rpc) && this.patternRegistry.hasRpcHandlers()) {
@@ -1053,6 +1070,13 @@ var import_nats5 = require("nats");
 // src/context/rpc.context.ts
 var import_microservices3 = require("@nestjs/microservices");
 var RpcContext = class extends import_microservices3.BaseRpcContext {
+  _shouldRetry = false;
+  _retryDelay;
+  _shouldTerminate = false;
+  _terminateReason;
+  // ---------------------------------------------------------------------------
+  // Message accessors
+  // ---------------------------------------------------------------------------
   /**
    * Get the underlying NATS message.
    *
@@ -1087,6 +1111,96 @@ var RpcContext = class extends import_microservices3.BaseRpcContext {
   isJetStream() {
     return "ack" in this.args[0];
   }
+  // ---------------------------------------------------------------------------
+  // JetStream metadata (return undefined for Core NATS messages)
+  // ---------------------------------------------------------------------------
+  /** How many times this message has been delivered. */
+  getDeliveryCount() {
+    return this.asJetStream()?.info.deliveryCount;
+  }
+  /** The JetStream stream this message belongs to. */
+  getStream() {
+    return this.asJetStream()?.info.stream;
+  }
+  /** The stream sequence number. */
+  getSequence() {
+    return this.asJetStream()?.seq;
+  }
+  /** The message timestamp as a `Date` (derived from `info.timestampNanos`). */
+  getTimestamp() {
+    const nanos = this.asJetStream()?.info.timestampNanos;
+    return typeof nanos === "number" ? new Date(nanos / 1e6) : void 0;
+  }
+  /** The name of the service that published this message (from `x-caller-name` header). */
+  getCallerName() {
+    return this.getHeader("x-caller-name" /* CallerName */);
+  }
+  // ---------------------------------------------------------------------------
+  // Handler-controlled settlement
+  // ---------------------------------------------------------------------------
+  /**
+   * 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) {
+    this.assertJetStream("retry");
+    if (this._shouldTerminate) {
+      throw new Error("Cannot retry \u2014 terminate() was already called");
+    }
+    this._shouldRetry = true;
+    this._retryDelay = opts?.delayMs;
+  }
+  /**
+   * 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) {
+    this.assertJetStream("terminate");
+    if (this._shouldRetry) {
+      throw new Error("Cannot terminate \u2014 retry() was already called");
+    }
+    this._shouldTerminate = true;
+    this._terminateReason = reason;
+  }
+  /** Narrow to JsMsg or return null for Core messages. Used by metadata getters. */
+  asJetStream() {
+    return this.isJetStream() ? this.args[0] : null;
+  }
+  /** Ensure the message is JetStream — settlement actions are not available for Core NATS. */
+  assertJetStream(method) {
+    if (!this.isJetStream()) {
+      throw new Error(`${method}() is only available for JetStream messages`);
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Transport-facing state (read by EventRouter)
+  // ---------------------------------------------------------------------------
+  /** @internal */
+  get shouldRetry() {
+    return this._shouldRetry;
+  }
+  /** @internal */
+  get retryDelay() {
+    return this._retryDelay;
+  }
+  /** @internal */
+  get shouldTerminate() {
+    return this._shouldTerminate;
+  }
+  /** @internal */
+  get terminateReason() {
+    return this._terminateReason;
+  }
 };
 
 // src/utils/ack-extension.ts
@@ -1125,15 +1239,20 @@ var serializeError = (err) => {
 
 // src/utils/unwrap-result.ts
 var import_rxjs2 = require("rxjs");
-var unwrapResult = async (result) => {
+var RESOLVED_VOID = Promise.resolve(void 0);
+var RESOLVED_NULL = Promise.resolve(null);
+var unwrapResult = (result) => {
+  if (result === void 0) return RESOLVED_VOID;
+  if (result === null) return RESOLVED_NULL;
   if ((0, import_rxjs2.isObservable)(result)) {
     return subscribeToFirst(result);
   }
-  const resolved = await result;
-  if ((0, import_rxjs2.isObservable)(resolved)) {
-    return subscribeToFirst(resolved);
+  if (typeof result.then === "function") {
+    return result.then(
+      (resolved) => (0, import_rxjs2.isObservable)(resolved) ? subscribeToFirst(resolved) : resolved
+    );
   }
-  return resolved;
+  return Promise.resolve(result);
 };
 var subscribeToFirst = (obs) => new Promise((resolve, reject) => {
   let done = false;
@@ -1211,7 +1330,7 @@ var CoreRpcServer = class {
       this.respondWithError(msg, new Error(`No handler for subject: ${msg.subject}`));
       return;
     }
-    this.eventBus.emit("messageRouted" /* MessageRouted */, msg.subject, "rpc" /* Rpc */);
+    this.eventBus.emitMessageRouted(msg.subject, "rpc" /* Rpc */);
     let data;
     try {
       data = this.codec.decode(msg.data);
@@ -1696,6 +1815,10 @@ var PatternRegistry = class {
   registry = /* @__PURE__ */ new Map();
   // Cached after registerHandlers() — the registry is immutable from that point
   cachedPatterns = null;
+  _hasEvents = false;
+  _hasCommands = false;
+  _hasBroadcasts = false;
+  _hasOrdered = false;
   /**
    * Register all handlers from the NestJS strategy.
    *
@@ -1729,6 +1852,10 @@ var PatternRegistry = class {
       this.logger.debug(`Registered ${HANDLER_LABELS[kind]}: ${pattern} -> ${fullSubject}`);
     }
     this.cachedPatterns = this.buildPatternsByKind();
+    this._hasEvents = this.cachedPatterns.events.length > 0;
+    this._hasCommands = this.cachedPatterns.commands.length > 0;
+    this._hasBroadcasts = this.cachedPatterns.broadcasts.length > 0;
+    this._hasOrdered = this.cachedPatterns.ordered.length > 0;
     this.logSummary();
   }
   /** Find handler for a full NATS subject. */
@@ -1740,16 +1867,16 @@ var PatternRegistry = class {
     return this.getPatternsByKind().broadcasts.map((p) => buildBroadcastSubject(p));
   }
   hasBroadcastHandlers() {
-    return this.getPatternsByKind().broadcasts.length > 0;
+    return this._hasBroadcasts;
   }
   hasRpcHandlers() {
-    return this.getPatternsByKind().commands.length > 0;
+    return this._hasCommands;
   }
   hasEventHandlers() {
-    return this.getPatternsByKind().events.length > 0;
+    return this._hasEvents;
   }
   hasOrderedHandlers() {
-    return this.getPatternsByKind().ordered.length > 0;
+    return this._hasOrdered;
   }
   /** Get fully-qualified NATS subjects for ordered handlers. */
   getOrderedSubjects() {
@@ -1853,13 +1980,8 @@ var EventRouter = class {
     const isOrdered = kind === "ordered" /* Ordered */;
     const ackExtensionInterval = isOrdered ? null : resolveAckExtensionInterval(this.getAckExtensionConfig(kind), this.ackWaitMap?.get(kind));
     const concurrency = this.getConcurrency(kind);
-    const route = (msg) => (0, import_rxjs4.defer)(
-      () => isOrdered ? this.handleOrdered(msg) : this.handle(msg, ackExtensionInterval)
-    ).pipe(
-      (0, import_rxjs4.catchError)((err) => {
-        this.logger.error(`Unexpected error in ${kind} event router`, err);
-        return import_rxjs4.EMPTY;
-      })
+    const route = (msg) => (0, import_rxjs4.from)(
+      isOrdered ? this.handleOrderedSafe(msg) : this.handleSafe(msg, ackExtensionInterval, kind)
     );
     const subscription = stream$.pipe(isOrdered ? (0, import_rxjs4.concatMap)(route) : (0, import_rxjs4.mergeMap)(route, concurrency)).subscribe();
     this.subscriptions.push(subscription);
@@ -1874,23 +1996,36 @@ var EventRouter = class {
     if (kind === "broadcast" /* Broadcast */) return this.processingConfig?.broadcast?.ackExtension;
     return void 0;
   }
-  /** Handle a single event message: decode -> execute handler -> ack/nak. */
-  handle(msg, ackExtensionInterval) {
-    const resolved = this.decodeMessage(msg);
-    if (!resolved) return import_rxjs4.EMPTY;
-    return (0, import_rxjs4.from)(
-      this.executeHandler(resolved.handler, resolved.data, resolved.ctx, msg, ackExtensionInterval)
-    );
+  /** Handle a single event message with error isolation. */
+  async handleSafe(msg, ackExtensionInterval, kind) {
+    try {
+      const resolved = this.decodeMessage(msg);
+      if (!resolved) return;
+      await this.executeHandler(
+        resolved.handler,
+        resolved.data,
+        resolved.ctx,
+        msg,
+        ackExtensionInterval
+      );
+    } catch (err) {
+      this.logger.error(`Unexpected error in ${kind} event router`, err);
+    }
   }
-  /** Handle an ordered message: decode -> execute handler -> no ack/nak. */
-  handleOrdered(msg) {
-    const resolved = this.decodeMessage(msg, true);
-    if (!resolved) return import_rxjs4.EMPTY;
-    return (0, import_rxjs4.from)(
-      unwrapResult(resolved.handler(resolved.data, resolved.ctx)).catch((err) => {
-        this.logger.error(`Ordered handler error (${msg.subject}):`, err);
-      })
-    );
+  /** Handle an ordered message with error isolation. */
+  async handleOrderedSafe(msg) {
+    try {
+      const resolved = this.decodeMessage(msg, true);
+      if (!resolved) return;
+      await unwrapResult(resolved.handler(resolved.data, resolved.ctx));
+      if (resolved.ctx.shouldRetry || resolved.ctx.shouldTerminate) {
+        this.logger.warn(
+          `retry()/terminate() ignored for ordered message ${msg.subject} \u2014 ordered consumers auto-acknowledge`
+        );
+      }
+    } catch (err) {
+      this.logger.error(`Ordered handler error (${msg.subject}):`, err);
+    }
   }
   /** Resolve handler, decode payload, and build context. Returns null on failure. */
   decodeMessage(msg, isOrdered = false) {
@@ -1908,7 +2043,7 @@ var EventRouter = class {
       this.logger.error(`Decode error for ${msg.subject}:`, err);
       return null;
     }
-    this.eventBus.emit("messageRouted" /* MessageRouted */, msg.subject, "event" /* Event */);
+    this.eventBus.emitMessageRouted(msg.subject, "event" /* Event */);
     return { handler, data, ctx: new RpcContext([msg]) };
   }
   /** Execute handler, then ack on success or nak/dead-letter on failure. */
@@ -1916,7 +2051,13 @@ var EventRouter = class {
     const stopAckExtension = startAckExtensionTimer(msg, ackExtensionInterval);
     try {
       await unwrapResult(handler(data, ctx));
-      msg.ack();
+      if (ctx.shouldTerminate) {
+        msg.term(ctx.terminateReason);
+      } else if (ctx.shouldRetry) {
+        msg.nak(ctx.retryDelay);
+      } else {
+        msg.ack();
+      }
     } catch (err) {
       this.logger.error(`Event handler error (${msg.subject}):`, err);
       if (this.isDeadLetter(msg)) {
@@ -1983,6 +2124,7 @@ var RpcRouter = class {
   concurrency;
   resolvedAckExtensionInterval;
   subscription = null;
+  cachedNc = null;
   /** Lazily resolve the ack extension interval (needs ackWaitMap populated at runtime). */
   get ackExtensionInterval() {
     if (this.resolvedAckExtensionInterval !== void 0) return this.resolvedAckExtensionInterval;
@@ -1993,56 +2135,50 @@ var RpcRouter = class {
     return this.resolvedAckExtensionInterval;
   }
   /** Start routing command messages to handlers. */
-  start() {
-    this.subscription = this.messageProvider.commands$.pipe(
-      (0, import_rxjs5.mergeMap)(
-        (msg) => (0, import_rxjs5.defer)(() => this.handle(msg)).pipe(
-          (0, import_rxjs5.catchError)((err) => {
-            this.logger.error("Unexpected error in RPC router", err);
-            return import_rxjs5.EMPTY;
-          })
-        ),
-        this.concurrency
-      )
-    ).subscribe();
+  async start() {
+    this.cachedNc = await this.connection.getConnection();
+    this.subscription = this.messageProvider.commands$.pipe((0, import_rxjs5.mergeMap)((msg) => (0, import_rxjs5.from)(this.handleSafe(msg)), this.concurrency)).subscribe();
   }
   /** Stop routing and unsubscribe. */
   destroy() {
     this.subscription?.unsubscribe();
     this.subscription = null;
   }
-  /** Handle a single RPC command message. */
-  handle(msg) {
-    const handler = this.patternRegistry.getHandler(msg.subject);
-    if (!handler) {
-      msg.term(`No handler for RPC: ${msg.subject}`);
-      this.logger.error(`No handler for RPC subject: ${msg.subject}`);
-      return import_rxjs5.EMPTY;
-    }
-    const replyTo = msg.headers?.get("x-reply-to" /* ReplyTo */);
-    const correlationId = msg.headers?.get("x-correlation-id" /* CorrelationId */);
-    if (!replyTo || !correlationId) {
-      msg.term("Missing required headers (reply-to or correlation-id)");
-      this.logger.error(`Missing headers for RPC: ${msg.subject}`);
-      return import_rxjs5.EMPTY;
-    }
-    let data;
+  /** Handle a single RPC command message with error isolation. */
+  async handleSafe(msg) {
     try {
-      data = this.codec.decode(msg.data);
+      const handler = this.patternRegistry.getHandler(msg.subject);
+      if (!handler) {
+        msg.term(`No handler for RPC: ${msg.subject}`);
+        this.logger.error(`No handler for RPC subject: ${msg.subject}`);
+        return;
+      }
+      const { headers: msgHeaders } = msg;
+      const replyTo = msgHeaders?.get("x-reply-to" /* ReplyTo */);
+      const correlationId = msgHeaders?.get("x-correlation-id" /* CorrelationId */);
+      if (!replyTo || !correlationId) {
+        msg.term("Missing required headers (reply-to or correlation-id)");
+        this.logger.error(`Missing headers for RPC: ${msg.subject}`);
+        return;
+      }
+      let data;
+      try {
+        data = this.codec.decode(msg.data);
+      } catch (err) {
+        msg.term("Decode error");
+        this.logger.error(`Decode error for RPC ${msg.subject}:`, err);
+        return;
+      }
+      this.eventBus.emitMessageRouted(msg.subject, "rpc" /* Rpc */);
+      await this.executeHandler(handler, data, msg, replyTo, correlationId);
     } catch (err) {
-      msg.term("Decode error");
-      this.logger.error(`Decode error for RPC ${msg.subject}:`, err);
-      return import_rxjs5.EMPTY;
+      this.logger.error("Unexpected error in RPC router", err);
     }
-    this.eventBus.emit("messageRouted" /* MessageRouted */, msg.subject, "rpc" /* Rpc */);
-    return (0, import_rxjs5.from)(this.executeHandler(handler, data, msg, replyTo, correlationId));
   }
   /** Execute handler, publish response, settle message. */
   async executeHandler(handler, data, msg, replyTo, correlationId) {
-    const nc = await this.connection.getConnection();
+    const nc = this.cachedNc ?? await this.connection.getConnection();
     const ctx = new RpcContext([msg]);
-    const hdrs = (0, import_nats9.headers)();
-    hdrs.set("x-correlation-id" /* CorrelationId */, correlationId);
     let settled = false;
     const stopAckExtension = startAckExtensionTimer(msg, this.ackExtensionInterval);
     const timeoutId = setTimeout(() => {
@@ -2061,6 +2197,8 @@ var RpcRouter = class {
       stopAckExtension?.();
       msg.ack();
       try {
+        const hdrs = (0, import_nats9.headers)();
+        hdrs.set("x-correlation-id" /* CorrelationId */, correlationId);
         nc.publish(replyTo, this.codec.encode(result), { headers: hdrs });
       } catch (publishErr) {
         this.logger.error(`Failed to publish RPC response for ${msg.subject}`, publishErr);
@@ -2071,6 +2209,8 @@ var RpcRouter = class {
       clearTimeout(timeoutId);
       stopAckExtension?.();
       try {
+        const hdrs = (0, import_nats9.headers)();
+        hdrs.set("x-correlation-id" /* CorrelationId */, correlationId);
         hdrs.set("x-error" /* Error */, "true");
         nc.publish(replyTo, this.codec.encode(serializeError(err)), { headers: hdrs });
       } catch (encodeErr) {

package/dist/index.d.cts

@@ -416,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;
 }
 
 /**
@@ -491,6 +497,10 @@ declare class PatternRegistry {
     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.
@@ -613,10 +623,10 @@ declare class EventRouter {
     private subscribeToStream;
     private getConcurrency;
     private getAckExtensionConfig;
-    /** Handle a single event message: decode -> execute handler -> ack/nak. */
-    private handle;
-    /** Handle an ordered message: decode -> execute handler -> no ack/nak. */
-    private handleOrdered;
+    /** 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. */
@@ -652,15 +662,16 @@ declare class RpcRouter {
     private readonly concurrency;
     private resolvedAckExtensionInterval;
     private subscription;
+    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;
 }
@@ -1137,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.
      *
@@ -1176,6 +1201,50 @@ 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;
 }
 
 /**

package/dist/index.d.ts

@@ -416,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;
 }
 
 /**
@@ -491,6 +497,10 @@ declare class PatternRegistry {
     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.
@@ -613,10 +623,10 @@ declare class EventRouter {
     private subscribeToStream;
     private getConcurrency;
     private getAckExtensionConfig;
-    /** Handle a single event message: decode -> execute handler -> ack/nak. */
-    private handle;
-    /** Handle an ordered message: decode -> execute handler -> no ack/nak. */
-    private handleOrdered;
+    /** 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. */
@@ -652,15 +662,16 @@ declare class RpcRouter {
     private readonly concurrency;
     private resolvedAckExtensionInterval;
     private subscription;
+    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;
 }
@@ -1137,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.
      *
@@ -1176,6 +1201,50 @@ 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;
 }
 
 /**

package/dist/index.js

@@ -809,6 +809,23 @@ var EventBus = class {
   emit(event, ...args) {
     const hook = this.hooks[event];
     if (!hook) return;
+    this.callHook(event, hook, ...args);
+  }
+  /**
+   * Hot-path optimized emit for MessageRouted events.
+   * Avoids rest/spread overhead of the generic `emit()`.
+   */
+  emitMessageRouted(subject, kind) {
+    const hook = this.hooks["messageRouted" /* MessageRouted */];
+    if (!hook) return;
+    this.callHook(
+      "messageRouted" /* MessageRouted */,
+      hook,
+      subject,
+      kind
+    );
+  }
+  callHook(event, hook, ...args) {
     try {
       const result = hook(...args);
       if (result && typeof result.catch === "function") {
@@ -938,7 +955,7 @@ var JetstreamStrategy = class extends Server {
         this.eventRouter.start();
       }
       if (isJetStreamRpcMode(this.options.rpc) && this.patternRegistry.hasRpcHandlers()) {
-        this.rpcRouter.start();
+        await this.rpcRouter.start();
       }
     }
     if (isCoreRpcMode(this.options.rpc) && this.patternRegistry.hasRpcHandlers()) {
@@ -1032,6 +1049,13 @@ import { headers as natsHeaders2 } from "nats";
 // src/context/rpc.context.ts
 import { BaseRpcContext } from "@nestjs/microservices";
 var RpcContext = class extends BaseRpcContext {
+  _shouldRetry = false;
+  _retryDelay;
+  _shouldTerminate = false;
+  _terminateReason;
+  // ---------------------------------------------------------------------------
+  // Message accessors
+  // ---------------------------------------------------------------------------
   /**
    * Get the underlying NATS message.
    *
@@ -1066,6 +1090,96 @@ var RpcContext = class extends BaseRpcContext {
   isJetStream() {
     return "ack" in this.args[0];
   }
+  // ---------------------------------------------------------------------------
+  // JetStream metadata (return undefined for Core NATS messages)
+  // ---------------------------------------------------------------------------
+  /** How many times this message has been delivered. */
+  getDeliveryCount() {
+    return this.asJetStream()?.info.deliveryCount;
+  }
+  /** The JetStream stream this message belongs to. */
+  getStream() {
+    return this.asJetStream()?.info.stream;
+  }
+  /** The stream sequence number. */
+  getSequence() {
+    return this.asJetStream()?.seq;
+  }
+  /** The message timestamp as a `Date` (derived from `info.timestampNanos`). */
+  getTimestamp() {
+    const nanos = this.asJetStream()?.info.timestampNanos;
+    return typeof nanos === "number" ? new Date(nanos / 1e6) : void 0;
+  }
+  /** The name of the service that published this message (from `x-caller-name` header). */
+  getCallerName() {
+    return this.getHeader("x-caller-name" /* CallerName */);
+  }
+  // ---------------------------------------------------------------------------
+  // Handler-controlled settlement
+  // ---------------------------------------------------------------------------
+  /**
+   * 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) {
+    this.assertJetStream("retry");
+    if (this._shouldTerminate) {
+      throw new Error("Cannot retry \u2014 terminate() was already called");
+    }
+    this._shouldRetry = true;
+    this._retryDelay = opts?.delayMs;
+  }
+  /**
+   * 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) {
+    this.assertJetStream("terminate");
+    if (this._shouldRetry) {
+      throw new Error("Cannot terminate \u2014 retry() was already called");
+    }
+    this._shouldTerminate = true;
+    this._terminateReason = reason;
+  }
+  /** Narrow to JsMsg or return null for Core messages. Used by metadata getters. */
+  asJetStream() {
+    return this.isJetStream() ? this.args[0] : null;
+  }
+  /** Ensure the message is JetStream — settlement actions are not available for Core NATS. */
+  assertJetStream(method) {
+    if (!this.isJetStream()) {
+      throw new Error(`${method}() is only available for JetStream messages`);
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Transport-facing state (read by EventRouter)
+  // ---------------------------------------------------------------------------
+  /** @internal */
+  get shouldRetry() {
+    return this._shouldRetry;
+  }
+  /** @internal */
+  get retryDelay() {
+    return this._retryDelay;
+  }
+  /** @internal */
+  get shouldTerminate() {
+    return this._shouldTerminate;
+  }
+  /** @internal */
+  get terminateReason() {
+    return this._terminateReason;
+  }
 };
 
 // src/utils/ack-extension.ts
@@ -1104,15 +1218,20 @@ var serializeError = (err) => {
 
 // src/utils/unwrap-result.ts
 import { isObservable } from "rxjs";
-var unwrapResult = async (result) => {
+var RESOLVED_VOID = Promise.resolve(void 0);
+var RESOLVED_NULL = Promise.resolve(null);
+var unwrapResult = (result) => {
+  if (result === void 0) return RESOLVED_VOID;
+  if (result === null) return RESOLVED_NULL;
   if (isObservable(result)) {
     return subscribeToFirst(result);
   }
-  const resolved = await result;
-  if (isObservable(resolved)) {
-    return subscribeToFirst(resolved);
+  if (typeof result.then === "function") {
+    return result.then(
+      (resolved) => isObservable(resolved) ? subscribeToFirst(resolved) : resolved
+    );
   }
-  return resolved;
+  return Promise.resolve(result);
 };
 var subscribeToFirst = (obs) => new Promise((resolve, reject) => {
   let done = false;
@@ -1190,7 +1309,7 @@ var CoreRpcServer = class {
       this.respondWithError(msg, new Error(`No handler for subject: ${msg.subject}`));
       return;
     }
-    this.eventBus.emit("messageRouted" /* MessageRouted */, msg.subject, "rpc" /* Rpc */);
+    this.eventBus.emitMessageRouted(msg.subject, "rpc" /* Rpc */);
     let data;
     try {
       data = this.codec.decode(msg.data);
@@ -1688,6 +1807,10 @@ var PatternRegistry = class {
   registry = /* @__PURE__ */ new Map();
   // Cached after registerHandlers() — the registry is immutable from that point
   cachedPatterns = null;
+  _hasEvents = false;
+  _hasCommands = false;
+  _hasBroadcasts = false;
+  _hasOrdered = false;
   /**
    * Register all handlers from the NestJS strategy.
    *
@@ -1721,6 +1844,10 @@ var PatternRegistry = class {
       this.logger.debug(`Registered ${HANDLER_LABELS[kind]}: ${pattern} -> ${fullSubject}`);
     }
     this.cachedPatterns = this.buildPatternsByKind();
+    this._hasEvents = this.cachedPatterns.events.length > 0;
+    this._hasCommands = this.cachedPatterns.commands.length > 0;
+    this._hasBroadcasts = this.cachedPatterns.broadcasts.length > 0;
+    this._hasOrdered = this.cachedPatterns.ordered.length > 0;
     this.logSummary();
   }
   /** Find handler for a full NATS subject. */
@@ -1732,16 +1859,16 @@ var PatternRegistry = class {
     return this.getPatternsByKind().broadcasts.map((p) => buildBroadcastSubject(p));
   }
   hasBroadcastHandlers() {
-    return this.getPatternsByKind().broadcasts.length > 0;
+    return this._hasBroadcasts;
   }
   hasRpcHandlers() {
-    return this.getPatternsByKind().commands.length > 0;
+    return this._hasCommands;
   }
   hasEventHandlers() {
-    return this.getPatternsByKind().events.length > 0;
+    return this._hasEvents;
   }
   hasOrderedHandlers() {
-    return this.getPatternsByKind().ordered.length > 0;
+    return this._hasOrdered;
   }
   /** Get fully-qualified NATS subjects for ordered handlers. */
   getOrderedSubjects() {
@@ -1804,14 +1931,7 @@ var PatternRegistry = class {
 
 // src/server/routing/event.router.ts
 import { Logger as Logger9 } from "@nestjs/common";
-import {
-  catchError as catchError2,
-  concatMap,
-  defer as defer3,
-  EMPTY as EMPTY2,
-  from as from2,
-  mergeMap
-} from "rxjs";
+import { concatMap, from as from2, mergeMap } from "rxjs";
 var EventRouter = class {
   constructor(messageProvider, patternRegistry, codec, eventBus, deadLetterConfig, processingConfig, ackWaitMap) {
     this.messageProvider = messageProvider;
@@ -1852,13 +1972,8 @@ var EventRouter = class {
     const isOrdered = kind === "ordered" /* Ordered */;
     const ackExtensionInterval = isOrdered ? null : resolveAckExtensionInterval(this.getAckExtensionConfig(kind), this.ackWaitMap?.get(kind));
     const concurrency = this.getConcurrency(kind);
-    const route = (msg) => defer3(
-      () => isOrdered ? this.handleOrdered(msg) : this.handle(msg, ackExtensionInterval)
-    ).pipe(
-      catchError2((err) => {
-        this.logger.error(`Unexpected error in ${kind} event router`, err);
-        return EMPTY2;
-      })
+    const route = (msg) => from2(
+      isOrdered ? this.handleOrderedSafe(msg) : this.handleSafe(msg, ackExtensionInterval, kind)
     );
     const subscription = stream$.pipe(isOrdered ? concatMap(route) : mergeMap(route, concurrency)).subscribe();
     this.subscriptions.push(subscription);
@@ -1873,23 +1988,36 @@ var EventRouter = class {
     if (kind === "broadcast" /* Broadcast */) return this.processingConfig?.broadcast?.ackExtension;
     return void 0;
   }
-  /** Handle a single event message: decode -> execute handler -> ack/nak. */
-  handle(msg, ackExtensionInterval) {
-    const resolved = this.decodeMessage(msg);
-    if (!resolved) return EMPTY2;
-    return from2(
-      this.executeHandler(resolved.handler, resolved.data, resolved.ctx, msg, ackExtensionInterval)
-    );
+  /** Handle a single event message with error isolation. */
+  async handleSafe(msg, ackExtensionInterval, kind) {
+    try {
+      const resolved = this.decodeMessage(msg);
+      if (!resolved) return;
+      await this.executeHandler(
+        resolved.handler,
+        resolved.data,
+        resolved.ctx,
+        msg,
+        ackExtensionInterval
+      );
+    } catch (err) {
+      this.logger.error(`Unexpected error in ${kind} event router`, err);
+    }
   }
-  /** Handle an ordered message: decode -> execute handler -> no ack/nak. */
-  handleOrdered(msg) {
-    const resolved = this.decodeMessage(msg, true);
-    if (!resolved) return EMPTY2;
-    return from2(
-      unwrapResult(resolved.handler(resolved.data, resolved.ctx)).catch((err) => {
-        this.logger.error(`Ordered handler error (${msg.subject}):`, err);
-      })
-    );
+  /** Handle an ordered message with error isolation. */
+  async handleOrderedSafe(msg) {
+    try {
+      const resolved = this.decodeMessage(msg, true);
+      if (!resolved) return;
+      await unwrapResult(resolved.handler(resolved.data, resolved.ctx));
+      if (resolved.ctx.shouldRetry || resolved.ctx.shouldTerminate) {
+        this.logger.warn(
+          `retry()/terminate() ignored for ordered message ${msg.subject} \u2014 ordered consumers auto-acknowledge`
+        );
+      }
+    } catch (err) {
+      this.logger.error(`Ordered handler error (${msg.subject}):`, err);
+    }
   }
   /** Resolve handler, decode payload, and build context. Returns null on failure. */
   decodeMessage(msg, isOrdered = false) {
@@ -1907,7 +2035,7 @@ var EventRouter = class {
       this.logger.error(`Decode error for ${msg.subject}:`, err);
       return null;
     }
-    this.eventBus.emit("messageRouted" /* MessageRouted */, msg.subject, "event" /* Event */);
+    this.eventBus.emitMessageRouted(msg.subject, "event" /* Event */);
     return { handler, data, ctx: new RpcContext([msg]) };
   }
   /** Execute handler, then ack on success or nak/dead-letter on failure. */
@@ -1915,7 +2043,13 @@ var EventRouter = class {
     const stopAckExtension = startAckExtensionTimer(msg, ackExtensionInterval);
     try {
       await unwrapResult(handler(data, ctx));
-      msg.ack();
+      if (ctx.shouldTerminate) {
+        msg.term(ctx.terminateReason);
+      } else if (ctx.shouldRetry) {
+        msg.nak(ctx.retryDelay);
+      } else {
+        msg.ack();
+      }
     } catch (err) {
       this.logger.error(`Event handler error (${msg.subject}):`, err);
       if (this.isDeadLetter(msg)) {
@@ -1964,7 +2098,7 @@ var EventRouter = class {
 // src/server/routing/rpc.router.ts
 import { Logger as Logger10 } from "@nestjs/common";
 import { headers } from "nats";
-import { catchError as catchError3, defer as defer4, EMPTY as EMPTY3, from as from3, mergeMap as mergeMap2 } from "rxjs";
+import { from as from3, mergeMap as mergeMap2 } from "rxjs";
 var RpcRouter = class {
   constructor(messageProvider, patternRegistry, connection, codec, eventBus, rpcOptions, ackWaitMap) {
     this.messageProvider = messageProvider;
@@ -1982,6 +2116,7 @@ var RpcRouter = class {
   concurrency;
   resolvedAckExtensionInterval;
   subscription = null;
+  cachedNc = null;
   /** Lazily resolve the ack extension interval (needs ackWaitMap populated at runtime). */
   get ackExtensionInterval() {
     if (this.resolvedAckExtensionInterval !== void 0) return this.resolvedAckExtensionInterval;
@@ -1992,56 +2127,50 @@ var RpcRouter = class {
     return this.resolvedAckExtensionInterval;
   }
   /** Start routing command messages to handlers. */
-  start() {
-    this.subscription = this.messageProvider.commands$.pipe(
-      mergeMap2(
-        (msg) => defer4(() => this.handle(msg)).pipe(
-          catchError3((err) => {
-            this.logger.error("Unexpected error in RPC router", err);
-            return EMPTY3;
-          })
-        ),
-        this.concurrency
-      )
-    ).subscribe();
+  async start() {
+    this.cachedNc = await this.connection.getConnection();
+    this.subscription = this.messageProvider.commands$.pipe(mergeMap2((msg) => from3(this.handleSafe(msg)), this.concurrency)).subscribe();
   }
   /** Stop routing and unsubscribe. */
   destroy() {
     this.subscription?.unsubscribe();
     this.subscription = null;
   }
-  /** Handle a single RPC command message. */
-  handle(msg) {
-    const handler = this.patternRegistry.getHandler(msg.subject);
-    if (!handler) {
-      msg.term(`No handler for RPC: ${msg.subject}`);
-      this.logger.error(`No handler for RPC subject: ${msg.subject}`);
-      return EMPTY3;
-    }
-    const replyTo = msg.headers?.get("x-reply-to" /* ReplyTo */);
-    const correlationId = msg.headers?.get("x-correlation-id" /* CorrelationId */);
-    if (!replyTo || !correlationId) {
-      msg.term("Missing required headers (reply-to or correlation-id)");
-      this.logger.error(`Missing headers for RPC: ${msg.subject}`);
-      return EMPTY3;
-    }
-    let data;
+  /** Handle a single RPC command message with error isolation. */
+  async handleSafe(msg) {
     try {
-      data = this.codec.decode(msg.data);
+      const handler = this.patternRegistry.getHandler(msg.subject);
+      if (!handler) {
+        msg.term(`No handler for RPC: ${msg.subject}`);
+        this.logger.error(`No handler for RPC subject: ${msg.subject}`);
+        return;
+      }
+      const { headers: msgHeaders } = msg;
+      const replyTo = msgHeaders?.get("x-reply-to" /* ReplyTo */);
+      const correlationId = msgHeaders?.get("x-correlation-id" /* CorrelationId */);
+      if (!replyTo || !correlationId) {
+        msg.term("Missing required headers (reply-to or correlation-id)");
+        this.logger.error(`Missing headers for RPC: ${msg.subject}`);
+        return;
+      }
+      let data;
+      try {
+        data = this.codec.decode(msg.data);
+      } catch (err) {
+        msg.term("Decode error");
+        this.logger.error(`Decode error for RPC ${msg.subject}:`, err);
+        return;
+      }
+      this.eventBus.emitMessageRouted(msg.subject, "rpc" /* Rpc */);
+      await this.executeHandler(handler, data, msg, replyTo, correlationId);
     } catch (err) {
-      msg.term("Decode error");
-      this.logger.error(`Decode error for RPC ${msg.subject}:`, err);
-      return EMPTY3;
+      this.logger.error("Unexpected error in RPC router", err);
     }
-    this.eventBus.emit("messageRouted" /* MessageRouted */, msg.subject, "rpc" /* Rpc */);
-    return from3(this.executeHandler(handler, data, msg, replyTo, correlationId));
   }
   /** Execute handler, publish response, settle message. */
   async executeHandler(handler, data, msg, replyTo, correlationId) {
-    const nc = await this.connection.getConnection();
+    const nc = this.cachedNc ?? await this.connection.getConnection();
     const ctx = new RpcContext([msg]);
-    const hdrs = headers();
-    hdrs.set("x-correlation-id" /* CorrelationId */, correlationId);
     let settled = false;
     const stopAckExtension = startAckExtensionTimer(msg, this.ackExtensionInterval);
     const timeoutId = setTimeout(() => {
@@ -2060,6 +2189,8 @@ var RpcRouter = class {
       stopAckExtension?.();
       msg.ack();
       try {
+        const hdrs = headers();
+        hdrs.set("x-correlation-id" /* CorrelationId */, correlationId);
         nc.publish(replyTo, this.codec.encode(result), { headers: hdrs });
       } catch (publishErr) {
         this.logger.error(`Failed to publish RPC response for ${msg.subject}`, publishErr);
@@ -2070,6 +2201,8 @@ var RpcRouter = class {
       clearTimeout(timeoutId);
       stopAckExtension?.();
       try {
+        const hdrs = headers();
+        hdrs.set("x-correlation-id" /* CorrelationId */, correlationId);
         hdrs.set("x-error" /* Error */, "true");
         nc.publish(replyTo, this.codec.encode(serializeError(err)), { headers: hdrs });
       } catch (encodeErr) {

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@horizon-republic/nestjs-jetstream",
-  "version": "2.6.1",
+  "version": "2.7.0",
   "description": "A NestJS transport for NATS with JetStream events, broadcast fan-out, and Core/JetStream RPC.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/HorizonRepublic/nestjs-jetstream.git"
   },
-  "homepage": "https://github.com/HorizonRepublic/nestjs-jetstream#readme",
+  "homepage": "https://horizonrepublic.github.io/nestjs-jetstream/",
   "bugs": {
     "url": "https://github.com/HorizonRepublic/nestjs-jetstream/issues"
   },
@@ -67,7 +67,7 @@
     "@nestjs/platform-express": "^11.1.17",
     "@nestjs/testing": "^11.1.17",
     "@types/node": "^25.5.0",
-    "@vitest/coverage-v8": "^4.1.1",
+    "@vitest/coverage-v8": "^4.1.2",
     "eslint": "^10.1.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prefer-arrow": "^1.2.3",
@@ -77,9 +77,9 @@
     "prettier": "^3.8.1",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
-    "typescript": "~5.9.0",
+    "typescript": "~5.9.3",
     "typescript-eslint": "^8.57.2",
-    "vitest": "^4.1.1"
+    "vitest": "^4.1.2"
   },
   "scripts": {
     "build": "tsup",