@horizon-republic/nestjs-jetstream 2.9.0 → 2.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -525,6 +525,13 @@ declare class EventBus {
525
525
  * Avoids rest/spread overhead of the generic `emit()`.
526
526
  */
527
527
  emitMessageRouted(subject: string, kind: MessageKind): void;
528
+ /**
529
+ * Check whether a hook is registered for the given event.
530
+ *
531
+ * Used by the routing hot path to elide the emit call entirely when the
532
+ * transport owner did not register a listener.
533
+ */
534
+ hasHook(event: keyof TransportHooks): boolean;
528
535
  private callHook;
529
536
  }
530
537
 
@@ -764,20 +771,10 @@ declare class EventRouter {
764
771
  start(): void;
765
772
  /** Stop routing and unsubscribe from all streams. */
766
773
  destroy(): void;
767
- /** Subscribe to a message stream and route each message. */
774
+ /** Subscribe to a message stream and route each message to its handler. */
768
775
  private subscribeToStream;
769
776
  private getConcurrency;
770
777
  private getAckExtensionConfig;
771
- /** Handle a single event message with error isolation. */
772
- private handleSafe;
773
- /** Handle an ordered message with error isolation. */
774
- private handleOrderedSafe;
775
- /** Resolve handler, decode payload, and build context. Returns null on failure. */
776
- private decodeMessage;
777
- /** Execute handler, then ack on success or nak/dead-letter on failure. */
778
- private executeHandler;
779
- /** Check if the message has exhausted all delivery attempts. */
780
- private isDeadLetter;
781
778
  /** Handle a dead letter: invoke callback, then term or nak based on result. */
782
779
  /**
783
780
  * Fallback execution for a dead letter when DLQ is disabled, or when
@@ -839,10 +836,6 @@ declare class RpcRouter {
839
836
  start(): Promise<void>;
840
837
  /** Stop routing and unsubscribe. */
841
838
  destroy(): void;
842
- /** Handle a single RPC command message with error isolation. */
843
- private handleSafe;
844
- /** Execute handler, publish response, settle message. */
845
- private executeHandler;
846
839
  }
847
840
 
848
841
  /**
@@ -978,7 +971,7 @@ declare class MessageProvider {
978
971
  private createOrderedFlow;
979
972
  /** Shared self-healing flow: defer -> retry with exponential backoff on error/completion. */
980
973
  private createSelfHealingFlow;
981
- /** Single iteration: create ordered consumer -> iterate messages. */
974
+ /** Single iteration: create ordered consumer -> push messages into the subject. */
982
975
  private consumeOrderedOnce;
983
976
  }
984
977
 
@@ -1033,6 +1026,21 @@ declare class MetadataProvider {
1033
1026
  private openBucket;
1034
1027
  }
1035
1028
 
1029
+ /**
1030
+ * NATS JetStream API error codes used by the transport.
1031
+ *
1032
+ * Ref: https://github.com/nats-io/nats-server (server error definitions)
1033
+ * Verified on NATS 2.12.6 via integration tests (2026-04-02).
1034
+ */
1035
+ declare enum NatsErrorCode {
1036
+ /** Consumer does not exist on the specified stream. */
1037
+ ConsumerNotFound = 10014,
1038
+ /** Consumer name already in use with different configuration (race condition on create). */
1039
+ ConsumerAlreadyExists = 10148,
1040
+ /** Stream does not exist. */
1041
+ StreamNotFound = 10059
1042
+ }
1043
+
1036
1044
  /**
1037
1045
  * NestJS custom transport strategy for NATS JetStream.
1038
1046
  *
@@ -1227,6 +1235,21 @@ declare class JetstreamClient extends ClientProxy {
1227
1235
  private readonly targetName;
1228
1236
  /** Pre-cached caller name derived from rootOptions.name, computed once in constructor. */
1229
1237
  private readonly callerName;
1238
+ /**
1239
+ * Subject prefixes of the form `{serviceName}__microservice.{kind}.` — one
1240
+ * per stream kind this client may publish to. Built once in the constructor
1241
+ * so producing a full subject is a single string concat with the user pattern.
1242
+ */
1243
+ private readonly eventSubjectPrefix;
1244
+ private readonly commandSubjectPrefix;
1245
+ private readonly orderedSubjectPrefix;
1246
+ /**
1247
+ * RPC configuration snapshots. The values are derived from rootOptions at
1248
+ * construction time so the publish hot path never has to re-run
1249
+ * isCoreRpcMode / getRpcTimeout on every call.
1250
+ */
1251
+ private readonly isCoreMode;
1252
+ private readonly defaultRpcTimeout;
1230
1253
  /** Shared inbox for JetStream-mode RPC responses. */
1231
1254
  private inbox;
1232
1255
  private inboxSubscription;
@@ -1236,6 +1259,12 @@ declare class JetstreamClient extends ClientProxy {
1236
1259
  private readonly pendingTimeouts;
1237
1260
  /** Subscription to connection status events for disconnect handling. */
1238
1261
  private statusSubscription;
1262
+ /**
1263
+ * Cached readiness flag. Once `connect()` has wired the inbox and status
1264
+ * subscription, subsequent publishes skip the `await connect()` microtask
1265
+ * and reach for the underlying connection synchronously instead.
1266
+ */
1267
+ private readyForPublish;
1239
1268
  constructor(rootOptions: JetstreamModuleOptions, targetServiceName: string, connection: ConnectionProvider, codec: Codec, eventBus: EventBus);
1240
1269
  /**
1241
1270
  * Establish connection. Called automatically by NestJS on first use.
@@ -1282,7 +1311,14 @@ declare class JetstreamClient extends ClientProxy {
1282
1311
  private setupInbox;
1283
1312
  /** Route an inbox reply to the matching pending callback. */
1284
1313
  private routeInboxReply;
1285
- /** Build event subject — workqueue, broadcast, or ordered. */
1314
+ /**
1315
+ * Resolve a user pattern to a fully-qualified NATS subject, dispatching
1316
+ * between the event, broadcast, and ordered prefixes.
1317
+ *
1318
+ * The leading-char check short-circuits the `startsWith` comparisons for
1319
+ * patterns that cannot possibly carry a broadcast/ordered marker, which is
1320
+ * the overwhelmingly common case.
1321
+ */
1286
1322
  private buildEventSubject;
1287
1323
  /** Build NATS headers merging custom headers with transport headers. */
1288
1324
  private buildHeaders;
@@ -1300,7 +1336,6 @@ declare class JetstreamClient extends ClientProxy {
1300
1336
  * - `broadcast.config.updated` → `broadcast._sch.config.updated`
1301
1337
  */
1302
1338
  private buildScheduleSubject;
1303
- private getRpcTimeout;
1304
1339
  }
1305
1340
 
1306
1341
  /**
@@ -1469,6 +1504,52 @@ declare class JsonCodec implements Codec {
1469
1504
  decode(data: Uint8Array): unknown;
1470
1505
  }
1471
1506
 
1507
+ /**
1508
+ * Minimal shape of a `msgpackr` `Packr` instance used by {@link MsgpackCodec}.
1509
+ *
1510
+ * Typed locally so consumers who do not use MessagePack encoding never pay
1511
+ * for a `msgpackr` import.
1512
+ */
1513
+ interface PackrLike {
1514
+ pack(data: unknown): Uint8Array;
1515
+ unpack(data: Uint8Array): unknown;
1516
+ }
1517
+ /**
1518
+ * MessagePack codec backed by a caller-provided `msgpackr` `Packr` instance.
1519
+ *
1520
+ * Use this codec when publishing structured payloads larger than roughly
1521
+ * 1–2 KB — below that size the default {@link JsonCodec} wins on per-call
1522
+ * constant overhead. Above it, MessagePack encodes and decodes several times
1523
+ * faster and produces smaller wire frames. The format is cross-language, so
1524
+ * Node producers and non-Node consumers (Python, Go, Java, Rust, ...) stay
1525
+ * interoperable.
1526
+ *
1527
+ * Requires installing the optional `msgpackr` peer dependency:
1528
+ *
1529
+ * ```bash
1530
+ * npm install msgpackr
1531
+ * # or: pnpm add msgpackr
1532
+ * ```
1533
+ *
1534
+ * @example
1535
+ * ```typescript
1536
+ * import { JetstreamModule, MsgpackCodec } from '@horizon-republic/nestjs-jetstream';
1537
+ * import { Packr } from 'msgpackr';
1538
+ *
1539
+ * JetstreamModule.forRoot({
1540
+ * name: 'orders',
1541
+ * servers: ['nats://localhost:4222'],
1542
+ * codec: new MsgpackCodec(new Packr()),
1543
+ * });
1544
+ * ```
1545
+ */
1546
+ declare class MsgpackCodec implements Codec {
1547
+ private readonly packr;
1548
+ constructor(packr: PackrLike);
1549
+ encode(data: unknown): Uint8Array;
1550
+ decode(data: Uint8Array): unknown;
1551
+ }
1552
+
1472
1553
  type NatsMessage = JsMsg | Msg;
1473
1554
  /**
1474
1555
  * Execution context for RPC and event handlers.
@@ -1625,8 +1706,6 @@ declare const JETSTREAM_OPTIONS: unique symbol;
1625
1706
  declare const JETSTREAM_CONNECTION: unique symbol;
1626
1707
  /** Token for the global Codec instance. */
1627
1708
  declare const JETSTREAM_CODEC: unique symbol;
1628
- /** Token for the EventBus instance. */
1629
- declare const JETSTREAM_EVENT_BUS: unique symbol;
1630
1709
  /**
1631
1710
  * Generate the injection token for a `forFeature()` client.
1632
1711
  *
@@ -1659,6 +1738,28 @@ type TimeUnit = 'ms' | 'seconds' | 'minutes' | 'hours' | 'days';
1659
1738
  * ```
1660
1739
  */
1661
1740
  declare const toNanos: (value: number, unit: TimeUnit) => number;
1741
+ /** Default config for workqueue event streams. */
1742
+ declare const DEFAULT_EVENT_STREAM_CONFIG: Partial<StreamConfig>;
1743
+ /** Default config for RPC command streams (jetstream mode only). */
1744
+ declare const DEFAULT_COMMAND_STREAM_CONFIG: Partial<StreamConfig>;
1745
+ /** Default config for broadcast event streams. */
1746
+ declare const DEFAULT_BROADCAST_STREAM_CONFIG: Partial<StreamConfig>;
1747
+ /** Default config for ordered event streams (Limits retention). */
1748
+ declare const DEFAULT_ORDERED_STREAM_CONFIG: Partial<StreamConfig>;
1749
+ /** Default config for dead-letter queue (DLQ) streams. */
1750
+ declare const DEFAULT_DLQ_STREAM_CONFIG: Partial<StreamConfig>;
1751
+ /** Default config for workqueue event consumers. */
1752
+ declare const DEFAULT_EVENT_CONSUMER_CONFIG: Partial<ConsumerConfig>;
1753
+ /** Default config for RPC command consumers (jetstream mode only). */
1754
+ declare const DEFAULT_COMMAND_CONSUMER_CONFIG: Partial<ConsumerConfig>;
1755
+ /** Default config for broadcast event consumers. */
1756
+ declare const DEFAULT_BROADCAST_CONSUMER_CONFIG: Partial<ConsumerConfig>;
1757
+ /** Default RPC timeout for Core mode (30 seconds). */
1758
+ declare const DEFAULT_RPC_TIMEOUT = 30000;
1759
+ /** Default RPC timeout for JetStream mode (3 minutes). */
1760
+ declare const DEFAULT_JETSTREAM_RPC_TIMEOUT = 180000;
1761
+ /** Default graceful shutdown timeout (10 seconds). */
1762
+ declare const DEFAULT_SHUTDOWN_TIMEOUT = 10000;
1662
1763
  /** Default KV bucket name for handler metadata. */
1663
1764
  declare const DEFAULT_METADATA_BUCKET = "handler_registry";
1664
1765
  /** Default number of KV bucket replicas. */
@@ -1698,7 +1799,7 @@ declare enum JetstreamHeader {
1698
1799
  Error = "x-error"
1699
1800
  }
1700
1801
  declare enum JetstreamDlqHeader {
1701
- /** Reason for the message being sent to the DLQ (error message or 'max_deliver_exceeded') */
1802
+ /** Reason for the message being sent to the DLQ — the last handler error message. */
1702
1803
  DeadLetterReason = "x-dead-letter-reason",
1703
1804
  /** Original NATS subject the message was originally published to */
1704
1805
  OriginalSubject = "x-original-subject",
@@ -1709,6 +1810,8 @@ declare enum JetstreamDlqHeader {
1709
1810
  /** Number of times the message has been delivered */
1710
1811
  DeliveryCount = "x-delivery-count"
1711
1812
  }
1813
+ /** Set of header names that are reserved and cannot be set by users. */
1814
+ declare const RESERVED_HEADERS: Set<string>;
1712
1815
  /**
1713
1816
  * Build the internal service name with microservice suffix.
1714
1817
  *
@@ -1770,4 +1873,4 @@ declare const isJetStreamRpcMode: (rpc: RpcConfig | undefined) => boolean;
1770
1873
  /** Check if the RPC config specifies Core mode (default). */
1771
1874
  declare const isCoreRpcMode: (rpc: RpcConfig | undefined) => boolean;
1772
1875
 
1773
- export { type Codec, DEFAULT_METADATA_BUCKET, DEFAULT_METADATA_HISTORY, DEFAULT_METADATA_REPLICAS, DEFAULT_METADATA_TTL, type DeadLetterInfo, EventBus, JETSTREAM_CODEC, JETSTREAM_CONNECTION, JETSTREAM_EVENT_BUS, JETSTREAM_OPTIONS, JetstreamClient, JetstreamDlqHeader, type JetstreamFeatureOptions, JetstreamHeader, JetstreamHealthIndicator, type JetstreamHealthStatus, JetstreamModule, type JetstreamModuleAsyncOptions, type JetstreamModuleOptions, JetstreamRecord, JetstreamRecordBuilder, JetstreamStrategy, JsonCodec, MIN_METADATA_TTL, MessageKind, type MetadataRegistryOptions, type OrderedEventOverrides, PatternPrefix, type RpcConfig, RpcContext, type ScheduleRecordOptions, type StreamConfigOverrides, type StreamConsumerOverrides, StreamKind, TransportEvent, type TransportHooks, buildBroadcastSubject, buildSubject, consumerName, dlqStreamName, getClientToken, internalName, isCoreRpcMode, isJetStreamRpcMode, metadataKey, streamName, toNanos };
1876
+ export { type Codec, DEFAULT_BROADCAST_CONSUMER_CONFIG, DEFAULT_BROADCAST_STREAM_CONFIG, DEFAULT_COMMAND_CONSUMER_CONFIG, DEFAULT_COMMAND_STREAM_CONFIG, DEFAULT_DLQ_STREAM_CONFIG, DEFAULT_EVENT_CONSUMER_CONFIG, DEFAULT_EVENT_STREAM_CONFIG, DEFAULT_JETSTREAM_RPC_TIMEOUT, DEFAULT_METADATA_BUCKET, DEFAULT_METADATA_HISTORY, DEFAULT_METADATA_REPLICAS, DEFAULT_METADATA_TTL, DEFAULT_ORDERED_STREAM_CONFIG, DEFAULT_RPC_TIMEOUT, DEFAULT_SHUTDOWN_TIMEOUT, type DeadLetterInfo, JETSTREAM_CODEC, JETSTREAM_CONNECTION, JETSTREAM_OPTIONS, JetstreamClient, JetstreamDlqHeader, type JetstreamFeatureOptions, JetstreamHeader, JetstreamHealthIndicator, type JetstreamHealthStatus, JetstreamModule, type JetstreamModuleAsyncOptions, type JetstreamModuleOptions, JetstreamRecord, JetstreamRecordBuilder, JetstreamStrategy, JsonCodec, MIN_METADATA_TTL, MessageKind, type MetadataRegistryOptions, MsgpackCodec, NatsErrorCode, type OrderedEventOverrides, PatternPrefix, RESERVED_HEADERS, type RpcConfig, RpcContext, type ScheduleRecordOptions, type StreamConfigOverrides, type StreamConsumerOverrides, StreamKind, TransportEvent, type TransportHooks, buildBroadcastSubject, buildSubject, consumerName, dlqStreamName, getClientToken, internalName, isCoreRpcMode, isJetStreamRpcMode, metadataKey, streamName, toNanos };
package/dist/index.d.ts CHANGED
@@ -525,6 +525,13 @@ declare class EventBus {
525
525
  * Avoids rest/spread overhead of the generic `emit()`.
526
526
  */
527
527
  emitMessageRouted(subject: string, kind: MessageKind): void;
528
+ /**
529
+ * Check whether a hook is registered for the given event.
530
+ *
531
+ * Used by the routing hot path to elide the emit call entirely when the
532
+ * transport owner did not register a listener.
533
+ */
534
+ hasHook(event: keyof TransportHooks): boolean;
528
535
  private callHook;
529
536
  }
530
537
 
@@ -764,20 +771,10 @@ declare class EventRouter {
764
771
  start(): void;
765
772
  /** Stop routing and unsubscribe from all streams. */
766
773
  destroy(): void;
767
- /** Subscribe to a message stream and route each message. */
774
+ /** Subscribe to a message stream and route each message to its handler. */
768
775
  private subscribeToStream;
769
776
  private getConcurrency;
770
777
  private getAckExtensionConfig;
771
- /** Handle a single event message with error isolation. */
772
- private handleSafe;
773
- /** Handle an ordered message with error isolation. */
774
- private handleOrderedSafe;
775
- /** Resolve handler, decode payload, and build context. Returns null on failure. */
776
- private decodeMessage;
777
- /** Execute handler, then ack on success or nak/dead-letter on failure. */
778
- private executeHandler;
779
- /** Check if the message has exhausted all delivery attempts. */
780
- private isDeadLetter;
781
778
  /** Handle a dead letter: invoke callback, then term or nak based on result. */
782
779
  /**
783
780
  * Fallback execution for a dead letter when DLQ is disabled, or when
@@ -839,10 +836,6 @@ declare class RpcRouter {
839
836
  start(): Promise<void>;
840
837
  /** Stop routing and unsubscribe. */
841
838
  destroy(): void;
842
- /** Handle a single RPC command message with error isolation. */
843
- private handleSafe;
844
- /** Execute handler, publish response, settle message. */
845
- private executeHandler;
846
839
  }
847
840
 
848
841
  /**
@@ -978,7 +971,7 @@ declare class MessageProvider {
978
971
  private createOrderedFlow;
979
972
  /** Shared self-healing flow: defer -> retry with exponential backoff on error/completion. */
980
973
  private createSelfHealingFlow;
981
- /** Single iteration: create ordered consumer -> iterate messages. */
974
+ /** Single iteration: create ordered consumer -> push messages into the subject. */
982
975
  private consumeOrderedOnce;
983
976
  }
984
977
 
@@ -1033,6 +1026,21 @@ declare class MetadataProvider {
1033
1026
  private openBucket;
1034
1027
  }
1035
1028
 
1029
+ /**
1030
+ * NATS JetStream API error codes used by the transport.
1031
+ *
1032
+ * Ref: https://github.com/nats-io/nats-server (server error definitions)
1033
+ * Verified on NATS 2.12.6 via integration tests (2026-04-02).
1034
+ */
1035
+ declare enum NatsErrorCode {
1036
+ /** Consumer does not exist on the specified stream. */
1037
+ ConsumerNotFound = 10014,
1038
+ /** Consumer name already in use with different configuration (race condition on create). */
1039
+ ConsumerAlreadyExists = 10148,
1040
+ /** Stream does not exist. */
1041
+ StreamNotFound = 10059
1042
+ }
1043
+
1036
1044
  /**
1037
1045
  * NestJS custom transport strategy for NATS JetStream.
1038
1046
  *
@@ -1227,6 +1235,21 @@ declare class JetstreamClient extends ClientProxy {
1227
1235
  private readonly targetName;
1228
1236
  /** Pre-cached caller name derived from rootOptions.name, computed once in constructor. */
1229
1237
  private readonly callerName;
1238
+ /**
1239
+ * Subject prefixes of the form `{serviceName}__microservice.{kind}.` — one
1240
+ * per stream kind this client may publish to. Built once in the constructor
1241
+ * so producing a full subject is a single string concat with the user pattern.
1242
+ */
1243
+ private readonly eventSubjectPrefix;
1244
+ private readonly commandSubjectPrefix;
1245
+ private readonly orderedSubjectPrefix;
1246
+ /**
1247
+ * RPC configuration snapshots. The values are derived from rootOptions at
1248
+ * construction time so the publish hot path never has to re-run
1249
+ * isCoreRpcMode / getRpcTimeout on every call.
1250
+ */
1251
+ private readonly isCoreMode;
1252
+ private readonly defaultRpcTimeout;
1230
1253
  /** Shared inbox for JetStream-mode RPC responses. */
1231
1254
  private inbox;
1232
1255
  private inboxSubscription;
@@ -1236,6 +1259,12 @@ declare class JetstreamClient extends ClientProxy {
1236
1259
  private readonly pendingTimeouts;
1237
1260
  /** Subscription to connection status events for disconnect handling. */
1238
1261
  private statusSubscription;
1262
+ /**
1263
+ * Cached readiness flag. Once `connect()` has wired the inbox and status
1264
+ * subscription, subsequent publishes skip the `await connect()` microtask
1265
+ * and reach for the underlying connection synchronously instead.
1266
+ */
1267
+ private readyForPublish;
1239
1268
  constructor(rootOptions: JetstreamModuleOptions, targetServiceName: string, connection: ConnectionProvider, codec: Codec, eventBus: EventBus);
1240
1269
  /**
1241
1270
  * Establish connection. Called automatically by NestJS on first use.
@@ -1282,7 +1311,14 @@ declare class JetstreamClient extends ClientProxy {
1282
1311
  private setupInbox;
1283
1312
  /** Route an inbox reply to the matching pending callback. */
1284
1313
  private routeInboxReply;
1285
- /** Build event subject — workqueue, broadcast, or ordered. */
1314
+ /**
1315
+ * Resolve a user pattern to a fully-qualified NATS subject, dispatching
1316
+ * between the event, broadcast, and ordered prefixes.
1317
+ *
1318
+ * The leading-char check short-circuits the `startsWith` comparisons for
1319
+ * patterns that cannot possibly carry a broadcast/ordered marker, which is
1320
+ * the overwhelmingly common case.
1321
+ */
1286
1322
  private buildEventSubject;
1287
1323
  /** Build NATS headers merging custom headers with transport headers. */
1288
1324
  private buildHeaders;
@@ -1300,7 +1336,6 @@ declare class JetstreamClient extends ClientProxy {
1300
1336
  * - `broadcast.config.updated` → `broadcast._sch.config.updated`
1301
1337
  */
1302
1338
  private buildScheduleSubject;
1303
- private getRpcTimeout;
1304
1339
  }
1305
1340
 
1306
1341
  /**
@@ -1469,6 +1504,52 @@ declare class JsonCodec implements Codec {
1469
1504
  decode(data: Uint8Array): unknown;
1470
1505
  }
1471
1506
 
1507
+ /**
1508
+ * Minimal shape of a `msgpackr` `Packr` instance used by {@link MsgpackCodec}.
1509
+ *
1510
+ * Typed locally so consumers who do not use MessagePack encoding never pay
1511
+ * for a `msgpackr` import.
1512
+ */
1513
+ interface PackrLike {
1514
+ pack(data: unknown): Uint8Array;
1515
+ unpack(data: Uint8Array): unknown;
1516
+ }
1517
+ /**
1518
+ * MessagePack codec backed by a caller-provided `msgpackr` `Packr` instance.
1519
+ *
1520
+ * Use this codec when publishing structured payloads larger than roughly
1521
+ * 1–2 KB — below that size the default {@link JsonCodec} wins on per-call
1522
+ * constant overhead. Above it, MessagePack encodes and decodes several times
1523
+ * faster and produces smaller wire frames. The format is cross-language, so
1524
+ * Node producers and non-Node consumers (Python, Go, Java, Rust, ...) stay
1525
+ * interoperable.
1526
+ *
1527
+ * Requires installing the optional `msgpackr` peer dependency:
1528
+ *
1529
+ * ```bash
1530
+ * npm install msgpackr
1531
+ * # or: pnpm add msgpackr
1532
+ * ```
1533
+ *
1534
+ * @example
1535
+ * ```typescript
1536
+ * import { JetstreamModule, MsgpackCodec } from '@horizon-republic/nestjs-jetstream';
1537
+ * import { Packr } from 'msgpackr';
1538
+ *
1539
+ * JetstreamModule.forRoot({
1540
+ * name: 'orders',
1541
+ * servers: ['nats://localhost:4222'],
1542
+ * codec: new MsgpackCodec(new Packr()),
1543
+ * });
1544
+ * ```
1545
+ */
1546
+ declare class MsgpackCodec implements Codec {
1547
+ private readonly packr;
1548
+ constructor(packr: PackrLike);
1549
+ encode(data: unknown): Uint8Array;
1550
+ decode(data: Uint8Array): unknown;
1551
+ }
1552
+
1472
1553
  type NatsMessage = JsMsg | Msg;
1473
1554
  /**
1474
1555
  * Execution context for RPC and event handlers.
@@ -1625,8 +1706,6 @@ declare const JETSTREAM_OPTIONS: unique symbol;
1625
1706
  declare const JETSTREAM_CONNECTION: unique symbol;
1626
1707
  /** Token for the global Codec instance. */
1627
1708
  declare const JETSTREAM_CODEC: unique symbol;
1628
- /** Token for the EventBus instance. */
1629
- declare const JETSTREAM_EVENT_BUS: unique symbol;
1630
1709
  /**
1631
1710
  * Generate the injection token for a `forFeature()` client.
1632
1711
  *
@@ -1659,6 +1738,28 @@ type TimeUnit = 'ms' | 'seconds' | 'minutes' | 'hours' | 'days';
1659
1738
  * ```
1660
1739
  */
1661
1740
  declare const toNanos: (value: number, unit: TimeUnit) => number;
1741
+ /** Default config for workqueue event streams. */
1742
+ declare const DEFAULT_EVENT_STREAM_CONFIG: Partial<StreamConfig>;
1743
+ /** Default config for RPC command streams (jetstream mode only). */
1744
+ declare const DEFAULT_COMMAND_STREAM_CONFIG: Partial<StreamConfig>;
1745
+ /** Default config for broadcast event streams. */
1746
+ declare const DEFAULT_BROADCAST_STREAM_CONFIG: Partial<StreamConfig>;
1747
+ /** Default config for ordered event streams (Limits retention). */
1748
+ declare const DEFAULT_ORDERED_STREAM_CONFIG: Partial<StreamConfig>;
1749
+ /** Default config for dead-letter queue (DLQ) streams. */
1750
+ declare const DEFAULT_DLQ_STREAM_CONFIG: Partial<StreamConfig>;
1751
+ /** Default config for workqueue event consumers. */
1752
+ declare const DEFAULT_EVENT_CONSUMER_CONFIG: Partial<ConsumerConfig>;
1753
+ /** Default config for RPC command consumers (jetstream mode only). */
1754
+ declare const DEFAULT_COMMAND_CONSUMER_CONFIG: Partial<ConsumerConfig>;
1755
+ /** Default config for broadcast event consumers. */
1756
+ declare const DEFAULT_BROADCAST_CONSUMER_CONFIG: Partial<ConsumerConfig>;
1757
+ /** Default RPC timeout for Core mode (30 seconds). */
1758
+ declare const DEFAULT_RPC_TIMEOUT = 30000;
1759
+ /** Default RPC timeout for JetStream mode (3 minutes). */
1760
+ declare const DEFAULT_JETSTREAM_RPC_TIMEOUT = 180000;
1761
+ /** Default graceful shutdown timeout (10 seconds). */
1762
+ declare const DEFAULT_SHUTDOWN_TIMEOUT = 10000;
1662
1763
  /** Default KV bucket name for handler metadata. */
1663
1764
  declare const DEFAULT_METADATA_BUCKET = "handler_registry";
1664
1765
  /** Default number of KV bucket replicas. */
@@ -1698,7 +1799,7 @@ declare enum JetstreamHeader {
1698
1799
  Error = "x-error"
1699
1800
  }
1700
1801
  declare enum JetstreamDlqHeader {
1701
- /** Reason for the message being sent to the DLQ (error message or 'max_deliver_exceeded') */
1802
+ /** Reason for the message being sent to the DLQ — the last handler error message. */
1702
1803
  DeadLetterReason = "x-dead-letter-reason",
1703
1804
  /** Original NATS subject the message was originally published to */
1704
1805
  OriginalSubject = "x-original-subject",
@@ -1709,6 +1810,8 @@ declare enum JetstreamDlqHeader {
1709
1810
  /** Number of times the message has been delivered */
1710
1811
  DeliveryCount = "x-delivery-count"
1711
1812
  }
1813
+ /** Set of header names that are reserved and cannot be set by users. */
1814
+ declare const RESERVED_HEADERS: Set<string>;
1712
1815
  /**
1713
1816
  * Build the internal service name with microservice suffix.
1714
1817
  *
@@ -1770,4 +1873,4 @@ declare const isJetStreamRpcMode: (rpc: RpcConfig | undefined) => boolean;
1770
1873
  /** Check if the RPC config specifies Core mode (default). */
1771
1874
  declare const isCoreRpcMode: (rpc: RpcConfig | undefined) => boolean;
1772
1875
 
1773
- export { type Codec, DEFAULT_METADATA_BUCKET, DEFAULT_METADATA_HISTORY, DEFAULT_METADATA_REPLICAS, DEFAULT_METADATA_TTL, type DeadLetterInfo, EventBus, JETSTREAM_CODEC, JETSTREAM_CONNECTION, JETSTREAM_EVENT_BUS, JETSTREAM_OPTIONS, JetstreamClient, JetstreamDlqHeader, type JetstreamFeatureOptions, JetstreamHeader, JetstreamHealthIndicator, type JetstreamHealthStatus, JetstreamModule, type JetstreamModuleAsyncOptions, type JetstreamModuleOptions, JetstreamRecord, JetstreamRecordBuilder, JetstreamStrategy, JsonCodec, MIN_METADATA_TTL, MessageKind, type MetadataRegistryOptions, type OrderedEventOverrides, PatternPrefix, type RpcConfig, RpcContext, type ScheduleRecordOptions, type StreamConfigOverrides, type StreamConsumerOverrides, StreamKind, TransportEvent, type TransportHooks, buildBroadcastSubject, buildSubject, consumerName, dlqStreamName, getClientToken, internalName, isCoreRpcMode, isJetStreamRpcMode, metadataKey, streamName, toNanos };
1876
+ export { type Codec, DEFAULT_BROADCAST_CONSUMER_CONFIG, DEFAULT_BROADCAST_STREAM_CONFIG, DEFAULT_COMMAND_CONSUMER_CONFIG, DEFAULT_COMMAND_STREAM_CONFIG, DEFAULT_DLQ_STREAM_CONFIG, DEFAULT_EVENT_CONSUMER_CONFIG, DEFAULT_EVENT_STREAM_CONFIG, DEFAULT_JETSTREAM_RPC_TIMEOUT, DEFAULT_METADATA_BUCKET, DEFAULT_METADATA_HISTORY, DEFAULT_METADATA_REPLICAS, DEFAULT_METADATA_TTL, DEFAULT_ORDERED_STREAM_CONFIG, DEFAULT_RPC_TIMEOUT, DEFAULT_SHUTDOWN_TIMEOUT, type DeadLetterInfo, JETSTREAM_CODEC, JETSTREAM_CONNECTION, JETSTREAM_OPTIONS, JetstreamClient, JetstreamDlqHeader, type JetstreamFeatureOptions, JetstreamHeader, JetstreamHealthIndicator, type JetstreamHealthStatus, JetstreamModule, type JetstreamModuleAsyncOptions, type JetstreamModuleOptions, JetstreamRecord, JetstreamRecordBuilder, JetstreamStrategy, JsonCodec, MIN_METADATA_TTL, MessageKind, type MetadataRegistryOptions, MsgpackCodec, NatsErrorCode, type OrderedEventOverrides, PatternPrefix, RESERVED_HEADERS, type RpcConfig, RpcContext, type ScheduleRecordOptions, type StreamConfigOverrides, type StreamConsumerOverrides, StreamKind, TransportEvent, type TransportHooks, buildBroadcastSubject, buildSubject, consumerName, dlqStreamName, getClientToken, internalName, isCoreRpcMode, isJetStreamRpcMode, metadataKey, streamName, toNanos };