@zdavison/matador 2.0.1

package/dist/transport/index.d.ts

@@ -0,0 +1,11 @@
+export type { TransportCapabilities } from './capabilities.js';
+export { hasNativeDeadLetter, supportsDeliveryMode, supportsDelayedMessages, } from './capabilities.js';
+export type { MessageHandler, MessageReceipt, RabbitMQSendOptions, RabbitMQSubscribeOptions, SendOptions, SubscribeOptions, Subscription, Transport, TransportSendOptions, TransportSubscribeOptions, } from './transport.js';
+export type { ConnectFn, ConnectionManagerConfig, ConnectionState, DisconnectFn, StateChangeCallback, } from './connection-manager.js';
+export { ConnectionManager, defaultConnectionConfig, } from './connection-manager.js';
+export { LocalTransport } from './local/local-transport.js';
+export type { MultiTransportConfig, MultiTransportHooks, } from './multi/multi-transport.js';
+export { MultiTransport } from './multi/multi-transport.js';
+export type { RabbitMQTransportConfig } from './rabbitmq/rabbitmq-transport.js';
+export { RabbitMQTransport } from './rabbitmq/rabbitmq-transport.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transport/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EACV,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,wBAAwB,EACxB,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACV,SAAS,EACT,uBAAuB,EACvB,eAAe,EACf,YAAY,EACZ,mBAAmB,GACpB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAE5D,YAAY,EACV,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAE5D,YAAY,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAChF,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC"}

package/dist/transport/index.js

@@ -0,0 +1,5 @@
+export { hasNativeDeadLetter, supportsDeliveryMode, supportsDelayedMessages, } from './capabilities.js';
+export { ConnectionManager, defaultConnectionConfig, } from './connection-manager.js';
+export { LocalTransport } from './local/local-transport.js';
+export { MultiTransport } from './multi/multi-transport.js';
+export { RabbitMQTransport } from './rabbitmq/rabbitmq-transport.js';

package/dist/transport/local/local-transport.d.ts

@@ -0,0 +1,62 @@
+import { type Logger } from '../../hooks/index.js';
+import type { Topology } from '../../topology/types.js';
+import type { Envelope } from '../../types/index.js';
+import type { TransportCapabilities } from '../capabilities.js';
+import type { MessageHandler, MessageReceipt, SendOptions, SubscribeOptions, Subscription, Transport } from '../transport.js';
+/**
+ * Local in-memory transport for testing and fallback.
+ * Messages are stored in memory and delivered synchronously.
+ */
+export declare class LocalTransport implements Transport {
+    readonly name = "local";
+    readonly capabilities: TransportCapabilities;
+    private connected;
+    private readonly queues;
+    private readonly subscriptions;
+    private readonly completedMessages;
+    private readonly delayedTimers;
+    private messageIdCounter;
+    private readonly logger;
+    constructor(logger?: Logger);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    applyTopology(topology: Topology): Promise<void>;
+    send(queue: string, envelope: Envelope, options?: SendOptions): Promise<Transport['name']>;
+    /**
+     * Schedules a message for delayed delivery.
+     * Returns immediately (non-blocking) to match real transport behavior.
+     */
+    private scheduleDelayedMessage;
+    private enqueue;
+    private deliverToSubscribers;
+    subscribe(queue: string, handler: MessageHandler, options?: SubscribeOptions): Promise<Subscription>;
+    complete(receipt: MessageReceipt): Promise<void>;
+    sendToDeadLetter(receipt: MessageReceipt, dlqName: string, envelope: Envelope, _reason: string): Promise<void>;
+    /**
+     * Gets the current size of a queue.
+     */
+    getQueueSize(queue: string): number;
+    /**
+     * Gets all completed message receipts.
+     */
+    getCompleted(): readonly MessageReceipt[];
+    /**
+     * Gets pending (uncompleted) messages from a queue.
+     */
+    getPendingMessages(queue: string): readonly Envelope[];
+    /**
+     * Clears all state (for test isolation).
+     */
+    clear(): void;
+    /**
+     * Receives one message from the queue without a subscription.
+     * Useful for testing.
+     */
+    receiveOne(queue: string): Promise<{
+        envelope: Envelope;
+        receipt: MessageReceipt;
+    } | null>;
+    private getOrCreateQueue;
+}
+//# sourceMappingURL=local-transport.d.ts.map

package/dist/transport/local/local-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-transport.d.ts","sourceRoot":"","sources":["../../../src/transport/local/local-transport.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAAiB,MAAM,sBAAsB,CAAC;AAClE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACV,MAAM,iBAAiB,CAAC;AAiCzB;;;GAGG;AACH,qBAAa,cAAe,YAAW,SAAS;IAC9C,QAAQ,CAAC,IAAI,WAAW;IACxB,QAAQ,CAAC,YAAY,wBAAqB;IAE1C,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsC;IAC7D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA2C;IACzE,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAwB;IAC1D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4C;IAC1E,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,MAAM,CAAC,EAAE,MAAM;IAIrB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBjC,WAAW,IAAI,OAAO;IAIhB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBhD,IAAI,CACR,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAe7B;;;OAGG;IACH,OAAO,CAAC,sBAAsB;YAkBhB,OAAO;YAgBP,oBAAoB;IA4B5B,SAAS,CACb,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,cAAc,EACvB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,YAAY,CAAC;IAsClB,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAMhD,gBAAgB,CACpB,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC;IAQhB;;OAEG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAMnC;;OAEG;IACH,YAAY,IAAI,SAAS,cAAc,EAAE;IAIzC;;OAEG;IACH,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,QAAQ,EAAE;IAMtD;;OAEG;IACH,KAAK,IAAI,IAAI;IAYb;;;OAGG;IACG,UAAU,CACd,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,OAAO,EAAE,cAAc,CAAA;KAAE,GAAG,IAAI,CAAC;IAmBlE,OAAO,CAAC,gBAAgB;CAQzB"}

package/dist/transport/local/local-transport.js

@@ -0,0 +1,241 @@
+import { TransportNotConnectedError } from '../../errors/index.js';
+import { consoleLogger } from '../../hooks/index.js';
+/**
+ * Capabilities of the LocalTransport.
+ */
+const localCapabilities = {
+    deliveryModes: ['at-least-once', 'at-most-once'],
+    delayedMessages: true, // Implemented with setTimeout
+    deadLetterRouting: 'manual',
+    attemptTracking: false,
+    concurrencyModel: 'none',
+    ordering: 'queue',
+    priorities: false,
+};
+/**
+ * Local in-memory transport for testing and fallback.
+ * Messages are stored in memory and delivered synchronously.
+ */
+export class LocalTransport {
+    name = 'local';
+    capabilities = localCapabilities;
+    connected = false;
+    queues = new Map();
+    subscriptions = new Map();
+    completedMessages = [];
+    delayedTimers = new Set();
+    messageIdCounter = 0;
+    logger;
+    constructor(logger) {
+        this.logger = logger ?? consoleLogger;
+    }
+    async connect() {
+        this.connected = true;
+    }
+    async disconnect() {
+        // Cancel all delayed message timers
+        for (const timer of this.delayedTimers) {
+            clearTimeout(timer);
+        }
+        this.delayedTimers.clear();
+        // Deactivate all subscriptions
+        for (const subs of this.subscriptions.values()) {
+            for (const sub of subs) {
+                sub.active = false;
+            }
+        }
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected;
+    }
+    async applyTopology(topology) {
+        if (!this.connected) {
+            throw new TransportNotConnectedError(this.name, 'applyTopology');
+        }
+        // Initialize queues for the topology.
+        // Note: Retry queues are not pre-created here because LocalTransport handles
+        // retries by re-enqueueing messages with a delay to the original queue, matching
+        // how the pipeline schedules retries via transport.send() with a delay option.
+        for (const queueDef of topology.queues) {
+            const queueName = `${topology.namespace}.${queueDef.name}`;
+            if (!this.queues.has(queueName)) {
+                this.queues.set(queueName, []);
+            }
+        }
+    }
+    async send(queue, envelope, options) {
+        if (!this.connected) {
+            throw new TransportNotConnectedError(this.name, 'send');
+        }
+        // Handle delayed messages (non-blocking, like real transports)
+        if (options?.delay !== undefined && options.delay > 0) {
+            this.scheduleDelayedMessage(queue, envelope, options.delay);
+            return this.name;
+        }
+        await this.enqueue(queue, envelope);
+        return this.name;
+    }
+    /**
+     * Schedules a message for delayed delivery.
+     * Returns immediately (non-blocking) to match real transport behavior.
+     */
+    scheduleDelayedMessage(queue, envelope, delayMs) {
+        const timer = setTimeout(() => {
+            this.delayedTimers.delete(timer);
+            // Fire and forget - errors are logged in enqueue/deliverToSubscribers
+            this.enqueue(queue, envelope).catch((error) => {
+                this.logger.error('[Matador] 🔴 Failed to enqueue delayed message', error);
+            });
+        }, delayMs);
+        this.delayedTimers.add(timer);
+    }
+    async enqueue(queue, envelope) {
+        const messages = this.getOrCreateQueue(queue);
+        const messageId = `${++this.messageIdCounter}`;
+        const queuedMessage = {
+            envelope,
+            id: messageId,
+            completed: false,
+        };
+        messages.push(queuedMessage);
+        // Deliver to any active subscriptions
+        await this.deliverToSubscribers(queue, queuedMessage);
+    }
+    async deliverToSubscribers(queue, message) {
+        const subs = this.subscriptions.get(queue);
+        if (!subs)
+            return;
+        for (const sub of subs) {
+            if (!sub.active || message.completed)
+                continue;
+            const receipt = {
+                handle: message,
+                redelivered: false,
+                attemptNumber: message.envelope.docket.attempts,
+                deliveryCount: message.envelope.docket.attempts,
+                sourceQueue: queue,
+                sourceTransport: this.name,
+            };
+            try {
+                await sub.handler(message.envelope, receipt);
+            }
+            catch (error) {
+                // Handler errors should be caught in the pipeline
+                this.logger.error('🔴 Handler error in message processing', error);
+            }
+        }
+    }
+    async subscribe(queue, handler, options = {}) {
+        if (!this.connected) {
+            throw new TransportNotConnectedError(this.name, 'subscribe');
+        }
+        const subscription = {
+            handler,
+            options,
+            active: true,
+        };
+        const subs = this.subscriptions.get(queue) ?? [];
+        subs.push(subscription);
+        this.subscriptions.set(queue, subs);
+        // Deliver any pending messages
+        const messages = this.queues.get(queue) ?? [];
+        for (const message of messages) {
+            if (message.completed)
+                continue;
+            await this.deliverToSubscribers(queue, message);
+        }
+        return {
+            unsubscribe: async () => {
+                subscription.active = false;
+                const remaining = subs.filter((s) => s !== subscription);
+                if (remaining.length > 0) {
+                    this.subscriptions.set(queue, remaining);
+                }
+                else {
+                    this.subscriptions.delete(queue);
+                }
+            },
+            get isActive() {
+                return subscription.active;
+            },
+        };
+    }
+    async complete(receipt) {
+        const message = receipt.handle;
+        message.completed = true;
+        this.completedMessages.push(receipt);
+    }
+    async sendToDeadLetter(receipt, dlqName, envelope, _reason) {
+        const dlqQueueName = `${receipt.sourceQueue}.${dlqName}`;
+        await this.enqueue(dlqQueueName, envelope);
+        await this.complete(receipt);
+    }
+    // Test helpers
+    /**
+     * Gets the current size of a queue.
+     */
+    getQueueSize(queue) {
+        const messages = this.queues.get(queue);
+        if (!messages)
+            return 0;
+        return messages.filter((m) => !m.completed).length;
+    }
+    /**
+     * Gets all completed message receipts.
+     */
+    getCompleted() {
+        return this.completedMessages;
+    }
+    /**
+     * Gets pending (uncompleted) messages from a queue.
+     */
+    getPendingMessages(queue) {
+        const messages = this.queues.get(queue);
+        if (!messages)
+            return [];
+        return messages.filter((m) => !m.completed).map((m) => m.envelope);
+    }
+    /**
+     * Clears all state (for test isolation).
+     */
+    clear() {
+        this.queues.clear();
+        this.subscriptions.clear();
+        this.completedMessages.length = 0;
+        this.messageIdCounter = 0;
+        for (const timer of this.delayedTimers) {
+            clearTimeout(timer);
+        }
+        this.delayedTimers.clear();
+    }
+    /**
+     * Receives one message from the queue without a subscription.
+     * Useful for testing.
+     */
+    async receiveOne(queue) {
+        const messages = this.queues.get(queue);
+        if (!messages)
+            return null;
+        const pending = messages.find((m) => !m.completed);
+        if (!pending)
+            return null;
+        const receipt = {
+            handle: pending,
+            redelivered: false,
+            attemptNumber: pending.envelope.docket.attempts,
+            deliveryCount: pending.envelope.docket.attempts,
+            sourceQueue: queue,
+            sourceTransport: this.name,
+        };
+        return { envelope: pending.envelope, receipt };
+    }
+    getOrCreateQueue(queue) {
+        let messages = this.queues.get(queue);
+        if (!messages) {
+            messages = [];
+            this.queues.set(queue, messages);
+        }
+        return messages;
+    }
+}

package/dist/transport/local/local-transport.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=local-transport.test.d.ts.map

package/dist/transport/local/local-transport.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-transport.test.d.ts","sourceRoot":"","sources":["../../../src/transport/local/local-transport.test.ts"],"names":[],"mappings":""}

package/dist/transport/local/local-transport.test.js

@@ -0,0 +1,192 @@
+import { beforeEach, describe, expect, it } from 'bun:test';
+import { createEnvelope } from '../../types/index.js';
+import { LocalTransport } from './local-transport.js';
+describe('LocalTransport', () => {
+    let transport;
+    beforeEach(() => {
+        transport = new LocalTransport();
+    });
+    describe('connection', () => {
+        it('should start disconnected', () => {
+            expect(transport.isConnected()).toBe(false);
+        });
+        it('should connect successfully', async () => {
+            await transport.connect();
+            expect(transport.isConnected()).toBe(true);
+        });
+        it('should disconnect successfully', async () => {
+            await transport.connect();
+            await transport.disconnect();
+            expect(transport.isConnected()).toBe(false);
+        });
+    });
+    describe('capabilities', () => {
+        it('should report correct capabilities', () => {
+            expect(transport.name).toBe('local');
+            expect(transport.capabilities.deliveryModes).toContain('at-least-once');
+            expect(transport.capabilities.delayedMessages).toBe(true);
+            expect(transport.capabilities.deadLetterRouting).toBe('manual');
+        });
+    });
+    describe('send and receive', () => {
+        beforeEach(async () => {
+            await transport.connect();
+        });
+        it('should throw when sending while disconnected', async () => {
+            await transport.disconnect();
+            const envelope = createTestEnvelope();
+            await expect(transport.send('test-queue', envelope)).rejects.toThrow('is not connected');
+        });
+        it('should send and receive a message', async () => {
+            const envelope = createTestEnvelope();
+            await transport.send('test-queue', envelope);
+            const received = await transport.receiveOne('test-queue');
+            expect(received).not.toBeNull();
+            expect(received?.envelope.id).toBe(envelope.id);
+            expect(received?.envelope.data).toEqual({ test: 'data' });
+        });
+        it('should track queue size correctly', async () => {
+            expect(transport.getQueueSize('test-queue')).toBe(0);
+            await transport.send('test-queue', createTestEnvelope());
+            expect(transport.getQueueSize('test-queue')).toBe(1);
+            await transport.send('test-queue', createTestEnvelope());
+            expect(transport.getQueueSize('test-queue')).toBe(2);
+        });
+        it('should complete messages and remove from queue', async () => {
+            const envelope = createTestEnvelope();
+            await transport.send('test-queue', envelope);
+            const received = await transport.receiveOne('test-queue');
+            expect(received).not.toBeNull();
+            await transport.complete(received.receipt);
+            expect(transport.getQueueSize('test-queue')).toBe(0);
+            expect(transport.getCompleted()).toHaveLength(1);
+        });
+        it('should return null when queue is empty', async () => {
+            const received = await transport.receiveOne('empty-queue');
+            expect(received).toBeNull();
+        });
+    });
+    describe('subscriptions', () => {
+        beforeEach(async () => {
+            await transport.connect();
+        });
+        it('should throw when subscribing while disconnected', async () => {
+            await transport.disconnect();
+            await expect(transport.subscribe('test-queue', async () => { })).rejects.toThrow('is not connected');
+        });
+        it('should deliver messages to subscribers', async () => {
+            const receivedMessages = [];
+            await transport.subscribe('test-queue', async (envelope) => {
+                receivedMessages.push(envelope);
+            });
+            const envelope = createTestEnvelope();
+            await transport.send('test-queue', envelope);
+            expect(receivedMessages).toHaveLength(1);
+            expect(receivedMessages[0].id).toBe(envelope.id);
+        });
+        it('should deliver pending messages when subscribing', async () => {
+            const envelope = createTestEnvelope();
+            await transport.send('test-queue', envelope);
+            const receivedMessages = [];
+            await transport.subscribe('test-queue', async (env) => {
+                receivedMessages.push(env);
+            });
+            expect(receivedMessages).toHaveLength(1);
+        });
+        it('should stop delivering after unsubscribe', async () => {
+            const receivedMessages = [];
+            const subscription = await transport.subscribe('test-queue', async (envelope) => {
+                receivedMessages.push(envelope);
+            });
+            await transport.send('test-queue', createTestEnvelope());
+            expect(receivedMessages).toHaveLength(1);
+            await subscription.unsubscribe();
+            expect(subscription.isActive).toBe(false);
+        });
+    });
+    describe('dead letter queue', () => {
+        beforeEach(async () => {
+            await transport.connect();
+        });
+        it('should send messages to dead letter queue', async () => {
+            const envelope = createTestEnvelope();
+            await transport.send('test-queue', envelope);
+            const received = await transport.receiveOne('test-queue');
+            expect(received).not.toBeNull();
+            await transport.sendToDeadLetter(received.receipt, 'dlq', envelope, 'test error');
+            expect(transport.getQueueSize('test-queue')).toBe(0);
+            expect(transport.getQueueSize('test-queue.dlq')).toBe(1);
+        });
+    });
+    describe('topology', () => {
+        it('should apply topology and create queues', async () => {
+            const topology = {
+                namespace: 'test',
+                queues: [{ name: 'events' }, { name: 'notifications' }],
+                deadLetter: {
+                    unhandled: { enabled: true },
+                    undeliverable: { enabled: true },
+                },
+                retry: {
+                    enabled: true,
+                    defaultDelayMs: 1000,
+                    maxDelayMs: 30000,
+                },
+            };
+            await transport.connect();
+            await transport.applyTopology(topology);
+            // Queues should be created
+            expect(transport.getQueueSize('test.events')).toBe(0);
+            expect(transport.getQueueSize('test.notifications')).toBe(0);
+        });
+    });
+    describe('clear', () => {
+        it('should reset all state', async () => {
+            await transport.connect();
+            await transport.send('test-queue', createTestEnvelope());
+            const received = await transport.receiveOne('test-queue');
+            await transport.complete(received.receipt);
+            transport.clear();
+            expect(transport.getQueueSize('test-queue')).toBe(0);
+            expect(transport.getCompleted()).toHaveLength(0);
+        });
+    });
+    describe('delayed messages', () => {
+        beforeEach(async () => {
+            await transport.connect();
+        });
+        it('should return immediately and delay message delivery', async () => {
+            const envelope = createTestEnvelope();
+            // Send returns immediately (non-blocking)
+            await transport.send('test-queue', envelope, {
+                delay: 100,
+            });
+            // Message should not be in queue immediately
+            expect(transport.getQueueSize('test-queue')).toBe(0);
+            // Wait for the delay to pass
+            await new Promise((resolve) => setTimeout(resolve, 150));
+            // Message should now be in queue
+            expect(transport.getQueueSize('test-queue')).toBe(1);
+        });
+        it('should cancel delayed messages on disconnect', async () => {
+            const envelope = createTestEnvelope();
+            await transport.send('test-queue', envelope, {
+                delay: 100,
+            });
+            // Disconnect before delay expires
+            await transport.disconnect();
+            // Wait past the original delay
+            await new Promise((resolve) => setTimeout(resolve, 150));
+            // Message should never have been delivered
+            expect(transport.getQueueSize('test-queue')).toBe(0);
+        });
+    });
+});
+function createTestEnvelope() {
+    return createEnvelope({
+        eventKey: 'test.event',
+        targetSubscriber: 'test-subscriber',
+        data: { test: 'data' },
+        importance: 'should-investigate',
+    });
+}

package/dist/transport/multi/multi-transport.d.ts

@@ -0,0 +1,94 @@
+import type { TransportFallbackContext } from '../../hooks/index.js';
+import type { Topology } from '../../topology/types.js';
+import type { Envelope } from '../../types/index.js';
+import type { TransportCapabilities } from '../capabilities.js';
+import type { MessageHandler, MessageReceipt, SendOptions, SubscribeOptions, Subscription, Transport } from '../transport.js';
+/**
+ * Configuration for MultiTransport.
+ */
+export interface MultiTransportConfig {
+    /**
+     * Ordered list of transports.
+     * First transport is primary, rest are used as fallbacks when primary fails
+     * (if fallback is enabled), or can be explicitly selected via the getDesiredBackend hook.
+     */
+    readonly transports: readonly Transport[];
+    /**
+     * Whether to automatically try fallback transports when the primary/selected fails.
+     * When true (default), send() will try each transport in order until one succeeds.
+     * When false, send() will only use the selected transport and throw immediately on failure.
+     *
+     * @default true
+     */
+    readonly fallbackEnabled?: boolean;
+}
+/**
+ * Hooks for MultiTransport.
+ */
+export interface MultiTransportHooks {
+    /**
+     * Hook to dynamically select which backend to use.
+     * Return the transport name (e.g., 'local', 'rabbitmq') or undefined to use primary.
+     *
+     * @example
+     * ```typescript
+     * getDesiredBackend: async () => {
+     *   if (process.env.SANDBOX === 'true') return 'local';
+     *   const backend = await runtimeConfig.get('events.backend');
+     *   return backend || 'rabbitmq';
+     * }
+     * ```
+     */
+    readonly getDesiredBackend?: () => string | undefined | Promise<string | undefined>;
+    /**
+     * Called when a fallback transport is used successfully after the selected one fails.
+     * Only called when fallbackEnabled is true.
+     */
+    readonly onEnqueueFallback?: (context: TransportFallbackContext) => void;
+}
+/**
+ * A transport wrapper that manages multiple transports.
+ *
+ * Features:
+ * - All transports are connected upfront
+ * - send() tries transports in order until one succeeds (fallback behavior)
+ * - Specific transport can be selected via getDesiredBackend hook
+ * - Subscriptions are created on ALL transports
+ *
+ * @example
+ * ```typescript
+ * const transport = new MultiTransport(
+ *   { transports: [rabbitMQTransport, localTransport] },
+ *   { onEnqueueFallback: (ctx) => console.warn(`Fallback to ${ctx.nextTransport}`) },
+ * );
+ * ```
+ */
+export declare class MultiTransport implements Transport {
+    readonly name: string;
+    readonly capabilities: TransportCapabilities;
+    readonly primary: Transport;
+    /** All available transports, in order of preference (primary first). */
+    readonly transports: readonly Transport[];
+    /** Whether fallback to secondary transports is enabled. */
+    readonly fallbackEnabled: boolean;
+    private readonly hooks;
+    private connected;
+    constructor(config: MultiTransportConfig, hooks?: MultiTransportHooks);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    applyTopology(topology: Topology): Promise<void>;
+    send(queue: string, envelope: Envelope, options?: SendOptions): Promise<Transport['name']>;
+    /**
+     * Selects the transport to use based on the getDesiredBackend hook.
+     */
+    private selectTransport;
+    /**
+     * Returns transports in order, with the selected transport first.
+     */
+    private getTransportOrder;
+    subscribe(queue: string, handler: MessageHandler, options?: SubscribeOptions): Promise<Subscription>;
+    complete(receipt: MessageReceipt): Promise<void>;
+    sendToDeadLetter(receipt: MessageReceipt, dlqName: string, envelope: Envelope, reason: string): Promise<void>;
+}
+//# sourceMappingURL=multi-transport.d.ts.map

package/dist/transport/multi/multi-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-transport.d.ts","sourceRoot":"","sources":["../../../src/transport/multi/multi-transport.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACV,MAAM,iBAAiB,CAAC;AAgBzB;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,CAAC;IAE1C;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MACzB,MAAM,GACN,SAAS,GACT,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAEhC;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,wBAAwB,KAAK,IAAI,CAAC;CAC1E;AAmBD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,cAAe,YAAW,SAAS;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,qBAAqB,CAAC;IAC7C,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAE5B,wEAAwE;IACxE,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,CAAC;IAE1C,2DAA2D;IAC3D,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAElC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsB;IAC5C,OAAO,CAAC,SAAS,CAAS;gBAEd,MAAM,EAAE,oBAAoB,EAAE,KAAK,GAAE,mBAAwB;IAcnE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAMxB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAMjC,WAAW,IAAI,OAAO;IAKhB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAKhD,IAAI,CACR,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAyC7B;;OAEG;YACW,eAAe;IAwB7B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IASnB,SAAS,CACb,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,YAAY,CAAC;IA0BlB,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAKhD,gBAAgB,CACpB,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC;CAOjB"}