@warlock.js/herald 4.0.174 → 4.1.1

package/cjs/index.cjs

@@ -0,0 +1,1355 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (!no_symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+
+//#endregion
+let node_events = require("node:events");
+let _warlock_js_seal = require("@warlock.js/seal");
+let node_crypto = require("node:crypto");
+let crypto = require("crypto");
+
+//#region ../../@warlock.js/herald/src/communicators/broker.ts
+/**
+* Broker - wrapper around a driver with metadata
+*
+* Similar to DataSource in @warlock.js/cascade
+*
+* @example
+* ```typescript
+* const broker = new Broker({
+*   name: "default",
+*   driver: rabbitMQDriver,
+*   isDefault: true,
+* });
+*
+* // Get a channel
+* const channel = broker.channel("user.created");
+* ```
+*/
+var Broker = class {
+	/**
+	* Create a new Broker
+	*
+	* @param options - Broker configuration
+	*/
+	constructor(options) {
+		this.name = options.name;
+		this.driver = options.driver;
+		this.isDefault = Boolean(options.isDefault);
+	}
+	/**
+	* Subscribe the given consumer
+	*/
+	subscribe(consumer) {
+		return this.driver.subscribe(consumer);
+	}
+	/**
+	* Publish the given event message
+	*/
+	publish(event) {
+		this.driver.publish(event);
+	}
+	/**
+	* Get or create a channel
+	*
+	* @param name - Channel name
+	* @param options - Channel options
+	* @returns Channel instance
+	*
+	* @example
+	* ```typescript
+	* // Simple channel
+	* const channel = broker.channel("notifications");
+	*
+	* // Typed channel with schema
+	* const orderChannel = broker.channel<OrderPayload>("orders", {
+	*   schema: OrderSchema,
+	*   durable: true,
+	* });
+	* ```
+	*/
+	channel(name, options) {
+		return this.driver.channel(name, options);
+	}
+	/**
+	* Check if the broker is connected
+	*/
+	get isConnected() {
+		return this.driver.isConnected;
+	}
+	/**
+	* Connect the underlying driver
+	*/
+	async connect() {
+		await this.driver.connect();
+	}
+	/**
+	* Disconnect the underlying driver
+	*/
+	async disconnect() {
+		await this.driver.disconnect();
+	}
+	/**
+	* Start consuming messages
+	*/
+	async startConsuming() {
+		await this.driver.startConsuming();
+	}
+	/**
+	* Stop consuming messages
+	*/
+	async stopConsuming() {
+		await this.driver.stopConsuming();
+	}
+	/**
+	* Health check
+	*/
+	async healthCheck() {
+		return this.driver.healthCheck();
+	}
+};
+
+//#endregion
+//#region ../../@warlock.js/herald/src/communicators/broker-registry.ts
+/**
+* Error thrown when a broker is not found
+*/
+var MissingBrokerError = class extends Error {
+	constructor(message, brokerName) {
+		super(message);
+		this.name = "MissingBrokerError";
+		this.brokerName = brokerName;
+	}
+};
+/**
+* Broker Registry
+*
+* Maintains registry of named brokers.
+* Similar to DataSourceRegistry in @warlock.js/cascade
+*
+* @example
+* ```typescript
+* // Register a broker
+* brokerRegistry.register({
+*   name: "default",
+*   driver: rabbitMQDriver,
+*   isDefault: true,
+* });
+*
+* // Get the default broker
+* const comm = brokerRegistry.get();
+*
+* // Get a specific broker by name
+* const analytics = brokerRegistry.get("analytics");
+*
+* // Listen for events
+* brokerRegistry.on("connected", (comm) => {
+*   console.log(`${comm.name} connected`);
+* });
+* ```
+*/
+var BrokerRegistry = class {
+	constructor() {
+		this.sources = /* @__PURE__ */ new Map();
+		this.events = new node_events.EventEmitter();
+	}
+	/**
+	* Register a new broker
+	*
+	* Sets up event forwarding from the driver to the registry.
+	*
+	* @param options - Broker configuration
+	* @returns The registered broker instance
+	*
+	* @example
+	* ```typescript
+	* const broker = brokerRegistry.register({
+	*   name: "primary",
+	*   driver: myDriver,
+	*   isDefault: true,
+	* });
+	* ```
+	*/
+	register(options) {
+		const broker = new Broker(options);
+		this.sources.set(broker.name, broker);
+		const isNewDefault = broker.isDefault || !this.defaultSource;
+		if (isNewDefault) this.defaultSource = broker;
+		this.events.emit("registered", broker);
+		if (isNewDefault) this.events.emit("default-registered", broker);
+		broker.driver.on("connected", () => {
+			this.events.emit("connected", broker);
+		});
+		broker.driver.on("disconnected", () => {
+			this.events.emit("disconnected", broker);
+		});
+		return broker;
+	}
+	/**
+	* Clear all registered brokers
+	*/
+	clear() {
+		this.defaultSource = void 0;
+		this.sources.clear();
+	}
+	/**
+	* Listen for registry events
+	*
+	* @param event - Event to listen for
+	* @param listener - Callback function
+	*
+	* @example
+	* ```typescript
+	* brokerRegistry.on("registered", (comm) => {
+	*   console.log(`Broker "${comm.name}" registered`);
+	* });
+	*
+	* brokerRegistry.on("connected", (comm) => {
+	*   console.log(`Broker "${comm.name}" connected`);
+	* });
+	* ```
+	*/
+	on(event, listener) {
+		this.events.on(event, listener);
+	}
+	/**
+	* Listen for a registry event once
+	*
+	* @param event - Event to listen for
+	* @param listener - Callback function
+	*/
+	once(event, listener) {
+		this.events.once(event, listener);
+	}
+	/**
+	* Remove an event listener
+	*
+	* @param event - Event to stop listening for
+	* @param listener - Callback to remove
+	*/
+	off(event, listener) {
+		this.events.off(event, listener);
+	}
+	/**
+	* Get a broker by name or the default one
+	*
+	* @param name - Optional broker name
+	* @returns Broker instance
+	* @throws MissingBrokerError if not found
+	*
+	* @example
+	* ```typescript
+	* // Get default broker
+	* const comm = brokerRegistry.get();
+	*
+	* // Get specific broker
+	* const analytics = brokerRegistry.get("analytics");
+	* ```
+	*/
+	get(name) {
+		if (name !== void 0) {
+			const source = this.sources.get(name);
+			if (!source) throw new MissingBrokerError(`Broker "${name}" is not registered.`, name);
+			return source;
+		}
+		if (!this.defaultSource) throw new MissingBrokerError("No default broker registered.");
+		return this.defaultSource;
+	}
+	/**
+	* Check if a broker exists
+	*
+	* @param name - Broker name to check
+	* @returns True if exists
+	*/
+	has(name) {
+		return this.sources.has(name);
+	}
+	/**
+	* Check if any brokers are registered
+	*/
+	hasAny() {
+		return this.sources.size > 0;
+	}
+	/**
+	* Get all registered brokers
+	*
+	* @returns Array of all brokers
+	*
+	* @example
+	* ```typescript
+	* // Disconnect all brokers
+	* for (const comm of brokerRegistry.getAll()) {
+	*   await comm.disconnect();
+	* }
+	* ```
+	*/
+	getAll() {
+		return Array.from(this.sources.values());
+	}
+	/**
+	* Get all broker names
+	*
+	* @returns Array of broker names
+	*/
+	getNames() {
+		return Array.from(this.sources.keys());
+	}
+	/**
+	* Get the default broker (if any)
+	*
+	* @returns Default broker or undefined
+	*/
+	getDefault() {
+		return this.defaultSource;
+	}
+};
+/**
+* Global broker registry instance
+*/
+const brokerRegistry = new BrokerRegistry();
+
+//#endregion
+//#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
+//#region ../../@warlock.js/herald/src/drivers/rabbitmq/rabbitmq-channel.ts
+/**
+* RabbitMQ Channel Implementation
+*
+* Wraps a RabbitMQ queue/exchange with a unified API.
+*
+* @template TPayload - The typed payload
+*/
+var RabbitMQChannel = class {
+	/**
+	* Create a new RabbitMQ channel
+	*/
+	constructor(name, amqpChannel, options) {
+		this.subscriptions = /* @__PURE__ */ new Map();
+		this.asserted = false;
+		this.name = name;
+		this.amqpChannel = amqpChannel;
+		this.options = options ?? {};
+	}
+	/**
+	* Assert the queue exists
+	*/
+	async assert() {
+		if (this.asserted) return;
+		const queueOptions = {
+			durable: this.options.durable ?? true,
+			autoDelete: this.options.autoDelete ?? false,
+			exclusive: this.options.exclusive ?? false,
+			messageTtl: this.options.messageTtl,
+			maxLength: this.options.maxLength,
+			deadLetterExchange: this.options.deadLetter?.channel ? "" : void 0,
+			deadLetterRoutingKey: this.options.deadLetter?.channel
+		};
+		await this.amqpChannel.assertQueue(this.name, queueOptions);
+		this.asserted = true;
+	}
+	/**
+	* Publish a message
+	*/
+	async publish(payload, options) {
+		await this.assert();
+		if (this.options.schema) {
+			const context = {
+				allValues: payload,
+				value: payload
+			};
+			const result = await _warlock_js_seal.v.validate(this.options.schema, payload, { context });
+			if (!result.isValid) throw new Error(`Message validation failed: ${JSON.stringify(result.errors)}`);
+			payload = result.data;
+		}
+		const messageId = (0, node_crypto.randomUUID)();
+		const timestamp = /* @__PURE__ */ new Date();
+		const messageContent = JSON.stringify({
+			payload,
+			metadata: {
+				messageId,
+				timestamp: timestamp.toISOString(),
+				correlationId: options?.correlationId,
+				headers: options?.headers
+			}
+		});
+		const publishOptions = {
+			persistent: options?.persistent ?? true,
+			messageId,
+			timestamp: timestamp.getTime(),
+			correlationId: options?.correlationId,
+			expiration: options?.expiration?.toString(),
+			priority: options?.priority,
+			headers: options?.headers
+		};
+		if (options?.delay) publishOptions.headers = {
+			...publishOptions.headers,
+			"x-delay": options.delay
+		};
+		this.amqpChannel.sendToQueue(this.name, Buffer.from(messageContent), publishOptions);
+	}
+	/**
+	* Publish multiple messages
+	*/
+	async publishBatch(messages, options) {
+		for (const payload of messages) await this.publish(payload, options);
+	}
+	/**
+	* Subscribe to messages
+	*
+	* Smart auto-ack behavior (when autoAck is not true):
+	* - If handler completes successfully without explicit ack/nack/reject → auto-ack
+	* - If handler throws an error → auto-nack (with retry if configured)
+	* - If handler explicitly calls ack/nack/reject → respects that call
+	*/
+	async subscribe(handler, options) {
+		await this.assert();
+		const subscriptionId = options?.consumerId ?? (0, node_crypto.randomUUID)();
+		if (options?.prefetch) await this.amqpChannel.prefetch(options.prefetch);
+		const isFireAndForget = options?.autoAck === true;
+		const consumerOptions = {
+			noAck: isFireAndForget,
+			exclusive: options?.exclusive ?? false,
+			consumerTag: options?.group ?? subscriptionId
+		};
+		const { consumerTag } = await this.amqpChannel.consume(this.name, async (msg) => {
+			if (!msg) return;
+			let ackHandled = isFireAndForget;
+			try {
+				const content = JSON.parse(msg.content.toString());
+				let payload = content.payload;
+				if (this.options.schema) {
+					const context = {
+						allValues: payload,
+						value: payload
+					};
+					const result = await _warlock_js_seal.v.validate(this.options.schema, payload, { context });
+					if (!result.isValid) {
+						this.amqpChannel.nack(msg, false, false);
+						return;
+					}
+					payload = result.data;
+				}
+				const metadata = {
+					messageId: msg.properties.messageId || content.metadata?.messageId || (0, node_crypto.randomUUID)(),
+					timestamp: new Date(msg.properties.timestamp || content.metadata?.timestamp),
+					correlationId: msg.properties.correlationId || content.metadata?.correlationId,
+					replyTo: msg.properties.replyTo,
+					priority: msg.properties.priority,
+					headers: msg.properties.headers,
+					retryCount: msg.properties.headers?.["x-retry-count"] || 0,
+					originalChannel: this.name
+				};
+				const message = {
+					metadata,
+					payload,
+					raw: msg
+				};
+				await handler(message, {
+					ack: async () => {
+						if (!ackHandled) {
+							ackHandled = true;
+							this.amqpChannel.ack(msg);
+						}
+					},
+					nack: async (requeue = true) => {
+						if (!ackHandled) {
+							ackHandled = true;
+							this.amqpChannel.nack(msg, false, requeue);
+						}
+					},
+					reject: async () => {
+						if (!ackHandled) {
+							ackHandled = true;
+							this.amqpChannel.reject(msg, false);
+						}
+					},
+					reply: async (replyPayload) => {
+						if (msg.properties.replyTo) {
+							const replyContent = JSON.stringify({
+								payload: replyPayload,
+								metadata: {
+									messageId: (0, node_crypto.randomUUID)(),
+									timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+									correlationId: msg.properties.correlationId
+								}
+							});
+							this.amqpChannel.sendToQueue(msg.properties.replyTo, Buffer.from(replyContent), { correlationId: msg.properties.correlationId });
+						}
+					},
+					retry: async (delay) => {
+						if (ackHandled) return;
+						ackHandled = true;
+						const retryCount = (metadata.retryCount || 0) + 1;
+						if (retryCount > (options?.retry?.maxRetries ?? 3)) {
+							if (options?.deadLetter) await this.sendToDeadLetter(message, options.deadLetter.channel);
+							this.amqpChannel.ack(msg);
+							return;
+						}
+						const headers = {
+							...msg.properties.headers,
+							"x-retry-count": retryCount
+						};
+						if (delay) headers["x-delay"] = delay;
+						this.amqpChannel.sendToQueue(this.name, msg.content, {
+							...msg.properties,
+							headers
+						});
+						this.amqpChannel.ack(msg);
+					}
+				});
+				if (!ackHandled) this.amqpChannel.ack(msg);
+			} catch (error) {
+				if (ackHandled) return;
+				if (options?.retry) if ((msg.properties.headers?.["x-retry-count"] || 0) < options.retry.maxRetries) this.amqpChannel.nack(msg, false, true);
+				else if (options.deadLetter) this.amqpChannel.nack(msg, false, false);
+				else this.amqpChannel.reject(msg, false);
+				else this.amqpChannel.nack(msg, false, false);
+			}
+		}, consumerOptions);
+		const subscription = new RabbitMQSubscription(subscriptionId, this.name, consumerTag, this.amqpChannel);
+		this.subscriptions.set(subscriptionId, subscription);
+		return subscription;
+	}
+	/**
+	* Unsubscribe by consumer ID
+	*/
+	async unsubscribeById(consumerId) {
+		const subscription = this.subscriptions.get(consumerId);
+		if (subscription) {
+			await subscription.unsubscribe();
+			this.subscriptions.delete(consumerId);
+		}
+	}
+	/**
+	* Stop consuming messages on this channel.
+	* Cancels all active subscriptions gracefully.
+	*/
+	async stopConsuming() {
+		const cancellations = Array.from(this.subscriptions.values()).map((sub) => sub.unsubscribe());
+		await Promise.all(cancellations);
+	}
+	/**
+	* Send message to dead-letter queue
+	*/
+	async sendToDeadLetter(message, deadLetterChannel) {
+		const content = JSON.stringify({
+			payload: message.payload,
+			metadata: {
+				...message.metadata,
+				originalChannel: this.name
+			}
+		});
+		this.amqpChannel.sendToQueue(deadLetterChannel, Buffer.from(content), { persistent: true });
+	}
+	/**
+	* Request-response pattern
+	*/
+	async request(payload, options) {
+		await this.assert();
+		const correlationId = (0, node_crypto.randomUUID)();
+		const timeout = options?.timeout ?? 3e4;
+		const { queue: replyQueue } = await this.amqpChannel.assertQueue("", {
+			exclusive: true,
+			autoDelete: true
+		});
+		return new Promise((resolve, reject) => {
+			const timeoutId = setTimeout(() => {
+				reject(/* @__PURE__ */ new Error(`Request timeout after ${timeout}ms`));
+			}, timeout);
+			this.amqpChannel.consume(replyQueue, (msg) => {
+				if (msg?.properties.correlationId === correlationId) {
+					clearTimeout(timeoutId);
+					resolve(JSON.parse(msg.content.toString()).payload);
+				}
+			}, { noAck: true });
+			const messageContent = JSON.stringify({
+				payload,
+				metadata: {
+					messageId: (0, node_crypto.randomUUID)(),
+					timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+					correlationId
+				}
+			});
+			this.amqpChannel.sendToQueue(this.name, Buffer.from(messageContent), {
+				correlationId,
+				replyTo: replyQueue,
+				expiration: timeout.toString(),
+				...options
+			});
+		});
+	}
+	/**
+	* Register response handler for RPC
+	*/
+	async respond(handler) {
+		return this.subscribe(async (message, ctx) => {
+			const response = await handler(message, ctx);
+			await ctx.reply(response);
+			await ctx.ack();
+		});
+	}
+	/**
+	* Get queue statistics
+	*/
+	async stats() {
+		await this.assert();
+		const queueInfo = await this.amqpChannel.checkQueue(this.name);
+		return {
+			name: this.name,
+			messageCount: queueInfo.messageCount,
+			consumerCount: queueInfo.consumerCount
+		};
+	}
+	/**
+	* Purge all messages
+	*/
+	async purge() {
+		await this.assert();
+		return (await this.amqpChannel.purgeQueue(this.name)).messageCount;
+	}
+	/**
+	* Check if queue exists
+	*/
+	async exists() {
+		try {
+			await this.amqpChannel.checkQueue(this.name);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Delete the queue
+	*/
+	async delete() {
+		for (const subscription of this.subscriptions.values()) await subscription.unsubscribe();
+		this.subscriptions.clear();
+		try {
+			await this.amqpChannel.deleteQueue(this.name);
+		} catch {}
+		this.asserted = false;
+	}
+};
+/**
+* RabbitMQ Subscription Implementation
+*/
+var RabbitMQSubscription = class {
+	constructor(id, channel, consumerTag, amqpChannel) {
+		this._isActive = true;
+		this.id = id;
+		this.channel = channel;
+		this.consumerTag = consumerTag;
+		this.amqpChannel = amqpChannel;
+	}
+	async unsubscribe() {
+		if (!this._isActive) return;
+		await this.amqpChannel.cancel(this.consumerTag);
+		this._isActive = false;
+	}
+	async pause() {
+		await this.amqpChannel.cancel(this.consumerTag);
+	}
+	async resume() {
+		throw new Error("Resume is not supported for RabbitMQ. Please create a new subscription.");
+	}
+	isActive() {
+		return this._isActive;
+	}
+};
+
+//#endregion
+//#region ../../@warlock.js/herald/src/drivers/rabbitmq/rabbitmq-driver.ts
+var rabbitmq_driver_exports = /* @__PURE__ */ __exportAll({ RabbitMQDriver: () => RabbitMQDriver });
+/**
+* Cached amqplib module (loaded once, reused)
+*/
+let amqplibModule;
+/**
+* Module availability flag
+*/
+let isModuleExists = null;
+/**
+* Installation instructions for amqplib
+*/
+const AMQPLIB_INSTALL_INSTRUCTIONS = `
+RabbitMQ driver requires the amqplib package.
+Install it with:
+
+  npx warlock add herald --driver=rabbitmq
+
+Or manually:
+
+  npm install amqplib
+  pnpm add amqplib
+  yarn add amqplib
+`.trim();
+/**
+* Load amqplib module
+*/
+async function loadAmqplibModule() {
+	try {
+		amqplibModule = await import("amqplib");
+		isModuleExists = true;
+	} catch {
+		isModuleExists = false;
+	}
+}
+loadAmqplibModule();
+/**
+* RabbitMQ Driver
+*
+* Implementation of BrokerDriverContract for RabbitMQ/AMQP.
+*
+* **Important:** This driver requires the `amqplib` package to be installed.
+* Install it with: `npx warlock add herald --driver=rabbitmq` or `npm install amqplib`
+*
+* @example
+* ```typescript
+* const driver = new RabbitMQDriver({
+*   driver: "rabbitmq",
+*   host: "localhost",
+*   port: 5672,
+*   username: "guest",
+*   password: "guest",
+* });
+*
+* await driver.connect();
+* const channel = driver.channel("user.created");
+* ```
+*/
+var RabbitMQDriver = class {
+	/**
+	* Create a new RabbitMQ driver
+	*
+	* @param options - RabbitMQ connection options
+	*/
+	constructor(options) {
+		this.name = "rabbitmq";
+		this.consumers = [];
+		this.events = new node_events.EventEmitter();
+		this.channels = /* @__PURE__ */ new Map();
+		this.connection = null;
+		this.amqpChannel = null;
+		this._isConnected = false;
+		this.options = options;
+	}
+	/**
+	* Whether connected to RabbitMQ
+	*/
+	get isConnected() {
+		return this._isConnected;
+	}
+	/**
+	* Subscribe the given consumer class to the driver
+	*
+	* @param consumer - Consumer class to subscribe
+	*
+	* @example
+	* ```typescript
+	* driver.subscribe(UserUpdatedConsumer);
+	* ```
+	*/
+	subscribe(Consumer) {
+		if (this.isConnected) this.channel(Consumer.eventName).subscribe(prepareConsumerSubscription(Consumer, (error, eventName) => {
+			this.events.emit("error", error, eventName);
+		}), { consumerId: Consumer.consumerId });
+		else this.consumers.push(Consumer);
+		return () => {
+			this.unsubscribe(Consumer);
+		};
+	}
+	/**
+	* Unsubscribe the given consumer
+	*/
+	unsubscribe(Consumer) {
+		if (this.isConnected) this.channel(Consumer.eventName).unsubscribeById(Consumer.consumerId);
+		const index = this.consumers.indexOf(Consumer);
+		if (index > -1) this.consumers.splice(index, 1);
+	}
+	/**
+	* Publish the given event message.
+	* Auto-creates the channel if it hasn't been accessed before.
+	*/
+	publish(event) {
+		this.channel(event.eventName).publish(event.serialize());
+	}
+	/**
+	* Connect to RabbitMQ
+	*/
+	async connect() {
+		if (isModuleExists === false) throw new Error(`amqplib is not installed.\n\n${AMQPLIB_INSTALL_INSTRUCTIONS}`);
+		if (isModuleExists === null) {
+			await loadAmqplibModule();
+			if (!isModuleExists) throw new Error(`amqplib is not installed.\n\n${AMQPLIB_INSTALL_INSTRUCTIONS}`);
+		}
+		try {
+			const url = this.buildConnectionUrl();
+			const connectOptions = {
+				heartbeat: this.options.heartbeat ?? 60,
+				timeout: this.options.connectionTimeout,
+				...this.options.clientOptions
+			};
+			this.connection = await amqplibModule.connect(url, connectOptions);
+			this.amqpChannel = await this.connection.createChannel();
+			if (this.options.prefetch) await this.amqpChannel.prefetch(this.options.prefetch);
+			this._isConnected = true;
+			this.events.emit("connected");
+			for (const consumer of this.consumers) this.subscribe(consumer);
+			this.consumers.length = 0;
+			this.connection.on("close", () => {
+				this._isConnected = false;
+				this.events.emit("disconnected");
+				if (this.options.reconnect !== false) this.handleReconnect();
+			});
+			this.connection.on("error", (error) => {
+				this.events.emit("error", error);
+			});
+		} catch (error) {
+			this._isConnected = false;
+			throw new Error(`Failed to connect to RabbitMQ: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	/**
+	* Build connection URL from options
+	*/
+	buildConnectionUrl() {
+		if (this.options.uri) return this.options.uri;
+		const protocol = "amqp";
+		const host = this.options.host ?? "localhost";
+		const port = this.options.port ?? 5672;
+		const vhost = this.options.vhost ?? "/";
+		return `${protocol}://${this.options.username ?? "guest"}:${this.options.password ?? "guest"}@${host}:${port}/${encodeURIComponent(vhost)}`;
+	}
+	/**
+	* Handle reconnection
+	*/
+	async handleReconnect() {
+		const delay = this.options.reconnectDelay ?? 5e3;
+		let attempt = 0;
+		const tryReconnect = async () => {
+			attempt++;
+			this.events.emit("reconnecting", attempt);
+			try {
+				await this.connect();
+			} catch {
+				setTimeout(tryReconnect, delay);
+			}
+		};
+		setTimeout(tryReconnect, delay);
+	}
+	/**
+	* Disconnect from RabbitMQ
+	*/
+	async disconnect() {
+		if (this.amqpChannel) {
+			try {
+				await this.amqpChannel.close();
+			} catch {}
+			this.amqpChannel = null;
+		}
+		if (this.connection) {
+			try {
+				await this.connection.close();
+			} catch {}
+			this.connection = null;
+		}
+		this._isConnected = false;
+		this.events.emit("disconnected");
+	}
+	/**
+	* Register event listener
+	*/
+	on(event, listener) {
+		this.events.on(event, listener);
+	}
+	/**
+	* Remove event listener
+	*/
+	off(event, listener) {
+		this.events.off(event, listener);
+	}
+	/**
+	* Get or create a channel
+	*/
+	channel(name, options) {
+		const existing = this.channels.get(name);
+		if (existing) return existing;
+		const channel = new RabbitMQChannel(name, this.amqpChannel, options);
+		this.channels.set(name, channel);
+		return channel;
+	}
+	/**
+	* Start consuming messages
+	*/
+	async startConsuming() {}
+	/**
+	* Stop consuming messages from all subscribed channels.
+	* Gracefully cancels all active consumers.
+	*/
+	async stopConsuming() {
+		const stops = Array.from(this.channels.values()).map((channel) => channel.stopConsuming());
+		await Promise.all(stops);
+	}
+	/**
+	* Health check
+	*/
+	async healthCheck() {
+		if (!this._isConnected || !this.connection) return {
+			healthy: false,
+			error: "Not connected to RabbitMQ"
+		};
+		const start = Date.now();
+		try {
+			await this.amqpChannel.checkQueue("amq.rabbitmq.reply-to").catch(() => {});
+			return {
+				healthy: true,
+				latency: Date.now() - start
+			};
+		} catch (error) {
+			return {
+				healthy: false,
+				error: error instanceof Error ? error.message : String(error),
+				latency: Date.now() - start
+			};
+		}
+	}
+	/**
+	* Get all channel names
+	*/
+	getChannelNames() {
+		return Array.from(this.channels.keys());
+	}
+	/**
+	* Close a specific channel
+	*/
+	async closeChannel(name) {
+		const channel = this.channels.get(name);
+		if (channel) {
+			await channel.delete();
+			this.channels.delete(name);
+		}
+	}
+	/**
+	* Get the raw AMQP channel (for advanced use)
+	*/
+	getRawChannel() {
+		return this.amqpChannel;
+	}
+	/**
+	* Get the raw connection (for advanced use)
+	*/
+	getRawConnection() {
+		return this.connection;
+	}
+};
+
+//#endregion
+//#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 Promise.resolve().then(() => rabbitmq_driver_exports);
+			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
+//#region ../../@warlock.js/herald/src/decorators/consumable.ts
+const pendingSubscribers = /* @__PURE__ */ new Set();
+/**
+* Register the consumer to the broker
+*/
+function Consumable(options) {
+	return function(target) {
+		const brokerName = options?.broker;
+		try {
+			const currentBroker = brokerRegistry.get(brokerName);
+			if (currentBroker?.isConnected) currentBroker.subscribe(target);
+			else pendingSubscribers.add({
+				Consumer: target,
+				options
+			});
+		} catch {
+			pendingSubscribers.add({
+				Consumer: target,
+				options
+			});
+		}
+	};
+}
+brokerRegistry.on("connected", (broker) => {
+	for (const { Consumer, options } of pendingSubscribers) {
+		if (options?.broker && broker.name !== options.broker) continue;
+		broker.subscribe(Consumer);
+	}
+});
+
+//#endregion
+//#region ../../@warlock.js/herald/src/message-managers/event-consumer.ts
+/**
+* This class is used to be part of the Herald Event Consumer Manager.
+* It should be used to consume events from Either RabbitMQ or Kafka through Herald
+*
+* It's highly recommended using it instead of declaring manual channel namd and subscribing to event
+*/
+var EventConsumer = class {
+	static get consumerId() {
+		if (!this._consumerId) this._consumerId = (0, crypto.randomUUID)();
+		return this._consumerId;
+	}
+	get eventName() {
+		return this.constructor.eventName;
+	}
+	/**
+	* Determine whether this is accepted version to be used by this consumer
+	*/
+	static isAcceptedVersion(version) {
+		if (this.minVersion && version < this.minVersion) return false;
+		if (this.maxVersion && version > this.maxVersion) return false;
+		return true;
+	}
+	/**
+	* Validate the given data
+	*/
+	async validate(data) {
+		if (!this.schema) return;
+		return await _warlock_js_seal.v.validate(this.schema, data);
+	}
+};
+/**
+* A shorthand to define an event consumer without declaring an entire class
+*/
+function defineConsumer(eventName, options) {
+	const Class = class AnnouncedConsumer extends EventConsumer {
+		constructor(..._args) {
+			super(..._args);
+			this.schema = options.schema;
+		}
+		static {
+			this.eventName = eventName;
+		}
+		async handle(payload, event) {
+			if (options.validate) {
+				const result = await options.validate(payload);
+				if (!result || !result.isValid) return;
+			}
+			return options.handle(payload, event);
+		}
+	};
+	Consumable()(Class);
+	return Class;
+}
+
+//#endregion
+//#region ../../@warlock.js/herald/src/message-managers/event-message.ts
+var EventMessage = class {
+	/**
+	* Data that will be sent with the event (Payload)
+	*/
+	toJSON() {
+		if (!this.data) throw new Error(`no Data is defined for Event: ${this.eventName}`);
+		return this.data;
+	}
+	constructor(data) {
+		this.data = data;
+	}
+	/**
+	* Serialize the event to be ready for publishing.
+	* Delegates payload resolution to toJSON() — override toJSON() to customize.
+	*
+	* @throws Error if toJSON() throws (e.g. no data provided)
+	*/
+	serialize() {
+		return {
+			payload: this.toJSON(),
+			metadata: this.metadata,
+			messageId: this.messageId ?? (0, crypto.randomUUID)(),
+			eventName: this.eventName,
+			version: this.version,
+			occurredAt: /* @__PURE__ */ new Date(),
+			__through: "EventMessage"
+		};
+	}
+};
+/**
+* A shorthand to define an event without declaring an entire class.
+*
+* This factory function creates an EventMessage subclass that transforms
+* input data (IncomingData) into a different output format (OutgoingData).
+*
+* @template IncomingData - The type of data passed to the constructor
+* @template OutgoingData - The type of data returned by toJSON()
+*
+* @example
+* ```typescript
+* const UserCreatedEvent = defineEvent<User, { id: number; name: string }>(
+*   "user.created",
+*   { toJSON: (user) => user.only(["id", "name"]) }
+* );
+*
+* publishEvent(new UserCreatedEvent(user));
+* ```
+*/
+function defineEvent(eventName, options = {}) {
+	return class AnnouncedEvent extends EventMessage {
+		constructor(data) {
+			super(data);
+			this.eventName = eventName;
+			this.schema = options.schema;
+		}
+		toJSON() {
+			if (!options.toJSON) return this.data;
+			return options.toJSON(this.data);
+		}
+	};
+}
+
+//#endregion
+//#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
+exports.Broker = Broker;
+exports.Consumable = Consumable;
+exports.EventConsumer = EventConsumer;
+exports.EventMessage = EventMessage;
+exports.MissingBrokerError = MissingBrokerError;
+exports.RabbitMQChannel = RabbitMQChannel;
+exports.RabbitMQDriver = RabbitMQDriver;
+exports.brokerRegistry = brokerRegistry;
+exports.connectToBroker = connectToBroker;
+exports.defineConsumer = defineConsumer;
+exports.defineEvent = defineEvent;
+exports.herald = herald;
+exports.heraldBroadcast = heraldBroadcast;
+exports.heraldChannel = heraldChannel;
+exports.pendingSubscribers = pendingSubscribers;
+exports.publishEvent = publishEvent;
+exports.subscribeConsumer = subscribeConsumer;
+//# sourceMappingURL=index.cjs.map