@horizon-republic/nestjs-jetstream 2.3.2 → 2.3.4

package/README.md

@@ -252,7 +252,7 @@ interface JetstreamModuleOptions {
   /** Broadcast event stream/consumer overrides. */
   broadcast?: { stream?: Partial<StreamConfig>; consumer?: Partial<ConsumerConfig> };
 
-  /** Transport lifecycle hook handlers. Unset hooks fall back to NestJS Logger. */
+  /** Transport lifecycle hook handlers. Unset hooks are silently ignored. */
   hooks?: Partial<TransportHooks>;
 
   /** Async callback for dead letter handling. See Dead Letter Queue section below. */
@@ -584,7 +584,7 @@ JetstreamModule.forFeature({
 
 ### Lifecycle Hooks
 
-Subscribe to transport events for monitoring, alerting, or custom logic:
+Subscribe to transport events for monitoring, alerting, or custom logic. Events without a registered hook are silently ignored — no default logging:
 
 ```typescript
 import { JetstreamModule, TransportEvent } from '@horizon-republic/nestjs-jetstream';
@@ -611,17 +611,17 @@ JetstreamModule.forRoot({
 
 **Available events:**
 
-| Event              | Arguments                                   | Default (no hook) |
-|--------------------|---------------------------------------------|-------------------|
-| `connect`          | `(server: string)`                          | `Logger.log`      |
-| `disconnect`       | `()`                                        | `Logger.warn`     |
-| `reconnect`        | `(server: string)`                          | `Logger.log`      |
-| `error`            | `(error: Error, context?: string)`          | `Logger.error`    |
-| `rpcTimeout`       | `(subject: string, correlationId: string)`  | `Logger.warn`     |
-| `messageRouted`    | `(subject: string, kind: 'rpc' \| 'event')` | `Logger.debug`    |
-| `shutdownStart`    | `()`                                        | `Logger.log`      |
-| `shutdownComplete` | `()`                                        | `Logger.log`      |
-| `deadLetter`       | `(info: DeadLetterInfo)`                    | `Logger.warn`     |
+| Event              | Arguments                                   |
+|--------------------|---------------------------------------------|
+| `connect`          | `(server: string)`                          |
+| `disconnect`       | `()`                                        |
+| `reconnect`        | `(server: string)`                          |
+| `error`            | `(error: Error, context?: string)`          |
+| `rpcTimeout`       | `(subject: string, correlationId: string)`  |
+| `messageRouted`    | `(subject: string, kind: 'rpc' \| 'event')` |
+| `shutdownStart`    | `()`                                        |
+| `shutdownComplete` | `()`                                        |
+| `deadLetter`       | `(info: DeadLetterInfo)`                    |
 
 #### Dead Letter Queue (DLQ)
 

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,13 +305,17 @@ 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() {
     const nc = this.connection.unwrap;
     if (!nc) {
@@ -585,7 +611,9 @@ var ConnectionProvider = class {
     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;
@@ -594,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;
   }
@@ -678,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}`
+      );
     }
   }
 };
@@ -741,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;
@@ -763,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();
@@ -832,7 +832,7 @@ 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();
@@ -852,7 +852,11 @@ 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() {
     const nc = this.connection.unwrap;
     if (!nc) {
@@ -893,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];
   }