@warlock.js/herald 4.0.100

package/esm/contracts/channel.contract.d.ts

@@ -0,0 +1,175 @@
+import type { ChannelOptions, ChannelStats, MessageHandler, PublishOptions, RequestOptions, ResponseHandler, Subscription, SubscribeOptions } from "../types";
+/**
+ * Channel contract - represents a queue (RabbitMQ) or topic (Kafka)
+ *
+ * Provides a unified pub/sub interface across different message brokers.
+ *
+ * @template TPayload - The typed payload for messages on this channel
+ *
+ * @example
+ * ```typescript
+ * // Get a typed channel
+ * const userChannel = communicators().channel<UserPayload>("user.created");
+ *
+ * // Publish
+ * await userChannel.publish({ userId: 1, email: "test@example.com" });
+ *
+ * // Subscribe
+ * userChannel.subscribe(async (message, ctx) => {
+ *   console.log(message.payload.userId);
+ *   await ctx.ack();
+ * });
+ * ```
+ */
+export interface ChannelContract<TPayload = unknown> {
+    /**
+     * Channel name/routing key
+     */
+    readonly name: string;
+    /**
+     * Channel options
+     */
+    readonly options: ChannelOptions<TPayload>;
+    /**
+     * Publish a message to this channel
+     *
+     * @param payload - The message payload
+     * @param options - Optional publish options
+     *
+     * @example
+     * ```typescript
+     * await channel.publish({ orderId: 123 });
+     *
+     * // With options
+     * await channel.publish({ orderId: 123 }, {
+     *   priority: 5,
+     *   persistent: true,
+     *   correlationId: "req-123",
+     * });
+     * ```
+     */
+    publish(payload: TPayload, options?: PublishOptions): Promise<void>;
+    /**
+     * Publish multiple messages in a batch
+     *
+     * More efficient than publishing one by one.
+     *
+     * @param messages - Array of payloads to publish
+     * @param options - Optional publish options (applied to all messages)
+     *
+     * @example
+     * ```typescript
+     * await channel.publishBatch([
+     *   { event: "page_view", page: "/home" },
+     *   { event: "page_view", page: "/products" },
+     * ]);
+     * ```
+     */
+    publishBatch(messages: TPayload[], options?: PublishOptions): Promise<void>;
+    /**
+     * Subscribe to messages on this channel
+     *
+     * @param handler - Function to handle incoming messages
+     * @param options - Optional subscribe options
+     * @returns Subscription object for managing the subscription
+     *
+     * @example
+     * ```typescript
+     * const subscription = await channel.subscribe(
+     *   async (message, ctx) => {
+     *     await processOrder(message.payload);
+     *     await ctx.ack();
+     *   },
+     *   {
+     *     prefetch: 10,
+     *     retry: { maxRetries: 3, delay: 1000 },
+     *   }
+     * );
+     *
+     * // Later: unsubscribe
+     * await subscription.unsubscribe();
+     * ```
+     */
+    subscribe(handler: MessageHandler<TPayload>, options?: SubscribeOptions): Promise<Subscription>;
+    /**
+     * Request-Response pattern (RPC)
+     *
+     * Publishes a message and waits for a response.
+     *
+     * @param payload - The request payload
+     * @param options - Request options including timeout
+     * @returns Promise resolving to the response
+     *
+     * @example
+     * ```typescript
+     * const result = await channel.request<ProcessResult>(
+     *   { imageUrl: "https://..." },
+     *   { timeout: 30000 }
+     * );
+     * console.log(result.processedUrl);
+     * ```
+     */
+    request<TResponse = unknown>(payload: TPayload, options?: RequestOptions): Promise<TResponse>;
+    /**
+     * Register a response handler for RPC pattern
+     *
+     * The return value of the handler becomes the response.
+     *
+     * @param handler - Function to handle requests and return responses
+     * @returns Subscription for managing the responder
+     *
+     * @example
+     * ```typescript
+     * channel.respond(async (message, ctx) => {
+     *   const result = await processImage(message.payload);
+     *   return { processedUrl: result.url };
+     * });
+     * ```
+     */
+    respond<TResponse = unknown>(handler: ResponseHandler<TPayload, TResponse>): Promise<Subscription>;
+    /**
+     * Get channel statistics
+     *
+     * @returns Channel stats including message count and consumer count
+     *
+     * @example
+     * ```typescript
+     * const stats = await channel.stats();
+     * console.log(`Messages: ${stats.messageCount}, Consumers: ${stats.consumerCount}`);
+     * ```
+     */
+    stats(): Promise<ChannelStats>;
+    /**
+     * Purge all messages from the channel
+     *
+     * Use with caution - this deletes all pending messages.
+     *
+     * @returns Number of messages purged
+     *
+     * @example
+     * ```typescript
+     * const purgedCount = await channel.purge();
+     * console.log(`Purged ${purgedCount} messages`);
+     * ```
+     */
+    purge(): Promise<number>;
+    /**
+     * Check if the channel exists
+     *
+     * @returns True if the channel exists on the broker
+     */
+    exists(): Promise<boolean>;
+    /**
+     * Delete the channel
+     *
+     * Use with caution - this removes the queue/topic entirely.
+     */
+    delete(): Promise<void>;
+    /**
+     * Assert/create the channel with its options
+     *
+     * Creates the channel if it doesn't exist, or verifies options match.
+     */
+    assert(): Promise<void>;
+}
+//# sourceMappingURL=channel.contract.d.ts.map

package/esm/contracts/channel.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.contract.d.ts","sourceRoot":"","sources":["../../src/contracts/channel.contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EAEZ,cAAc,EACd,cAAc,EACd,cAAc,EACd,eAAe,EACf,YAAY,EACZ,gBAAgB,EACjB,MAAM,UAAU,CAAC;AAElB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,eAAe,CAAC,QAAQ,GAAG,OAAO;IACjD;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;IAE3C;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpE;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,QAAQ,EAAE,QAAQ,EAAE,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5E;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,SAAS,CAAC,OAAO,EAAE,cAAc,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAEhG;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,SAAS,GAAG,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAE9F;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,SAAS,GAAG,OAAO,EAAE,OAAO,EAAE,eAAe,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAEnG;;;;;;;;;;OAUG;IACH,KAAK,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC;IAE/B;;;;;;;;;;;;OAYG;IACH,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAEzB;;;;OAIG;IACH,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAE3B;;;;OAIG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAExB;;;;OAIG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB"}

package/esm/contracts/communicator-driver.contract.d.ts

@@ -0,0 +1,168 @@
+import type { ChannelContract } from "./channel.contract";
+import type { ChannelOptions, CommunicatorEvent, CommunicatorEventListener, CommunicatorDriverType, HealthCheckResult } from "../types";
+/**
+ * Communicator Driver Contract
+ *
+ * Base contract for all message bus drivers (RabbitMQ, Kafka, etc.)
+ * Similar to DriverContract in @warlock.js/cascade
+ *
+ * @example
+ * ```typescript
+ * // Driver implementation
+ * class RabbitMQDriver implements CommunicatorDriverContract {
+ *   readonly name = "rabbitmq";
+ *   // ...
+ * }
+ * ```
+ */
+export interface CommunicatorDriverContract {
+    /**
+     * Driver name identifier
+     *
+     * @example "rabbitmq", "kafka", "redis-streams"
+     */
+    readonly name: CommunicatorDriverType;
+    /**
+     * Whether currently connected to the message broker
+     */
+    readonly isConnected: boolean;
+    /**
+     * Establish connection to the message broker
+     *
+     * @throws Error if connection fails
+     *
+     * @example
+     * ```typescript
+     * await driver.connect();
+     * console.log("Connected to RabbitMQ");
+     * ```
+     */
+    connect(): Promise<void>;
+    /**
+     * Close connection gracefully
+     *
+     * Ensures all pending operations complete before disconnecting.
+     *
+     * @example
+     * ```typescript
+     * await driver.disconnect();
+     * ```
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Register event listeners for driver lifecycle events
+     *
+     * @param event - Event name to listen for
+     * @param listener - Callback function
+     *
+     * @example
+     * ```typescript
+     * driver.on("connected", () => {
+     *   console.log("Connected to broker");
+     * });
+     *
+     * driver.on("disconnected", () => {
+     *   console.log("Disconnected from broker");
+     * });
+     *
+     * driver.on("error", (error) => {
+     *   console.error("Driver error:", error);
+     * });
+     *
+     * driver.on("reconnecting", (attempt) => {
+     *   console.log(`Reconnection attempt ${attempt}`);
+     * });
+     * ```
+     */
+    on(event: CommunicatorEvent, listener: CommunicatorEventListener): void;
+    /**
+     * Remove an event listener
+     *
+     * @param event - Event name
+     * @param listener - Callback to remove
+     */
+    off(event: CommunicatorEvent, listener: CommunicatorEventListener): void;
+    /**
+     * Get or create a channel
+     *
+     * Channels are lazy-created and cached for reuse.
+     *
+     * @param name - Channel/queue/topic name
+     * @param options - Channel configuration
+     * @returns Channel instance
+     *
+     * @example
+     * ```typescript
+     * // Simple channel
+     * const channel = driver.channel("user.created");
+     *
+     * // With options
+     * const orderChannel = driver.channel("orders", {
+     *   durable: true,
+     *   deadLetter: { channel: "orders.failed" },
+     * });
+     *
+     * // Typed channel
+     * const typedChannel = driver.channel<OrderPayload>("orders", {
+     *   schema: OrderSchema,
+     * });
+     * ```
+     */
+    channel<TPayload = unknown>(name: string, options?: ChannelOptions<TPayload>): ChannelContract<TPayload>;
+    /**
+     * Start consuming messages from all subscribed channels
+     *
+     * Call this after setting up all subscriptions to begin processing.
+     *
+     * @example
+     * ```typescript
+     * // Set up subscriptions
+     * channel1.subscribe(handler1);
+     * channel2.subscribe(handler2);
+     *
+     * // Start consuming
+     * await driver.startConsuming();
+     * ```
+     */
+    startConsuming(): Promise<void>;
+    /**
+     * Stop consuming messages gracefully
+     *
+     * Waits for currently processing messages to complete.
+     *
+     * @example
+     * ```typescript
+     * await driver.stopConsuming();
+     * ```
+     */
+    stopConsuming(): Promise<void>;
+    /**
+     * Perform a health check on the connection
+     *
+     * @returns Health check result with status and optional latency
+     *
+     * @example
+     * ```typescript
+     * const health = await driver.healthCheck();
+     * if (health.healthy) {
+     *   console.log(`Healthy, latency: ${health.latency}ms`);
+     * } else {
+     *   console.error(`Unhealthy: ${health.error}`);
+     * }
+     * ```
+     */
+    healthCheck(): Promise<HealthCheckResult>;
+    /**
+     * Get list of all channels managed by this driver
+     *
+     * @returns Array of channel names
+     */
+    getChannelNames(): string[];
+    /**
+     * Close and remove a specific channel
+     *
+     * @param name - Channel name to close
+     */
+    closeChannel(name: string): Promise<void>;
+}
+//# sourceMappingURL=communicator-driver.contract.d.ts.map

package/esm/contracts/communicator-driver.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"communicator-driver.contract.d.ts","sourceRoot":"","sources":["../../src/contracts/communicator-driver.contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,yBAAyB,EACzB,sBAAsB,EACtB,iBAAiB,EAClB,MAAM,UAAU,CAAC;AAElB;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IAEtC;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAE9B;;;;;;;;;;OAUG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzB;;;;;;;;;OASG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,EAAE,CAAC,KAAK,EAAE,iBAAiB,EAAE,QAAQ,EAAE,yBAAyB,GAAG,IAAI,CAAC;IAExE;;;;;OAKG;IACH,GAAG,CAAC,KAAK,EAAE,iBAAiB,EAAE,QAAQ,EAAE,yBAAyB,GAAG,IAAI,CAAC;IAEzE;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,OAAO,CAAC,QAAQ,GAAG,OAAO,EACxB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC,GACjC,eAAe,CAAC,QAAQ,CAAC,CAAC;IAE7B;;;;;;;;;;;;;;OAcG;IACH,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhC;;;;;;;;;OASG;IACH,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/B;;;;;;;;;;;;;;OAcG;IACH,WAAW,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAE1C;;;;OAIG;IACH,eAAe,IAAI,MAAM,EAAE,CAAC;IAE5B;;;;OAIG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C"}

package/esm/contracts/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./channel.contract";
+export * from "./communicator-driver.contract";
+//# sourceMappingURL=index.d.ts.map

package/esm/contracts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contracts/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,gCAAgC,CAAC"}

package/esm/drivers/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./rabbitmq";
+//# sourceMappingURL=index.d.ts.map

package/esm/drivers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/drivers/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC"}

package/esm/drivers/rabbitmq/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./rabbitmq-driver";
+export * from "./rabbitmq-channel";
+//# sourceMappingURL=index.d.ts.map

package/esm/drivers/rabbitmq/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/drivers/rabbitmq/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC"}

package/esm/drivers/rabbitmq/rabbitmq-channel.d.ts

@@ -0,0 +1,70 @@
+import type { ChannelContract } from "../../contracts";
+import type { ChannelOptions, ChannelStats, MessageHandler, PublishOptions, RequestOptions, ResponseHandler, SubscribeOptions, Subscription } from "../../types";
+/**
+ * RabbitMQ Channel Implementation
+ *
+ * Wraps a RabbitMQ queue/exchange with a unified API.
+ *
+ * @template TPayload - The typed payload
+ */
+export declare class RabbitMQChannel<TPayload = unknown> implements ChannelContract<TPayload> {
+    readonly name: string;
+    readonly options: ChannelOptions<TPayload>;
+    private readonly amqpChannel;
+    private readonly subscriptions;
+    private asserted;
+    /**
+     * Create a new RabbitMQ channel
+     */
+    constructor(name: string, amqpChannel: any, options?: ChannelOptions<TPayload>);
+    /**
+     * Assert the queue exists
+     */
+    assert(): Promise<void>;
+    /**
+     * Publish a message
+     */
+    publish(payload: TPayload, options?: PublishOptions): Promise<void>;
+    /**
+     * Publish multiple messages
+     */
+    publishBatch(messages: TPayload[], options?: PublishOptions): Promise<void>;
+    /**
+     * 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
+     */
+    subscribe(handler: MessageHandler<TPayload>, options?: SubscribeOptions): Promise<Subscription>;
+    /**
+     * Send message to dead-letter queue
+     */
+    private sendToDeadLetter;
+    /**
+     * Request-response pattern
+     */
+    request<TResponse = unknown>(payload: TPayload, options?: RequestOptions): Promise<TResponse>;
+    /**
+     * Register response handler for RPC
+     */
+    respond<TResponse = unknown>(handler: ResponseHandler<TPayload, TResponse>): Promise<Subscription>;
+    /**
+     * Get queue statistics
+     */
+    stats(): Promise<ChannelStats>;
+    /**
+     * Purge all messages
+     */
+    purge(): Promise<number>;
+    /**
+     * Check if queue exists
+     */
+    exists(): Promise<boolean>;
+    /**
+     * Delete the queue
+     */
+    delete(): Promise<void>;
+}
+//# sourceMappingURL=rabbitmq-channel.d.ts.map

package/esm/drivers/rabbitmq/rabbitmq-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rabbitmq-channel.d.ts","sourceRoot":"","sources":["../../../src/drivers/rabbitmq/rabbitmq-channel.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EAGZ,cAAc,EAEd,cAAc,EACd,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,YAAY,EACb,MAAM,aAAa,CAAC;AAErB;;;;;;GAMG;AACH,qBAAa,eAAe,CAAC,QAAQ,GAAG,OAAO,CAAE,YAAW,eAAe,CAAC,QAAQ,CAAC;IACnF,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,OAAO,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;IAElD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAM;IAClC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA2C;IACzE,OAAO,CAAC,QAAQ,CAAS;IAEzB;;OAEG;gBACgB,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC;IAMrF;;OAEG;IACU,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBpC;;OAEG;IACU,OAAO,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAkDhF;;OAEG;IACU,YAAY,CAAC,QAAQ,EAAE,QAAQ,EAAE,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxF;;;;;;;OAOG;IACU,SAAS,CACpB,OAAO,EAAE,cAAc,CAAC,QAAQ,CAAC,EACjC,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,YAAY,CAAC;IAmLxB;;OAEG;YACW,gBAAgB;IAe9B;;OAEG;IACU,OAAO,CAAC,SAAS,GAAG,OAAO,EACtC,OAAO,EAAE,QAAQ,EACjB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,SAAS,CAAC;IAiDrB;;OAEG;IACU,OAAO,CAAC,SAAS,GAAG,OAAO,EACtC,OAAO,EAAE,eAAe,CAAC,QAAQ,EAAE,SAAS,CAAC,GAC5C,OAAO,CAAC,YAAY,CAAC;IAQxB;;OAEG;IACU,KAAK,IAAI,OAAO,CAAC,YAAY,CAAC;IAY3C;;OAEG;IACU,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAOrC;;OAEG;IACU,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC;IASvC;;OAEG;IACU,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAerC"}