@zdavison/matador 2.0.3 → 2.0.5

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/retry/standard-policy.test.ts

@@ -14,7 +14,15 @@ describe('StandardRetryPolicy', () => {
   describe('shouldRetry', () => {
     it('should dead-letter on EventAssertionError', () => {
       const policy = new StandardRetryPolicy();
-      const context = createContext(new EventAssertionError('Invalid event'));
+      const envelope = createEnvelope({
+        eventKey: 'test.event',
+        targetSubscriber: 'test-subscriber',
+        data: { test: 'data' },
+        importance: 'should-investigate',
+      });
+      const context = createContext(
+        new EventAssertionError(envelope, 'Invalid event'),
+      );
 
       const decision = policy.shouldRetry(context);
 

package/src/schema/registry.ts

@@ -120,9 +120,12 @@ export class SchemaRegistry {
 
     const def: SubscriberDefinition = {
       name: subscriber.name,
-      description: subscriber.description,
       idempotent: subscriber.idempotent ?? 'unknown',
       importance: subscriber.importance ?? 'should-investigate',
+      ...('description' in subscriber &&
+        subscriber.description !== undefined && {
+          description: subscriber.description,
+        }),
     };
 
     if (subscriber.targetQueue !== undefined) {

package/src/schema/types.test.ts

@@ -225,7 +225,6 @@ describe('installPlugins', () => {
     });
     const stubSub = createSubscriberStub({
       name: 'remote-analytics',
-      description: 'Remote analytics stub',
       targetQueue: 'analytics-worker',
     });
 

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/envelope.ts

@@ -150,3 +150,26 @@ export function createEnvelope<T>(
     },
   };
 }
+
+/**
+ * Helper to create a test envelope for a given event instance.
+ * Useful for unit testing subscriber callbacks directly.
+ *
+ * @example
+ * ```typescript
+ * const event = new UserCreatedEvent({ userId: '123', email: 'test@example.com' });
+ * const envelope = createDummyEnvelope(event);
+ * await mySubscriber.callback(envelope, event);
+ * ```
+ */
+export function createDummyEnvelope<T>(event: {
+  data: T;
+  constructor: { key: string };
+}): Envelope<T> {
+  return createEnvelope({
+    data: event.data,
+    eventKey: event.constructor.key,
+    targetSubscriber: 'dummy-subscriber',
+    importance: 'can-ignore',
+  });
+}

package/src/types/index.ts

@@ -7,8 +7,10 @@ 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';
+export { createDummyEnvelope, createEnvelope } from './envelope.js';
 
 export type {
   Event,
@@ -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,20 +26,35 @@ 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.
+ *
+ * The callback may optionally return a value, which will be included in the
+ * onWorkerSuccess hook context for logging or observability purposes.
  */
 export type StandardCallback<T = unknown> = (
   envelope: Envelope<T>,
-) => Promise<void> | void;
+  context: CallbackContext,
+) => Promise<unknown> | unknown | 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.
+ *
+ * The callback may optionally return a value, which will be included in the
+ * onWorkerSuccess hook context for logging or observability purposes.
  */
 export type ResumableCallback<T = unknown> = (
   envelope: Envelope<T>,
-  context: SubscriberContext,
-) => Promise<void> | void;
+  context: ResumableCallbackContext,
+) => Promise<unknown> | unknown | void;
 
 /**
  * Callback function executed when an event is received.
@@ -114,7 +139,8 @@ export type Subscriber<T extends MatadorEvent> =
  * is in a remote service. Declares the subscriber contract without providing
  * the callback.
  */
-export interface SubscriberStub extends StandardSubscriberOptions {
+export interface SubscriberStub
+  extends Omit<StandardSubscriberOptions, 'description'> {
   /** Human-readable name for the subscriber */
   readonly name: string;
 
@@ -263,7 +289,6 @@ export function createSubscriber<T extends MatadorEvent>(
  */
 export interface CreateSubscriberStubInput {
   readonly name: string;
-  readonly description: string;
   readonly idempotent?: 'yes' | 'no' | 'unknown' | undefined;
   readonly importance?: Importance | undefined;
   readonly targetQueue?: string | undefined;
@@ -277,7 +302,6 @@ export interface CreateSubscriberStubInput {
  * ```typescript
  * const stub = createSubscriberStub({
  *   name: 'remote-analytics',
- *   description: 'Sends events to remote analytics service',
  *   targetQueue: 'analytics-worker',
  * });
  * ```
@@ -287,7 +311,6 @@ export function createSubscriberStub(
 ): SubscriberStub {
   return {
     name: input.name,
-    description: input.description,
     isStub: true,
     idempotent: input.idempotent ?? 'unknown',
     importance: input.importance ?? 'should-investigate',
@@ -303,7 +326,7 @@ export function createSubscriberStub(
  */
 export interface SubscriberDefinition {
   readonly name: string;
-  readonly description: string;
+  readonly description?: string | undefined;
   readonly idempotent: Idempotency;
   readonly importance: Importance;
   readonly targetQueue?: string | undefined;