@horizon-republic/nestjs-jetstream 2.2.0 → 2.3.2

package/dist/index.d.ts

@@ -1,13 +1,995 @@
-export { JetstreamModule } from './jetstream.module';
-export { TransportEvent } from './interfaces';
-export type { Codec, DeadLetterInfo, JetstreamFeatureOptions, JetstreamModuleAsyncOptions, JetstreamModuleOptions, RpcConfig, StreamConsumerOverrides, TransportHooks, } from './interfaces';
-export { JetstreamClient } from './client';
-export { JetstreamRecord, JetstreamRecordBuilder } from './client';
-export { JsonCodec } from './codec';
-export { RpcContext } from './context';
-export { JetstreamHealthIndicator } from './health';
-export type { JetstreamHealthStatus } from './health';
-export { getClientToken, JetstreamHeader, JETSTREAM_CODEC, JETSTREAM_CONNECTION, JETSTREAM_EVENT_BUS, JETSTREAM_OPTIONS, nanos, } from './jetstream.constants';
-export { EventBus } from './hooks';
-export { JetstreamStrategy } from './server';
-//# sourceMappingURL=index.d.ts.map
+import { ModuleMetadata, FactoryProvider, Type, Logger, OnApplicationShutdown, DynamicModule } from '@nestjs/common';
+import { MsgHdrs, StreamConfig, ConsumerConfig, ConnectionOptions, NatsConnection, Status, JetStreamManager, ConsumerInfo, JsMsg, Msg } from 'nats';
+import { MessageHandler, Server, CustomTransportStrategy, ClientProxy, ReadPacket, WritePacket, BaseRpcContext } from '@nestjs/microservices';
+import { Observable } from 'rxjs';
+
+/**
+ * Codec interface for encoding and decoding message payloads.
+ *
+ * Implementations handle serialization between application objects and
+ * binary data transmitted over NATS. The transport uses a single global
+ * codec — all messages (RPC and events) share the same format.
+ *
+ * @example
+ * ```typescript
+ * import { encode, decode } from '@msgpack/msgpack';
+ *
+ * class MsgPackCodec implements Codec {
+ *   encode(data: unknown): Uint8Array {
+ *     return encode(data);
+ *   }
+ *   decode(data: Uint8Array): unknown {
+ *     return decode(data);
+ *   }
+ * }
+ * ```
+ */
+interface Codec {
+    /** Serialize application data to binary for NATS transmission. */
+    encode(data: unknown): Uint8Array;
+    /** Deserialize binary NATS payload back to application data. */
+    decode(data: Uint8Array): unknown;
+}
+
+declare enum TransportEvent {
+    Connect = "connect",
+    Disconnect = "disconnect",
+    Reconnect = "reconnect",
+    Error = "error",
+    RpcTimeout = "rpcTimeout",
+    MessageRouted = "messageRouted",
+    ShutdownStart = "shutdownStart",
+    ShutdownComplete = "shutdownComplete",
+    DeadLetter = "deadLetter"
+}
+/**
+ * Hook callbacks for transport lifecycle and operational events.
+ *
+ * Each hook has a default implementation that logs via NestJS Logger.
+ * Providing a custom hook replaces the default for that specific event.
+ * Hooks that are not overridden continue using the Logger fallback.
+ *
+ * @example
+ * ```typescript
+ * JetstreamModule.forRoot({
+ *   hooks: {
+ *     [TransportEvent.Error]: (error, context) => sentry.captureException(error),
+ *     [TransportEvent.RpcTimeout]: (subject) => metrics.increment('rpc.timeout'),
+ *   },
+ * })
+ * ```
+ */
+interface TransportHooks {
+    /** Fired when NATS connection is established. */
+    [TransportEvent.Connect](server: string): void;
+    /** Fired when NATS connection is lost. */
+    [TransportEvent.Disconnect](): void;
+    /** Fired when NATS connection is re-established after a disconnect. */
+    [TransportEvent.Reconnect](server: string): void;
+    /** Fired on any transport-level error. */
+    [TransportEvent.Error](error: Error, context?: string): void;
+    /** Fired when an RPC handler exceeds its timeout. */
+    [TransportEvent.RpcTimeout](subject: string, correlationId: string): void;
+    /** Fired after a message is successfully routed to its handler. */
+    [TransportEvent.MessageRouted](subject: string, kind: 'rpc' | 'event'): void;
+    /** Fired at the start of the graceful shutdown sequence. */
+    [TransportEvent.ShutdownStart](): void;
+    /** Fired after graceful shutdown completes. */
+    [TransportEvent.ShutdownComplete](): void;
+    /** Fired when a message exhausts all delivery attempts (dead letter). */
+    [TransportEvent.DeadLetter](info: DeadLetterInfo): void;
+}
+/**
+ * Context passed to the onDeadLetter callback when a message exhausts all delivery attempts.
+ */
+interface DeadLetterInfo {
+    /** The NATS subject the message was published to. */
+    subject: string;
+    /** Decoded message payload. */
+    data: unknown;
+    /** Message headers (raw NATS MsgHdrs). */
+    headers: MsgHdrs | undefined;
+    /** The error that caused the last handler failure. */
+    error: unknown;
+    /** How many times this message was delivered. */
+    deliveryCount: number;
+    /** The stream this message belongs to. */
+    stream: string;
+    /** The stream sequence number. */
+    streamSequence: number;
+    /** ISO timestamp of the message (derived from msg.info.timestampNanos). */
+    timestamp: string;
+}
+
+/**
+ * RPC transport configuration.
+ *
+ * Discriminated union on `mode`:
+ * - `'core'`      — NATS native request/reply. Lowest latency.
+ * - `'jetstream'`  — Commands persisted in JetStream. Responses via Core NATS inbox.
+ *
+ * When `mode` is `'core'`, only `timeout` is available.
+ * When `mode` is `'jetstream'`, additional stream/consumer overrides are exposed.
+ */
+type RpcConfig = {
+    mode: 'core';
+    /** Request timeout in ms. Default: 30_000. */
+    timeout?: number;
+} | {
+    mode: 'jetstream';
+    /** Handler timeout in ms. Default: 180_000 (3 min). */
+    timeout?: number;
+    /** Raw NATS StreamConfig overrides for the command stream. */
+    stream?: Partial<StreamConfig>;
+    /** Raw NATS ConsumerConfig overrides for the command consumer. */
+    consumer?: Partial<ConsumerConfig>;
+};
+/** Overrides for JetStream stream and consumer configuration. */
+interface StreamConsumerOverrides {
+    stream?: Partial<StreamConfig>;
+    consumer?: Partial<ConsumerConfig>;
+}
+/**
+ * Root module configuration for `JetstreamModule.forRoot()`.
+ *
+ * Minimal usage requires only `name` and `servers`.
+ * All other fields have production-ready defaults.
+ */
+interface JetstreamModuleOptions {
+    /** Service name. Used for stream/consumer/subject naming. */
+    name: string;
+    /** NATS server URLs. */
+    servers: string[];
+    /**
+     * Global message codec.
+     * @default JsonCodec
+     */
+    codec?: Codec;
+    /**
+     * RPC transport mode and configuration.
+     * @default { mode: 'core' }
+     */
+    rpc?: RpcConfig;
+    /**
+     * Enable consumer infrastructure (streams, consumers, message routing).
+     * Set to `false` for publisher-only services (e.g., API gateways).
+     * @default true
+     */
+    consumer?: boolean;
+    /** Workqueue event stream/consumer overrides. */
+    events?: StreamConsumerOverrides;
+    /** Broadcast event stream/consumer overrides. */
+    broadcast?: StreamConsumerOverrides;
+    /**
+     * Transport lifecycle hook handlers.
+     * Unset hooks fall back to NestJS Logger.
+     */
+    hooks?: Partial<TransportHooks>;
+    /**
+     * Async callback invoked when an event message exhausts all delivery attempts.
+     * Called before msg.term(). If it throws, the message is nak'd for retry.
+     *
+     * Use this to persist dead letters to an external store (DB, S3, another queue).
+     * The NATS connection is available via `JETSTREAM_CONNECTION` token in forRootAsync.
+     *
+     * @example
+     * ```typescript
+     * JetstreamModule.forRootAsync({
+     *   name: 'my-service',
+     *   imports: [DlqModule],
+     *   inject: [DlqService, JETSTREAM_CONNECTION],
+     *   useFactory: (dlqService, connection) => ({
+     *     servers: ['nats://localhost:4222'],
+     *     onDeadLetter: async (info) => {
+     *       await dlqService.persist(info);
+     *     },
+     *   }),
+     * })
+     * ```
+     */
+    onDeadLetter?(info: DeadLetterInfo): Promise<void>;
+    /**
+     * Graceful shutdown timeout in ms.
+     * Handlers exceeding this are abandoned.
+     * @default 10_000
+     */
+    shutdownTimeout?: number;
+    /**
+     * Raw NATS ConnectionOptions pass-through for advanced connection config.
+     * Allows setting tls, auth, reconnect behavior, maxReconnectAttempts, etc.
+     * Merged with `name` and `servers` — those take precedence.
+     */
+    connectionOptions?: Partial<ConnectionOptions>;
+}
+/** Options for `JetstreamModule.forFeature()`. */
+interface JetstreamFeatureOptions {
+    /** Target service name for subject construction. */
+    name: string;
+    /**
+     * Override the global codec for this client.
+     * Falls back to the root codec from `forRoot()` when omitted.
+     */
+    codec?: Codec;
+}
+/**
+ * Async configuration for `JetstreamModule.forRootAsync()`.
+ *
+ * Supports three patterns: `useFactory`, `useExisting`, `useClass`.
+ */
+type JetstreamModuleAsyncOptions = {
+    /** Service name — required upfront for DI token generation. */
+    name: string;
+    /** Additional module imports (e.g., ConfigModule). */
+    imports?: ModuleMetadata['imports'];
+} & ({
+    useFactory(...args: unknown[]): Promise<Omit<JetstreamModuleOptions, 'name'>> | Omit<JetstreamModuleOptions, 'name'>;
+    inject?: FactoryProvider['inject'];
+    useExisting?: never;
+    useClass?: never;
+} | {
+    useExisting: Type<Omit<JetstreamModuleOptions, 'name'>>;
+    useFactory?: never;
+    inject?: never;
+    useClass?: never;
+} | {
+    useClass: Type<Omit<JetstreamModuleOptions, 'name'>>;
+    useFactory?: never;
+    inject?: never;
+    useExisting?: never;
+});
+
+/** Identifies a JetStream stream/consumer kind. */
+type StreamKind = 'ev' | 'cmd' | 'broadcast';
+
+/** Grouped pattern lists by stream kind. */
+interface PatternsByKind {
+    events: string[];
+    commands: string[];
+    broadcasts: string[];
+}
+
+/**
+ * Central event bus for transport lifecycle notifications.
+ *
+ * Dispatches events to user-provided hooks or falls back to
+ * the NestJS Logger for each event type independently.
+ *
+ * @example
+ * ```typescript
+ * const bus = new EventBus(logger, {
+ *   [TransportEvent.Error]: (err) => sentry.captureException(err),
+ * });
+ *
+ * bus.emit(TransportEvent.Error, new Error('timeout'), 'rpc-router');
+ * // → calls sentry, not logger
+ *
+ * bus.emit(TransportEvent.Connect, 'nats://localhost:4222');
+ * // → calls logger.log (no custom hook for connect)
+ * ```
+ */
+declare class EventBus {
+    private readonly hooks;
+    private readonly logger;
+    constructor(logger: Logger, hooks?: Partial<TransportHooks>);
+    /** Emit a lifecycle event. Dispatches to custom hook or Logger fallback. */
+    emit<K extends keyof TransportHooks>(event: K, ...args: Parameters<TransportHooks[K]>): void;
+    /** Default Logger-based handlers for each event type. */
+    private defaultHandler;
+}
+
+/**
+ * Manages the lifecycle of a single NATS connection shared across the application.
+ *
+ * Provides both Promise-based and Observable-based access to the connection:
+ * - `connect()` / `getConnection()` — async/await for one-time setup
+ * - `nc$` — cached observable (shareReplay) for reactive consumers
+ * - `status$` — live connection status event stream
+ *
+ * One instance per application, created by `JetstreamModule.forRoot()`.
+ */
+declare class ConnectionProvider {
+    private readonly options;
+    private readonly eventBus;
+    /** Cached observable that replays the established connection to new subscribers. */
+    readonly nc$: Observable<NatsConnection>;
+    /** Live stream of connection status events (no replay). */
+    readonly status$: Observable<Status>;
+    private readonly logger;
+    private connection;
+    private connectionPromise;
+    private jsmInstance;
+    constructor(options: JetstreamModuleOptions, eventBus: EventBus);
+    /**
+     * Establish NATS connection. Idempotent — returns cached connection on subsequent calls.
+     *
+     * @throws Error if connection is refused (fail fast).
+     */
+    getConnection(): Promise<NatsConnection>;
+    /**
+     * Get JetStream manager. Cached after first call.
+     */
+    getJetStreamManager(): Promise<JetStreamManager>;
+    /** Direct access to the raw NATS connection (assumes already connected). */
+    get unwrap(): NatsConnection | null;
+    /**
+     * Gracefully shut down the connection.
+     *
+     * Sequence: drain → wait for close. Falls back to force-close on error.
+     */
+    shutdown(): Promise<void>;
+    /** Internal: establish the physical connection with reconnect monitoring. */
+    private establish;
+    /** Subscribe to connection status events and emit hooks. */
+    private monitorStatus;
+}
+
+/**
+ * Registry mapping NATS subjects to NestJS message handlers.
+ *
+ * Handles subject normalization and categorization:
+ * - Detects broadcast handlers via `extras.broadcast` metadata
+ * - Normalizes full NATS subjects back to user-facing patterns
+ * - Provides lists of patterns by category for stream/consumer setup
+ */
+declare class PatternRegistry {
+    private readonly options;
+    private readonly logger;
+    private readonly registry;
+    constructor(options: JetstreamModuleOptions);
+    /**
+     * Register all handlers from the NestJS strategy.
+     *
+     * @param handlers Map of pattern -> MessageHandler from `Server.getHandlers()`.
+     */
+    registerHandlers(handlers: Map<string, MessageHandler>): void;
+    /** Find handler for a full NATS subject. */
+    getHandler(subject: string): MessageHandler | null;
+    /** Get all registered broadcast patterns (for consumer filter_subject setup). */
+    getBroadcastPatterns(): string[];
+    /** Check if any broadcast handlers are registered. */
+    hasBroadcastHandlers(): boolean;
+    /** Check if any RPC (command) handlers are registered. */
+    hasRpcHandlers(): boolean;
+    /** Check if any workqueue event handlers are registered. */
+    hasEventHandlers(): boolean;
+    /** Get patterns grouped by kind. */
+    getPatternsByKind(): PatternsByKind;
+    /** Normalize a full NATS subject back to the user-facing pattern. */
+    normalizeSubject(subject: string): string;
+    /** Log a summary of all registered handlers. */
+    private logSummary;
+}
+
+/**
+ * Handles RPC via NATS Core request/reply pattern.
+ *
+ * Subscribes to `{service}.cmd.>` with a queue group for load balancing.
+ * Each request is processed and replied to directly via `msg.respond()`.
+ *
+ * This is the default RPC mode — lowest latency, no persistence overhead.
+ */
+declare class CoreRpcServer {
+    private readonly options;
+    private readonly connection;
+    private readonly patternRegistry;
+    private readonly codec;
+    private readonly eventBus;
+    private readonly logger;
+    private subscription;
+    constructor(options: JetstreamModuleOptions, connection: ConnectionProvider, patternRegistry: PatternRegistry, codec: Codec, eventBus: EventBus);
+    /** Start listening for RPC requests on the command subject. */
+    start(): Promise<void>;
+    /** Stop listening and clean up the subscription. */
+    stop(): void;
+    /** Handle an incoming Core NATS request. */
+    private handleRequest;
+    /** Send an error response back to the caller with x-error header. */
+    private respondWithError;
+}
+
+/**
+ * Manages JetStream stream lifecycle: creation, updates, and idempotent ensures.
+ *
+ * Creates up to three stream types depending on configuration:
+ * - **Event stream** — workqueue events (always, when consumer enabled)
+ * - **Command stream** — RPC commands (only in jetstream RPC mode)
+ * - **Broadcast stream** — fan-out events (only if broadcast handlers exist)
+ *
+ * All operations are idempotent: safe to call on every startup and reconnection.
+ */
+declare class StreamProvider {
+    private readonly options;
+    private readonly connection;
+    private readonly logger;
+    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.
+     */
+    ensureStreams(kinds: StreamKind[]): Promise<void>;
+    /** Get the stream name for a given kind. */
+    getStreamName(kind: StreamKind): string;
+    /** Get the subjects pattern for a given kind. */
+    getSubjects(kind: StreamKind): string[];
+    /** Ensure a single stream exists, creating or updating as needed. */
+    private ensureStream;
+    /** Build the full stream config by merging defaults with user overrides. */
+    private buildConfig;
+    /** Get default config for a stream kind. */
+    private getDefaults;
+    /** Get user-provided overrides for a stream kind. */
+    private getOverrides;
+}
+
+/** Options for dead letter queue handling. */
+interface DeadLetterConfig {
+    /**
+     * Map of stream name -> max_deliver value.
+     * Used to detect when a message from a given stream has exhausted all delivery attempts.
+     */
+    maxDeliverByStream: Map<string, number>;
+    /** Async callback invoked when a message exhausts all deliveries. */
+    onDeadLetter(info: DeadLetterInfo): Promise<void>;
+}
+/**
+ * Routes incoming event messages (workqueue and broadcast) to NestJS handlers.
+ *
+ * Delivery semantics (at-least-once):
+ * - Handler executes first
+ * - Success -> ack (message consumed)
+ * - Handler error -> nak (NATS redelivers, up to `max_deliver` times)
+ * - Dead letter (max_deliver reached) -> onDeadLetter hook -> term or nak
+ * - Decode error -> term (no retry for malformed payloads)
+ * - No handler found -> term (configuration error)
+ *
+ * Both workqueue and broadcast use the same ack/nak semantics.
+ * Each durable consumer tracks delivery independently, so a nak from
+ * one broadcast consumer does not affect others.
+ *
+ * Handlers must be idempotent — NATS may redeliver on failure or timeout.
+ */
+declare class EventRouter {
+    private readonly messageProvider;
+    private readonly patternRegistry;
+    private readonly codec;
+    private readonly eventBus;
+    private readonly deadLetterConfig?;
+    private readonly logger;
+    private readonly subscriptions;
+    constructor(messageProvider: MessageProvider, patternRegistry: PatternRegistry, codec: Codec, eventBus: EventBus, deadLetterConfig?: DeadLetterConfig | undefined);
+    /** Start routing event and broadcast messages to handlers. */
+    start(): void;
+    /** Stop routing and unsubscribe from all streams. */
+    destroy(): void;
+    /** Subscribe to a message stream and route each message. */
+    private subscribeToStream;
+    /** Handle a single event message: decode -> execute handler -> ack/nak. */
+    private handle;
+    /** 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. */
+    private handleDeadLetter;
+}
+
+/**
+ * Routes RPC command messages in JetStream mode.
+ *
+ * Delivery semantics:
+ * - Handler must complete within timeout (default: 3 min)
+ * - Success -> ack -> publish response to ReplyTo (publish failure does not affect ack)
+ * - Handler error -> publish error to ReplyTo -> term (no redelivery)
+ * - Timeout -> no response -> term
+ * - No handler / decode error -> term immediately
+ *
+ * Nak is never used for RPC — prevents duplicate side effects.
+ */
+declare class RpcRouter {
+    private readonly messageProvider;
+    private readonly patternRegistry;
+    private readonly connection;
+    private readonly codec;
+    private readonly eventBus;
+    private readonly logger;
+    private readonly timeout;
+    private subscription;
+    constructor(messageProvider: MessageProvider, patternRegistry: PatternRegistry, connection: ConnectionProvider, codec: Codec, eventBus: EventBus, timeout?: number);
+    /** Start routing command messages to handlers. */
+    start(): void;
+    /** Stop routing and unsubscribe. */
+    destroy(): void;
+    /** Handle a single RPC command message. */
+    private handle;
+    /** Execute handler, publish response, settle message. */
+    private executeHandler;
+}
+
+/**
+ * Manages JetStream consumer lifecycle: creation and idempotent ensures.
+ *
+ * Creates durable pull-based consumers that survive restarts.
+ * Consumer configuration is merged from defaults and user overrides.
+ */
+declare class ConsumerProvider {
+    private readonly options;
+    private readonly connection;
+    private readonly streamProvider;
+    private readonly patternRegistry;
+    private readonly logger;
+    constructor(options: JetstreamModuleOptions, connection: ConnectionProvider, streamProvider: StreamProvider, patternRegistry: PatternRegistry);
+    /**
+     * Ensure consumers exist for the specified kinds.
+     *
+     * @returns Map of kind -> ConsumerInfo for downstream use.
+     */
+    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;
+    /** Build consumer config by merging defaults with user overrides. */
+    private buildConfig;
+    /** Get default config for a consumer kind. */
+    private getDefaults;
+    /** Get user-provided overrides for a consumer kind. */
+    private getOverrides;
+}
+
+/**
+ * Manages pull-based message consumption from JetStream consumers.
+ *
+ * Uses `defer()` + `repeat()` pattern for self-healing: when the async
+ * iterator completes (e.g., NATS restart), the consumer automatically
+ * re-establishes after a short delay.
+ *
+ * Emits messages to kind-specific RxJS subjects for downstream routing.
+ */
+declare class MessageProvider {
+    private readonly connection;
+    private readonly eventBus;
+    private readonly logger;
+    private readonly destroy$;
+    private readonly activeIterators;
+    private readonly eventMessages$;
+    private readonly commandMessages$;
+    private readonly broadcastMessages$;
+    constructor(connection: ConnectionProvider, eventBus: EventBus);
+    /** Observable stream of workqueue event messages. */
+    get events$(): Observable<JsMsg>;
+    /** Observable stream of RPC command messages (jetstream mode). */
+    get commands$(): Observable<JsMsg>;
+    /** Observable stream of broadcast event messages. */
+    get broadcasts$(): Observable<JsMsg>;
+    /**
+     * Start consuming messages from the given consumer infos.
+     *
+     * Each consumer gets an independent self-healing flow.
+     * Call `destroy()` to stop all consumers.
+     */
+    start(consumers: Map<StreamKind, ConsumerInfo>): void;
+    /** Stop all consumer flows and complete all subjects. */
+    destroy(): void;
+    /** Create a self-healing consumer flow for a specific kind. */
+    private createFlow;
+    /** Single iteration: get consumer -> pull messages -> emit to subject. */
+    private consumeOnce;
+    /** Get the target subject for a consumer kind. */
+    private getTargetSubject;
+}
+
+/**
+ * NestJS custom transport strategy for NATS JetStream.
+ *
+ * Coordinates all server-side providers:
+ * 1. Registers handlers from NestJS into PatternRegistry
+ * 2. Creates required streams and consumers
+ * 3. Starts message consumption and routing
+ * 4. Handles Core or JetStream RPC based on configuration
+ *
+ * All dependencies are injected via the NestJS DI container.
+ */
+declare class JetstreamStrategy extends Server implements CustomTransportStrategy {
+    private readonly options;
+    private readonly connection;
+    private readonly patternRegistry;
+    private readonly streamProvider;
+    private readonly consumerProvider;
+    private readonly messageProvider;
+    private readonly eventRouter;
+    private readonly rpcRouter;
+    private readonly coreRpcServer;
+    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);
+    /**
+     * 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>;
+    /** Gracefully stop the transport. */
+    close(): void;
+    /**
+     * Register event listener (required by Server base class).
+     *
+     * Stores callbacks for client use. Primary lifecycle events
+     * are routed through EventBus.
+     */
+    on(event: string, callback: Function): void;
+    /** Unwrap the underlying NATS connection. */
+    unwrap<T>(): T;
+    /** Access the pattern registry (for module-level introspection). */
+    getPatternRegistry(): PatternRegistry;
+    /** Determine which JetStream stream kinds are needed. */
+    private resolveStreamKinds;
+    private isCoreRpcMode;
+    private isJetStreamRpcMode;
+}
+
+/**
+ * Orchestrates graceful transport shutdown.
+ *
+ * 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
+ */
+declare class ShutdownManager {
+    private readonly connection;
+    private readonly eventBus;
+    private readonly timeout;
+    private readonly logger;
+    constructor(connection: ConnectionProvider, eventBus: EventBus, timeout: number);
+    /**
+     * Execute the full shutdown sequence.
+     *
+     * @param strategy Optional strategy to close (stops consumers and subscriptions).
+     */
+    shutdown(strategy?: JetstreamStrategy): Promise<void>;
+}
+
+/**
+ * Root module for the NestJS JetStream transport.
+ *
+ * - `forRoot()` / `forRootAsync()` — registers once in AppModule.
+ *   Creates shared NATS connection, codec, event bus, and optionally
+ *   the consumer infrastructure.
+ *
+ * - `forFeature()` — registers in feature modules.
+ *   Creates a lightweight client proxy targeting a specific service.
+ *
+ * @example
+ * ```typescript
+ * // AppModule — global setup
+ * @Module({
+ *   imports: [
+ *     JetstreamModule.forRoot({
+ *       name: 'orders',
+ *       servers: ['nats://localhost:4222'],
+ *     }),
+ *   ],
+ * })
+ * export class AppModule {}
+ *
+ * // Feature module — per-service clients
+ * @Module({
+ *   imports: [
+ *     JetstreamModule.forFeature({ name: 'users' }),
+ *     JetstreamModule.forFeature({ name: 'payments' }),
+ *   ],
+ * })
+ * export class OrdersModule {}
+ * ```
+ */
+declare class JetstreamModule implements OnApplicationShutdown {
+    private readonly shutdownManager?;
+    private readonly strategy?;
+    constructor(shutdownManager?: ShutdownManager | undefined, strategy?: (JetstreamStrategy | null) | undefined);
+    /**
+     * Register the JetStream transport globally.
+     *
+     * Creates a shared NATS connection, codec, event bus, and optionally
+     * the full consumer infrastructure (streams, consumers, routers).
+     *
+     * @param options Module configuration.
+     * @returns Dynamic module ready to be imported.
+     */
+    static forRoot(options: JetstreamModuleOptions): DynamicModule;
+    /**
+     * Register the JetStream transport globally with async configuration.
+     *
+     * Supports `useFactory`, `useExisting`, and `useClass` patterns
+     * for loading configuration from ConfigService, environment, etc.
+     *
+     * @param asyncOptions Async configuration.
+     * @returns Dynamic module ready to be imported.
+     */
+    static forRootAsync(asyncOptions: JetstreamModuleAsyncOptions): DynamicModule;
+    /**
+     * Register a lightweight client proxy for a target service.
+     *
+     * Reuses the shared NATS connection from `forRoot()`.
+     * Import in each feature module that needs to communicate with a specific service.
+     *
+     * @param options Feature options with target service name.
+     * @returns Dynamic module with the client provider.
+     */
+    static forFeature(options: JetstreamFeatureOptions): DynamicModule;
+    /** Create all providers for synchronous forRoot(). */
+    /**
+     * Build a map of stream name -> max_deliver for dead letter detection.
+     * Each stream kind (ev, broadcast) has its own consumer config with potentially
+     * different max_deliver values.
+     */
+    private static buildMaxDeliverMap;
+    private static createCoreProviders;
+    /** Create providers that depend on JETSTREAM_OPTIONS (shared by sync and async). */
+    private static createCoreDependentProviders;
+    /** Create async options provider from useFactory/useExisting/useClass. */
+    private static createAsyncOptionsProvider;
+    /**
+     * Gracefully shut down the transport on application termination.
+     */
+    onApplicationShutdown(): Promise<void>;
+}
+
+/**
+ * NestJS ClientProxy implementation for the JetStream transport.
+ *
+ * Supports two operational modes:
+ * - **Core mode** (default): Uses `nc.request()` for RPC, `nc.publish()` for events.
+ * - **JetStream mode**: Uses `js.publish()` for RPC commands + inbox for responses.
+ *
+ * Events always go through JetStream publish for guaranteed delivery.
+ * The mode only affects RPC (request/reply) behavior.
+ *
+ * Clients are lightweight — they share the NATS connection from `forRoot()`.
+ */
+declare class JetstreamClient extends ClientProxy {
+    private readonly rootOptions;
+    private readonly connection;
+    private readonly codec;
+    private readonly eventBus;
+    private readonly logger;
+    /** Target service name this client sends messages to. */
+    private readonly targetName;
+    /** Shared inbox for JetStream-mode RPC responses. */
+    private inbox;
+    private inboxSubscription;
+    /** Pending JetStream-mode RPC callbacks, keyed by correlation ID. */
+    private readonly pendingMessages;
+    /** Pending JetStream-mode RPC timeouts, keyed by correlation ID. */
+    private readonly pendingTimeouts;
+    /** Subscription to connection status events for disconnect handling. */
+    private statusSubscription;
+    constructor(rootOptions: JetstreamModuleOptions, targetServiceName: string, connection: ConnectionProvider, codec: Codec, eventBus: EventBus);
+    /** Establish connection. Called automatically by NestJS on first use. */
+    connect(): Promise<NatsConnection>;
+    /** Clean up resources. */
+    close(): Promise<void>;
+    /** Direct access to the raw NATS connection. */
+    unwrap<T = NatsConnection>(): T;
+    /**
+     * Publish a fire-and-forget event to JetStream.
+     *
+     * Events are published to either the workqueue stream or broadcast stream
+     * depending on the subject prefix.
+     */
+    protected dispatchEvent<T = unknown>(packet: ReadPacket): Promise<T>;
+    /**
+     * Publish an RPC command and register callback for response.
+     *
+     * Core mode: uses nc.request() with timeout.
+     * JetStream mode: publishes to stream + waits for inbox response.
+     */
+    protected publish(packet: ReadPacket, callback: (p: WritePacket) => void): () => void;
+    /** Core mode: nc.request() with timeout. */
+    private publishCoreRpc;
+    /** JetStream mode: publish to stream + wait for inbox response. */
+    private publishJetStreamRpc;
+    /** Fail-fast all pending JetStream RPC callbacks on connection loss. */
+    private handleDisconnect;
+    /** Reject all pending RPC callbacks, clear timeouts, and tear down inbox. */
+    private rejectPendingRpcs;
+    /** Setup shared inbox subscription for JetStream RPC responses. */
+    private setupInbox;
+    /** Route an inbox reply to the matching pending callback. */
+    private routeInboxReply;
+    /** Build event subject — workqueue or broadcast. */
+    private buildEventSubject;
+    /** Build NATS headers merging custom headers with transport headers. */
+    private buildHeaders;
+    /** Extract data, headers, and timeout from raw packet data or JetstreamRecord. */
+    private extractRecordData;
+    private isCoreRpcMode;
+    private isJetStreamRpcMode;
+    private getRpcTimeout;
+}
+
+/**
+ * Immutable message record for JetStream transport.
+ *
+ * Compatible with NestJS record builder pattern (like RmqRecord, NatsRecord).
+ * Pass as the second argument to `client.send()` or `client.emit()`.
+ *
+ * @example
+ * ```typescript
+ * const record = new JetstreamRecordBuilder({ id: 1 })
+ *   .setHeader('x-tenant', 'acme')
+ *   .setTimeout(5000)
+ *   .build();
+ *
+ * client.send('get.user', record);
+ * ```
+ */
+declare class JetstreamRecord<TData = unknown> {
+    readonly data: TData;
+    readonly headers: ReadonlyMap<string, string>;
+    readonly timeout?: number | undefined;
+    constructor(data: TData, headers: ReadonlyMap<string, string>, timeout?: number | undefined);
+}
+/**
+ * Fluent builder for constructing JetstreamRecord instances.
+ *
+ * Protected headers (`correlation-id`, `reply-to`, `error`) cannot be
+ * set by the user — attempting to do so throws an error at build time.
+ */
+declare class JetstreamRecordBuilder<TData = unknown> {
+    private data;
+    private readonly headers;
+    private timeout;
+    constructor(data?: TData);
+    /** Set the message payload. */
+    setData(data: TData): this;
+    /**
+     * Set a single custom header.
+     *
+     * @throws Error if the header name is reserved by the transport.
+     */
+    setHeader(key: string, value: string): this;
+    /**
+     * Set multiple custom headers at once.
+     *
+     * @throws Error if any header name is reserved by the transport.
+     */
+    setHeaders(headers: Record<string, string>): this;
+    /** Set RPC request timeout in milliseconds. */
+    setTimeout(ms: number): this;
+    /** Build the immutable JetstreamRecord. */
+    build(): JetstreamRecord<TData>;
+    /** Validate that a header key is not reserved. */
+    private validateHeaderKey;
+}
+
+/**
+ * Default JSON codec wrapping the nats.js JSONCodec.
+ *
+ * Serializes to/from JSON using the native NATS implementation
+ * which handles `TextEncoder`/`TextDecoder` internally.
+ *
+ * @example
+ * ```typescript
+ * const codec = new JsonCodec();
+ * const bytes = codec.encode({ hello: 'world' });
+ * const data = codec.decode(bytes); // { hello: 'world' }
+ * ```
+ */
+declare class JsonCodec implements Codec {
+    private readonly inner;
+    encode(data: unknown): Uint8Array;
+    decode(data: Uint8Array): unknown;
+}
+
+type NatsMessage = JsMsg | Msg;
+/**
+ * Execution context for RPC and event handlers.
+ *
+ * Provides convenient accessors for the NATS message, subject,
+ * and headers without needing to interact with the raw message directly.
+ *
+ * @example
+ * ```typescript
+ * @MessagePattern('get.user')
+ * getUser(data: GetUserDto, @Ctx() ctx: RpcContext) {
+ *   const traceId = ctx.getHeader('x-trace-id');
+ *   const subject = ctx.getSubject();
+ *   return this.userService.findOne(data.id);
+ * }
+ * ```
+ */
+declare class RpcContext extends BaseRpcContext<[NatsMessage]> {
+    /** Get the underlying NATS message (JsMsg for JetStream, Msg for Core). */
+    getMessage(): NatsMessage;
+    /** Get the NATS subject this message was published to. */
+    getSubject(): string;
+    /** Get all NATS message headers, or undefined if none are present. */
+    getHeaders(): MsgHdrs | undefined;
+    /** Get a single header value by key. Returns undefined if the header or headers object is missing. */
+    getHeader(key: string): string | undefined;
+    /** Type guard: narrows getMessage() return type to JsMsg when true. */
+    isJetStream(): this is RpcContext & {
+        getMessage(): JsMsg;
+    };
+}
+
+/**
+ * Health status returned by `check()`.
+ */
+interface JetstreamHealthStatus {
+    connected: boolean;
+    server: string | null;
+    /** Round-trip latency in ms (null if disconnected). */
+    latency: number | null;
+}
+/**
+ * Health indicator result compatible with @nestjs/terminus.
+ *
+ * Follows the Terminus convention: returns status object on success,
+ * throws on failure. Works with Terminus out of the box — no wrapper needed:
+ *
+ * @example
+ * ```typescript
+ * // With Terminus
+ * this.health.check([() => this.jetstream.isHealthy()])
+ *
+ * // Standalone
+ * const status = await this.jetstream.check();
+ * ```
+ */
+declare class JetstreamHealthIndicator {
+    private readonly connection;
+    private readonly logger;
+    constructor(connection: ConnectionProvider);
+    /**
+     * Plain health status check.
+     *
+     * Returns the current connection status without throwing.
+     * Use this for custom health endpoints or monitoring integrations.
+     */
+    check(): Promise<JetstreamHealthStatus>;
+    /**
+     * Terminus-compatible health check.
+     *
+     * Returns `{ [key]: { status: 'up', ... } }` on success.
+     * Throws an error with `{ [key]: { status: 'down', ... } }` on failure.
+     *
+     * @param key Health indicator key (default: 'jetstream')
+     */
+    isHealthy(key?: string): Promise<Record<string, Record<string, unknown>>>;
+}
+
+/** Token for the resolved JetstreamModuleOptions. */
+declare const JETSTREAM_OPTIONS: unique symbol;
+/** Token for the shared ConnectionProvider instance. */
+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 a unique injection token for a forFeature client.
+ * This is what users inject with `@Inject('service-name')`.
+ */
+declare const getClientToken: (name: string) => string;
+/** Convert milliseconds to nanoseconds (NATS JetStream format). */
+declare const nanos: (ms: number) => number;
+/** NATS headers managed by the transport. Users cannot overwrite these. */
+declare enum JetstreamHeader {
+    CorrelationId = "x-correlation-id",
+    ReplyTo = "x-reply-to",
+    Subject = "x-subject",
+    CallerName = "x-caller-name",
+    RequestId = "x-request-id",
+    TraceId = "x-trace-id",
+    SpanId = "x-span-id",
+    /** Set to 'true' on error responses so the client can distinguish success from failure. */
+    Error = "x-error"
+}
+
+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, type RpcConfig, RpcContext, type StreamConsumerOverrides, TransportEvent, type TransportHooks, getClientToken, nanos };