@horizon-republic/nestjs-jetstream 2.6.1 → 2.7.1

package/dist/index.d.cts

@@ -346,6 +346,13 @@ declare enum StreamKind {
     Broadcast = "broadcast",
     Ordered = "ordered"
 }
+/**
+ * Subset of {@link StreamKind} used for direct subject building.
+ *
+ * Excludes `Broadcast` because broadcast subjects use a different
+ * naming convention (`broadcast.{pattern}` instead of `{service}.{kind}.{pattern}`).
+ */
+type SubjectKind = Exclude<StreamKind, StreamKind.Broadcast>;
 
 /** @internal Grouped pattern lists by stream kind, used for stream/consumer setup. */
 interface PatternsByKind {
@@ -416,6 +423,12 @@ declare class EventBus {
      * @param args - Arguments matching the hook signature for this event.
      */
     emit<K extends keyof TransportHooks>(event: K, ...args: Parameters<TransportHooks[K]>): void;
+    /**
+     * Hot-path optimized emit for MessageRouted events.
+     * Avoids rest/spread overhead of the generic `emit()`.
+     */
+    emitMessageRouted(subject: string, kind: MessageKind): void;
+    private callHook;
 }
 
 /**
@@ -491,6 +504,10 @@ declare class PatternRegistry {
     private readonly logger;
     private readonly registry;
     private cachedPatterns;
+    private _hasEvents;
+    private _hasCommands;
+    private _hasBroadcasts;
+    private _hasOrdered;
     constructor(options: JetstreamModuleOptions);
     /**
      * Register all handlers from the NestJS strategy.
@@ -613,10 +630,10 @@ declare class EventRouter {
     private subscribeToStream;
     private getConcurrency;
     private getAckExtensionConfig;
-    /** Handle a single event message: decode -> execute handler -> ack/nak. */
-    private handle;
-    /** Handle an ordered message: decode -> execute handler -> no ack/nak. */
-    private handleOrdered;
+    /** 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. */
@@ -652,15 +669,16 @@ declare class RpcRouter {
     private readonly concurrency;
     private resolvedAckExtensionInterval;
     private subscription;
+    private cachedNc;
     constructor(messageProvider: MessageProvider, patternRegistry: PatternRegistry, connection: ConnectionProvider, codec: Codec, eventBus: EventBus, rpcOptions?: RpcRouterOptions | undefined, ackWaitMap?: Map<StreamKind, number> | undefined);
     /** Lazily resolve the ack extension interval (needs ackWaitMap populated at runtime). */
     private get ackExtensionInterval();
     /** Start routing command messages to handlers. */
-    start(): void;
+    start(): Promise<void>;
     /** Stop routing and unsubscribe. */
     destroy(): void;
-    /** Handle a single RPC command message. */
-    private handle;
+    /** Handle a single RPC command message with error isolation. */
+    private handleSafe;
     /** Execute handler, publish response, settle message. */
     private executeHandler;
 }
@@ -1137,19 +1155,33 @@ 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.
+ * headers, and JetStream metadata without needing to interact
+ * with the raw message directly.
+ *
+ * Handlers can also control message settlement via {@link retry}
+ * and {@link terminate} instead of throwing errors.
  *
  * @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);
+ * @EventPattern('order.process')
+ * async handle(@Payload() data: OrderDto, @Ctx() ctx: RpcContext) {
+ *   if (ctx.getDeliveryCount()! >= 3) {
+ *     ctx.terminate('Max business retries exceeded');
+ *     return;
+ *   }
+ *   if (!this.isReady()) {
+ *     ctx.retry({ delay: 5000 });
+ *     return;
+ *   }
+ *   await this.process(data);
  * }
  * ```
  */
 declare class RpcContext extends BaseRpcContext<[NatsMessage]> {
+    private _shouldRetry;
+    private _retryDelay;
+    private _shouldTerminate;
+    private _terminateReason;
     /**
      * Get the underlying NATS message.
      *
@@ -1176,6 +1208,50 @@ declare class RpcContext extends BaseRpcContext<[NatsMessage]> {
     isJetStream(): this is RpcContext & {
         getMessage(): JsMsg;
     };
+    /** How many times this message has been delivered. */
+    getDeliveryCount(): number | undefined;
+    /** The JetStream stream this message belongs to. */
+    getStream(): string | undefined;
+    /** The stream sequence number. */
+    getSequence(): number | undefined;
+    /** The message timestamp as a `Date` (derived from `info.timestampNanos`). */
+    getTimestamp(): Date | undefined;
+    /** The name of the service that published this message (from `x-caller-name` header). */
+    getCallerName(): string | undefined;
+    /**
+     * Signal the transport to retry (nak) this message instead of acknowledging it.
+     *
+     * Use for business-level retries without throwing errors.
+     * Only affects JetStream event handlers (workqueue/broadcast).
+     *
+     * @param opts - Optional delay in ms before redelivery.
+     * @throws Error if {@link terminate} was already called.
+     */
+    retry(opts?: {
+        delayMs?: number;
+    }): void;
+    /**
+     * Signal the transport to permanently reject (term) this message.
+     *
+     * Use when a message is no longer relevant and should not be retried or sent to DLQ.
+     * Only affects JetStream event handlers (workqueue/broadcast).
+     *
+     * @param reason - Optional reason for termination (logged by NATS).
+     * @throws Error if {@link retry} was already called.
+     */
+    terminate(reason?: string): void;
+    /** Narrow to JsMsg or return null for Core messages. Used by metadata getters. */
+    private asJetStream;
+    /** Ensure the message is JetStream — settlement actions are not available for Core NATS. */
+    private assertJetStream;
+    /** @internal */
+    get shouldRetry(): boolean;
+    /** @internal */
+    get retryDelay(): number | undefined;
+    /** @internal */
+    get shouldTerminate(): boolean;
+    /** @internal */
+    get terminateReason(): string | undefined;
 }
 
 /**
@@ -1278,6 +1354,38 @@ declare enum JetstreamHeader {
     /** Set to `'true'` on error responses so the client can distinguish success from failure. */
     Error = "x-error"
 }
+/**
+ * Build the internal service name with microservice suffix.
+ *
+ * @param name - Service name from `forRoot({ name })`.
+ * @returns `{name}__microservice`
+ */
+declare const internalName: (name: string) => string;
+/**
+ * Build a fully-qualified NATS subject for workqueue events, RPC commands, or ordered events.
+ *
+ * @param serviceName - Target service name.
+ * @param kind - Subject kind (`'ev'`, `'cmd'`, or `'ordered'`).
+ * @param pattern - The message pattern (e.g. `'user.created'`).
+ * @returns `{serviceName}__microservice.{kind}.{pattern}`
+ */
+declare const buildSubject: (serviceName: string, kind: SubjectKind, pattern: string) => string;
+/**
+ * Build the JetStream stream name for a given service and kind.
+ *
+ * @param serviceName - Service name from `forRoot({ name })`.
+ * @param kind - Stream kind (`'ev'`, `'cmd'`, or `'broadcast'`).
+ * @returns Stream name (e.g. `orders__microservice_ev-stream` or `broadcast-stream`).
+ */
+declare const streamName: (serviceName: string, kind: StreamKind) => string;
+/**
+ * Build the JetStream consumer name for a given service and kind.
+ *
+ * @param serviceName - Service name from `forRoot({ name })`.
+ * @param kind - Stream kind (`'ev'`, `'cmd'`, or `'broadcast'`).
+ * @returns Consumer name (e.g. `orders__microservice_ev-consumer`).
+ */
+declare const consumerName: (serviceName: string, kind: StreamKind) => string;
 /**
  * Prefixes used in event patterns to route to specific stream types.
  * Applied by the user when emitting events (e.g. `client.emit('broadcast:config.updated', data)`).
@@ -1293,4 +1401,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 StreamConsumerOverrides, StreamKind, TransportEvent, type TransportHooks, getClientToken, isCoreRpcMode, isJetStreamRpcMode, toNanos };
+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 StreamConsumerOverrides, StreamKind, TransportEvent, type TransportHooks, buildSubject, consumerName, getClientToken, internalName, isCoreRpcMode, isJetStreamRpcMode, streamName, toNanos };

package/dist/index.d.ts

@@ -346,6 +346,13 @@ declare enum StreamKind {
     Broadcast = "broadcast",
     Ordered = "ordered"
 }
+/**
+ * Subset of {@link StreamKind} used for direct subject building.
+ *
+ * Excludes `Broadcast` because broadcast subjects use a different
+ * naming convention (`broadcast.{pattern}` instead of `{service}.{kind}.{pattern}`).
+ */
+type SubjectKind = Exclude<StreamKind, StreamKind.Broadcast>;
 
 /** @internal Grouped pattern lists by stream kind, used for stream/consumer setup. */
 interface PatternsByKind {
@@ -416,6 +423,12 @@ declare class EventBus {
      * @param args - Arguments matching the hook signature for this event.
      */
     emit<K extends keyof TransportHooks>(event: K, ...args: Parameters<TransportHooks[K]>): void;
+    /**
+     * Hot-path optimized emit for MessageRouted events.
+     * Avoids rest/spread overhead of the generic `emit()`.
+     */
+    emitMessageRouted(subject: string, kind: MessageKind): void;
+    private callHook;
 }
 
 /**
@@ -491,6 +504,10 @@ declare class PatternRegistry {
     private readonly logger;
     private readonly registry;
     private cachedPatterns;
+    private _hasEvents;
+    private _hasCommands;
+    private _hasBroadcasts;
+    private _hasOrdered;
     constructor(options: JetstreamModuleOptions);
     /**
      * Register all handlers from the NestJS strategy.
@@ -613,10 +630,10 @@ declare class EventRouter {
     private subscribeToStream;
     private getConcurrency;
     private getAckExtensionConfig;
-    /** Handle a single event message: decode -> execute handler -> ack/nak. */
-    private handle;
-    /** Handle an ordered message: decode -> execute handler -> no ack/nak. */
-    private handleOrdered;
+    /** 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. */
@@ -652,15 +669,16 @@ declare class RpcRouter {
     private readonly concurrency;
     private resolvedAckExtensionInterval;
     private subscription;
+    private cachedNc;
     constructor(messageProvider: MessageProvider, patternRegistry: PatternRegistry, connection: ConnectionProvider, codec: Codec, eventBus: EventBus, rpcOptions?: RpcRouterOptions | undefined, ackWaitMap?: Map<StreamKind, number> | undefined);
     /** Lazily resolve the ack extension interval (needs ackWaitMap populated at runtime). */
     private get ackExtensionInterval();
     /** Start routing command messages to handlers. */
-    start(): void;
+    start(): Promise<void>;
     /** Stop routing and unsubscribe. */
     destroy(): void;
-    /** Handle a single RPC command message. */
-    private handle;
+    /** Handle a single RPC command message with error isolation. */
+    private handleSafe;
     /** Execute handler, publish response, settle message. */
     private executeHandler;
 }
@@ -1137,19 +1155,33 @@ 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.
+ * headers, and JetStream metadata without needing to interact
+ * with the raw message directly.
+ *
+ * Handlers can also control message settlement via {@link retry}
+ * and {@link terminate} instead of throwing errors.
  *
  * @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);
+ * @EventPattern('order.process')
+ * async handle(@Payload() data: OrderDto, @Ctx() ctx: RpcContext) {
+ *   if (ctx.getDeliveryCount()! >= 3) {
+ *     ctx.terminate('Max business retries exceeded');
+ *     return;
+ *   }
+ *   if (!this.isReady()) {
+ *     ctx.retry({ delay: 5000 });
+ *     return;
+ *   }
+ *   await this.process(data);
  * }
  * ```
  */
 declare class RpcContext extends BaseRpcContext<[NatsMessage]> {
+    private _shouldRetry;
+    private _retryDelay;
+    private _shouldTerminate;
+    private _terminateReason;
     /**
      * Get the underlying NATS message.
      *
@@ -1176,6 +1208,50 @@ declare class RpcContext extends BaseRpcContext<[NatsMessage]> {
     isJetStream(): this is RpcContext & {
         getMessage(): JsMsg;
     };
+    /** How many times this message has been delivered. */
+    getDeliveryCount(): number | undefined;
+    /** The JetStream stream this message belongs to. */
+    getStream(): string | undefined;
+    /** The stream sequence number. */
+    getSequence(): number | undefined;
+    /** The message timestamp as a `Date` (derived from `info.timestampNanos`). */
+    getTimestamp(): Date | undefined;
+    /** The name of the service that published this message (from `x-caller-name` header). */
+    getCallerName(): string | undefined;
+    /**
+     * Signal the transport to retry (nak) this message instead of acknowledging it.
+     *
+     * Use for business-level retries without throwing errors.
+     * Only affects JetStream event handlers (workqueue/broadcast).
+     *
+     * @param opts - Optional delay in ms before redelivery.
+     * @throws Error if {@link terminate} was already called.
+     */
+    retry(opts?: {
+        delayMs?: number;
+    }): void;
+    /**
+     * Signal the transport to permanently reject (term) this message.
+     *
+     * Use when a message is no longer relevant and should not be retried or sent to DLQ.
+     * Only affects JetStream event handlers (workqueue/broadcast).
+     *
+     * @param reason - Optional reason for termination (logged by NATS).
+     * @throws Error if {@link retry} was already called.
+     */
+    terminate(reason?: string): void;
+    /** Narrow to JsMsg or return null for Core messages. Used by metadata getters. */
+    private asJetStream;
+    /** Ensure the message is JetStream — settlement actions are not available for Core NATS. */
+    private assertJetStream;
+    /** @internal */
+    get shouldRetry(): boolean;
+    /** @internal */
+    get retryDelay(): number | undefined;
+    /** @internal */
+    get shouldTerminate(): boolean;
+    /** @internal */
+    get terminateReason(): string | undefined;
 }
 
 /**
@@ -1278,6 +1354,38 @@ declare enum JetstreamHeader {
     /** Set to `'true'` on error responses so the client can distinguish success from failure. */
     Error = "x-error"
 }
+/**
+ * Build the internal service name with microservice suffix.
+ *
+ * @param name - Service name from `forRoot({ name })`.
+ * @returns `{name}__microservice`
+ */
+declare const internalName: (name: string) => string;
+/**
+ * Build a fully-qualified NATS subject for workqueue events, RPC commands, or ordered events.
+ *
+ * @param serviceName - Target service name.
+ * @param kind - Subject kind (`'ev'`, `'cmd'`, or `'ordered'`).
+ * @param pattern - The message pattern (e.g. `'user.created'`).
+ * @returns `{serviceName}__microservice.{kind}.{pattern}`
+ */
+declare const buildSubject: (serviceName: string, kind: SubjectKind, pattern: string) => string;
+/**
+ * Build the JetStream stream name for a given service and kind.
+ *
+ * @param serviceName - Service name from `forRoot({ name })`.
+ * @param kind - Stream kind (`'ev'`, `'cmd'`, or `'broadcast'`).
+ * @returns Stream name (e.g. `orders__microservice_ev-stream` or `broadcast-stream`).
+ */
+declare const streamName: (serviceName: string, kind: StreamKind) => string;
+/**
+ * Build the JetStream consumer name for a given service and kind.
+ *
+ * @param serviceName - Service name from `forRoot({ name })`.
+ * @param kind - Stream kind (`'ev'`, `'cmd'`, or `'broadcast'`).
+ * @returns Consumer name (e.g. `orders__microservice_ev-consumer`).
+ */
+declare const consumerName: (serviceName: string, kind: StreamKind) => string;
 /**
  * Prefixes used in event patterns to route to specific stream types.
  * Applied by the user when emitting events (e.g. `client.emit('broadcast:config.updated', data)`).
@@ -1293,4 +1401,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 StreamConsumerOverrides, StreamKind, TransportEvent, type TransportHooks, getClientToken, isCoreRpcMode, isJetStreamRpcMode, toNanos };
+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 StreamConsumerOverrides, StreamKind, TransportEvent, type TransportHooks, buildSubject, consumerName, getClientToken, internalName, isCoreRpcMode, isJetStreamRpcMode, streamName, toNanos };