@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/README.md +15 -2
- package/dist/index.cjs +544 -212
- package/dist/index.d.cts +125 -22
- package/dist/index.d.ts +125 -22
- package/dist/index.js +526 -206
- package/package.json +22 -7
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 ->
|
|
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
|
-
/**
|
|
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
|
|
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,
|
|
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 ->
|
|
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
|
-
/**
|
|
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
|
|
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,
|
|
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 };
|