@warlock.js/herald 4.0.100

package/esm/types.d.ts

@@ -0,0 +1,396 @@
+/// <reference types="node" />
+import type { BaseValidator } from "@warlock.js/seal";
+/**
+ * Message metadata that accompanies every message
+ */
+export type MessageMetadata = {
+    /** Unique message ID (auto-generated) */
+    messageId: string;
+    /** Correlation ID for request-response patterns */
+    correlationId?: string;
+    /** Reply-to channel for RPC patterns */
+    replyTo?: string;
+    /** Message priority (0-9, where 9 is highest) */
+    priority?: number;
+    /** Timestamp when message was published */
+    timestamp: Date;
+    /** Custom headers */
+    headers?: Record<string, string>;
+    /** Retry count (incremented on each retry) */
+    retryCount?: number;
+    /** Original queue/channel name */
+    originalChannel?: string;
+};
+/**
+ * A message received from a channel
+ *
+ * @template TPayload - The typed payload
+ */
+export type Message<TPayload = unknown> = {
+    /** Message metadata */
+    readonly metadata: MessageMetadata;
+    /** Typed payload data */
+    readonly payload: TPayload;
+    /** Raw message data from the driver */
+    readonly raw?: unknown;
+};
+/**
+ * Options when publishing a message
+ */
+export type PublishOptions = {
+    /** Message priority (0-9, where 9 is highest) */
+    priority?: number;
+    /** Time-to-live in milliseconds */
+    ttl?: number;
+    /** Delay before message is available (delayed messaging) */
+    delay?: number;
+    /** Custom headers */
+    headers?: Record<string, string>;
+    /** Enable message persistence (survives broker restart) */
+    persistent?: boolean;
+    /** Correlation ID for tracking related messages */
+    correlationId?: string;
+    /** Expiration time in milliseconds */
+    expiration?: number;
+};
+/**
+ * Retry configuration for failed message processing
+ */
+export type RetryOptions = {
+    /** Maximum number of retry attempts */
+    maxRetries: number;
+    /** Delay between retries in ms, or function for custom backoff */
+    delay: number | ((attempt: number) => number);
+};
+/**
+ * Dead-letter configuration for messages that exceed retry attempts
+ */
+export type DeadLetterOptions = {
+    /** Dead-letter queue/channel name */
+    channel: string;
+    /** Whether to preserve original message metadata */
+    preserveOriginal?: boolean;
+};
+/**
+ * Options when subscribing to a channel
+ */
+export type SubscribeOptions = {
+    /** Consumer group/tag name */
+    group?: string;
+    /** Number of messages to prefetch (concurrency) */
+    prefetch?: number;
+    /** Auto-acknowledge messages (default: false for manual ack) */
+    autoAck?: boolean;
+    /** Retry configuration for failed messages */
+    retry?: RetryOptions;
+    /** Dead-letter configuration */
+    deadLetter?: DeadLetterOptions;
+    /** Exclusive consumer (only one consumer on this queue) */
+    exclusive?: boolean;
+};
+/**
+ * Options for request-response (RPC) pattern
+ */
+export type RequestOptions = PublishOptions & {
+    /** Timeout in milliseconds to wait for response */
+    timeout?: number;
+};
+/**
+ * Context provided to message handlers for controlling message flow
+ */
+export type MessageContext = {
+    /** Acknowledge the message (mark as successfully processed) */
+    ack(): Promise<void>;
+    /** Negative acknowledge (requeue or send to dead-letter) */
+    nack(requeue?: boolean): Promise<void>;
+    /** Reject the message (don't requeue) */
+    reject(): Promise<void>;
+    /** Reply to a message (for RPC patterns) */
+    reply<T>(payload: T): Promise<void>;
+    /** Manually retry the message with optional delay */
+    retry(delay?: number): Promise<void>;
+};
+/**
+ * Represents an active subscription to a channel
+ */
+export type Subscription = {
+    /** Unique subscription ID */
+    readonly id: string;
+    /** Channel name this subscription is for */
+    readonly channel: string;
+    /** Consumer tag (driver-specific identifier) */
+    readonly consumerTag?: string;
+    /** Unsubscribe from the channel */
+    unsubscribe(): Promise<void>;
+    /** Pause message consumption */
+    pause(): Promise<void>;
+    /** Resume message consumption */
+    resume(): Promise<void>;
+    /** Check if subscription is active */
+    isActive(): boolean;
+};
+/**
+ * Handler function for processing messages
+ *
+ * @template TPayload - The typed payload
+ */
+export type MessageHandler<TPayload = unknown> = (message: Message<TPayload>, ctx: MessageContext) => Promise<void> | void;
+/**
+ * Handler function for request-response (RPC) pattern
+ *
+ * @template TPayload - The request payload type
+ * @template TResponse - The response payload type
+ */
+export type ResponseHandler<TPayload = unknown, TResponse = unknown> = (message: Message<TPayload>, ctx: MessageContext) => Promise<TResponse> | TResponse;
+/**
+ * Channel/queue configuration options
+ */
+export type ChannelOptions<TPayload = unknown> = {
+    /** Channel type (queue for point-to-point, topic for pub/sub, fanout for broadcast) */
+    type?: "queue" | "topic" | "fanout";
+    /** Durable channel (survives broker restart) */
+    durable?: boolean;
+    /** Auto-delete when last consumer disconnects */
+    autoDelete?: boolean;
+    /** Exclusive channel (single connection only) */
+    exclusive?: boolean;
+    /** Dead-letter configuration */
+    deadLetter?: DeadLetterOptions;
+    /** Maximum message size in bytes */
+    maxMessageSize?: number;
+    /** Default message TTL in milliseconds */
+    messageTtl?: number;
+    /** Maximum number of messages in queue */
+    maxLength?: number;
+    /** Seal schema for validation */
+    schema?: BaseValidator;
+};
+/**
+ * Statistics for a channel
+ */
+export type ChannelStats = {
+    /** Number of messages in the queue */
+    messageCount: number;
+    /** Number of active consumers */
+    consumerCount: number;
+    /** Channel name */
+    name: string;
+};
+/**
+ * Supported communicator driver types
+ */
+export type CommunicatorDriverType = "rabbitmq" | "kafka" | "redis-streams" | "sqs";
+/**
+ * Events emitted by communicator drivers
+ */
+export type CommunicatorEvent = "connected" | "disconnected" | "error" | "reconnecting";
+/**
+ * Listener function for communicator events
+ */
+export type CommunicatorEventListener = (...args: unknown[]) => void;
+/**
+ * Result of a health check
+ */
+export type HealthCheckResult = {
+    /** Whether the communicator is healthy */
+    healthy: boolean;
+    /** Latency in milliseconds */
+    latency?: number;
+    /** Error message if unhealthy */
+    error?: string;
+    /** Additional details */
+    details?: Record<string, unknown>;
+};
+/**
+ * Base connection options shared across all drivers
+ */
+export type BaseConnectionOptions = {
+    /** Unique name for this communicator */
+    name?: string;
+    /** Whether this should be the default communicator */
+    isDefault?: boolean;
+};
+/**
+ * Native amqplib socket options
+ * These are passed directly to the underlying socket connection
+ */
+export type RabbitMQSocketOptions = {
+    /** Keep-alive delay in milliseconds */
+    keepAlive?: boolean | number;
+    /** Disable Nagle's algorithm */
+    noDelay?: boolean;
+    /** Socket timeout in milliseconds */
+    timeout?: number;
+    /** Custom certificate authority (for TLS) */
+    ca?: string | Buffer | Array<string | Buffer>;
+    /** Client certificate (for TLS) */
+    cert?: string | Buffer;
+    /** Client private key (for TLS) */
+    key?: string | Buffer;
+    /** Passphrase for the private key */
+    passphrase?: string;
+    /** Server name for SNI (TLS) */
+    servername?: string;
+    /** Reject unauthorized certificates (default: true) */
+    rejectUnauthorized?: boolean;
+};
+/**
+ * RabbitMQ client options (native amqplib options)
+ * These are passed directly to amqplib.connect()
+ */
+export type RabbitMQClientOptions = {
+    /** Frame max size in bytes */
+    frameMax?: number;
+    /** Channel max (0 = unlimited) */
+    channelMax?: number;
+    /** Locale (default: 'en_US') */
+    locale?: string;
+    /** Socket options for the underlying connection */
+    socket?: RabbitMQSocketOptions;
+};
+/**
+ * RabbitMQ-specific connection options
+ *
+ * @template TClientOptions - Native amqplib client options
+ *
+ * @example
+ * ```typescript
+ * const config: RabbitMQConnectionOptions = {
+ *   driver: "rabbitmq",
+ *   host: "localhost",
+ *   port: 5672,
+ *   username: "guest",
+ *   password: "guest",
+ *
+ *   // Native amqplib options
+ *   clientOptions: {
+ *     frameMax: 0,
+ *     channelMax: 0,
+ *     socket: {
+ *       keepAlive: true,
+ *       noDelay: true,
+ *     },
+ *   },
+ * };
+ * ```
+ */
+export type RabbitMQConnectionOptions<TClientOptions extends RabbitMQClientOptions = RabbitMQClientOptions> = BaseConnectionOptions & {
+    driver: "rabbitmq";
+    /** Host address */
+    host?: string;
+    /** Port number */
+    port?: number;
+    /** Username for authentication */
+    username?: string;
+    /** Password for authentication */
+    password?: string;
+    /** Virtual host */
+    vhost?: string;
+    /** Connection URI (alternative to host/port) */
+    uri?: string;
+    /** Heartbeat interval in seconds */
+    heartbeat?: number;
+    /** Connection timeout in milliseconds */
+    connectionTimeout?: number;
+    /** Enable automatic reconnection */
+    reconnect?: boolean;
+    /** Delay between reconnection attempts in milliseconds */
+    reconnectDelay?: number;
+    /** Default prefetch count for consumers */
+    prefetch?: number;
+    /**
+     * Native amqplib client options
+     *
+     * These options are passed directly to amqplib.connect()
+     * for low-level configuration like frame size, TLS, etc.
+     */
+    clientOptions?: TClientOptions;
+};
+/**
+ * Kafka client options (native kafkajs options)
+ */
+export type KafkaClientOptions = {
+    /** Retry configuration */
+    retry?: {
+        initialRetryTime?: number;
+        retries?: number;
+        maxRetryTime?: number;
+        factor?: number;
+        multiplier?: number;
+    };
+    /** Log level */
+    logLevel?: number;
+    /** Custom logger */
+    logCreator?: any;
+};
+/**
+ * Kafka-specific connection options
+ *
+ * @template TClientOptions - Native kafkajs client options
+ */
+export type KafkaConnectionOptions<TClientOptions extends KafkaClientOptions = KafkaClientOptions> = BaseConnectionOptions & {
+    driver: "kafka";
+    /** Broker addresses */
+    brokers: string[];
+    /** Client ID */
+    clientId?: string;
+    /** Connection timeout in milliseconds */
+    connectionTimeout?: number;
+    /** Request timeout in milliseconds */
+    requestTimeout?: number;
+    /** SSL configuration */
+    ssl?: boolean | object;
+    /** SASL authentication */
+    sasl?: {
+        mechanism: "plain" | "scram-sha-256" | "scram-sha-512";
+        username: string;
+        password: string;
+    };
+    /**
+     * Native kafkajs client options
+     */
+    clientOptions?: TClientOptions;
+};
+/**
+ * Union type for all connection options
+ */
+export type ConnectionOptions = RabbitMQConnectionOptions | KafkaConnectionOptions;
+/**
+ * Communicator configuration options
+ *
+ * This is the main type for configuring communicators in your application.
+ * Similar to ConnectionOptions in @warlock.js/cascade.
+ *
+ * @template TClientOptions - Native client options (amqplib, kafkajs, etc.)
+ *
+ * @example
+ * ```typescript
+ * // RabbitMQ with client options
+ * const config: CommunicatorConfigurations<RabbitMQClientOptions> = {
+ *   driver: "rabbitmq",
+ *   host: "localhost",
+ *   clientOptions: {
+ *     socket: { keepAlive: true },
+ *   },
+ * };
+ *
+ * // Kafka
+ * const kafkaConfig: CommunicatorConfigurations<KafkaClientOptions> = {
+ *   driver: "kafka",
+ *   brokers: ["localhost:9092"],
+ *   clientOptions: {
+ *     retry: { retries: 5 },
+ *   },
+ * };
+ * ```
+ */
+export type CommunicatorConfigurations<TClientOptions = any> = RabbitMQConnectionOptions<TClientOptions extends RabbitMQClientOptions ? TClientOptions : RabbitMQClientOptions> | KafkaConnectionOptions<TClientOptions extends KafkaClientOptions ? TClientOptions : KafkaClientOptions>;
+/**
+ * Events emitted by the communicator registry
+ */
+export type CommunicatorRegistryEvent = "registered" | "default-registered" | "connected" | "disconnected";
+/**
+ * Listener for registry events
+ */
+export type CommunicatorRegistryListener = (communicator: unknown) => void;
+//# sourceMappingURL=types.d.ts.map

package/esm/types.d.ts.map

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

package/esm/utils/connect-to-communicator.d.ts

@@ -0,0 +1,86 @@
+import { Communicator } from "../communicators";
+import type { ConnectionOptions } from "../types";
+/**
+ * Connect to a message broker and register the communicator.
+ *
+ * This is a high-level utility function that simplifies connection setup
+ * for most projects. It handles driver instantiation, connection,
+ * communicator 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 Communicator instance
+ * @throws {Error} If connection fails or driver is not implemented
+ *
+ * @example
+ * ```typescript
+ * // RabbitMQ connection
+ * const communicator = await connectToCommunicator({
+ *   driver: "rabbitmq",
+ *   host: "localhost",
+ *   port: 5672,
+ *   username: "guest",
+ *   password: "guest",
+ * });
+ *
+ * // Use the communicator
+ * await communicator.channel("user.created").publish({ userId: 1 });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Multiple communicators
+ * await connectToCommunicator({
+ *   driver: "rabbitmq",
+ *   name: "notifications",
+ *   isDefault: true,
+ *   host: process.env.RABBITMQ_HOST,
+ * });
+ *
+ * await connectToCommunicator({
+ *   driver: "rabbitmq",
+ *   name: "analytics",
+ *   host: process.env.ANALYTICS_RABBITMQ_HOST,
+ * });
+ *
+ * // Use default communicator
+ * communicators().channel("notifications").publish({ ... });
+ *
+ * // Use specific communicator
+ * communicators("analytics").channel("events").publish({ ... });
+ * ```
+ */
+export declare function connectToCommunicator(options: ConnectionOptions): Promise<Communicator>;
+/**
+ * Get a communicator by name or the default one.
+ *
+ * This is the main entry point for using communicators in your application.
+ *
+ * @param name - Optional communicator name (uses default if not provided)
+ * @returns Communicator instance
+ * @throws MissingCommunicatorError if communicator not found
+ *
+ * @example
+ * ```typescript
+ * // Get default communicator
+ * const channel = communicators().channel("user.created");
+ * await channel.publish({ userId: 1 });
+ *
+ * // Get specific communicator
+ * const analyticsChannel = communicators("analytics").channel("events");
+ * await analyticsChannel.publish({ event: "page_view" });
+ *
+ * // Subscribe to messages
+ * communicators()
+ *   .channel<UserPayload>("user.created")
+ *   .subscribe(async (message, ctx) => {
+ *     console.log("User created:", message.payload);
+ *     await ctx.ack();
+ *   });
+ * ```
+ */
+export declare function communicators(name?: string): Communicator;
+//# sourceMappingURL=connect-to-communicator.d.ts.map

package/esm/utils/connect-to-communicator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect-to-communicator.d.ts","sourceRoot":"","sources":["../../src/utils/connect-to-communicator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAwB,MAAM,kBAAkB,CAAC;AAEtE,OAAO,KAAK,EAAE,iBAAiB,EAA6B,MAAM,UAAU,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,CAAC,CA+C7F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,aAAa,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,YAAY,CAEzD"}

package/esm/utils/connect-to-communicator.js

@@ -0,0 +1,122 @@
+import {communicatorRegistry}from'../communicators/communicator-registry.js';/**
+ * Connect to a message broker and register the communicator.
+ *
+ * This is a high-level utility function that simplifies connection setup
+ * for most projects. It handles driver instantiation, connection,
+ * communicator 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 Communicator instance
+ * @throws {Error} If connection fails or driver is not implemented
+ *
+ * @example
+ * ```typescript
+ * // RabbitMQ connection
+ * const communicator = await connectToCommunicator({
+ *   driver: "rabbitmq",
+ *   host: "localhost",
+ *   port: 5672,
+ *   username: "guest",
+ *   password: "guest",
+ * });
+ *
+ * // Use the communicator
+ * await communicator.channel("user.created").publish({ userId: 1 });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Multiple communicators
+ * await connectToCommunicator({
+ *   driver: "rabbitmq",
+ *   name: "notifications",
+ *   isDefault: true,
+ *   host: process.env.RABBITMQ_HOST,
+ * });
+ *
+ * await connectToCommunicator({
+ *   driver: "rabbitmq",
+ *   name: "analytics",
+ *   host: process.env.ANALYTICS_RABBITMQ_HOST,
+ * });
+ *
+ * // Use default communicator
+ * communicators().channel("notifications").publish({ ... });
+ *
+ * // Use specific communicator
+ * communicators("analytics").channel("events").publish({ ... });
+ * ```
+ */
+async function connectToCommunicator(options) {
+    // Default values
+    const driverType = options.driver ?? "rabbitmq";
+    const communicatorName = options.name ?? "default";
+    const isDefault = options.isDefault ?? true;
+    // Create driver based on type
+    let driver;
+    switch (driverType) {
+        case "rabbitmq": {
+            const rabbitOptions = options;
+            // Dynamic import to avoid requiring amqplib if not used
+            const { RabbitMQDriver } = await import('../drivers/rabbitmq/rabbitmq-driver.js');
+            driver = new RabbitMQDriver(rabbitOptions);
+            break;
+        }
+        case "kafka": {
+            // const kafkaOptions = options as KafkaConnectionOptions;
+            // Dynamic import to avoid requiring kafkajs if not used
+            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`);
+    }
+    // Create communicator
+    const communicator = communicatorRegistry.register({
+        name: communicatorName,
+        driver,
+        isDefault,
+    });
+    // Connect to the message broker
+    try {
+        await driver.connect();
+    }
+    catch (error) {
+        throw new Error(`Failed to connect to ${driverType}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return communicator;
+}
+/**
+ * Get a communicator by name or the default one.
+ *
+ * This is the main entry point for using communicators in your application.
+ *
+ * @param name - Optional communicator name (uses default if not provided)
+ * @returns Communicator instance
+ * @throws MissingCommunicatorError if communicator not found
+ *
+ * @example
+ * ```typescript
+ * // Get default communicator
+ * const channel = communicators().channel("user.created");
+ * await channel.publish({ userId: 1 });
+ *
+ * // Get specific communicator
+ * const analyticsChannel = communicators("analytics").channel("events");
+ * await analyticsChannel.publish({ event: "page_view" });
+ *
+ * // Subscribe to messages
+ * communicators()
+ *   .channel<UserPayload>("user.created")
+ *   .subscribe(async (message, ctx) => {
+ *     console.log("User created:", message.payload);
+ *     await ctx.ack();
+ *   });
+ * ```
+ */
+function communicators(name) {
+    return communicatorRegistry.get(name);
+}export{communicators,connectToCommunicator};//# sourceMappingURL=connect-to-communicator.js.map

package/esm/utils/connect-to-communicator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect-to-communicator.js","sources":["../../src/utils/connect-to-communicator.ts"],"sourcesContent":[null],"names":[],"mappings":"6EAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoDG;AACI,eAAe,qBAAqB,CAAC,OAA0B,EAAA;;AAEpE,IAAA,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,IAAI,UAAU,CAAC;AAChD,IAAA,MAAM,gBAAgB,GAAG,OAAO,CAAC,IAAI,IAAI,SAAS,CAAC;AACnD,IAAA,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC;;AAG5C,IAAA,IAAI,MAAkC,CAAC;AAEvC,IAAA,QAAQ,UAAU;QAChB,KAAK,UAAU,EAAE;YACf,MAAM,aAAa,GAAG,OAAoC,CAAC;;YAE3D,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,OAAO,wCAAqC,CAAC,CAAC;AAC/E,YAAA,MAAM,GAAG,IAAI,cAAc,CAAC,aAAa,CAAC,CAAC;YAC3C,MAAM;AACP,SAAA;QAED,KAAK,OAAO,EAAE;;;AAGZ,YAAA,MAAM,IAAI,KAAK,CACb,iFAAiF,CAClF,CAAC;AACH,SAAA;AAED,QAAA;AACE,YAAA,MAAM,IAAI,KAAK,CAAC,oBAAoB,UAAU,CAAA,qCAAA,CAAuC,CAAC,CAAC;AAC1F,KAAA;;AAGD,IAAA,MAAM,YAAY,GAAG,oBAAoB,CAAC,QAAQ,CAAC;AACjD,QAAA,IAAI,EAAE,gBAAgB;QACtB,MAAM;QACN,SAAS;AACV,KAAA,CAAC,CAAC;;IAGH,IAAI;AACF,QAAA,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;AACxB,KAAA;AAAC,IAAA,OAAO,KAAK,EAAE;QACd,MAAM,IAAI,KAAK,CACb,CAAwB,qBAAA,EAAA,UAAU,KAAK,KAAK,YAAY,KAAK,GAAG,KAAK,CAAC,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAE,CAAA,CAChG,CAAC;AACH,KAAA;AAED,IAAA,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BG;AACG,SAAU,aAAa,CAAC,IAAa,EAAA;AACzC,IAAA,OAAO,oBAAoB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACxC"}

package/esm/utils/index.d.ts

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

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

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

package/package.json

@@ -0,0 +1,47 @@
+{
+    "name": "@warlock.js/herald",
+    "version": "4.0.100",
+    "description": "Message bus/communicators for RabbitMQ, Kafka, and more",
+    "main": "./cjs/index.js",
+    "dependencies": {
+        "@mongez/copper": "^1.0.1",
+        "@mongez/events": "^2.1.0",
+        "@mongez/reinforcements": "^2.3.17",
+        "@warlock.js/logger": "4.0.100",
+        "@warlock.js/seal": "4.0.100"
+    },
+    "scripts": {
+        "update": "npx ncu -u",
+        "fix": "eslint --fix -c ./.eslintrc.json ./src",
+        "format": "prettier --write ./src/**/*.{js,jsx,ts,tsx,css,md,json} --config ./.prettierrc.json",
+        "test": "vitest",
+        "test:coverage": "vitest --coverage",
+        "test:watch": "vitest --watch"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/warlockjs/herald"
+    },
+    "peerDependencies": {
+        "amqplib": "^0.10.0"
+    },
+    "peerDependenciesMeta": {
+        "amqplib": {
+            "optional": true
+        }
+    },
+    "keywords": [
+        "message-bus",
+        "rabbitmq",
+        "kafka",
+        "queue",
+        "pub-sub",
+        "communicator",
+        "amqp",
+        "message-broker"
+    ],
+    "author": "hassanzohdy",
+    "license": "MIT",
+    "module": "./esm/index.js",
+    "typings": "./cjs/index.d.ts"
+}