@zdavison/matador 2.0.1

package/dist/errors/matador-errors.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Base class for all Matador errors.
+ * All errors have a unique name that appears in monitoring tools (e.g., DataDog)
+ * and a description explaining the error and actions to resolve it.
+ *
+ * The `name` property is automatically set to the class name for proper
+ * identification in error monitoring and logging systems.
+ */
+export declare abstract class MatadorError extends Error {
+    /**
+     * Error class name (e.g., "NotStartedError", "TransportNotConnectedError").
+     * This is preserved during serialization for error monitoring tools.
+     */
+    readonly name: string;
+    /**
+     * Human-readable description explaining what went wrong and
+     * what ACTION the user should take to resolve the issue.
+     */
+    abstract readonly description: string;
+    constructor(message: string);
+    /**
+     * Returns a serializable representation for logging/monitoring.
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Thrown when attempting to use Matador before calling start().
+ */
+export declare class NotStartedError extends MatadorError {
+    readonly description: string;
+    constructor(operation?: string);
+}
+/**
+ * Thrown when attempting to dispatch events during shutdown.
+ */
+export declare class ShutdownInProgressError extends MatadorError {
+    readonly description: string;
+    constructor();
+}
+/**
+ * Thrown when a transport operation is attempted but the transport is not connected.
+ */
+export declare class TransportNotConnectedError extends MatadorError {
+    readonly transportName: string;
+    readonly description: string;
+    constructor(transportName: string, operation?: string);
+}
+/**
+ * Thrown when the transport has been closed (during shutdown).
+ */
+export declare class TransportClosedError extends MatadorError {
+    readonly transportName: string;
+    readonly description: string;
+    constructor(transportName: string);
+}
+/**
+ * Thrown when all transports in a fallback chain fail.
+ */
+export declare class AllTransportsFailedError extends MatadorError {
+    readonly queue: string;
+    readonly errors: readonly Error[];
+    readonly description: string;
+    constructor(queue: string, errors: readonly Error[]);
+}
+/**
+ * Thrown when sending a message to the transport fails.
+ */
+export declare class TransportSendError extends MatadorError {
+    readonly queue: string;
+    readonly cause: Error;
+    readonly description: string;
+    constructor(queue: string, cause: Error);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Thrown when delayed messages are requested but the plugin is not available.
+ */
+export declare class DelayedMessagesNotSupportedError extends MatadorError {
+    readonly transportName: string;
+    readonly description: string;
+    constructor(transportName: string);
+}
+/**
+ * Thrown when an event is not registered in the schema.
+ */
+export declare class EventNotRegisteredError extends MatadorError {
+    readonly eventKey: string;
+    readonly description: string;
+    constructor(eventKey: string);
+}
+/**
+ * Thrown when a subscriber is not found for an event.
+ */
+export declare class SubscriberNotRegisteredError extends MatadorError {
+    readonly subscriberName: string;
+    readonly eventKey?: string | undefined;
+    readonly description: string;
+    constructor(subscriberName: string, eventKey?: string | undefined);
+}
+/**
+ * Thrown when no subscribers exist for an event during fanout.
+ */
+export declare class NoSubscribersExistError extends MatadorError {
+    readonly eventKey: string;
+    readonly description: string;
+    constructor(eventKey: string);
+}
+/**
+ * Thrown when the schema configuration is invalid.
+ */
+export declare class InvalidSchemaError extends MatadorError {
+    readonly cause?: string | undefined;
+    readonly description: string;
+    constructor(message: string, cause?: string | undefined);
+}
+/**
+ * Thrown when a subscriber is a stub but is being processed locally.
+ */
+export declare class SubscriberIsStubError extends MatadorError {
+    readonly subscriberName: string;
+    readonly description: string;
+    constructor(subscriberName: string);
+}
+/**
+ * Thrown when a LocalTransport tries to process a stub subscriber.
+ */
+export declare class LocalTransportCannotProcessStubError extends MatadorError {
+    readonly subscriberName: string;
+    readonly description: string;
+    constructor(subscriberName: string);
+}
+/**
+ * Thrown when a queue is not found or not created.
+ */
+export declare class QueueNotFoundError extends MatadorError {
+    readonly queueName: string;
+    readonly description: string;
+    constructor(queueName: string);
+}
+/**
+ * Thrown when an event is invalid or malformed.
+ */
+export declare class InvalidEventError extends MatadorError {
+    readonly cause?: string | undefined;
+    readonly description: string;
+    constructor(message: string, cause?: string | undefined);
+}
+/**
+ * Thrown when a message has been redelivered too many times (poison message).
+ */
+export declare class MessageMaybePoisonedError extends MatadorError {
+    readonly eventId: string;
+    readonly deliveryCount: number;
+    readonly maxDeliveries: number;
+    readonly description: string;
+    constructor(eventId: string, deliveryCount: number, maxDeliveries: number);
+}
+/**
+ * Thrown when a non-idempotent message cannot be retried after redelivery.
+ */
+export declare class IdempotentMessageCannotRetryError extends MatadorError {
+    readonly eventId: string;
+    readonly subscriberName: string;
+    readonly description: string;
+    constructor(eventId: string, subscriberName: string);
+}
+/**
+ * Thrown when an operation times out.
+ */
+export declare class TimeoutError extends MatadorError {
+    readonly operation: string;
+    readonly timeoutMs: number;
+    readonly description: string;
+    constructor(operation: string, timeoutMs: number);
+}
+export declare function isMatadorError(error: unknown): error is MatadorError;
+export declare function isNotStartedError(error: unknown): error is NotStartedError;
+export declare function isTransportNotConnectedError(error: unknown): error is TransportNotConnectedError;
+export declare function isEventNotRegisteredError(error: unknown): error is EventNotRegisteredError;
+export declare function isSubscriberNotRegisteredError(error: unknown): error is SubscriberNotRegisteredError;
+export declare function isMessageMaybePoisonedError(error: unknown): error is MessageMaybePoisonedError;
+export declare function isIdempotentMessageCannotRetryError(error: unknown): error is IdempotentMessageCannotRetryError;
+//# sourceMappingURL=matador-errors.d.ts.map

package/dist/errors/matador-errors.d.ts.map

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

package/dist/errors/matador-errors.js

@@ -0,0 +1,376 @@
+/**
+ * Base class for all Matador errors.
+ * All errors have a unique name that appears in monitoring tools (e.g., DataDog)
+ * and a description explaining the error and actions to resolve it.
+ *
+ * The `name` property is automatically set to the class name for proper
+ * identification in error monitoring and logging systems.
+ */
+export class MatadorError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = this.constructor.name;
+        // Ensure name is preserved when serialized
+        Object.defineProperty(this, 'name', {
+            value: this.constructor.name,
+            enumerable: true,
+            configurable: false,
+            writable: false,
+        });
+    }
+    /**
+     * Returns a serializable representation for logging/monitoring.
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            description: this.description,
+            stack: this.stack,
+        };
+    }
+}
+// ============================================================================
+// Lifecycle Errors
+// ============================================================================
+/**
+ * Thrown when attempting to use Matador before calling start().
+ */
+export class NotStartedError extends MatadorError {
+    description = 'Matador has not been started. ' +
+        'ACTION: Call matador.start() before dispatching events or performing other operations. ' +
+        'Ensure start() completes successfully before using other methods.';
+    constructor(operation = 'operation') {
+        super(`Cannot perform ${operation}: Matador has not been started. Call start() first.`);
+    }
+}
+/**
+ * Thrown when attempting to dispatch events during shutdown.
+ */
+export class ShutdownInProgressError extends MatadorError {
+    description = 'Matador is shutting down and will not accept new events. ' +
+        'ACTION: Do not dispatch events after calling shutdown(). ' +
+        'If you need to send events, do so before initiating shutdown. ' +
+        'Consider implementing a pre-shutdown event flush if needed.';
+    constructor() {
+        super('Cannot dispatch events: Matador is shutting down.');
+    }
+}
+// ============================================================================
+// Transport Errors
+// ============================================================================
+/**
+ * Thrown when a transport operation is attempted but the transport is not connected.
+ */
+export class TransportNotConnectedError extends MatadorError {
+    transportName;
+    description = 'The transport is not connected to the message broker. ' +
+        'ACTION: Ensure the transport is connected by calling transport.connect() or matador.start(). ' +
+        'Check that the broker (e.g., RabbitMQ) is running and accessible. ' +
+        'Verify connection settings (URL, credentials, network access).';
+    constructor(transportName, operation = 'operation') {
+        super(`Cannot perform ${operation}: Transport "${transportName}" is not connected. ` +
+            `Ensure connect() was called and the broker is accessible.`);
+        this.transportName = transportName;
+    }
+}
+/**
+ * Thrown when the transport has been closed (during shutdown).
+ */
+export class TransportClosedError extends MatadorError {
+    transportName;
+    description = 'The transport has been closed and will not accept new operations. ' +
+        'ACTION: This typically occurs during application shutdown. ' +
+        'If unexpected, check for early shutdown triggers. ' +
+        'Events sent after transport closure will be lost.';
+    constructor(transportName) {
+        super(`Transport "${transportName}" has been closed and will not accept new operations.`);
+        this.transportName = transportName;
+    }
+}
+/**
+ * Thrown when all transports in a fallback chain fail.
+ */
+export class AllTransportsFailedError extends MatadorError {
+    queue;
+    errors;
+    description = 'All transports failed to send the message. ' +
+        'ACTION: Check the health of all configured transports (primary and fallbacks). ' +
+        'Review the errors array for specific failure reasons. ' +
+        'Ensure at least one transport is properly configured and reachable. ' +
+        'Consider adding a LocalTransport as a last-resort fallback.';
+    constructor(queue, errors) {
+        super(`All transports failed to send message to queue "${queue}". ` +
+            `Errors: ${errors.map((e) => e.message).join('; ')}`);
+        this.queue = queue;
+        this.errors = errors;
+    }
+}
+/**
+ * Thrown when sending a message to the transport fails.
+ */
+export class TransportSendError extends MatadorError {
+    queue;
+    cause;
+    description = 'Failed to send a message through the transport. ' +
+        'ACTION: Check the underlying error for details. Common causes: ' +
+        '(1) Transport disconnected during send, ' +
+        '(2) Network issues between application and broker, ' +
+        '(3) Broker rejected the message (size, permissions, queue limits). ' +
+        'The message was NOT delivered and should be retried or logged.';
+    constructor(queue, cause) {
+        super(`Failed to send message to queue "${queue}": ${cause.message}`);
+        this.queue = queue;
+        this.cause = cause;
+    }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            queue: this.queue,
+            cause: {
+                name: this.cause.name,
+                message: this.cause.message,
+            },
+        };
+    }
+}
+/**
+ * Thrown when delayed messages are requested but the plugin is not available.
+ */
+export class DelayedMessagesNotSupportedError extends MatadorError {
+    transportName;
+    description = 'Delayed messages were requested but the transport does not support them. ' +
+        'ACTION: For RabbitMQ, install the rabbitmq_delayed_message_exchange plugin. ' +
+        'Run: rabbitmq-plugins enable rabbitmq_delayed_message_exchange ' +
+        'Then restart RabbitMQ and reconnect. ' +
+        'Alternatively, remove delayMs from your event options if delays are not required.';
+    constructor(transportName) {
+        super(`Delayed messages require the RabbitMQ delayed message exchange plugin. ` +
+            `Install rabbitmq_delayed_message_exchange or remove delayMs from event options.`);
+        this.transportName = transportName;
+    }
+}
+// ============================================================================
+// Schema & Configuration Errors
+// ============================================================================
+/**
+ * Thrown when an event is not registered in the schema.
+ */
+export class EventNotRegisteredError extends MatadorError {
+    eventKey;
+    description = 'The event type is not registered in the schema. ' +
+        'ACTION: Register the event using matador.register(EventClass, subscribers) before dispatching. ' +
+        'If this occurs during message consumption, it may indicate schema drift between services. ' +
+        'Ensure all services have matching schema registrations for shared events.';
+    constructor(eventKey) {
+        super(`Event "${eventKey}" is not registered in schema. ` +
+            `Register it using matador.register(EventClass, subscribers).`);
+        this.eventKey = eventKey;
+    }
+}
+/**
+ * Thrown when a subscriber is not found for an event.
+ */
+export class SubscriberNotRegisteredError extends MatadorError {
+    subscriberName;
+    eventKey;
+    description = 'The subscriber is not registered for this event in the schema. ' +
+        'ACTION: Ensure the subscriber is included in the registration for this event. ' +
+        'This may occur if: (1) The subscriber was removed from the schema but messages still exist, ' +
+        '(2) Schema drift between producer and consumer services, ' +
+        '(3) A deployment is in progress with different schema versions. ' +
+        'Check the dead-letter queue for affected messages.';
+    constructor(subscriberName, eventKey) {
+        super(`Subscriber "${subscriberName}" is not registered` +
+            (eventKey ? ` for event "${eventKey}"` : '') +
+            '. Check schema registration.');
+        this.subscriberName = subscriberName;
+        this.eventKey = eventKey;
+    }
+}
+/**
+ * Thrown when no subscribers exist for an event during fanout.
+ */
+export class NoSubscribersExistError extends MatadorError {
+    eventKey;
+    description = 'The event has no subscribers registered. ' +
+        'ACTION: Register at least one subscriber for this event type. ' +
+        'If subscribers were intentionally removed, consider also removing the event dispatch. ' +
+        'Events without subscribers are not useful and may indicate configuration issues.';
+    constructor(eventKey) {
+        super(`No subscribers registered for event "${eventKey}". ` +
+            `Add subscribers using matador.register(EventClass, [subscriber1, subscriber2]).`);
+        this.eventKey = eventKey;
+    }
+}
+/**
+ * Thrown when the schema configuration is invalid.
+ */
+export class InvalidSchemaError extends MatadorError {
+    cause;
+    description = 'The schema configuration is invalid. ' +
+        'ACTION: Review the schema registration for issues. Common problems: ' +
+        '(1) Duplicate subscriber names for the same event, ' +
+        '(2) Missing required fields on event class (key, description), ' +
+        '(3) Invalid alias configuration. ' +
+        'Check the cause property for specific details.';
+    constructor(message, cause) {
+        super(`Invalid schema: ${message}` + (cause ? `. Cause: ${cause}` : ''));
+        this.cause = cause;
+    }
+}
+/**
+ * Thrown when a subscriber is a stub but is being processed locally.
+ */
+export class SubscriberIsStubError extends MatadorError {
+    subscriberName;
+    description = 'A SubscriberStub was registered in a consuming schema. ' +
+        'ACTION: SubscriberStubs should only be used in producer schemas to declare ' +
+        'that a subscriber exists in another service. ' +
+        'In the consumer service, provide a full Subscriber with a callback function. ' +
+        'Remove the stub from the consumer schema and add the actual implementation.';
+    constructor(subscriberName) {
+        super(`Subscriber "${subscriberName}" is a stub and cannot be processed locally. ` +
+            `Replace with a full Subscriber implementation in the consumer schema.`);
+        this.subscriberName = subscriberName;
+    }
+}
+/**
+ * Thrown when a LocalTransport tries to process a stub subscriber.
+ */
+export class LocalTransportCannotProcessStubError extends MatadorError {
+    subscriberName;
+    description = 'The LocalTransport cannot process events for SubscriberStubs. ' +
+        'ACTION: SubscriberStubs represent remote implementations that only RabbitMQ can route. ' +
+        'If using LocalTransport for testing, provide mock implementations instead of stubs. ' +
+        'For production fallback scenarios, be aware that stub-targeted events will be dropped.';
+    constructor(subscriberName) {
+        super(`LocalTransport cannot process stub subscriber "${subscriberName}". ` +
+            `Stub subscribers require a distributed transport like RabbitMQ.`);
+        this.subscriberName = subscriberName;
+    }
+}
+// ============================================================================
+// Queue Errors
+// ============================================================================
+/**
+ * Thrown when a queue is not found or not created.
+ */
+export class QueueNotFoundError extends MatadorError {
+    queueName;
+    description = 'The specified queue does not exist or has not been created. ' +
+        'ACTION: Ensure the queue is defined in the topology configuration. ' +
+        'Call transport.applyTopology() or matador.start() to create queues. ' +
+        'Check that the queue name matches the topology definition.';
+    constructor(queueName) {
+        super(`Queue "${queueName}" not found. ` +
+            `Ensure it is defined in topology and applyTopology() was called.`);
+        this.queueName = queueName;
+    }
+}
+// ============================================================================
+// Event Validation Errors
+// ============================================================================
+/**
+ * Thrown when an event is invalid or malformed.
+ */
+export class InvalidEventError extends MatadorError {
+    cause;
+    description = 'The event is invalid or missing required fields. ' +
+        'ACTION: Ensure the event has all required properties. ' +
+        'Common issues: missing targetSubscriber during processing, ' +
+        'null/undefined data when the event type requires data, ' +
+        'malformed event structure from codec decode failure.';
+    constructor(message, cause) {
+        super(`Invalid event: ${message}` + (cause ? `. Cause: ${cause}` : ''));
+        this.cause = cause;
+    }
+}
+// ============================================================================
+// Message Processing Errors
+// ============================================================================
+/**
+ * Thrown when a message has been redelivered too many times (poison message).
+ */
+export class MessageMaybePoisonedError extends MatadorError {
+    eventId;
+    deliveryCount;
+    maxDeliveries;
+    description = 'A message was redelivered multiple times without successful processing. ' +
+        'This usually indicates the message causes a crash or timeout during processing. ' +
+        'ACTION: (1) Check application logs for errors/crashes during message processing, ' +
+        '(2) Inspect the message in the dead-letter queue for malformed data, ' +
+        '(3) Review the subscriber code for bugs that cause crashes, ' +
+        '(4) Consider increasing processing timeout if the operation is legitimately slow. ' +
+        'This message will NOT be retried to prevent crash loops.';
+    constructor(eventId, deliveryCount, maxDeliveries) {
+        super(`Message "${eventId}" delivered ${deliveryCount} times (max: ${maxDeliveries}). ` +
+            `Possible poison message - will not be retried.`);
+        this.eventId = eventId;
+        this.deliveryCount = deliveryCount;
+        this.maxDeliveries = maxDeliveries;
+    }
+}
+/**
+ * Thrown when a non-idempotent message cannot be retried after redelivery.
+ */
+export class IdempotentMessageCannotRetryError extends MatadorError {
+    eventId;
+    subscriberName;
+    description = 'A non-idempotent subscriber received a redelivered message. ' +
+        'Retrying would risk duplicate side effects (e.g., double payments, duplicate emails). ' +
+        'ACTION: (1) Mark the subscriber as idempotent if it safely handles duplicates, ' +
+        '(2) Implement idempotency keys in the subscriber logic, ' +
+        '(3) Manually inspect and replay the message from the dead-letter queue after verification. ' +
+        'The message will be sent to the dead-letter queue for manual review.';
+    constructor(eventId, subscriberName) {
+        super(`Non-idempotent subscriber "${subscriberName}" cannot retry redelivered message "${eventId}". ` +
+            `Mark subscriber as idempotent='yes' or implement idempotency handling.`);
+        this.eventId = eventId;
+        this.subscriberName = subscriberName;
+    }
+}
+// ============================================================================
+// Timeout Errors
+// ============================================================================
+/**
+ * Thrown when an operation times out.
+ */
+export class TimeoutError extends MatadorError {
+    operation;
+    timeoutMs;
+    description = 'An operation timed out before completing. ' +
+        'ACTION: (1) Increase the timeout if the operation legitimately needs more time, ' +
+        '(2) Optimize the operation to complete faster, ' +
+        '(3) Check for deadlocks or blocking operations, ' +
+        '(4) Verify external service dependencies are responsive.';
+    constructor(operation, timeoutMs) {
+        super(`Operation "${operation}" timed out after ${timeoutMs}ms.`);
+        this.operation = operation;
+        this.timeoutMs = timeoutMs;
+    }
+}
+// ============================================================================
+// Type Guards
+// ============================================================================
+export function isMatadorError(error) {
+    return error instanceof MatadorError;
+}
+export function isNotStartedError(error) {
+    return error instanceof NotStartedError;
+}
+export function isTransportNotConnectedError(error) {
+    return error instanceof TransportNotConnectedError;
+}
+export function isEventNotRegisteredError(error) {
+    return error instanceof EventNotRegisteredError;
+}
+export function isSubscriberNotRegisteredError(error) {
+    return error instanceof SubscriberNotRegisteredError;
+}
+export function isMessageMaybePoisonedError(error) {
+    return error instanceof MessageMaybePoisonedError;
+}
+export function isIdempotentMessageCannotRetryError(error) {
+    return error instanceof IdempotentMessageCannotRetryError;
+}

package/dist/errors/retry-errors.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Base class for retry control errors.
+ * These errors control the retry behavior of message processing.
+ */
+export declare abstract class RetryControlError extends Error {
+    /**
+     * Error class name for monitoring tools.
+     */
+    readonly name: string;
+    /**
+     * Human-readable description of the error and recommended actions.
+     */
+    abstract readonly description: string;
+    constructor(message: string);
+    /**
+     * Returns a serializable representation for logging/monitoring.
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Forces retry regardless of subscriber idempotency setting.
+ * Use when you know the operation is safe to retry.
+ *
+ * ACTION: Check subscriber code to understand why retry was forced.
+ * This overrides default retry behavior based on idempotency settings.
+ */
+export declare class DoRetry extends RetryControlError {
+    readonly description: string;
+    constructor(message?: string);
+}
+/**
+ * Prevents retry regardless of subscriber idempotency setting.
+ * Use for permanent failures that should not be retried.
+ *
+ * ACTION: Check subscriber code to understand why retry was disabled.
+ * Typically used for permanent failures like invalid data or business rule violations.
+ */
+export declare class DontRetry extends RetryControlError {
+    readonly description: string;
+    constructor(message?: string);
+}
+/**
+ * Assertion error that should never be retried.
+ * Use for programming errors and invariant violations.
+ *
+ * ACTION: Review the assertion failure message to identify the bug
+ * in the event payload or subscriber logic.
+ */
+export declare class EventAssertionError extends Error {
+    readonly name: string;
+    readonly description: string;
+    constructor(message: string);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Checks if an error forces a retry.
+ */
+export declare function isDoRetry(error: unknown): error is DoRetry;
+/**
+ * Checks if an error prevents retry.
+ */
+export declare function isDontRetry(error: unknown): error is DontRetry;
+/**
+ * Checks if an error is an assertion error (never retry).
+ */
+export declare function isAssertionError(error: unknown): error is EventAssertionError;
+//# sourceMappingURL=retry-errors.d.ts.map

package/dist/errors/retry-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-errors.d.ts","sourceRoot":"","sources":["../../src/errors/retry-errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,8BAAsB,iBAAkB,SAAQ,KAAK;IACnD;;OAEG;IACH,SAAiB,IAAI,EAAE,MAAM,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAE1B,OAAO,EAAE,MAAM;IAY3B;;OAEG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAQlC;AAED;;;;;;GAMG;AACH,qBAAa,OAAQ,SAAQ,iBAAiB;IAC5C,QAAQ,CAAC,WAAW,SAGyD;gBAEjE,OAAO,SAA2B;CAG/C;AAED;;;;;;GAMG;AACH,qBAAa,SAAU,SAAQ,iBAAiB;IAC9C,QAAQ,CAAC,WAAW,SAIqD;gBAE7D,OAAO,SAA8B;CAGlD;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,SAAiB,IAAI,EAAE,MAAM,CAAC;IAE9B,QAAQ,CAAC,WAAW,SAImB;gBAE3B,OAAO,EAAE,MAAM;IAW3B,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAQlC;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAE1D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAE9D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAE7E"}