@zdavison/matador 2.0.4 → 2.0.6

package/dist/pipeline/pipeline.test.js

@@ -426,6 +426,39 @@ describe('ProcessingPipeline', () => {
                 transport: 'mock',
             });
         });
+        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',
+                        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();

package/dist/retry/standard-policy.test.js

@@ -6,7 +6,13 @@ 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);
             expect(decision.action).toBe('dead-letter');
             assertDeadLetter(decision);

package/dist/schema/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/schema/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EACV,aAAa,EACb,UAAU,EACV,YAAY,EACZ,UAAU,EACV,oBAAoB,EACrB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EACV,eAAe,EAGf,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAM,YAAW,cAAc;IAC9D,QAAQ,CAAC,WAAW,SAIM;gBAEd,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IAErD;;OAEG;IACH,QAAQ,CAAC,CAAC,EACR,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EACzB,WAAW,EAAE,SAAS,aAAa,EAAE,EACrC,OAAO,GAAE,eAAoB,GAC5B,IAAI;IA6BP;;OAEG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAalD;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,aAAa,EAAE;IAK1D;;OAEG;IACH,aAAa,CACX,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,GACrB,aAAa,GAAG,SAAS;IAK5B;;OAEG;IACH,uBAAuB,CACrB,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,GACrB,oBAAoB,GAAG,SAAS;IAkBnC;;OAEG;IACH,uBAAuB,CACrB,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,GACrB,UAAU,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,GAAG,SAAS;IAMhD;;OAEG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAMtD;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI9B;;OAEG;IACH,YAAY,IAAI,SAAS,MAAM,EAAE;IAIjC;;OAEG;IACH,QAAQ,IAAI,sBAAsB;IAkClC;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb,OAAO,CAAC,QAAQ;CAWjB"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/schema/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EACV,aAAa,EACb,UAAU,EACV,YAAY,EACZ,UAAU,EACV,oBAAoB,EACrB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EACV,eAAe,EAGf,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAM,YAAW,cAAc;IAC9D,QAAQ,CAAC,WAAW,SAIM;gBAEd,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IAErD;;OAEG;IACH,QAAQ,CAAC,CAAC,EACR,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EACzB,WAAW,EAAE,SAAS,aAAa,EAAE,EACrC,OAAO,GAAE,eAAoB,GAC5B,IAAI;IA6BP;;OAEG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAalD;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,aAAa,EAAE;IAK1D;;OAEG;IACH,aAAa,CACX,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,GACrB,aAAa,GAAG,SAAS;IAK5B;;OAEG;IACH,uBAAuB,CACrB,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,GACrB,oBAAoB,GAAG,SAAS;IAqBnC;;OAEG;IACH,uBAAuB,CACrB,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,GACrB,UAAU,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,GAAG,SAAS;IAMhD;;OAEG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAMtD;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI9B;;OAEG;IACH,YAAY,IAAI,SAAS,MAAM,EAAE;IAIjC;;OAEG;IACH,QAAQ,IAAI,sBAAsB;IAkClC;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb,OAAO,CAAC,QAAQ;CAWjB"}

package/dist/schema/registry.js

@@ -79,9 +79,12 @@ export class SchemaRegistry {
             return undefined;
         const def = {
             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) {
             def.targetQueue = subscriber.targetQueue;

package/dist/schema/types.test.js

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

package/dist/types/envelope.d.ts

@@ -78,5 +78,17 @@ export interface CreateEnvelopeOptions<T> extends DocketCreateFields {
  * Creates a new envelope with the provided options.
  */
 export declare function createEnvelope<T>(options: CreateEnvelopeOptions<T>): Envelope<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 declare function createDummyEnvelope<T>(data: T): Envelope<T>;
 export {};
 //# sourceMappingURL=envelope.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/types/envelope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;GAGG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC,GAAG,OAAO;IACnC,kCAAkC;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,qBAAqB;IACrB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAEjB,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,MAAM;IAGrB,4BAA4B;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,0EAA0E;IAC1E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE/C,6CAA6C;IAC7C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAElC,oDAAoD;IACpD,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAEnC,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAIlC;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAEhC,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAI/B,sCAAsC;IACtC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAEhC,yCAAyC;IACzC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE5C;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CACzD;AAED;;GAEG;AACH,KAAK,kBAAkB,GAAG,IAAI,CAC5B,MAAM,EACJ,UAAU,GACV,kBAAkB,GAClB,kBAAkB,GAClB,YAAY,GACZ,eAAe,CAClB,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC,CAAE,SAAQ,kBAAkB;IAClE,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAEjC,qBAAqB;IACrB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAEjB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAExD;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAEjE,iDAAiD;IACjD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAChC,QAAQ,CAAC,CAAC,CAAC,CAmCb"}
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/types/envelope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;GAGG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC,GAAG,OAAO;IACnC,kCAAkC;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,qBAAqB;IACrB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAEjB,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,MAAM;IAGrB,4BAA4B;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,0EAA0E;IAC1E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE/C,6CAA6C;IAC7C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAElC,oDAAoD;IACpD,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAEnC,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAIlC;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAEhC,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAI/B,sCAAsC;IACtC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAEhC,yCAAyC;IACzC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE5C;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CACzD;AAED;;GAEG;AACH,KAAK,kBAAkB,GAAG,IAAI,CAC5B,MAAM,EACJ,UAAU,GACV,kBAAkB,GAClB,kBAAkB,GAClB,YAAY,GACZ,eAAe,CAClB,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC,CAAE,SAAQ,kBAAkB;IAClE,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAEjC,qBAAqB;IACrB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAEjB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAExD;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAEjE,iDAAiD;IACjD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAChC,QAAQ,CAAC,CAAC,CAAC,CAmCb;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAO3D"}

package/dist/types/envelope.js

@@ -34,3 +34,22 @@ export function createEnvelope(options) {
         },
     };
 }
+/**
+ * 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(data) {
+    return createEnvelope({
+        data,
+        eventKey: 'dummy.event.key',
+        targetSubscriber: 'dummy-subscriber',
+        importance: 'can-ignore',
+    });
+}

package/dist/types/index.d.ts

@@ -2,7 +2,7 @@ export type { DeliveryMode, Idempotency, Importance, ValidationError, Validation
 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, EventClass, EventData, EventKey, EventOptions, EventStatic, JsonPrimitive, JsonRecord, JsonValue, } from './event.js';
 export { MatadorEvent } from './event.js';
 export type { AnySubscriber, BaseSubscriberOptions, CallbackContext, CreateResumableSubscriberInput, CreateStandardSubscriberInput, CreateSubscriberInput, EnvelopeOf, ResumableCallback, ResumableCallbackContext, ResumableSubscriber, ResumableSubscriberOptions, StandardCallback, StandardSubscriber, StandardSubscriberOptions, Subscriber, SubscriberCallback, SubscriberDefinition, SubscriberOptions, SubscriberStub, } from './subscriber.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,YAAY,EACZ,WAAW,EACX,UAAU,EACV,eAAe,EACf,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEzD,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,YAAY,EAAE,qBAAqB,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,YAAY,EACV,KAAK,EACL,UAAU,EACV,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,aAAa,EACb,UAAU,EACV,SAAS,GACV,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,YAAY,EACV,aAAa,EACb,qBAAqB,EACrB,eAAe,EACf,8BAA8B,EAC9B,6BAA6B,EAC7B,qBAAqB,EACrB,UAAU,EACV,iBAAiB,EACjB,wBAAwB,EACxB,mBAAmB,EACnB,0BAA0B,EAC1B,gBAAgB,EAChB,kBAAkB,EAClB,yBAAyB,EACzB,UAAU,EACV,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,cAAc,GACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,GACjB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,YAAY,EACZ,WAAW,EACX,UAAU,EACV,eAAe,EACf,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEzD,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,YAAY,EAAE,qBAAqB,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC7E,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpE,YAAY,EACV,KAAK,EACL,UAAU,EACV,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,aAAa,EACb,UAAU,EACV,SAAS,GACV,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,YAAY,EACV,aAAa,EACb,qBAAqB,EACrB,eAAe,EACf,8BAA8B,EAC9B,6BAA6B,EAC7B,qBAAqB,EACrB,UAAU,EACV,iBAAiB,EACjB,wBAAwB,EACxB,mBAAmB,EACnB,0BAA0B,EAC1B,gBAAgB,EAChB,kBAAkB,EAClB,yBAAyB,EACzB,UAAU,EACV,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,cAAc,GACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,GACjB,MAAM,iBAAiB,CAAC"}

package/dist/types/index.js

@@ -1,4 +1,4 @@
 export { invalidResult, validResult } from './common.js';
-export { createEnvelope } from './envelope.js';
+export { createDummyEnvelope, createEnvelope } from './envelope.js';
 export { MatadorEvent } from './event.js';
 export { createSubscriber, createSubscriberStub, isResumableSubscriber, isStandardSubscriber, isSubscriber, isSubscriberStub, } from './subscriber.js';

package/dist/types/subscriber.d.ts

@@ -25,8 +25,11 @@ 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, 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>, context: CallbackContext) => 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.
@@ -36,8 +39,11 @@ export type ResumableCallbackContext = SubscriberContext & CallbackContext;
  * Callback function for resumable subscribers.
  * 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: ResumableCallbackContext) => 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.
@@ -102,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 */
@@ -191,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;
@@ -204,7 +209,6 @@ export interface CreateSubscriberStubInput {
  * ```typescript
  * const stub = createSubscriberStub({
  *   name: 'remote-analytics',
- *   description: 'Sends events to remote analytics service',
  *   targetQueue: 'analytics-worker',
  * });
  * ```
@@ -215,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.4",
+  "version": "2.0.6",
   "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/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

@@ -48,6 +48,7 @@ export type {
 } from './types/index.js';
 export {
   MatadorEvent,
+  createDummyEnvelope,
   createEnvelope,
   createSubscriber,
   createSubscriberStub,
@@ -171,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

@@ -542,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();

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);