@zdavison/matador 2.0.8 → 2.0.10

package/src/topology/builder.test.ts

@@ -1,451 +0,0 @@
-import { describe, expect, it } from 'bun:test';
-import { TopologyBuilder, TopologyValidationError } from './builder.js';
-import { resolveQueueName } from './types.js';
-
-describe('TopologyBuilder', () => {
-  describe('withNamespace', () => {
-    it('should set the namespace', () => {
-      const topology = TopologyBuilder.create()
-        .withNamespace('myapp')
-        .addQueue('events')
-        .build();
-
-      expect(topology.namespace).toBe('myapp');
-    });
-
-    it('should reject empty namespace', () => {
-      const builder = TopologyBuilder.create()
-        .withNamespace('')
-        .addQueue('events');
-
-      expect(() => builder.build()).toThrow(TopologyValidationError);
-    });
-
-    it('should reject namespace starting with number', () => {
-      const builder = TopologyBuilder.create()
-        .withNamespace('123app')
-        .addQueue('events');
-
-      expect(() => builder.build()).toThrow(TopologyValidationError);
-    });
-
-    it('should allow hyphens and underscores in namespace', () => {
-      const topology = TopologyBuilder.create()
-        .withNamespace('my-app_v2')
-        .addQueue('events')
-        .build();
-
-      expect(topology.namespace).toBe('my-app_v2');
-    });
-  });
-
-  describe('addQueue', () => {
-    it('should add a queue with defaults', () => {
-      const topology = TopologyBuilder.create()
-        .withNamespace('test')
-        .addQueue('events')
-        .build();
-
-      expect(topology.queues).toHaveLength(1);
-      expect(topology.queues[0]?.name).toBe('events');
-    });
-
-    it('should add queue with options', () => {
-      const topology = TopologyBuilder.create()
-        .withNamespace('test')
-        .addQueue('events', {
-          concurrency: 5,
-          consumerTimeout: 30000,
-          priorities: true,
-        })
-        .build();
-
-      expect(topology.queues[0]?.concurrency).toBe(5);
-      expect(topology.queues[0]?.consumerTimeout).toBe(30000);
-      expect(topology.queues[0]?.priorities).toBe(true);
-    });
-
-    it('should add multiple queues', () => {
-      const topology = TopologyBuilder.create()
-        .withNamespace('test')
-        .addQueue('events')
-        .addQueue('notifications')
-        .addQueue('analytics')
-        .build();
-
-      expect(topology.queues).toHaveLength(3);
-    });
-
-    it('should reject duplicate queue names', () => {
-      const builder = TopologyBuilder.create()
-        .withNamespace('test')
-        .addQueue('events')
-        .addQueue('events');
-
-      expect(() => builder.build()).toThrow('Duplicate queue name');
-    });
-
-    it('should reject empty queue name', () => {
-      const builder = TopologyBuilder.create()
-        .withNamespace('test')
-        .addQueue('');
-
-      expect(() => builder.build()).toThrow('Queue name cannot be empty');
-    });
-
-    it('should reject queue names starting with number', () => {
-      const builder = TopologyBuilder.create()
-        .withNamespace('test')
-        .addQueue('123queue');
-
-      expect(() => builder.build()).toThrow('must start with a letter');
-    });
-
-    it('should reject invalid concurrency', () => {
-      const builder = TopologyBuilder.create()
-        .withNamespace('test')
-        .addQueue('events', { concurrency: 0 });
-
-      expect(() => builder.build()).toThrow('concurrency must be at least 1');
-    });
-
-    it('should reject negative consumer timeout', () => {
-      const builder = TopologyBuilder.create()
-        .withNamespace('test')
-        .addQueue('events', { consumerTimeout: -1 });
-
-      expect(() => builder.build()).toThrow(
-        'consumer timeout must be non-negative',
-      );
-    });
-  });
-
-  describe('withDeadLetter', () => {
-    it('should configure dead letter settings', () => {
-      const topology = TopologyBuilder.create()
-        .withNamespace('test')
-        .addQueue('events')
-        .withDeadLetter({
-          unhandled: { enabled: false },
-          undeliverable: { enabled: true },
-        })
-        .build();
-
-      expect(topology.deadLetter.unhandled.enabled).toBe(false);
-      expect(topology.deadLetter.undeliverable.enabled).toBe(true);
-    });
-
-    it('should merge with defaults', () => {
-      const topology = TopologyBuilder.create()
-        .withNamespace('test')
-        .addQueue('events')
-        .withDeadLetter({ unhandled: { enabled: false } })
-        .build();
-
-      // undeliverable should keep default
-      expect(topology.deadLetter.unhandled.enabled).toBe(false);
-      expect(topology.deadLetter.undeliverable.enabled).toBe(true);
-    });
-  });
-
-  describe('withRetry', () => {
-    it('should configure retry settings', () => {
-      const topology = TopologyBuilder.create()
-        .withNamespace('test')
-        .addQueue('events')
-        .withRetry({
-          enabled: true,
-          defaultDelayMs: 5000,
-          maxDelayMs: 600000,
-        })
-        .build();
-
-      expect(topology.retry.enabled).toBe(true);
-      expect(topology.retry.defaultDelayMs).toBe(5000);
-      expect(topology.retry.maxDelayMs).toBe(600000);
-    });
-
-    it('should reject negative default delay', () => {
-      const builder = TopologyBuilder.create()
-        .withNamespace('test')
-        .addQueue('events')
-        .withRetry({ defaultDelayMs: -1 });
-
-      expect(() => builder.build()).toThrow('delay must be non-negative');
-    });
-
-    it('should reject max delay less than default', () => {
-      const builder = TopologyBuilder.create()
-        .withNamespace('test')
-        .addQueue('events')
-        .withRetry({
-          defaultDelayMs: 10000,
-          maxDelayMs: 5000,
-        });
-
-      expect(() => builder.build()).toThrow(
-        'Max retry delay must be greater than or equal to default',
-      );
-    });
-  });
-
-  describe('withoutRetry', () => {
-    it('should disable retry', () => {
-      const topology = TopologyBuilder.create()
-        .withNamespace('test')
-        .addQueue('events')
-        .withoutRetry()
-        .build();
-
-      expect(topology.retry.enabled).toBe(false);
-    });
-  });
-
-  describe('withoutDeadLetter', () => {
-    it('should disable dead letter queues', () => {
-      const topology = TopologyBuilder.create()
-        .withNamespace('test')
-        .addQueue('events')
-        .withoutDeadLetter()
-        .build();
-
-      expect(topology.deadLetter.unhandled.enabled).toBe(false);
-      expect(topology.deadLetter.undeliverable.enabled).toBe(false);
-    });
-  });
-
-  describe('validate', () => {
-    it('should return issues without throwing', () => {
-      const builder = TopologyBuilder.create();
-      const issues = builder.validate();
-
-      expect(issues.length).toBeGreaterThan(0);
-      expect(issues).toContain('Namespace is required');
-      expect(issues).toContain('At least one queue is required');
-    });
-
-    it('should return empty array for valid topology', () => {
-      const builder = TopologyBuilder.create()
-        .withNamespace('test')
-        .addQueue('events');
-
-      const issues = builder.validate();
-      expect(issues).toHaveLength(0);
-    });
-  });
-
-  describe('build', () => {
-    it('should throw TopologyValidationError with issues', () => {
-      const builder = TopologyBuilder.create();
-
-      try {
-        builder.build();
-        expect(true).toBe(false); // Should not reach here
-      } catch (error) {
-        expect(error).toBeInstanceOf(TopologyValidationError);
-        expect((error as TopologyValidationError).issues).toContain(
-          'Namespace is required',
-        );
-      }
-    });
-
-    it('should return immutable topology', () => {
-      const topology = TopologyBuilder.create()
-        .withNamespace('test')
-        .addQueue('events')
-        .build();
-
-      // Verify structure
-      expect(topology.namespace).toBe('test');
-      expect(topology.queues).toHaveLength(1);
-      expect(topology.deadLetter.unhandled.enabled).toBe(true);
-      expect(topology.retry.enabled).toBe(true);
-    });
-  });
-
-  describe('exact queue option', () => {
-    it('should mark queue as exact (external)', () => {
-      const topology = TopologyBuilder.create()
-        .withNamespace('test')
-        .addQueue('external-queue', { exact: true })
-        .build();
-
-      expect(topology.queues[0]?.exact).toBe(true);
-    });
-
-    it('should allow dots in queue name when exact: true', () => {
-      const topology = TopologyBuilder.create()
-        .withNamespace('test')
-        .addQueue('matador.shared.id-platform', { exact: true })
-        .build();
-
-      expect(topology.queues[0]?.name).toBe('matador.shared.id-platform');
-      expect(topology.queues[0]?.exact).toBe(true);
-    });
-
-    it('should reject dots in queue name when exact: false', () => {
-      const builder = TopologyBuilder.create()
-        .withNamespace('test')
-        .addQueue('invalid.queue.name');
-
-      expect(() => builder.build()).toThrow('must start with a letter');
-    });
-
-    it('should allow transport-specific RabbitMQ options with exact queue', () => {
-      const topology = TopologyBuilder.create()
-        .withNamespace('test')
-        .addQueue('matador.shared.id-platform', {
-          exact: true,
-          transport: {
-            rabbitmq: {
-              options: {
-                durable: true,
-                deadLetterExchange: 'matador.shared.dlx-undeliverable',
-                arguments: {
-                  'x-queue-type': 'quorum',
-                },
-              },
-            },
-          },
-        })
-        .build();
-
-      expect(topology.queues[0]?.name).toBe('matador.shared.id-platform');
-      expect(topology.queues[0]?.exact).toBe(true);
-      expect(topology.queues[0]?.transport?.rabbitmq?.options?.durable).toBe(
-        true,
-      );
-      expect(
-        topology.queues[0]?.transport?.rabbitmq?.options?.deadLetterExchange,
-      ).toBe('matador.shared.dlx-undeliverable');
-      expect(
-        topology.queues[0]?.transport?.rabbitmq?.options?.arguments?.[
-          'x-queue-type'
-        ],
-      ).toBe('quorum');
-    });
-  });
-
-  describe('addQueue with QueueDefinition object', () => {
-    it('should accept a QueueDefinition object', () => {
-      const queueDef = {
-        name: 'events',
-        concurrency: 5,
-        consumerTimeout: 30000,
-      };
-
-      const topology = TopologyBuilder.create()
-        .withNamespace('test')
-        .addQueue(queueDef)
-        .build();
-
-      expect(topology.queues).toHaveLength(1);
-      expect(topology.queues[0]?.name).toBe('events');
-      expect(topology.queues[0]?.concurrency).toBe(5);
-      expect(topology.queues[0]?.consumerTimeout).toBe(30000);
-    });
-
-    it('should allow reusing queue definitions across builders', () => {
-      const sharedQueue = {
-        name: 'shared-queue',
-        concurrency: 10,
-        exact: true,
-      };
-
-      const topology1 = TopologyBuilder.create()
-        .withNamespace('app1')
-        .addQueue(sharedQueue)
-        .build();
-
-      const topology2 = TopologyBuilder.create()
-        .withNamespace('app2')
-        .addQueue(sharedQueue)
-        .build();
-
-      expect(topology1.queues[0]).toEqual(sharedQueue);
-      expect(topology2.queues[0]).toEqual(sharedQueue);
-    });
-
-    it('should work with queue() alias', () => {
-      const queueDef = {
-        name: 'analytics',
-        priorities: true,
-      };
-
-      const topology = TopologyBuilder.create()
-        .withNamespace('test')
-        .queue(queueDef)
-        .build();
-
-      expect(topology.queues[0]?.name).toBe('analytics');
-      expect(topology.queues[0]?.priorities).toBe(true);
-    });
-
-    it('should mix QueueDefinition objects with name+options style', () => {
-      const reusableQueue = {
-        name: 'shared',
-        concurrency: 3,
-      };
-
-      const topology = TopologyBuilder.create()
-        .withNamespace('test')
-        .addQueue(reusableQueue)
-        .addQueue('local', { concurrency: 1 })
-        .build();
-
-      expect(topology.queues).toHaveLength(2);
-      expect(topology.queues[0]?.name).toBe('shared');
-      expect(topology.queues[1]?.name).toBe('local');
-    });
-
-    it('should validate QueueDefinition objects the same way', () => {
-      const invalidQueue = {
-        name: '123invalid',
-        concurrency: 5,
-      };
-
-      const builder = TopologyBuilder.create()
-        .withNamespace('test')
-        .addQueue(invalidQueue);
-
-      expect(() => builder.build()).toThrow('must start with a letter');
-    });
-  });
-});
-
-describe('resolveQueueName', () => {
-  it('should return namespace.name for regular queues', () => {
-    const queueDef = { name: 'events' };
-    expect(resolveQueueName('myapp', queueDef)).toBe('myapp.events');
-  });
-
-  it('should return name as-is when exact: true', () => {
-    const queueDef = { name: 'matador.shared.id-platform', exact: true };
-    expect(resolveQueueName('myapp', queueDef)).toBe(
-      'matador.shared.id-platform',
-    );
-  });
-
-  it('should return namespace.name when exact: false', () => {
-    const queueDef = { name: 'events', exact: false };
-    expect(resolveQueueName('myapp', queueDef)).toBe('myapp.events');
-  });
-
-  it('should work with full QueueDefinition including transport options', () => {
-    const queueDef = {
-      name: 'matador.shared.id-platform',
-      exact: true,
-      transport: {
-        rabbitmq: {
-          options: {
-            durable: true,
-            deadLetterExchange: 'matador.shared.dlx-undeliverable',
-          },
-        },
-      },
-    };
-    expect(resolveQueueName('myapp', queueDef)).toBe(
-      'matador.shared.id-platform',
-    );
-  });
-});

package/src/topology/builder.ts

@@ -1,238 +0,0 @@
-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'>;
-
-/**
- * Type guard to check if the argument is a QueueDefinition object.
- */
-function isQueueDefinition(
-  arg: string | QueueDefinition,
-): arg is QueueDefinition {
-  return typeof arg === 'object' && arg !== null && 'name' in arg;
-}
-
-/**
- * Error thrown when topology validation fails.
- */
-export class TopologyValidationError extends Error implements HasDescription {
-  readonly 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: string,
-    public readonly issues: readonly string[],
-  ) {
-    super(message);
-    this.name = 'TopologyValidationError';
-  }
-}
-
-/**
- * Fluent builder for creating Topology configurations.
- */
-export class TopologyBuilder {
-  /**
-   * Creates a new TopologyBuilder instance.
-   */
-  static create(): TopologyBuilder {
-    return new TopologyBuilder();
-  }
-
-  private namespace = '';
-  private queues: QueueDefinition[] = [];
-  private deadLetter: DeadLetterConfig = {
-    unhandled: { enabled: true },
-    undeliverable: { enabled: true },
-  };
-  private retry: RetryConfig = {
-    enabled: true,
-    defaultDelayMs: 1000,
-    maxDelayMs: 300000, // 5 minutes
-  };
-
-  /**
-   * Sets the namespace prefix for all queues.
-   */
-  withNamespace(namespace: string): this {
-    this.namespace = namespace;
-    return 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;
-  addQueue(
-    nameOrDefinition: string | QueueDefinition,
-    options: QueueOptions = {},
-  ): this {
-    if (isQueueDefinition(nameOrDefinition)) {
-      this.queues.push(nameOrDefinition);
-    } else {
-      this.queues.push({ name: nameOrDefinition, ...options });
-    }
-    return 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;
-  queue(
-    nameOrDefinition: string | QueueDefinition,
-    options: QueueOptions = {},
-  ): this {
-    if (isQueueDefinition(nameOrDefinition)) {
-      return this.addQueue(nameOrDefinition);
-    }
-    return this.addQueue(nameOrDefinition, options);
-  }
-
-  /**
-   * Configures dead-letter queue settings.
-   */
-  withDeadLetter(config: Partial<DeadLetterConfig>): this {
-    this.deadLetter = {
-      unhandled: config.unhandled ?? this.deadLetter.unhandled,
-      undeliverable: config.undeliverable ?? this.deadLetter.undeliverable,
-    };
-    return this;
-  }
-
-  /**
-   * Configures retry settings.
-   */
-  withRetry(config: Partial<RetryConfig>): this {
-    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 {
-    this.retry = { ...this.retry, enabled: false };
-    return this;
-  }
-
-  /**
-   * Disables dead-letter queues.
-   */
-  withoutDeadLetter(): this {
-    this.deadLetter = {
-      unhandled: { enabled: false },
-      undeliverable: { enabled: false },
-    };
-    return this;
-  }
-
-  /**
-   * Validates the topology configuration.
-   */
-  validate(): readonly string[] {
-    const issues: string[] = [];
-
-    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<string>();
-    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(): Topology {
-    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/src/topology/index.ts

@@ -1,19 +0,0 @@
-export type {
-  DeadLetterConfig,
-  DeadLetterQueueConfig,
-  QueueDefinition,
-  RabbitMQQueueDefinition,
-  RabbitMQQueueOptions,
-  RetryConfig,
-  Topology,
-  TransportQueueOptions,
-} from './types.js';
-export {
-  getDeadLetterQueueName,
-  getQualifiedQueueName,
-  getRetryQueueName,
-  resolveQueueName,
-} from './types.js';
-
-export type { QueueOptions } from './builder.js';
-export { TopologyBuilder, TopologyValidationError } from './builder.js';