@horizon-republic/nestjs-jetstream 2.7.0 → 2.8.0

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import { ModuleMetadata, FactoryProvider, Type, Logger, OnApplicationShutdown, DynamicModule } from '@nestjs/common';
-import { MsgHdrs, StreamConfig, ConsumerConfig, ConsumeOptions, DeliverPolicy, ReplayPolicy, ConnectionOptions, NatsConnection, Status, JetStreamManager, JetStreamClient, ConsumerInfo, JsMsg, Msg } from 'nats';
+import { MsgHdrs, ConnectionOptions, NatsConnection, Status, Msg } from '@nats-io/transport-node';
+import { StreamConfig, ConsumerConfig, ConsumeOptions, DeliverPolicy, ReplayPolicy, JetStreamManager, JetStreamClient, ConsumerInfo, JsMsg } from '@nats-io/jetstream';
 import { MessageHandler, Server, CustomTransportStrategy, ClientProxy, ReadPacket, WritePacket, BaseRpcContext } from '@nestjs/microservices';
 import { Observable } from 'rxjs';
 
@@ -346,6 +347,19 @@ 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>;
+
+/** Options for one-shot delayed delivery via NATS 2.12 message scheduling. */
+interface ScheduleRecordOptions {
+    /** When to deliver the message. Must be in the future. */
+    at: Date;
+}
 
 /** @internal Grouped pattern lists by stream kind, used for stream/consumer setup. */
 interface PatternsByKind {
@@ -478,6 +492,7 @@ declare class ConnectionProvider {
      * Sequence: drain → wait for close. Falls back to force-close on error.
      */
     shutdown(): Promise<void>;
+    private initJetStreamManager;
     /** Internal: establish the physical connection with reconnect monitoring. */
     private establish;
     /** Subscribe to connection status events and emit hooks. */
@@ -585,6 +600,8 @@ declare class StreamProvider {
     private buildConfig;
     /** 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. */
     private getOverrides;
 }
@@ -990,7 +1007,9 @@ declare class JetstreamClient extends ClientProxy {
      * Publish a fire-and-forget event to JetStream.
      *
      * Events are published to either the workqueue stream or broadcast stream
-     * depending on the subject prefix.
+     * depending on the subject prefix. When a schedule is present the message
+     * is published to a `_sch` subject within the same stream, with the target
+     * set to the original event subject.
      */
     protected dispatchEvent<T = unknown>(packet: ReadPacket): Promise<T>;
     /**
@@ -1016,8 +1035,20 @@ declare class JetstreamClient extends ClientProxy {
     private buildEventSubject;
     /** Build NATS headers merging custom headers with transport headers. */
     private buildHeaders;
-    /** Extract data, headers, and timeout from raw packet data or JetstreamRecord. */
+    /** Extract data, headers, timeout, and schedule from raw packet data or JetstreamRecord. */
     private extractRecordData;
+    /**
+     * Build a schedule-holder subject for NATS message scheduling.
+     *
+     * The schedule-holder subject resides in the same stream as the target but
+     * uses a separate `_sch` namespace that is NOT matched by any consumer filter.
+     * NATS holds the message and publishes it to the target subject after the delay.
+     *
+     * Examples:
+     * - `{svc}__microservice.ev.order.reminder` → `{svc}__microservice._sch.order.reminder`
+     * - `broadcast.config.updated` → `broadcast._sch.config.updated`
+     */
+    private buildScheduleSubject;
     private getRpcTimeout;
 }
 
@@ -1046,6 +1077,8 @@ declare class JetstreamRecord<TData = unknown> {
     readonly timeout?: number | undefined;
     /** Custom message ID for JetStream deduplication. */
     readonly messageId?: string | undefined;
+    /** Schedule options for delayed delivery. */
+    readonly schedule?: ScheduleRecordOptions | undefined;
     constructor(
     /** Message payload. */
     data: TData, 
@@ -1054,7 +1087,9 @@ declare class JetstreamRecord<TData = unknown> {
     /** Per-request RPC timeout override in ms. */
     timeout?: number | undefined, 
     /** Custom message ID for JetStream deduplication. */
-    messageId?: string | undefined);
+    messageId?: string | undefined, 
+    /** Schedule options for delayed delivery. */
+    schedule?: ScheduleRecordOptions | undefined);
 }
 /**
  * Fluent builder for constructing JetstreamRecord instances.
@@ -1067,6 +1102,7 @@ declare class JetstreamRecordBuilder<TData = unknown> {
     private readonly headers;
     private timeout;
     private messageId;
+    private scheduleOptions;
     constructor(data?: TData);
     /**
      * Set the message payload.
@@ -1114,6 +1150,20 @@ declare class JetstreamRecordBuilder<TData = unknown> {
      * @param ms - Timeout in milliseconds. Overrides the global RPC timeout for this request only.
      */
     setTimeout(ms: number): this;
+    /**
+     * Schedule one-shot delayed delivery.
+     *
+     * The message is held by NATS and delivered to the event consumer
+     * at the specified time. Requires NATS >= 2.12 and `allow_msg_schedules: true`
+     * on the event stream (via `events: { stream: { allow_msg_schedules: true } }`).
+     *
+     * Only meaningful for events (`client.emit()`). If used with RPC
+     * (`client.send()`), a warning is logged and the schedule is ignored.
+     *
+     * @param date - Delivery time. Must be in the future.
+     * @throws Error if the date is not in the future.
+     */
+    scheduleAt(date: Date): this;
     /**
      * Build the immutable {@link JetstreamRecord}.
      *
@@ -1125,10 +1175,10 @@ declare class JetstreamRecordBuilder<TData = unknown> {
 }
 
 /**
- * Default JSON codec wrapping the nats.js JSONCodec.
+ * Default JSON codec using native `TextEncoder`/`TextDecoder`.
  *
- * Serializes to/from JSON using the native NATS implementation
- * which handles `TextEncoder`/`TextDecoder` internally.
+ * Serializes values to JSON via `JSON.stringify` and encodes the
+ * resulting string into a `Uint8Array`. Decoding reverses the process.
  *
  * @example
  * ```typescript
@@ -1138,7 +1188,6 @@ declare class JetstreamRecordBuilder<TData = unknown> {
  * ```
  */
 declare class JsonCodec implements Codec {
-    private readonly inner;
     encode(data: unknown): Uint8Array;
     decode(data: Uint8Array): unknown;
 }
@@ -1347,6 +1396,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 ({@link StreamKind.Event}, {@link StreamKind.Command}, or {@link StreamKind.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 ({@link StreamKind}).
+ * @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 ({@link StreamKind}).
+ * @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)`).
@@ -1362,4 +1443,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 ScheduleRecordOptions, type StreamConsumerOverrides, StreamKind, TransportEvent, type TransportHooks, buildSubject, consumerName, getClientToken, internalName, isCoreRpcMode, isJetStreamRpcMode, streamName, toNanos };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { ModuleMetadata, FactoryProvider, Type, Logger, OnApplicationShutdown, DynamicModule } from '@nestjs/common';
-import { MsgHdrs, StreamConfig, ConsumerConfig, ConsumeOptions, DeliverPolicy, ReplayPolicy, ConnectionOptions, NatsConnection, Status, JetStreamManager, JetStreamClient, ConsumerInfo, JsMsg, Msg } from 'nats';
+import { MsgHdrs, ConnectionOptions, NatsConnection, Status, Msg } from '@nats-io/transport-node';
+import { StreamConfig, ConsumerConfig, ConsumeOptions, DeliverPolicy, ReplayPolicy, JetStreamManager, JetStreamClient, ConsumerInfo, JsMsg } from '@nats-io/jetstream';
 import { MessageHandler, Server, CustomTransportStrategy, ClientProxy, ReadPacket, WritePacket, BaseRpcContext } from '@nestjs/microservices';
 import { Observable } from 'rxjs';
 
@@ -346,6 +347,19 @@ 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>;
+
+/** Options for one-shot delayed delivery via NATS 2.12 message scheduling. */
+interface ScheduleRecordOptions {
+    /** When to deliver the message. Must be in the future. */
+    at: Date;
+}
 
 /** @internal Grouped pattern lists by stream kind, used for stream/consumer setup. */
 interface PatternsByKind {
@@ -478,6 +492,7 @@ declare class ConnectionProvider {
      * Sequence: drain → wait for close. Falls back to force-close on error.
      */
     shutdown(): Promise<void>;
+    private initJetStreamManager;
     /** Internal: establish the physical connection with reconnect monitoring. */
     private establish;
     /** Subscribe to connection status events and emit hooks. */
@@ -585,6 +600,8 @@ declare class StreamProvider {
     private buildConfig;
     /** 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. */
     private getOverrides;
 }
@@ -990,7 +1007,9 @@ declare class JetstreamClient extends ClientProxy {
      * Publish a fire-and-forget event to JetStream.
      *
      * Events are published to either the workqueue stream or broadcast stream
-     * depending on the subject prefix.
+     * depending on the subject prefix. When a schedule is present the message
+     * is published to a `_sch` subject within the same stream, with the target
+     * set to the original event subject.
      */
     protected dispatchEvent<T = unknown>(packet: ReadPacket): Promise<T>;
     /**
@@ -1016,8 +1035,20 @@ declare class JetstreamClient extends ClientProxy {
     private buildEventSubject;
     /** Build NATS headers merging custom headers with transport headers. */
     private buildHeaders;
-    /** Extract data, headers, and timeout from raw packet data or JetstreamRecord. */
+    /** Extract data, headers, timeout, and schedule from raw packet data or JetstreamRecord. */
     private extractRecordData;
+    /**
+     * Build a schedule-holder subject for NATS message scheduling.
+     *
+     * The schedule-holder subject resides in the same stream as the target but
+     * uses a separate `_sch` namespace that is NOT matched by any consumer filter.
+     * NATS holds the message and publishes it to the target subject after the delay.
+     *
+     * Examples:
+     * - `{svc}__microservice.ev.order.reminder` → `{svc}__microservice._sch.order.reminder`
+     * - `broadcast.config.updated` → `broadcast._sch.config.updated`
+     */
+    private buildScheduleSubject;
     private getRpcTimeout;
 }
 
@@ -1046,6 +1077,8 @@ declare class JetstreamRecord<TData = unknown> {
     readonly timeout?: number | undefined;
     /** Custom message ID for JetStream deduplication. */
     readonly messageId?: string | undefined;
+    /** Schedule options for delayed delivery. */
+    readonly schedule?: ScheduleRecordOptions | undefined;
     constructor(
     /** Message payload. */
     data: TData, 
@@ -1054,7 +1087,9 @@ declare class JetstreamRecord<TData = unknown> {
     /** Per-request RPC timeout override in ms. */
     timeout?: number | undefined, 
     /** Custom message ID for JetStream deduplication. */
-    messageId?: string | undefined);
+    messageId?: string | undefined, 
+    /** Schedule options for delayed delivery. */
+    schedule?: ScheduleRecordOptions | undefined);
 }
 /**
  * Fluent builder for constructing JetstreamRecord instances.
@@ -1067,6 +1102,7 @@ declare class JetstreamRecordBuilder<TData = unknown> {
     private readonly headers;
     private timeout;
     private messageId;
+    private scheduleOptions;
     constructor(data?: TData);
     /**
      * Set the message payload.
@@ -1114,6 +1150,20 @@ declare class JetstreamRecordBuilder<TData = unknown> {
      * @param ms - Timeout in milliseconds. Overrides the global RPC timeout for this request only.
      */
     setTimeout(ms: number): this;
+    /**
+     * Schedule one-shot delayed delivery.
+     *
+     * The message is held by NATS and delivered to the event consumer
+     * at the specified time. Requires NATS >= 2.12 and `allow_msg_schedules: true`
+     * on the event stream (via `events: { stream: { allow_msg_schedules: true } }`).
+     *
+     * Only meaningful for events (`client.emit()`). If used with RPC
+     * (`client.send()`), a warning is logged and the schedule is ignored.
+     *
+     * @param date - Delivery time. Must be in the future.
+     * @throws Error if the date is not in the future.
+     */
+    scheduleAt(date: Date): this;
     /**
      * Build the immutable {@link JetstreamRecord}.
      *
@@ -1125,10 +1175,10 @@ declare class JetstreamRecordBuilder<TData = unknown> {
 }
 
 /**
- * Default JSON codec wrapping the nats.js JSONCodec.
+ * Default JSON codec using native `TextEncoder`/`TextDecoder`.
  *
- * Serializes to/from JSON using the native NATS implementation
- * which handles `TextEncoder`/`TextDecoder` internally.
+ * Serializes values to JSON via `JSON.stringify` and encodes the
+ * resulting string into a `Uint8Array`. Decoding reverses the process.
  *
  * @example
  * ```typescript
@@ -1138,7 +1188,6 @@ declare class JetstreamRecordBuilder<TData = unknown> {
  * ```
  */
 declare class JsonCodec implements Codec {
-    private readonly inner;
     encode(data: unknown): Uint8Array;
     decode(data: Uint8Array): unknown;
 }
@@ -1347,6 +1396,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 ({@link StreamKind.Event}, {@link StreamKind.Command}, or {@link StreamKind.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 ({@link StreamKind}).
+ * @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 ({@link StreamKind}).
+ * @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)`).
@@ -1362,4 +1443,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 ScheduleRecordOptions, type StreamConsumerOverrides, StreamKind, TransportEvent, type TransportHooks, buildSubject, consumerName, getClientToken, internalName, isCoreRpcMode, isJetStreamRpcMode, streamName, toNanos };