@horizon-republic/nestjs-jetstream 2.6.1 → 2.7.1

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) {
@@ -2517,8 +2650,12 @@ export {
   RpcContext,
   StreamKind,
   TransportEvent,
+  buildSubject,
+  consumerName,
   getClientToken,
+  internalName,
   isCoreRpcMode,
   isJetStreamRpcMode,
+  streamName,
   toNanos
 };

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@horizon-republic/nestjs-jetstream",
-  "version": "2.6.1",
+  "version": "2.7.1",
   "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",