@zdavison/matador 2.0.1

package/dist/topology/builder.test.js

@@ -0,0 +1,222 @@
+import { describe, expect, it } from 'bun:test';
+import { TopologyBuilder, TopologyValidationError } from './builder.js';
+describe('TopologyBuilder', () => {
+    describe('withNamespace', () => {
+        it('should set the namespace', () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('myapp')
+                .addQueue('events')
+                .build();
+            expect(topology.namespace).toBe('myapp');
+        });
+        it('should reject empty namespace', () => {
+            const builder = TopologyBuilder.create()
+                .withNamespace('')
+                .addQueue('events');
+            expect(() => builder.build()).toThrow(TopologyValidationError);
+        });
+        it('should reject namespace starting with number', () => {
+            const builder = TopologyBuilder.create()
+                .withNamespace('123app')
+                .addQueue('events');
+            expect(() => builder.build()).toThrow(TopologyValidationError);
+        });
+        it('should allow hyphens and underscores in namespace', () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('my-app_v2')
+                .addQueue('events')
+                .build();
+            expect(topology.namespace).toBe('my-app_v2');
+        });
+    });
+    describe('addQueue', () => {
+        it('should add a queue with defaults', () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .build();
+            expect(topology.queues).toHaveLength(1);
+            expect(topology.queues[0]?.name).toBe('events');
+        });
+        it('should add queue with options', () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events', {
+                concurrency: 5,
+                consumerTimeout: 30000,
+                priorities: true,
+            })
+                .build();
+            expect(topology.queues[0]?.concurrency).toBe(5);
+            expect(topology.queues[0]?.consumerTimeout).toBe(30000);
+            expect(topology.queues[0]?.priorities).toBe(true);
+        });
+        it('should add multiple queues', () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .addQueue('notifications')
+                .addQueue('analytics')
+                .build();
+            expect(topology.queues).toHaveLength(3);
+        });
+        it('should reject duplicate queue names', () => {
+            const builder = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .addQueue('events');
+            expect(() => builder.build()).toThrow('Duplicate queue name');
+        });
+        it('should reject empty queue name', () => {
+            const builder = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('');
+            expect(() => builder.build()).toThrow('Queue name cannot be empty');
+        });
+        it('should reject queue names starting with number', () => {
+            const builder = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('123queue');
+            expect(() => builder.build()).toThrow('must start with a letter');
+        });
+        it('should reject invalid concurrency', () => {
+            const builder = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events', { concurrency: 0 });
+            expect(() => builder.build()).toThrow('concurrency must be at least 1');
+        });
+        it('should reject negative consumer timeout', () => {
+            const builder = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events', { consumerTimeout: -1 });
+            expect(() => builder.build()).toThrow('consumer timeout must be non-negative');
+        });
+    });
+    describe('withDeadLetter', () => {
+        it('should configure dead letter settings', () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .withDeadLetter({
+                unhandled: { enabled: false },
+                undeliverable: { enabled: true },
+            })
+                .build();
+            expect(topology.deadLetter.unhandled.enabled).toBe(false);
+            expect(topology.deadLetter.undeliverable.enabled).toBe(true);
+        });
+        it('should merge with defaults', () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .withDeadLetter({ unhandled: { enabled: false } })
+                .build();
+            // undeliverable should keep default
+            expect(topology.deadLetter.unhandled.enabled).toBe(false);
+            expect(topology.deadLetter.undeliverable.enabled).toBe(true);
+        });
+    });
+    describe('withRetry', () => {
+        it('should configure retry settings', () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .withRetry({
+                enabled: true,
+                defaultDelayMs: 5000,
+                maxDelayMs: 600000,
+            })
+                .build();
+            expect(topology.retry.enabled).toBe(true);
+            expect(topology.retry.defaultDelayMs).toBe(5000);
+            expect(topology.retry.maxDelayMs).toBe(600000);
+        });
+        it('should reject negative default delay', () => {
+            const builder = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .withRetry({ defaultDelayMs: -1 });
+            expect(() => builder.build()).toThrow('delay must be non-negative');
+        });
+        it('should reject max delay less than default', () => {
+            const builder = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .withRetry({
+                defaultDelayMs: 10000,
+                maxDelayMs: 5000,
+            });
+            expect(() => builder.build()).toThrow('Max retry delay must be greater than or equal to default');
+        });
+    });
+    describe('withoutRetry', () => {
+        it('should disable retry', () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .withoutRetry()
+                .build();
+            expect(topology.retry.enabled).toBe(false);
+        });
+    });
+    describe('withoutDeadLetter', () => {
+        it('should disable dead letter queues', () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .withoutDeadLetter()
+                .build();
+            expect(topology.deadLetter.unhandled.enabled).toBe(false);
+            expect(topology.deadLetter.undeliverable.enabled).toBe(false);
+        });
+    });
+    describe('validate', () => {
+        it('should return issues without throwing', () => {
+            const builder = TopologyBuilder.create();
+            const issues = builder.validate();
+            expect(issues.length).toBeGreaterThan(0);
+            expect(issues).toContain('Namespace is required');
+            expect(issues).toContain('At least one queue is required');
+        });
+        it('should return empty array for valid topology', () => {
+            const builder = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events');
+            const issues = builder.validate();
+            expect(issues).toHaveLength(0);
+        });
+    });
+    describe('build', () => {
+        it('should throw TopologyValidationError with issues', () => {
+            const builder = TopologyBuilder.create();
+            try {
+                builder.build();
+                expect(true).toBe(false); // Should not reach here
+            }
+            catch (error) {
+                expect(error).toBeInstanceOf(TopologyValidationError);
+                expect(error.issues).toContain('Namespace is required');
+            }
+        });
+        it('should return immutable topology', () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .build();
+            // Verify structure
+            expect(topology.namespace).toBe('test');
+            expect(topology.queues).toHaveLength(1);
+            expect(topology.deadLetter.unhandled.enabled).toBe(true);
+            expect(topology.retry.enabled).toBe(true);
+        });
+    });
+    describe('exact queue option', () => {
+        it('should mark queue as exact (external)', () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('external-queue', { exact: true })
+                .build();
+            expect(topology.queues[0]?.exact).toBe(true);
+        });
+    });
+});

package/dist/topology/index.d.ts

@@ -0,0 +1,5 @@
+export type { DeadLetterConfig, DeadLetterQueueConfig, QueueDefinition, RetryConfig, Topology, } from './types.js';
+export { getDeadLetterQueueName, getQualifiedQueueName, getRetryQueueName, } from './types.js';
+export type { QueueOptions } from './builder.js';
+export { TopologyBuilder, TopologyValidationError } from './builder.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/topology/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/topology/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EACf,WAAW,EACX,QAAQ,GACT,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC"}

package/dist/topology/index.js

@@ -0,0 +1,2 @@
+export { getDeadLetterQueueName, getQualifiedQueueName, getRetryQueueName, } from './types.js';
+export { TopologyBuilder, TopologyValidationError } from './builder.js';

package/dist/topology/types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Transport-agnostic topology definition.
+ * Matador owns the topology; transports translate and apply it.
+ */
+export interface Topology {
+    /** Namespace prefix for all queues */
+    readonly namespace: string;
+    /** Work queues for processing events */
+    readonly queues: readonly QueueDefinition[];
+    /** Dead-letter queue configuration */
+    readonly deadLetter: DeadLetterConfig;
+    /** Retry queue configuration */
+    readonly retry: RetryConfig;
+}
+/**
+ * Individual queue definition.
+ */
+export interface QueueDefinition {
+    /** Queue name (will be prefixed with namespace) */
+    readonly name: string;
+    /** Concurrency for this queue */
+    readonly concurrency?: number | undefined;
+    /** Consumer timeout in milliseconds */
+    readonly consumerTimeout?: number | undefined;
+    /** Enable priority support if transport allows */
+    readonly priorities?: boolean | undefined;
+    /**
+     * When true, the queue name is used exactly as provided without any
+     * modification. The namespace prefix will NOT be added, and no other
+     * transformations will be applied. Use this for referencing external
+     * queues that are not managed by Matador.
+     */
+    readonly exact?: boolean | undefined;
+}
+/**
+ * Dead-letter queue configuration.
+ */
+export interface DeadLetterConfig {
+    /** Unhandled events (schema mismatch) queue */
+    readonly unhandled: DeadLetterQueueConfig;
+    /** Undeliverable events (permanent failures) queue */
+    readonly undeliverable: DeadLetterQueueConfig;
+}
+/**
+ * Configuration for a specific dead-letter queue.
+ */
+export interface DeadLetterQueueConfig {
+    /** Whether this DLQ is enabled */
+    readonly enabled: boolean;
+    /** Maximum number of messages in the DLQ */
+    readonly maxLength?: number | undefined;
+}
+/**
+ * Retry queue configuration.
+ */
+export interface RetryConfig {
+    /** Enable retry queue with delay */
+    readonly enabled: boolean;
+    /** Default retry delay in milliseconds */
+    readonly defaultDelayMs: number;
+    /** Maximum retry delay in milliseconds */
+    readonly maxDelayMs: number;
+}
+/**
+ * Gets the fully qualified queue name with namespace prefix.
+ */
+export declare function getQualifiedQueueName(namespace: string, queueName: string): string;
+/**
+ * Gets the dead-letter queue name for a given queue.
+ */
+export declare function getDeadLetterQueueName(namespace: string, queueName: string, dlqType: 'unhandled' | 'undeliverable'): string;
+/**
+ * Gets the retry queue name for a given queue.
+ */
+export declare function getRetryQueueName(namespace: string, queueName: string): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/topology/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/topology/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,sCAAsC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,wCAAwC;IACxC,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;IAE5C,sCAAsC;IACtC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IAEtC,gCAAgC;IAChC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,iCAAiC;IACjC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE1C,uCAAuC;IACvC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE9C,kDAAkD;IAClD,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAE1C;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,EAAE,qBAAqB,CAAC;IAE1C,sDAAsD;IACtD,QAAQ,CAAC,aAAa,EAAE,qBAAqB,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,oCAAoC;IACpC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B,0CAA0C;IAC1C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC,0CAA0C;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,MAAM,CAER;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,WAAW,GAAG,eAAe,GACrC,MAAM,CAER;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,MAAM,CAER"}

package/dist/topology/types.js

@@ -0,0 +1,18 @@
+/**
+ * Gets the fully qualified queue name with namespace prefix.
+ */
+export function getQualifiedQueueName(namespace, queueName) {
+    return `${namespace}.${queueName}`;
+}
+/**
+ * Gets the dead-letter queue name for a given queue.
+ */
+export function getDeadLetterQueueName(namespace, queueName, dlqType) {
+    return `${namespace}.${queueName}.${dlqType}`;
+}
+/**
+ * Gets the retry queue name for a given queue.
+ */
+export function getRetryQueueName(namespace, queueName) {
+    return `${namespace}.${queueName}.retry`;
+}

package/dist/transport/capabilities.d.ts

@@ -0,0 +1,66 @@
+import type { DeliveryMode } from '../types/index.js';
+/**
+ * Describes the native capabilities of a transport.
+ * Matador adapts its behavior based on these capabilities.
+ */
+export interface TransportCapabilities {
+    /**
+     * Delivery semantics the transport supports.
+     * - 'at-least-once': Ack after processing (may redeliver on failure)
+     * - 'at-most-once': Ack before processing (no redelivery, may lose messages)
+     */
+    readonly deliveryModes: readonly DeliveryMode[];
+    /**
+     * Transport can delay message delivery natively.
+     * - true: Use transport's native delay (BullMQ, RabbitMQ with plugin)
+     * - false: Matador handles via retry queue with TTL or external scheduler
+     */
+    readonly delayedMessages: boolean;
+    /**
+     * Transport can route failed messages to dead-letter queue natively.
+     * - 'native': Transport handles DL routing (RabbitMQ DLX)
+     * - 'manual': Matador must send() to DLQ then complete() original
+     * - 'none': No DL support, Matador logs and discards
+     */
+    readonly deadLetterRouting: 'native' | 'manual' | 'none';
+    /**
+     * Transport tracks delivery/attempt count natively.
+     * - true: Receipt includes accurate attemptNumber from transport
+     * - false: Matador tracks attempts in envelope.docket.attempts field
+     */
+    readonly attemptTracking: boolean;
+    /**
+     * How transport handles concurrency.
+     * - 'prefetch': Channel-based prefetch (RabbitMQ)
+     * - 'worker': Worker concurrency setting (BullMQ)
+     * - 'partition': Partition-based parallelism (Kafka)
+     * - 'none': No concurrency control (Memory)
+     */
+    readonly concurrencyModel: 'prefetch' | 'worker' | 'partition' | 'none';
+    /**
+     * Message ordering guarantees.
+     * - 'none': No ordering guarantee (most transports with multiple consumers)
+     * - 'queue': Ordered within queue (single consumer scenarios)
+     * - 'partition': Ordered within partition/key (Kafka)
+     */
+    readonly ordering: 'none' | 'queue' | 'partition';
+    /**
+     * Transport supports message priority.
+     * - true: Higher priority messages processed first
+     * - false: FIFO only
+     */
+    readonly priorities: boolean;
+}
+/**
+ * Checks if the transport supports a specific delivery mode.
+ */
+export declare function supportsDeliveryMode(capabilities: TransportCapabilities, mode: DeliveryMode): boolean;
+/**
+ * Checks if the transport supports native delayed messages.
+ */
+export declare function supportsDelayedMessages(capabilities: TransportCapabilities): boolean;
+/**
+ * Checks if the transport has native dead-letter routing.
+ */
+export declare function hasNativeDeadLetter(capabilities: TransportCapabilities): boolean;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/transport/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/transport/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,CAAC;IAEhD;;;;OAIG;IACH,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAElC;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;IAEzD;;;;OAIG;IACH,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAElC;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,EAAE,UAAU,GAAG,QAAQ,GAAG,WAAW,GAAG,MAAM,CAAC;IAExE;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,GAAG,WAAW,CAAC;IAElD;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,qBAAqB,EACnC,IAAI,EAAE,YAAY,GACjB,OAAO,CAET;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,qBAAqB,GAClC,OAAO,CAET;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,qBAAqB,GAClC,OAAO,CAET"}

package/dist/transport/capabilities.js

@@ -0,0 +1,18 @@
+/**
+ * Checks if the transport supports a specific delivery mode.
+ */
+export function supportsDeliveryMode(capabilities, mode) {
+    return capabilities.deliveryModes.includes(mode);
+}
+/**
+ * Checks if the transport supports native delayed messages.
+ */
+export function supportsDelayedMessages(capabilities) {
+    return capabilities.delayedMessages;
+}
+/**
+ * Checks if the transport has native dead-letter routing.
+ */
+export function hasNativeDeadLetter(capabilities) {
+    return capabilities.deadLetterRouting === 'native';
+}

package/dist/transport/connection-manager.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Connection state machine states.
+ */
+export type ConnectionState = {
+    readonly status: 'disconnected';
+} | {
+    readonly status: 'connecting';
+    readonly attempt: number;
+} | {
+    readonly status: 'connected';
+} | {
+    readonly status: 'reconnecting';
+    readonly attempt: number;
+    readonly lastError: Error;
+} | {
+    readonly status: 'failed';
+    readonly error: Error;
+};
+/**
+ * Configuration for the connection manager.
+ */
+export interface ConnectionManagerConfig {
+    /** Maximum reconnection attempts before giving up (0 = infinite) */
+    readonly maxReconnectAttempts: number;
+    /** Initial delay between reconnection attempts (ms) */
+    readonly initialReconnectDelay: number;
+    /** Maximum delay between reconnection attempts (ms) */
+    readonly maxReconnectDelay: number;
+    /** Backoff multiplier for reconnection delay */
+    readonly backoffMultiplier: number;
+    /** Heartbeat interval for connection health (ms), optional */
+    readonly heartbeatInterval?: number;
+}
+/**
+ * Default configuration values.
+ */
+export declare const defaultConnectionConfig: ConnectionManagerConfig;
+/**
+ * Callback for state change notifications.
+ */
+export type StateChangeCallback = (state: ConnectionState) => void;
+/**
+ * Function that performs the actual connection.
+ */
+export type ConnectFn = () => Promise<void>;
+/**
+ * Function that performs disconnection.
+ */
+export type DisconnectFn = () => Promise<void>;
+/**
+ * Manages connection lifecycle with automatic reconnection.
+ */
+export declare class ConnectionManager {
+    private readonly connectFn;
+    private readonly disconnectFn;
+    private _state;
+    private readonly listeners;
+    private reconnectTimer;
+    private readonly config;
+    constructor(connectFn: ConnectFn, disconnectFn: DisconnectFn, config?: Partial<ConnectionManagerConfig>);
+    /**
+     * Current connection state.
+     */
+    get state(): ConnectionState;
+    /**
+     * Whether currently connected.
+     */
+    isConnected(): boolean;
+    /**
+     * Register a callback for connection state changes.
+     */
+    onStateChange(callback: StateChangeCallback): () => void;
+    /**
+     * Attempt to establish connection.
+     */
+    connect(): Promise<void>;
+    /**
+     * Gracefully disconnect.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Called by transport when connection is lost unexpectedly.
+     */
+    handleConnectionLost(error: Error): Promise<void>;
+    /**
+     * Calculate delay for a given attempt using exponential backoff.
+     */
+    calculateDelay(attempt: number): number;
+    private setState;
+    private handleConnectionFailure;
+    private shouldGiveUp;
+    private attemptReconnect;
+    private clearReconnectTimer;
+}
+//# sourceMappingURL=connection-manager.d.ts.map

package/dist/transport/connection-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-manager.d.ts","sourceRoot":"","sources":["../../src/transport/connection-manager.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;CAAE,GACnC;IAAE,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC3D;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAChC;IACE,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC;CAC3B,GACD;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAEzD;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,oEAAoE;IACpE,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IAEtC,uDAAuD;IACvD,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IAEvC,uDAAuD;IACvD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IAEnC,gDAAgD;IAChD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IAEnC,8DAA8D;IAC9D,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAE,uBAKrC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;AAEnE;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;AAE5C;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;AAE/C;;GAEG;AACH,qBAAa,iBAAiB;IAO1B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAP/B,OAAO,CAAC,MAAM,CAA+C;IAC7D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuC;IACjE,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;gBAG9B,SAAS,EAAE,SAAS,EACpB,YAAY,EAAE,YAAY,EAC3C,MAAM,GAAE,OAAO,CAAC,uBAAuB,CAAM;IAK/C;;OAEG;IACH,IAAI,KAAK,IAAI,eAAe,CAE3B;IAED;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,aAAa,CAAC,QAAQ,EAAE,mBAAmB,GAAG,MAAM,IAAI;IAKxD;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB9B;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAcjC;;OAEG;IACG,oBAAoB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IASvD;;OAEG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAOvC,OAAO,CAAC,QAAQ;YAWF,uBAAuB;IAiBrC,OAAO,CAAC,YAAY;YAON,gBAAgB;IAoB9B,OAAO,CAAC,mBAAmB;CAM5B"}

package/dist/transport/connection-manager.js

@@ -0,0 +1,144 @@
+/**
+ * Default configuration values.
+ */
+export const defaultConnectionConfig = {
+    maxReconnectAttempts: 0, // Infinite
+    initialReconnectDelay: 1000,
+    maxReconnectDelay: 30000,
+    backoffMultiplier: 2,
+};
+/**
+ * Manages connection lifecycle with automatic reconnection.
+ */
+export class ConnectionManager {
+    connectFn;
+    disconnectFn;
+    _state = { status: 'disconnected' };
+    listeners = new Set();
+    reconnectTimer = null;
+    config;
+    constructor(connectFn, disconnectFn, config = {}) {
+        this.connectFn = connectFn;
+        this.disconnectFn = disconnectFn;
+        this.config = { ...defaultConnectionConfig, ...config };
+    }
+    /**
+     * Current connection state.
+     */
+    get state() {
+        return this._state;
+    }
+    /**
+     * Whether currently connected.
+     */
+    isConnected() {
+        return this._state.status === 'connected';
+    }
+    /**
+     * Register a callback for connection state changes.
+     */
+    onStateChange(callback) {
+        this.listeners.add(callback);
+        return () => this.listeners.delete(callback);
+    }
+    /**
+     * Attempt to establish connection.
+     */
+    async connect() {
+        if (this._state.status === 'connected') {
+            return;
+        }
+        this.setState({ status: 'connecting', attempt: 1 });
+        try {
+            await this.connectFn();
+            this.setState({ status: 'connected' });
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            await this.handleConnectionFailure(err, 1);
+        }
+    }
+    /**
+     * Gracefully disconnect.
+     */
+    async disconnect() {
+        this.clearReconnectTimer();
+        if (this._state.status === 'disconnected') {
+            return;
+        }
+        try {
+            await this.disconnectFn();
+        }
+        finally {
+            this.setState({ status: 'disconnected' });
+        }
+    }
+    /**
+     * Called by transport when connection is lost unexpectedly.
+     */
+    async handleConnectionLost(error) {
+        if (this._state.status === 'disconnected') {
+            return;
+        }
+        this.setState({ status: 'reconnecting', attempt: 1, lastError: error });
+        await this.attemptReconnect(1);
+    }
+    /**
+     * Calculate delay for a given attempt using exponential backoff.
+     */
+    calculateDelay(attempt) {
+        const delay = this.config.initialReconnectDelay *
+            Math.pow(this.config.backoffMultiplier, attempt - 1);
+        return Math.min(delay, this.config.maxReconnectDelay);
+    }
+    setState(state) {
+        this._state = state;
+        for (const listener of this.listeners) {
+            try {
+                listener(state);
+            }
+            catch {
+                // Ignore listener errors
+            }
+        }
+    }
+    async handleConnectionFailure(error, attempt) {
+        if (this.shouldGiveUp(attempt)) {
+            this.setState({ status: 'failed', error });
+            throw error;
+        }
+        this.setState({
+            status: 'reconnecting',
+            attempt: attempt + 1,
+            lastError: error,
+        });
+        await this.attemptReconnect(attempt + 1);
+    }
+    shouldGiveUp(attempt) {
+        return (this.config.maxReconnectAttempts > 0 &&
+            attempt >= this.config.maxReconnectAttempts);
+    }
+    async attemptReconnect(attempt) {
+        const delay = this.calculateDelay(attempt);
+        await new Promise((resolve) => {
+            this.reconnectTimer = setTimeout(resolve, delay);
+        });
+        if (this._state.status === 'disconnected') {
+            return;
+        }
+        try {
+            await this.connectFn();
+            this.setState({ status: 'connected' });
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            await this.handleConnectionFailure(err, attempt);
+        }
+    }
+    clearReconnectTimer() {
+        if (this.reconnectTimer !== null) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+}