@horizon-republic/nestjs-jetstream 2.3.6 → 2.4.1

package/dist/index.js

@@ -109,6 +109,20 @@ var DEFAULT_BROADCAST_STREAM_CONFIG = {
   duplicate_window: nanos(2 * 60 * 1e3)
   // 2 min
 };
+var DEFAULT_ORDERED_STREAM_CONFIG = {
+  ...baseStreamConfig,
+  retention: RetentionPolicy.Limits,
+  allow_rollup_hdrs: false,
+  max_consumers: 100,
+  max_msg_size: 10 * MB,
+  max_msgs_per_subject: 5e6,
+  max_msgs: 5e7,
+  max_bytes: 5 * GB,
+  max_age: nanos(24 * 60 * 60 * 1e3),
+  // 1 day
+  duplicate_window: nanos(2 * 60 * 1e3)
+  // 2 min
+};
 var DEFAULT_EVENT_CONSUMER_CONFIG = {
   ack_wait: nanos(10 * 1e3),
   // 10s
@@ -144,9 +158,6 @@ var JetstreamHeader = /* @__PURE__ */ ((JetstreamHeader2) => {
   JetstreamHeader2["ReplyTo"] = "x-reply-to";
   JetstreamHeader2["Subject"] = "x-subject";
   JetstreamHeader2["CallerName"] = "x-caller-name";
-  JetstreamHeader2["RequestId"] = "x-request-id";
-  JetstreamHeader2["TraceId"] = "x-trace-id";
-  JetstreamHeader2["SpanId"] = "x-span-id";
   JetstreamHeader2["Error"] = "x-error";
   return JetstreamHeader2;
 })(JetstreamHeader || {});
@@ -169,16 +180,18 @@ var consumerName = (serviceName, kind) => {
 
 // src/client/jetstream.record.ts
 var JetstreamRecord = class {
-  constructor(data, headers2, timeout) {
+  constructor(data, headers2, timeout, messageId) {
     this.data = data;
     this.headers = headers2;
     this.timeout = timeout;
+    this.messageId = messageId;
   }
 };
 var JetstreamRecordBuilder = class {
   data;
   headers = /* @__PURE__ */ new Map();
   timeout;
+  messageId;
   constructor(data) {
     this.data = data;
   }
@@ -215,6 +228,28 @@ var JetstreamRecordBuilder = class {
     }
     return this;
   }
+  /**
+   * Set a custom message ID for JetStream deduplication.
+   *
+   * NATS JetStream uses this ID to detect duplicate publishes within the
+   * stream's `duplicate_window`. If two messages with the same ID arrive
+   * within the window, the second is silently dropped.
+   *
+   * When not set, a random UUID is generated automatically.
+   *
+   * @param id - Unique message identifier (e.g. order ID, idempotency key).
+   *
+   * @example
+   * ```typescript
+   * new JetstreamRecordBuilder(data)
+   *   .setMessageId(`order-${order.id}`)
+   *   .build();
+   * ```
+   */
+  setMessageId(id) {
+    this.messageId = id;
+    return this;
+  }
   /**
    * Set per-request RPC timeout.
    *
@@ -230,7 +265,12 @@ var JetstreamRecordBuilder = class {
    * @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);
+    return new JetstreamRecord(
+      this.data,
+      new Map(this.headers),
+      this.timeout,
+      this.messageId
+    );
   }
   /** Validate that a header key is not reserved. */
   validateHeaderKey(key) {
@@ -310,12 +350,12 @@ var JetstreamClient = class extends ClientProxy {
    */
   async dispatchEvent(packet) {
     const nc = await this.connect();
-    const { data, hdrs } = this.extractRecordData(packet.data);
+    const { data, hdrs, messageId } = this.extractRecordData(packet.data);
     const subject = this.buildEventSubject(packet.pattern);
     const msgHeaders = this.buildHeaders(hdrs, { subject });
     const ack = await nc.jetstream().publish(subject, this.codec.encode(data), {
       headers: msgHeaders,
-      msgID: crypto.randomUUID()
+      msgID: messageId ?? crypto.randomUUID()
     });
     if (ack.duplicate) {
       this.logger.warn(`Duplicate event publish detected: ${subject} (seq: ${ack.seq})`);
@@ -330,7 +370,7 @@ var JetstreamClient = class extends ClientProxy {
    */
   publish(packet, callback) {
     const subject = buildSubject(this.targetName, "cmd", packet.pattern);
-    const { data, hdrs, timeout } = this.extractRecordData(packet.data);
+    const { data, hdrs, timeout, messageId } = this.extractRecordData(packet.data);
     const onUnhandled = (err) => {
       this.logger.error("Unhandled publish error:", err);
       callback({ err: new Error("Internal transport error"), response: null, isDisposed: true });
@@ -346,7 +386,8 @@ var JetstreamClient = class extends ClientProxy {
         hdrs,
         timeout,
         callback,
-        jetStreamCorrelationId
+        jetStreamCorrelationId,
+        messageId
       ).catch(onUnhandled);
     }
     return () => {
@@ -384,7 +425,7 @@ var JetstreamClient = class extends ClientProxy {
     }
   }
   /** JetStream mode: publish to stream + wait for inbox response. */
-  async publishJetStreamRpc(subject, data, customHeaders, timeout, callback, correlationId = crypto.randomUUID()) {
+  async publishJetStreamRpc(subject, data, customHeaders, timeout, callback, correlationId = crypto.randomUUID(), messageId) {
     const effectiveTimeout = timeout ?? this.getRpcTimeout();
     this.pendingMessages.set(correlationId, callback);
     const timeoutId = setTimeout(() => {
@@ -408,7 +449,7 @@ var JetstreamClient = class extends ClientProxy {
       });
       await nc.jetstream().publish(subject, this.codec.encode(data), {
         headers: hdrs,
-        msgID: crypto.randomUUID()
+        msgID: messageId ?? crypto.randomUUID()
       });
     } catch (err) {
       clearTimeout(timeoutId);
@@ -486,11 +527,14 @@ var JetstreamClient = class extends ClientProxy {
       this.pendingMessages.delete(correlationId);
     }
   }
-  /** Build event subject — workqueue or broadcast. */
+  /** Build event subject — workqueue, broadcast, or ordered. */
   buildEventSubject(pattern) {
     if (pattern.startsWith("broadcast:")) {
       return buildBroadcastSubject(pattern.slice("broadcast:".length));
     }
+    if (pattern.startsWith("ordered:")) {
+      return buildSubject(this.targetName, "ordered", pattern.slice("ordered:".length));
+    }
     return buildSubject(this.targetName, "ev", pattern);
   }
   /** Build NATS headers merging custom headers with transport headers. */
@@ -517,10 +561,11 @@ var JetstreamClient = class extends ClientProxy {
       return {
         data: rawData.data,
         hdrs: rawData.headers.size > 0 ? new Map(rawData.headers) : null,
-        timeout: rawData.timeout
+        timeout: rawData.timeout,
+        messageId: rawData.messageId
       };
     }
-    return { data: rawData, hdrs: null, timeout: void 0 };
+    return { data: rawData, hdrs: null, timeout: void 0, messageId: void 0 };
   }
   isCoreRpcMode() {
     return !this.rootOptions.rpc || this.rootOptions.rpc.mode === "core";
@@ -822,12 +867,23 @@ var JetstreamStrategy = class extends Server {
     this.started = true;
     this.patternRegistry.registerHandlers(this.getHandlers());
     const streamKinds = this.resolveStreamKinds();
+    const durableKinds = this.resolveDurableConsumerKinds();
     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()) {
+      if (durableKinds.length > 0) {
+        const consumers = await this.consumerProvider.ensureConsumers(durableKinds);
+        this.eventRouter.updateMaxDeliverMap(this.buildMaxDeliverMap(consumers));
+        this.messageProvider.start(consumers);
+      }
+      if (this.patternRegistry.hasOrderedHandlers()) {
+        const orderedStreamName = this.streamProvider.getStreamName("ordered");
+        await this.messageProvider.startOrdered(
+          orderedStreamName,
+          this.patternRegistry.getOrderedSubjects(),
+          this.options.ordered
+        );
+      }
+      if (this.patternRegistry.hasEventHandlers() || this.patternRegistry.hasBroadcastHandlers() || this.patternRegistry.hasOrderedHandlers()) {
         this.eventRouter.start();
       }
       if (this.isJetStreamRpcMode() && this.patternRegistry.hasRpcHandlers()) {
@@ -875,8 +931,25 @@ var JetstreamStrategy = class extends Server {
   getPatternRegistry() {
     return this.patternRegistry;
   }
-  /** Determine which JetStream stream kinds are needed. */
+  /** Determine which JetStream streams are needed. */
   resolveStreamKinds() {
+    const kinds = [];
+    if (this.patternRegistry.hasEventHandlers()) {
+      kinds.push("ev");
+    }
+    if (this.patternRegistry.hasOrderedHandlers()) {
+      kinds.push("ordered");
+    }
+    if (this.isJetStreamRpcMode() && this.patternRegistry.hasRpcHandlers()) {
+      kinds.push("cmd");
+    }
+    if (this.patternRegistry.hasBroadcastHandlers()) {
+      kinds.push("broadcast");
+    }
+    return kinds;
+  }
+  /** Determine which stream kinds need durable consumers (ordered consumers are ephemeral). */
+  resolveDurableConsumerKinds() {
     const kinds = [];
     if (this.patternRegistry.hasEventHandlers()) {
       kinds.push("ev");
@@ -1103,6 +1176,8 @@ var StreamProvider = class {
         return [`${name}.cmd.>`];
       case "broadcast":
         return ["broadcast.>"];
+      case "ordered":
+        return [`${name}.ordered.>`];
     }
   }
   /** Ensure a single stream exists, creating or updating as needed. */
@@ -1145,6 +1220,8 @@ var StreamProvider = class {
         return DEFAULT_COMMAND_STREAM_CONFIG;
       case "broadcast":
         return DEFAULT_BROADCAST_STREAM_CONFIG;
+      case "ordered":
+        return DEFAULT_ORDERED_STREAM_CONFIG;
     }
   }
   /** Get user-provided overrides for a stream kind. */
@@ -1156,6 +1233,8 @@ var StreamProvider = class {
         return this.options.rpc?.mode === "jetstream" ? this.options.rpc.stream ?? {} : {};
       case "broadcast":
         return this.options.broadcast?.stream ?? {};
+      case "ordered":
+        return this.options.ordered?.stream ?? {};
     }
   }
 };
@@ -1257,6 +1336,8 @@ var ConsumerProvider = class {
         return DEFAULT_COMMAND_CONSUMER_CONFIG;
       case "broadcast":
         return DEFAULT_BROADCAST_CONSUMER_CONFIG;
+      case "ordered":
+        throw new Error("Ordered consumers are ephemeral and should not use durable config");
     }
   }
   /** Get user-provided overrides for a consumer kind. */
@@ -1268,12 +1349,15 @@ var ConsumerProvider = class {
         return this.options.rpc?.mode === "jetstream" ? this.options.rpc.consumer ?? {} : {};
       case "broadcast":
         return this.options.broadcast?.consumer ?? {};
+      case "ordered":
+        throw new Error("Ordered consumers are ephemeral and should not use durable config");
     }
   }
 };
 
 // src/server/infrastructure/message.provider.ts
 import { Logger as Logger7 } from "@nestjs/common";
+import { DeliverPolicy as DeliverPolicy2 } from "nats";
 import {
   catchError,
   defer as defer2,
@@ -1292,10 +1376,13 @@ var MessageProvider = class {
   }
   logger = new Logger7("Jetstream:Message");
   activeIterators = /* @__PURE__ */ new Set();
+  orderedReadyResolve = null;
+  orderedReadyReject = null;
   destroy$ = new Subject();
   eventMessages$ = new Subject();
   commandMessages$ = new Subject();
   broadcastMessages$ = new Subject();
+  orderedMessages$ = new Subject();
   /** Observable stream of workqueue event messages. */
   get events$() {
     return this.eventMessages$.asObservable();
@@ -1308,6 +1395,10 @@ var MessageProvider = class {
   get broadcasts$() {
     return this.broadcastMessages$.asObservable();
   }
+  /** Observable stream of ordered event messages (strict sequential delivery). */
+  get ordered$() {
+    return this.orderedMessages$.asObservable();
+  }
   /**
    * Start consuming messages from the given consumer infos.
    *
@@ -1323,6 +1414,37 @@ var MessageProvider = class {
       merge(...flows).pipe(takeUntil(this.destroy$)).subscribe();
     }
   }
+  /**
+   * Start an ordered consumer for strict sequential delivery.
+   *
+   * Unlike durable consumers, ordered consumers are ephemeral — created at
+   * consumption time, no durable state. nats.js handles auto-recreation.
+   *
+   * @param streamName - JetStream stream to consume from.
+   * @param filterSubjects - NATS subjects to filter on.
+   */
+  async startOrdered(streamName2, filterSubjects, orderedConfig) {
+    const consumerOpts = { filterSubjects };
+    if (orderedConfig?.deliverPolicy !== void 0 && orderedConfig.deliverPolicy !== DeliverPolicy2.All) {
+      consumerOpts.deliver_policy = orderedConfig.deliverPolicy;
+    }
+    if (orderedConfig?.optStartSeq !== void 0) {
+      consumerOpts.opt_start_seq = orderedConfig.optStartSeq;
+    }
+    if (orderedConfig?.optStartTime !== void 0) {
+      consumerOpts.opt_start_time = orderedConfig.optStartTime;
+    }
+    if (orderedConfig?.replayPolicy !== void 0) {
+      consumerOpts.replay_policy = orderedConfig.replayPolicy;
+    }
+    const ready = new Promise((resolve, reject) => {
+      this.orderedReadyResolve = resolve;
+      this.orderedReadyReject = reject;
+    });
+    const flow = this.createOrderedFlow(streamName2, consumerOpts);
+    flow.pipe(takeUntil(this.destroy$)).subscribe();
+    return ready;
+  }
   /** Stop all consumer flows and reinitialize subjects for potential restart. */
   destroy() {
     this.destroy$.next();
@@ -1334,10 +1456,12 @@ var MessageProvider = class {
     this.eventMessages$.complete();
     this.commandMessages$.complete();
     this.broadcastMessages$.complete();
+    this.orderedMessages$.complete();
     this.destroy$ = new Subject();
     this.eventMessages$ = new Subject();
     this.commandMessages$ = new Subject();
     this.broadcastMessages$ = new Subject();
+    this.orderedMessages$ = new Subject();
   }
   /** Create a self-healing consumer flow for a specific kind. */
   createFlow(kind, info) {
@@ -1395,6 +1519,63 @@ var MessageProvider = class {
         return this.commandMessages$;
       case "broadcast":
         return this.broadcastMessages$;
+      case "ordered":
+        return this.orderedMessages$;
+    }
+  }
+  /** Create a self-healing ordered consumer flow. */
+  createOrderedFlow(streamName2, consumerOpts) {
+    let consecutiveFailures = 0;
+    let lastRunFailed = false;
+    return defer2(() => this.consumeOrderedOnce(streamName2, consumerOpts)).pipe(
+      tap(() => {
+        lastRunFailed = false;
+      }),
+      catchError((err) => {
+        consecutiveFailures++;
+        lastRunFailed = true;
+        this.logger.error("Ordered consumer error, will restart:", err);
+        this.eventBus.emit(
+          "error" /* Error */,
+          err instanceof Error ? err : new Error(String(err)),
+          "message-provider"
+        );
+        if (this.orderedReadyReject) {
+          this.orderedReadyReject(err);
+          this.orderedReadyReject = null;
+          this.orderedReadyResolve = null;
+        }
+        return EMPTY;
+      }),
+      repeat({
+        delay: () => {
+          if (!lastRunFailed) {
+            consecutiveFailures = 0;
+          }
+          const delay = Math.min(100 * Math.pow(2, consecutiveFailures), 3e4);
+          this.logger.warn(`Ordered consumer stream ended, restarting in ${delay}ms...`);
+          return timer(delay);
+        }
+      })
+    );
+  }
+  /** Single iteration: create ordered consumer -> iterate messages. */
+  async consumeOrderedOnce(streamName2, consumerOpts) {
+    const js = (await this.connection.getConnection()).jetstream();
+    const consumer = await js.consumers.get(streamName2, consumerOpts);
+    const messages = await consumer.consume();
+    if (this.orderedReadyResolve) {
+      this.orderedReadyResolve();
+      this.orderedReadyResolve = null;
+      this.orderedReadyReject = null;
+    }
+    this.activeIterators.add(messages);
+    try {
+      for await (const msg of messages) {
+        this.orderedMessages$.next(msg);
+      }
+    } finally {
+      this.activeIterators.delete(messages);
     }
   }
 };
@@ -1415,11 +1596,20 @@ var PatternRegistry = class {
   registerHandlers(handlers) {
     const serviceName = this.options.name;
     for (const [pattern, handler] of handlers) {
+      const extras = handler.extras;
       const isEvent = handler.isEventHandler ?? false;
-      const isBroadcast = !!handler.extras?.broadcast;
+      const isBroadcast = !!extras?.broadcast;
+      const isOrdered = !!extras?.ordered;
+      if (isBroadcast && isOrdered) {
+        throw new Error(
+          `Handler "${pattern}" cannot be both broadcast and ordered. Use one or the other.`
+        );
+      }
       let fullSubject;
       if (isBroadcast) {
         fullSubject = buildBroadcastSubject(pattern);
+      } else if (isOrdered) {
+        fullSubject = buildSubject(serviceName, "ordered", pattern);
       } else if (isEvent) {
         fullSubject = buildSubject(serviceName, "ev", pattern);
       } else {
@@ -1428,12 +1618,15 @@ var PatternRegistry = class {
       this.registry.set(fullSubject, {
         handler,
         pattern,
-        isEvent,
-        isBroadcast
+        isEvent: isEvent && !isOrdered,
+        isBroadcast,
+        isOrdered
       });
       let kind;
       if (isBroadcast) {
         kind = "broadcast";
+      } else if (isOrdered) {
+        kind = "ordered";
       } else if (isEvent) {
         kind = "event";
       } else {
@@ -1457,28 +1650,41 @@ var PatternRegistry = class {
   }
   /** Check if any RPC (command) handlers are registered. */
   hasRpcHandlers() {
-    return Array.from(this.registry.values()).some((r) => !r.isEvent && !r.isBroadcast);
+    return Array.from(this.registry.values()).some(
+      (r) => !r.isEvent && !r.isBroadcast && !r.isOrdered
+    );
   }
   /** Check if any workqueue event handlers are registered. */
   hasEventHandlers() {
     return Array.from(this.registry.values()).some((r) => r.isEvent && !r.isBroadcast);
   }
+  /** Check if any ordered event handlers are registered. */
+  hasOrderedHandlers() {
+    return Array.from(this.registry.values()).some((r) => r.isOrdered);
+  }
+  /** Get fully-qualified NATS subjects for ordered handlers. */
+  getOrderedSubjects() {
+    const name = internalName(this.options.name);
+    return Array.from(this.registry.values()).filter((r) => r.isOrdered).map((r) => `${name}.ordered.${r.pattern}`);
+  }
   /** Get patterns grouped by kind. */
   getPatternsByKind() {
     const events = [];
     const commands = [];
     const broadcasts = [];
+    const ordered = [];
     for (const entry of this.registry.values()) {
       if (entry.isBroadcast) broadcasts.push(entry.pattern);
+      else if (entry.isOrdered) ordered.push(entry.pattern);
       else if (entry.isEvent) events.push(entry.pattern);
       else commands.push(entry.pattern);
     }
-    return { events, commands, broadcasts };
+    return { events, commands, broadcasts, ordered };
   }
   /** Normalize a full NATS subject back to the user-facing pattern. */
   normalizeSubject(subject) {
     const name = internalName(this.options.name);
-    const prefixes = [`${name}.cmd.`, `${name}.ev.`, "broadcast."];
+    const prefixes = [`${name}.cmd.`, `${name}.ev.`, `${name}.ordered.`, "broadcast."];
     for (const prefix of prefixes) {
       if (subject.startsWith(prefix)) {
         return subject.slice(prefix.length);
@@ -1488,16 +1694,29 @@ var PatternRegistry = class {
   }
   /** Log a summary of all registered handlers. */
   logSummary() {
-    const { events, commands, broadcasts } = this.getPatternsByKind();
-    this.logger.log(
-      `Registered handlers: ${commands.length} RPC, ${events.length} events, ${broadcasts.length} broadcasts`
-    );
+    const { events, commands, broadcasts, ordered } = this.getPatternsByKind();
+    const parts = [
+      `${commands.length} RPC`,
+      `${events.length} events`,
+      `${broadcasts.length} broadcasts`
+    ];
+    if (ordered.length > 0) {
+      parts.push(`${ordered.length} ordered`);
+    }
+    this.logger.log(`Registered handlers: ${parts.join(", ")}`);
   }
 };
 
 // src/server/routing/event.router.ts
 import { Logger as Logger9 } from "@nestjs/common";
-import { catchError as catchError2, defer as defer3, EMPTY as EMPTY2, from as from2, mergeMap } from "rxjs";
+import {
+  catchError as catchError2,
+  concatMap,
+  defer as defer3,
+  EMPTY as EMPTY2,
+  from as from2,
+  mergeMap
+} from "rxjs";
 var EventRouter = class {
   constructor(messageProvider, patternRegistry, codec, eventBus, deadLetterConfig) {
     this.messageProvider = messageProvider;
@@ -1516,10 +1735,13 @@ var EventRouter = class {
     if (!this.deadLetterConfig) return;
     this.deadLetterConfig.maxDeliverByStream = consumerMaxDelivers;
   }
-  /** Start routing event and broadcast messages to handlers. */
+  /** Start routing event, broadcast, and ordered messages to handlers. */
   start() {
     this.subscribeToStream(this.messageProvider.events$, "workqueue");
     this.subscribeToStream(this.messageProvider.broadcasts$, "broadcast");
+    if (this.patternRegistry.hasOrderedHandlers()) {
+      this.subscribeToStream(this.messageProvider.ordered$, "ordered", true);
+    }
   }
   /** Stop routing and unsubscribe from all streams. */
   destroy() {
@@ -1529,17 +1751,14 @@ var EventRouter = class {
     this.subscriptions.length = 0;
   }
   /** Subscribe to a message stream and route each message. */
-  subscribeToStream(stream$, label) {
-    const subscription = stream$.pipe(
-      mergeMap(
-        (msg) => defer3(() => this.handle(msg)).pipe(
-          catchError2((err) => {
-            this.logger.error(`Unexpected error in ${label} event router`, err);
-            return EMPTY2;
-          })
-        )
-      )
-    ).subscribe();
+  subscribeToStream(stream$, label, isOrdered = false) {
+    const route = (msg) => defer3(() => isOrdered ? this.handleOrdered(msg) : this.handle(msg)).pipe(
+      catchError2((err) => {
+        this.logger.error(`Unexpected error in ${label} event router`, err);
+        return EMPTY2;
+      })
+    );
+    const subscription = stream$.pipe(isOrdered ? concatMap(route) : mergeMap(route)).subscribe();
     this.subscriptions.push(subscription);
   }
   /** Handle a single event message: decode -> execute handler -> ack/nak. */
@@ -1576,6 +1795,28 @@ var EventRouter = class {
       }
     }
   }
+  /** Handle an ordered message: decode -> execute handler -> no ack/nak. */
+  handleOrdered(msg) {
+    const handler = this.patternRegistry.getHandler(msg.subject);
+    if (!handler) {
+      this.logger.error(`No handler for ordered subject: ${msg.subject}`);
+      return EMPTY2;
+    }
+    let data;
+    try {
+      data = this.codec.decode(msg.data);
+    } catch (err) {
+      this.logger.error(`Decode error for ordered ${msg.subject}:`, err);
+      return EMPTY2;
+    }
+    this.eventBus.emit("messageRouted" /* MessageRouted */, msg.subject, "event");
+    const ctx = new RpcContext([msg]);
+    return from2(
+      unwrapResult(handler(data, ctx)).catch((err) => {
+        this.logger.error(`Ordered handler error (${msg.subject}):`, err);
+      })
+    );
+  }
   /** Check if the message has exhausted all delivery attempts. */
   isDeadLetter(msg) {
     if (!this.deadLetterConfig) return false;