@zdavison/matador 4.0.0 → 4.0.2

package/dist/core/fanout.d.ts

@@ -12,6 +12,7 @@ export interface FanoutConfig {
     readonly hooks: SafeHooks;
     readonly topology: Topology;
     readonly defaultQueue: string;
+    readonly maxRetryBufferSize?: number | undefined;
 }
 /**
  * Result of sending an event.
@@ -46,7 +47,11 @@ export declare class FanoutEngine {
     private readonly topology;
     private readonly defaultQueue;
     private enqueuingCount;
+    private readonly retryBuffer;
+    private readonly maxRetryBufferSize;
+    private readonly disposeOnConnected;
     constructor(config: FanoutConfig);
+    dispose(): void;
     /**
      * Current count of events being enqueued.
      */
@@ -55,6 +60,12 @@ export declare class FanoutEngine {
      * Sends an event to all registered subscribers.
      */
     send<T>(eventClass: EventClass<T>, event: Event<T>, options?: EventOptions): Promise<SendResult>;
+    /**
+     * Flushes the retry buffer
+     *
+     * This is called when the transport reconnects, and is used to retry any messages that were buffered while the transport was disconnected
+     */
+    private flushRetryBuffer;
     private isSubscriberEnabled;
 }
 //# sourceMappingURL=fanout.d.ts.map

package/dist/core/fanout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fanout.d.ts","sourceRoot":"","sources":["../../src/core/fanout.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAEV,KAAK,EACL,UAAU,EACV,YAAY,EACb,MAAM,mBAAmB,CAAC;AAG3B;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,cAAc,CAAK;gBAEf,MAAM,EAAE,YAAY;IAQhC;;OAEG;IACH,IAAI,wBAAwB,IAAI,MAAM,CAErC;IAED;;OAEG;IACG,IAAI,CAAC,CAAC,EACV,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EACzB,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EACf,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,UAAU,CAAC;YAsFR,mBAAmB;CAelC"}
+{"version":3,"file":"fanout.d.ts","sourceRoot":"","sources":["../../src/core/fanout.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,KAAK,EAAe,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,KAAK,EAGV,KAAK,EACL,UAAU,EACV,YAAY,EACb,MAAM,mBAAmB,CAAC;AAa3B;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClD;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsB;IAClD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA2B;gBAElD,MAAM,EAAE,YAAY;IAehC,OAAO,IAAI,IAAI;IAKf;;OAEG;IACH,IAAI,wBAAwB,IAAI,MAAM,CAErC;IAED;;OAEG;IACG,IAAI,CAAC,CAAC,EACV,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EACzB,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EACf,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,UAAU,CAAC;IAyHtB;;;;OAIG;YACW,gBAAgB;YAsDhB,mBAAmB;CAelC"}

package/dist/core/fanout.js

@@ -17,12 +17,25 @@ export class FanoutEngine {
     topology;
     defaultQueue;
     enqueuingCount = 0;
+    retryBuffer = [];
+    maxRetryBufferSize;
+    disposeOnConnected;
     constructor(config) {
         this.transport = config.transport;
         this.schema = config.schema;
         this.hooks = config.hooks;
         this.topology = config.topology;
         this.defaultQueue = config.defaultQueue;
+        this.maxRetryBufferSize = config.maxRetryBufferSize ?? 5000;
+        // If the transport supports it, add a callback to flush the retry buffer when the transport reconnects
+        // The returned value is a function to unsubscribe from the callback
+        this.disposeOnConnected = this.transport.onConnected?.(() => {
+            void this.flushRetryBuffer();
+        });
+    }
+    dispose() {
+        // Unsubscribe from the callback (that flushes the retry buffer when the transport reconnects)
+        this.disposeOnConnected?.();
     }
     /**
      * Current count of events being enqueued.
@@ -68,11 +81,10 @@ export class FanoutEngine {
                 delayMs: options.delayMs,
             });
             // Send to transport
+            const sendOptions = options.delayMs !== undefined ? { delay: options.delayMs } : undefined;
             this.enqueuingCount++;
             try {
-                const usedTransport = await this.transport.send(qualifiedQueue, envelope, options.delayMs !== undefined
-                    ? { delay: options.delayMs }
-                    : undefined);
+                const usedTransport = await this.transport.send(qualifiedQueue, envelope, sendOptions);
                 sent++;
                 await this.hooks.onEnqueueSuccess({
                     envelope,
@@ -82,17 +94,46 @@ export class FanoutEngine {
             }
             catch (error) {
                 const cause = error instanceof Error ? error : new Error(String(error));
-                const err = new TransportSendError(qualifiedQueue, cause);
-                errors.push({
-                    subscriberName: subscriber.name,
-                    queue: qualifiedQueue,
-                    error: err,
-                });
-                await this.hooks.onEnqueueError({
-                    envelope,
-                    error: err,
-                    transport: this.transport.name,
-                });
+                const shouldBuffer = options.buffer !== false;
+                if (shouldBuffer && this.retryBuffer.length < this.maxRetryBufferSize) {
+                    this.retryBuffer.push({
+                        queue: qualifiedQueue,
+                        envelope,
+                        sendOptions,
+                        subscriberName: subscriber.name,
+                    });
+                    this.hooks.logger.warn(`[Matador] 🟡 Message for '${subscriber.name}' buffered for retry on reconnect (buffer: ${this.retryBuffer.length}/${this.maxRetryBufferSize}).`);
+                    if (options.throwOnBufferedFailure) {
+                        const err = new TransportSendError(qualifiedQueue, cause);
+                        // By adding the error, the main Send in Matador will throw
+                        errors.push({
+                            subscriberName: subscriber.name,
+                            queue: qualifiedQueue,
+                            error: err,
+                        });
+                        await this.hooks.onEnqueueError({
+                            envelope,
+                            error: err,
+                            transport: this.transport.name,
+                        });
+                    }
+                }
+                else {
+                    if (shouldBuffer) {
+                        this.hooks.logger.error(`[Matador] 🔴 Retry buffer full (${this.maxRetryBufferSize}). Message for '${subscriber.name}' dropped and will not be retried.`);
+                    }
+                    const err = new TransportSendError(qualifiedQueue, cause);
+                    errors.push({
+                        subscriberName: subscriber.name,
+                        queue: qualifiedQueue,
+                        error: err,
+                    });
+                    await this.hooks.onEnqueueError({
+                        envelope,
+                        error: err,
+                        transport: this.transport.name,
+                    });
+                }
             }
             finally {
                 this.enqueuingCount--;
@@ -105,6 +146,54 @@ export class FanoutEngine {
             errors,
         };
     }
+    /**
+     * Flushes the retry buffer
+     *
+     * This is called when the transport reconnects, and is used to retry any messages that were buffered while the transport was disconnected
+     */
+    async flushRetryBuffer() {
+        if (this.retryBuffer.length === 0)
+            return;
+        this.hooks.logger.info(`[Matador] ⏳ Flushing ${this.retryBuffer.length} buffered message(s)...`);
+        // Drain the buffer atomically so concurrent flush calls don't double-send.
+        const toFlush = this.retryBuffer.splice(0);
+        for (const item of toFlush) {
+            this.enqueuingCount++;
+            try {
+                const usedTransport = await this.transport.send(item.queue, item.envelope, item.sendOptions);
+                await this.hooks.onEnqueueSuccess({
+                    envelope: item.envelope,
+                    queue: item.queue,
+                    transport: usedTransport,
+                });
+            }
+            catch (error) {
+                // Re-buffer on failure; it will be retried on the next reconnect.
+                if (this.retryBuffer.length < this.maxRetryBufferSize) {
+                    this.retryBuffer.push(item);
+                }
+                else {
+                    const cause = error instanceof Error ? error : new Error(String(error));
+                    const err = new TransportSendError(item.queue, cause);
+                    await this.hooks.onEnqueueError({
+                        envelope: item.envelope,
+                        error: err,
+                        transport: this.transport.name,
+                    });
+                }
+            }
+            finally {
+                this.enqueuingCount--;
+            }
+        }
+        const remaining = this.retryBuffer.length;
+        if (remaining > 0) {
+            this.hooks.logger.warn(`[Matador] 🟡 ${remaining} buffered message(s) could not be flushed; will retry on next reconnect.`);
+        }
+        else {
+            this.hooks.logger.info('[Matador] 🟢 All buffered messages flushed successfully.');
+        }
+    }
     async isSubscriberEnabled(subscriber) {
         if (!subscriber.enabled) {
             return true;

package/dist/core/fanout.test.js

@@ -3,6 +3,7 @@ import { TransportSendError } from '../errors/index.js';
 import { SafeHooks } from '../hooks/index.js';
 import { SchemaRegistry } from '../schema/index.js';
 import { TopologyBuilder } from '../topology/index.js';
+import { MultiTransport } from '../transport/index.js';
 import { MatadorEvent, createSubscriber, createSubscriberStub, } from '../types/index.js';
 import { FanoutEngine } from './fanout.js';
 class UserCreatedEvent extends MatadorEvent {
@@ -514,7 +515,7 @@ describe('FanoutEngine', () => {
         });
     });
     describe('error handling', () => {
-        it('should capture error when transport.send fails', async () => {
+        it('should capture error when transport.send fails and buffer is disabled', async () => {
             const sendError = new Error('Network timeout');
             const failingTransport = {
                 ...transport,
@@ -539,7 +540,7 @@ describe('FanoutEngine', () => {
                 userId: '123',
                 email: 'test@example.com',
             });
-            const result = await fanoutWithFailingTransport.send(UserCreatedEvent, event);
+            const result = await fanoutWithFailingTransport.send(UserCreatedEvent, event, { buffer: false });
             expect(result.subscribersSent).toBe(0);
             expect(result.subscribersSkipped).toBe(0);
             expect(result.errors).toHaveLength(1);
@@ -581,7 +582,7 @@ describe('FanoutEngine', () => {
                 userId: '123',
                 email: 'test@example.com',
             });
-            const result = await fanoutWithFailingTransport.send(UserCreatedEvent, event);
+            const result = await fanoutWithFailingTransport.send(UserCreatedEvent, event, { buffer: false });
             expect(result.subscribersSent).toBe(1);
             expect(result.subscribersSkipped).toBe(0);
             expect(result.errors).toHaveLength(1);
@@ -611,7 +612,7 @@ describe('FanoutEngine', () => {
                 userId: '123',
                 email: 'test@example.com',
             });
-            const result = await fanoutWithFailingTransport.send(UserCreatedEvent, event);
+            const result = await fanoutWithFailingTransport.send(UserCreatedEvent, event, { buffer: false });
             expect(result.errors).toHaveLength(1);
             expect(result.errors[0]?.error).toBeInstanceOf(TransportSendError);
             expect(result.errors[0]?.error.message).toContain('matador.test.events');
@@ -867,7 +868,9 @@ describe('FanoutEngine', () => {
                 userId: '123',
                 email: 'test@example.com',
             });
-            await fanoutWithHooks.send(UserCreatedEvent, event);
+            await fanoutWithHooks.send(UserCreatedEvent, event, {
+                throwOnBufferedFailure: true,
+            });
             expect(onEnqueueError).toHaveBeenCalledTimes(1);
             expect(onEnqueueError).toHaveBeenCalledWith({
                 envelope: expect.any(Object),
@@ -1069,4 +1072,373 @@ describe('FanoutEngine', () => {
             expect(envelope.docket.importance).toBe('should-investigate');
         });
     });
+    describe('retry buffering', () => {
+        it('should buffer a failed send and not return it as an error', async () => {
+            const subscriber = createSubscriber({
+                name: 'handle-user',
+                description: 'Handles user events',
+                callback: async () => { },
+            });
+            schema.register(UserCreatedEvent, [subscriber]);
+            const failingTransport = {
+                ...transport,
+                send: mock(async () => {
+                    throw new Error('Connection lost');
+                }),
+            };
+            const fanoutWithFailingTransport = new FanoutEngine({
+                transport: failingTransport,
+                schema,
+                hooks,
+                topology: testTopology,
+                defaultQueue: 'events',
+            });
+            const event = new UserCreatedEvent({
+                userId: '123',
+                email: 'test@example.com',
+            });
+            const result = await fanoutWithFailingTransport.send(UserCreatedEvent, event);
+            expect(result.errors).toHaveLength(0);
+            expect(result.subscribersSent).toBe(0);
+        });
+        it('should buffer stub failures too', async () => {
+            const stub = createSubscriberStub({ name: 'remote-service' });
+            schema.register(UserCreatedEvent, [stub]);
+            const failingTransport = {
+                ...transport,
+                send: mock(async () => {
+                    throw new Error('Connection lost');
+                }),
+            };
+            const fanoutWithFailingTransport = new FanoutEngine({
+                transport: failingTransport,
+                schema,
+                hooks,
+                topology: testTopology,
+                defaultQueue: 'events',
+            });
+            const event = new UserCreatedEvent({
+                userId: '123',
+                email: 'test@example.com',
+            });
+            const result = await fanoutWithFailingTransport.send(UserCreatedEvent, event);
+            expect(result.errors).toHaveLength(0);
+            expect(result.subscribersSent).toBe(0);
+        });
+        it('should flush buffered messages when onConnected fires', async () => {
+            let connectedCallback;
+            const failThenSucceed = mock(async () => {
+                throw new Error('Connection lost');
+            });
+            const transportWithReconnect = {
+                ...transport,
+                send: failThenSucceed,
+                onConnected: (cb) => {
+                    connectedCallback = cb;
+                    return () => { };
+                },
+            };
+            const fanoutWithReconnect = new FanoutEngine({
+                transport: transportWithReconnect,
+                schema,
+                hooks,
+                topology: testTopology,
+                defaultQueue: 'events',
+            });
+            const subscriber = createSubscriber({
+                name: 'handle-user',
+                description: 'Handles user events',
+                callback: async () => { },
+            });
+            schema.register(UserCreatedEvent, [subscriber]);
+            const event = new UserCreatedEvent({
+                userId: '123',
+                email: 'test@example.com',
+            });
+            // First send — transport fails, message should be buffered
+            await fanoutWithReconnect.send(UserCreatedEvent, event);
+            expect(failThenSucceed).toHaveBeenCalledTimes(1);
+            // Simulate reconnect — now send succeeds
+            transportWithReconnect.send.mockImplementation(async () => 'mock');
+            expect(connectedCallback).toBeDefined();
+            connectedCallback?.();
+            // Give the async flush a chance to run
+            await new Promise((resolve) => setTimeout(resolve, 0));
+            expect(transportWithReconnect.send).toHaveBeenCalledTimes(2);
+        });
+        it('should re-buffer on flush failure and retry on next reconnect', async () => {
+            let connectedCallback;
+            const transportWithReconnect = {
+                ...transport,
+                send: mock(async () => {
+                    throw new Error('Still down');
+                }),
+                onConnected: (cb) => {
+                    connectedCallback = cb;
+                    return () => { };
+                },
+            };
+            const fanoutWithReconnect = new FanoutEngine({
+                transport: transportWithReconnect,
+                schema,
+                hooks,
+                topology: testTopology,
+                defaultQueue: 'events',
+            });
+            const subscriber = createSubscriber({
+                name: 'handle-user',
+                description: 'Handles user events',
+                callback: async () => { },
+            });
+            schema.register(UserCreatedEvent, [subscriber]);
+            const event = new UserCreatedEvent({
+                userId: '123',
+                email: 'test@example.com',
+            });
+            await fanoutWithReconnect.send(UserCreatedEvent, event);
+            expect(transportWithReconnect.send).toHaveBeenCalledTimes(1);
+            // Simulate reconnect — flush fails, item should be re-buffered
+            connectedCallback?.();
+            await new Promise((resolve) => setTimeout(resolve, 0));
+            // send was attempted again during the flush
+            expect(transportWithReconnect.send).toHaveBeenCalledTimes(2);
+            // Simulate a second reconnect — should retry again
+            connectedCallback?.();
+            await new Promise((resolve) => setTimeout(resolve, 0));
+            expect(transportWithReconnect.send).toHaveBeenCalledTimes(3);
+        });
+        it('should not buffer when transport works fine', async () => {
+            let connectedCallback;
+            const successTransport = {
+                ...transport,
+                onConnected: (cb) => {
+                    connectedCallback = cb;
+                    return () => { };
+                },
+            };
+            const fanoutWithReconnect = new FanoutEngine({
+                transport: successTransport,
+                schema,
+                hooks,
+                topology: testTopology,
+                defaultQueue: 'events',
+            });
+            const subscriber = createSubscriber({
+                name: 'handle-user',
+                description: 'Handles user events',
+                callback: async () => { },
+            });
+            schema.register(UserCreatedEvent, [subscriber]);
+            const event = new UserCreatedEvent({
+                userId: '123',
+                email: 'test@example.com',
+            });
+            const result = await fanoutWithReconnect.send(UserCreatedEvent, event);
+            expect(result.subscribersSent).toBe(1);
+            expect(result.errors).toHaveLength(0);
+            // onConnected fires — nothing buffered so flush is a no-op
+            connectedCallback?.();
+            await new Promise((resolve) => setTimeout(resolve, 0));
+            // Only one call total (the original send — not a spurious re-send)
+            expect(successTransport.send).toHaveBeenCalledTimes(1);
+        });
+        it('should report error in result when buffer is false', async () => {
+            const subscriber = createSubscriber({
+                name: 'handle-user',
+                description: 'Handles user events',
+                callback: async () => { },
+            });
+            schema.register(UserCreatedEvent, [subscriber]);
+            const failingTransport = {
+                ...transport,
+                send: mock(async () => {
+                    throw new Error('Connection lost');
+                }),
+            };
+            const fanoutWithFailingTransport = new FanoutEngine({
+                transport: failingTransport,
+                schema,
+                hooks,
+                topology: testTopology,
+                defaultQueue: 'events',
+            });
+            const event = new UserCreatedEvent({
+                userId: '123',
+                email: 'test@example.com',
+            });
+            const result = await fanoutWithFailingTransport.send(UserCreatedEvent, event, { buffer: false });
+            expect(result.errors).toHaveLength(1);
+            expect(result.errors[0]?.subscriberName).toBe('handle-user');
+            expect(result.errors[0]?.error).toBeInstanceOf(TransportSendError);
+        });
+        it('should both buffer and report error when reportBufferedFailure is true', async () => {
+            let connectedCallback;
+            const failingTransport = {
+                ...transport,
+                send: mock(async () => {
+                    throw new Error('Connection lost');
+                }),
+                onConnected: (cb) => {
+                    connectedCallback = cb;
+                    return () => { };
+                },
+            };
+            const fanoutWithReconnect = new FanoutEngine({
+                transport: failingTransport,
+                schema,
+                hooks,
+                topology: testTopology,
+                defaultQueue: 'events',
+            });
+            const subscriber = createSubscriber({
+                name: 'handle-user',
+                description: 'Handles user events',
+                callback: async () => { },
+            });
+            schema.register(UserCreatedEvent, [subscriber]);
+            const event = new UserCreatedEvent({
+                userId: '123',
+                email: 'test@example.com',
+            });
+            const result = await fanoutWithReconnect.send(UserCreatedEvent, event, {
+                throwOnBufferedFailure: true,
+            });
+            // Error is reported immediately
+            expect(result.errors).toHaveLength(1);
+            expect(result.errors[0]?.subscriberName).toBe('handle-user');
+            // But it was also buffered — it should retry on reconnect
+            failingTransport.send.mockImplementation(async () => 'mock');
+            connectedCallback?.();
+            await new Promise((resolve) => setTimeout(resolve, 0));
+            expect(failingTransport.send).toHaveBeenCalledTimes(2);
+        });
+        it('should unsubscribe the onConnected listener when dispose() is called', () => {
+            const unsubscribe = mock(() => { });
+            const transportWithOnConnected = {
+                ...transport,
+                onConnected: mock((_cb) => unsubscribe),
+            };
+            const fanout = new FanoutEngine({
+                transport: transportWithOnConnected,
+                schema,
+                hooks,
+                topology: testTopology,
+                defaultQueue: 'events',
+            });
+            expect(unsubscribe).not.toHaveBeenCalled();
+            fanout.dispose();
+            expect(unsubscribe).toHaveBeenCalledTimes(1);
+        });
+        it('should drop and report error when retry buffer is full', async () => {
+            const subscriber = createSubscriber({
+                name: 'handle-user',
+                description: 'Handles user events',
+                callback: async () => { },
+            });
+            schema.register(UserCreatedEvent, [subscriber]);
+            const failingTransport = {
+                ...transport,
+                send: mock(async () => {
+                    throw new Error('Connection lost');
+                }),
+            };
+            const fanoutWithSmallBuffer = new FanoutEngine({
+                transport: failingTransport,
+                schema,
+                hooks,
+                topology: testTopology,
+                defaultQueue: 'events',
+                maxRetryBufferSize: 1,
+            });
+            const event = new UserCreatedEvent({
+                userId: '123',
+                email: 'test@example.com',
+            });
+            // First send fills the buffer
+            const first = await fanoutWithSmallBuffer.send(UserCreatedEvent, event);
+            expect(first.errors).toHaveLength(0);
+            // Second send hits the full buffer — must report an error
+            const second = await fanoutWithSmallBuffer.send(UserCreatedEvent, event);
+            expect(second.errors).toHaveLength(1);
+            expect(second.errors[0]?.error).toBeInstanceOf(TransportSendError);
+        });
+        it('should report buffer-full drop via onEnqueueError on initial send', async () => {
+            const onEnqueueError = mock(async () => { });
+            const hooksInstance = new SafeHooks({
+                onEnqueueError,
+            });
+            const failingTransport = {
+                ...transport,
+                send: mock(async () => {
+                    throw new Error('Connection lost');
+                }),
+            };
+            const subscriber = createSubscriber({
+                name: 'handle-user',
+                description: 'Handles user events',
+                callback: async () => { },
+            });
+            schema.register(UserCreatedEvent, [subscriber]);
+            const fanoutWithSmallBuffer = new FanoutEngine({
+                transport: failingTransport,
+                schema,
+                hooks: hooksInstance,
+                topology: testTopology,
+                defaultQueue: 'events',
+                maxRetryBufferSize: 1,
+            });
+            const event = new UserCreatedEvent({
+                userId: '123',
+                email: 'test@example.com',
+            });
+            // First send fills the buffer — no error reported to caller or hook
+            const first = await fanoutWithSmallBuffer.send(UserCreatedEvent, event);
+            expect(first.errors).toHaveLength(0);
+            expect(onEnqueueError).not.toHaveBeenCalled();
+            // Second send finds the buffer full — onEnqueueError fires and error is returned
+            const second = await fanoutWithSmallBuffer.send(UserCreatedEvent, event);
+            expect(second.errors).toHaveLength(1);
+            expect(onEnqueueError).toHaveBeenCalledTimes(1);
+        });
+        it('should not buffer when a fallback transport succeeds after the primary fails', async () => {
+            const rabbitMock = {
+                ...transport,
+                name: 'rabbitmq',
+                send: mock(async () => {
+                    throw new Error('RabbitMQ down');
+                }),
+            };
+            const localMock = {
+                ...transport,
+                name: 'local',
+                send: mock(async () => 'local'),
+            };
+            const multiTransport = new MultiTransport({
+                transports: [rabbitMock, localMock],
+            });
+            const fanoutWithMulti = new FanoutEngine({
+                transport: multiTransport,
+                schema,
+                hooks,
+                topology: testTopology,
+                defaultQueue: 'events',
+            });
+            const subscriber = createSubscriber({
+                name: 'handle-user',
+                description: 'Handles user events',
+                callback: async () => { },
+            });
+            schema.register(UserCreatedEvent, [subscriber]);
+            const event = new UserCreatedEvent({
+                userId: '123',
+                email: 'test@example.com',
+            });
+            const result = await fanoutWithMulti.send(UserCreatedEvent, event);
+            expect(result.subscribersSent).toBe(1);
+            expect(result.errors).toHaveLength(0);
+            expect(rabbitMock.send).toHaveBeenCalledTimes(1);
+            expect(localMock.send).toHaveBeenCalledTimes(1);
+            expect(fanoutWithMulti.eventsBeingEnqueuedCount).toBe(0);
+        });
+    });
 });

package/dist/core/matador.d.ts.map

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

package/dist/core/matador.js

@@ -235,6 +235,7 @@ export class Matador {
         if (!this.started) {
             return;
         }
+        this.fanout.dispose();
         await this.shutdownManager.shutdown();
         this.started = false;
     }

package/dist/core/matador.test.js

@@ -317,7 +317,7 @@ describe('Matador', () => {
                 throw sendError;
             });
             const thrown = await matador
-                .send(new UserCreatedEvent({ userId: '123', email: 'test@example.com' }))
+                .send(new UserCreatedEvent({ userId: '123', email: 'test@example.com' }), { buffer: false })
                 .catch((e) => e);
             expect(thrown).toBeInstanceOf(SomeSendError);
             expect(thrown.eventKey).toBe(UserCreatedEvent.key);