@warlock.js/herald 4.8.2 → 4.9.0

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

@@ -1,7 +1,7 @@
 import { brokerRegistry } from "../communicators/broker-registry.mjs";
 import "../communicators/index.mjs";
 
-//#region ../@warlock.js/herald/src/utils/connect-to-broker.ts
+//#region ../herald/src/utils/connect-to-broker.ts
 /**
 * Connect to a message broker and register it.
 *

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

@@ -1 +1 @@
-{"version":3,"file":"connect-to-broker.mjs","names":[],"sources":["../../../../../../../@warlock.js/herald/src/utils/connect-to-broker.ts"],"sourcesContent":["import { Broker, brokerRegistry } from \"../communicators\";\r\nimport type { BrokerDriverContract, ChannelContract } from \"../contracts\";\r\nimport { EventConsumerClass, EventMessage } from \"../message-managers\";\r\nimport type { ChannelOptions, ConnectionOptions, RabbitMQConnectionOptions } from \"../types\";\r\n\r\n/**\r\n * Connect to a message broker and register it.\r\n *\r\n * This is a high-level utility function that simplifies connection setup\r\n * for most projects. It handles driver instantiation, connection,\r\n * broker creation, and automatic registration.\r\n *\r\n * **Supported Drivers:**\r\n * - `rabbitmq` (default) - RabbitMQ/AMQP driver\r\n * - `kafka` - Apache Kafka driver (coming soon)\r\n *\r\n * @param options - Connection configuration options\r\n * @returns A connected and registered Broker instance\r\n * @throws {Error} If connection fails or driver is not implemented\r\n *\r\n * @example\r\n * ```typescript\r\n * // RabbitMQ connection\r\n * const broker = await connectToBroker({\r\n *   driver: \"rabbitmq\",\r\n *   host: \"localhost\",\r\n *   port: 5672,\r\n *   username: \"guest\",\r\n *   password: \"guest\",\r\n * });\r\n *\r\n * // Use the broker\r\n * await broker.channel(\"user.created\").publish({ userId: 1 });\r\n * ```\r\n *\r\n * @example\r\n * ```typescript\r\n * // Multiple brokers\r\n * await connectToBroker({\r\n *   driver: \"rabbitmq\",\r\n *   name: \"notifications\",\r\n *   isDefault: true,\r\n *   host: process.env.RABBITMQ_HOST,\r\n * });\r\n *\r\n * await connectToBroker({\r\n *   driver: \"rabbitmq\",\r\n *   name: \"analytics\",\r\n *   host: process.env.ANALYTICS_RABBITMQ_HOST,\r\n * });\r\n *\r\n * // Use default broker\r\n * herald().channel(\"notifications\").publish({ ... });\r\n *\r\n * // Use specific broker\r\n * herald(\"analytics\").channel(\"events\").publish({ ... });\r\n * ```\r\n */\r\nexport async function connectToBroker(options: ConnectionOptions): Promise<Broker> {\r\n  // Default values\r\n  const driverType = options.driver ?? \"rabbitmq\";\r\n  const brokerName = options.name ?? \"default\";\r\n  const isDefault = options.isDefault ?? true;\r\n\r\n  // Create driver based on type\r\n  let driver: BrokerDriverContract;\r\n\r\n  switch (driverType) {\r\n    case \"rabbitmq\": {\r\n      const rabbitOptions = options as RabbitMQConnectionOptions;\r\n      // Dynamic import to avoid requiring amqplib if not used\r\n      const { RabbitMQDriver } = await import(\"../drivers/rabbitmq/rabbitmq-driver\");\r\n      driver = new RabbitMQDriver(rabbitOptions);\r\n      break;\r\n    }\r\n\r\n    case \"kafka\": {\r\n      // const kafkaOptions = options as KafkaConnectionOptions;\r\n      // Dynamic import to avoid requiring kafkajs if not used\r\n      throw new Error(\r\n        \"Kafka driver is not yet implemented. Coming soon! For now, please use RabbitMQ.\",\r\n      );\r\n    }\r\n\r\n    default:\r\n      throw new Error(`Unknown driver: \"${driverType}\". Supported drivers: rabbitmq, kafka`);\r\n  }\r\n\r\n  // Create broker\r\n  const broker = brokerRegistry.register({\r\n    name: brokerName,\r\n    driver,\r\n    isDefault,\r\n  });\r\n\r\n  // Connect to the message broker\r\n  try {\r\n    await driver.connect();\r\n  } catch (error) {\r\n    throw new Error(\r\n      `Failed to connect to ${driverType}: ${error instanceof Error ? error.message : String(error)}`,\r\n    );\r\n  }\r\n\r\n  return broker;\r\n}\r\n\r\n/**\r\n * Get a broker by name or the default one.\r\n *\r\n * This is the main entry point for using brokers in your application.\r\n * Named after the package — `herald()` carries your messages!\r\n *\r\n * @param name - Optional broker name (uses default if not provided)\r\n * @returns Broker instance\r\n * @throws MissingBrokerError if broker not found\r\n *\r\n * @example\r\n * // Get default broker\r\n * const channel = herald().channel(\"user.created\");\r\n * await channel.publish({ userId: 1 });\r\n *\r\n * // Get specific broker\r\n * const analyticsChannel = herald(\"analytics\").channel(\"events\");\r\n * await analyticsChannel.publish({ event: \"page_view\" });\r\n *\r\n * // Subscribe to messages\r\n * herald()\r\n *   .channel<UserPayload>(\"user.created\")\r\n *   .subscribe(async (message, ctx) => {\r\n *     console.log(\"User created:\", message.payload);\r\n *     await ctx.ack();\r\n *   });\r\n * ```\r\n */\r\nexport function herald(name?: string): Broker {\r\n  return brokerRegistry.get(name);\r\n}\r\n\r\n/**\r\n * Get channel instance for the given name from default broker.\r\n *\r\n * Shorthand for `herald().channel(name, options)`.\r\n *\r\n * @param name - Channel name\r\n * @param options - Optional channel options\r\n * @returns Channel instance\r\n * @throws MissingBrokerError if broker not found\r\n *\r\n * @example\r\n * ```typescript\r\n * const channel = heraldChannel(\"user.created\");\r\n * await channel.publish({ userId: 1 });\r\n * ```\r\n */\r\nexport function heraldChannel<TPayload = unknown>(\r\n  name: string,\r\n  options?: ChannelOptions<TPayload>,\r\n): ChannelContract<TPayload> {\r\n  return herald().channel<TPayload>(name, options);\r\n}\r\n\r\n/**\r\n * Publish an EventMessage to the default broker.\r\n *\r\n * @param event - Event message to publish\r\n * @returns Promise that resolves when the event is published\r\n * @throws Error if the broker is not connected\r\n *\r\n * @example\r\n * ```typescript\r\n * await publishEvent(new UserUpdatedEvent({ id: 1, name: \"John Doe\" }));\r\n * ```\r\n */\r\nexport async function publishEvent<TPayload = Record<string, any>>(event: EventMessage<TPayload>) {\r\n  return herald().publish(event);\r\n}\r\n\r\n/**\r\n * Subscribe an EventConsumer class to the default broker.\r\n *\r\n * @param Consumer - Event consumer class\r\n * @returns Unsubscribe function\r\n * @throws MissingBrokerError if broker not found\r\n *\r\n * @example\r\n * ```typescript\r\n * await subscribeConsumer(UserUpdatedConsumer);\r\n * ```\r\n */\r\nexport async function subscribeConsumer<TPayload = Record<string, any>>(\r\n  Consumer: EventConsumerClass<TPayload>,\r\n) {\r\n  return herald().subscribe(Consumer);\r\n}\r\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DA,eAAsB,gBAAgB,SAA6C;CAEjF,MAAM,aAAa,QAAQ,UAAU;CACrC,MAAM,aAAa,QAAQ,QAAQ;CACnC,MAAM,YAAY,QAAQ,aAAa;CAGvC,IAAI;CAEJ,QAAQ,YAAR;EACE,KAAK,YAAY;GACf,MAAM,gBAAgB;GAEtB,MAAM,EAAE,mBAAmB,MAAM,OAAO;GACxC,SAAS,IAAI,eAAe,aAAa;GACzC;EACF;EAEA,KAAK,SAGH,MAAM,IAAI,MACR,iFACF;EAGF,SACE,MAAM,IAAI,MAAM,oBAAoB,WAAW,sCAAsC;CACzF;CAGA,MAAM,SAAS,eAAe,SAAS;EACrC,MAAM;EACN;EACA;CACF,CAAC;CAGD,IAAI;EACF,MAAM,OAAO,QAAQ;CACvB,SAAS,OAAO;EACd,MAAM,IAAI,MACR,wBAAwB,WAAW,IAAI,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,GAC9F;CACF;CAEA,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,SAAgB,OAAO,MAAuB;CAC5C,OAAO,eAAe,IAAI,IAAI;AAChC;;;;;;;;;;;;;;;;;AAkBA,SAAgB,cACd,MACA,SAC2B;CAC3B,OAAO,OAAO,CAAC,CAAC,QAAkB,MAAM,OAAO;AACjD;;;;;;;;;;;;;AAcA,eAAsB,aAA6C,OAA+B;CAChG,OAAO,OAAO,CAAC,CAAC,QAAQ,KAAK;AAC/B;;;;;;;;;;;;;AAcA,eAAsB,kBACpB,UACA;CACA,OAAO,OAAO,CAAC,CAAC,UAAU,QAAQ;AACpC"}
+{"version":3,"file":"connect-to-broker.mjs","names":[],"sources":["../../../../../../../herald/src/utils/connect-to-broker.ts"],"sourcesContent":["import { Broker, brokerRegistry } from \"../communicators\";\r\nimport type { BrokerDriverContract, ChannelContract } from \"../contracts\";\r\nimport { EventConsumerClass, EventMessage } from \"../message-managers\";\r\nimport type { ChannelOptions, ConnectionOptions, RabbitMQConnectionOptions } from \"../types\";\r\n\r\n/**\r\n * Connect to a message broker and register it.\r\n *\r\n * This is a high-level utility function that simplifies connection setup\r\n * for most projects. It handles driver instantiation, connection,\r\n * broker creation, and automatic registration.\r\n *\r\n * **Supported Drivers:**\r\n * - `rabbitmq` (default) - RabbitMQ/AMQP driver\r\n * - `kafka` - Apache Kafka driver (coming soon)\r\n *\r\n * @param options - Connection configuration options\r\n * @returns A connected and registered Broker instance\r\n * @throws {Error} If connection fails or driver is not implemented\r\n *\r\n * @example\r\n * ```typescript\r\n * // RabbitMQ connection\r\n * const broker = await connectToBroker({\r\n *   driver: \"rabbitmq\",\r\n *   host: \"localhost\",\r\n *   port: 5672,\r\n *   username: \"guest\",\r\n *   password: \"guest\",\r\n * });\r\n *\r\n * // Use the broker\r\n * await broker.channel(\"user.created\").publish({ userId: 1 });\r\n * ```\r\n *\r\n * @example\r\n * ```typescript\r\n * // Multiple brokers\r\n * await connectToBroker({\r\n *   driver: \"rabbitmq\",\r\n *   name: \"notifications\",\r\n *   isDefault: true,\r\n *   host: process.env.RABBITMQ_HOST,\r\n * });\r\n *\r\n * await connectToBroker({\r\n *   driver: \"rabbitmq\",\r\n *   name: \"analytics\",\r\n *   host: process.env.ANALYTICS_RABBITMQ_HOST,\r\n * });\r\n *\r\n * // Use default broker\r\n * herald().channel(\"notifications\").publish({ ... });\r\n *\r\n * // Use specific broker\r\n * herald(\"analytics\").channel(\"events\").publish({ ... });\r\n * ```\r\n */\r\nexport async function connectToBroker(options: ConnectionOptions): Promise<Broker> {\r\n  // Default values\r\n  const driverType = options.driver ?? \"rabbitmq\";\r\n  const brokerName = options.name ?? \"default\";\r\n  const isDefault = options.isDefault ?? true;\r\n\r\n  // Create driver based on type\r\n  let driver: BrokerDriverContract;\r\n\r\n  switch (driverType) {\r\n    case \"rabbitmq\": {\r\n      const rabbitOptions = options as RabbitMQConnectionOptions;\r\n      // Dynamic import to avoid requiring amqplib if not used\r\n      const { RabbitMQDriver } = await import(\"../drivers/rabbitmq/rabbitmq-driver\");\r\n      driver = new RabbitMQDriver(rabbitOptions);\r\n      break;\r\n    }\r\n\r\n    case \"kafka\": {\r\n      // const kafkaOptions = options as KafkaConnectionOptions;\r\n      // Dynamic import to avoid requiring kafkajs if not used\r\n      throw new Error(\r\n        \"Kafka driver is not yet implemented. Coming soon! For now, please use RabbitMQ.\",\r\n      );\r\n    }\r\n\r\n    default:\r\n      throw new Error(`Unknown driver: \"${driverType}\". Supported drivers: rabbitmq, kafka`);\r\n  }\r\n\r\n  // Create broker\r\n  const broker = brokerRegistry.register({\r\n    name: brokerName,\r\n    driver,\r\n    isDefault,\r\n  });\r\n\r\n  // Connect to the message broker\r\n  try {\r\n    await driver.connect();\r\n  } catch (error) {\r\n    throw new Error(\r\n      `Failed to connect to ${driverType}: ${error instanceof Error ? error.message : String(error)}`,\r\n    );\r\n  }\r\n\r\n  return broker;\r\n}\r\n\r\n/**\r\n * Get a broker by name or the default one.\r\n *\r\n * This is the main entry point for using brokers in your application.\r\n * Named after the package — `herald()` carries your messages!\r\n *\r\n * @param name - Optional broker name (uses default if not provided)\r\n * @returns Broker instance\r\n * @throws MissingBrokerError if broker not found\r\n *\r\n * @example\r\n * // Get default broker\r\n * const channel = herald().channel(\"user.created\");\r\n * await channel.publish({ userId: 1 });\r\n *\r\n * // Get specific broker\r\n * const analyticsChannel = herald(\"analytics\").channel(\"events\");\r\n * await analyticsChannel.publish({ event: \"page_view\" });\r\n *\r\n * // Subscribe to messages\r\n * herald()\r\n *   .channel<UserPayload>(\"user.created\")\r\n *   .subscribe(async (message, ctx) => {\r\n *     console.log(\"User created:\", message.payload);\r\n *     await ctx.ack();\r\n *   });\r\n * ```\r\n */\r\nexport function herald(name?: string): Broker {\r\n  return brokerRegistry.get(name);\r\n}\r\n\r\n/**\r\n * Get channel instance for the given name from default broker.\r\n *\r\n * Shorthand for `herald().channel(name, options)`.\r\n *\r\n * @param name - Channel name\r\n * @param options - Optional channel options\r\n * @returns Channel instance\r\n * @throws MissingBrokerError if broker not found\r\n *\r\n * @example\r\n * ```typescript\r\n * const channel = heraldChannel(\"user.created\");\r\n * await channel.publish({ userId: 1 });\r\n * ```\r\n */\r\nexport function heraldChannel<TPayload = unknown>(\r\n  name: string,\r\n  options?: ChannelOptions<TPayload>,\r\n): ChannelContract<TPayload> {\r\n  return herald().channel<TPayload>(name, options);\r\n}\r\n\r\n/**\r\n * Publish an EventMessage to the default broker.\r\n *\r\n * @param event - Event message to publish\r\n * @returns Promise that resolves when the event is published\r\n * @throws Error if the broker is not connected\r\n *\r\n * @example\r\n * ```typescript\r\n * await publishEvent(new UserUpdatedEvent({ id: 1, name: \"John Doe\" }));\r\n * ```\r\n */\r\nexport async function publishEvent<TPayload = Record<string, any>>(event: EventMessage<TPayload>) {\r\n  return herald().publish(event);\r\n}\r\n\r\n/**\r\n * Subscribe an EventConsumer class to the default broker.\r\n *\r\n * @param Consumer - Event consumer class\r\n * @returns Unsubscribe function\r\n * @throws MissingBrokerError if broker not found\r\n *\r\n * @example\r\n * ```typescript\r\n * await subscribeConsumer(UserUpdatedConsumer);\r\n * ```\r\n */\r\nexport async function subscribeConsumer<TPayload = Record<string, any>>(\r\n  Consumer: EventConsumerClass<TPayload>,\r\n) {\r\n  return herald().subscribe(Consumer);\r\n}\r\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DA,eAAsB,gBAAgB,SAA6C;CAEjF,MAAM,aAAa,QAAQ,UAAU;CACrC,MAAM,aAAa,QAAQ,QAAQ;CACnC,MAAM,YAAY,QAAQ,aAAa;CAGvC,IAAI;CAEJ,QAAQ,YAAR;EACE,KAAK,YAAY;GACf,MAAM,gBAAgB;GAEtB,MAAM,EAAE,mBAAmB,MAAM,OAAO;GACxC,SAAS,IAAI,eAAe,aAAa;GACzC;EACF;EAEA,KAAK,SAGH,MAAM,IAAI,MACR,iFACF;EAGF,SACE,MAAM,IAAI,MAAM,oBAAoB,WAAW,sCAAsC;CACzF;CAGA,MAAM,SAAS,eAAe,SAAS;EACrC,MAAM;EACN;EACA;CACF,CAAC;CAGD,IAAI;EACF,MAAM,OAAO,QAAQ;CACvB,SAAS,OAAO;EACd,MAAM,IAAI,MACR,wBAAwB,WAAW,IAAI,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,GAC9F;CACF;CAEA,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,SAAgB,OAAO,MAAuB;CAC5C,OAAO,eAAe,IAAI,IAAI;AAChC;;;;;;;;;;;;;;;;;AAkBA,SAAgB,cACd,MACA,SAC2B;CAC3B,OAAO,OAAO,CAAC,CAAC,QAAkB,MAAM,OAAO;AACjD;;;;;;;;;;;;;AAcA,eAAsB,aAA6C,OAA+B;CAChG,OAAO,OAAO,CAAC,CAAC,QAAQ,KAAK;AAC/B;;;;;;;;;;;;;AAcA,eAAsB,kBACpB,UACA;CACA,OAAO,OAAO,CAAC,CAAC,UAAU,QAAQ;AACpC"}

package/package.json

@@ -22,13 +22,13 @@
     "@mongez/copper": "^2.1.2",
     "@mongez/events": "^2.2.6",
     "@mongez/reinforcements": "^3.3.0",
-    "@warlock.js/logger": "4.8.2",
-    "@warlock.js/seal": "4.8.2"
+    "@warlock.js/logger": "4.9.0",
+    "@warlock.js/seal": "4.9.0"
   },
   "peerDependencies": {
     "amqplib": "^0.10.0"
   },
-  "version": "4.8.2",
+  "version": "4.9.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",