@warlock.js/herald 4.0.174 → 4.1.1

package/esm/message-managers/event-message.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-message.mjs","names":[],"sources":["../../../../../../@warlock.js/herald/src/message-managers/event-message.ts"],"sourcesContent":["/**\n * This class is used to be part of the Herald Event Message Manager.\n * It should be used to trigger events to Either RabbitMQ or Kafka through Herald\n *\n * It's highly recommended using it instead of declaring manual channel namd and publishing data\n */\nimport { GenericObject } from \"@mongez/reinforcements\";\nimport { type ObjectValidator } from \"@warlock.js/seal\";\nimport { randomUUID } from \"crypto\";\n\nexport abstract class EventMessage<TPayload = Record<string, any>> {\n  /**\n   * Event Name\n   */\n  public abstract eventName: string;\n\n  /**\n   * Event version\n   */\n  public version?: number;\n\n  /**\n   * Additional metadata (if any)\n   */\n  public metadata?: Record<string, any>;\n\n  /**\n   * Event Message id\n   */\n  public messageId?: string;\n\n  /**\n   * Schema of payload that will be used to determine whether this event should be published\n   */\n  public schema?: ObjectValidator;\n\n  /**\n   * Data that will be sent with the event (Payload)\n   */\n  public toJSON(): TPayload {\n    if (!this.data) {\n      throw new Error(`no Data is defined for Event: ${this.eventName}`);\n    }\n\n    return this.data as TPayload;\n  }\n\n  public constructor(protected data?: TPayload) {}\n\n  /**\n   * Serialize the event to be ready for publishing.\n   * Delegates payload resolution to toJSON() — override toJSON() to customize.\n   *\n   * @throws Error if toJSON() throws (e.g. no data provided)\n   */\n  public serialize() {\n    const payload = this.toJSON();\n\n    return {\n      payload,\n      metadata: this.metadata,\n      messageId: this.messageId ?? randomUUID(),\n      eventName: this.eventName,\n      version: this.version,\n      occurredAt: new Date(),\n      __through: \"EventMessage\",\n    };\n  }\n}\n\ntype EventOptions<T> = {\n  /**\n   * Shapen the data that will be used\n   */\n  toJSON?: (data: T) => GenericObject;\n  /**\n   * Validation schema\n   */\n  schema?: ObjectValidator;\n};\n\n/**\n * Represents an EventMessage class constructor.\n *\n * @template TIncoming - The type of data accepted by the constructor\n * @template TOutgoing - The type of data returned by toJSON() (defaults to TIncoming)\n */\ntype EventMessageClass<TIncoming = Record<string, any>, TOutgoing = TIncoming> = new (\n  data?: TIncoming,\n) => EventMessage<TOutgoing>;\n\n/**\n * A shorthand to define an event without declaring an entire class.\n *\n * This factory function creates an EventMessage subclass that transforms\n * input data (IncomingData) into a different output format (OutgoingData).\n *\n * @template IncomingData - The type of data passed to the constructor\n * @template OutgoingData - The type of data returned by toJSON()\n *\n * @example\n * ```typescript\n * const UserCreatedEvent = defineEvent<User, { id: number; name: string }>(\n *   \"user.created\",\n *   { toJSON: (user) => user.only([\"id\", \"name\"]) }\n * );\n *\n * publishEvent(new UserCreatedEvent(user));\n * ```\n */\nexport function defineEvent<IncomingData = unknown, OutgoingData = unknown>(\n  eventName: string,\n  options: EventOptions<IncomingData> = {},\n): EventMessageClass<IncomingData, OutgoingData> {\n  // We need to use `any` here to bridge the IncomingData -> OutgoingData transformation\n  // The class accepts IncomingData in constructor but outputs OutgoingData via toJSON()\n  return class AnnouncedEvent extends EventMessage<OutgoingData> {\n    public eventName = eventName;\n    public schema = options.schema;\n\n    public constructor(data?: IncomingData) {\n      super(data as any);\n    }\n\n    public toJSON(): OutgoingData {\n      if (!options.toJSON) return this.data as OutgoingData;\n\n      return options.toJSON(this.data as IncomingData) as OutgoingData;\n    }\n  };\n}\n"],"mappings":";;;AAUA,IAAsB,eAAtB,MAAmE;;;;CA6BjE,AAAO,SAAmB;EACxB,IAAI,CAAC,KAAK,MACR,MAAM,IAAI,MAAM,iCAAiC,KAAK,WAAW;EAGnE,OAAO,KAAK;CACd;CAEA,AAAO,YAAY,AAAU,MAAiB;EAAjB;CAAkB;;;;;;;CAQ/C,AAAO,YAAY;EAGjB,OAAO;GACL,SAHc,KAAK,OAGb;GACN,UAAU,KAAK;GACf,WAAW,KAAK,aAAa,WAAW;GACxC,WAAW,KAAK;GAChB,SAAS,KAAK;GACd,4BAAY,IAAI,KAAK;GACrB,WAAW;EACb;CACF;AACF;;;;;;;;;;;;;;;;;;;;AA0CA,SAAgB,YACd,WACA,UAAsC,CAAC,GACQ;CAG/C,OAAO,MAAM,uBAAuB,aAA2B;EAI7D,AAAO,YAAY,MAAqB;GACtC,MAAM,IAAW;oBAJA;iBACH,QAAQ;EAIxB;EAEA,AAAO,SAAuB;GAC5B,IAAI,CAAC,QAAQ,QAAQ,OAAO,KAAK;GAEjC,OAAO,QAAQ,OAAO,KAAK,IAAoB;EACjD;CACF;AACF"}

package/esm/message-managers/index.d.mts

@@ -0,0 +1,3 @@
+import { EventMessage, defineEvent } from "./event-message.mjs";
+import { EventConsumer, defineConsumer } from "./event-consumer.mjs";
+import { ConsumedEventMessage, EventConsumerClass } from "./types.mjs";

package/esm/message-managers/index.mjs

@@ -0,0 +1,4 @@
+import { EventConsumer, defineConsumer } from "./event-consumer.mjs";
+import { EventMessage, defineEvent } from "./event-message.mjs";
+
+export {  };

package/esm/message-managers/prepare-consumer-subscription.mjs

@@ -0,0 +1,42 @@
+//#region ../../@warlock.js/herald/src/message-managers/prepare-consumer-subscription.ts
+function prepareConsumerSubscription(Consumer, onError) {
+	const callback = async (message, ctx) => {
+		const envelope = message.payload;
+		let eventPayload = envelope.payload;
+		if (envelope.version) {
+			if (!Consumer.isAcceptedVersion(Number(envelope.version))) {
+				ctx.ack();
+				return;
+			}
+		}
+		const consumer = new Consumer();
+		if (consumer.schema) {
+			const result = await consumer.validate(eventPayload);
+			if (!result || result.isValid === false) {
+				ctx.nack();
+				return;
+			}
+			eventPayload = result.data;
+		}
+		try {
+			await consumer.handle(eventPayload, {
+				payload: eventPayload,
+				eventName: Consumer.eventName,
+				messageId: message.metadata.messageId,
+				occurredAt: envelope.occurredAt ? new Date(envelope.occurredAt) : void 0,
+				metadata: envelope.metadata,
+				version: envelope.version,
+				message
+			});
+			ctx.ack();
+		} catch (error) {
+			ctx.nack(true);
+			if (onError) onError(error, Consumer.eventName);
+		}
+	};
+	return callback;
+}
+
+//#endregion
+export { prepareConsumerSubscription };
+//# sourceMappingURL=prepare-consumer-subscription.mjs.map

package/esm/message-managers/prepare-consumer-subscription.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepare-consumer-subscription.mjs","names":[],"sources":["../../../../../../@warlock.js/herald/src/message-managers/prepare-consumer-subscription.ts"],"sourcesContent":["import type { MessageHandler } from \"./../types\";\nimport { EventConsumerClass } from \"./types\";\n\nexport function prepareConsumerSubscription(\n  Consumer: EventConsumerClass,\n  onError?: (error: unknown, consumerName: string) => void,\n) {\n  const callback: MessageHandler<any> = async (message, ctx) => {\n    const envelope = message.payload;\n    let eventPayload = envelope.payload;\n\n    if (envelope.version) {\n      if (!Consumer.isAcceptedVersion(Number(envelope.version))) {\n        ctx.ack(); // Acknowledge but don't process\n        return;\n      }\n    }\n\n    const consumer = new Consumer();\n\n    if (consumer.schema) {\n      const result = await consumer.validate(eventPayload);\n      if (!result || result.isValid === false) {\n        ctx.nack();\n        return;\n      }\n\n      eventPayload = result.data;\n    }\n    try {\n      await consumer.handle(eventPayload, {\n        payload: eventPayload,\n        eventName: Consumer.eventName,\n        messageId: message.metadata.messageId!,\n        occurredAt: envelope.occurredAt ? new Date(envelope.occurredAt) : undefined,\n        metadata: envelope.metadata,\n        version: envelope.version,\n        message,\n      });\n      ctx.ack(); // Auto-ack on success?\n    } catch (error) {\n      ctx.nack(true); // Requeue on failure\n      if (onError) {\n        onError(error, Consumer.eventName);\n      }\n    }\n  };\n\n  return callback;\n}\n"],"mappings":";AAGA,SAAgB,4BACd,UACA,SACA;CACA,MAAM,WAAgC,OAAO,SAAS,QAAQ;EAC5D,MAAM,WAAW,QAAQ;EACzB,IAAI,eAAe,SAAS;EAE5B,IAAI,SAAS,SACX;OAAI,CAAC,SAAS,kBAAkB,OAAO,SAAS,OAAO,CAAC,GAAG;IACzD,IAAI,IAAI;IACR;GACF;;EAGF,MAAM,WAAW,IAAI,SAAS;EAE9B,IAAI,SAAS,QAAQ;GACnB,MAAM,SAAS,MAAM,SAAS,SAAS,YAAY;GACnD,IAAI,CAAC,UAAU,OAAO,YAAY,OAAO;IACvC,IAAI,KAAK;IACT;GACF;GAEA,eAAe,OAAO;EACxB;EACA,IAAI;GACF,MAAM,SAAS,OAAO,cAAc;IAClC,SAAS;IACT,WAAW,SAAS;IACpB,WAAW,QAAQ,SAAS;IAC5B,YAAY,SAAS,aAAa,IAAI,KAAK,SAAS,UAAU,IAAI;IAClE,UAAU,SAAS;IACnB,SAAS,SAAS;IAClB;GACF,CAAC;GACD,IAAI,IAAI;EACV,SAAS,OAAO;GACd,IAAI,KAAK,IAAI;GACb,IAAI,SACF,QAAQ,OAAO,SAAS,SAAS;EAErC;CACF;CAEA,OAAO;AACT"}

package/esm/message-managers/types.d.mts

@@ -0,0 +1,23 @@
+import { Message } from "../types/message.types.mjs";
+import { EventConsumer } from "./event-consumer.mjs";
+//#region ../../@warlock.js/herald/src/message-managers/types.d.ts
+type ConsumedEventMessage = {
+  version?: number;
+  occurredAt?: Date;
+  metadata?: Record<string, any>;
+  messageId: string;
+  eventName: string;
+  payload: Record<string, any>;
+  message: Message<any>;
+};
+type EventConsumerClass<P = Record<string, any>> = {
+  new (): EventConsumer<P>;
+  eventName: string;
+  consumerId: string;
+  minVersion?: number;
+  maxVersion?: number;
+  isAcceptedVersion(version: number): boolean;
+};
+//#endregion
+export { ConsumedEventMessage, EventConsumerClass };
+//# sourceMappingURL=types.d.mts.map

package/esm/message-managers/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../@warlock.js/herald/src/message-managers/types.ts"],"mappings":";;;KAGY,oBAAA;EACV,OAAA;EACA,UAAA,GAAa,IAAA;EACb,QAAA,GAAW,MAAA;EACX,SAAA;EACA,SAAA;EACA,OAAA,EAAS,MAAA;EACT,OAAA,EAAS,OAAA;AAAA;AAAA,KAGC,kBAAA,KAAuB,MAAA;EAAA,QACzB,aAAA,CAAc,CAAA;EACtB,SAAA;EACA,UAAA;EACA,UAAA;EACA,UAAA;EACA,iBAAA,CAAkB,OAAA;AAAA"}

package/esm/types/channel.types.d.mts

@@ -0,0 +1,23 @@
+import { DeadLetterOptions } from "./subscribe.types.mjs";
+import { BaseValidator } from "@warlock.js/seal";
+
+//#region ../../@warlock.js/herald/src/types/channel.types.d.ts
+type ChannelOptions<TPayload = unknown> = {
+  type?: "queue" | "topic" | "fanout";
+  durable?: boolean;
+  autoDelete?: boolean;
+  exclusive?: boolean;
+  deadLetter?: DeadLetterOptions;
+  maxMessageSize?: number;
+  messageTtl?: number;
+  maxLength?: number;
+  schema?: BaseValidator;
+};
+type ChannelStats = {
+  messageCount: number;
+  consumerCount: number;
+  name: string;
+};
+//#endregion
+export { ChannelOptions, ChannelStats };
+//# sourceMappingURL=channel.types.d.mts.map

package/esm/types/channel.types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.types.d.mts","names":[],"sources":["../../../../../../@warlock.js/herald/src/types/channel.types.ts"],"mappings":";;;;KAGY,cAAA;EACV,IAAA;EACA,OAAA;EACA,UAAA;EACA,SAAA;EACA,UAAA,GAAa,iBAAA;EACb,cAAA;EACA,UAAA;EACA,SAAA;EACA,MAAA,GAAS,aAAa;AAAA;AAAA,KAGZ,YAAA;EACV,YAAA;EACA,aAAA;EACA,IAAA;AAAA"}

package/esm/types/connection.types.d.mts

@@ -0,0 +1,67 @@
+//#region ../../@warlock.js/herald/src/types/connection.types.d.ts
+type BaseConnectionOptions = {
+  name?: string;
+  isDefault?: boolean;
+};
+type RabbitMQSocketOptions = {
+  keepAlive?: boolean | number;
+  noDelay?: boolean;
+  timeout?: number;
+  ca?: string | Buffer | Array<string | Buffer>;
+  cert?: string | Buffer;
+  key?: string | Buffer;
+  passphrase?: string;
+  servername?: string;
+  rejectUnauthorized?: boolean;
+};
+type RabbitMQClientOptions = {
+  frameMax?: number;
+  channelMax?: number;
+  locale?: string;
+  socket?: RabbitMQSocketOptions;
+};
+type RabbitMQConnectionOptions<TClientOptions extends RabbitMQClientOptions = RabbitMQClientOptions> = BaseConnectionOptions & {
+  driver: "rabbitmq";
+  host?: string;
+  port?: number;
+  username?: string;
+  password?: string;
+  vhost?: string;
+  uri?: string;
+  heartbeat?: number;
+  connectionTimeout?: number;
+  reconnect?: boolean;
+  reconnectDelay?: number;
+  prefetch?: number;
+  clientOptions?: TClientOptions;
+};
+type KafkaClientOptions = {
+  retry?: {
+    initialRetryTime?: number;
+    retries?: number;
+    maxRetryTime?: number;
+    factor?: number;
+    multiplier?: number;
+  };
+  logLevel?: number;
+  logCreator?: any;
+};
+type KafkaConnectionOptions<TClientOptions extends KafkaClientOptions = KafkaClientOptions> = BaseConnectionOptions & {
+  driver: "kafka";
+  brokers: string[];
+  clientId?: string;
+  connectionTimeout?: number;
+  requestTimeout?: number;
+  ssl?: boolean | object;
+  sasl?: {
+    mechanism: "plain" | "scram-sha-256" | "scram-sha-512";
+    username: string;
+    password: string;
+  };
+  clientOptions?: TClientOptions;
+};
+type ConnectionOptions = RabbitMQConnectionOptions | KafkaConnectionOptions;
+type BrokerConfigurations<TClientOptions = any> = RabbitMQConnectionOptions<TClientOptions extends RabbitMQClientOptions ? TClientOptions : RabbitMQClientOptions> | KafkaConnectionOptions<TClientOptions extends KafkaClientOptions ? TClientOptions : KafkaClientOptions>;
+//#endregion
+export { BaseConnectionOptions, BrokerConfigurations, ConnectionOptions, KafkaClientOptions, KafkaConnectionOptions, RabbitMQClientOptions, RabbitMQConnectionOptions, RabbitMQSocketOptions };
+//# sourceMappingURL=connection.types.d.mts.map

package/esm/types/connection.types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.types.d.mts","names":[],"sources":["../../../../../../@warlock.js/herald/src/types/connection.types.ts"],"mappings":";KAAY,qBAAA;EACV,IAAA;EACA,SAAS;AAAA;AAAA,KAGC,qBAAA;EACV,SAAA;EACA,OAAA;EACA,OAAA;EACA,EAAA,YAAc,MAAA,GAAS,KAAA,UAAe,MAAA;EACtC,IAAA,YAAgB,MAAA;EAChB,GAAA,YAAe,MAAA;EACf,UAAA;EACA,UAAA;EACA,kBAAA;AAAA;AAAA,KAGU,qBAAA;EACV,QAAA;EACA,UAAA;EACA,MAAA;EACA,MAAA,GAAS,qBAAqB;AAAA;AAAA,KAGpB,yBAAA,wBACa,qBAAA,GAAwB,qBAAA,IAC7C,qBAAA;EACF,MAAA;EACA,IAAA;EACA,IAAA;EACA,QAAA;EACA,QAAA;EACA,KAAA;EACA,GAAA;EACA,SAAA;EACA,iBAAA;EACA,SAAA;EACA,cAAA;EACA,QAAA;EACA,aAAA,GAAgB,cAAA;AAAA;AAAA,KAGN,kBAAA;EACV,KAAA;IACE,gBAAA;IACA,OAAA;IACA,YAAA;IACA,MAAA;IACA,UAAA;EAAA;EAEF,QAAA;EACA,UAAA;AAAA;AAAA,KAGU,sBAAA,wBAA8C,kBAAA,GAAqB,kBAAA,IAC7E,qBAAA;EACE,MAAA;EACA,OAAA;EACA,QAAA;EACA,iBAAA;EACA,cAAA;EACA,GAAA;EACA,IAAA;IACE,SAAA;IACA,QAAA;IACA,QAAA;EAAA;EAEF,aAAA,GAAgB,cAAA;AAAA;AAAA,KAGR,iBAAA,GAAoB,yBAAA,GAA4B,sBAAsB;AAAA,KAEtE,oBAAA,yBACR,yBAAA,CACE,cAAA,SAAuB,qBAAA,GAAwB,cAAA,GAAiB,qBAAA,IAElE,sBAAA,CACE,cAAA,SAAuB,kBAAA,GAAqB,cAAA,GAAiB,kBAAA"}

package/esm/types/driver.types.d.mts

@@ -0,0 +1,13 @@
+//#region ../../@warlock.js/herald/src/types/driver.types.d.ts
+type BrokerDriverType = "rabbitmq" | "kafka" | "redis-streams" | "sqs";
+type BrokerEvent = "connected" | "disconnected" | "error" | "reconnecting";
+type BrokerEventListener = (...args: unknown[]) => void;
+type HealthCheckResult = {
+  healthy: boolean;
+  latency?: number;
+  error?: string;
+  details?: Record<string, unknown>;
+};
+//#endregion
+export { BrokerDriverType, BrokerEvent, BrokerEventListener, HealthCheckResult };
+//# sourceMappingURL=driver.types.d.mts.map

package/esm/types/driver.types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.types.d.mts","names":[],"sources":["../../../../../../@warlock.js/herald/src/types/driver.types.ts"],"mappings":";KAAY,gBAAA;AAAA,KAEA,WAAA;AAAA,KAEA,mBAAA,OAA0B,IAAI;AAAA,KAE9B,iBAAA;EACV,OAAA;EACA,OAAA;EACA,KAAA;EACA,OAAA,GAAU,MAAM;AAAA"}

package/esm/types/index.d.mts

@@ -0,0 +1,7 @@
+import { DeadLetterOptions, RetryOptions, SubscribeOptions } from "./subscribe.types.mjs";
+import { ChannelOptions, ChannelStats } from "./channel.types.mjs";
+import { BaseConnectionOptions, BrokerConfigurations, ConnectionOptions, KafkaClientOptions, KafkaConnectionOptions, RabbitMQClientOptions, RabbitMQConnectionOptions, RabbitMQSocketOptions } from "./connection.types.mjs";
+import { BrokerDriverType, BrokerEvent, BrokerEventListener, HealthCheckResult } from "./driver.types.mjs";
+import { Message, MessageContext, MessageHandler, MessageMetadata, ResponseHandler, Subscription } from "./message.types.mjs";
+import { PublishOptions, RequestOptions } from "./publish.types.mjs";
+import { BrokerRegistryEvent, BrokerRegistryListener } from "./registry.types.mjs";

package/esm/types/message.types.d.mts

@@ -0,0 +1,37 @@
+//#region ../../@warlock.js/herald/src/types/message.types.d.ts
+type MessageMetadata = {
+  messageId: string;
+  correlationId?: string;
+  replyTo?: string;
+  priority?: number;
+  timestamp: Date;
+  headers?: Record<string, string>;
+  retryCount?: number;
+  originalChannel?: string;
+};
+type Message<TPayload = unknown> = {
+  readonly metadata: MessageMetadata;
+  readonly payload: TPayload;
+  readonly raw?: unknown;
+};
+type MessageContext = {
+  ack(): Promise<void>;
+  nack(requeue?: boolean): Promise<void>;
+  reject(): Promise<void>;
+  reply<T>(payload: T): Promise<void>;
+  retry(delay?: number): Promise<void>;
+};
+type Subscription = {
+  readonly id: string;
+  readonly channel: string;
+  readonly consumerTag?: string;
+  unsubscribe(): Promise<void>;
+  pause(): Promise<void>;
+  resume(): Promise<void>;
+  isActive(): boolean;
+};
+type MessageHandler<TPayload = unknown> = (message: Message<TPayload>, ctx: MessageContext) => Promise<void> | void;
+type ResponseHandler<TPayload = unknown, TResponse = unknown> = (message: Message<TPayload>, ctx: MessageContext) => Promise<TResponse> | TResponse;
+//#endregion
+export { Message, MessageContext, MessageHandler, MessageMetadata, ResponseHandler, Subscription };
+//# sourceMappingURL=message.types.d.mts.map

package/esm/types/message.types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.types.d.mts","names":[],"sources":["../../../../../../@warlock.js/herald/src/types/message.types.ts"],"mappings":";KAAY,eAAA;EACV,SAAA;EACA,aAAA;EACA,OAAA;EACA,QAAA;EACA,SAAA,EAAW,IAAA;EACX,OAAA,GAAU,MAAM;EAChB,UAAA;EACA,eAAA;AAAA;AAAA,KAGU,OAAA;EAAA,SACD,QAAA,EAAU,eAAA;EAAA,SACV,OAAA,EAAS,QAAQ;EAAA,SACjB,GAAA;AAAA;AAAA,KAGC,cAAA;EACV,GAAA,IAAO,OAAA;EACP,IAAA,CAAK,OAAA,aAAoB,OAAA;EACzB,MAAA,IAAU,OAAA;EACV,KAAA,IAAS,OAAA,EAAS,CAAA,GAAI,OAAA;EACtB,KAAA,CAAM,KAAA,YAAiB,OAAA;AAAA;AAAA,KAGb,YAAA;EAAA,SACD,EAAA;EAAA,SACA,OAAA;EAAA,SACA,WAAA;EACT,WAAA,IAAe,OAAA;EACf,KAAA,IAAS,OAAA;EACT,MAAA,IAAU,OAAA;EACV,QAAA;AAAA;AAAA,KAGU,cAAA,wBACV,OAAA,EAAS,OAAA,CAAQ,QAAA,GACjB,GAAA,EAAK,cAAA,KACF,OAAA;AAAA,KAEO,eAAA,6CACV,OAAA,EAAS,OAAA,CAAQ,QAAA,GACjB,GAAA,EAAK,cAAA,KACF,OAAA,CAAQ,SAAA,IAAa,SAAA"}

package/esm/types/publish.types.d.mts

@@ -0,0 +1,16 @@
+//#region ../../@warlock.js/herald/src/types/publish.types.d.ts
+type PublishOptions = {
+  priority?: number;
+  ttl?: number;
+  delay?: number;
+  headers?: Record<string, string>;
+  persistent?: boolean;
+  correlationId?: string;
+  expiration?: number;
+};
+type RequestOptions = PublishOptions & {
+  timeout?: number;
+};
+//#endregion
+export { PublishOptions, RequestOptions };
+//# sourceMappingURL=publish.types.d.mts.map

package/esm/types/publish.types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish.types.d.mts","names":[],"sources":["../../../../../../@warlock.js/herald/src/types/publish.types.ts"],"mappings":";KAAY,cAAA;EACV,QAAA;EACA,GAAA;EACA,KAAA;EACA,OAAA,GAAU,MAAM;EAChB,UAAA;EACA,aAAA;EACA,UAAA;AAAA;AAAA,KAGU,cAAA,GAAiB,cAAc;EACzC,OAAO;AAAA"}

package/esm/types/registry.types.d.mts

@@ -0,0 +1,8 @@
+import { Broker } from "../communicators/broker.mjs";
+
+//#region ../../@warlock.js/herald/src/types/registry.types.d.ts
+type BrokerRegistryEvent = "registered" | "default-registered" | "connected" | "disconnected";
+type BrokerRegistryListener = (broker: Broker) => void;
+//#endregion
+export { BrokerRegistryEvent, BrokerRegistryListener };
+//# sourceMappingURL=registry.types.d.mts.map

package/esm/types/registry.types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.types.d.mts","names":[],"sources":["../../../../../../@warlock.js/herald/src/types/registry.types.ts"],"mappings":";;;KAEY,mBAAA;AAAA,KAMA,sBAAA,IAA0B,MAAc,EAAN,MAAM"}

package/esm/types/subscribe.types.d.mts

@@ -0,0 +1,21 @@
+//#region ../../@warlock.js/herald/src/types/subscribe.types.d.ts
+type RetryOptions = {
+  maxRetries: number;
+  delay: number | ((attempt: number) => number);
+};
+type DeadLetterOptions = {
+  channel: string;
+  preserveOriginal?: boolean;
+};
+type SubscribeOptions = {
+  consumerId?: string;
+  group?: string;
+  prefetch?: number;
+  autoAck?: boolean;
+  retry?: RetryOptions;
+  deadLetter?: DeadLetterOptions;
+  exclusive?: boolean;
+};
+//#endregion
+export { DeadLetterOptions, RetryOptions, SubscribeOptions };
+//# sourceMappingURL=subscribe.types.d.mts.map

package/esm/types/subscribe.types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscribe.types.d.mts","names":[],"sources":["../../../../../../@warlock.js/herald/src/types/subscribe.types.ts"],"mappings":";KAAY,YAAA;EACV,UAAA;EACA,KAAA,aAAkB,OAAA;AAAA;AAAA,KAGR,iBAAA;EACV,OAAA;EACA,gBAAgB;AAAA;AAAA,KAGN,gBAAA;EACV,UAAA;EACA,KAAA;EACA,QAAA;EACA,OAAA;EACA,KAAA,GAAQ,YAAA;EACR,UAAA,GAAa,iBAAiB;EAC9B,SAAA;AAAA"}

package/esm/use-case-broadcast.d.mts

@@ -0,0 +1,41 @@
+//#region ../../@warlock.js/herald/src/use-case-broadcast.d.ts
+/**
+ * Minimal mirror of `@warlock.js/core`'s `UseCaseBroadcastEvent`.
+ *
+ * Kept local on purpose: this adapter is **structurally typed** so `@warlock.js/herald`
+ * takes no dependency on `@warlock.js/core`. The shape only needs the fields the
+ * adapter reads (`event` for the channel, `payload` for the body).
+ */
+type UseCaseBroadcastEvent = {
+  useCase: string;
+  event: string;
+  id: string;
+  at: Date;
+  payload: unknown;
+};
+/**
+ * Channel adapter that publishes use-case broadcast events onto a herald broker.
+ *
+ * Register it in the use-cases config so successful use cases fan out to the bus:
+ *
+ * @example
+ * // src/config/use-cases.ts
+ * import { heraldBroadcast } from "@warlock.js/herald";
+ *
+ * export default {
+ *   broadcast: {
+ *     enabled: true,
+ *     channels: [heraldBroadcast({ broker: "default" })],
+ *   },
+ * } satisfies UseCaseConfigurations;
+ *
+ * @param options - Optional broker name (defaults to the default broker)
+ */
+declare function heraldBroadcast(options?: {
+  broker?: string;
+}): {
+  broadcast(event: UseCaseBroadcastEvent): Promise<void>;
+};
+//#endregion
+export { UseCaseBroadcastEvent, heraldBroadcast };
+//# sourceMappingURL=use-case-broadcast.d.mts.map

package/esm/use-case-broadcast.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-case-broadcast.d.mts","names":[],"sources":["../../../../../@warlock.js/herald/src/use-case-broadcast.ts"],"mappings":";;AASA;;;;;;KAAY,qBAAA;EACV,OAAA;EACA,KAAA;EACA,EAAA;EACA,EAAA,EAAI,IAAI;EACR,OAAA;AAAA;;;;;;;;;;;AAuBwD;;;;;;;;iBAF1C,eAAA,CAAgB,OAAA;EAAY,MAAA;AAAA;mBAEjB,qBAAA,GAAwB,OAAO;AAAA"}

package/esm/use-case-broadcast.mjs

@@ -0,0 +1,30 @@
+import { herald } from "./utils/connect-to-broker.mjs";
+
+//#region ../../@warlock.js/herald/src/use-case-broadcast.ts
+/**
+* Channel adapter that publishes use-case broadcast events onto a herald broker.
+*
+* Register it in the use-cases config so successful use cases fan out to the bus:
+*
+* @example
+* // src/config/use-cases.ts
+* import { heraldBroadcast } from "@warlock.js/herald";
+*
+* export default {
+*   broadcast: {
+*     enabled: true,
+*     channels: [heraldBroadcast({ broker: "default" })],
+*   },
+* } satisfies UseCaseConfigurations;
+*
+* @param options - Optional broker name (defaults to the default broker)
+*/
+function heraldBroadcast(options) {
+	return { async broadcast(event) {
+		await herald(options?.broker).channel(event.event).publish(event.payload);
+	} };
+}
+
+//#endregion
+export { heraldBroadcast };
+//# sourceMappingURL=use-case-broadcast.mjs.map

package/esm/use-case-broadcast.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-case-broadcast.mjs","names":[],"sources":["../../../../../@warlock.js/herald/src/use-case-broadcast.ts"],"sourcesContent":["import { herald } from \"./utils/connect-to-broker\";\n\n/**\n * Minimal mirror of `@warlock.js/core`'s `UseCaseBroadcastEvent`.\n *\n * Kept local on purpose: this adapter is **structurally typed** so `@warlock.js/herald`\n * takes no dependency on `@warlock.js/core`. The shape only needs the fields the\n * adapter reads (`event` for the channel, `payload` for the body).\n */\nexport type UseCaseBroadcastEvent = {\n  useCase: string;\n  event: string;\n  id: string;\n  at: Date;\n  payload: unknown;\n};\n\n/**\n * Channel adapter that publishes use-case broadcast events onto a herald broker.\n *\n * Register it in the use-cases config so successful use cases fan out to the bus:\n *\n * @example\n * // src/config/use-cases.ts\n * import { heraldBroadcast } from \"@warlock.js/herald\";\n *\n * export default {\n *   broadcast: {\n *     enabled: true,\n *     channels: [heraldBroadcast({ broker: \"default\" })],\n *   },\n * } satisfies UseCaseConfigurations;\n *\n * @param options - Optional broker name (defaults to the default broker)\n */\nexport function heraldBroadcast(options?: { broker?: string }) {\n  return {\n    async broadcast(event: UseCaseBroadcastEvent): Promise<void> {\n      await herald(options?.broker).channel(event.event).publish(event.payload);\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAmCA,SAAgB,gBAAgB,SAA+B;CAC7D,OAAO,EACL,MAAM,UAAU,OAA6C;EAC3D,MAAM,OAAO,SAAS,MAAM,EAAE,QAAQ,MAAM,KAAK,EAAE,QAAQ,MAAM,OAAO;CAC1E,EACF;AACF"}

package/esm/utils/{connect-to-broker.d.ts → connect-to-broker.d.mts}

@@ -1,7 +1,10 @@
-import { Broker } from "../communicators";
-import type { ChannelContract } from "../contracts";
-import { EventConsumerClass, EventMessage } from "../message-managers";
-import type { ChannelOptions, ConnectionOptions } from "../types";
+import { ChannelOptions } from "../types/channel.types.mjs";
+import { ConnectionOptions } from "../types/connection.types.mjs";
+import { ChannelContract } from "../contracts/channel.contract.mjs";
+import { EventMessage } from "../message-managers/event-message.mjs";
+import { EventConsumerClass } from "../message-managers/types.mjs";
+import { Broker } from "../communicators/broker.mjs";
+//#region ../../@warlock.js/herald/src/utils/connect-to-broker.d.ts
 /**
  * Connect to a message broker and register it.
  *
@@ -55,7 +58,7 @@ import type { ChannelOptions, ConnectionOptions } from "../types";
  * herald("analytics").channel("events").publish({ ... });
  * ```
  */
-export declare function connectToBroker(options: ConnectionOptions): Promise<Broker>;
+declare function connectToBroker(options: ConnectionOptions): Promise<Broker>;
 /**
  * Get a broker by name or the default one.
  *
@@ -84,7 +87,7 @@ export declare function connectToBroker(options: ConnectionOptions): Promise<Bro
  *   });
  * ```
  */
-export declare function herald(name?: string): Broker;
+declare function herald(name?: string): Broker;
 /**
  * Get channel instance for the given name from default broker.
  *
@@ -101,7 +104,7 @@ export declare function herald(name?: string): Broker;
  * await channel.publish({ userId: 1 });
  * ```
  */
-export declare function heraldChannel<TPayload = unknown>(name: string, options?: ChannelOptions<TPayload>): ChannelContract<TPayload>;
+declare function heraldChannel<TPayload = unknown>(name: string, options?: ChannelOptions<TPayload>): ChannelContract<TPayload>;
 /**
  * Publish an EventMessage to the default broker.
  *
@@ -114,7 +117,7 @@ export declare function heraldChannel<TPayload = unknown>(name: string, options?
  * await publishEvent(new UserUpdatedEvent({ id: 1, name: "John Doe" }));
  * ```
  */
-export declare function publishEvent<TPayload = Record<string, any>>(event: EventMessage<TPayload>): Promise<void>;
+declare function publishEvent<TPayload = Record<string, any>>(event: EventMessage<TPayload>): Promise<void>;
 /**
  * Subscribe an EventConsumer class to the default broker.
  *
@@ -127,5 +130,7 @@ export declare function publishEvent<TPayload = Record<string, any>>(event: Even
  * await subscribeConsumer(UserUpdatedConsumer);
  * ```
  */
-export declare function subscribeConsumer<TPayload = Record<string, any>>(Consumer: EventConsumerClass<TPayload>): Promise<() => void>;
-//# sourceMappingURL=connect-to-broker.d.ts.map
+declare function subscribeConsumer<TPayload = Record<string, any>>(Consumer: EventConsumerClass<TPayload>): Promise<() => void>;
+//#endregion
+export { connectToBroker, herald, heraldChannel, publishEvent, subscribeConsumer };
+//# sourceMappingURL=connect-to-broker.d.mts.map

package/esm/utils/connect-to-broker.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect-to-broker.d.mts","names":[],"sources":["../../../../../../@warlock.js/herald/src/utils/connect-to-broker.ts"],"mappings":";;;;;;;;;;;;;;;AA0DA;;;;;;;;;;;;;AAAiF;AA6EjF;;;;AAA6C;AAoB7C;;;;;;;;;;;;;;;;;AAG2B;AAgB3B;;;;;;;;iBApHsB,eAAA,CAAgB,OAAA,EAAS,iBAAA,GAAoB,OAAA,CAAQ,MAAA;;;;;;;;AAoHqB;AAgBhG;;;;;;;;;;;;;;;;AACwC;;;;iBAxDxB,MAAA,CAAO,IAAA,YAAgB,MAAM;;;;;;;;;;;;;;;;;iBAoB7B,aAAA,oBAAA,CACd,IAAA,UACA,OAAA,GAAU,cAAA,CAAe,QAAA,IACxB,eAAA,CAAgB,QAAA;;;;;;;;;;;;;iBAgBG,YAAA,YAAwB,MAAA,cAAA,CAAqB,KAAA,EAAO,YAAA,CAAa,QAAA,IAAS,OAAA;;;;;;;;;;;;;iBAgB1E,iBAAA,YAA6B,MAAA,cAAA,CACjD,QAAA,EAAU,kBAAA,CAAmB,QAAA,IAAS,OAAA"}

package/esm/utils/connect-to-broker.mjs

@@ -0,0 +1,168 @@
+import { brokerRegistry } from "../communicators/broker-registry.mjs";
+import "../communicators/index.mjs";
+
+//#region ../../@warlock.js/herald/src/utils/connect-to-broker.ts
+/**
+* Connect to a message broker and register it.
+*
+* This is a high-level utility function that simplifies connection setup
+* for most projects. It handles driver instantiation, connection,
+* broker creation, and automatic registration.
+*
+* **Supported Drivers:**
+* - `rabbitmq` (default) - RabbitMQ/AMQP driver
+* - `kafka` - Apache Kafka driver (coming soon)
+*
+* @param options - Connection configuration options
+* @returns A connected and registered Broker instance
+* @throws {Error} If connection fails or driver is not implemented
+*
+* @example
+* ```typescript
+* // RabbitMQ connection
+* const broker = await connectToBroker({
+*   driver: "rabbitmq",
+*   host: "localhost",
+*   port: 5672,
+*   username: "guest",
+*   password: "guest",
+* });
+*
+* // Use the broker
+* await broker.channel("user.created").publish({ userId: 1 });
+* ```
+*
+* @example
+* ```typescript
+* // Multiple brokers
+* await connectToBroker({
+*   driver: "rabbitmq",
+*   name: "notifications",
+*   isDefault: true,
+*   host: process.env.RABBITMQ_HOST,
+* });
+*
+* await connectToBroker({
+*   driver: "rabbitmq",
+*   name: "analytics",
+*   host: process.env.ANALYTICS_RABBITMQ_HOST,
+* });
+*
+* // Use default broker
+* herald().channel("notifications").publish({ ... });
+*
+* // Use specific broker
+* herald("analytics").channel("events").publish({ ... });
+* ```
+*/
+async function connectToBroker(options) {
+	const driverType = options.driver ?? "rabbitmq";
+	const brokerName = options.name ?? "default";
+	const isDefault = options.isDefault ?? true;
+	let driver;
+	switch (driverType) {
+		case "rabbitmq": {
+			const rabbitOptions = options;
+			const { RabbitMQDriver } = await import("../drivers/rabbitmq/rabbitmq-driver.mjs");
+			driver = new RabbitMQDriver(rabbitOptions);
+			break;
+		}
+		case "kafka": throw new Error("Kafka driver is not yet implemented. Coming soon! For now, please use RabbitMQ.");
+		default: throw new Error(`Unknown driver: "${driverType}". Supported drivers: rabbitmq, kafka`);
+	}
+	const broker = brokerRegistry.register({
+		name: brokerName,
+		driver,
+		isDefault
+	});
+	try {
+		await driver.connect();
+	} catch (error) {
+		throw new Error(`Failed to connect to ${driverType}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	return broker;
+}
+/**
+* Get a broker by name or the default one.
+*
+* This is the main entry point for using brokers in your application.
+* Named after the package — `herald()` carries your messages!
+*
+* @param name - Optional broker name (uses default if not provided)
+* @returns Broker instance
+* @throws MissingBrokerError if broker not found
+*
+* @example
+* // Get default broker
+* const channel = herald().channel("user.created");
+* await channel.publish({ userId: 1 });
+*
+* // Get specific broker
+* const analyticsChannel = herald("analytics").channel("events");
+* await analyticsChannel.publish({ event: "page_view" });
+*
+* // Subscribe to messages
+* herald()
+*   .channel<UserPayload>("user.created")
+*   .subscribe(async (message, ctx) => {
+*     console.log("User created:", message.payload);
+*     await ctx.ack();
+*   });
+* ```
+*/
+function herald(name) {
+	return brokerRegistry.get(name);
+}
+/**
+* Get channel instance for the given name from default broker.
+*
+* Shorthand for `herald().channel(name, options)`.
+*
+* @param name - Channel name
+* @param options - Optional channel options
+* @returns Channel instance
+* @throws MissingBrokerError if broker not found
+*
+* @example
+* ```typescript
+* const channel = heraldChannel("user.created");
+* await channel.publish({ userId: 1 });
+* ```
+*/
+function heraldChannel(name, options) {
+	return herald().channel(name, options);
+}
+/**
+* Publish an EventMessage to the default broker.
+*
+* @param event - Event message to publish
+* @returns Promise that resolves when the event is published
+* @throws Error if the broker is not connected
+*
+* @example
+* ```typescript
+* await publishEvent(new UserUpdatedEvent({ id: 1, name: "John Doe" }));
+* ```
+*/
+async function publishEvent(event) {
+	return herald().publish(event);
+}
+/**
+* Subscribe an EventConsumer class to the default broker.
+*
+* @param Consumer - Event consumer class
+* @returns Unsubscribe function
+* @throws MissingBrokerError if broker not found
+*
+* @example
+* ```typescript
+* await subscribeConsumer(UserUpdatedConsumer);
+* ```
+*/
+async function subscribeConsumer(Consumer) {
+	return herald().subscribe(Consumer);
+}
+
+//#endregion
+export { connectToBroker, herald, heraldChannel, publishEvent, subscribeConsumer };
+//# sourceMappingURL=connect-to-broker.mjs.map