@zdavison/matador 2.0.9 → 2.0.11

package/dist/schema/types.test.js

@@ -0,0 +1,242 @@
+import { describe, expect, it } from 'bun:test';
+import { MatadorEvent, createSubscriber, createSubscriberStub, } from '../types/index.js';
+import { bind, installPlugins, isSchemaEntryTuple } from './types.js';
+class UserCreatedEvent extends MatadorEvent {
+    data;
+    static key = 'user.created';
+    static description = 'User created event';
+    constructor(data) {
+        super();
+        this.data = data;
+    }
+}
+class OrderPlacedEvent extends MatadorEvent {
+    data;
+    static key = 'order.placed';
+    static description = 'Order placed event';
+    constructor(data) {
+        super();
+        this.data = data;
+    }
+}
+class ChatMessageSentEvent extends MatadorEvent {
+    data;
+    static key = 'chat.message.sent';
+    static description = 'Chat message sent event';
+    constructor(data) {
+        super();
+        this.data = data;
+    }
+}
+describe('bind', () => {
+    it('should create a schema entry tuple', () => {
+        const subscriber = createSubscriber({
+            name: 'test-sub',
+            description: 'Test subscriber',
+            callback: async () => { },
+        });
+        const entry = bind(UserCreatedEvent, [subscriber]);
+        expect(isSchemaEntryTuple(entry)).toBe(true);
+        expect(entry[0]).toBe(UserCreatedEvent);
+        expect(entry[1]).toHaveLength(1);
+        expect(entry[1][0]).toBe(subscriber);
+    });
+});
+describe('isSchemaEntryTuple', () => {
+    it('should return true for tuple format', () => {
+        const entry = [UserCreatedEvent, []];
+        expect(isSchemaEntryTuple(entry)).toBe(true);
+    });
+    it('should return false for object format', () => {
+        const entry = { eventClass: UserCreatedEvent, subscribers: [] };
+        expect(isSchemaEntryTuple(entry)).toBe(false);
+    });
+});
+describe('installPlugins', () => {
+    it('should add plugin subscriber to all events', () => {
+        const sub1 = createSubscriber({
+            name: 'user-handler',
+            description: 'Handles user events',
+            callback: async () => { },
+        });
+        const sub2 = createSubscriber({
+            name: 'order-handler',
+            description: 'Handles order events',
+            callback: async () => { },
+        });
+        const globalSub = createSubscriber({
+            name: 'analytics',
+            description: 'Analytics subscriber',
+            callback: async () => { },
+        });
+        const baseSchema = {
+            [UserCreatedEvent.key]: [UserCreatedEvent, [sub1]],
+            [OrderPlacedEvent.key]: [OrderPlacedEvent, [sub2]],
+        };
+        const schema = installPlugins(baseSchema, [{ subscriber: globalSub }]);
+        // Check user.created has both subscribers
+        const userEntry = schema[UserCreatedEvent.key];
+        expect(isSchemaEntryTuple(userEntry)).toBe(true);
+        const [, userSubs] = userEntry;
+        expect(userSubs).toHaveLength(2);
+        expect(userSubs[0]).toBe(sub1);
+        expect(userSubs[1]).toBe(globalSub);
+        // Check order.placed has both subscribers
+        const orderEntry = schema[OrderPlacedEvent.key];
+        const [, orderSubs] = orderEntry;
+        expect(orderSubs).toHaveLength(2);
+        expect(orderSubs[0]).toBe(sub2);
+        expect(orderSubs[1]).toBe(globalSub);
+    });
+    it('should respect exclusions', () => {
+        const sub1 = createSubscriber({
+            name: 'user-handler',
+            description: 'Handles user events',
+            callback: async () => { },
+        });
+        const sub2 = createSubscriber({
+            name: 'order-handler',
+            description: 'Handles order events',
+            callback: async () => { },
+        });
+        const sub3 = createSubscriber({
+            name: 'chat-handler',
+            description: 'Handles chat events',
+            callback: async () => { },
+        });
+        const globalSub = createSubscriber({
+            name: 'analytics',
+            description: 'Analytics subscriber',
+            callback: async () => { },
+        });
+        const baseSchema = {
+            [UserCreatedEvent.key]: [UserCreatedEvent, [sub1]],
+            [OrderPlacedEvent.key]: [OrderPlacedEvent, [sub2]],
+            [ChatMessageSentEvent.key]: [ChatMessageSentEvent, [sub3]],
+        };
+        const schema = installPlugins(baseSchema, [
+            {
+                subscriber: globalSub,
+                exclusions: [ChatMessageSentEvent.key],
+            },
+        ]);
+        // user.created should have analytics
+        const userEntry = schema[UserCreatedEvent.key];
+        const [, userSubs] = userEntry;
+        expect(userSubs).toHaveLength(2);
+        // order.placed should have analytics
+        const orderEntry = schema[OrderPlacedEvent.key];
+        const [, orderSubs] = orderEntry;
+        expect(orderSubs).toHaveLength(2);
+        // chat.message.sent should NOT have analytics (excluded)
+        const chatEntry = schema[ChatMessageSentEvent.key];
+        const [, chatSubs] = chatEntry;
+        expect(chatSubs).toHaveLength(1);
+        expect(chatSubs[0]).toBe(sub3);
+    });
+    it('should handle multiple plugins', () => {
+        const sub1 = createSubscriber({
+            name: 'user-handler',
+            description: 'Handles user events',
+            callback: async () => { },
+        });
+        const analyticsSub = createSubscriber({
+            name: 'analytics',
+            description: 'Analytics subscriber',
+            callback: async () => { },
+        });
+        const loggingSub = createSubscriber({
+            name: 'logging',
+            description: 'Logging subscriber',
+            callback: async () => { },
+        });
+        const baseSchema = {
+            [UserCreatedEvent.key]: [UserCreatedEvent, [sub1]],
+        };
+        const schema = installPlugins(baseSchema, [
+            { subscriber: analyticsSub },
+            { subscriber: loggingSub },
+        ]);
+        const entry = schema[UserCreatedEvent.key];
+        const [, subs] = entry;
+        expect(subs).toHaveLength(3);
+        expect(subs[0]).toBe(sub1);
+        expect(subs[1]).toBe(analyticsSub);
+        expect(subs[2]).toBe(loggingSub);
+    });
+    it('should handle object format schema entries', () => {
+        const sub1 = createSubscriber({
+            name: 'user-handler',
+            description: 'Handles user events',
+            callback: async () => { },
+        });
+        const globalSub = createSubscriber({
+            name: 'analytics',
+            description: 'Analytics subscriber',
+            callback: async () => { },
+        });
+        const baseSchema = {
+            [UserCreatedEvent.key]: {
+                eventClass: UserCreatedEvent,
+                subscribers: [sub1],
+            },
+        };
+        const schema = installPlugins(baseSchema, [{ subscriber: globalSub }]);
+        const entry = schema[UserCreatedEvent.key];
+        expect(isSchemaEntryTuple(entry)).toBe(true);
+        const [eventClass, subs] = entry;
+        expect(eventClass).toBe(UserCreatedEvent);
+        expect(subs).toHaveLength(2);
+    });
+    it('should work with subscriber stubs', () => {
+        const sub1 = createSubscriber({
+            name: 'user-handler',
+            description: 'Handles user events',
+            callback: async () => { },
+        });
+        const stubSub = createSubscriberStub({
+            name: 'remote-analytics',
+            targetQueue: 'analytics-worker',
+        });
+        const baseSchema = {
+            [UserCreatedEvent.key]: [UserCreatedEvent, [sub1]],
+        };
+        const schema = installPlugins(baseSchema, [{ subscriber: stubSub }]);
+        const entry = schema[UserCreatedEvent.key];
+        const [, subs] = entry;
+        expect(subs).toHaveLength(2);
+        expect(subs[1]).toBe(stubSub);
+    });
+    it('should return empty schema for empty input', () => {
+        const schema = installPlugins({}, [
+            {
+                subscriber: createSubscriber({
+                    name: 'analytics',
+                    description: 'Analytics subscriber',
+                    callback: async () => { },
+                }),
+            },
+        ]);
+        expect(Object.keys(schema)).toHaveLength(0);
+    });
+    it('should not modify original schema', () => {
+        const sub1 = createSubscriber({
+            name: 'user-handler',
+            description: 'Handles user events',
+            callback: async () => { },
+        });
+        const globalSub = createSubscriber({
+            name: 'analytics',
+            description: 'Analytics subscriber',
+            callback: async () => { },
+        });
+        const baseSchema = {
+            [UserCreatedEvent.key]: [UserCreatedEvent, [sub1]],
+        };
+        installPlugins(baseSchema, [{ subscriber: globalSub }]);
+        // Original schema should be unchanged
+        const entry = baseSchema[UserCreatedEvent.key];
+        const [, subs] = entry;
+        expect(subs).toHaveLength(1);
+    });
+});

package/dist/topology/builder.d.ts

@@ -0,0 +1,80 @@
+import type { HasDescription } from '../errors/index.js';
+import type { DeadLetterConfig, QueueDefinition, RetryConfig, Topology } from './types.js';
+/**
+ * Options for adding a queue.
+ * Excludes 'name' as that is provided as the first argument to addQueue.
+ */
+export type QueueOptions = Omit<QueueDefinition, 'name'>;
+/**
+ * Error thrown when topology validation fails.
+ */
+export declare class TopologyValidationError extends Error implements HasDescription {
+    readonly issues: readonly string[];
+    readonly description: string;
+    constructor(message: string, issues: readonly string[]);
+}
+/**
+ * Fluent builder for creating Topology configurations.
+ */
+export declare class TopologyBuilder {
+    /**
+     * Creates a new TopologyBuilder instance.
+     */
+    static create(): TopologyBuilder;
+    private namespace;
+    private queues;
+    private deadLetter;
+    private retry;
+    /**
+     * Sets the namespace prefix for all queues.
+     */
+    withNamespace(namespace: string): this;
+    /**
+     * Adds a queue to the topology.
+     * @param definition - A complete QueueDefinition object
+     */
+    addQueue(definition: QueueDefinition): this;
+    /**
+     * Adds a queue to the topology.
+     * @param name - Queue name
+     * @param options - Queue options
+     */
+    addQueue(name: string, options?: QueueOptions): this;
+    /**
+     * Alias for addQueue().
+     * @param definition - A complete QueueDefinition object
+     */
+    queue(definition: QueueDefinition): this;
+    /**
+     * Alias for addQueue().
+     * @param name - Queue name
+     * @param options - Queue options
+     */
+    queue(name: string, options?: QueueOptions): this;
+    /**
+     * Configures dead-letter queue settings.
+     */
+    withDeadLetter(config: Partial<DeadLetterConfig>): this;
+    /**
+     * Configures retry settings.
+     */
+    withRetry(config: Partial<RetryConfig>): this;
+    /**
+     * Disables retry functionality.
+     */
+    withoutRetry(): this;
+    /**
+     * Disables dead-letter queues.
+     */
+    withoutDeadLetter(): this;
+    /**
+     * Validates the topology configuration.
+     */
+    validate(): readonly string[];
+    /**
+     * Builds the topology configuration.
+     * @throws TopologyValidationError if validation fails
+     */
+    build(): Topology;
+}
+//# sourceMappingURL=builder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/topology/builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,QAAQ,EACT,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;AAWzD;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,KAAM,YAAW,cAAc;aASxD,MAAM,EAAE,SAAS,MAAM,EAAE;IAR3C,QAAQ,CAAC,WAAW,SAIuC;gBAGzD,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,SAAS,MAAM,EAAE;CAK5C;AAED;;GAEG;AACH,qBAAa,eAAe;IAC1B;;OAEG;IACH,MAAM,CAAC,MAAM,IAAI,eAAe;IAIhC,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,UAAU,CAGhB;IACF,OAAO,CAAC,KAAK,CAIX;IAEF;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAKtC;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,eAAe,GAAG,IAAI;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI;IAapD;;;OAGG;IACH,KAAK,CAAC,UAAU,EAAE,eAAe,GAAG,IAAI;IACxC;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI;IAWjD;;OAEG;IACH,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,IAAI;IAQvD;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI;IAS7C;;OAEG;IACH,YAAY,IAAI,IAAI;IAKpB;;OAEG;IACH,iBAAiB,IAAI,IAAI;IAQzB;;OAEG;IACH,QAAQ,IAAI,SAAS,MAAM,EAAE;IAuD7B;;;OAGG;IACH,KAAK,IAAI,QAAQ;CAgBlB"}

package/dist/topology/builder.js

@@ -0,0 +1,165 @@
+/**
+ * Type guard to check if the argument is a QueueDefinition object.
+ */
+function isQueueDefinition(arg) {
+    return typeof arg === 'object' && arg !== null && 'name' in arg;
+}
+/**
+ * Error thrown when topology validation fails.
+ */
+export class TopologyValidationError extends Error {
+    issues;
+    description = 'The topology configuration is invalid. Check the issues array for ' +
+        'specific validation failures such as missing namespace, invalid queue ' +
+        'names, or conflicting settings. This error occurs during Matador ' +
+        'initialization and must be fixed in the configuration.';
+    constructor(message, issues) {
+        super(message);
+        this.issues = issues;
+        this.name = 'TopologyValidationError';
+    }
+}
+/**
+ * Fluent builder for creating Topology configurations.
+ */
+export class TopologyBuilder {
+    /**
+     * Creates a new TopologyBuilder instance.
+     */
+    static create() {
+        return new TopologyBuilder();
+    }
+    namespace = '';
+    queues = [];
+    deadLetter = {
+        unhandled: { enabled: true },
+        undeliverable: { enabled: true },
+    };
+    retry = {
+        enabled: true,
+        defaultDelayMs: 1000,
+        maxDelayMs: 300000, // 5 minutes
+    };
+    /**
+     * Sets the namespace prefix for all queues.
+     */
+    withNamespace(namespace) {
+        this.namespace = namespace;
+        return this;
+    }
+    addQueue(nameOrDefinition, options = {}) {
+        if (isQueueDefinition(nameOrDefinition)) {
+            this.queues.push(nameOrDefinition);
+        }
+        else {
+            this.queues.push({ name: nameOrDefinition, ...options });
+        }
+        return this;
+    }
+    queue(nameOrDefinition, options = {}) {
+        if (isQueueDefinition(nameOrDefinition)) {
+            return this.addQueue(nameOrDefinition);
+        }
+        return this.addQueue(nameOrDefinition, options);
+    }
+    /**
+     * Configures dead-letter queue settings.
+     */
+    withDeadLetter(config) {
+        this.deadLetter = {
+            unhandled: config.unhandled ?? this.deadLetter.unhandled,
+            undeliverable: config.undeliverable ?? this.deadLetter.undeliverable,
+        };
+        return this;
+    }
+    /**
+     * Configures retry settings.
+     */
+    withRetry(config) {
+        this.retry = {
+            enabled: config.enabled ?? this.retry.enabled,
+            defaultDelayMs: config.defaultDelayMs ?? this.retry.defaultDelayMs,
+            maxDelayMs: config.maxDelayMs ?? this.retry.maxDelayMs,
+        };
+        return this;
+    }
+    /**
+     * Disables retry functionality.
+     */
+    withoutRetry() {
+        this.retry = { ...this.retry, enabled: false };
+        return this;
+    }
+    /**
+     * Disables dead-letter queues.
+     */
+    withoutDeadLetter() {
+        this.deadLetter = {
+            unhandled: { enabled: false },
+            undeliverable: { enabled: false },
+        };
+        return this;
+    }
+    /**
+     * Validates the topology configuration.
+     */
+    validate() {
+        const issues = [];
+        if (!this.namespace || this.namespace.trim() === '') {
+            issues.push('Namespace is required');
+        }
+        else if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(this.namespace)) {
+            issues.push('Namespace must start with a letter and contain only alphanumeric characters, underscores, and hyphens');
+        }
+        if (this.queues.length === 0) {
+            issues.push('At least one queue is required');
+        }
+        const queueNames = new Set();
+        for (const queue of this.queues) {
+            if (!queue.name || queue.name.trim() === '') {
+                issues.push('Queue name cannot be empty');
+            }
+            else if (!queue.exact && !/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(queue.name)) {
+                // Skip pattern validation for exact queues (allows names like 'matador.shared.id-platform')
+                issues.push(`Queue name "${queue.name}" must start with a letter and contain only alphanumeric characters, underscores, and hyphens`);
+            }
+            else if (queueNames.has(queue.name)) {
+                issues.push(`Duplicate queue name: "${queue.name}"`);
+            }
+            else {
+                queueNames.add(queue.name);
+            }
+            if (queue.concurrency !== undefined && queue.concurrency < 1) {
+                issues.push(`Queue "${queue.name}" concurrency must be at least 1`);
+            }
+            if (queue.consumerTimeout !== undefined && queue.consumerTimeout < 0) {
+                issues.push(`Queue "${queue.name}" consumer timeout must be non-negative`);
+            }
+        }
+        if (this.retry.enabled) {
+            if (this.retry.defaultDelayMs < 0) {
+                issues.push('Default retry delay must be non-negative');
+            }
+            if (this.retry.maxDelayMs < this.retry.defaultDelayMs) {
+                issues.push('Max retry delay must be greater than or equal to default delay');
+            }
+        }
+        return issues;
+    }
+    /**
+     * Builds the topology configuration.
+     * @throws TopologyValidationError if validation fails
+     */
+    build() {
+        const issues = this.validate();
+        if (issues.length > 0) {
+            throw new TopologyValidationError(`Invalid topology: ${issues.join('; ')}`, issues);
+        }
+        return {
+            namespace: this.namespace,
+            queues: [...this.queues],
+            deadLetter: this.deadLetter,
+            retry: this.retry,
+        };
+    }
+}

package/dist/topology/builder.test.d.ts

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

package/dist/topology/builder.test.d.ts.map

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