@horizon-republic/nestjs-jetstream 2.3.4 → 2.3.6

package/README.md

@@ -5,7 +5,7 @@ A production-grade NestJS transport for NATS JetStream with built-in support for
 [![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)
 [![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://badge.socket.dev/npm/package/@horizon-republic/nestjs-jetstream)
+[![Socket Badge](https://badge.socket.dev/npm/package/@horizon-republic/nestjs-jetstream)](https://socket.dev/npm/package/@horizon-republic/nestjs-jetstream)
 
 ## Table of Contents
 
@@ -63,9 +63,9 @@ yarn add @horizon-republic/nestjs-jetstream
 **Peer dependencies:**
 
 ```
-@nestjs/common        ^11.0.0
-@nestjs/core          ^11.0.0
-@nestjs/microservices ^11.0.0
+@nestjs/common        ^10.2.0 || ^11.0.0
+@nestjs/core          ^10.2.0 || ^11.0.0
+@nestjs/microservices ^10.2.0 || ^11.0.0
 nats                  ^2.0.0
 reflect-metadata      ^0.2.0
 rxjs                  ^7.8.0
@@ -305,6 +305,8 @@ Discriminated union on `mode`:
 | `'core'`      | 30s             | None             | Low-latency, simple RPC                |
 | `'jetstream'` | 3 min           | JetStream stream | Commands must survive handler downtime |
 
+> **Note:** `timeout` controls both the **client-side wait** (how long the caller waits for a response) and the **server-side handler limit** (how long the handler is allowed to run before being terminated). Both sides use the same value from their own `forRoot()` config.
+
 ```typescript
 // Core mode (default)
 rpc: { mode: 'core', timeout: 10_000 }
@@ -348,7 +350,8 @@ JetstreamModule.forRoot({
 |----------|--------|
 | Handler success | Response returned to caller |
 | Handler throws | Error response returned to caller |
-| No handler running | Client times out |
+| No handler registered | Error response returned to caller |
+| Server not running | Client times out |
 | Decode error | Error response returned to caller |
 
 #### JetStream Mode
@@ -671,7 +674,9 @@ JetstreamModule.forRootAsync({
 
 ### Health Checks
 
-`JetstreamHealthIndicator` is automatically registered and exported by `forRoot()`. It checks NATS connection status and measures round-trip latency. `@nestjs/terminus` is **not required** — the indicator follows the Terminus API convention so it works seamlessly when Terminus is present, but can also be used standalone.
+`JetstreamHealthIndicator` is automatically registered and exported by `forRoot()`. It checks NATS connection status and measures round-trip latency. `@nestjs/terminus` is **not required** — the indicator follows the Terminus API convention and can be used standalone.
+
+> **Note:** `isHealthy()` throws a plain `Error` with attached status details rather than Terminus's `HealthCheckError`. Terminus will report the service as unhealthy, but the structured `{ status: 'down', server, latency }` details may not appear in the response body. For full Terminus formatting, use the `check()` method in a custom wrapper.
 
 **With [@nestjs/terminus](https://docs.nestjs.com/recipes/terminus) (zero boilerplate):**
 
@@ -788,7 +793,7 @@ If the initial NATS connection is refused, the module throws an `Error` immediat
 
 #### Observable return values
 
-Handlers can return Observables. The transport takes the **first emitted value** for RPC responses and awaits completion for events:
+Handlers can return Observables. The transport resolves on the **first emitted value** (or on completion if the Observable emits nothing):
 
 ```typescript
 @MessagePattern('user.get')
@@ -798,7 +803,7 @@ getUser(@Payload() data: { id: number }): Observable<UserDto> {
 
 @EventPattern('order.created')
 handleOrder(@Payload() data: OrderDto): Observable<void> {
-  return this.pipeline.process(data); // awaits completion before ack
+  return this.pipeline.process(data); // ack after first emission or completion
 }
 ```
 

package/dist/index.cjs

@@ -592,6 +592,7 @@ var ConnectionProvider = class {
   connection = null;
   connectionPromise = null;
   jsmInstance = null;
+  jsmPromise = null;
   /**
    * Establish NATS connection. Idempotent — returns cached connection on subsequent calls.
    *
@@ -617,10 +618,16 @@ var ConnectionProvider = class {
    */
   async getJetStreamManager() {
     if (this.jsmInstance) return this.jsmInstance;
-    const nc = await this.getConnection();
-    this.jsmInstance = await nc.jetstreamManager();
-    this.logger.log("JetStream manager initialized");
-    return this.jsmInstance;
+    if (this.jsmPromise) return this.jsmPromise;
+    this.jsmPromise = (async () => {
+      const nc = await this.getConnection();
+      this.jsmInstance = await nc.jetstreamManager();
+      this.logger.log("JetStream manager initialized");
+      return this.jsmInstance;
+    })().finally(() => {
+      this.jsmPromise = null;
+    });
+    return this.jsmPromise;
   }
   /** Direct access to the raw NATS connection, or `null` if not yet connected. */
   get unwrap() {
@@ -632,6 +639,12 @@ var ConnectionProvider = class {
    * Sequence: drain → wait for close. Falls back to force-close on error.
    */
   async shutdown() {
+    if (this.connectionPromise) {
+      try {
+        await this.connectionPromise;
+      } catch {
+      }
+    }
     if (!this.connection || this.connection.isClosed()) return;
     try {
       await this.connection.drain();
@@ -645,6 +658,7 @@ var ConnectionProvider = class {
       this.connection = null;
       this.connectionPromise = null;
       this.jsmInstance = null;
+      this.jsmPromise = null;
     }
   }
   /** Internal: establish the physical connection with reconnect monitoring. */
@@ -678,6 +692,7 @@ var ConnectionProvider = class {
             break;
           case import_nats4.Events.Reconnect:
             this.jsmInstance = null;
+            this.jsmPromise = null;
             this.eventBus.emit("reconnect" /* Reconnect */, nc.getServer());
             break;
           case import_nats4.Events.Error:
@@ -716,7 +731,14 @@ var EventBus = class {
     const hook = this.hooks[event];
     if (!hook) return;
     try {
-      hook(...args);
+      const result = hook(...args);
+      if (result && typeof result.catch === "function") {
+        result.catch((err) => {
+          this.logger.error(
+            `Async hook "${event}" rejected: ${err instanceof Error ? err.message : err}`
+          );
+        });
+      }
     } catch (err) {
       this.logger.error(
         `Hook "${event}" threw an error: ${err instanceof Error ? err.message : err}`
@@ -819,6 +841,7 @@ var JetstreamStrategy = class extends import_microservices2.Server {
     if (streamKinds.length > 0) {
       await this.streamProvider.ensureStreams(streamKinds);
       const consumers = await this.consumerProvider.ensureConsumers(streamKinds);
+      this.eventRouter.updateMaxDeliverMap(this.buildMaxDeliverMap(consumers));
       this.messageProvider.start(consumers);
       if (this.patternRegistry.hasEventHandlers() || this.patternRegistry.hasBroadcastHandlers()) {
         this.eventRouter.start();
@@ -882,6 +905,18 @@ var JetstreamStrategy = class extends import_microservices2.Server {
     }
     return kinds;
   }
+  /** Build max_deliver map from actual NATS consumer configs (not options). */
+  buildMaxDeliverMap(consumers) {
+    const map = /* @__PURE__ */ new Map();
+    for (const [, info] of consumers) {
+      const stream = info.stream_name;
+      const maxDeliver = info.config.max_deliver;
+      if (stream && maxDeliver !== void 0 && maxDeliver > 0) {
+        map.set(stream, maxDeliver);
+      }
+    }
+    return map;
+  }
   isCoreRpcMode() {
     return !this.options.rpc || this.options.rpc.mode === "core";
   }
@@ -955,11 +990,13 @@ var unwrapResult = async (result) => {
 };
 var subscribeToFirst = (obs) => new Promise((resolve, reject) => {
   let done = false;
-  obs.subscribe({
+  let subscription = null;
+  subscription = obs.subscribe({
     next: (val) => {
       if (!done) {
         done = true;
         resolve(val);
+        subscription?.unsubscribe();
       }
     },
     error: reject,
@@ -967,6 +1004,9 @@ var subscribeToFirst = (obs) => new Promise((resolve, reject) => {
       if (!done) resolve(void 0);
     }
   });
+  if (done) {
+    subscription.unsubscribe();
+  }
 });
 
 // src/server/core-rpc.server.ts
@@ -1012,6 +1052,7 @@ var CoreRpcServer = class {
     const handler = this.patternRegistry.getHandler(msg.subject);
     if (!handler) {
       this.logger.warn(`No handler for Core RPC: ${msg.subject}`);
+      this.respondWithError(msg, new Error(`No handler for subject: ${msg.subject}`));
       return;
     }
     this.eventBus.emit("messageRouted" /* MessageRouted */, msg.subject, "rpc");
@@ -1174,9 +1215,9 @@ var ConsumerProvider = class {
     const name = config.durable_name;
     this.logger.log(`Ensuring consumer: ${name} on stream: ${stream}`);
     try {
-      const info = await jsm.consumers.info(stream, name);
-      this.logger.debug(`Consumer exists: ${name}`);
-      return info;
+      await jsm.consumers.info(stream, name);
+      this.logger.debug(`Consumer exists, updating: ${name}`);
+      return await jsm.consumers.update(stream, name, config);
     } catch (err) {
       if (err instanceof import_nats7.NatsError && err.api_error?.err_code === CONSUMER_NOT_FOUND) {
         this.logger.log(`Creating consumer: ${name}`);
@@ -1194,6 +1235,9 @@ var ConsumerProvider = class {
     const overrides = this.getOverrides(kind);
     if (kind === "broadcast") {
       const broadcastPatterns = this.patternRegistry.getBroadcastPatterns();
+      if (broadcastPatterns.length === 0) {
+        throw new Error("Broadcast consumer requested but no broadcast patterns are registered");
+      }
       if (broadcastPatterns.length === 1) {
         return {
           ...defaults,
@@ -1253,8 +1297,8 @@ var MessageProvider = class {
     this.eventBus = eventBus;
   }
   logger = new import_common7.Logger("Jetstream:Message");
-  destroy$ = new import_rxjs3.Subject();
   activeIterators = /* @__PURE__ */ new Set();
+  destroy$ = new import_rxjs3.Subject();
   eventMessages$ = new import_rxjs3.Subject();
   commandMessages$ = new import_rxjs3.Subject();
   broadcastMessages$ = new import_rxjs3.Subject();
@@ -1285,7 +1329,7 @@ var MessageProvider = class {
       (0, import_rxjs3.merge)(...flows).pipe((0, import_rxjs3.takeUntil)(this.destroy$)).subscribe();
     }
   }
-  /** Stop all consumer flows and complete all subjects. */
+  /** Stop all consumer flows and reinitialize subjects for potential restart. */
   destroy() {
     this.destroy$.next();
     this.destroy$.complete();
@@ -1296,17 +1340,23 @@ var MessageProvider = class {
     this.eventMessages$.complete();
     this.commandMessages$.complete();
     this.broadcastMessages$.complete();
+    this.destroy$ = new import_rxjs3.Subject();
+    this.eventMessages$ = new import_rxjs3.Subject();
+    this.commandMessages$ = new import_rxjs3.Subject();
+    this.broadcastMessages$ = new import_rxjs3.Subject();
   }
   /** Create a self-healing consumer flow for a specific kind. */
   createFlow(kind, info) {
     const target$ = this.getTargetSubject(kind);
     let consecutiveFailures = 0;
+    let lastRunFailed = false;
     return (0, import_rxjs3.defer)(() => this.consumeOnce(info, target$)).pipe(
       (0, import_rxjs3.tap)(() => {
-        consecutiveFailures = 0;
+        lastRunFailed = false;
       }),
       (0, import_rxjs3.catchError)((err) => {
         consecutiveFailures++;
+        lastRunFailed = true;
         this.logger.error(`Consumer ${info.name} error, will restart:`, err);
         this.eventBus.emit(
           "error" /* Error */,
@@ -1317,13 +1367,11 @@ var MessageProvider = class {
       }),
       (0, import_rxjs3.repeat)({
         delay: () => {
+          if (!lastRunFailed) {
+            consecutiveFailures = 0;
+          }
           const delay = Math.min(100 * Math.pow(2, consecutiveFailures), 3e4);
           this.logger.warn(`Consumer ${info.name} stream ended, restarting in ${delay}ms...`);
-          this.eventBus.emit(
-            "error" /* Error */,
-            new Error(`Consumer ${info.name} stream ended`),
-            "message-provider"
-          );
           return (0, import_rxjs3.timer)(delay);
         }
       }),
@@ -1466,6 +1514,14 @@ var EventRouter = class {
   }
   logger = new import_common9.Logger("Jetstream:EventRouter");
   subscriptions = [];
+  /**
+   * Update the max_deliver thresholds from actual NATS consumer configs.
+   * Called after consumers are ensured so the DLQ map reflects reality.
+   */
+  updateMaxDeliverMap(consumerMaxDelivers) {
+    if (!this.deadLetterConfig) return;
+    this.deadLetterConfig.maxDeliverByStream = consumerMaxDelivers;
+  }
   /** Start routing event and broadcast messages to handlers. */
   start() {
     this.subscribeToStream(this.messageProvider.events$, "workqueue");
@@ -1515,10 +1571,7 @@ var EventRouter = class {
   /** Execute handler, then ack on success or nak/dead-letter on failure. */
   async executeHandler(handler, data, ctx, msg) {
     try {
-      const result = await handler(data, ctx);
-      if ((0, import_rxjs4.isObservable)(result)) {
-        await (0, import_rxjs4.lastValueFrom)(result, { defaultValue: void 0 });
-      }
+      await unwrapResult(handler(data, ctx));
       msg.ack();
     } catch (err) {
       this.logger.error(`Event handler error (${msg.subject}):`, err);
@@ -1533,7 +1586,7 @@ var EventRouter = class {
   isDeadLetter(msg) {
     if (!this.deadLetterConfig) return false;
     const maxDeliver = this.deadLetterConfig.maxDeliverByStream.get(msg.info.stream);
-    if (maxDeliver === void 0) return false;
+    if (maxDeliver === void 0 || maxDeliver <= 0) return false;
     return msg.info.deliveryCount >= maxDeliver;
   }
   /** Handle a dead letter: invoke callback, then term or nak based on result. */
@@ -1791,26 +1844,6 @@ var JetstreamModule = class {
   // -------------------------------------------------------------------
   // Provider factories
   // -------------------------------------------------------------------
-  /** Create all providers for synchronous forRoot(). */
-  /**
-   * Build a map of stream name -> max_deliver for dead letter detection.
-   * Each stream kind (ev, broadcast) has its own consumer config with potentially
-   * different max_deliver values.
-   */
-  static buildMaxDeliverMap(options) {
-    const map = /* @__PURE__ */ new Map();
-    const defaultEventMax = DEFAULT_EVENT_CONSUMER_CONFIG.max_deliver ?? 3;
-    const defaultBroadcastMax = DEFAULT_BROADCAST_CONSUMER_CONFIG.max_deliver ?? 3;
-    map.set(
-      streamName(options.name, "ev"),
-      options.events?.consumer?.max_deliver ?? defaultEventMax
-    );
-    map.set(
-      streamName(options.name, "broadcast"),
-      options.broadcast?.consumer?.max_deliver ?? defaultBroadcastMax
-    );
-    return map;
-  }
   static createCoreProviders(options) {
     return [
       {
@@ -1921,7 +1954,7 @@ var JetstreamModule = class {
         useFactory: (options, messageProvider, patternRegistry, codec, eventBus) => {
           if (options.consumer === false) return null;
           const deadLetterConfig = options.onDeadLetter ? {
-            maxDeliverByStream: JetstreamModule.buildMaxDeliverMap(options),
+            maxDeliverByStream: /* @__PURE__ */ new Map(),
             onDeadLetter: options.onDeadLetter
           } : void 0;
           return new EventRouter(