@horizon-republic/nestjs-jetstream 2.8.0 → 2.9.1

package/dist/index.d.ts

@@ -117,6 +117,14 @@ interface JetstreamHealthStatus {
     latency: number | null;
 }
 
+/**
+ * Stream config overrides exposed to users.
+ *
+ * `retention` is excluded because it is controlled by the transport layer
+ * (Workqueue for events/commands, Limits for broadcast/ordered).
+ * Any `retention` value provided at runtime is silently stripped.
+ */
+type StreamConfigOverrides = Partial<Omit<StreamConfig, 'retention'>>;
 /**
  * RPC transport configuration.
  *
@@ -136,7 +144,7 @@ type RpcConfig = {
     /** Handler timeout in ms. Default: 180_000 (3 min). */
     timeout?: number;
     /** Raw NATS StreamConfig overrides for the command stream. */
-    stream?: Partial<StreamConfig>;
+    stream?: StreamConfigOverrides;
     /** Raw NATS ConsumerConfig overrides for the command consumer. */
     consumer?: Partial<ConsumerConfig>;
     /** Options passed to the nats.js `consumer.consume()` call for the command consumer. */
@@ -151,7 +159,7 @@ type RpcConfig = {
 };
 /** Overrides for JetStream stream and consumer configuration. */
 interface StreamConsumerOverrides {
-    stream?: Partial<StreamConfig>;
+    stream?: StreamConfigOverrides;
     consumer?: Partial<ConsumerConfig>;
     /**
      * Options passed to the nats.js `consumer.consume()` call.
@@ -195,7 +203,7 @@ interface StreamConsumerOverrides {
  */
 interface OrderedEventOverrides {
     /** Stream overrides (e.g. `max_age`, `max_bytes`). */
-    stream?: Partial<StreamConfig>;
+    stream?: StreamConfigOverrides;
     /**
      * Where to start reading when the consumer is (re)created.
      * @default DeliverPolicy.All
@@ -215,6 +223,38 @@ interface OrderedEventOverrides {
      */
     replayPolicy?: ReplayPolicy;
 }
+/**
+ * Configuration for the handler metadata KV registry.
+ *
+ * When any handler has `meta` in its extras, the transport writes metadata
+ * entries to a NATS KV bucket at startup. External services (API gateways,
+ * dashboards) can watch the bucket for service discovery.
+ *
+ * All fields are optional — sensible defaults are applied.
+ */
+interface MetadataRegistryOptions {
+    /**
+     * KV bucket name.
+     * @default 'handler_registry'
+     */
+    bucket?: string;
+    /**
+     * Number of KV bucket replicas. Must be an odd number (1, 3, 5, 7, ...).
+     * Requires a NATS cluster with at least this many nodes.
+     * @default 1
+     */
+    replicas?: number;
+    /**
+     * KV bucket TTL in milliseconds.
+     *
+     * Entries expire automatically unless refreshed by a heartbeat.
+     * The transport refreshes entries every `ttl / 2` while the pod is alive.
+     * When the pod stops (graceful or crash), entries expire after this duration.
+     *
+     * @default 30_000 (30 seconds)
+     */
+    ttl?: number;
+}
 /**
  * Root module configuration for `JetstreamModule.forRoot()`.
  *
@@ -283,12 +323,62 @@ interface JetstreamModuleOptions {
      * ```
      */
     onDeadLetter?(info: DeadLetterInfo): Promise<void>;
+    /**
+     * Dead-letter queue (DLQ) configuration.
+     * DLQ is a separate stream used to store messages that have exhausted all delivery attempts.
+     * @example
+     * ```typescript
+     * JetstreamModule.forRootAsync({
+     *   name: 'my-service',
+     *   servers: ['nats://localhost:4222'],
+     *   dlq: {
+     *     stream: {
+     *       max_age: toNanos(30, 'days'),
+     *     },
+     *   },
+     * })
+     * ```
+     */
+    dlq?: {
+        stream?: StreamConfigOverrides;
+    };
     /**
      * Graceful shutdown timeout in ms.
      * Handlers exceeding this are abandoned.
      * @default 10_000
      */
     shutdownTimeout?: number;
+    /**
+     * Allow destructive stream migration when immutable config changes are detected.
+     *
+     * When `true`, the transport will recreate streams (via blue-green sourcing)
+     * if immutable properties like `storage` differ from the running stream.
+     * Messages are preserved during migration.
+     *
+     * `retention` is NOT migratable — it is controlled by the transport
+     * (Workqueue for events, Limits for broadcast/ordered) and a mismatch
+     * is always treated as an error regardless of this flag.
+     *
+     * When `false` (default), immutable conflicts are logged as warnings and
+     * the stream continues with its existing configuration.
+     *
+     * @default false
+     */
+    allowDestructiveMigration?: boolean;
+    /**
+     * Handler metadata KV registry configuration.
+     *
+     * When any handler has `meta` in its `@EventPattern` / `@MessagePattern` extras,
+     * the transport writes metadata to a NATS KV bucket at startup.
+     * External services (API gateways, dashboards, CLI tools) can read or watch
+     * the bucket for dynamic service discovery.
+     *
+     * Auto-enabled when any handler has `meta`. Set to customize bucket name,
+     * replicas, or TTL.
+     *
+     * @see MetadataRegistryOptions
+     */
+    metadata?: MetadataRegistryOptions;
     /**
      * Raw NATS ConnectionOptions pass-through for advanced connection config.
      * Allows setting tls, auth, reconnect behavior, maxReconnectAttempts, etc.
@@ -435,6 +525,13 @@ declare class EventBus {
      * Avoids rest/spread overhead of the generic `emit()`.
      */
     emitMessageRouted(subject: string, kind: MessageKind): void;
+    /**
+     * Check whether a hook is registered for the given event.
+     *
+     * Used by the routing hot path to elide the emit call entirely when the
+     * transport owner did not register a listener.
+     */
+    hasHook(event: keyof TransportHooks): boolean;
     private callHook;
 }
 
@@ -516,6 +613,7 @@ declare class PatternRegistry {
     private _hasCommands;
     private _hasBroadcasts;
     private _hasOrdered;
+    private _hasMetadata;
     constructor(options: JetstreamModuleOptions);
     /**
      * Register all handlers from the NestJS strategy.
@@ -533,11 +631,21 @@ declare class PatternRegistry {
     hasOrderedHandlers(): boolean;
     /** Get fully-qualified NATS subjects for ordered handlers. */
     getOrderedSubjects(): string[];
+    /** Check if any registered handler has metadata. */
+    hasMetadata(): boolean;
+    /**
+     * Get handler metadata entries for KV publishing.
+     *
+     * Returns a map of KV key -> metadata object for all handlers that have `meta`.
+     * Key format: `{serviceName}.{kind}.{pattern}`.
+     */
+    getMetadataEntries(): Map<string, Record<string, unknown>>;
     /** Get patterns grouped by kind (cached after registration). */
     getPatternsByKind(): PatternsByKind;
     /** Normalize a full NATS subject back to the user-facing pattern. */
     normalizeSubject(subject: string): string;
     private buildPatternsByKind;
+    private resolveStreamKind;
     private logSummary;
 }
 
@@ -582,12 +690,14 @@ declare class StreamProvider {
     private readonly options;
     private readonly connection;
     private readonly logger;
+    private readonly migration;
     constructor(options: JetstreamModuleOptions, connection: ConnectionProvider);
     /**
      * Ensure all required streams exist with correct configuration.
      *
      * @param kinds Which stream kinds to create. Determined by the module based
      *              on RPC mode and registered handler patterns.
+     * If the dlq option is enabled, also ensures the DLQ stream exists.
      */
     ensureStreams(kinds: StreamKind[]): Promise<void>;
     /** Get the stream name for a given kind. */
@@ -596,14 +706,32 @@ declare class StreamProvider {
     getSubjects(kind: StreamKind): string[];
     /** Ensure a single stream exists, creating or updating as needed. */
     private ensureStream;
+    /** Ensure a dead-letter queue stream exists, creating or updating as needed. */
+    private ensureDlqStream;
+    private handleExistingStream;
+    private buildMutableOnlyConfig;
+    private logChanges;
     /** Build the full stream config by merging defaults with user overrides. */
     private buildConfig;
+    /**
+     * Build the stream configuration for the Dead-Letter Queue (DLQ).
+     *
+     * Merges the library default DLQ config with user-provided overrides.
+     * Ensures transport-controlled settings like retention are safely decoupled.
+     */
+    private buildDlqConfig;
     /** Get default config for a stream kind. */
     private getDefaults;
     /** Check if scheduling is enabled for a stream kind via `allow_msg_schedules` override. */
     private isSchedulingEnabled;
-    /** Get user-provided overrides for a stream kind. */
+    /** Get user-provided overrides for a stream kind, stripping transport-controlled properties. */
     private getOverrides;
+    /**
+     * Remove transport-controlled properties from user overrides.
+     * `retention` is managed by the transport (Workqueue/Limits per stream kind)
+     * and silently stripped to protect users from misconfiguration.
+     */
+    private stripTransportControlled;
 }
 
 /**
@@ -615,6 +743,11 @@ declare class StreamProvider {
  * **Ordered** — strict sequential delivery:
  * - No ack/nak/DLQ — nats.js auto-acknowledges ordered consumer messages.
  * - Handler errors are logged but do not affect delivery.
+ *
+ * **Dead-Letter Queue (DLQ) - for handling failed message deliveries**
+ * - If `options.dlq` is configured, messages that exhaust their max delivery attempts are published to a DLQ stream.
+ * - The DLQ stream name is derived from the service name (e.g., `orders__microservice_dlq-stream`).
+ * - Original message data and metadata are preserved in the DLQ message, with additional headers indicating the reason for failure.
  */
 declare class EventRouter {
     private readonly messageProvider;
@@ -624,9 +757,11 @@ declare class EventRouter {
     private readonly deadLetterConfig?;
     private readonly processingConfig?;
     private readonly ackWaitMap?;
+    private readonly connection?;
+    private readonly options?;
     private readonly logger;
     private readonly subscriptions;
-    constructor(messageProvider: MessageProvider, patternRegistry: PatternRegistry, codec: Codec, eventBus: EventBus, deadLetterConfig?: DeadLetterConfig | undefined, processingConfig?: EventProcessingConfig | undefined, ackWaitMap?: Map<StreamKind, number> | undefined);
+    constructor(messageProvider: MessageProvider, patternRegistry: PatternRegistry, codec: Codec, eventBus: EventBus, deadLetterConfig?: DeadLetterConfig | undefined, processingConfig?: EventProcessingConfig | undefined, ackWaitMap?: Map<StreamKind, number> | undefined, connection?: ConnectionProvider | undefined, options?: JetstreamModuleOptions | undefined);
     /**
      * Update the max_deliver thresholds from actual NATS consumer configs.
      * Called after consumers are ensured so the DLQ map reflects reality.
@@ -636,21 +771,35 @@ declare class EventRouter {
     start(): void;
     /** Stop routing and unsubscribe from all streams. */
     destroy(): void;
-    /** Subscribe to a message stream and route each message. */
+    /** Subscribe to a message stream and route each message to its handler. */
     private subscribeToStream;
     private getConcurrency;
     private getAckExtensionConfig;
-    /** Handle a single event message with error isolation. */
-    private handleSafe;
-    /** Handle an ordered message with error isolation. */
-    private handleOrderedSafe;
-    /** Resolve handler, decode payload, and build context. Returns null on failure. */
-    private decodeMessage;
-    /** Execute handler, then ack on success or nak/dead-letter on failure. */
-    private executeHandler;
-    /** Check if the message has exhausted all delivery attempts. */
-    private isDeadLetter;
     /** Handle a dead letter: invoke callback, then term or nak based on result. */
+    /**
+     * Fallback execution for a dead letter when DLQ is disabled, or when
+     * publishing to the DLQ stream fails (due to network or NATS errors).
+     *
+     * Triggers the user-provided `onDeadLetter` hook for logging/alerting.
+     * On success, terminates the message. On error, leaves it unacknowledged (nak)
+     * so NATS can retry the delivery on the next cycle.
+     */
+    private fallbackToOnDeadLetterCallback;
+    /**
+     * Publish a dead letter to the configured Dead-Letter Queue (DLQ) stream.
+     *
+     * Appends diagnostic metadata headers to the original message and preserves
+     * the primary payload. If publishing succeeds, it notifies the standard
+     * `onDeadLetter` callback and terminates the message. If it fails, it falls
+     * back to the callback entirely to prevent silent data loss.
+     */
+    private publishToDlq;
+    /**
+     * Orchestrates the handling of a message that has exhausted delivery limits.
+     *
+     * Emits a system event and delegates either to the robust DLQ stream publisher
+     * or directly to the fallback callback based on the active module configuration.
+     */
     private handleDeadLetter;
 }
 
@@ -687,10 +836,6 @@ declare class RpcRouter {
     start(): Promise<void>;
     /** Stop routing and unsubscribe. */
     destroy(): void;
-    /** Handle a single RPC command message with error isolation. */
-    private handleSafe;
-    /** Execute handler, publish response, settle message. */
-    private executeHandler;
 }
 
 /**
@@ -714,8 +859,36 @@ declare class ConsumerProvider {
     ensureConsumers(kinds: StreamKind[]): Promise<Map<StreamKind, ConsumerInfo>>;
     /** Get the consumer name for a given kind. */
     getConsumerName(kind: StreamKind): string;
-    /** Ensure a single consumer exists, creating if needed. */
-    private ensureConsumer;
+    /**
+     * Ensure a single consumer exists with the desired config.
+     * Used at **startup** — creates or updates the consumer to match
+     * the current pod's configuration.
+     */
+    ensureConsumer(jsm: Awaited<ReturnType<ConnectionProvider['getJetStreamManager']>>, kind: StreamKind): Promise<ConsumerInfo>;
+    /**
+     * Recover a consumer that disappeared during runtime.
+     * Used by **self-healing** — creates if missing, but NEVER updates config.
+     *
+     * If a migration backup stream exists, another pod is mid-migration — we
+     * throw so the self-healing retry loop waits with backoff until migration
+     * completes and the backup is cleaned up.
+     *
+     * This prevents old pods from:
+     * - Overwriting a newer pod's consumer config during rolling updates
+     * - Creating consumers during migration (which would consume and delete
+     *   workqueue messages while they're being restored)
+     */
+    recoverConsumer(jsm: Awaited<ReturnType<ConnectionProvider['getJetStreamManager']>>, kind: StreamKind): Promise<ConsumerInfo>;
+    /**
+     * Throw if a migration backup stream exists for this stream.
+     * The self-healing retry loop catches the error and retries with backoff,
+     * naturally waiting until the migrating pod finishes and cleans up the backup.
+     */
+    private assertNoMigrationInProgress;
+    /**
+     * Create a consumer, handling the race where another pod creates it first.
+     */
+    private createConsumer;
     /** Build consumer config by merging defaults with user overrides. */
     private buildConfig;
     /** Get default config for a consumer kind. */
@@ -724,6 +897,8 @@ declare class ConsumerProvider {
     private getOverrides;
 }
 
+/** Callback to recreate a consumer when it disappears. */
+type ConsumerRecoveryFn = (kind: StreamKind) => Promise<ConsumerInfo>;
 /**
  * Manages pull-based message consumption from JetStream consumers.
  *
@@ -737,6 +912,7 @@ declare class MessageProvider {
     private readonly connection;
     private readonly eventBus;
     private readonly consumeOptionsMap;
+    private readonly consumerRecoveryFn?;
     private readonly logger;
     private readonly activeIterators;
     private orderedReadyResolve;
@@ -746,7 +922,7 @@ declare class MessageProvider {
     private commandMessages$;
     private broadcastMessages$;
     private orderedMessages$;
-    constructor(connection: ConnectionProvider, eventBus: EventBus, consumeOptionsMap?: Map<StreamKind, Partial<ConsumeOptions>>);
+    constructor(connection: ConnectionProvider, eventBus: EventBus, consumeOptionsMap?: Map<StreamKind, Partial<ConsumeOptions>>, consumerRecoveryFn?: ConsumerRecoveryFn | undefined);
     /** Observable stream of workqueue event messages. */
     get events$(): Observable<JsMsg>;
     /** Observable stream of RPC command messages (jetstream mode). */
@@ -779,6 +955,14 @@ declare class MessageProvider {
     private createFlow;
     /** Single iteration: get consumer -> pull messages -> emit to subject. */
     private consumeOnce;
+    /**
+     * Detect "consumer not found" errors from `js.consumers.get()`.
+     *
+     * Unlike JetStream Manager calls (which throw `JetStreamApiError`),
+     * the JetStream client's `consumers.get()` throws a plain `Error`
+     * with the error code embedded in the message text.
+     */
+    private isConsumerNotFound;
     /** Get the target subject for a consumer kind. */
     private getTargetSubject;
     /** Monitor heartbeats and restart the consumer iterator on prolonged silence. */
@@ -787,10 +971,76 @@ declare class MessageProvider {
     private createOrderedFlow;
     /** Shared self-healing flow: defer -> retry with exponential backoff on error/completion. */
     private createSelfHealingFlow;
-    /** Single iteration: create ordered consumer -> iterate messages. */
+    /** Single iteration: create ordered consumer -> push messages into the subject. */
     private consumeOrderedOnce;
 }
 
+/**
+ * Publishes handler metadata to a NATS KV bucket for external service discovery.
+ *
+ * Uses TTL + heartbeat to manage entry lifecycle:
+ * - Entries are written on startup and refreshed every `ttl / 2`
+ * - When the pod stops (graceful or crash), heartbeat stops → entries expire via TTL
+ * - No explicit delete needed — NATS handles expiry automatically
+ *
+ * This provider is fully decoupled from stream/consumer infrastructure —
+ * it only depends on the NATS connection and module options.
+ */
+declare class MetadataProvider {
+    private readonly connection;
+    private readonly logger;
+    private readonly bucketName;
+    private readonly replicas;
+    private readonly ttl;
+    private currentEntries?;
+    private heartbeatTimer?;
+    private cachedKv?;
+    constructor(options: JetstreamModuleOptions, connection: ConnectionProvider);
+    /**
+     * Write handler metadata entries to the KV bucket and start heartbeat.
+     *
+     * Creates the bucket if it doesn't exist (idempotent).
+     * Skips silently when entries map is empty.
+     * Starts a heartbeat interval that refreshes entries every `ttl / 2`
+     * to prevent TTL expiry while the pod is alive.
+     *
+     * Non-critical — errors are logged but do not prevent transport startup.
+     *
+     * @param entries Map of KV key → metadata object.
+     */
+    publish(entries: Map<string, Record<string, unknown>>): Promise<void>;
+    /**
+     * Stop the heartbeat timer.
+     *
+     * After this call, entries will expire via TTL once the heartbeat window passes.
+     * Called during transport shutdown (strategy.close()).
+     */
+    destroy(): void;
+    /** Write entries to KV with per-entry error handling. */
+    private writeEntries;
+    /** Start heartbeat interval that refreshes entries every ttl/2. */
+    private startHeartbeat;
+    /** Refresh all current entries in KV (heartbeat tick). */
+    private refreshEntries;
+    /** Create or open the KV bucket (cached after first call). */
+    private openBucket;
+}
+
+/**
+ * NATS JetStream API error codes used by the transport.
+ *
+ * Ref: https://github.com/nats-io/nats-server (server error definitions)
+ * Verified on NATS 2.12.6 via integration tests (2026-04-02).
+ */
+declare enum NatsErrorCode {
+    /** Consumer does not exist on the specified stream. */
+    ConsumerNotFound = 10014,
+    /** Consumer name already in use with different configuration (race condition on create). */
+    ConsumerAlreadyExists = 10148,
+    /** Stream does not exist. */
+    StreamNotFound = 10059
+}
+
 /**
  * NestJS custom transport strategy for NATS JetStream.
  *
@@ -813,17 +1063,18 @@ declare class JetstreamStrategy extends Server implements CustomTransportStrateg
     private readonly rpcRouter;
     private readonly coreRpcServer;
     private readonly ackWaitMap;
+    private readonly metadataProvider?;
     readonly transportId: symbol;
     private readonly listeners;
     private started;
-    constructor(options: JetstreamModuleOptions, connection: ConnectionProvider, patternRegistry: PatternRegistry, streamProvider: StreamProvider, consumerProvider: ConsumerProvider, messageProvider: MessageProvider, eventRouter: EventRouter, rpcRouter: RpcRouter, coreRpcServer: CoreRpcServer, ackWaitMap?: Map<StreamKind, number>);
+    constructor(options: JetstreamModuleOptions, connection: ConnectionProvider, patternRegistry: PatternRegistry, streamProvider: StreamProvider, consumerProvider: ConsumerProvider, messageProvider: MessageProvider, eventRouter: EventRouter, rpcRouter: RpcRouter, coreRpcServer: CoreRpcServer, ackWaitMap?: Map<StreamKind, number>, metadataProvider?: MetadataProvider | undefined);
     /**
      * Start the transport: register handlers, create infrastructure, begin consumption.
      *
      * Called by NestJS when `connectMicroservice()` is used, or internally by the module.
      */
     listen(callback: () => void): Promise<void>;
-    /** Stop all consumers, routers, and subscriptions. Called during shutdown. */
+    /** Stop all consumers, routers, subscriptions, and metadata heartbeat. Called during shutdown. */
     close(): void;
     /**
      * Register event listener (required by Server base class).
@@ -858,22 +1109,30 @@ interface Stoppable {
  * Shutdown sequence:
  * 1. Emit onShutdownStart hook
  * 2. Stop accepting new messages (close subscriptions, stop consumers)
- * 3. Wait for in-flight handlers to complete (up to timeout)
- * 4. Drain and close NATS connection
- * 5. Emit onShutdownComplete hook
+ * 3. Drain and close NATS connection (with timeout safety net)
+ * 4. Emit onShutdownComplete hook
+ *
+ * Idempotent — concurrent or repeated calls return the same promise.
+ * This is critical because NestJS may call `onApplicationShutdown` on
+ * multiple module instances (forRoot + forFeature) that share this
+ * singleton, and the call order is not guaranteed.
  */
 declare class ShutdownManager {
     private readonly connection;
     private readonly eventBus;
     private readonly timeout;
     private readonly logger;
+    private shutdownPromise?;
     constructor(connection: ConnectionProvider, eventBus: EventBus, timeout: number);
     /**
      * Execute the full shutdown sequence.
      *
+     * Idempotent — concurrent or repeated calls return the same promise.
+     *
      * @param strategy Optional stoppable to close (stops consumers and subscriptions).
      */
     shutdown(strategy?: Stoppable): Promise<void>;
+    private doShutdown;
 }
 
 /**
@@ -976,6 +1235,21 @@ declare class JetstreamClient extends ClientProxy {
     private readonly targetName;
     /** Pre-cached caller name derived from rootOptions.name, computed once in constructor. */
     private readonly callerName;
+    /**
+     * Subject prefixes of the form `{serviceName}__microservice.{kind}.` — one
+     * per stream kind this client may publish to. Built once in the constructor
+     * so producing a full subject is a single string concat with the user pattern.
+     */
+    private readonly eventSubjectPrefix;
+    private readonly commandSubjectPrefix;
+    private readonly orderedSubjectPrefix;
+    /**
+     * RPC configuration snapshots. The values are derived from rootOptions at
+     * construction time so the publish hot path never has to re-run
+     * isCoreRpcMode / getRpcTimeout on every call.
+     */
+    private readonly isCoreMode;
+    private readonly defaultRpcTimeout;
     /** Shared inbox for JetStream-mode RPC responses. */
     private inbox;
     private inboxSubscription;
@@ -985,6 +1259,12 @@ declare class JetstreamClient extends ClientProxy {
     private readonly pendingTimeouts;
     /** Subscription to connection status events for disconnect handling. */
     private statusSubscription;
+    /**
+     * Cached readiness flag. Once `connect()` has wired the inbox and status
+     * subscription, subsequent publishes skip the `await connect()` microtask
+     * and reach for the underlying connection synchronously instead.
+     */
+    private readyForPublish;
     constructor(rootOptions: JetstreamModuleOptions, targetServiceName: string, connection: ConnectionProvider, codec: Codec, eventBus: EventBus);
     /**
      * Establish connection. Called automatically by NestJS on first use.
@@ -1031,7 +1311,14 @@ declare class JetstreamClient extends ClientProxy {
     private setupInbox;
     /** Route an inbox reply to the matching pending callback. */
     private routeInboxReply;
-    /** Build event subject — workqueue, broadcast, or ordered. */
+    /**
+     * Resolve a user pattern to a fully-qualified NATS subject, dispatching
+     * between the event, broadcast, and ordered prefixes.
+     *
+     * The leading-char check short-circuits the `startsWith` comparisons for
+     * patterns that cannot possibly carry a broadcast/ordered marker, which is
+     * the overwhelmingly common case.
+     */
     private buildEventSubject;
     /** Build NATS headers merging custom headers with transport headers. */
     private buildHeaders;
@@ -1049,7 +1336,6 @@ declare class JetstreamClient extends ClientProxy {
      * - `broadcast.config.updated` → `broadcast._sch.config.updated`
      */
     private buildScheduleSubject;
-    private getRpcTimeout;
 }
 
 /**
@@ -1079,6 +1365,8 @@ declare class JetstreamRecord<TData = unknown> {
     readonly messageId?: string | undefined;
     /** Schedule options for delayed delivery. */
     readonly schedule?: ScheduleRecordOptions | undefined;
+    /** Per-message TTL as Go duration string (e.g. "30s", "5m"). */
+    readonly ttl?: string | undefined;
     constructor(
     /** Message payload. */
     data: TData, 
@@ -1089,7 +1377,9 @@ declare class JetstreamRecord<TData = unknown> {
     /** Custom message ID for JetStream deduplication. */
     messageId?: string | undefined, 
     /** Schedule options for delayed delivery. */
-    schedule?: ScheduleRecordOptions | undefined);
+    schedule?: ScheduleRecordOptions | undefined, 
+    /** Per-message TTL as Go duration string (e.g. "30s", "5m"). */
+    ttl?: string | undefined);
 }
 /**
  * Fluent builder for constructing JetstreamRecord instances.
@@ -1103,6 +1393,7 @@ declare class JetstreamRecordBuilder<TData = unknown> {
     private timeout;
     private messageId;
     private scheduleOptions;
+    private ttlDuration;
     constructor(data?: TData);
     /**
      * Set the message payload.
@@ -1164,6 +1455,27 @@ declare class JetstreamRecordBuilder<TData = unknown> {
      * @throws Error if the date is not in the future.
      */
     scheduleAt(date: Date): this;
+    /**
+     * Set per-message TTL (time-to-live).
+     *
+     * The message expires individually after the specified duration,
+     * independent of the stream's `max_age`. Requires NATS >= 2.11 and
+     * `allow_msg_ttl: true` on the stream.
+     *
+     * Only meaningful for events (`client.emit()`). If used with RPC
+     * (`client.send()`), a warning is logged and the TTL is ignored.
+     *
+     * @param nanos - TTL in nanoseconds. Use {@link toNanos} for human-readable values.
+     *
+     * @example
+     * ```typescript
+     * import { toNanos } from '@horizon-republic/nestjs-jetstream';
+     *
+     * new JetstreamRecordBuilder(payload).ttl(toNanos(30, 'minutes')).build();
+     * new JetstreamRecordBuilder(payload).ttl(toNanos(24, 'hours')).build();
+     * ```
+     */
+    ttl(nanos: number): this;
     /**
      * Build the immutable {@link JetstreamRecord}.
      *
@@ -1192,6 +1504,52 @@ declare class JsonCodec implements Codec {
     decode(data: Uint8Array): unknown;
 }
 
+/**
+ * Minimal shape of a `msgpackr` `Packr` instance used by {@link MsgpackCodec}.
+ *
+ * Typed locally so consumers who do not use MessagePack encoding never pay
+ * for a `msgpackr` import.
+ */
+interface PackrLike {
+    pack(data: unknown): Uint8Array;
+    unpack(data: Uint8Array): unknown;
+}
+/**
+ * MessagePack codec backed by a caller-provided `msgpackr` `Packr` instance.
+ *
+ * Use this codec when publishing structured payloads larger than roughly
+ * 1–2 KB — below that size the default {@link JsonCodec} wins on per-call
+ * constant overhead. Above it, MessagePack encodes and decodes several times
+ * faster and produces smaller wire frames. The format is cross-language, so
+ * Node producers and non-Node consumers (Python, Go, Java, Rust, ...) stay
+ * interoperable.
+ *
+ * Requires installing the optional `msgpackr` peer dependency:
+ *
+ * ```bash
+ * npm install msgpackr
+ * # or: pnpm add msgpackr
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { JetstreamModule, MsgpackCodec } from '@horizon-republic/nestjs-jetstream';
+ * import { Packr } from 'msgpackr';
+ *
+ * JetstreamModule.forRoot({
+ *   name: 'orders',
+ *   servers: ['nats://localhost:4222'],
+ *   codec: new MsgpackCodec(new Packr()),
+ * });
+ * ```
+ */
+declare class MsgpackCodec implements Codec {
+    private readonly packr;
+    constructor(packr: PackrLike);
+    encode(data: unknown): Uint8Array;
+    decode(data: Uint8Array): unknown;
+}
+
 type NatsMessage = JsMsg | Msg;
 /**
  * Execution context for RPC and event handlers.
@@ -1212,7 +1570,7 @@ type NatsMessage = JsMsg | Msg;
  *     return;
  *   }
  *   if (!this.isReady()) {
- *     ctx.retry({ delay: 5000 });
+ *     ctx.retry({ delayMs: 5000 });
  *     return;
  *   }
  *   await this.process(data);
@@ -1330,9 +1688,14 @@ declare class JetstreamHealthIndicator {
      * Returns `{ [key]: { status: 'up', ... } }` on success.
      * Throws an error with `{ [key]: { status: 'down', ... } }` on failure.
      *
+     * The thrown error sets `isHealthCheckError: true` and `causes` — the
+     * duck-type contract that Terminus `HealthCheckExecutor` uses to distinguish
+     * health failures from unexpected exceptions. Works with both Terminus v10
+     * (`instanceof HealthCheckError`) and v11+ (`error?.isHealthCheckError`).
+     *
      * @param key - Health indicator key (default: `'jetstream'`).
      * @returns Object with status, server, and latency under the given key.
-     * @throws Error with `{ [key]: { status: 'down' } }` when disconnected.
+     * @throws Error with `isHealthCheckError`, `causes`, and `{ [key]: { status: 'down' } }`.
      */
     isHealthy(key?: string): Promise<Record<string, Record<string, unknown>>>;
 }
@@ -1343,8 +1706,6 @@ declare const JETSTREAM_OPTIONS: unique symbol;
 declare const JETSTREAM_CONNECTION: unique symbol;
 /** Token for the global Codec instance. */
 declare const JETSTREAM_CODEC: unique symbol;
-/** Token for the EventBus instance. */
-declare const JETSTREAM_EVENT_BUS: unique symbol;
 /**
  * Generate the injection token for a `forFeature()` client.
  *
@@ -1377,6 +1738,47 @@ type TimeUnit = 'ms' | 'seconds' | 'minutes' | 'hours' | 'days';
  * ```
  */
 declare const toNanos: (value: number, unit: TimeUnit) => number;
+/** Default config for workqueue event streams. */
+declare const DEFAULT_EVENT_STREAM_CONFIG: Partial<StreamConfig>;
+/** Default config for RPC command streams (jetstream mode only). */
+declare const DEFAULT_COMMAND_STREAM_CONFIG: Partial<StreamConfig>;
+/** Default config for broadcast event streams. */
+declare const DEFAULT_BROADCAST_STREAM_CONFIG: Partial<StreamConfig>;
+/** Default config for ordered event streams (Limits retention). */
+declare const DEFAULT_ORDERED_STREAM_CONFIG: Partial<StreamConfig>;
+/** Default config for dead-letter queue (DLQ) streams. */
+declare const DEFAULT_DLQ_STREAM_CONFIG: Partial<StreamConfig>;
+/** Default config for workqueue event consumers. */
+declare const DEFAULT_EVENT_CONSUMER_CONFIG: Partial<ConsumerConfig>;
+/** Default config for RPC command consumers (jetstream mode only). */
+declare const DEFAULT_COMMAND_CONSUMER_CONFIG: Partial<ConsumerConfig>;
+/** Default config for broadcast event consumers. */
+declare const DEFAULT_BROADCAST_CONSUMER_CONFIG: Partial<ConsumerConfig>;
+/** Default RPC timeout for Core mode (30 seconds). */
+declare const DEFAULT_RPC_TIMEOUT = 30000;
+/** Default RPC timeout for JetStream mode (3 minutes). */
+declare const DEFAULT_JETSTREAM_RPC_TIMEOUT = 180000;
+/** Default graceful shutdown timeout (10 seconds). */
+declare const DEFAULT_SHUTDOWN_TIMEOUT = 10000;
+/** Default KV bucket name for handler metadata. */
+declare const DEFAULT_METADATA_BUCKET = "handler_registry";
+/** Default number of KV bucket replicas. */
+declare const DEFAULT_METADATA_REPLICAS = 1;
+/** Default KV bucket history depth (latest value only). */
+declare const DEFAULT_METADATA_HISTORY = 1;
+/** Default KV bucket TTL in milliseconds (entries expire unless refreshed). */
+declare const DEFAULT_METADATA_TTL = 30000;
+/** Minimum allowed metadata TTL in milliseconds. Prevents tight heartbeat loops. */
+declare const MIN_METADATA_TTL = 5000;
+/**
+ * Build a KV key for a handler's metadata entry.
+ *
+ * @param serviceName - Service name from `forRoot({ name })`.
+ * @param kind - Handler's stream kind ({@link StreamKind}).
+ * @param pattern - The message pattern (e.g. `'order.created'`).
+ * @returns KV key (e.g. `orders.ev.order.created`).
+ */
+declare const metadataKey: (serviceName: string, kind: StreamKind, pattern: string) => string;
 /**
  * NATS headers managed by the transport.
  *
@@ -1396,6 +1798,20 @@ declare enum JetstreamHeader {
     /** Set to `'true'` on error responses so the client can distinguish success from failure. */
     Error = "x-error"
 }
+declare enum JetstreamDlqHeader {
+    /** Reason for the message being sent to the DLQ — the last handler error message. */
+    DeadLetterReason = "x-dead-letter-reason",
+    /** Original NATS subject the message was originally published to */
+    OriginalSubject = "x-original-subject",
+    /** Source stream name */
+    OriginalStream = "x-original-stream",
+    /** ISO timestamp of when the message was moved to DLQ */
+    FailedAt = "x-failed-at",
+    /** Number of times the message has been delivered */
+    DeliveryCount = "x-delivery-count"
+}
+/** Set of header names that are reserved and cannot be set by users. */
+declare const RESERVED_HEADERS: Set<string>;
 /**
  * Build the internal service name with microservice suffix.
  *
@@ -1412,6 +1828,13 @@ declare const internalName: (name: string) => string;
  * @returns `{serviceName}__microservice.{kind}.{pattern}`
  */
 declare const buildSubject: (serviceName: string, kind: SubjectKind, pattern: string) => string;
+/**
+ * Build a broadcast subject.
+ *
+ * @param pattern - The message pattern (e.g. `'config.updated'`).
+ * @returns `broadcast.{pattern}`
+ */
+declare const buildBroadcastSubject: (pattern: string) => string;
 /**
  * Build the JetStream stream name for a given service and kind.
  *
@@ -1420,6 +1843,13 @@ declare const buildSubject: (serviceName: string, kind: SubjectKind, pattern: st
  * @returns Stream name (e.g. `orders__microservice_ev-stream` or `broadcast-stream`).
  */
 declare const streamName: (serviceName: string, kind: StreamKind) => string;
+/**
+ * Build the JetStream dead-letter queue stream name for a given service.
+ *
+ * @param serviceName - Service name from `forRoot({ name })`.
+ * @returns DLQ Stream name (e.g. `orders__microservice_dlq-stream`).
+ */
+declare const dlqStreamName: (serviceName: string) => string;
 /**
  * Build the JetStream consumer name for a given service and kind.
  *
@@ -1443,4 +1873,4 @@ declare const isJetStreamRpcMode: (rpc: RpcConfig | undefined) => boolean;
 /** Check if the RPC config specifies Core mode (default). */
 declare const isCoreRpcMode: (rpc: RpcConfig | undefined) => boolean;
 
-export { type Codec, type DeadLetterInfo, EventBus, JETSTREAM_CODEC, JETSTREAM_CONNECTION, JETSTREAM_EVENT_BUS, JETSTREAM_OPTIONS, JetstreamClient, type JetstreamFeatureOptions, JetstreamHeader, JetstreamHealthIndicator, type JetstreamHealthStatus, JetstreamModule, type JetstreamModuleAsyncOptions, type JetstreamModuleOptions, JetstreamRecord, JetstreamRecordBuilder, JetstreamStrategy, JsonCodec, MessageKind, type OrderedEventOverrides, PatternPrefix, type RpcConfig, RpcContext, type ScheduleRecordOptions, type StreamConsumerOverrides, StreamKind, TransportEvent, type TransportHooks, buildSubject, consumerName, getClientToken, internalName, isCoreRpcMode, isJetStreamRpcMode, streamName, toNanos };
+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 };