@zdavison/matador 2.0.1

package/dist/core/matador.test.js

@@ -0,0 +1,446 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { TopologyBuilder } from '../topology/builder.js';
+import { LocalTransport } from '../transport/local/local-transport.js';
+import { MatadorEvent, createSubscriber } from '../types/index.js';
+import { Matador } from './matador.js';
+class UserCreatedEvent extends MatadorEvent {
+    data;
+    static key = 'user.created';
+    static description = 'Fired when a new user is created';
+    constructor(data) {
+        super();
+        this.data = data;
+    }
+}
+class OrderPlacedEvent extends MatadorEvent {
+    data;
+    static key = 'order.placed';
+    static description = 'Fired when an order is placed';
+    constructor(data) {
+        super();
+        this.data = data;
+    }
+}
+describe('Matador', () => {
+    let transport;
+    let matador;
+    beforeEach(() => {
+        transport = new LocalTransport();
+    });
+    afterEach(async () => {
+        if (matador) {
+            await matador.shutdown();
+        }
+    });
+    describe('configuration', () => {
+        it('should create with schema in config using constructor', () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .build();
+            const subscriber = createSubscriber({
+                name: 'handle-user',
+                description: 'Handles user events',
+                callback: async () => { },
+            });
+            const schema = {
+                [UserCreatedEvent.key]: [UserCreatedEvent, [subscriber]],
+            };
+            matador = new Matador({ transport, topology, schema });
+            expect(matador).toBeInstanceOf(Matador);
+            expect(matador.isConnected()).toBe(false);
+        });
+        it('should support hooks as second argument for dependency injection', () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .build();
+            const subscriber = createSubscriber({
+                name: 'handle-user',
+                description: 'Handles user events',
+                callback: async () => { },
+            });
+            const schema = {
+                [UserCreatedEvent.key]: [UserCreatedEvent, [subscriber]],
+            };
+            const logs = [];
+            const mockLogger = {
+                debug: (msg) => logs.push(`debug: ${msg}`),
+                info: (msg) => logs.push(`info: ${msg}`),
+                warn: (msg) => logs.push(`warn: ${msg}`),
+                error: (msg) => logs.push(`error: ${msg}`),
+            };
+            matador = new Matador({ transport, topology, schema }, { logger: mockLogger });
+            expect(matador).toBeInstanceOf(Matador);
+        });
+    });
+    describe('registration', () => {
+        it('should register events via schema in constructor', () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .build();
+            const subscriber = createSubscriber({
+                name: 'send-welcome-email',
+                description: 'Sends welcome email',
+                callback: async () => { },
+            });
+            const schema = {
+                [UserCreatedEvent.key]: [UserCreatedEvent, [subscriber]],
+            };
+            matador = new Matador({ transport, topology, schema });
+            expect(matador).toBeInstanceOf(Matador);
+        });
+        it('should support multiple events in schema', () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .build();
+            const userSub = createSubscriber({
+                name: 'handle-user',
+                description: 'Handles user events',
+                callback: async () => { },
+            });
+            const orderSub = createSubscriber({
+                name: 'handle-order',
+                description: 'Handles order events',
+                callback: async () => { },
+            });
+            const schema = {
+                [UserCreatedEvent.key]: [UserCreatedEvent, [userSub]],
+                [OrderPlacedEvent.key]: [OrderPlacedEvent, [orderSub]],
+            };
+            matador = new Matador({ transport, topology, schema });
+            expect(matador).toBeInstanceOf(Matador);
+        });
+    });
+    describe('start', () => {
+        it('should connect transport and be ready', async () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .build();
+            const subscriber = createSubscriber({
+                name: 'handle-user',
+                description: 'Handles user events',
+                callback: async () => { },
+            });
+            const schema = {
+                [UserCreatedEvent.key]: [UserCreatedEvent, [subscriber]],
+            };
+            matador = new Matador({ transport, topology, schema });
+            await matador.start();
+            expect(matador.isConnected()).toBe(true);
+        });
+        it('should throw if started twice', async () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .build();
+            const subscriber = createSubscriber({
+                name: 'handle-user',
+                description: 'Handles user events',
+                callback: async () => { },
+            });
+            const schema = {
+                [UserCreatedEvent.key]: [UserCreatedEvent, [subscriber]],
+            };
+            matador = new Matador({ transport, topology, schema });
+            await matador.start();
+            // start() is idempotent - calling it again should not throw
+            await expect(matador.start()).resolves.toBeUndefined();
+        });
+        it('should throw on invalid schema', async () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .build();
+            // Register duplicate subscriber names
+            const sub1 = createSubscriber({
+                name: 'same-name',
+                description: 'Test subscriber',
+                callback: async () => { },
+            });
+            const sub2 = createSubscriber({
+                name: 'same-name',
+                description: 'Test subscriber',
+                callback: async () => { },
+            });
+            const schema = {
+                [UserCreatedEvent.key]: [UserCreatedEvent, [sub1, sub2]],
+            };
+            matador = new Matador({ transport, topology, schema });
+            expect(matador.start()).rejects.toThrow('Schema validation failed');
+        });
+    });
+    describe('send', () => {
+        it('should throw if not started', async () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .build();
+            const subscriber = createSubscriber({
+                name: 'handle-user',
+                description: 'Handles user events',
+                callback: async () => { },
+            });
+            const schema = {
+                [UserCreatedEvent.key]: [UserCreatedEvent, [subscriber]],
+            };
+            matador = new Matador({ transport, topology, schema });
+            const event = new UserCreatedEvent({
+                userId: '123',
+                email: 'test@example.com',
+            });
+            await expect(matador.send(event)).rejects.toThrow('Matador has not been started');
+        });
+        it('should send events to transport', async () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .build();
+            const subscriber = createSubscriber({
+                name: 'handle-user',
+                description: 'Handles user events',
+                callback: async () => { },
+            });
+            const schema = {
+                [UserCreatedEvent.key]: [UserCreatedEvent, [subscriber]],
+            };
+            matador = new Matador({ transport, topology, schema });
+            await matador.start();
+            const event = new UserCreatedEvent({
+                userId: '123',
+                email: 'test@example.com',
+            });
+            const result = await matador.send(event);
+            expect(result.subscribersSent).toBe(1);
+            expect(result.errors).toHaveLength(0);
+        });
+        it('should send events using class + data shorthand', async () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .build();
+            const subscriber = createSubscriber({
+                name: 'handle-user',
+                description: 'Handles user events',
+                callback: async () => { },
+            });
+            const schema = {
+                [UserCreatedEvent.key]: [UserCreatedEvent, [subscriber]],
+            };
+            matador = new Matador({ transport, topology, schema });
+            await matador.start();
+            // Use the shorthand: send(EventClass, data)
+            const result = await matador.send(UserCreatedEvent, {
+                userId: '123',
+                email: 'test@example.com',
+            });
+            expect(result.subscribersSent).toBe(1);
+            expect(result.errors).toHaveLength(0);
+        });
+        it('should create one envelope per subscriber', async () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .build();
+            const sub1 = createSubscriber({
+                name: 'sub-1',
+                description: 'Subscriber 1',
+                callback: async () => { },
+            });
+            const sub2 = createSubscriber({
+                name: 'sub-2',
+                description: 'Subscriber 2',
+                callback: async () => { },
+            });
+            const sub3 = createSubscriber({
+                name: 'sub-3',
+                description: 'Subscriber 3',
+                callback: async () => { },
+            });
+            const schema = {
+                [UserCreatedEvent.key]: [UserCreatedEvent, [sub1, sub2, sub3]],
+            };
+            matador = new Matador({ transport, topology, schema });
+            await matador.start();
+            const event = new UserCreatedEvent({
+                userId: '123',
+                email: 'test@example.com',
+            });
+            const result = await matador.send(event);
+            expect(result.subscribersSent).toBe(3);
+        });
+        it('should include correlation ID in send', async () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .build();
+            const subscriber = createSubscriber({
+                name: 'handle-user',
+                description: 'Handles user events',
+                callback: async () => { },
+            });
+            const schema = {
+                [UserCreatedEvent.key]: [UserCreatedEvent, [subscriber]],
+            };
+            matador = new Matador({ transport, topology, schema });
+            await matador.start();
+            const event = new UserCreatedEvent({
+                userId: '123',
+                email: 'test@example.com',
+            });
+            const result = await matador.send(event, {
+                correlationId: 'request-456',
+            });
+            expect(result.subscribersSent).toBe(1);
+        });
+    });
+    describe('shutdown', () => {
+        it('should gracefully shutdown', async () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .build();
+            const subscriber = createSubscriber({
+                name: 'handle-user',
+                description: 'Handles user events',
+                callback: async () => { },
+            });
+            const schema = {
+                [UserCreatedEvent.key]: [UserCreatedEvent, [subscriber]],
+            };
+            matador = new Matador({ transport, topology, schema });
+            await matador.start();
+            await matador.shutdown();
+            expect(matador.isConnected()).toBe(false);
+        });
+        it('should be idempotent', async () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .build();
+            const subscriber = createSubscriber({
+                name: 'handle-user',
+                description: 'Handles user events',
+                callback: async () => { },
+            });
+            const schema = {
+                [UserCreatedEvent.key]: [UserCreatedEvent, [subscriber]],
+            };
+            matador = new Matador({ transport, topology, schema });
+            await matador.start();
+            await matador.shutdown();
+            await matador.shutdown(); // Should not throw
+            expect(matador.isConnected()).toBe(false);
+        });
+        it('should reject send after shutdown initiated', async () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .build();
+            const subscriber = createSubscriber({
+                name: 'handle-user',
+                description: 'Handles user events',
+                callback: async () => { },
+            });
+            const schema = {
+                [UserCreatedEvent.key]: [UserCreatedEvent, [subscriber]],
+            };
+            matador = new Matador({ transport, topology, schema });
+            await matador.start();
+            // Initiate shutdown but don't await
+            const shutdownPromise = matador.shutdown();
+            const event = new UserCreatedEvent({
+                userId: '123',
+                email: 'test@example.com',
+            });
+            // Send should fail during/after shutdown
+            await shutdownPromise;
+            expect(matador.send(event)).rejects.toThrow();
+        });
+    });
+    describe('idle state', () => {
+        it('should report idle when no processing', async () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .build();
+            const subscriber = createSubscriber({
+                name: 'handle-user',
+                description: 'Handles user events',
+                callback: async () => { },
+            });
+            const schema = {
+                [UserCreatedEvent.key]: [UserCreatedEvent, [subscriber]],
+            };
+            matador = new Matador({ transport, topology, schema });
+            await matador.start();
+            expect(matador.isIdle()).toBe(true);
+        });
+        it('should return handlers state', async () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .build();
+            const subscriber = createSubscriber({
+                name: 'handle-user',
+                description: 'Handles user events',
+                callback: async () => { },
+            });
+            const schema = {
+                [UserCreatedEvent.key]: [UserCreatedEvent, [subscriber]],
+            };
+            matador = new Matador({ transport, topology, schema });
+            await matador.start();
+            const state = matador.getHandlersState();
+            expect(state.isIdle).toBe(true);
+            expect(state.eventsBeingProcessed).toBe(0);
+            expect(state.eventsBeingEnqueued).toBe(0);
+        });
+        it('should wait for idle', async () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .build();
+            const subscriber = createSubscriber({
+                name: 'handle-user',
+                description: 'Handles user events',
+                callback: async () => { },
+            });
+            const schema = {
+                [UserCreatedEvent.key]: [UserCreatedEvent, [subscriber]],
+            };
+            matador = new Matador({ transport, topology, schema });
+            await matador.start();
+            const isIdle = await matador.waitForIdle(1000);
+            expect(isIdle).toBe(true);
+        });
+    });
+    describe('consuming from queues', () => {
+        it('should subscribe to specified queues', async () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('test')
+                .addQueue('events')
+                .addQueue('notifications')
+                .build();
+            const subscriber = createSubscriber({
+                name: 'handle-user',
+                description: 'Handles user events',
+                callback: async () => { },
+            });
+            const schema = {
+                [UserCreatedEvent.key]: [UserCreatedEvent, [subscriber]],
+            };
+            matador = new Matador({
+                transport,
+                topology,
+                schema,
+                consumeFrom: ['events'],
+            });
+            await matador.start();
+            expect(matador.isConnected()).toBe(true);
+        });
+    });
+});

package/dist/core/shutdown.d.ts

@@ -0,0 +1,78 @@
+import { type Logger } from '../hooks/index.js';
+/**
+ * Shutdown state.
+ */
+export type ShutdownState = 'running' | 'stopping-receive' | 'waiting-handlers' | 'stopping-enqueue' | 'disconnecting' | 'stopped';
+/**
+ * Configuration for shutdown manager.
+ */
+export interface ShutdownConfig {
+    /** Timeout for graceful shutdown in milliseconds */
+    readonly gracefulShutdownTimeout: number;
+    /** Polling interval when waiting for handlers to idle */
+    readonly idlePollingInterval: number;
+    /** Logger for shutdown events (defaults to console) */
+    readonly logger: Logger;
+}
+/**
+ * Default shutdown configuration.
+ */
+export declare const defaultShutdownConfig: ShutdownConfig;
+/**
+ * Handler state tracking.
+ */
+export interface HandlersState {
+    readonly eventsBeingProcessed: number;
+    readonly eventsBeingEnqueued: number;
+    readonly isIdle: boolean;
+}
+/**
+ * Manages graceful shutdown of Matador.
+ *
+ * Shutdown sequence:
+ * 1. Stop receiving new messages
+ * 2. Wait for in-flight processing to complete
+ * 3. Stop accepting new enqueue requests
+ * 4. Disconnect transport
+ */
+export declare class ShutdownManager {
+    private readonly getEnqueueCount;
+    private readonly stopReceiving;
+    private readonly disconnectTransport;
+    private _state;
+    private readonly config;
+    private eventsBeingProcessed;
+    private acceptingEnqueue;
+    constructor(getEnqueueCount: () => number, stopReceiving: () => Promise<void>, disconnectTransport: () => Promise<void>, config?: Partial<ShutdownConfig>);
+    /**
+     * Current shutdown state.
+     */
+    get state(): ShutdownState;
+    /**
+     * Whether enqueue is currently allowed.
+     */
+    get isEnqueueAllowed(): boolean;
+    /**
+     * Gets current handler state.
+     */
+    getHandlersState(): HandlersState;
+    /**
+     * Increment processing counter.
+     */
+    incrementProcessing(): void;
+    /**
+     * Decrement processing counter.
+     */
+    decrementProcessing(): void;
+    /**
+     * Performs graceful shutdown.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Forcefully stops without waiting.
+     */
+    forceStop(): Promise<void>;
+    private waitForIdle;
+    private sleep;
+}
+//# sourceMappingURL=shutdown.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../../src/core/shutdown.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAiB,MAAM,mBAAmB,CAAC;AAE/D;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB,SAAS,GACT,kBAAkB,GAClB,kBAAkB,GAClB,kBAAkB,GAClB,eAAe,GACf,SAAS,CAAC;AAEd;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;IAEzC,yDAAyD;IACzD,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IAErC,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,eAAO,MAAM,qBAAqB,EAAE,cAInC,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAe;IAOxB,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IARtC,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,oBAAoB,CAAK;IACjC,OAAO,CAAC,gBAAgB,CAAQ;gBAGb,eAAe,EAAE,MAAM,MAAM,EAC7B,aAAa,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EAClC,mBAAmB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EACzD,MAAM,GAAE,OAAO,CAAC,cAAc,CAAM;IAKtC;;OAEG;IACH,IAAI,KAAK,IAAI,aAAa,CAEzB;IAED;;OAEG;IACH,IAAI,gBAAgB,IAAI,OAAO,CAE9B;IAED;;OAEG;IACH,gBAAgB,IAAI,aAAa;IASjC;;OAEG;IACH,mBAAmB,IAAI,IAAI;IAI3B;;OAEG;IACH,mBAAmB,IAAI,IAAI;IAI3B;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAwB/B;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;YAOlB,WAAW;IAezB,OAAO,CAAC,KAAK;CAGd"}

package/dist/core/shutdown.js

@@ -0,0 +1,111 @@
+import { consoleLogger } from '../hooks/index.js';
+/**
+ * Default shutdown configuration.
+ */
+export const defaultShutdownConfig = {
+    gracefulShutdownTimeout: 30000,
+    idlePollingInterval: 1000,
+    logger: consoleLogger,
+};
+/**
+ * Manages graceful shutdown of Matador.
+ *
+ * Shutdown sequence:
+ * 1. Stop receiving new messages
+ * 2. Wait for in-flight processing to complete
+ * 3. Stop accepting new enqueue requests
+ * 4. Disconnect transport
+ */
+export class ShutdownManager {
+    getEnqueueCount;
+    stopReceiving;
+    disconnectTransport;
+    _state = 'running';
+    config;
+    eventsBeingProcessed = 0;
+    acceptingEnqueue = true;
+    constructor(getEnqueueCount, stopReceiving, disconnectTransport, config = {}) {
+        this.getEnqueueCount = getEnqueueCount;
+        this.stopReceiving = stopReceiving;
+        this.disconnectTransport = disconnectTransport;
+        this.config = { ...defaultShutdownConfig, ...config };
+    }
+    /**
+     * Current shutdown state.
+     */
+    get state() {
+        return this._state;
+    }
+    /**
+     * Whether enqueue is currently allowed.
+     */
+    get isEnqueueAllowed() {
+        return this.acceptingEnqueue;
+    }
+    /**
+     * Gets current handler state.
+     */
+    getHandlersState() {
+        const eventsBeingEnqueued = this.getEnqueueCount();
+        return {
+            eventsBeingProcessed: this.eventsBeingProcessed,
+            eventsBeingEnqueued,
+            isIdle: this.eventsBeingProcessed === 0 && eventsBeingEnqueued === 0,
+        };
+    }
+    /**
+     * Increment processing counter.
+     */
+    incrementProcessing() {
+        this.eventsBeingProcessed++;
+    }
+    /**
+     * Decrement processing counter.
+     */
+    decrementProcessing() {
+        this.eventsBeingProcessed--;
+    }
+    /**
+     * Performs graceful shutdown.
+     */
+    async shutdown() {
+        if (this._state !== 'running') {
+            return;
+        }
+        // 1. Stop receiving new messages
+        this._state = 'stopping-receive';
+        await this.stopReceiving();
+        // 2. Wait for handlers to idle
+        this._state = 'waiting-handlers';
+        await this.waitForIdle();
+        // 3. Stop accepting new enqueue requests
+        this._state = 'stopping-enqueue';
+        this.acceptingEnqueue = false;
+        // 4. Disconnect transport
+        this._state = 'disconnecting';
+        await this.disconnectTransport();
+        this._state = 'stopped';
+    }
+    /**
+     * Forcefully stops without waiting.
+     */
+    async forceStop() {
+        this.acceptingEnqueue = false;
+        await this.stopReceiving();
+        await this.disconnectTransport();
+        this._state = 'stopped';
+    }
+    async waitForIdle() {
+        const deadline = Date.now() + this.config.gracefulShutdownTimeout;
+        while (!this.getHandlersState().isIdle) {
+            if (Date.now() > deadline) {
+                this.config.logger.warn(`[Matador] ⚠️ Shutdown timeout reached with ${this.eventsBeingProcessed} events still processing`);
+                break;
+            }
+            await this.sleep(this.config.idlePollingInterval);
+        }
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}

package/dist/core/shutdown.test.d.ts

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

package/dist/core/shutdown.test.d.ts.map

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