@zdavison/matador 2.0.3 → 2.0.5

package/dist/types/subscriber.d.ts

@@ -1,7 +1,16 @@
 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.
@@ -14,14 +23,27 @@ import type { MatadorEvent } from './event.js';
 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;
+export type StandardCallback<T = unknown> = (envelope: Envelope<T>, 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;
+export type ResumableCallback<T = unknown> = (envelope: Envelope<T>, context: ResumableCallbackContext) => Promise<unknown> | unknown | void;
 /**
  * Callback function executed when an event is received.
  * @deprecated Use StandardCallback or ResumableCallback instead.
@@ -86,7 +108,7 @@ export type Subscriber<T extends MatadorEvent> = StandardSubscriber<T> | Resumab
  * 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;
     /** Indicates this is a stub without implementation */
@@ -175,7 +197,6 @@ export declare function createSubscriber<T extends MatadorEvent>(input: CreateSu
  */
 export interface CreateSubscriberStubInput {
     readonly name: string;
-    readonly description: string;
     readonly idempotent?: 'yes' | 'no' | 'unknown' | undefined;
     readonly importance?: Importance | undefined;
     readonly targetQueue?: string | undefined;
@@ -188,7 +209,6 @@ export interface CreateSubscriberStubInput {
  * ```typescript
  * const stub = createSubscriberStub({
  *   name: 'remote-analytics',
- *   description: 'Sends events to remote analytics service',
  *   targetQueue: 'analytics-worker',
  * });
  * ```
@@ -199,7 +219,7 @@ export declare function createSubscriberStub(input: CreateSubscriberStubInput):
  */
 export interface SubscriberDefinition {
     readonly name: string;
-    readonly description: string;
+    readonly description?: string | undefined;
     readonly idempotent: Idempotency;
     readonly importance: Importance;
     readonly targetQueue?: string | undefined;

package/dist/types/subscriber.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subscriber.d.ts","sourceRoot":"","sources":["../../src/types/subscriber.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"subscriber.d.ts","sourceRoot":"","sources":["../../src/types/subscriber.ts"],"names":[],"mappings":"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"}

package/dist/types/subscriber.js

@@ -79,7 +79,6 @@ export function createSubscriber(input) {
  * ```typescript
  * const stub = createSubscriberStub({
  *   name: 'remote-analytics',
- *   description: 'Sends events to remote analytics service',
  *   targetQueue: 'analytics-worker',
  * });
  * ```
@@ -87,7 +86,6 @@ export function createSubscriber(input) {
 export function createSubscriberStub(input) {
     return {
         name: input.name,
-        description: input.description,
         isStub: true,
         idempotent: input.idempotent ?? 'unknown',
         importance: input.importance ?? 'should-investigate',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zdavison/matador",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "description": "A batteries-included event system.",
   "type": "module",
   "main": "./dist/index.cjs",

package/src/core/fanout.test.ts

@@ -630,7 +630,6 @@ describe('FanoutEngine', () => {
     it('should work with subscriber stubs', async () => {
       const stub = createSubscriberStub({
         name: 'remote-subscriber',
-        description: 'Remote subscriber stub',
         enabled: () => false,
       });
 

package/src/core/matador.ts

@@ -18,6 +18,7 @@ import { getQualifiedQueueName } from '../topology/index.js';
 import type { Subscription, Transport } from '../transport/index.js';
 import type {
   AnySubscriber,
+  Dispatcher,
   Event,
   EventClass,
   EventOptions,
@@ -71,7 +72,7 @@ export interface MatadorConfig {
  * - Fanout: Event sending
  * - Shutdown: Graceful termination
  */
-export class Matador {
+export class Matador implements Dispatcher {
   private readonly transport: Transport;
   private readonly topology: Topology;
   private readonly schema;
@@ -114,6 +115,7 @@ export class Matador {
       retryPolicy: this.retryPolicy,
       hooks: this.hooks,
       checkpointStore: config.checkpointStore,
+      dispatcher: this,
     });
 
     // Create fanout engine

package/src/errors/index.ts

@@ -2,6 +2,7 @@ export type { HasDescription } from './has-description.js';
 export { hasDescription } from './has-description.js';
 
 export {
+  assertEvent,
   DontRetry,
   DoRetry,
   EventAssertionError,

package/src/errors/retry-errors.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect, it } from 'bun:test';
+import { createEnvelope } from '../types/envelope.js';
+import {
+  assertEvent,
+  DontRetry,
+  DoRetry,
+  EventAssertionError,
+  isAssertionError,
+  isDontRetry,
+  isDoRetry,
+} from './retry-errors.js';
+
+function createTestEnvelope(data: unknown = { foo: 'bar' }) {
+  return createEnvelope({
+    data,
+    eventKey: 'test.event',
+    targetSubscriber: 'test-subscriber',
+    importance: 'can-ignore',
+  });
+}
+
+describe('retry-errors', () => {
+  describe('DoRetry', () => {
+    it('should have correct name', () => {
+      const error = new DoRetry('test message');
+      expect(error.name).toBe('DoRetry');
+    });
+
+    it('should have description', () => {
+      const error = new DoRetry('test message');
+      expect(error.description).toBeDefined();
+    });
+
+    it('should serialize to JSON', () => {
+      const error = new DoRetry('test message');
+      const json = error.toJSON();
+      expect(json.name).toBe('DoRetry');
+      expect(json.message).toBe('test message');
+      expect(json.description).toBeDefined();
+    });
+  });
+
+  describe('DontRetry', () => {
+    it('should have correct name', () => {
+      const error = new DontRetry('test message');
+      expect(error.name).toBe('DontRetry');
+    });
+
+    it('should have description', () => {
+      const error = new DontRetry('test message');
+      expect(error.description).toBeDefined();
+    });
+
+    it('should serialize to JSON', () => {
+      const error = new DontRetry('test message');
+      const json = error.toJSON();
+      expect(json.name).toBe('DontRetry');
+      expect(json.message).toBe('test message');
+      expect(json.description).toBeDefined();
+    });
+  });
+
+  describe('EventAssertionError', () => {
+    it('should have correct name', () => {
+      const envelope = createTestEnvelope();
+      const error = new EventAssertionError(envelope, 'assertion failed');
+      expect(error.name).toBe('EventAssertionError');
+    });
+
+    it('should store the envelope', () => {
+      const envelope = createTestEnvelope();
+      const error = new EventAssertionError(envelope, 'assertion failed');
+      expect(error.envelope).toBe(envelope);
+    });
+
+    it('should have description', () => {
+      const envelope = createTestEnvelope();
+      const error = new EventAssertionError(envelope, 'assertion failed');
+      expect(error.description).toBeDefined();
+      expect(error.description).toContain('NOT to retry');
+    });
+
+    it('should serialize to JSON with envelope', () => {
+      const envelope = createTestEnvelope();
+      const error = new EventAssertionError(envelope, 'assertion failed');
+      const json = error.toJSON();
+      expect(json.name).toBe('EventAssertionError');
+      expect(json.message).toBe('assertion failed');
+      expect(json.envelope).toBe(envelope);
+      expect(json.description).toBeDefined();
+    });
+  });
+
+  describe('assertEvent', () => {
+    it('should not throw when value is truthy', () => {
+      const envelope = createTestEnvelope();
+      expect(() => assertEvent(envelope, true, 'should be true')).not.toThrow();
+      expect(() =>
+        assertEvent(envelope, 'string', 'should be string'),
+      ).not.toThrow();
+      expect(() => assertEvent(envelope, 1, 'should be number')).not.toThrow();
+      expect(() => assertEvent(envelope, {}, 'should be object')).not.toThrow();
+      expect(() => assertEvent(envelope, [], 'should be array')).not.toThrow();
+    });
+
+    it('should throw EventAssertionError when value is falsy', () => {
+      const envelope = createTestEnvelope();
+
+      expect(() => assertEvent(envelope, false, 'value was false')).toThrow(
+        EventAssertionError,
+      );
+      expect(() => assertEvent(envelope, null, 'value was null')).toThrow(
+        EventAssertionError,
+      );
+      expect(() =>
+        assertEvent(envelope, undefined, 'value was undefined'),
+      ).toThrow(EventAssertionError);
+      expect(() => assertEvent(envelope, 0, 'value was zero')).toThrow(
+        EventAssertionError,
+      );
+      expect(() => assertEvent(envelope, '', 'value was empty string')).toThrow(
+        EventAssertionError,
+      );
+    });
+
+    it('should include envelope in thrown error', () => {
+      const envelope = createTestEnvelope();
+      try {
+        assertEvent(envelope, false, 'assertion failed');
+        expect.unreachable('should have thrown');
+      } catch (error) {
+        expect(error).toBeInstanceOf(EventAssertionError);
+        expect((error as EventAssertionError).envelope).toBe(envelope);
+        expect((error as EventAssertionError).message).toBe('assertion failed');
+      }
+    });
+
+    it('should include message in thrown error', () => {
+      const envelope = createTestEnvelope();
+      try {
+        assertEvent(envelope, null, 'userId is required');
+        expect.unreachable('should have thrown');
+      } catch (error) {
+        expect(error).toBeInstanceOf(EventAssertionError);
+        expect((error as EventAssertionError).message).toBe('userId is required');
+      }
+    });
+  });
+
+  describe('type guards', () => {
+    it('isDoRetry should identify DoRetry errors', () => {
+      expect(isDoRetry(new DoRetry('test'))).toBe(true);
+      expect(isDoRetry(new DontRetry('test'))).toBe(false);
+      expect(isDoRetry(new Error('test'))).toBe(false);
+      expect(isDoRetry(null)).toBe(false);
+    });
+
+    it('isDontRetry should identify DontRetry errors', () => {
+      expect(isDontRetry(new DontRetry('test'))).toBe(true);
+      expect(isDontRetry(new DoRetry('test'))).toBe(false);
+      expect(isDontRetry(new Error('test'))).toBe(false);
+      expect(isDontRetry(null)).toBe(false);
+    });
+
+    it('isAssertionError should identify EventAssertionError', () => {
+      const envelope = createTestEnvelope();
+      expect(isAssertionError(new EventAssertionError(envelope, 'test'))).toBe(
+        true,
+      );
+      expect(isAssertionError(new DoRetry('test'))).toBe(false);
+      expect(isAssertionError(new Error('test'))).toBe(false);
+      expect(isAssertionError(null)).toBe(false);
+    });
+  });
+});

package/src/errors/retry-errors.ts

@@ -1,3 +1,6 @@
+import assert from 'node:assert';
+import type { Envelope } from '../types/envelope.js';
+
 /**
  * Base class for retry control errors.
  * These errors control the retry behavior of message processing.
@@ -76,24 +79,37 @@ export class DontRetry extends RetryControlError {
 }
 
 /**
- * Assertion error that should never be retried.
- * Use for programming errors and invariant violations.
+ * Thrown by `assertEvent` in the event of a failed assertion.
+ *
+ * This error indicates that an event was in an unexpected state when it reached the subscriber.
+ * Throwing this error will indicate to Matador NOT to retry the event - it will be sent
+ * directly to the undeliverable dead-letter queue.
  *
- * ACTION: Review the assertion failure message to identify the bug
- * in the event payload or subscriber logic.
+ * Use `assertEvent` in your subscribers to assert properties about an event payload.
+ * This is useful in scenarios where you would expect an event payload to contain a field
+ * based on the types, but something unexpected caused it to not be present.
+ *
+ * @see assertEvent
  */
 export class EventAssertionError extends Error {
   declare readonly name: string;
 
   readonly description =
-    'An event assertion failed, indicating a programming error or invariant violation. ' +
-    'ACTION: Review the assertion failure message to identify the bug in the ' +
-    'event payload or subscriber logic. These errors are never retried and go ' +
-    'directly to the dead-letter queue.';
+    'Thrown to indicate that an event was in an unexpected state when it reached the subscriber. ' +
+    'Throwing this error will indicate to Matador NOT to retry the event. ' +
+    'Matador does not throw this error directly - it is thrown by assertEvent, which you can ' +
+    'use in your subscribers to assert properties about an event. ' +
+    'This can be useful in scenarios where you would expect an event payload to contain a field ' +
+    'based on the types, but something unexpected caused it to not be present. ' +
+    'Using this instead of the NodeJS assert allows Matador to not retry the event subscriber.';
 
-  constructor(message: string) {
+  /** The envelope that failed the assertion */
+  readonly envelope: Envelope<unknown>;
+
+  constructor(envelope: Envelope<unknown>, message: string) {
     super(message);
     this.name = 'EventAssertionError';
+    this.envelope = envelope;
     Object.defineProperty(this, 'name', {
       value: 'EventAssertionError',
       enumerable: true,
@@ -107,6 +123,7 @@ export class EventAssertionError extends Error {
       name: this.name,
       message: this.message,
       description: this.description,
+      envelope: this.envelope,
       stack: this.stack,
     };
   }
@@ -132,3 +149,40 @@ export function isDontRetry(error: unknown): error is DontRetry {
 export function isAssertionError(error: unknown): error is EventAssertionError {
   return error instanceof EventAssertionError;
 }
+
+/**
+ * Same as Node.js `assert`, but throws an `EventAssertionError` if the assertion fails.
+ *
+ * `EventAssertionError`s thrown within a subscriber do not cause the subscriber to be retried.
+ * The event will be delivered to the undeliverable dead-letter queue instead.
+ *
+ * @see https://nodejs.org/api/assert.html#assertvalue-message
+ * @param envelope - The envelope this assertion relates to.
+ * @param value - The value to assert. If falsy, the assertion fails.
+ * @param message - The message to include in the error if the assertion fails.
+ * @throws {EventAssertionError} If the assertion fails.
+ *
+ * @example
+ * ```typescript
+ * const subscriber = createSubscriber<MyEvent>({
+ *   name: 'my-subscriber',
+ *   description: 'Processes MyEvent',
+ *   callback: async (envelope) => {
+ *     // Assert that userId exists - if not, event goes to DLQ without retry
+ *     assertEvent(envelope, envelope.data.userId, 'userId is required');
+ *     // ... rest of processing
+ *   },
+ * });
+ * ```
+ */
+export function assertEvent(
+  envelope: Envelope<unknown>,
+  value: unknown,
+  message: string,
+): asserts value {
+  try {
+    assert(value, message);
+  } catch {
+    throw new EventAssertionError(envelope, message);
+  }
+}

package/src/index.ts

@@ -19,8 +19,10 @@ export {
 export type {
   AnySubscriber,
   BaseSubscriberOptions,
+  CallbackContext,
   CreateEnvelopeOptions,
   DeliveryMode,
+  Dispatcher,
   Docket,
   Envelope,
   EnvelopeOf,
@@ -33,6 +35,9 @@ export type {
   Idempotency,
   Importance,
   JsonRecord,
+  ResumableCallback,
+  ResumableCallbackContext,
+  StandardCallback,
   Subscriber,
   SubscriberCallback,
   SubscriberDefinition,
@@ -43,6 +48,7 @@ export type {
 } from './types/index.js';
 export {
   MatadorEvent,
+  createDummyEnvelope,
   createEnvelope,
   createSubscriber,
   createSubscriberStub,
@@ -91,13 +97,17 @@ export type {
   DeadLetterQueueConfig,
   QueueDefinition,
   QueueOptions,
+  RabbitMQQueueDefinition,
+  RabbitMQQueueOptions,
   RetryConfig,
   Topology,
+  TransportQueueOptions,
 } from './topology/index.js';
 export {
   getDeadLetterQueueName,
   getQualifiedQueueName,
   getRetryQueueName,
+  resolveQueueName,
   TopologyBuilder,
   TopologyValidationError,
 } from './topology/index.js';
@@ -162,6 +172,7 @@ export { ProcessingPipeline } from './pipeline/index.js';
 export type { HasDescription } from './errors/index.js';
 export {
   // Retry control errors
+  assertEvent,
   DontRetry,
   DoRetry,
   EventAssertionError,

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 () => {
@@ -532,6 +542,44 @@ describe('ProcessingPipeline', () => {
       });
     });
 
+    it('should pass subscriber return value to onWorkerSuccess', async () => {
+      const envelope = createTestEnvelope();
+      const subscriberDef = createSubscriberDefinition();
+      const onWorkerSuccessMock = mock(async () => {});
+      const returnValue = { processed: true, count: 42 };
+
+      const config = createMockConfig({
+        codec: {
+          decode: mock(() => envelope),
+        },
+        schema: {
+          getSubscriberDefinition: mock(() => subscriberDef),
+          getExecutableSubscriber: mock(() => ({
+            name: 'test-subscriber',
+            description: 'Test subscriber',
+            idempotent: 'unknown' as const,
+            callback: mock(async () => returnValue),
+          })),
+        },
+        hooks: {
+          onWorkerSuccess: onWorkerSuccessMock,
+        },
+      });
+
+      const pipeline = new ProcessingPipeline(config);
+      const receipt = createReceipt();
+
+      await pipeline.process(new Uint8Array(), receipt);
+
+      expect(onWorkerSuccessMock).toHaveBeenCalledWith({
+        envelope,
+        subscriber: subscriberDef,
+        result: returnValue,
+        durationMs: expect.any(Number),
+        transport: 'mock',
+      });
+    });
+
     it('should call onWorkerError after failed callback', async () => {
       const envelope = createTestEnvelope();
       const subscriberDef = createSubscriberDefinition();
@@ -1189,6 +1237,7 @@ function createMockConfig(
     codec: Partial<Codec>;
     retryPolicy: RetryPolicy | Partial<RetryPolicy>;
     hooks: Partial<SafeHooks>;
+    dispatcher: Partial<Dispatcher>;
   }> = {},
 ): PipelineConfig {
   const defaultTransport: Transport = {
@@ -1272,12 +1321,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,
   };
 }