@zdavison/matador 2.0.4 → 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/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 {
@@ -534,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 {
@@ -581,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",
@@ -1834,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;
@@ -3166,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;