@zdavison/matador 2.0.4 → 2.0.6

package/src/schema/registry.ts

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

package/src/schema/types.test.ts

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

package/src/types/envelope.ts

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

package/src/types/index.ts

@@ -10,7 +10,7 @@ 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,

package/src/types/subscriber.ts

@@ -28,11 +28,14 @@ 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;
+) => Promise<unknown> | unknown | void;
 
 /**
  * Context for resumable subscriber callbacks.
@@ -44,11 +47,14 @@ 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;
+) => Promise<unknown> | unknown | void;
 
 /**
  * Callback function executed when an event is received.
@@ -133,7 +139,8 @@ export type Subscriber<T extends MatadorEvent> =
  * is in a remote service. Declares the subscriber contract without providing
  * the callback.
  */
-export interface SubscriberStub extends StandardSubscriberOptions {
+export interface SubscriberStub
+  extends Omit<StandardSubscriberOptions, 'description'> {
   /** Human-readable name for the subscriber */
   readonly name: string;
 
@@ -282,7 +289,6 @@ export function createSubscriber<T extends MatadorEvent>(
  */
 export interface CreateSubscriberStubInput {
   readonly name: string;
-  readonly description: string;
   readonly idempotent?: 'yes' | 'no' | 'unknown' | undefined;
   readonly importance?: Importance | undefined;
   readonly targetQueue?: string | undefined;
@@ -296,7 +302,6 @@ export interface CreateSubscriberStubInput {
  * ```typescript
  * const stub = createSubscriberStub({
  *   name: 'remote-analytics',
- *   description: 'Sends events to remote analytics service',
  *   targetQueue: 'analytics-worker',
  * });
  * ```
@@ -306,7 +311,6 @@ export function createSubscriberStub(
 ): SubscriberStub {
   return {
     name: input.name,
-    description: input.description,
     isStub: true,
     idempotent: input.idempotent ?? 'unknown',
     importance: input.importance ?? 'should-investigate',
@@ -322,7 +326,7 @@ export function createSubscriberStub(
  */
 export interface SubscriberDefinition {
   readonly name: string;
-  readonly description: string;
+  readonly description?: string | undefined;
   readonly idempotent: Idempotency;
   readonly importance: Importance;
   readonly targetQueue?: string | undefined;