@horizon-republic/nestjs-jetstream 1.0.4

package/dist/client/jetstream.client-proxy.js

@@ -0,0 +1,300 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JetstreamClientProxy = void 0;
+const common_1 = require("@nestjs/common");
+const microservices_1 = require("@nestjs/microservices");
+const nats_1 = require("nats");
+const rxjs_1 = require("rxjs");
+const uuid_1 = require("uuid");
+const enum_1 = require("../enum");
+/**
+ * NATS JetStream client proxy for NestJS microservices.
+ *
+ * Implements hybrid messaging pattern:
+ * - Events: Fire-and-forget via JetStream (guaranteed delivery, no response)
+ * - Commands: Request-reply via JetStream + Core NATS inbox (RPC with response).
+ *
+ * Architecture:.
+ * ```
+ * Events:   Client --[JetStream publish]--> Stream --> Consumers
+ *           └─> returns immediately
+ *
+ * Commands: Client --[JetStream publish]--> Stream --> Consumer
+ *           └─[inbox subscribe]<--[Core NATS publish]<-- Response
+ *           └─> waits for response via callback
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Fire-and-forget event
+ * await firstValueFrom(client.emit('user.created', { id: 1 }));
+ *
+ * // Request-reply command
+ * const user = await firstValueFrom(client.send('get.user', { id: 1 }));
+ * ```
+ */
+class JetstreamClientProxy extends microservices_1.ClientProxy {
+    constructor(providers) {
+        super();
+        this.providers = providers;
+        this.logger = new common_1.Logger(JetstreamClientProxy.name);
+        this.destroy$ = new rxjs_1.Subject();
+        /**
+         * Unique inbox subject for receiving RPC responses.
+         * Format: <service_name>.<random>
+         * Shared across all command requests from this client instance.
+         */
+        this.inbox = (0, nats_1.createInbox)(this.providers.options.name);
+        // todo: make configurable
+        this.codec = (0, nats_1.JSONCodec)();
+        /**
+         * Map of pending RPC requests awaiting responses.
+         * Key: correlation ID (UUID v7)
+         * Value: callback to invoke when response arrives.
+         */
+        this.pendingMessages = new Map();
+        /**
+         * Flag to prevent duplicate inbox subscriptions.
+         * Reset to false on connection errors to allow re-subscription.
+         */
+        this.isInboxSubscribed = false;
+    }
+    /**
+     * Establish connection and setup inbox on module initialization to don't wait for the first request.
+     */
+    onModuleInit() {
+        void this.connect();
+    }
+    /**
+     * Establishes NATS connection and sets up an inbox subscription for RPC responses.
+     *
+     * Idempotent: multiple calls reuse existing connection and subscription.
+     * Automatically recovers subscription after reconnection.
+     *
+     * @returns Promise resolving to active NATS connection.
+     */
+    async connect() {
+        const nc = await (0, rxjs_1.firstValueFrom)(this.providers.connectionProvider.nc);
+        if (!this.isInboxSubscribed) {
+            this.isInboxSubscribed = true;
+            this.providers.connectionProvider.nc
+                .pipe((0, rxjs_1.tap)((connection) => {
+                if (!connection.isClosed() && !connection.isDraining()) {
+                    this.setupInboxSubscription(connection);
+                }
+            }), (0, rxjs_1.takeUntil)(this.destroy$))
+                .subscribe({
+                error: (err) => {
+                    this.logger.error('Connection stream error, will retry on next connect()', err);
+                    this.isInboxSubscribed = false;
+                },
+            });
+        }
+        return nc;
+    }
+    /**
+     * Gracefully closes connection and cleans up resources.
+     *
+     * Emits destroy signal to stop connection monitoring,
+     * completes all pending observables, and closes NATS connection.
+     */
+    async close() {
+        this.logger.debug('Closing client and cleaning up resources');
+        this.destroy$.next();
+        this.destroy$.complete();
+        const nc = await (0, rxjs_1.firstValueFrom)(this.providers.connectionProvider.nc);
+        await nc.close();
+    }
+    /**
+     * Returns raw NATS connection for advanced use cases.
+     *
+     * @returns Raw NATS connection instance.
+     */
+    unwrap() {
+        return this.providers.connectionProvider.unwrap;
+    }
+    /**
+     * Publishes fire-and-forget event to JetStream.
+     *
+     * Does not wait for acknowledgment or response.
+     * JetStream guarantees persistence and at-least-once delivery to consumers.
+     *
+     * @param packet Event packet containing pattern and data.
+     * @returns Promise resolving immediately after publish (undefined).
+     */
+    async dispatchEvent(packet) {
+        const subject = this.buildSubject(enum_1.JetStreamKind.Event, packet.pattern);
+        const messageId = (0, uuid_1.v7)();
+        const nc = await this.connect();
+        const hdrs = this.createHeaders({ messageId, subject });
+        // Fire-and-forget: don't await acknowledgment
+        void nc.jetstream().publish(subject, this.codec.encode(packet.data), { headers: hdrs });
+        return undefined;
+    }
+    /**
+     * Publishes RPC command to JetStream and registers callback for response.
+     *
+     * Command is persisted in JetStream for guaranteed delivery.
+     * Response arrives via Core NATS inbox subscription.
+     *
+     * Pattern:
+     * 1. Register callback in pending map with correlation ID
+     * 2. Publish command with reply-to inbox address
+     * 3. Consumer processes command and publishes response to inbox
+     * 4. Inbox subscription routes response to callback via correlation ID.
+     *
+     * @param packet Command packet containing pattern and data.
+     * @param callback Function to invoke when response arrives or error occurs.
+     * @returns Cleanup function to cancel pending request.
+     */
+    publish(packet, callback) {
+        const subject = this.buildSubject(enum_1.JetStreamKind.Command, packet.pattern);
+        const correlationId = (0, uuid_1.v7)();
+        const messageId = (0, uuid_1.v7)();
+        this.pendingMessages.set(correlationId, callback);
+        void this.publishCommand(subject, packet.data, { correlationId, messageId, callback });
+        return () => {
+            this.pendingMessages.delete(correlationId);
+        };
+    }
+    /**
+     * Internal: executes command publication with error handling.
+     *
+     * Invokes callback immediately on publish error to fail fast.
+     * On success, response will arrive asynchronously via inbox.
+     *
+     * @param subject Fully-qualified NATS subject to publish to.
+     * @param data Payload data to encode and send.
+     * @param ctx Context object containing correlation metadata.
+     * @param ctx.correlationId UUID v7 linking request and response.
+     * @param ctx.messageId Unique message identifier for tracing.
+     * @param ctx.callback Function to invoke on error or when response arrives.
+     */
+    async publishCommand(subject, data, ctx) {
+        try {
+            const nc = await this.connect();
+            const hdrs = this.createHeaders({
+                correlationId: ctx.correlationId,
+                messageId: ctx.messageId,
+                subject,
+                replyTo: this.inbox,
+            });
+            await nc.jetstream().publish(subject, this.codec.encode(data), { headers: hdrs });
+        }
+        catch (error) {
+            this.logger.error(`Command publish failed: ${subject}`, error);
+            // Fail fast: invoke callback with error
+            ctx.callback({
+                err: error instanceof Error ? error.message : 'Unknown error',
+                response: null,
+            });
+            this.pendingMessages.delete(ctx.correlationId);
+        }
+    }
+    /**
+     * Sets up Core NATS subscription to inbox for receiving RPC responses.
+     *
+     * Inbox subscription persists across multiple command requests.
+     * Each response is routed to the correct callback via correlation ID.
+     *
+     * Note: Uses Core NATS (not JetStream) for low-latency, ephemeral replies.
+     *
+     * @param nc Active NATS connection to subscribe with.
+     */
+    setupInboxSubscription(nc) {
+        this.logger.log(`Inbox subscription established: ${this.inbox}`);
+        nc.subscribe(this.inbox, {
+            callback: (error, msg) => {
+                if (error) {
+                    this.logger.error('Inbox subscription error:', error);
+                    return;
+                }
+                this.routeReply(msg);
+            },
+        });
+    }
+    /**
+     * Routes inbox message to pending callback using correlation ID.
+     *
+     * Handles:
+     * - Missing correlation ID (warns and ignores)
+     * - No matching handler (warns - possible timeout/cleanup race)
+     * - Decoding errors (invokes callback with error)
+     * - Success (invokes callback with response).
+     *
+     * Always cleans up pending message entry after processing.
+     *
+     * @param msg NATS message received in inbox subscription.
+     */
+    routeReply(msg) {
+        const correlationId = msg.headers?.get(enum_1.JetstreamHeaders.CorrelationId);
+        if (!correlationId) {
+            this.logger.warn('Received reply without correlation ID, ignoring');
+            return;
+        }
+        const handler = this.pendingMessages.get(correlationId);
+        if (!handler) {
+            this.logger.warn(`No pending handler for correlation ID: ${correlationId} ` +
+                '(possible timeout or already processed)');
+            return;
+        }
+        try {
+            const response = this.codec.decode(msg.data);
+            handler({ err: null, response, isDisposed: true });
+        }
+        catch (error) {
+            this.logger.error(`Failed to decode response (cid: ${correlationId})`, error);
+            handler({ err: error.message, response: null, isDisposed: true });
+        }
+        finally {
+            this.pendingMessages.delete(correlationId);
+        }
+    }
+    /**
+     * Creates NATS message headers with common metadata.
+     *
+     * Standard headers:
+     * - message-id: Unique identifier for idempotency and tracing
+     * - subject: Full subject name for routing and debugging.
+     *
+     * Optional headers:
+     * - correlation-id: Links request and response for RPC pattern
+     * - reply-to: Inbox address for receiving responses.
+     *
+     * @param data Header data configuration object.
+     * @param data.messageId Unique message identifier (UUID v7).
+     * @param data.subject Fully-qualified NATS subject.
+     * @param data.correlationId Optional correlation ID for RPC linking.
+     * @param data.replyTo Optional inbox subject for receiving responses.
+     * @returns NATS message headers instance.
+     */
+    createHeaders(data) {
+        const hdrs = (0, nats_1.headers)();
+        hdrs.set(enum_1.JetstreamHeaders.MessageId, data.messageId);
+        hdrs.set(enum_1.JetstreamHeaders.Subject, data.subject);
+        if (data.correlationId) {
+            hdrs.set(enum_1.JetstreamHeaders.CorrelationId, data.correlationId);
+        }
+        if (data.replyTo) {
+            hdrs.set(enum_1.JetstreamHeaders.ReplyTo, data.replyTo);
+        }
+        return hdrs;
+    }
+    /**
+     * Builds fully-qualified NATS subject from kind and pattern.
+     *
+     * Format: <service-name>.<kind>.<pattern>
+     * Example: "user-service.Command.get.user".
+     *
+     * This namespacing prevents collisions between services and message types.
+     *
+     * @param kind Message type (Event or Command).
+     * @param pattern User-defined pattern from decorator (e.g., "get.user").
+     * @returns Fully-qualified NATS subject string.
+     */
+    buildSubject(kind, pattern) {
+        return `${this.providers.options.name}.${kind}.${pattern}`;
+    }
+}
+exports.JetstreamClientProxy = JetstreamClientProxy;
+//# sourceMappingURL=jetstream.client-proxy.js.map

package/dist/client/jetstream.client-proxy.js.map

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

package/dist/client/types/index.d.ts

@@ -0,0 +1,7 @@
+import { ConnectionProvider } from '../../common/connection.provider';
+import { IJetstreamTransportOptions } from '../../common/types';
+export interface IClientProviders {
+    options: IJetstreamTransportOptions;
+    connectionProvider: ConnectionProvider;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/client/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/types/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAEhE,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,0BAA0B,CAAC;IACpC,kBAAkB,EAAE,kBAAkB,CAAC;CACxC"}

package/dist/client/types/index.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=index.js.map

package/dist/client/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/client/types/index.ts"],"names":[],"mappings":""}

package/dist/common/connection.provider.d.ts

@@ -0,0 +1,309 @@
+import { OnModuleDestroy } from '@nestjs/common';
+import { JetStreamManager, NatsConnection, NatsError, Status } from 'nats';
+import { Observable } from 'rxjs';
+import { IJetstreamTransportOptions } from './types';
+/**
+ * Provider that manages the lifecycle of a NATS connection and JetStream manager.
+ *
+ * @description
+ * This provider is responsible for establishing and maintaining a connection to NATS servers,
+ * providing access to the JetStream manager, and handling connection lifecycle events.
+ * It serves as the foundation for all NATS JetStream operations in the transport.
+ *
+ * @remarks
+ * **Key responsibilities:**
+ *
+ * 1. **Connection management:**
+ *    - Establishes connection to NATS servers on initialization
+ *    - Provides reactive access to the connection via observables
+ *    - Handles connection errors and reconnection events
+ *    - Implements graceful shutdown with proper drain/close sequence
+ *
+ * 2. **JetStream integration:**
+ *    - Creates and caches a JetStream manager instance
+ *    - Provides reactive access to the manager via observable
+ *    - Ensures manager is available before stream/consumer operations
+ *
+ * 3. **Status monitoring:**
+ *    - Exposes connection status as an observable stream
+ *    - Emits status events (connect, disconnect, reconnect, etc.)
+ *    - Allows other components to react to connection state changes
+ *
+ * 4. **Resource cleanup:**
+ *    - Implements OnModuleDestroy for proper lifecycle management
+ *    - Ensures subscriptions are cleaned up on module destruction
+ *    - Handles graceful shutdown on application termination
+ *
+ * **Observable caching:**
+ *
+ * The provider uses `shareReplay({ bufferSize: 1, refCount: false })` for connection
+ * and JetStream manager observables. This ensures:
+ * - Single connection instance shared across all subscribers
+ * - New subscribers immediately receive the cached connection
+ * - Connection persists even when all subscribers unsubscribe
+ * - No duplicate connection attempts
+ *
+ * **Error handling:**
+ *
+ * Connection errors are categorized:
+ * - `CONNECTION_REFUSED`: Terminal error, throws RuntimeException
+ * - Other errors: Non-terminal, returns EMPTY to allow reconnection attempts
+ *
+ * @example
+ * ```typescript
+ * // Basic usage in a provider
+ * class MyProvider {
+ *   constructor(private connectionProvider: ConnectionProvider) {
+ *     this.connectionProvider.nc.pipe(
+ *       take(1),
+ *       tap(connection => console.log('Connected to:', connection.nc))
+ *     ).subscribe();
+ *   }
+ * }
+ *
+ * // Monitoring connection status
+ * connectionProvider.status.subscribe(status => {
+ *   console.log('Connection status:', status.type);
+ * });
+ *
+ * // Graceful shutdown
+ * connectionProvider.gracefulShutdown().subscribe(() => {
+ *   console.log('Connection closed gracefully');
+ * });
+ * ```
+ *
+ * @see {@link https://docs.nats.io/using-nats/developer/connecting | NATS Connection Documentation}
+ * @see {@link https://docs.nats.io/nats-concepts/jetstream | JetStream Documentation}
+ */
+export declare class ConnectionProvider implements OnModuleDestroy {
+    private readonly options;
+    private readonly logger;
+    /**
+     * Observable that emits the NATS connection once established.
+     * Cached and shared across all subscribers.
+     *
+     */
+    private nc$;
+    /**
+     * Observable that emits the JetStream manager once available.
+     * Cached and shared across all subscribers.
+     *
+     */
+    private jsm$;
+    /**
+     * Observable stream of connection status events.
+     * Emits events like connect, disconnect, reconnect, error, etc.
+     *
+     */
+    private status$;
+    /**
+     * Raw unwrapped NATS connection instance.
+     * Stored for direct access and graceful shutdown.
+     *
+     */
+    private unwrappedConnection;
+    /**
+     * Optional subscription for internal cleanup.
+     * Currently unused but available for future enhancements.
+     *
+     */
+    private readonly subscription?;
+    /**
+     * Creates a ConnectionProvider instance.
+     *
+     * @param options JetStream transport options including NATS connection configuration.
+     *
+     * @description
+     * Initializes the connection setup immediately in the constructor.
+     * The actual connection is established lazily when the nc$ observable is subscribed to.
+     */
+    constructor(options: IJetstreamTransportOptions);
+    /**
+     * Observable stream of connection status events.
+     *
+     * @description
+     * Provides access to the NATS connection status stream. Status events include:
+     * - `connect`: Initial connection established
+     * - `disconnect`: Connection lost
+     * - `reconnect`: Connection re-established after disconnect
+     * - `update`: Server discovery or cluster changes
+     * - `error`: Connection errors.
+     *
+     * This stream does NOT replay previous events (uses `share()` instead of `shareReplay`),
+     * so subscribers only receive events that occur after subscription.
+     *
+     * @returns Observable that emits connection status events.
+     *
+     * @example
+     * ```typescript
+     * connectionProvider.status.subscribe(status => {
+     *   if (status.type === 'disconnect') {
+     *     console.log('Connection lost, will attempt reconnect...');
+     *   }
+     * });
+     * ```
+     */
+    get status(): Observable<Status>;
+    /**
+     * Observable that emits the NATS connection once established.
+     *
+     * @description
+     * Provides reactive access to the NATS connection. The connection is:
+     * - Established on first subscription (lazy)
+     * - Cached and shared across all subsequent subscribers
+     * - Persists even when all subscribers unsubscribe.
+     *
+     * Multiple subscriptions will share the same connection instance.
+     *
+     * @returns Observable that emits the NATS connection.
+     *
+     * @example
+     * ```typescript
+     * connectionProvider.nc.pipe(
+     *   take(1),
+     *   tap(nc => console.log('Server:', nc.getServer()))
+     * ).subscribe();
+     * ```
+     */
+    get nc(): Observable<NatsConnection>;
+    /**
+     * Observable that emits the JetStream manager once available.
+     *
+     * @description
+     * Provides reactive access to the JetStream manager instance.
+     * The manager is created from the NATS connection and enables:
+     * - Stream management (create, update, delete streams)
+     * - Consumer management (create, update, delete consumers)
+     * - Stream and consumer info queries.
+     *
+     * Like the connection, the manager is cached and shared.
+     *
+     * @returns Observable that emits the JetStream manager.
+     *
+     * @example
+     * ```typescript
+     * connectionProvider.jsm.pipe(
+     *   take(1),
+     *   switchMap(jsm => from(jsm.streams.list()))
+     * ).subscribe(streams => console.log('Streams:', streams));
+     * ```
+     */
+    get jsm(): Observable<JetStreamManager>;
+    /**
+     * Direct access to the unwrapped NATS connection.
+     *
+     * @description
+     * Provides synchronous access to the raw NATS connection instance.
+     * Use this when you need immediate access without subscribing to an observable.
+     *
+     * **Warning:** This getter assumes the connection has already been established.
+     * If called before the connection is ready, it will return undefined.
+     *
+     * @returns The raw NATS connection instance.
+     *
+     * @example
+     * ```typescript
+     * const nc = connectionProvider.unwrap;
+     * const serverUrl = nc.getServer();
+     * ```
+     */
+    get unwrap(): NatsConnection;
+    /**
+     * Lifecycle hook called when the module is being destroyed.
+     *
+     * @description
+     * Cleans up any active subscriptions to prevent memory leaks.
+     * Currently, the subscription is optional and may not be used.
+     */
+    onModuleDestroy(): void;
+    /**
+     * Gracefully shuts down the NATS connection.
+     *
+     * @description
+     * Implements a proper shutdown sequence:
+     *
+     * 1. Checks if connection is already closed
+     *    - If yes: returns immediately (no-op)
+     *    - If no: proceeds with shutdown.
+     *
+     * 2. Drains the connection:
+     *    - Stops accepting new messages
+     *    - Waits for pending outbound messages to be sent
+     *    - Waits for pending subscriptions to be flushed.
+     *
+     * 3. Waits for connection close:
+     *    - Waits for the connection to fully close
+     *    - Ensures all resources are released.
+     *
+     * 4. Error handling:
+     *    - If drain fails: attempts force close
+     *    - If close fails: swallows error and returns void.
+     *
+     * This ensures messages are not lost during shutdown and resources
+     * are properly cleaned up.
+     *
+     * @returns Observable that completes when shutdown is finished or emits error if shutdown fails.
+     *
+     * @example
+     * ```typescript
+     * // In application shutdown hook
+     * connectionProvider.gracefulShutdown().subscribe({
+     *   next: () => console.log('Connection closed'),
+     *   error: (err) => console.error('Shutdown error:', err),
+     * });
+     * ```
+     */
+    gracefulShutdown(): Observable<void | Error | undefined>;
+    /**
+     * Sets up the NATS connection and related observables.
+     *
+     * @description
+     * This method initializes three key observables:
+     *
+     * 1. **Connection observable (nc$):**
+     *    - Creates connection to NATS servers using provided options
+     *    - Adds service type suffix to connection name for identification
+     *    - Handles connection errors via handleError()
+     *    - Logs successful connection with server URL
+     *    - Stores raw connection reference in unwrappedConnection
+     *    - Uses shareReplay to cache and share connection.
+     *
+     * 2. **JetStream manager observable (jsm$):**
+     *    - Derives from connection observable
+     *    - Creates JetStream manager from connection
+     *    - Logs manager initialization
+     *    - Uses shareReplay to cache and share manager.
+     *
+     * 3. **Status observable (status$):**
+     *    - Derives from connection observable
+     *    - Maps connection to its status iterator
+     *    - Converts async iterator to observable
+     *    - Uses share() for event bus behavior (no replay).
+     *
+     * The setup is lazy - actual connection happens on first subscription.
+     */
+    protected setupConnection(): void;
+    /**
+     * Handles connection errors with appropriate error strategies.
+     *
+     * @description
+     * Implements error categorization:
+     *
+     * - **CONNECTION_REFUSED:**
+     *   This is a terminal error indicating NATS servers are unreachable.
+     *   Throws RuntimeException to fail fast and prevent the application
+     *   from starting in an inconsistent state.
+     *
+     * - **Other errors:**
+     *   Non-terminal errors that may be transient (network issues, etc.).
+     *   Returns EMPTY to complete the observable without emitting.
+     *   This allows retry logic at higher levels to attempt reconnection.
+     *
+     * @param err The NATS error to handle.
+     * @returns Observable that either throws or completes empty.
+     *
+     * @throws {RuntimeException} When connection is refused (servers unreachable).
+     */
+    protected handleError(err: NatsError): Observable<NatsConnection>;
+}
+//# sourceMappingURL=connection.provider.d.ts.map

package/dist/common/connection.provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.provider.d.ts","sourceRoot":"","sources":["../../src/common/connection.provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAErE,OAAO,EAGL,gBAAgB,EAChB,cAAc,EACd,SAAS,EACT,MAAM,EACP,MAAM,MAAM,CAAC;AACd,OAAO,EAKL,UAAU,EAQX,MAAM,MAAM,CAAC;AAEd,OAAO,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH,qBACa,kBAAmB,YAAW,eAAe;IA+CrC,OAAO,CAAC,QAAQ,CAAC,OAAO;IA9C3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;IAE9D;;;;OAIG;IACH,OAAO,CAAC,GAAG,CAA8B;IAEzC;;;;OAIG;IACH,OAAO,CAAC,IAAI,CAAgC;IAE5C;;;;OAIG;IACH,OAAO,CAAC,OAAO,CAAsB;IAErC;;;;OAIG;IACH,OAAO,CAAC,mBAAmB,CAAkB;IAE7C;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAe;IAE7C;;;;;;;;OAQG;gBACiC,OAAO,EAAE,0BAA0B;IAIvE;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,IAAW,MAAM,IAAI,UAAU,CAAC,MAAM,CAAC,CAEtC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,IAAW,EAAE,IAAI,UAAU,CAAC,cAAc,CAAC,CAE1C;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,IAAW,GAAG,IAAI,UAAU,CAAC,gBAAgB,CAAC,CAE7C;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,IAAW,MAAM,IAAI,cAAc,CAElC;IAED;;;;;;OAMG;IACI,eAAe,IAAI,IAAI;IAI9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACI,gBAAgB,IAAI,UAAU,CAAC,IAAI,GAAG,KAAK,GAAG,SAAS,CAAC;IAiB/D;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,SAAS,CAAC,eAAe,IAAI,IAAI;IA+BjC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,SAAS,CAAC,WAAW,CAAC,GAAG,EAAE,SAAS,GAAG,UAAU,CAAC,cAAc,CAAC;CAKlE"}