@zdavison/matador 2.0.3 → 2.0.4

package/src/pipeline/pipeline.test.ts

@@ -10,7 +10,11 @@ import type { RetryDecision, RetryPolicy } from '../retry/index.js';
 import { StandardRetryPolicy } from '../retry/index.js';
 import type { SchemaRegistry } from '../schema/index.js';
 import type { MessageReceipt, Transport } from '../transport/index.js';
-import type { Envelope, SubscriberDefinition } from '../types/index.js';
+import type {
+  Dispatcher,
+  Envelope,
+  SubscriberDefinition,
+} from '../types/index.js';
 import { createEnvelope } from '../types/index.js';
 import type { PipelineConfig } from './pipeline.js';
 import { ProcessingPipeline } from './pipeline.js';
@@ -324,7 +328,13 @@ describe('ProcessingPipeline', () => {
       const result = await pipeline.process(new Uint8Array(), receipt);
 
       expect(result.success).toBe(true);
-      expect(callbackMock).toHaveBeenCalledWith(envelope);
+      expect(callbackMock).toHaveBeenCalledTimes(1);
+      // Callback receives envelope as first argument and context (with matador) as second
+      const calls = callbackMock.mock.calls as unknown as [
+        [Envelope, { matador: Dispatcher }],
+      ];
+      expect(calls[0][0]).toEqual(envelope);
+      expect(calls[0][1]).toHaveProperty('matador');
     });
 
     it('should handle callback throwing error', async () => {
@@ -1189,6 +1199,7 @@ function createMockConfig(
     codec: Partial<Codec>;
     retryPolicy: RetryPolicy | Partial<RetryPolicy>;
     hooks: Partial<SafeHooks>;
+    dispatcher: Partial<Dispatcher>;
   }> = {},
 ): PipelineConfig {
   const defaultTransport: Transport = {
@@ -1272,12 +1283,23 @@ function createMockConfig(
     ...overrides.hooks,
   } as SafeHooks;
 
+  const defaultDispatcher: Dispatcher = {
+    send: mock(async () => ({
+      eventKey: 'test.event',
+      subscribersSent: 0,
+      subscribersSkipped: 0,
+      errors: [],
+    })),
+    ...overrides.dispatcher,
+  } as Dispatcher;
+
   return {
     transport: defaultTransport,
     schema: { ...defaultSchema, ...overrides.schema } as SchemaRegistry,
     codec: defaultCodec,
     retryPolicy: defaultRetryPolicy,
     hooks: defaultHooks,
+    dispatcher: defaultDispatcher,
   };
 }
 

package/src/pipeline/pipeline.ts

@@ -10,7 +10,13 @@ import type { SafeHooks } from '../hooks/index.js';
 import type { RetryDecision, RetryPolicy } from '../retry/index.js';
 import type { SchemaRegistry } from '../schema/index.js';
 import type { MessageReceipt, Transport } from '../transport/index.js';
-import type { Envelope, SubscriberDefinition } from '../types/index.js';
+import type {
+  CallbackContext,
+  Dispatcher,
+  Envelope,
+  ResumableCallbackContext,
+  SubscriberDefinition,
+} from '../types/index.js';
 import { isResumableSubscriber } from '../types/index.js';
 
 /**
@@ -24,6 +30,8 @@ export interface PipelineConfig {
   readonly hooks: SafeHooks;
   /** Optional checkpoint store for resumable subscribers */
   readonly checkpointStore?: CheckpointStore | undefined;
+  /** Dispatcher (matador) for sending events from subscriber callbacks */
+  readonly dispatcher: Dispatcher;
 }
 
 /**
@@ -54,6 +62,7 @@ export class ProcessingPipeline {
   private readonly retryPolicy: RetryPolicy;
   private readonly hooks: SafeHooks;
   private readonly checkpointStore: CheckpointStore;
+  private readonly dispatcher: Dispatcher;
 
   constructor(config: PipelineConfig) {
     this.transport = config.transport;
@@ -62,6 +71,7 @@ export class ProcessingPipeline {
     this.retryPolicy = config.retryPolicy;
     this.hooks = config.hooks;
     this.checkpointStore = config.checkpointStore ?? new NoOpCheckpointStore();
+    this.dispatcher = config.dispatcher;
   }
 
   /**
@@ -180,24 +190,36 @@ export class ProcessingPipeline {
       });
     }
 
+    // Create base callback context with matador dispatcher
+    const callbackContext: CallbackContext = { matador: this.dispatcher };
+
     await this.hooks.onWorkerWrap(envelope, subscriberDef, async () => {
       await this.hooks.onWorkerBeforeProcess(envelope, subscriberDef);
 
       try {
         if (isResumable && context) {
-          // Resumable subscriber: pass context as second argument
+          // Resumable subscriber: pass combined context (checkpoint + matador)
           // Cast needed because TypeScript can't narrow the union type based on isResumable
           const resumableCallback = subscriber.callback as (
             envelope: Envelope,
-            context: ResumableContext,
+            context: ResumableCallbackContext,
           ) => Promise<void> | void;
-          result = await resumableCallback(envelope, context);
+          // Create combined context by binding class methods and adding matador
+          const fullContext: ResumableCallbackContext = {
+            io: context.io.bind(context),
+            all: context.all.bind(context),
+            attempt: context.attempt,
+            isRetry: context.isRetry,
+            matador: this.dispatcher,
+          };
+          result = await resumableCallback(envelope, fullContext);
         } else {
-          // Standard subscriber: just pass envelope
+          // Standard subscriber: pass envelope and callback context
           const standardCallback = subscriber.callback as (
             envelope: Envelope,
+            context: CallbackContext,
           ) => Promise<void> | void;
-          result = await standardCallback(envelope);
+          result = await standardCallback(envelope, callbackContext);
         }
       } catch (e) {
         error = e instanceof Error ? e : new Error(String(e));

package/src/topology/builder.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'bun:test';
 import { TopologyBuilder, TopologyValidationError } from './builder.js';
+import { resolveQueueName } from './types.js';
 
 describe('TopologyBuilder', () => {
   describe('withNamespace', () => {
@@ -271,6 +272,58 @@ describe('TopologyBuilder', () => {
 
       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', () => {
@@ -359,3 +412,40 @@ describe('TopologyBuilder', () => {
     });
   });
 });
+
+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

@@ -179,7 +179,8 @@ export class TopologyBuilder {
     for (const queue of this.queues) {
       if (!queue.name || queue.name.trim() === '') {
         issues.push('Queue name cannot be empty');
-      } else if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(queue.name)) {
+      } 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`,
         );

package/src/topology/index.ts

@@ -2,13 +2,17 @@ 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';

package/src/topology/types.ts

@@ -20,7 +20,7 @@ export interface Topology {
  * Individual queue definition.
  */
 export interface QueueDefinition {
-  /** Queue name (will be prefixed with namespace) */
+  /** Queue name (will be prefixed with namespace unless exact: true) */
   readonly name: string;
 
   /** Concurrency for this queue */
@@ -39,6 +39,66 @@ export interface QueueDefinition {
    * queues that are not managed by Matador.
    */
   readonly exact?: boolean | undefined;
+
+  /** Transport-specific queue options */
+  readonly transport?: TransportQueueOptions | undefined;
+}
+
+/**
+ * Transport-specific queue options.
+ * Each transport can define its own options under its transport name key.
+ */
+export interface TransportQueueOptions {
+  /** RabbitMQ-specific queue options */
+  readonly rabbitmq?: RabbitMQQueueDefinition | undefined;
+}
+
+/**
+ * RabbitMQ-specific queue definition options.
+ */
+export interface RabbitMQQueueDefinition {
+  /**
+   * Exact RabbitMQ queue assertion options.
+   * When provided, these options completely replace all auto-computed defaults
+   * (durable, x-queue-type, x-dead-letter-exchange, etc.).
+   */
+  readonly options?: RabbitMQQueueOptions | undefined;
+}
+
+/**
+ * RabbitMQ queue assertion options.
+ * Maps to amqplib's Options.AssertQueue.
+ */
+export interface RabbitMQQueueOptions {
+  /** Queue survives broker restart */
+  readonly durable?: boolean | undefined;
+
+  /** Queue is deleted when last consumer unsubscribes */
+  readonly autoDelete?: boolean | undefined;
+
+  /** Queue can only be used by the declaring connection */
+  readonly exclusive?: boolean | undefined;
+
+  /** Exchange to which dead-lettered messages are sent */
+  readonly deadLetterExchange?: string | undefined;
+
+  /** Routing key for dead-lettered messages */
+  readonly deadLetterRoutingKey?: string | undefined;
+
+  /** Message TTL in milliseconds */
+  readonly messageTtl?: number | undefined;
+
+  /** Queue expires after this many milliseconds of non-use */
+  readonly expires?: number | undefined;
+
+  /** Maximum number of messages in the queue */
+  readonly maxLength?: number | undefined;
+
+  /** Maximum priority level (0-255) */
+  readonly maxPriority?: number | undefined;
+
+  /** Additional x-* arguments for RabbitMQ */
+  readonly arguments?: Record<string, unknown> | undefined;
 }
 
 /**
@@ -107,3 +167,17 @@ export function getRetryQueueName(
 ): string {
   return `${namespace}.${queueName}.retry`;
 }
+
+/**
+ * Resolves the actual queue name for a given queue definition.
+ * When exact: true, returns name as-is. Otherwise, returns namespace.name.
+ */
+export function resolveQueueName(
+  namespace: string,
+  queueDef: QueueDefinition,
+): string {
+  if (queueDef.exact) {
+    return queueDef.name;
+  }
+  return `${namespace}.${queueDef.name}`;
+}

package/src/transport/rabbitmq/rabbitmq-transport.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it, mock } from 'bun:test';
 import type { Logger } from '../../hooks/index.js';
-import { redactAmqpUrl, RabbitMQTransport } from './rabbitmq-transport.js';
+import { RabbitMQTransport, redactAmqpUrl } from './rabbitmq-transport.js';
 
 describe('redactAmqpUrl', () => {
   it('should redact username and password with 4 asterisks', () => {

package/src/transport/rabbitmq/rabbitmq-transport.ts

@@ -604,36 +604,44 @@ export class RabbitMQTransport implements Transport {
       ? queueDef.name
       : `${topology.namespace}.${queueDef.name}`;
 
-    const queueOptions: Options.AssertQueue = {
-      durable: true,
-      arguments: {} as Record<string, unknown>,
-    };
+    const rabbitmqOptions = queueDef.transport?.rabbitmq?.options;
+
+    // If user provided exact RabbitMQ options, use them directly (replaces all defaults)
+    if (rabbitmqOptions) {
+      await channel.assertQueue(queueName, rabbitmqOptions);
+    } else {
+      // Use computed defaults
+      const queueOptions: Options.AssertQueue = {
+        durable: true,
+        arguments: {} as Record<string, unknown>,
+      };
 
-    // Use quorum queues for durability
-    if (this.config.quorumQueues && !queueDef.exact) {
-      queueOptions.arguments['x-queue-type'] = 'quorum';
-    }
+      // Use quorum queues for durability
+      if (this.config.quorumQueues && !queueDef.exact) {
+        queueOptions.arguments['x-queue-type'] = 'quorum';
+      }
 
-    // Set up dead-letter exchange routing
-    const dlxExchange = this.getDLXExchangeName(topology.namespace);
-    if (
-      topology.deadLetter.unhandled.enabled ||
-      topology.deadLetter.undeliverable.enabled
-    ) {
-      queueOptions.arguments['x-dead-letter-exchange'] = dlxExchange;
-    }
+      // Set up dead-letter exchange routing
+      const dlxExchange = this.getDLXExchangeName(topology.namespace);
+      if (
+        topology.deadLetter.unhandled.enabled ||
+        topology.deadLetter.undeliverable.enabled
+      ) {
+        queueOptions.arguments['x-dead-letter-exchange'] = dlxExchange;
+      }
 
-    // Enable priority if requested
-    if (queueDef.priorities) {
-      queueOptions.arguments['x-max-priority'] = 10;
-    }
+      // Enable priority if requested
+      if (queueDef.priorities) {
+        queueOptions.arguments['x-max-priority'] = 10;
+      }
 
-    // Set consumer timeout if specified
-    if (queueDef.consumerTimeout) {
-      queueOptions.arguments['x-consumer-timeout'] = queueDef.consumerTimeout;
-    }
+      // Set consumer timeout if specified
+      if (queueDef.consumerTimeout) {
+        queueOptions.arguments['x-consumer-timeout'] = queueDef.consumerTimeout;
+      }
 
-    await channel.assertQueue(queueName, queueOptions);
+      await channel.assertQueue(queueName, queueOptions);
+    }
 
     // Bind queue to main exchange
     const mainExchange = this.getMainExchangeName(topology.namespace);

package/src/types/dispatcher.ts

@@ -0,0 +1,18 @@
+import type { SendResult } from '../core/fanout.js';
+import type { Event, EventClass, EventOptions } from './event.js';
+
+/**
+ * Interface for dispatching events.
+ * Implemented by Matador to allow subscribers to send events.
+ */
+export interface Dispatcher {
+  /**
+   * Sends an event to all registered subscribers.
+   */
+  send<T>(
+    eventClass: EventClass<T>,
+    data: T,
+    options?: EventOptions,
+  ): Promise<SendResult>;
+  send<T>(event: Event<T>, options?: EventOptions): Promise<SendResult>;
+}

package/src/types/index.ts

@@ -7,6 +7,8 @@ export type {
 } from './common.js';
 export { invalidResult, validResult } from './common.js';
 
+export type { Dispatcher } from './dispatcher.js';
+
 export type { CreateEnvelopeOptions, Docket, Envelope } from './envelope.js';
 export { createEnvelope } from './envelope.js';
 
@@ -26,11 +28,13 @@ export { MatadorEvent } from './event.js';
 export type {
   AnySubscriber,
   BaseSubscriberOptions,
+  CallbackContext,
   CreateResumableSubscriberInput,
   CreateStandardSubscriberInput,
   CreateSubscriberInput,
   EnvelopeOf,
   ResumableCallback,
+  ResumableCallbackContext,
   ResumableSubscriber,
   ResumableSubscriberOptions,
   StandardCallback,

package/src/types/subscriber.ts

@@ -1,8 +1,18 @@
 import type { SubscriberContext } from '../checkpoint/index.js';
 import type { Idempotency, Importance } from './common.js';
+import type { Dispatcher } from './dispatcher.js';
 import type { Envelope } from './envelope.js';
 import type { MatadorEvent } from './event.js';
 
+/**
+ * Context passed to subscriber callbacks.
+ * Provides access to the Matador instance for sending additional events.
+ */
+export interface CallbackContext {
+  /** Matador dispatcher for sending additional events from within a subscriber */
+  readonly matador: Dispatcher;
+}
+
 /**
  * Helper type to get the envelope type for a subscriber callback.
  * Extracts the data type from a MatadorEvent and wraps it in an Envelope.
@@ -16,19 +26,28 @@ export type EnvelopeOf<T extends MatadorEvent> = Envelope<T['data']>;
 
 /**
  * Callback function executed when an event is received (standard subscribers).
- * Receives the full envelope containing id, data, and docket.
+ * Receives the full envelope containing id, data, and docket, plus a context
+ * with access to the matador instance for sending additional events.
  */
 export type StandardCallback<T = unknown> = (
   envelope: Envelope<T>,
+  context: CallbackContext,
 ) => Promise<void> | void;
 
+/**
+ * Context for resumable subscriber callbacks.
+ * Combines checkpoint operations (io, all) with matador access.
+ */
+export type ResumableCallbackContext = SubscriberContext & CallbackContext;
+
 /**
  * Callback function for resumable subscribers.
- * Receives the envelope and a SubscriberContext with io() for checkpointed operations.
+ * Receives the envelope and a context with io() for checkpointed operations
+ * and matador for sending additional events.
  */
 export type ResumableCallback<T = unknown> = (
   envelope: Envelope<T>,
-  context: SubscriberContext,
+  context: ResumableCallbackContext,
 ) => Promise<void> | void;
 
 /**