@horizon-republic/nestjs-jetstream 1.0.4

package/dist/server/providers/message.provider.js

@@ -0,0 +1,209 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var MessageProvider_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MessageProvider = void 0;
+const common_1 = require("@nestjs/common");
+const rxjs_1 = require("rxjs");
+const connection_provider_1 = require("../../common/connection.provider");
+const enum_1 = require("../../enum");
+const consumer_provider_1 = require("./consumer.provider");
+/**
+ * Manages NATS JetStream pull-based message consumption with automatic reconnection.
+ *
+ * This provider orchestrates the lifecycle of JetStream consumers, handling:
+ * - Initial consumer setup and subscription
+ * - Automatic recovery from NATS restarts or connection failures
+ * - Separate handling for Event and Command (RPC) messages
+ * - Graceful shutdown and resource cleanup.
+ *
+ * The implementation uses RxJS `defer()` + `repeat()` pattern to ensure consumers
+ * automatically restart after the async iterator completes (e.g., during NATS restart),
+ * preventing message loss during reconnection windows.
+ *
+ * Message flow:
+ * - Event messages → eventMessages$ subject (ack immediately)
+ * - Command messages → commandMessages$ subject (ack after handler success).
+ */
+let MessageProvider = MessageProvider_1 = class MessageProvider {
+    /**
+     * Initializes pull consumers for both Event and Command streams.
+     *
+     * Uses `take(1)` on a consumer map to prevent recreating observables on every
+     * reconnection event. Each consumer observable handles its own reconnection logic
+     * through the `repeat()` operator, ensuring continuous message delivery even
+     * when NATS restarts.
+     *
+     * @param connectionProvider Connection provider.
+     * @param consumerProvider Consumer provider.
+     */
+    constructor(connectionProvider, consumerProvider) {
+        this.connectionProvider = connectionProvider;
+        this.consumerProvider = consumerProvider;
+        this.logger = new common_1.Logger(MessageProvider_1.name);
+        this.destroy$ = new rxjs_1.Subject();
+        /**
+         * Subject for Event pattern messages.
+         * Events are acknowledged immediately upon receipt, regardless of handler outcome.
+         */
+        this.eventMessages$ = new rxjs_1.Subject();
+        /**
+         * Subject for Command (RPC) pattern messages.
+         * Commands are acknowledged only after successful handler execution.
+         */
+        this.commandMessages$ = new rxjs_1.Subject();
+        this.subscription = this.consumerProvider.consumerMap$
+            .pipe((0, rxjs_1.take)(1), // Only subscribe once to prevent observer recreation on reconnects
+        (0, rxjs_1.switchMap)((consumerMap) => this.initializeConsumers(consumerMap)), (0, rxjs_1.takeUntil)(this.destroy$))
+            .subscribe();
+    }
+    /**
+     * Observable stream of Event messages for handler processing.
+     * Events should be acknowledged immediately after emission.
+     *
+     * @returns Observable<JsMsg> of Event messages.
+     */
+    get events$() {
+        return this.eventMessages$.asObservable();
+    }
+    /**
+     * Observable stream of Command (RPC) messages for handler processing.
+     * Commands should be acknowledged after successful handler execution.
+     *
+     * @returns Observable<JsMsg> of Command messages.
+     */
+    get commands$() {
+        return this.commandMessages$.asObservable();
+    }
+    /**
+     * Cleans up resources on module destruction.
+     *
+     * Completes all subjects and the destroy$ subject to stop all active subscriptions
+     * and explicitly unsubscribes from the main subscription.
+     */
+    onModuleDestroy() {
+        this.destroy$.next();
+        this.destroy$.complete();
+        this.eventMessages$.complete();
+        this.commandMessages$.complete();
+        this.subscription?.unsubscribe();
+    }
+    /**
+     * Initializes and starts consumer flows for available stream types.
+     *
+     * Creates separate observable flows for Event and Command consumers,
+     * each pushing messages to their respective subjects. Returns a merged
+     * observable that completes only when all consumers are done.
+     *
+     * @param consumerMap Map of consumer info by stream kind.
+     * @returns Observable that completes when all consumers are initialized.
+     */
+    initializeConsumers(consumerMap) {
+        const flows = [];
+        const evConsumer = consumerMap.get(enum_1.JetStreamKind.Event);
+        const cmdConsumer = consumerMap.get(enum_1.JetStreamKind.Command);
+        if (evConsumer)
+            flows.push(this.createConsumerFlow(evConsumer, enum_1.JetStreamKind.Event));
+        if (cmdConsumer)
+            flows.push(this.createConsumerFlow(cmdConsumer, enum_1.JetStreamKind.Command));
+        return (0, rxjs_1.merge)(...flows).pipe((0, rxjs_1.takeUntil)(this.destroy$));
+    }
+    /**
+     * Creates a self-healing consumer flow with automatic restart capability.
+     *
+     * Uses `defer()` to create a fresh observable on each subscription attempt,
+     * and `repeat()` to automatically restart when the async iterator completes
+     * (e.g., after NATS restart). This pattern ensures no messages are lost
+     * during reconnection periods.
+     *
+     * Messages are routed to the appropriate subject based on the stream kind:
+     * - Event messages → eventMessages$
+     * - Command messages → commandMessages$.
+     *
+     * The flow:
+     * 1. Fetches the JetStream consumer instance
+     * 2. Calls consume() to get an async iterator
+     * 3. Converts iterator to observable and emits messages to the appropriate subject
+     * 4. On completion, waits 100ms and restarts (via repeat)
+     * 5. On fatal error, logs and stops the flow.
+     *
+     * @param consumerInfo Consumer metadata from NATS.
+     * @param kind Stream kind (Event or Command).
+     * @returns Observable that manages the consumer lifecycle.
+     */
+    createConsumerFlow(consumerInfo, kind) {
+        const targetSubject$ = kind === enum_1.JetStreamKind.Event ? this.eventMessages$ : this.commandMessages$;
+        return (0, rxjs_1.defer)(() => this.startConsumerIteration(consumerInfo, targetSubject$)).pipe((0, rxjs_1.repeat)({
+            delay: () => {
+                this.logger.warn(`Consumer ${consumerInfo.name} stream completed. Restarting...`);
+                return (0, rxjs_1.timer)(100);
+            },
+        }), (0, rxjs_1.catchError)((err) => {
+            this.logger.error(`Fatal error in consumer ${consumerInfo.name}:`, err);
+            return rxjs_1.EMPTY;
+        }), (0, rxjs_1.takeUntil)(this.destroy$));
+    }
+    /**
+     * Executes a single iteration of consumer message processing.
+     *
+     * This method represents one complete lifecycle of the consumer:
+     * - Retrieves the consumer from JetStream
+     * - Starts the consume() async iterator
+     * - Emits messages to the target subject.
+     *
+     * When the async iterator completes (e.g., connection lost), this observable
+     * completes, triggering the `repeat()` operator to restart the flow.
+     *
+     * @param consumerInfo Consumer metadata.
+     * @param targetSubject$ Subject to emit messages to (events$ or commands$).
+     * @returns Observable that completes when the iteration ends.
+     */
+    startConsumerIteration(consumerInfo, targetSubject$) {
+        return (0, rxjs_1.of)(consumerInfo).pipe((0, rxjs_1.switchMap)((info) => this.getConsumer(info)), (0, rxjs_1.switchMap)((consumer) => this.consumeMessages(consumer, targetSubject$)));
+    }
+    /**
+     * Converts the consumer's async iterator into an RxJS observable stream.
+     *
+     * Calls consumer.consume() to get the async message iterator, converts it
+     * to an observable, and emits each message to the target subject.
+     *
+     * @param consumer JetStream consumer instance.
+     * @param targetSubject$ Subject to emit messages to.
+     * @returns Observable that emits void and completes when iterator ends.
+     */
+    consumeMessages(consumer, targetSubject$) {
+        return (0, rxjs_1.from)(consumer.consume()).pipe((0, rxjs_1.switchMap)((messages) => (0, rxjs_1.from)(messages)), (0, rxjs_1.switchMap)((msg) => {
+            targetSubject$.next(msg);
+            return (0, rxjs_1.of)(void 0);
+        }));
+    }
+    /**
+     * Retrieves a JetStream consumer instance by stream and consumer name.
+     *
+     * @param consumerInfo Consumer metadata containing stream and consumer names.
+     * @returns Observable of the consumer instance.
+     */
+    getConsumer(consumerInfo) {
+        return this.connectionProvider.jsm.pipe((0, rxjs_1.switchMap)((jsm) => {
+            const consumerPromise = jsm
+                .jetstream()
+                .consumers.get(consumerInfo.stream_name, consumerInfo.name);
+            return (0, rxjs_1.from)(consumerPromise);
+        }));
+    }
+};
+exports.MessageProvider = MessageProvider;
+exports.MessageProvider = MessageProvider = MessageProvider_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [connection_provider_1.ConnectionProvider,
+        consumer_provider_1.ConsumerProvider])
+], MessageProvider);
+//# sourceMappingURL=message.provider.js.map

package/dist/server/providers/message.provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.provider.js","sourceRoot":"","sources":["../../../src/server/providers/message.provider.ts"],"names":[],"mappings":"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"}

package/dist/server/providers/stream.provider.d.ts

@@ -0,0 +1,320 @@
+import { StreamConfig, StreamInfo, StreamUpdateConfig } from 'nats';
+import { Observable } from 'rxjs';
+import { ConnectionProvider } from '../../common/connection.provider';
+import { IJetstreamTransportOptions } from '../../common/types';
+import { JetStreamKind } from '../../enum';
+/**
+ * Provider responsible for managing JetStream stream lifecycle.
+ *
+ * @description
+ * This provider handles the creation, updating, and configuration of JetStream streams
+ * that serve as the foundation for message storage and delivery in the transport.
+ * It ensures that both Event and Command streams exist and are properly configured
+ * before any message consumption begins.
+ *
+ * @remarks
+ * **Core responsibilities:**
+ *
+ * 1. **Stream creation and updates:**
+ *    - Creates Event and Command streams on initialization
+ *    - Updates existing streams if configuration changes
+ *    - Ensures streams match the required configuration
+ *    - Handles idempotent operations (safe to call multiple times)
+ *
+ * 2. **Stream naming convention:**
+ *    - Format: `{serviceName}_{kind}-stream`
+ *    - Examples: `orders-service_event-stream`, `orders-service_command-stream`
+ *    - Ensures unique streams per service instance
+ *
+ * 3. **Subject patterns:**
+ *    - Event subjects: `{serviceName}.event.>`
+ *    - Command subjects: `{serviceName}.command.>`
+ *    - The `>` wildcard allows hierarchical message routing
+ *
+ * 4. **Configuration management:**
+ *    - Applies base configuration common to all streams
+ *    - Applies kind-specific configuration (event vs command)
+ *    - Merges user-provided custom configuration
+ *
+ * **Stream types:**
+ *
+ * - **Event streams:**
+ *   Designed for pub/sub patterns and event broadcasting.
+ *   Multiple consumers can process the same events independently.
+ *   Typical configuration: longer retention, interest-based retention policy.
+ *
+ * - **Command streams:**
+ *   Designed for work queue patterns and RPC-style communication.
+ *   Messages are distributed across consumers (load balancing).
+ *   Typical configuration: shorter retention, work queue retention policy.
+ *
+ * **Idempotency:**
+ *
+ * The create() method is idempotent:
+ * - If streams don't exist: creates them
+ * - If streams exist with different config: updates them
+ * - If streams exist with same config: no-op (returns existing info)
+ *
+ * This makes it safe to call on every application startup and reconnection.
+ *
+ * @example
+ * ```typescript
+ * // Create both event and command streams
+ * streamProvider.create().subscribe(() => {
+ *   console.log('All streams ready');
+ * });
+ *
+ * // Get stream name for a specific kind
+ * const streamName = streamProvider.getStreamName(JetStreamKind.Event);
+ * // Returns: "my-service_event-stream"
+ * ```
+ *
+ * @see {@link https://docs.nats.io/nats-concepts/jetstream/streams | JetStream Streams Documentation}
+ * @see {@link https://docs.nats.io/using-nats/developer/develop_jetstream/model_deep_dive | Stream Configuration Guide}
+ */
+export declare class StreamProvider {
+    private readonly options;
+    private readonly connectionProvider;
+    private readonly logger;
+    /**
+     * Creates a StreamProvider instance.
+     *
+     * @param options JetStream transport options containing service name and custom stream configurations.
+     * @param connectionProvider Provider that manages NATS connection and JetStream manager access.
+     */
+    constructor(options: IJetstreamTransportOptions, connectionProvider: ConnectionProvider);
+    /**
+     * Creates or updates both Event and Command streams.
+     *
+     * @description
+     * Orchestrates the creation of both stream types in parallel using forkJoin.
+     * This ensures both streams are ready before the observable completes.
+     *
+     * The operation is idempotent:
+     * - Creates streams if they don't exist
+     * - Updates streams if configuration changed
+     * - No-op if streams exist with correct configuration.
+     *
+     * **Error handling:**
+     * - If one stream fails to create, the entire operation fails
+     * - Errors are not caught here, allowing caller to handle retry logic
+     * - Common errors: permission denied, invalid configuration, network issues.
+     *
+     * @returns Observable that completes when both streams are ready (emits void).
+     *
+     * @example
+     * ```typescript
+     * streamProvider.create().subscribe({
+     *   next: () => console.log('Streams ready'),
+     *   error: (err) => console.error('Stream creation failed:', err),
+     * });
+     * ```
+     */
+    create(): Observable<void>;
+    /**
+     * Generates the stream name for a specific kind.
+     *
+     * @description
+     * Constructs the stream name using the naming convention:
+     * `{serviceName}_{kind}-stream`.
+     *
+     * This ensures:
+     * - Stream names are unique per service
+     * - Stream names are predictable and discoverable
+     * - Different services don't interfere with each other.
+     *
+     * @param kind The stream kind (Event or Command).
+     * @returns The formatted stream name.
+     *
+     * @example
+     * ```typescript
+     * streamProvider.getStreamName(JetStreamKind.Event);
+     * // Returns: "orders-service_event-stream"
+     *
+     * streamProvider.getStreamName(JetStreamKind.Command);
+     * // Returns: "orders-service_command-stream"
+     * ```
+     */
+    getStreamName(kind: JetStreamKind): string;
+    /**
+     * Generates subject patterns for a specific stream kind.
+     *
+     * @description
+     * Constructs subject patterns that the stream will capture messages from.
+     * The pattern format is: `{serviceName}.{kind}.>`.
+     *
+     * The `>` wildcard means "match all tokens after this point", enabling:
+     * - Hierarchical subject organization
+     * - Flexible message routing
+     * - Namespace isolation per service.
+     *
+     * **Examples of matched subjects:**
+     * - Pattern: `orders.event.>`
+     *   - Matches: `orders.event.created`, `orders.event.updated`, `orders.event.deleted.v2`
+     *   - Does NOT match: `orders.command.create`, `payments.event.created`.
+     *
+     * @param kind The stream kind (Event or Command).
+     * @returns Array of subject patterns (currently single pattern, but array for future extensibility).
+     *
+     * @example
+     * ```typescript
+     * streamProvider.getSubjects(JetStreamKind.Event);
+     * // Returns: ["orders-service.event.>"]
+     * ```
+     */
+    protected getSubjects(kind: JetStreamKind): string[];
+    /**
+     * Creates or updates a stream for a specific kind.
+     *
+     * @description
+     * Implements the stream ensure logic with the following flow:
+     *
+     * 1. **Build configuration:**
+     *    - Merge base config (common settings)
+     *    - Merge kind-specific config (event vs command)
+     *    - Set stream name and subjects
+     *    - Add descriptive metadata.
+     *
+     * 2. **Check if stream exists:**
+     *    - Query stream info via `info()`
+     *    - If exists: proceed to update
+     *    - If not found: catch error and create new.
+     *
+     * 3. **Update existing stream:**
+     *    - Apply new configuration via `update()`
+     *    - JetStream validates if update is allowed
+     *    - Some changes require stream recreation.
+     *
+     * 4. **Create new stream:**
+     *    - Triggered by StreamNotFound error
+     *    - Creates stream with full configuration
+     *    - Logs successful creation.
+     *
+     * **Error handling:**
+     * - StreamNotFound → creates new stream
+     * - Other errors → propagated to caller.
+     *
+     * @param kind The stream kind to create/update.
+     * @returns Observable that emits StreamInfo when complete.
+     *
+     * @example
+     * ```typescript
+     * // Internal usage, called by create()
+     * this.createForKind(JetStreamKind.Event).subscribe(info => {
+     *   console.log('Stream created:', info.config.name);
+     * });
+     * ```
+     */
+    protected createForKind(kind: JetStreamKind): Observable<StreamInfo>;
+    /**
+     * Retrieves information about an existing stream.
+     *
+     * @description
+     * Queries the JetStream manager for stream metadata and configuration.
+     * This is used to:
+     * - Check if a stream exists
+     * - Verify stream configuration
+     * - Monitor stream state.
+     *
+     * **Stream info includes:**
+     * - Configuration (retention, limits, subjects)
+     * - State (messages count, bytes, first/last sequence)
+     * - Cluster information (if clustered)
+     * - Consumer count.
+     *
+     * @param streamName The name of the stream to query.
+     * @returns Observable that emits StreamInfo or errors if stream not found.
+     *
+     * @throws {NatsError} With code StreamNotFound if stream doesn't exist.
+     *
+     * @example
+     * ```typescript
+     * this.info('orders-service_event-stream').subscribe(info => {
+     *   console.log('Messages in stream:', info.state.messages);
+     * });
+     * ```
+     */
+    protected info(streamName: string): Observable<StreamInfo>;
+    /**
+     * Creates a new stream with the provided configuration.
+     *
+     * @description
+     * Creates a new JetStream stream from scratch. This is called when
+     * a stream doesn't exist yet (typically on first application start
+     * or after manual deletion).
+     *
+     * **Configuration validation:**
+     * - JetStream validates all configuration parameters
+     * - Invalid configs will cause the operation to fail
+     * - Common validations: subject uniqueness, retention policy compatibility.
+     *
+     * **Stream creation is atomic:**
+     * - Either the stream is fully created or it fails
+     * - No partial state
+     * - Safe to retry on failure.
+     *
+     * @param config Complete stream configuration including name, subjects, and policies.
+     * @returns Observable that emits StreamInfo of the newly created stream.
+     *
+     * @throws {NatsError} If creation fails (permissions, invalid config, etc.).
+     *
+     * @example
+     * ```typescript
+     * const config = {
+     *   name: 'my-stream',
+     *   subjects: ['my.service.>'],
+     *   retention: RetentionPolicy.Limits,
+     * };
+     *
+     * this.new(config).subscribe(info => {
+     *   console.log('Stream created:', info.config.name);
+     * });
+     * ```
+     */
+    protected new(config: StreamConfig): Observable<StreamInfo>;
+    /**
+     * Updates an existing stream with new configuration.
+     *
+     * @description
+     * Applies configuration changes to an existing stream. Not all changes
+     * are allowed - some require stream recreation.
+     *
+     * **Allowed updates:**
+     * - Subject list modifications (add/remove subjects)
+     * - Limit adjustments (max_msgs, max_bytes, max_age)
+     * - Description changes
+     * - Some policy changes.
+     *
+     * **Updates requiring recreation:**
+     * - Storage type change (file ↔ memory)
+     * - Retention policy change (in some cases)
+     * - Discard policy change (in some cases)
+     * - Changing stream name.
+     *
+     * **Behavior:**
+     * - If update is allowed: applies changes and returns updated info
+     * - If update is not allowed: returns error explaining why
+     * - No automatic recreation - caller must handle explicitly.
+     *
+     * @param streamName Name of the stream to update.
+     * @param config New configuration to apply.
+     * @returns Observable that emits updated StreamInfo.
+     *
+     * @throws {NatsError} If update is not allowed or fails.
+     *
+     * @example
+     * ```typescript
+     * const newConfig = {
+     *   name: 'my-stream',
+     *   subjects: ['my.service.>', 'other.service.>'], // Added subject
+     *   max_msgs: 10000,
+     * };
+     *
+     * this.update('my-stream', newConfig).subscribe(info => {
+     *   console.log('Stream updated, subjects:', info.config.subjects);
+     * });
+     * ```
+     */
+    protected update(streamName: string, config: StreamUpdateConfig): Observable<StreamInfo>;
+}
+//# sourceMappingURL=stream.provider.d.ts.map

package/dist/server/providers/stream.provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.provider.d.ts","sourceRoot":"","sources":["../../../src/server/providers/stream.provider.ts"],"names":[],"mappings":"AACA,OAAO,EAAa,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,MAAM,CAAC;AAC/E,OAAO,EAAmC,UAAU,EAAkB,MAAM,MAAM,CAAC;AAEnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAI3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,qBACa,cAAc;IAUvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IAVrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAE1D;;;;;OAKG;gBAEgB,OAAO,EAAE,0BAA0B,EACnC,kBAAkB,EAAE,kBAAkB;IAGzD;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACI,MAAM,IAAI,UAAU,CAAC,IAAI,CAAC;IAOjC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACI,aAAa,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM;IAIjD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,SAAS,CAAC,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,EAAE;IAIpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyCG;IACH,SAAS,CAAC,aAAa,CAAC,IAAI,EAAE,aAAa,GAAG,UAAU,CAAC,UAAU,CAAC;IAwBpE;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,SAAS,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,CAAC,UAAU,CAAC;IAU1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,YAAY,GAAG,UAAU,CAAC,UAAU,CAAC;IAU3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0CG;IACH,SAAS,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,UAAU,CAAC,UAAU,CAAC;CAWzF"}