@zdavison/matador 2.0.3 → 2.0.5

package/dist/core/fanout.test.js

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

package/dist/core/matador.d.ts

@@ -5,7 +5,7 @@ import type { RetryPolicy } from '../retry/index.js';
 import type { MatadorSchema } from '../schema/index.js';
 import type { Topology } from '../topology/index.js';
 import type { Transport } from '../transport/index.js';
-import type { AnySubscriber, Event, EventClass, EventOptions } from '../types/index.js';
+import type { AnySubscriber, Dispatcher, Event, EventClass, EventOptions } from '../types/index.js';
 import type { SendResult } from './fanout.js';
 import type { HandlersState, ShutdownConfig } from './shutdown.js';
 /**
@@ -44,7 +44,7 @@ export interface MatadorConfig {
  * - Fanout: Event sending
  * - Shutdown: Graceful termination
  */
-export declare class Matador {
+export declare class Matador implements Dispatcher {
     private readonly transport;
     private readonly topology;
     private readonly schema;

package/dist/core/matador.d.ts.map

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

package/dist/core/matador.js

@@ -56,6 +56,7 @@ export class Matador {
             retryPolicy: this.retryPolicy,
             hooks: this.hooks,
             checkpointStore: config.checkpointStore,
+            dispatcher: this,
         });
         // Create fanout engine
         const defaultQueue = this.topology.queues[0]?.name ?? 'default';

package/dist/errors/index.d.ts

@@ -1,6 +1,6 @@
 export type { HasDescription } from './has-description.js';
 export { hasDescription } from './has-description.js';
-export { DontRetry, DoRetry, EventAssertionError, isAssertionError, isDontRetry, isDoRetry, RetryControlError, } from './retry-errors.js';
+export { assertEvent, DontRetry, DoRetry, EventAssertionError, isAssertionError, isDontRetry, isDoRetry, RetryControlError, } from './retry-errors.js';
 export { MatadorError, isMatadorError, NotStartedError, isNotStartedError, ShutdownInProgressError, TransportNotConnectedError, isTransportNotConnectedError, TransportClosedError, TransportSendError, AllTransportsFailedError, DelayedMessagesNotSupportedError, EventNotRegisteredError, isEventNotRegisteredError, SubscriberNotRegisteredError, isSubscriberNotRegisteredError, NoSubscribersExistError, InvalidSchemaError, SubscriberIsStubError, LocalTransportCannotProcessStubError, QueueNotFoundError, InvalidEventError, MessageMaybePoisonedError, isMessageMaybePoisonedError, IdempotentMessageCannotRetryError, isIdempotentMessageCannotRetryError, TimeoutError, } from './matador-errors.js';
 export { CheckpointStoreError, DuplicateIoKeyError, isCheckpointStoreError, isDuplicateIoKeyError, } from './checkpoint-errors.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EACL,SAAS,EACT,OAAO,EACP,mBAAmB,EACnB,gBAAgB,EAChB,WAAW,EACX,SAAS,EACT,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAEL,YAAY,EACZ,cAAc,EAEd,eAAe,EACf,iBAAiB,EACjB,uBAAuB,EAEvB,0BAA0B,EAC1B,4BAA4B,EAC5B,oBAAoB,EACpB,kBAAkB,EAClB,wBAAwB,EACxB,gCAAgC,EAEhC,uBAAuB,EACvB,yBAAyB,EACzB,4BAA4B,EAC5B,8BAA8B,EAC9B,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,oCAAoC,EAEpC,kBAAkB,EAElB,iBAAiB,EAEjB,yBAAyB,EACzB,2BAA2B,EAC3B,iCAAiC,EACjC,mCAAmC,EAEnC,YAAY,GACb,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAEL,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EACL,WAAW,EACX,SAAS,EACT,OAAO,EACP,mBAAmB,EACnB,gBAAgB,EAChB,WAAW,EACX,SAAS,EACT,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAEL,YAAY,EACZ,cAAc,EAEd,eAAe,EACf,iBAAiB,EACjB,uBAAuB,EAEvB,0BAA0B,EAC1B,4BAA4B,EAC5B,oBAAoB,EACpB,kBAAkB,EAClB,wBAAwB,EACxB,gCAAgC,EAEhC,uBAAuB,EACvB,yBAAyB,EACzB,4BAA4B,EAC5B,8BAA8B,EAC9B,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,oCAAoC,EAEpC,kBAAkB,EAElB,iBAAiB,EAEjB,yBAAyB,EACzB,2BAA2B,EAC3B,iCAAiC,EACjC,mCAAmC,EAEnC,YAAY,GACb,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAEL,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC"}

package/dist/errors/index.js

@@ -1,5 +1,5 @@
 export { hasDescription } from './has-description.js';
-export { DontRetry, DoRetry, EventAssertionError, isAssertionError, isDontRetry, isDoRetry, RetryControlError, } from './retry-errors.js';
+export { assertEvent, DontRetry, DoRetry, EventAssertionError, isAssertionError, isDontRetry, isDoRetry, RetryControlError, } from './retry-errors.js';
 export { 
 // Base class
 MatadorError, isMatadorError, 

package/dist/errors/retry-errors.d.ts

@@ -1,3 +1,4 @@
+import type { Envelope } from '../types/envelope.js';
 /**
  * Base class for retry control errors.
  * These errors control the retry behavior of message processing.
@@ -40,16 +41,24 @@ export declare class DontRetry extends RetryControlError {
     constructor(message?: string);
 }
 /**
- * Assertion error that should never be retried.
- * Use for programming errors and invariant violations.
+ * Thrown by `assertEvent` in the event of a failed assertion.
  *
- * ACTION: Review the assertion failure message to identify the bug
- * in the event payload or subscriber logic.
+ * 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.
+ *
+ * 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 declare class EventAssertionError extends Error {
     readonly name: string;
     readonly description: string;
-    constructor(message: string);
+    /** The envelope that failed the assertion */
+    readonly envelope: Envelope<unknown>;
+    constructor(envelope: Envelope<unknown>, message: string);
     toJSON(): Record<string, unknown>;
 }
 /**
@@ -64,4 +73,30 @@ export declare function isDontRetry(error: unknown): error is DontRetry;
  * Checks if an error is an assertion error (never retry).
  */
 export declare function isAssertionError(error: unknown): error is 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 declare function assertEvent(envelope: Envelope<unknown>, value: unknown, message: string): asserts value;
 //# sourceMappingURL=retry-errors.d.ts.map

package/dist/errors/retry-errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retry-errors.d.ts","sourceRoot":"","sources":["../../src/errors/retry-errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,8BAAsB,iBAAkB,SAAQ,KAAK;IACnD;;OAEG;IACH,SAAiB,IAAI,EAAE,MAAM,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAE1B,OAAO,EAAE,MAAM;IAY3B;;OAEG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAQlC;AAED;;;;;;GAMG;AACH,qBAAa,OAAQ,SAAQ,iBAAiB;IAC5C,QAAQ,CAAC,WAAW,SAGyD;gBAEjE,OAAO,SAA2B;CAG/C;AAED;;;;;;GAMG;AACH,qBAAa,SAAU,SAAQ,iBAAiB;IAC9C,QAAQ,CAAC,WAAW,SAIqD;gBAE7D,OAAO,SAA8B;CAGlD;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,SAAiB,IAAI,EAAE,MAAM,CAAC;IAE9B,QAAQ,CAAC,WAAW,SAImB;gBAE3B,OAAO,EAAE,MAAM;IAW3B,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAQlC;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAE1D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAE9D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAE7E"}
+{"version":3,"file":"retry-errors.d.ts","sourceRoot":"","sources":["../../src/errors/retry-errors.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD;;;GAGG;AACH,8BAAsB,iBAAkB,SAAQ,KAAK;IACnD;;OAEG;IACH,SAAiB,IAAI,EAAE,MAAM,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAE1B,OAAO,EAAE,MAAM;IAY3B;;OAEG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAQlC;AAED;;;;;;GAMG;AACH,qBAAa,OAAQ,SAAQ,iBAAiB;IAC5C,QAAQ,CAAC,WAAW,SAGyD;gBAEjE,OAAO,SAA2B;CAG/C;AAED;;;;;;GAMG;AACH,qBAAa,SAAU,SAAQ,iBAAiB;IAC9C,QAAQ,CAAC,WAAW,SAIqD;gBAE7D,OAAO,SAA8B;CAGlD;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,SAAiB,IAAI,EAAE,MAAM,CAAC;IAE9B,QAAQ,CAAC,WAAW,SAO0E;IAE9F,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;gBAEzB,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM;IAYxD,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CASlC;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAE1D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAE9D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAE7E;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,EAC3B,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,KAAK,CAMf"}

package/dist/errors/retry-errors.js

@@ -1,3 +1,4 @@
+import assert from 'node:assert';
 /**
  * Base class for retry control errors.
  * These errors control the retry behavior of message processing.
@@ -58,20 +59,32 @@ 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.
  *
- * ACTION: Review the assertion failure message to identify the bug
- * in the event payload or subscriber logic.
+ * 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.
+ *
+ * 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 {
-    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.';
-    constructor(message) {
+    description = '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.';
+    /** The envelope that failed the assertion */
+    envelope;
+    constructor(envelope, message) {
         super(message);
         this.name = 'EventAssertionError';
+        this.envelope = envelope;
         Object.defineProperty(this, 'name', {
             value: 'EventAssertionError',
             enumerable: true,
@@ -84,6 +97,7 @@ export class EventAssertionError extends Error {
             name: this.name,
             message: this.message,
             description: this.description,
+            envelope: this.envelope,
             stack: this.stack,
         };
     }
@@ -106,3 +120,36 @@ export function isDontRetry(error) {
 export function isAssertionError(error) {
     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, value, message) {
+    try {
+        assert(value, message);
+    }
+    catch {
+        throw new EventAssertionError(envelope, message);
+    }
+}

package/dist/errors/retry-errors.test.d.ts

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

package/dist/errors/retry-errors.test.d.ts.map

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

package/dist/errors/retry-errors.test.js

@@ -0,0 +1,136 @@
+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 = { 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.envelope).toBe(envelope);
+                expect(error.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.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/dist/index.cjs

@@ -1,17 +1,17 @@
 'use strict';
 
+var assert = require('assert');
 var amqplib = require('amqplib');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
+var assert__default = /*#__PURE__*/_interopDefault(assert);
 var amqplib__default = /*#__PURE__*/_interopDefault(amqplib);
 
 // src/errors/has-description.ts
 function hasDescription(error) {
   return typeof error === "object" && error !== null && "description" in error && typeof error.description === "string";
 }
-
-// src/errors/retry-errors.ts
 var RetryControlError = class extends Error {
   constructor(message) {
     super(message);
@@ -48,10 +48,13 @@ var DontRetry = class extends RetryControlError {
   }
 };
 var EventAssertionError = class extends Error {
-  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.";
-  constructor(message) {
+  description = "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.";
+  /** The envelope that failed the assertion */
+  envelope;
+  constructor(envelope, message) {
     super(message);
     this.name = "EventAssertionError";
+    this.envelope = envelope;
     Object.defineProperty(this, "name", {
       value: "EventAssertionError",
       enumerable: true,
@@ -64,6 +67,7 @@ var EventAssertionError = class extends Error {
       name: this.name,
       message: this.message,
       description: this.description,
+      envelope: this.envelope,
       stack: this.stack
     };
   }
@@ -77,6 +81,13 @@ function isDontRetry(error) {
 function isAssertionError(error) {
   return error instanceof EventAssertionError;
 }
+function assertEvent(envelope, value, message) {
+  try {
+    assert__default.default(value, message);
+  } catch {
+    throw new EventAssertionError(envelope, message);
+  }
+}
 
 // src/errors/matador-errors.ts
 var MatadorError = class extends Error {
@@ -330,6 +341,12 @@ function getDeadLetterQueueName(namespace, queueName, dlqType) {
 function getRetryQueueName(namespace, queueName) {
   return `${namespace}.${queueName}.retry`;
 }
+function resolveQueueName(namespace, queueDef) {
+  if (queueDef.exact) {
+    return queueDef.name;
+  }
+  return `${namespace}.${queueDef.name}`;
+}
 
 // src/topology/builder.ts
 function isQueueDefinition(arg) {
@@ -440,7 +457,7 @@ var TopologyBuilder = 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)) {
         issues.push(
           `Queue name "${queue.name}" must start with a letter and contain only alphanumeric characters, underscores, and hyphens`
         );
@@ -528,6 +545,14 @@ function createEnvelope(options) {
     }
   };
 }
+function createDummyEnvelope(event) {
+  return createEnvelope({
+    data: event.data,
+    eventKey: event.constructor.key,
+    targetSubscriber: "dummy-subscriber",
+    importance: "can-ignore"
+  });
+}
 
 // src/types/event.ts
 var MatadorEvent = class {
@@ -575,7 +600,6 @@ function createSubscriber(input) {
 function createSubscriberStub(input) {
   return {
     name: input.name,
-    description: input.description,
     isStub: true,
     idempotent: input.idempotent ?? "unknown",
     importance: input.importance ?? "should-investigate",
@@ -1406,6 +1430,7 @@ var ProcessingPipeline = class {
   retryPolicy;
   hooks;
   checkpointStore;
+  dispatcher;
   constructor(config) {
     this.transport = config.transport;
     this.schema = config.schema;
@@ -1413,6 +1438,7 @@ var ProcessingPipeline = class {
     this.retryPolicy = config.retryPolicy;
     this.hooks = config.hooks;
     this.checkpointStore = config.checkpointStore ?? new NoOpCheckpointStore();
+    this.dispatcher = config.dispatcher;
   }
   /**
    * Processes a raw message from the transport.
@@ -1499,15 +1525,23 @@ var ProcessingPipeline = class {
         }
       });
     }
+    const callbackContext = { matador: this.dispatcher };
     await this.hooks.onWorkerWrap(envelope, subscriberDef, async () => {
       await this.hooks.onWorkerBeforeProcess(envelope, subscriberDef);
       try {
         if (isResumable && context) {
           const resumableCallback = subscriber.callback;
-          result = await resumableCallback(envelope, context);
+          const fullContext = {
+            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 {
           const standardCallback = subscriber.callback;
-          result = await standardCallback(envelope);
+          result = await standardCallback(envelope, callbackContext);
         }
       } catch (e) {
         error = e instanceof Error ? e : new Error(String(e));
@@ -1818,9 +1852,11 @@ var SchemaRegistry = class {
     if (!subscriber) return void 0;
     const def = {
       name: subscriber.name,
-      description: subscriber.description,
       idempotent: subscriber.idempotent ?? "unknown",
-      importance: subscriber.importance ?? "should-investigate"
+      importance: subscriber.importance ?? "should-investigate",
+      ..."description" in subscriber && subscriber.description !== void 0 && {
+        description: subscriber.description
+      }
     };
     if (subscriber.targetQueue !== void 0) {
       def.targetQueue = subscriber.targetQueue;
@@ -1940,7 +1976,8 @@ var Matador = class {
       codec: this.codec,
       retryPolicy: this.retryPolicy,
       hooks: this.hooks,
-      checkpointStore: config.checkpointStore
+      checkpointStore: config.checkpointStore,
+      dispatcher: this
     });
     const defaultQueue = this.topology.queues[0]?.name ?? "default";
     this.fanout = new FanoutEngine({
@@ -2986,24 +3023,29 @@ var RabbitMQTransport = class {
   }
   async assertWorkQueue(channel, topology, queueDef) {
     const queueName = queueDef.exact ? queueDef.name : `${topology.namespace}.${queueDef.name}`;
-    const queueOptions = {
-      durable: true,
-      arguments: {}
-    };
-    if (this.config.quorumQueues && !queueDef.exact) {
-      queueOptions.arguments["x-queue-type"] = "quorum";
-    }
-    const dlxExchange = this.getDLXExchangeName(topology.namespace);
-    if (topology.deadLetter.unhandled.enabled || topology.deadLetter.undeliverable.enabled) {
-      queueOptions.arguments["x-dead-letter-exchange"] = dlxExchange;
-    }
-    if (queueDef.priorities) {
-      queueOptions.arguments["x-max-priority"] = 10;
-    }
-    if (queueDef.consumerTimeout) {
-      queueOptions.arguments["x-consumer-timeout"] = queueDef.consumerTimeout;
+    const rabbitmqOptions = queueDef.transport?.rabbitmq?.options;
+    if (rabbitmqOptions) {
+      await channel.assertQueue(queueName, rabbitmqOptions);
+    } else {
+      const queueOptions = {
+        durable: true,
+        arguments: {}
+      };
+      if (this.config.quorumQueues && !queueDef.exact) {
+        queueOptions.arguments["x-queue-type"] = "quorum";
+      }
+      const dlxExchange = this.getDLXExchangeName(topology.namespace);
+      if (topology.deadLetter.unhandled.enabled || topology.deadLetter.undeliverable.enabled) {
+        queueOptions.arguments["x-dead-letter-exchange"] = dlxExchange;
+      }
+      if (queueDef.priorities) {
+        queueOptions.arguments["x-max-priority"] = 10;
+      }
+      if (queueDef.consumerTimeout) {
+        queueOptions.arguments["x-consumer-timeout"] = queueDef.consumerTimeout;
+      }
+      await channel.assertQueue(queueName, queueOptions);
     }
-    await channel.assertQueue(queueName, queueOptions);
     const mainExchange = this.getMainExchangeName(topology.namespace);
     await channel.bindQueue(queueName, mainExchange, queueName);
     if (this.delayedExchangeAvailable) {
@@ -3144,8 +3186,10 @@ exports.TopologyValidationError = TopologyValidationError;
 exports.TransportClosedError = TransportClosedError;
 exports.TransportNotConnectedError = TransportNotConnectedError;
 exports.TransportSendError = TransportSendError;
+exports.assertEvent = assertEvent;
 exports.bind = bind;
 exports.consoleLogger = consoleLogger;
+exports.createDummyEnvelope = createDummyEnvelope;
 exports.createEnvelope = createEnvelope;
 exports.createSubscriber = createSubscriber;
 exports.createSubscriberStub = createSubscriberStub;
@@ -3174,6 +3218,7 @@ exports.isSubscriber = isSubscriber;
 exports.isSubscriberNotRegisteredError = isSubscriberNotRegisteredError;
 exports.isSubscriberStub = isSubscriberStub;
 exports.isTransportNotConnectedError = isTransportNotConnectedError;
+exports.resolveQueueName = resolveQueueName;
 exports.supportsDelayedMessages = supportsDelayedMessages;
 exports.supportsDeliveryMode = supportsDeliveryMode;
 exports.validResult = validResult;