@zdavison/matador 2.0.6 → 2.0.8

package/dist/transport/rabbitmq/rabbitmq-transport.d.ts

@@ -10,6 +10,8 @@ import type { MessageHandler, MessageReceipt, SendOptions, SubscribeOptions, Sub
 export interface RabbitMQTransportConfig {
     /** RabbitMQ connection URL */
     readonly url: string;
+    /** Connection name displayed in RabbitMQ management UI */
+    readonly connectionName: string;
     /** Connection manager configuration */
     readonly connection?: Partial<ConnectionManagerConfig> | undefined;
     /** Use quorum queues for durability (default: true) */

package/dist/transport/rabbitmq/rabbitmq-transport.d.ts.map

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

package/dist/transport/rabbitmq/rabbitmq-transport.js

@@ -44,6 +44,7 @@ export class RabbitMQTransport {
         this.logger = config.logger ?? consoleLogger;
         this.config = {
             url: config.url,
+            connectionName: config.connectionName,
             connection: config.connection ?? {},
             quorumQueues: config.quorumQueues ?? true,
             defaultPrefetch: config.defaultPrefetch ?? 10,
@@ -272,7 +273,9 @@ export class RabbitMQTransport {
     }
     async doConnect() {
         this.logger.info(`[Matador] ⏳ Connecting to RabbitMQ at '${redactAmqpUrl(this.config.url)}'.`);
-        const connection = await amqplib.connect(this.config.url);
+        const connection = await amqplib.connect(this.config.url, {
+            clientProperties: { connection_name: this.config.connectionName },
+        });
         this.connection = connection;
         // Handle connection errors - let ConnectionManager handle reconnection
         connection.on('error', (err) => {

package/dist/transport/rabbitmq/rabbitmq-transport.test.js

@@ -54,6 +54,7 @@ describe('RabbitMQTransport', () => {
             };
             const transport = new RabbitMQTransport({
                 url: 'amqp://testuser:testpass@localhost:5672',
+                connectionName: 'test-connection',
                 logger: mockLogger,
                 connection: {
                     maxReconnectAttempts: 1, // Only try once to avoid long retries
@@ -80,6 +81,7 @@ describe('RabbitMQTransport', () => {
             };
             const transport = new RabbitMQTransport({
                 url: 'amqp://localhost:5672',
+                connectionName: 'test-connection',
                 logger: mockLogger,
                 connection: {
                     maxReconnectAttempts: 1,

package/dist/types/envelope.d.ts

@@ -1,4 +1,5 @@
 import type { Importance } from './common.js';
+import type { Event } from './event.js';
 /**
  * Message envelope containing the event data and routing/observability metadata.
  * This is the transport-agnostic message format used throughout Matador.
@@ -79,16 +80,52 @@ export interface CreateEnvelopeOptions<T> extends DocketCreateFields {
  */
 export declare function createEnvelope<T>(options: CreateEnvelopeOptions<T>): Envelope<T>;
 /**
- * Helper to create a test envelope for a given event instance.
+ * Options for creating a dummy envelope.
+ * All fields are optional and will use sensible defaults if not provided.
+ */
+export interface CreateDummyEnvelopeOptions {
+    readonly id?: string | undefined;
+    readonly eventKey?: string | undefined;
+    readonly eventDescription?: string | undefined;
+    readonly targetSubscriber?: string | undefined;
+    readonly importance?: Importance | undefined;
+    readonly correlationId?: string | undefined;
+    readonly metadata?: Record<string, unknown> | undefined;
+    readonly delayMs?: number | undefined;
+}
+/**
+ * Type helper to extract the data type from an Event, or return T as-is.
+ */
+type ExtractData<T> = T extends Event<infer D> ? D : T;
+/**
+ * Helper to create a test envelope for a given event instance or raw data.
  * Useful for unit testing subscriber callbacks directly.
  *
- * @example
+ * When passing an Event instance, the eventKey and eventDescription will be
+ * automatically extracted from the event class (unless overridden in options).
+ *
+ * @example With raw data
+ * ```typescript
+ * const envelope = createDummyEnvelope({ userId: '123', email: 'test@example.com' });
+ * ```
+ *
+ * @example With an Event instance
  * ```typescript
  * const event = new UserCreatedEvent({ userId: '123', email: 'test@example.com' });
  * const envelope = createDummyEnvelope(event);
- * await mySubscriber.callback(envelope, event);
+ * // eventKey is automatically set to UserCreatedEvent.key
+ * await mySubscriber.callback(envelope, event.data);
+ * ```
+ *
+ * @example With options
+ * ```typescript
+ * const event = new UserCreatedEvent({ userId: '123', email: 'test@example.com' });
+ * const envelope = createDummyEnvelope(event, {
+ *   metadata: { traceId: 'abc-123' },
+ *   correlationId: 'request-456',
+ * });
  * ```
  */
-export declare function createDummyEnvelope<T>(data: T): Envelope<T>;
+export declare function createDummyEnvelope<T>(dataOrEvent: T, options?: CreateDummyEnvelopeOptions): Envelope<ExtractData<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;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAO3D"}
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/types/envelope.ts"],"names":[],"mappings":"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"}

package/dist/types/envelope.js

@@ -35,21 +35,65 @@ export function createEnvelope(options) {
     };
 }
 /**
- * Helper to create a test envelope for a given event instance.
+ * Checks if a value is a Matador Event (has data property and constructor with key).
+ */
+function isEvent(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'data' in value &&
+        typeof value.constructor.key === 'string');
+}
+/**
+ * Helper to create a test envelope for a given event instance or raw data.
  * Useful for unit testing subscriber callbacks directly.
  *
- * @example
+ * When passing an Event instance, the eventKey and eventDescription will be
+ * automatically extracted from the event class (unless overridden in options).
+ *
+ * @example With raw data
+ * ```typescript
+ * const envelope = createDummyEnvelope({ userId: '123', email: 'test@example.com' });
+ * ```
+ *
+ * @example With an Event instance
  * ```typescript
  * const event = new UserCreatedEvent({ userId: '123', email: 'test@example.com' });
  * const envelope = createDummyEnvelope(event);
- * await mySubscriber.callback(envelope, event);
+ * // eventKey is automatically set to UserCreatedEvent.key
+ * await mySubscriber.callback(envelope, event.data);
+ * ```
+ *
+ * @example With options
+ * ```typescript
+ * const event = new UserCreatedEvent({ userId: '123', email: 'test@example.com' });
+ * const envelope = createDummyEnvelope(event, {
+ *   metadata: { traceId: 'abc-123' },
+ *   correlationId: 'request-456',
+ * });
  * ```
  */
-export function createDummyEnvelope(data) {
+export function createDummyEnvelope(dataOrEvent, options) {
+    let data;
+    let eventKey = options?.eventKey ?? 'dummy.event.key';
+    let eventDescription = options?.eventDescription;
+    if (isEvent(dataOrEvent)) {
+        data = dataOrEvent.data;
+        const eventStatic = dataOrEvent.constructor;
+        eventKey = options?.eventKey ?? eventStatic.key;
+        eventDescription = options?.eventDescription ?? eventStatic.description;
+    }
+    else {
+        data = dataOrEvent;
+    }
     return createEnvelope({
         data,
-        eventKey: 'dummy.event.key',
-        targetSubscriber: 'dummy-subscriber',
-        importance: 'can-ignore',
+        eventKey,
+        eventDescription,
+        targetSubscriber: options?.targetSubscriber ?? 'dummy-subscriber',
+        importance: options?.importance ?? 'can-ignore',
+        id: options?.id,
+        correlationId: options?.correlationId,
+        metadata: options?.metadata,
+        delayMs: options?.delayMs,
     });
 }

package/dist/types/event.d.ts

@@ -1,21 +1,17 @@
+import type { Jsonifiable } from 'type-fest';
 /**
  * Unique event routing key type alias.
  */
 export type EventKey = string;
-/**
- * JSON-serializable primitive types.
- */
-export type JsonPrimitive = string | number | boolean | null;
-/**
- * JSON-serializable value (recursive type for objects and arrays).
- */
-export type JsonValue = JsonPrimitive | JsonValue[] | {
-    [key: string]: JsonValue;
-};
 /**
  * JSON-serializable record type for metadata.
+ * Uses type-fest's Jsonifiable which accepts:
+ * - Primitives (string, number, boolean, null)
+ * - Arrays of Jsonifiable values
+ * - Objects with Jsonifiable values
+ * - Objects with a toJSON() method
  */
-export type JsonRecord = Record<string, JsonValue>;
+export type JsonRecord = Record<string, Jsonifiable>;
 /**
  * Static properties required on Event classes for schema registration.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../../src/types/event.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE9B;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAE7D;;GAEG;AACH,MAAM,MAAM,SAAS,GACjB,aAAa,GACb,SAAS,EAAE,GACX;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEjC;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO;IACtC,uCAAuC;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B,yDAAyD;IACzD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAErC,yDAAyD;IACzD,KAAK,IAAI,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,KAAK,CAAC,CAAC,GAAG,OAAO;IAChC,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAEjB,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAEtC,yCAAyC;IACzC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE5C;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,8BAAsB,YAAY,CAAC,CAAC,GAAG,OAAO,CAAE,YAAW,KAAK,CAAC,CAAC,CAAC;IACjE,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAC5B,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAE5C,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAE1B,8BAA8B;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,CAAC,GACtE,CAAC,GACD,KAAK,CAAC;AAEV;;GAEG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,OAAO,IAAI,WAAW,CAAC,CAAC,CAAC,GAClD,CAAC,KACC,IAAI,EAAE,CAAC,KACJ,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC"}
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../../src/types/event.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE9B;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO;IACtC,uCAAuC;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B,yDAAyD;IACzD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAErC,yDAAyD;IACzD,KAAK,IAAI,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,KAAK,CAAC,CAAC,GAAG,OAAO;IAChC,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAEjB,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAEtC,yCAAyC;IACzC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE5C;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,8BAAsB,YAAY,CAAC,CAAC,GAAG,OAAO,CAAE,YAAW,KAAK,CAAC,CAAC,CAAC;IACjE,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAC5B,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAE5C,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAE1B,8BAA8B;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,CAAC,GACtE,CAAC,GACD,KAAK,CAAC;AAEV;;GAEG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,OAAO,IAAI,WAAW,CAAC,CAAC,CAAC,GAClD,CAAC,KACC,IAAI,EAAE,CAAC,KACJ,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/dist/types/index.d.ts

@@ -1,10 +1,11 @@
 export type { DeliveryMode, Idempotency, Importance, ValidationError, ValidationResult, } from './common.js';
 export { invalidResult, validResult } from './common.js';
 export type { Dispatcher } from './dispatcher.js';
-export type { CreateEnvelopeOptions, Docket, Envelope } from './envelope.js';
+export type { CreateDummyEnvelopeOptions, CreateEnvelopeOptions, Docket, Envelope, } from './envelope.js';
 export { createDummyEnvelope, createEnvelope } from './envelope.js';
-export type { Event, EventClass, EventData, EventKey, EventOptions, EventStatic, JsonPrimitive, JsonRecord, JsonValue, } from './event.js';
+export type { Event, EventClass, EventData, EventKey, EventOptions, EventStatic, JsonRecord, } from './event.js';
 export { MatadorEvent } from './event.js';
+export type { Jsonifiable } from 'type-fest';
 export type { AnySubscriber, BaseSubscriberOptions, CallbackContext, CreateResumableSubscriberInput, CreateStandardSubscriberInput, CreateSubscriberInput, EnvelopeOf, ResumableCallback, ResumableCallbackContext, ResumableSubscriber, ResumableSubscriberOptions, StandardCallback, StandardSubscriber, StandardSubscriberOptions, Subscriber, SubscriberCallback, SubscriberDefinition, SubscriberOptions, SubscriberStub, } from './subscriber.js';
 export { createSubscriber, createSubscriberStub, isResumableSubscriber, isStandardSubscriber, isSubscriber, isSubscriberStub, } from './subscriber.js';
 //# sourceMappingURL=index.d.ts.map

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,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"}
+{"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,EACV,0BAA0B,EAC1B,qBAAqB,EACrB,MAAM,EACN,QAAQ,GACT,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpE,YAAY,EACV,KAAK,EACL,UAAU,EACV,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,UAAU,GACX,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG1C,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zdavison/matador",
-  "version": "2.0.6",
+  "version": "2.0.8",
   "description": "A batteries-included event system.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -34,7 +34,8 @@
     "send-test-event": "bun ./cli.ts ./examples/config.ts ./examples/event.ts"
   },
   "dependencies": {
-    "amqplib": "^0.10.4"
+    "amqplib": "^0.10.4",
+    "type-fest": "^5.3.1"
   },
   "devDependencies": {
     "@testcontainers/rabbitmq": "^10.16.0",

package/src/hooks/index.ts

@@ -2,7 +2,6 @@ export type {
   DecodeErrorContext,
   EnqueueErrorContext,
   EnqueueSuccessContext,
-  EnqueueWarningContext,
   Logger,
   MatadorHooks,
   TransportFallbackContext,

package/src/hooks/safe-hooks.ts

@@ -10,7 +10,6 @@ import {
   type DecodeErrorContext,
   type EnqueueErrorContext,
   type EnqueueSuccessContext,
-  type EnqueueWarningContext,
   type Logger,
   type MatadorHooks,
   type WorkerErrorContext,
@@ -40,12 +39,6 @@ export class SafeHooks {
     );
   }
 
-  async onEnqueueWarning(context: EnqueueWarningContext): Promise<void> {
-    await this.safeCall('onEnqueueWarning', () =>
-      this.hooks.onEnqueueWarning?.(context),
-    );
-  }
-
   async onEnqueueError(context: EnqueueErrorContext): Promise<void> {
     await this.safeCall('onEnqueueError', () =>
       this.hooks.onEnqueueError?.(context),
@@ -123,22 +116,6 @@ export class SafeHooks {
     }
   }
 
-  async getQueueConcurrency(queueName: string): Promise<number | undefined> {
-    if (!this.hooks.getQueueConcurrency) {
-      return undefined;
-    }
-
-    try {
-      return await this.hooks.getQueueConcurrency(queueName);
-    } catch (error) {
-      this.logger.warn(
-        '[Matador] 🟡 Hook getQueueConcurrency threw an error',
-        error,
-      );
-      return undefined;
-    }
-  }
-
   async getRetryDelay(
     envelope: Envelope,
     attemptNumber: number,

package/src/hooks/types.ts

@@ -38,16 +38,6 @@ export interface EnqueueSuccessContext {
   readonly transport: string;
 }
 
-/**
- * Context for enqueue warning hook (fallback used).
- */
-export interface EnqueueWarningContext {
-  readonly envelope: Envelope;
-  readonly originalQueue: string;
-  readonly fallbackQueue: string;
-  readonly error: Error;
-}
-
 /**
  * Context for transport fallback hook.
  */
@@ -130,11 +120,6 @@ export interface MatadorHooks {
    */
   onEnqueueSuccess?(context: EnqueueSuccessContext): void | Promise<void>;
 
-  /**
-   * Called when enqueue falls back to a secondary queue.
-   */
-  onEnqueueWarning?(context: EnqueueWarningContext): void | Promise<void>;
-
   /**
    * Called when transport fallback occurs during send.
    * Only fires when using MultiTransport with fallbackEnabled=true.
@@ -191,13 +176,6 @@ export interface MatadorHooks {
     | Record<string, unknown>
     | Promise<Record<string, unknown>>;
 
-  /**
-   * Dynamic queue concurrency lookup.
-   */
-  getQueueConcurrency?(
-    queueName: string,
-  ): number | undefined | Promise<number | undefined>;
-
   /**
    * Dynamic retry delay lookup.
    */

package/src/index.ts

@@ -155,7 +155,6 @@ export type {
   DecodeErrorContext,
   EnqueueErrorContext,
   EnqueueSuccessContext,
-  EnqueueWarningContext,
   Logger,
   MatadorHooks,
   WorkerErrorContext,

package/src/transport/rabbitmq/rabbitmq-transport.test.ts

@@ -66,6 +66,7 @@ describe('RabbitMQTransport', () => {
 
       const transport = new RabbitMQTransport({
         url: 'amqp://testuser:testpass@localhost:5672',
+        connectionName: 'test-connection',
         logger: mockLogger,
         connection: {
           maxReconnectAttempts: 1, // Only try once to avoid long retries
@@ -97,6 +98,7 @@ describe('RabbitMQTransport', () => {
 
       const transport = new RabbitMQTransport({
         url: 'amqp://localhost:5672',
+        connectionName: 'test-connection',
         logger: mockLogger,
         connection: {
           maxReconnectAttempts: 1,

package/src/transport/rabbitmq/rabbitmq-transport.ts

@@ -29,6 +29,9 @@ export interface RabbitMQTransportConfig {
   /** RabbitMQ connection URL */
   readonly url: string;
 
+  /** Connection name displayed in RabbitMQ management UI */
+  readonly connectionName: string;
+
   /** Connection manager configuration */
   readonly connection?: Partial<ConnectionManagerConfig> | undefined;
 
@@ -104,7 +107,7 @@ export class RabbitMQTransport implements Transport {
   private readonly config: Required<
     Omit<RabbitMQTransportConfig, 'connection' | 'logger'>
   > & {
-    connection: Partial<ConnectionManagerConfig>;
+    readonly connection: Partial<ConnectionManagerConfig>;
   };
 
   private readonly logger: Logger;
@@ -114,6 +117,7 @@ export class RabbitMQTransport implements Transport {
     this.logger = config.logger ?? consoleLogger;
     this.config = {
       url: config.url,
+      connectionName: config.connectionName,
       connection: config.connection ?? {},
       quorumQueues: config.quorumQueues ?? true,
       defaultPrefetch: config.defaultPrefetch ?? 10,
@@ -445,7 +449,9 @@ export class RabbitMQTransport implements Transport {
     this.logger.info(
       `[Matador] ⏳ Connecting to RabbitMQ at '${redactAmqpUrl(this.config.url)}'.`,
     );
-    const connection = await amqplib.connect(this.config.url);
+    const connection = await amqplib.connect(this.config.url, {
+      clientProperties: { connection_name: this.config.connectionName },
+    });
     this.connection = connection;
 
     // Handle connection errors - let ConnectionManager handle reconnection

package/src/types/envelope.ts

@@ -1,4 +1,5 @@
 import type { Importance } from './common.js';
+import type { Event, EventStatic } from './event.js';
 
 /**
  * Message envelope containing the event data and routing/observability metadata.
@@ -152,21 +153,92 @@ export function createEnvelope<T>(
 }
 
 /**
- * Helper to create a test envelope for a given event instance.
+ * Options for creating a dummy envelope.
+ * All fields are optional and will use sensible defaults if not provided.
+ */
+export interface CreateDummyEnvelopeOptions {
+  readonly id?: string | undefined;
+  readonly eventKey?: string | undefined;
+  readonly eventDescription?: string | undefined;
+  readonly targetSubscriber?: string | undefined;
+  readonly importance?: Importance | undefined;
+  readonly correlationId?: string | undefined;
+  readonly metadata?: Record<string, unknown> | undefined;
+  readonly delayMs?: number | undefined;
+}
+
+/**
+ * Type helper to extract the data type from an Event, or return T as-is.
+ */
+type ExtractData<T> = T extends Event<infer D> ? D : T;
+
+/**
+ * Checks if a value is a Matador Event (has data property and constructor with key).
+ */
+function isEvent<T>(value: unknown): value is Event<T> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'data' in value &&
+    typeof (value.constructor as EventStatic).key === 'string'
+  );
+}
+
+/**
+ * Helper to create a test envelope for a given event instance or raw data.
  * Useful for unit testing subscriber callbacks directly.
  *
- * @example
+ * When passing an Event instance, the eventKey and eventDescription will be
+ * automatically extracted from the event class (unless overridden in options).
+ *
+ * @example With raw data
+ * ```typescript
+ * const envelope = createDummyEnvelope({ userId: '123', email: 'test@example.com' });
+ * ```
+ *
+ * @example With an Event instance
  * ```typescript
  * const event = new UserCreatedEvent({ userId: '123', email: 'test@example.com' });
  * const envelope = createDummyEnvelope(event);
- * await mySubscriber.callback(envelope, event);
+ * // eventKey is automatically set to UserCreatedEvent.key
+ * await mySubscriber.callback(envelope, event.data);
+ * ```
+ *
+ * @example With options
+ * ```typescript
+ * const event = new UserCreatedEvent({ userId: '123', email: 'test@example.com' });
+ * const envelope = createDummyEnvelope(event, {
+ *   metadata: { traceId: 'abc-123' },
+ *   correlationId: 'request-456',
+ * });
  * ```
  */
-export function createDummyEnvelope<T>(data: T): Envelope<T> {
+export function createDummyEnvelope<T>(
+  dataOrEvent: T,
+  options?: CreateDummyEnvelopeOptions,
+): Envelope<ExtractData<T>> {
+  let data: ExtractData<T>;
+  let eventKey = options?.eventKey ?? 'dummy.event.key';
+  let eventDescription = options?.eventDescription;
+
+  if (isEvent(dataOrEvent)) {
+    data = dataOrEvent.data as ExtractData<T>;
+    const eventStatic = dataOrEvent.constructor as EventStatic;
+    eventKey = options?.eventKey ?? eventStatic.key;
+    eventDescription = options?.eventDescription ?? eventStatic.description;
+  } else {
+    data = dataOrEvent as ExtractData<T>;
+  }
+
   return createEnvelope({
     data,
-    eventKey: 'dummy.event.key',
-    targetSubscriber: 'dummy-subscriber',
-    importance: 'can-ignore',
+    eventKey,
+    eventDescription,
+    targetSubscriber: options?.targetSubscriber ?? 'dummy-subscriber',
+    importance: options?.importance ?? 'can-ignore',
+    id: options?.id,
+    correlationId: options?.correlationId,
+    metadata: options?.metadata,
+    delayMs: options?.delayMs,
   });
 }

package/src/types/event.ts

@@ -1,25 +1,19 @@
+import type { Jsonifiable } from 'type-fest';
+
 /**
  * Unique event routing key type alias.
  */
 export type EventKey = string;
 
-/**
- * JSON-serializable primitive types.
- */
-export type JsonPrimitive = string | number | boolean | null;
-
-/**
- * JSON-serializable value (recursive type for objects and arrays).
- */
-export type JsonValue =
-  | JsonPrimitive
-  | JsonValue[]
-  | { [key: string]: JsonValue };
-
 /**
  * JSON-serializable record type for metadata.
+ * Uses type-fest's Jsonifiable which accepts:
+ * - Primitives (string, number, boolean, null)
+ * - Arrays of Jsonifiable values
+ * - Objects with Jsonifiable values
+ * - Objects with a toJSON() method
  */
-export type JsonRecord = Record<string, JsonValue>;
+export type JsonRecord = Record<string, Jsonifiable>;
 
 /**
  * Static properties required on Event classes for schema registration.

package/src/types/index.ts

@@ -9,7 +9,12 @@ export { invalidResult, validResult } from './common.js';
 
 export type { Dispatcher } from './dispatcher.js';
 
-export type { CreateEnvelopeOptions, Docket, Envelope } from './envelope.js';
+export type {
+  CreateDummyEnvelopeOptions,
+  CreateEnvelopeOptions,
+  Docket,
+  Envelope,
+} from './envelope.js';
 export { createDummyEnvelope, createEnvelope } from './envelope.js';
 
 export type {
@@ -19,12 +24,13 @@ export type {
   EventKey,
   EventOptions,
   EventStatic,
-  JsonPrimitive,
   JsonRecord,
-  JsonValue,
 } from './event.js';
 export { MatadorEvent } from './event.js';
 
+// Re-export Jsonifiable from type-fest for convenience
+export type { Jsonifiable } from 'type-fest';
+
 export type {
   AnySubscriber,
   BaseSubscriberOptions,

package/test/e2e/multi-transport.e2e.test.ts

@@ -56,6 +56,7 @@ describe.skipIf(SKIP_E2E)('MultiTransport E2E', () => {
 
       rabbitTransport = new RabbitMQTransport({
         url: connectionUrl,
+        connectionName: 'matador-multi-transport-test',
         quorumQueues: false,
       });