@horizon-republic/nestjs-jetstream 2.3.0 → 2.3.4

package/dist/index.cjs

@@ -203,7 +203,11 @@ var JetstreamRecordBuilder = class {
   constructor(data) {
     this.data = data;
   }
-  /** Set the message payload. */
+  /**
+   * Set the message payload.
+   *
+   * @param data - Payload to serialize via the configured {@link Codec}.
+   */
   setData(data) {
     this.data = data;
     return this;
@@ -211,6 +215,8 @@ var JetstreamRecordBuilder = class {
   /**
    * Set a single custom header.
    *
+   * @param key - Header name (e.g. `'x-tenant'`).
+   * @param value - Header value.
    * @throws Error if the header name is reserved by the transport.
    */
   setHeader(key, value) {
@@ -221,6 +227,7 @@ var JetstreamRecordBuilder = class {
   /**
    * Set multiple custom headers at once.
    *
+   * @param headers - Key-value pairs to set as headers.
    * @throws Error if any header name is reserved by the transport.
    */
   setHeaders(headers2) {
@@ -229,12 +236,20 @@ var JetstreamRecordBuilder = class {
     }
     return this;
   }
-  /** Set RPC request timeout in milliseconds. */
+  /**
+   * Set per-request RPC timeout.
+   *
+   * @param ms - Timeout in milliseconds. Overrides the global RPC timeout for this request only.
+   */
   setTimeout(ms) {
     this.timeout = ms;
     return this;
   }
-  /** Build the immutable JetstreamRecord. */
+  /**
+   * Build the immutable {@link JetstreamRecord}.
+   *
+   * @returns A frozen record ready to pass to `client.send()` or `client.emit()`.
+   */
   build() {
     return new JetstreamRecord(this.data, new Map(this.headers), this.timeout);
   }
@@ -270,7 +285,14 @@ var JetstreamClient = class extends import_microservices.ClientProxy {
   pendingTimeouts = /* @__PURE__ */ new Map();
   /** Subscription to connection status events for disconnect handling. */
   statusSubscription = null;
-  /** Establish connection. Called automatically by NestJS on first use. */
+  /**
+   * Establish connection. Called automatically by NestJS on first use.
+   *
+   * Sets up the JetStream RPC inbox (if in JetStream mode) and subscribes
+   * to connection status events for fail-fast disconnect handling.
+   *
+   * @returns The underlying NATS connection.
+   */
   async connect() {
     const nc = await this.connection.getConnection();
     if (this.isJetStreamRpcMode() && !this.inboxSubscription) {
@@ -283,15 +305,23 @@ var JetstreamClient = class extends import_microservices.ClientProxy {
     });
     return nc;
   }
-  /** Clean up resources. */
+  /** Clean up resources: reject pending RPCs, unsubscribe from status events. */
   async close() {
     this.statusSubscription?.unsubscribe();
     this.statusSubscription = null;
     this.rejectPendingRpcs(new Error("Client closed"));
   }
-  /** Direct access to the raw NATS connection. */
+  /**
+   * Direct access to the raw NATS connection.
+   *
+   * @throws Error if not connected.
+   */
   unwrap() {
-    return this.connection.unwrap;
+    const nc = this.connection.unwrap;
+    if (!nc) {
+      throw new Error("Not connected \u2014 call connect() before unwrap()");
+    }
+    return nc;
   }
   /**
    * Publish a fire-and-forget event to JetStream.
@@ -304,10 +334,13 @@ var JetstreamClient = class extends import_microservices.ClientProxy {
     const { data, hdrs } = this.extractRecordData(packet.data);
     const subject = this.buildEventSubject(packet.pattern);
     const msgHeaders = this.buildHeaders(hdrs, { subject });
-    await nc.jetstream().publish(subject, this.codec.encode(data), {
+    const ack = await nc.jetstream().publish(subject, this.codec.encode(data), {
       headers: msgHeaders,
       msgID: crypto.randomUUID()
     });
+    if (ack.duplicate) {
+      this.logger.warn(`Duplicate event publish detected: ${subject} (seq: ${ack.seq})`);
+    }
     return void 0;
   }
   /**
@@ -571,11 +604,16 @@ var ConnectionProvider = class {
     if (this.connectionPromise) {
       return this.connectionPromise;
     }
-    this.connectionPromise = this.establish();
+    this.connectionPromise = this.establish().catch((err) => {
+      this.connectionPromise = null;
+      throw err;
+    });
     return this.connectionPromise;
   }
   /**
-   * Get JetStream manager. Cached after first call.
+   * Get the JetStream manager. Cached after first call.
+   *
+   * @returns The JetStreamManager for stream/consumer administration.
    */
   async getJetStreamManager() {
     if (this.jsmInstance) return this.jsmInstance;
@@ -584,7 +622,7 @@ var ConnectionProvider = class {
     this.logger.log("JetStream manager initialized");
     return this.jsmInstance;
   }
-  /** Direct access to the raw NATS connection (assumes already connected). */
+  /** Direct access to the raw NATS connection, or `null` if not yet connected. */
   get unwrap() {
     return this.connection;
   }
@@ -624,8 +662,7 @@ var ConnectionProvider = class {
       this.monitorStatus(nc);
       return nc;
     } catch (err) {
-      const natsErr = err;
-      if (natsErr.code === "CONNECTION_REFUSED") {
+      if (err instanceof import_nats4.NatsError && err.code === "CONNECTION_REFUSED") {
         throw new Error(`NATS connection refused: ${this.options.servers.join(", ")}`);
       }
       throw err;
@@ -669,53 +706,21 @@ var EventBus = class {
     this.logger = logger;
     this.hooks = hooks ?? {};
   }
-  /** Emit a lifecycle event. Dispatches to custom hook or Logger fallback. */
+  /**
+   * Emit a lifecycle event. Dispatches to custom hook if registered, otherwise no-op.
+   *
+   * @param event - The {@link TransportEvent} to emit.
+   * @param args - Arguments matching the hook signature for this event.
+   */
   emit(event, ...args) {
     const hook = this.hooks[event];
-    if (hook) {
-      try {
-        hook(...args);
-      } catch (err) {
-        this.logger.error(
-          `Hook "${event}" threw an error: ${err instanceof Error ? err.message : err}`
-        );
-      }
-      return;
-    }
-    this.defaultHandler(event, args);
-  }
-  /** Default Logger-based handlers for each event type. */
-  defaultHandler(event, args) {
-    switch (event) {
-      case "connect" /* Connect */:
-        this.logger.log(`Connected to NATS: ${args[0]}`);
-        break;
-      case "disconnect" /* Disconnect */:
-        this.logger.warn("NATS connection lost");
-        break;
-      case "reconnect" /* Reconnect */:
-        this.logger.log(`Reconnected to NATS: ${args[0]}`);
-        break;
-      case "error" /* Error */:
-        this.logger.error(`Transport error: ${args[0]}`, args[1] ?? "");
-        break;
-      case "rpcTimeout" /* RpcTimeout */:
-        this.logger.warn(`RPC timeout: ${args[0]} (cid: ${args[1]})`);
-        break;
-      case "messageRouted" /* MessageRouted */:
-        this.logger.debug(`Message routed: ${args[0]} [${args[1]}]`);
-        break;
-      case "shutdownStart" /* ShutdownStart */:
-        this.logger.log("Graceful shutdown initiated");
-        break;
-      case "shutdownComplete" /* ShutdownComplete */:
-        this.logger.log("Graceful shutdown complete");
-        break;
-      case "deadLetter" /* DeadLetter */: {
-        const info = args[0];
-        this.logger.warn(`Dead letter: ${info?.subject ?? "unknown"}`);
-        break;
-      }
+    if (!hook) return;
+    try {
+      hook(...args);
+    } catch (err) {
+      this.logger.error(
+        `Hook "${event}" threw an error: ${err instanceof Error ? err.message : err}`
+      );
     }
   }
 };
@@ -732,6 +737,8 @@ var JetstreamHealthIndicator = class {
    *
    * Returns the current connection status without throwing.
    * Use this for custom health endpoints or monitoring integrations.
+   *
+   * @returns Connection status with server URL and RTT latency.
    */
   async check() {
     const nc = this.connection.unwrap;
@@ -754,7 +761,9 @@ var JetstreamHealthIndicator = class {
    * Returns `{ [key]: { status: 'up', ... } }` on success.
    * Throws an error with `{ [key]: { status: 'down', ... } }` on failure.
    *
-   * @param key Health indicator key (default: 'jetstream')
+   * @param key - Health indicator key (default: `'jetstream'`).
+   * @returns Object with status, server, and latency under the given key.
+   * @throws Error with `{ [key]: { status: 'down' } }` when disconnected.
    */
   async isHealthy(key = "jetstream") {
     const status = await this.check();
@@ -793,12 +802,18 @@ var JetstreamStrategy = class extends import_microservices2.Server {
   transportId = /* @__PURE__ */ Symbol("jetstream-transport");
   // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
   listeners = /* @__PURE__ */ new Map();
+  started = false;
   /**
    * Start the transport: register handlers, create infrastructure, begin consumption.
    *
    * Called by NestJS when `connectMicroservice()` is used, or internally by the module.
    */
   async listen(callback) {
+    if (this.started) {
+      this.logger.warn("listen() called more than once \u2014 ignoring");
+      return;
+    }
+    this.started = true;
     this.patternRegistry.registerHandlers(this.getHandlers());
     const streamKinds = this.resolveStreamKinds();
     if (streamKinds.length > 0) {
@@ -817,17 +832,18 @@ var JetstreamStrategy = class extends import_microservices2.Server {
     }
     callback();
   }
-  /** Gracefully stop the transport. */
+  /** Stop all consumers, routers, and subscriptions. Called during shutdown. */
   close() {
     this.eventRouter.destroy();
     this.rpcRouter.destroy();
     this.coreRpcServer.stop();
     this.messageProvider.destroy();
+    this.started = false;
   }
   /**
    * Register event listener (required by Server base class).
    *
-   * Stores callbacks for potential use. Primary lifecycle events
+   * Stores callbacks for client use. Primary lifecycle events
    * are routed through EventBus.
    */
   // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
@@ -836,9 +852,17 @@ var JetstreamStrategy = class extends import_microservices2.Server {
     existing.push(callback);
     this.listeners.set(event, existing);
   }
-  /** Unwrap the underlying NATS connection. */
+  /**
+   * Unwrap the underlying NATS connection.
+   *
+   * @throws Error if the transport has not started.
+   */
   unwrap() {
-    return this.connection.unwrap;
+    const nc = this.connection.unwrap;
+    if (!nc) {
+      throw new Error("Not connected \u2014 transport has not started");
+    }
+    return nc;
   }
   /** Access the pattern registry (for module-level introspection). */
   getPatternRegistry() {
@@ -873,23 +897,37 @@ var import_nats5 = require("nats");
 // src/context/rpc.context.ts
 var import_microservices3 = require("@nestjs/microservices");
 var RpcContext = class extends import_microservices3.BaseRpcContext {
-  /** Get the underlying NATS message (JsMsg for JetStream, Msg for Core). */
+  /**
+   * Get the underlying NATS message.
+   *
+   * @returns `JsMsg` for JetStream handlers, `Msg` for Core RPC handlers.
+   */
   getMessage() {
     return this.args[0];
   }
-  /** Get the NATS subject this message was published to. */
+  /** @returns The NATS subject this message was published to. */
   getSubject() {
     return this.args[0].subject;
   }
-  /** Get all NATS message headers, or undefined if none are present. */
+  /** @returns All NATS message headers, or `undefined` if none are present. */
   getHeaders() {
     return this.args[0].headers;
   }
-  /** Get a single header value by key. Returns undefined if the header or headers object is missing. */
+  /**
+   * Get a single header value by key.
+   *
+   * @param key - Header name (e.g. `'x-trace-id'`).
+   * @returns Header value, or `undefined` if the header is missing.
+   */
   getHeader(key) {
     return this.args[0].headers?.get(key);
   }
-  /** Type guard: narrows getMessage() return type to JsMsg when true. */
+  /**
+   * Type guard: returns `true` when the message is a JetStream message.
+   *
+   * Narrows `getMessage()` return type to `JsMsg`, giving access to
+   * `ack()`, `nak()`, `term()`, and delivery metadata.
+   */
   isJetStream() {
     return "ack" in this.args[0];
   }
@@ -1008,6 +1046,7 @@ var CoreRpcServer = class {
 
 // src/server/infrastructure/stream.provider.ts
 var import_common5 = require("@nestjs/common");
+var import_nats6 = require("nats");
 var STREAM_NOT_FOUND = 10059;
 var StreamProvider = class {
   constructor(options, connection) {
@@ -1050,8 +1089,7 @@ var StreamProvider = class {
       this.logger.debug(`Stream exists, updating: ${config.name}`);
       return await jsm.streams.update(config.name, config);
     } catch (err) {
-      const natsErr = err;
-      if (natsErr.api_error?.err_code === STREAM_NOT_FOUND) {
+      if (err instanceof import_nats6.NatsError && err.api_error?.err_code === STREAM_NOT_FOUND) {
         this.logger.log(`Creating stream: ${config.name}`);
         return await jsm.streams.add(config);
       }
@@ -1099,6 +1137,7 @@ var StreamProvider = class {
 
 // src/server/infrastructure/consumer.provider.ts
 var import_common6 = require("@nestjs/common");
+var import_nats7 = require("nats");
 var CONSUMER_NOT_FOUND = 10014;
 var ConsumerProvider = class {
   constructor(options, connection, streamProvider, patternRegistry) {
@@ -1139,8 +1178,7 @@ var ConsumerProvider = class {
       this.logger.debug(`Consumer exists: ${name}`);
       return info;
     } catch (err) {
-      const natsErr = err;
-      if (natsErr.api_error?.err_code === CONSUMER_NOT_FOUND) {
+      if (err instanceof import_nats7.NatsError && err.api_error?.err_code === CONSUMER_NOT_FOUND) {
         this.logger.log(`Creating consumer: ${name}`);
         return await jsm.consumers.add(stream, config);
       }
@@ -1216,6 +1254,7 @@ var MessageProvider = class {
   }
   logger = new import_common7.Logger("Jetstream:Message");
   destroy$ = new import_rxjs3.Subject();
+  activeIterators = /* @__PURE__ */ new Set();
   eventMessages$ = new import_rxjs3.Subject();
   commandMessages$ = new import_rxjs3.Subject();
   broadcastMessages$ = new import_rxjs3.Subject();
@@ -1250,6 +1289,10 @@ var MessageProvider = class {
   destroy() {
     this.destroy$.next();
     this.destroy$.complete();
+    for (const messages of this.activeIterators) {
+      messages.stop();
+    }
+    this.activeIterators.clear();
     this.eventMessages$.complete();
     this.commandMessages$.complete();
     this.broadcastMessages$.complete();
@@ -1257,8 +1300,13 @@ var MessageProvider = class {
   /** Create a self-healing consumer flow for a specific kind. */
   createFlow(kind, info) {
     const target$ = this.getTargetSubject(kind);
+    let consecutiveFailures = 0;
     return (0, import_rxjs3.defer)(() => this.consumeOnce(info, target$)).pipe(
+      (0, import_rxjs3.tap)(() => {
+        consecutiveFailures = 0;
+      }),
       (0, import_rxjs3.catchError)((err) => {
+        consecutiveFailures++;
         this.logger.error(`Consumer ${info.name} error, will restart:`, err);
         this.eventBus.emit(
           "error" /* Error */,
@@ -1269,13 +1317,14 @@ var MessageProvider = class {
       }),
       (0, import_rxjs3.repeat)({
         delay: () => {
-          this.logger.warn(`Consumer ${info.name} stream ended, restarting...`);
+          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)(100);
+          return (0, import_rxjs3.timer)(delay);
         }
       }),
       (0, import_rxjs3.takeUntil)(this.destroy$)
@@ -1286,8 +1335,13 @@ var MessageProvider = class {
     const js = (await this.connection.getConnection()).jetstream();
     const consumer = await js.consumers.get(info.stream_name, info.name);
     const messages = await consumer.consume();
-    for await (const msg of messages) {
-      target$.next(msg);
+    this.activeIterators.add(messages);
+    try {
+      for await (const msg of messages) {
+        target$.next(msg);
+      }
+    } finally {
+      this.activeIterators.delete(messages);
     }
   }
   /** Get the target subject for a consumer kind. */
@@ -1427,11 +1481,14 @@ var EventRouter = class {
   /** Subscribe to a message stream and route each message. */
   subscribeToStream(stream$, label) {
     const subscription = stream$.pipe(
-      (0, import_rxjs4.mergeMap)((msg) => this.handle(msg)),
-      (0, import_rxjs4.catchError)((err, caught) => {
-        this.logger.error(`Unexpected error in ${label} event router`, err);
-        return caught;
-      })
+      (0, import_rxjs4.mergeMap)(
+        (msg) => (0, import_rxjs4.defer)(() => this.handle(msg)).pipe(
+          (0, import_rxjs4.catchError)((err) => {
+            this.logger.error(`Unexpected error in ${label} event router`, err);
+            return import_rxjs4.EMPTY;
+          })
+        )
+      )
     ).subscribe();
     this.subscriptions.push(subscription);
   }
@@ -1505,7 +1562,7 @@ var EventRouter = class {
 
 // src/server/routing/rpc.router.ts
 var import_common10 = require("@nestjs/common");
-var import_nats6 = require("nats");
+var import_nats8 = require("nats");
 var import_rxjs5 = require("rxjs");
 var RpcRouter = class {
   constructor(messageProvider, patternRegistry, connection, codec, eventBus, timeout) {
@@ -1522,11 +1579,14 @@ var RpcRouter = class {
   /** Start routing command messages to handlers. */
   start() {
     this.subscription = this.messageProvider.commands$.pipe(
-      (0, import_rxjs5.mergeMap)((msg) => this.handle(msg)),
-      (0, import_rxjs5.catchError)((err, caught) => {
-        this.logger.error("Unexpected error in RPC router", err);
-        return caught;
-      })
+      (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;
+          })
+        )
+      )
     ).subscribe();
   }
   /** Stop routing and unsubscribe. */
@@ -1564,7 +1624,7 @@ var RpcRouter = class {
   async executeHandler(handler, data, msg, replyTo, correlationId) {
     const nc = await this.connection.getConnection();
     const ctx = new RpcContext([msg]);
-    const hdrs = (0, import_nats6.headers)();
+    const hdrs = (0, import_nats8.headers)();
     hdrs.set("x-correlation-id" /* CorrelationId */, correlationId);
     let settled = false;
     const timeoutId = setTimeout(() => {
@@ -1579,8 +1639,12 @@ var RpcRouter = class {
       if (settled) return;
       settled = true;
       clearTimeout(timeoutId);
-      nc.publish(replyTo, this.codec.encode(result), { headers: hdrs });
       msg.ack();
+      try {
+        nc.publish(replyTo, this.codec.encode(result), { headers: hdrs });
+      } catch (publishErr) {
+        this.logger.error(`Failed to publish RPC response for ${msg.subject}`, publishErr);
+      }
     } catch (err) {
       if (settled) return;
       settled = true;
@@ -1614,10 +1678,17 @@ var ShutdownManager = class {
     this.eventBus.emit("shutdownStart" /* ShutdownStart */);
     this.logger.log(`Graceful shutdown started (timeout: ${this.timeout}ms)`);
     strategy?.close();
-    await Promise.race([
-      this.connection.shutdown(),
-      new Promise((resolve) => setTimeout(resolve, this.timeout))
-    ]);
+    let timeoutId;
+    try {
+      await Promise.race([
+        this.connection.shutdown(),
+        new Promise((resolve) => {
+          timeoutId = setTimeout(resolve, this.timeout);
+        })
+      ]);
+    } finally {
+      clearTimeout(timeoutId);
+    }
     this.eventBus.emit("shutdownComplete" /* ShutdownComplete */);
     this.logger.log("Graceful shutdown complete");
   }