@horizon-republic/nestjs-jetstream 2.7.1 → 2.8.0

package/dist/index.js

@@ -24,9 +24,9 @@ import { Logger } from "@nestjs/common";
 import { ClientProxy } from "@nestjs/microservices";
 import {
   createInbox,
-  Events,
   headers as natsHeaders
-} from "nats";
+} from "@nats-io/transport-node";
+import { nuid } from "@nats-io/nuid";
 
 // src/interfaces/hooks.interface.ts
 var MessageKind = /* @__PURE__ */ ((MessageKind2) => {
@@ -65,7 +65,7 @@ import {
   RetentionPolicy,
   StorageType,
   StoreCompression
-} from "nats";
+} from "@nats-io/jetstream";
 var JETSTREAM_OPTIONS = /* @__PURE__ */ Symbol("JETSTREAM_OPTIONS");
 var JETSTREAM_CONNECTION = /* @__PURE__ */ Symbol("JETSTREAM_CONNECTION");
 var JETSTREAM_CODEC = /* @__PURE__ */ Symbol("JETSTREAM_CODEC");
@@ -197,11 +197,12 @@ var isCoreRpcMode = (rpc) => !rpc || rpc.mode === "core";
 
 // src/client/jetstream.record.ts
 var JetstreamRecord = class {
-  constructor(data, headers2, timeout, messageId) {
+  constructor(data, headers2, timeout, messageId, schedule) {
     this.data = data;
     this.headers = headers2;
     this.timeout = timeout;
     this.messageId = messageId;
+    this.schedule = schedule;
   }
 };
 var JetstreamRecordBuilder = class {
@@ -209,6 +210,7 @@ var JetstreamRecordBuilder = class {
   headers = /* @__PURE__ */ new Map();
   timeout;
   messageId;
+  scheduleOptions;
   constructor(data) {
     this.data = data;
   }
@@ -276,17 +278,43 @@ var JetstreamRecordBuilder = class {
     this.timeout = ms;
     return this;
   }
+  /**
+   * Schedule one-shot delayed delivery.
+   *
+   * The message is held by NATS and delivered to the event consumer
+   * at the specified time. Requires NATS >= 2.12 and `allow_msg_schedules: true`
+   * on the event stream (via `events: { stream: { allow_msg_schedules: true } }`).
+   *
+   * Only meaningful for events (`client.emit()`). If used with RPC
+   * (`client.send()`), a warning is logged and the schedule is ignored.
+   *
+   * @param date - Delivery time. Must be in the future.
+   * @throws Error if the date is not in the future.
+   */
+  scheduleAt(date) {
+    const ts = date.getTime();
+    if (Number.isNaN(ts)) {
+      throw new Error("Schedule date is invalid");
+    }
+    if (ts <= Date.now()) {
+      throw new Error("Schedule date must be in the future");
+    }
+    this.scheduleOptions = { at: new Date(ts) };
+    return this;
+  }
   /**
    * Build the immutable {@link JetstreamRecord}.
    *
    * @returns A frozen record ready to pass to `client.send()` or `client.emit()`.
    */
   build() {
+    const schedule = this.scheduleOptions ? { at: new Date(this.scheduleOptions.at.getTime()) } : void 0;
     return new JetstreamRecord(
       this.data,
       new Map(this.headers),
       this.timeout,
-      this.messageId
+      this.messageId,
+      schedule
     );
   }
   /** Validate that a header key is not reserved. */
@@ -338,7 +366,7 @@ var JetstreamClient = class extends ClientProxy {
       this.setupInbox(nc);
     }
     this.statusSubscription ??= this.connection.status$.subscribe((status) => {
-      if (status.type === Events.Disconnect) {
+      if (status.type === "disconnect") {
         this.handleDisconnect();
       }
     });
@@ -366,19 +394,38 @@ var JetstreamClient = class extends ClientProxy {
    * Publish a fire-and-forget event to JetStream.
    *
    * Events are published to either the workqueue stream or broadcast stream
-   * depending on the subject prefix.
+   * depending on the subject prefix. When a schedule is present the message
+   * is published to a `_sch` subject within the same stream, with the target
+   * set to the original event subject.
    */
   async dispatchEvent(packet) {
     await this.connect();
-    const { data, hdrs, messageId } = this.extractRecordData(packet.data);
-    const subject = this.buildEventSubject(packet.pattern);
-    const msgHeaders = this.buildHeaders(hdrs, { subject });
-    const ack = await this.connection.getJetStreamClient().publish(subject, this.codec.encode(data), {
-      headers: msgHeaders,
-      msgID: messageId ?? crypto.randomUUID()
-    });
-    if (ack.duplicate) {
-      this.logger.warn(`Duplicate event publish detected: ${subject} (seq: ${ack.seq})`);
+    const { data, hdrs, messageId, schedule } = this.extractRecordData(packet.data);
+    const eventSubject = this.buildEventSubject(packet.pattern);
+    const msgHeaders = this.buildHeaders(hdrs, { subject: eventSubject });
+    if (schedule) {
+      const scheduleSubject = this.buildScheduleSubject(eventSubject);
+      const ack = await this.connection.getJetStreamClient().publish(scheduleSubject, this.codec.encode(data), {
+        headers: msgHeaders,
+        msgID: messageId ?? nuid.next(),
+        schedule: {
+          specification: schedule.at,
+          target: eventSubject
+        }
+      });
+      if (ack.duplicate) {
+        this.logger.warn(
+          `Duplicate scheduled publish detected: ${scheduleSubject} (seq: ${ack.seq})`
+        );
+      }
+    } else {
+      const ack = await this.connection.getJetStreamClient().publish(eventSubject, this.codec.encode(data), {
+        headers: msgHeaders,
+        msgID: messageId ?? nuid.next()
+      });
+      if (ack.duplicate) {
+        this.logger.warn(`Duplicate event publish detected: ${eventSubject} (seq: ${ack.seq})`);
+      }
     }
     return void 0;
   }
@@ -390,7 +437,12 @@ var JetstreamClient = class extends ClientProxy {
    */
   publish(packet, callback) {
     const subject = buildSubject(this.targetName, "cmd" /* Command */, packet.pattern);
-    const { data, hdrs, timeout, messageId } = this.extractRecordData(packet.data);
+    const { data, hdrs, timeout, messageId, schedule } = this.extractRecordData(packet.data);
+    if (schedule) {
+      this.logger.warn(
+        "scheduleAt() is ignored for RPC (client.send()). Use client.emit() for scheduled events."
+      );
+    }
     const onUnhandled = (err) => {
       this.logger.error("Unhandled publish error:", err);
       callback({ err: new Error("Internal transport error"), response: null, isDisposed: true });
@@ -399,7 +451,7 @@ var JetstreamClient = class extends ClientProxy {
     if (isCoreRpcMode(this.rootOptions.rpc)) {
       this.publishCoreRpc(subject, data, hdrs, timeout, callback).catch(onUnhandled);
     } else {
-      jetStreamCorrelationId = crypto.randomUUID();
+      jetStreamCorrelationId = nuid.next();
       this.publishJetStreamRpc(subject, data, callback, {
         headers: hdrs,
         timeout,
@@ -474,7 +526,7 @@ var JetstreamClient = class extends ClientProxy {
       });
       await this.connection.getJetStreamClient().publish(subject, this.codec.encode(data), {
         headers: hdrs,
-        msgID: messageId ?? crypto.randomUUID()
+        msgID: messageId ?? nuid.next()
       });
     } catch (err) {
       const existingTimeout = this.pendingTimeouts.get(correlationId);
@@ -587,17 +639,51 @@ var JetstreamClient = class extends ClientProxy {
     }
     return hdrs;
   }
-  /** Extract data, headers, and timeout from raw packet data or JetstreamRecord. */
+  /** Extract data, headers, timeout, and schedule from raw packet data or JetstreamRecord. */
   extractRecordData(rawData) {
     if (rawData instanceof JetstreamRecord) {
       return {
         data: rawData.data,
         hdrs: rawData.headers.size > 0 ? new Map(rawData.headers) : null,
         timeout: rawData.timeout,
-        messageId: rawData.messageId
+        messageId: rawData.messageId,
+        schedule: rawData.schedule
       };
     }
-    return { data: rawData, hdrs: null, timeout: void 0, messageId: void 0 };
+    return {
+      data: rawData,
+      hdrs: null,
+      timeout: void 0,
+      messageId: void 0,
+      schedule: void 0
+    };
+  }
+  /**
+   * Build a schedule-holder subject for NATS message scheduling.
+   *
+   * The schedule-holder subject resides in the same stream as the target but
+   * uses a separate `_sch` namespace that is NOT matched by any consumer filter.
+   * NATS holds the message and publishes it to the target subject after the delay.
+   *
+   * Examples:
+   * - `{svc}__microservice.ev.order.reminder` → `{svc}__microservice._sch.order.reminder`
+   * - `broadcast.config.updated` → `broadcast._sch.config.updated`
+   */
+  buildScheduleSubject(eventSubject) {
+    if (eventSubject.startsWith("broadcast.")) {
+      return eventSubject.replace("broadcast.", "broadcast._sch.");
+    }
+    const targetPrefix = `${internalName(this.targetName)}.`;
+    if (!eventSubject.startsWith(targetPrefix)) {
+      throw new Error(`Unexpected event subject format: ${eventSubject}`);
+    }
+    const withoutPrefix = eventSubject.slice(targetPrefix.length);
+    const dotIndex = withoutPrefix.indexOf(".");
+    if (dotIndex === -1) {
+      throw new Error(`Event subject missing pattern segment: ${eventSubject}`);
+    }
+    const pattern = withoutPrefix.slice(dotIndex + 1);
+    return `${targetPrefix}_sch.${pattern}`;
   }
   getRpcTimeout() {
     if (!this.rootOptions.rpc) return DEFAULT_RPC_TIMEOUT;
@@ -607,25 +693,26 @@ var JetstreamClient = class extends ClientProxy {
 };
 
 // src/codec/json.codec.ts
-import { JSONCodec as NatsJSONCodec } from "nats";
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
 var JsonCodec = class {
-  inner = NatsJSONCodec();
   encode(data) {
-    return this.inner.encode(data);
+    return encoder.encode(JSON.stringify(data));
   }
   decode(data) {
-    return this.inner.decode(data);
+    return JSON.parse(decoder.decode(data));
   }
 };
 
 // src/connection/connection.provider.ts
 import { Logger as Logger2 } from "@nestjs/common";
 import {
-  connect,
-  DebugEvents,
-  Events as Events2,
-  NatsError
-} from "nats";
+  connect
+} from "@nats-io/transport-node";
+import {
+  jetstream,
+  jetstreamManager
+} from "@nats-io/jetstream";
 import { defer, from, share, shareReplay, switchMap } from "rxjs";
 var DEFAULT_OPTIONS = {
   maxReconnectAttempts: -1,
@@ -679,14 +766,7 @@ var ConnectionProvider = class {
   async getJetStreamManager() {
     if (this.jsmInstance) 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;
-    });
+    this.jsmPromise = this.initJetStreamManager();
     return this.jsmPromise;
   }
   /**
@@ -702,7 +782,7 @@ var ConnectionProvider = class {
     if (!this.connection || this.connection.isClosed()) {
       throw new Error("Not connected \u2014 call getConnection() before getJetStreamClient()");
     }
-    this.jsClient ??= this.connection.jetstream();
+    this.jsClient ??= jetstream(this.connection);
     return this.jsClient;
   }
   /** Direct access to the raw NATS connection, or `null` if not yet connected. */
@@ -738,6 +818,16 @@ var ConnectionProvider = class {
       this.jsmPromise = null;
     }
   }
+  async initJetStreamManager() {
+    try {
+      const nc = await this.getConnection();
+      this.jsmInstance = await jetstreamManager(nc);
+      this.logger.log("JetStream manager initialized");
+      return this.jsmInstance;
+    } finally {
+      this.jsmPromise = null;
+    }
+  }
   /** Internal: establish the physical connection with reconnect monitoring. */
   async establish() {
     const name = internalName(this.options.name);
@@ -754,7 +844,7 @@ var ConnectionProvider = class {
       this.monitorStatus(nc);
       return nc;
     } catch (err) {
-      if (err instanceof NatsError && err.code === "CONNECTION_REFUSED") {
+      if (err instanceof Error && err.message.includes("REFUSED")) {
         throw new Error(`NATS connection refused: ${this.options.servers.join(", ")}`);
       }
       throw err;
@@ -762,27 +852,33 @@ var ConnectionProvider = class {
   }
   /** Subscribe to connection status events and emit hooks. */
   monitorStatus(nc) {
-    (async () => {
+    void (async () => {
       for await (const status of nc.status()) {
         switch (status.type) {
-          case Events2.Disconnect:
+          case "disconnect":
             this.eventBus.emit("disconnect" /* Disconnect */);
             break;
-          case Events2.Reconnect:
+          case "reconnect":
             this.jsClient = null;
             this.jsmInstance = null;
             this.jsmPromise = null;
             this.eventBus.emit("reconnect" /* Reconnect */, nc.getServer());
             break;
-          case Events2.Error:
-            this.eventBus.emit("error" /* Error */, new Error(String(status.data)), "connection");
+          case "error":
+            this.eventBus.emit(
+              "error" /* Error */,
+              status.error,
+              "connection"
+            );
             break;
-          case Events2.Update:
-          case Events2.LDM:
-          case DebugEvents.Reconnecting:
-          case DebugEvents.PingTimer:
-          case DebugEvents.StaleConnection:
-          case DebugEvents.ClientInitiatedReconnect:
+          case "update":
+          case "ldm":
+          case "reconnecting":
+          case "ping":
+          case "staleConnection":
+          case "forceReconnect":
+          case "slowConsumer":
+          case "close":
             break;
         }
       }
@@ -1044,7 +1140,7 @@ var JetstreamStrategy = class extends Server {
 
 // src/server/core-rpc.server.ts
 import { Logger as Logger4 } from "@nestjs/common";
-import { headers as natsHeaders2 } from "nats";
+import { headers as natsHeaders2 } from "@nats-io/transport-node";
 
 // src/context/rpc.context.ts
 import { BaseRpcContext } from "@nestjs/microservices";
@@ -1341,7 +1437,7 @@ var CoreRpcServer = class {
 
 // src/server/infrastructure/stream.provider.ts
 import { Logger as Logger5 } from "@nestjs/common";
-import { NatsError as NatsError2 } from "nats";
+import { JetStreamApiError } from "@nats-io/jetstream";
 var STREAM_NOT_FOUND = 10059;
 var StreamProvider = class {
   constructor(options, connection) {
@@ -1367,12 +1463,22 @@ var StreamProvider = class {
   getSubjects(kind) {
     const name = internalName(this.options.name);
     switch (kind) {
-      case "ev" /* Event */:
-        return [`${name}.${"ev" /* Event */}.>`];
+      case "ev" /* Event */: {
+        const subjects = [`${name}.${"ev" /* Event */}.>`];
+        if (this.isSchedulingEnabled(kind)) {
+          subjects.push(`${name}._sch.>`);
+        }
+        return subjects;
+      }
       case "cmd" /* Command */:
         return [`${name}.${"cmd" /* Command */}.>`];
-      case "broadcast" /* Broadcast */:
-        return ["broadcast.>"];
+      case "broadcast" /* Broadcast */: {
+        const subjects = ["broadcast.>"];
+        if (this.isSchedulingEnabled(kind)) {
+          subjects.push("broadcast._sch.>");
+        }
+        return subjects;
+      }
       case "ordered" /* Ordered */:
         return [`${name}.${"ordered" /* Ordered */}.>`];
     }
@@ -1386,7 +1492,7 @@ var StreamProvider = class {
       this.logger.debug(`Stream exists, updating: ${config.name}`);
       return await jsm.streams.update(config.name, config);
     } catch (err) {
-      if (err instanceof NatsError2 && err.api_error?.err_code === STREAM_NOT_FOUND) {
+      if (err instanceof JetStreamApiError && err.apiError().err_code === STREAM_NOT_FOUND) {
         this.logger.log(`Creating stream: ${config.name}`);
         return await jsm.streams.add(config);
       }
@@ -1421,6 +1527,11 @@ var StreamProvider = class {
         return DEFAULT_ORDERED_STREAM_CONFIG;
     }
   }
+  /** Check if scheduling is enabled for a stream kind via `allow_msg_schedules` override. */
+  isSchedulingEnabled(kind) {
+    const overrides = this.getOverrides(kind);
+    return overrides.allow_msg_schedules === true;
+  }
   /** Get user-provided overrides for a stream kind. */
   getOverrides(kind) {
     switch (kind) {
@@ -1438,7 +1549,7 @@ var StreamProvider = class {
 
 // src/server/infrastructure/consumer.provider.ts
 import { Logger as Logger6 } from "@nestjs/common";
-import { NatsError as NatsError3 } from "nats";
+import { JetStreamApiError as JetStreamApiError2 } from "@nats-io/jetstream";
 var CONSUMER_NOT_FOUND = 10014;
 var ConsumerProvider = class {
   constructor(options, connection, streamProvider, patternRegistry) {
@@ -1479,7 +1590,7 @@ var ConsumerProvider = class {
       this.logger.debug(`Consumer exists, updating: ${name}`);
       return await jsm.consumers.update(stream, name, config);
     } catch (err) {
-      if (err instanceof NatsError3 && err.api_error?.err_code === CONSUMER_NOT_FOUND) {
+      if (err instanceof JetStreamApiError2 && err.apiError().err_code === CONSUMER_NOT_FOUND) {
         this.logger.log(`Creating consumer: ${name}`);
         return await jsm.consumers.add(stream, config);
       }
@@ -1538,6 +1649,10 @@ var ConsumerProvider = class {
         return DEFAULT_BROADCAST_CONSUMER_CONFIG;
       case "ordered" /* Ordered */:
         throw new Error("Ordered consumers are ephemeral and should not use durable config");
+      default: {
+        const _exhaustive = kind;
+        throw new Error(`Unexpected StreamKind: ${_exhaustive}`);
+      }
     }
   }
   /** Get user-provided overrides for a consumer kind. */
@@ -1551,16 +1666,17 @@ var ConsumerProvider = class {
         return this.options.broadcast?.consumer ?? {};
       case "ordered" /* Ordered */:
         throw new Error("Ordered consumers are ephemeral and should not use durable config");
+      default: {
+        const _exhaustive = kind;
+        throw new Error(`Unexpected StreamKind: ${_exhaustive}`);
+      }
     }
   }
 };
 
 // src/server/infrastructure/message.provider.ts
 import { Logger as Logger7 } from "@nestjs/common";
-import {
-  ConsumerEvents,
-  DeliverPolicy as DeliverPolicy2
-} from "nats";
+import { DeliverPolicy as DeliverPolicy2 } from "@nats-io/jetstream";
 import {
   catchError,
   defer as defer2,
@@ -1629,7 +1745,7 @@ var MessageProvider = class {
    * @param orderedConfig - Optional overrides for ordered consumer options.
    */
   async startOrdered(streamName2, filterSubjects, orderedConfig) {
-    const consumerOpts = { filterSubjects };
+    const consumerOpts = { filter_subjects: filterSubjects };
     if (orderedConfig?.deliverPolicy !== void 0 && orderedConfig.deliverPolicy !== DeliverPolicy2.All) {
       consumerOpts.deliver_policy = orderedConfig.deliverPolicy;
     }
@@ -1714,10 +1830,10 @@ var MessageProvider = class {
   }
   /** Monitor heartbeats and restart the consumer iterator on prolonged silence. */
   monitorConsumerHealth(messages, name) {
-    (async () => {
-      for await (const status of await messages.status()) {
-        if (status.type === ConsumerEvents.HeartbeatsMissed && status.data >= 2) {
-          this.logger.warn(`Consumer ${name}: ${status.data} heartbeats missed, restarting`);
+    void (async () => {
+      for await (const status of messages.status()) {
+        if (status.type === "heartbeats_missed" && status.count >= 2) {
+          this.logger.warn(`Consumer ${name}: ${status.count} heartbeats missed, restarting`);
           messages.stop();
           break;
         }
@@ -2097,7 +2213,7 @@ var EventRouter = class {
 
 // src/server/routing/rpc.router.ts
 import { Logger as Logger10 } from "@nestjs/common";
-import { headers } from "nats";
+import { headers } from "@nats-io/transport-node";
 import { from as from3, mergeMap as mergeMap2 } from "rxjs";
 var RpcRouter = class {
   constructor(messageProvider, patternRegistry, connection, codec, eventBus, rpcOptions, ackWaitMap) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@horizon-republic/nestjs-jetstream",
-  "version": "2.7.1",
+  "version": "2.8.0",
   "description": "A NestJS transport for NATS with JetStream events, broadcast fan-out, and Core/JetStream RPC.",
   "repository": {
     "type": "git",
@@ -57,7 +57,6 @@
     "@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"
   },
@@ -75,12 +74,18 @@
     "eslint-plugin-sonarjs": "^4.0.2",
     "eslint-plugin-unused-imports": "^4.4.1",
     "prettier": "^3.8.1",
+    "testcontainers": "^11.13.0",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
     "typescript": "~5.9.3",
-    "typescript-eslint": "^8.57.2",
+    "typescript-eslint": "^8.58.0",
     "vitest": "^4.1.2"
   },
+  "dependencies": {
+    "@nats-io/jetstream": "^3.3.1",
+    "@nats-io/nuid": "^2.0.3",
+    "@nats-io/transport-node": "^3.3.1"
+  },
   "scripts": {
     "build": "tsup",
     "build:watch": "tsup --watch",