@horizon-republic/nestjs-jetstream 2.6.1 → 2.7.1

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

@@ -47,9 +47,13 @@ __export(index_exports, {
   RpcContext: () => RpcContext,
   StreamKind: () => StreamKind,
   TransportEvent: () => TransportEvent,
+  buildSubject: () => buildSubject,
+  consumerName: () => consumerName,
   getClientToken: () => getClientToken,
+  internalName: () => internalName,
   isCoreRpcMode: () => isCoreRpcMode,
   isJetStreamRpcMode: () => isJetStreamRpcMode,
+  streamName: () => streamName,
   toNanos: () => toNanos
 });
 module.exports = __toCommonJS(index_exports);
@@ -830,6 +834,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 +980,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 +1074,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 +1115,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 +1243,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 +1334,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 +1819,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 +1856,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 +1871,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 +1984,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 +2000,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 +2047,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 +2055,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 +2128,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 +2139,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 +2201,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 +2213,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) {
@@ -2519,8 +2663,12 @@ JetstreamModule = __decorateClass([
   RpcContext,
   StreamKind,
   TransportEvent,
+  buildSubject,
+  consumerName,
   getClientToken,
+  internalName,
   isCoreRpcMode,
   isJetStreamRpcMode,
+  streamName,
   toNanos
 });