@onlineapps/mq-client-core 1.0.0

package/README.md

@@ -0,0 +1,89 @@
+# @onlineapps/mq-client-core
+
+Core MQ client library for RabbitMQ - shared by infrastructure services and connectors.
+
+## Overview
+
+This is the **core library** extracted from `@onlineapps/conn-infra-mq` to provide basic MQ functionality for infrastructure services (gateway, registry, validator) without business-specific features.
+
+**Architecture Principle**: Connectors are exclusively for business services. If a connector contains functionality that should also serve infrastructure services, it must be extracted into a shared library.
+
+## Installation
+
+```bash
+npm install @onlineapps/mq-client-core
+```
+
+## Usage
+
+### For Infrastructure Services
+
+```javascript
+const BaseClient = require('@onlineapps/mq-client-core');
+
+const mqClient = new BaseClient({
+  type: 'rabbitmq',
+  host: 'amqp://localhost:5672',
+  queue: 'workflow.init' // Optional default queue
+});
+
+await mqClient.connect();
+await mqClient.publish('workflow.init', { workflowId: '123', data: '...' });
+```
+
+### Configuration
+
+**Flexible Schema** - Only `type` and `host` are required:
+
+```javascript
+{
+  type: 'rabbitmq',        // Required
+  host: 'amqp://...',      // Required
+  queue: 'optional',        // Optional default queue
+  exchange: '',             // Optional exchange
+  durable: true,            // Optional (default: true)
+  prefetch: 1,              // Optional (default: 1)
+  noAck: false,             // Optional (default: false)
+  logger: null              // Optional custom logger
+}
+```
+
+## API
+
+### BaseClient
+
+- `connect(options?)` - Connect to RabbitMQ
+- `disconnect()` - Disconnect from RabbitMQ
+- `publish(queue, message, options?)` - Publish message to queue
+- `consume(queue, handler, options?)` - Consume messages from queue
+- `ack(msg)` - Acknowledge message
+- `nack(msg, options?)` - Negative acknowledge message
+- `isConnected()` - Check connection status
+- `onError(callback)` - Register error handler
+
+## Architecture
+
+```
+mq-client-core (this library)
+├── BaseClient - Core AMQP operations
+├── RabbitMQClient - Transport implementation
+└── Basic publish/consume functionality
+
+conn-infra-mq (connector for business services)
+├── Uses mq-client-core internally
+├── ConnectorMQClient - Orchestrator with layers
+├── WorkflowRouter - Business workflow routing
+└── Additional business-specific features
+
+Infrastructure services (gateway, registry, validator)
+└── Use mq-client-core directly (not the connector)
+```
+
+## Related Packages
+
+- `@onlineapps/conn-infra-mq` - Full connector with business-specific features (uses this library internally)
+
+## License
+
+MIT
+

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@onlineapps/mq-client-core",
+  "version": "1.0.0",
+  "description": "Core MQ client library for RabbitMQ - shared by infrastructure services and connectors",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "jest",
+    "test:unit": "jest --testPathPattern=tests/unit",
+    "test:component": "jest --testPathPattern=tests/component",
+    "test:integration": "jest --testPathPattern=tests/integration"
+  },
+  "keywords": [
+    "rabbitmq",
+    "amqp",
+    "message-queue",
+    "mq"
+  ],
+  "author": "OnlineApps",
+  "license": "MIT",
+  "dependencies": {
+    "amqplib": "^0.10.3",
+    "ajv": "^8.12.0",
+    "lodash.merge": "^4.6.2"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
+

package/src/BaseClient.js

@@ -0,0 +1,230 @@
+'use strict';
+
+/**
+ * BaseClient: a promise-based, broker-agnostic client for RabbitMQ
+ * Core MQ client for infrastructure services and as base for connectors.
+ * Uses transportFactory to select the appropriate transport implementation.
+ */
+
+const Ajv = require('ajv');
+const merge = require('lodash.merge');
+
+const configSchema = require('./config/configSchema');
+const defaultConfig = require('./config/defaultConfig');
+const transportFactory = require('./transports/transportFactory');
+const serializer = require('./utils/serializer');
+const {
+  ConnectionError,
+  PublishError,
+  ConsumeError,
+  ValidationError,
+  SerializationError,
+} = require('./utils/errorHandler');
+
+class BaseClient {
+  /**
+   * @param {Object} config - User-supplied configuration.
+   * @throws {ValidationError} If required fields are missing or invalid.
+   */
+  constructor(config) {
+    const ajv = new Ajv({ allErrors: true, useDefaults: true });
+    const validate = ajv.compile(configSchema);
+
+    // Merge user config with defaults
+    this._config = merge({}, defaultConfig, config || {});
+
+    // Validate merged config
+    const valid = validate(this._config);
+    if (!valid) {
+      const details = validate.errors.map((err) => ({
+        path: err.instancePath,
+        message: err.message,
+      }));
+      throw new ValidationError('Invalid configuration', details);
+    }
+
+    this._transport = null;
+    this._connected = false;
+    this._errorHandlers = [];
+  }
+
+  /**
+   * Connects to the message broker using merged configuration.
+   * @param {Object} [options] - Optional overrides for host, queue, etc.
+   * @returns {Promise<void>}
+   * @throws {ConnectionError} If connecting fails.
+   */
+  async connect(options = {}) {
+    if (this._connected) return;
+
+    // Merge overrides into existing config
+    this._config = merge({}, this._config, options);
+
+    try {
+      // Instantiate appropriate transport: RabbitMQClient 
+      this._transport = transportFactory.create(this._config);
+
+      // Register internal error propagation
+      this._transport.on('error', (err) => this._handleError(err));
+
+      await this._transport.connect(this._config);
+      this._connected = true;
+    } catch (err) {
+      throw new ConnectionError('Failed to connect to broker', err);
+    }
+  }
+
+  /**
+   * Disconnects from the message broker.
+   * @returns {Promise<void>}
+   * @throws {Error} If disconnecting fails unexpectedly.
+   */
+  async disconnect() {
+    if (!this._connected || !this._transport) return;
+    try {
+      await this._transport.disconnect();
+      this._connected = false;
+      this._transport = null;
+    } catch (err) {
+      throw new Error(`Error during disconnect: ${err.message}`);
+    }
+  }
+
+  /**
+   * Publishes a message to the specified queue.
+   * @param {string} queue - Target queue name.
+   * @param {Object|Buffer|string} message - Payload to send.
+   * @param {Object} [options] - RabbitMQ-specific overrides (routingKey, persistent, headers, queueOptions).
+   * @returns {Promise<void>}
+   * @throws {ConnectionError} If not connected.
+   * @throws {PublishError} If publish fails.
+   */
+  async publish(queue, message, options = {}) {
+    if (!this._connected || !this._transport) {
+      throw new ConnectionError('Cannot publish: client is not connected');
+    }
+
+    let buffer;
+    try {
+      if (Buffer.isBuffer(message)) {
+        buffer = message;
+      } else if (typeof message === 'string') {
+        buffer = Buffer.from(message, 'utf8');
+      } else {
+        const json = serializer.serialize(message);
+        buffer = Buffer.from(json, 'utf8');
+      }
+    } catch (err) {
+      throw new SerializationError('Failed to serialize message', message, err);
+    }
+
+    try {
+      await this._transport.publish(queue, buffer, options);
+    } catch (err) {
+      throw new PublishError(`Failed to publish to queue "${queue}"`, queue, err);
+    }
+  }
+
+  /**
+   * Begins consuming messages from the specified queue.
+   * @param {string} queue - Name of the queue to consume from.
+   * @param {function(Object): Promise<void>} messageHandler - Async function to process each message.
+   * @param {Object} [options] - RabbitMQ-specific overrides (prefetch, noAck, queueOptions).
+   * @returns {Promise<void>}
+   * @throws {ConnectionError} If not connected.
+   * @throws {ConsumeError} If consumer setup fails.
+   */
+  async consume(queue, messageHandler, options = {}) {
+    if (!this._connected || !this._transport) {
+      throw new ConnectionError('Cannot consume: client is not connected');
+    }
+
+    // Apply prefetch and noAck overrides if provided
+    const { prefetch, noAck } = options;
+    const consumeOptions = {};
+    if (typeof prefetch === 'number') consumeOptions.prefetch = prefetch;
+    if (typeof noAck === 'boolean') consumeOptions.noAck = noAck;
+    if (options.queueOptions) consumeOptions.queueOptions = options.queueOptions;
+
+    try {
+      await this._transport.consume(
+        queue,
+        async (msg) => {
+          try {
+            await messageHandler(msg);
+            if (consumeOptions.noAck === false) {
+              await this.ack(msg);
+            }
+          } catch (handlerErr) {
+            // On handler error, nack with requeue: true
+            await this.nack(msg, { requeue: true });
+          }
+        },
+        consumeOptions
+      );
+    } catch (err) {
+      throw new ConsumeError(`Failed to start consumer for queue "${queue}"`, queue, err);
+    }
+  }
+
+  /**
+   * Acknowledges a RabbitMQ message.
+   * @param {Object} msg - RabbitMQ message object.
+   * @returns {Promise<void>}
+   */
+  async ack(msg) {
+    if (!this._connected || !this._transport) {
+      throw new ConnectionError('Cannot ack: client is not connected');
+    }
+    return this._transport.ack(msg);
+  }
+
+  /**
+   * Negative-acknowledges a RabbitMQ message.
+   * @param {Object} msg - RabbitMQ message object.
+   * @param {Object} [options] - Options such as { requeue: boolean }.
+   * @returns {Promise<void>}
+   */
+  async nack(msg, options = {}) {
+    if (!this._connected || !this._transport) {
+      throw new ConnectionError('Cannot nack: client is not connected');
+    }
+    return this._transport.nack(msg, options);
+  }
+
+  /**
+   * Registers a global error handler. Internal or transport-level errors will be forwarded here.
+   * @param {function(Error): void} callback
+   */
+  onError(callback) {
+    if (typeof callback === 'function') {
+      this._errorHandlers.push(callback);
+    }
+  }
+
+  /**
+   * Internal helper to invoke all registered error handlers.
+   * @param {Error} error
+   * @private
+   */
+  _handleError(error) {
+    this._errorHandlers.forEach((cb) => {
+      try {
+        cb(error);
+      } catch (_) {
+        // Ignore errors in user-provided error handlers
+      }
+    });
+  }
+
+  /**
+   * Check if client is connected
+   * @returns {boolean} Connection status
+   */
+  isConnected() {
+    return this._connected === true;
+  }
+}
+
+module.exports = BaseClient;
+

package/src/config/configSchema.js

@@ -0,0 +1,50 @@
+'use strict';
+
+/**
+ * configSchema.js
+ *
+ * JSON Schema used by Ajv to validate the user-supplied configuration object.
+ * 
+ * FLEXIBLE SCHEMA for infrastructure services:
+ * - Only requires 'type' and 'host'
+ * - Allows additional properties for flexibility
+ * - Queue is optional (infrastructure services may not need default queue)
+ */
+
+module.exports = {
+  type: 'object',
+  properties: {
+    type: {
+      type: 'string',
+      enum: ['rabbitmq'],
+    },
+    host: {
+      type: 'string',
+      minLength: 1,
+    },
+    // Queue is optional for infrastructure services
+    queue: {
+      type: 'string',
+    },
+    exchange: {
+      type: 'string',
+    },
+    durable: {
+      type: 'boolean',
+    },
+    prefetch: {
+      type: 'integer',
+      minimum: 0,
+    },
+    noAck: {
+      type: 'boolean',
+    },
+    logger: {
+      type: 'object',
+      description: 'Custom logger with methods: info, warn, error, debug',
+    },
+  },
+  required: ['type', 'host'], // Only type and host required
+  additionalProperties: true, // Allow additional properties for flexibility
+};
+

package/src/config/defaultConfig.js

@@ -0,0 +1,38 @@
+'use strict';
+
+/**
+ * defaultConfig.js
+ *
+ * Provides default configuration values for MQ Client Core.
+ * Users can override any of these by passing a custom config object
+ * or by supplying overrides to connect().
+ */
+
+module.exports = {
+  // Transport type: currently only 'rabbitmq' is fully supported.
+  type: 'rabbitmq',
+
+  // RabbitMQ connection URI or hostname (e.g., 'amqp://localhost:5672').
+  host: 'amqp://localhost:5672',
+
+  // Default queue name; can be overridden per call to publish/consume.
+  // Optional for infrastructure services (they may not need a default queue).
+  queue: '',
+
+  // Default exchange name (empty string → default direct exchange).
+  exchange: '',
+
+  // Declare queues/exchanges as durable by default.
+  durable: true,
+
+  // Default prefetch count for consumers.
+  prefetch: 1,
+
+  // Default auto-acknowledge setting for consumers.
+  noAck: false,
+
+  // Custom logger object (if not provided, console.* will be used).
+  // Expected interface: { info(), warn(), error(), debug() }.
+  logger: null,
+};
+

package/src/index.js

@@ -0,0 +1,30 @@
+'use strict';
+
+/**
+ * @onlineapps/mq-client-core
+ * 
+ * Core MQ client library for RabbitMQ - shared by infrastructure services and connectors.
+ * Provides basic publish/consume functionality without business-specific features.
+ */
+
+const BaseClient = require('./BaseClient');
+const RabbitMQClient = require('./transports/rabbitmqClient');
+const {
+  ValidationError,
+  ConnectionError,
+  PublishError,
+  ConsumeError,
+  SerializationError,
+} = require('./utils/errorHandler');
+
+module.exports = BaseClient;
+module.exports.BaseClient = BaseClient;
+module.exports.RabbitMQClient = RabbitMQClient;
+module.exports.errors = {
+  ValidationError,
+  ConnectionError,
+  PublishError,
+  ConsumeError,
+  SerializationError,
+};
+

package/src/transports/rabbitmqClient.js

@@ -0,0 +1,245 @@
+'use strict';
+
+/**
+ * RabbitMQClient: transport implementation for RabbitMQ using amqplib.
+ * Simplified version for infrastructure services - no queueConfig dependency.
+ * Implements connect, disconnect, publish, consume, ack, nack, and error propagation.
+ */
+
+const amqp = require('amqplib');
+const EventEmitter = require('events');
+
+class RabbitMQClient extends EventEmitter {
+  /**
+   * @param {Object} config
+   * @param {string} config.host         - AMQP URI or hostname (e.g., 'amqp://localhost:5672')
+   * @param {string} [config.queue]      - Default queue name (optional; can be overridden per call)
+   * @param {string} [config.exchange]   - Default exchange (default: '')
+   * @param {boolean} [config.durable]   - Declare queues/exchanges as durable (default: true)
+   * @param {number} [config.prefetch]   - Default prefetch count for consumers (default: 1)
+   * @param {boolean} [config.noAck]     - Default auto-acknowledge setting (default: false)
+   */
+  constructor(config) {
+    super();
+    this._config = Object.assign(
+      {
+        exchange: '',
+        durable: true,
+        prefetch: 1,
+        noAck: false,
+      },
+      config
+    );
+
+    this._connection = null;
+    this._channel = null;
+  }
+
+  /**
+   * Getter for channel - provides compatibility with QueueManager
+   */
+  get channel() {
+    return this._channel;
+  }
+
+  /**
+   * Connects to RabbitMQ server and creates a confirm channel.
+   * @returns {Promise<void>}
+   * @throws {Error} If connection or channel creation fails.
+   */
+  async connect() {
+    try {
+      this._connection = await amqp.connect(this._config.host);
+      this._connection.on('error', (err) => this.emit('error', err));
+      this._connection.on('close', () => {
+        // Emit a connection close error to notify listeners
+        this.emit('error', new Error('RabbitMQ connection closed unexpectedly'));
+      });
+
+      // Use ConfirmChannel to enable publisher confirms
+      this._channel = await this._connection.createConfirmChannel();
+      this._channel.on('error', (err) => this.emit('error', err));
+      this._channel.on('close', () => {
+        // Emit a channel close error
+        this.emit('error', new Error('RabbitMQ channel closed unexpectedly'));
+      });
+    } catch (err) {
+      // Cleanup partially created resources
+      if (this._connection) {
+        try {
+          await this._connection.close();
+        } catch (_) {
+          /* ignore */
+        }
+        this._connection = null;
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Disconnects: closes channel and connection.
+   * @returns {Promise<void>}
+   */
+  async disconnect() {
+    try {
+      if (this._channel) {
+        await this._channel.close();
+        this._channel = null;
+      }
+    } catch (err) {
+      this.emit('error', err);
+    }
+    try {
+      if (this._connection) {
+        await this._connection.close();
+        this._connection = null;
+      }
+    } catch (err) {
+      this.emit('error', err);
+    }
+  }
+
+  /**
+   * Publishes a message buffer to the specified queue (or default queue) or exchange.
+   * @param {string} queue           - Target queue name.
+   * @param {Buffer} buffer          - Message payload as Buffer.
+   * @param {Object} [options]       - Overrides: routingKey, persistent, headers.
+   * @returns {Promise<void>}
+   * @throws {Error} If publish fails or channel is not available.
+   */
+  async publish(queue, buffer, options = {}) {
+    if (!this._channel) {
+      throw new Error('Cannot publish: channel is not initialized');
+    }
+
+    const exchange = this._config.exchange || '';
+    const routingKey = options.routingKey || queue;
+    const persistent = options.persistent !== undefined ? options.persistent : this._config.durable;
+    const headers = options.headers || {};
+
+    try {
+      // Ensure queue exists if publishing directly to queue and using default exchange
+      if (!exchange) {
+        // Simple queue assertion - infrastructure services should ensure queues exist
+        // If queue doesn't exist, assertQueue will create it with default options
+        const queueOptions = options.queueOptions || { durable: this._config.durable };
+        await this._channel.assertQueue(queue, queueOptions);
+        this._channel.sendToQueue(queue, buffer, { persistent, headers, routingKey });
+      } else {
+        // If exchange is specified, assert exchange and publish to it
+        await this._channel.assertExchange(exchange, 'direct', { durable: this._config.durable });
+        this._channel.publish(exchange, routingKey, buffer, { persistent, headers });
+      }
+      // Wait for confirmation
+      await this._channel.waitForConfirms();
+    } catch (err) {
+      this.emit('error', err);
+      throw err;
+    }
+  }
+
+  /**
+   * Starts consuming messages from the specified queue.
+   * @param {string} queue                         - Queue name to consume from.
+   * @param {function(Object): Promise<void>} onMessage - Async handler receiving raw msg.
+   * @param {Object} [options]                     - Overrides: prefetch, noAck, queueOptions.
+   * @returns {Promise<void>}
+   * @throws {Error} If consume setup fails or channel is not available.
+   */
+  async consume(queue, onMessage, options = {}) {
+    if (!this._channel) {
+      throw new Error('Cannot consume: channel is not initialized');
+    }
+
+    const durable = options.durable !== undefined ? options.durable : this._config.durable;
+    const prefetch = options.prefetch !== undefined ? options.prefetch : this._config.prefetch;
+    const noAck = options.noAck !== undefined ? options.noAck : this._config.noAck;
+
+    try {
+      // Skip assertQueue for reply queues (they're already created with specific settings)
+      // Reply queues start with 'rpc.reply.' and are created as non-durable
+      if (!queue.startsWith('rpc.reply.')) {
+        // Simple queue assertion - infrastructure services should ensure queues exist
+        // If queue doesn't exist, assertQueue will create it with default options
+        // If it exists with different args (406), log warning and proceed
+        const queueOptions = options.queueOptions || { durable };
+        try {
+          await this._channel.assertQueue(queue, queueOptions);
+        } catch (assertErr) {
+          // If queue exists with different arguments (406), use it as-is
+          if (assertErr.code === 406) {
+            console.warn(`[RabbitMQClient] Queue ${queue} exists with different arguments, using as-is:`, assertErr.message);
+            // Don't try to re-assert - just proceed to consume
+          } else {
+            // Other error - rethrow
+            throw assertErr;
+          }
+        }
+      }
+      // Set prefetch if provided
+      if (typeof prefetch === 'number') {
+        this._channel.prefetch(prefetch);
+      }
+
+      await this._channel.consume(
+        queue,
+        async (msg) => {
+          if (msg === null) {
+            return;
+          }
+          try {
+            await onMessage(msg);
+            if (!noAck) {
+              this._channel.ack(msg);
+            }
+          } catch (handlerErr) {
+            // Negative acknowledge and requeue by default
+            this._channel.nack(msg, false, true);
+          }
+        },
+        { noAck }
+      );
+    } catch (err) {
+      this.emit('error', err);
+      throw err;
+    }
+  }
+
+  /**
+   * Acknowledges a message.
+   * @param {Object} msg - RabbitMQ message object.
+   */
+  async ack(msg) {
+    if (!this._channel) {
+      throw new Error('Cannot ack: channel is not initialized');
+    }
+    try {
+      this._channel.ack(msg);
+    } catch (err) {
+      this.emit('error', err);
+      throw err;
+    }
+  }
+
+  /**
+   * Negative-acknowledges a message.
+   * @param {Object} msg - RabbitMQ message object.
+   * @param {Object} [options] - { requeue: boolean }.
+   */
+  async nack(msg, options = {}) {
+    if (!this._channel) {
+      throw new Error('Cannot nack: channel is not initialized');
+    }
+    const requeue = options.requeue !== undefined ? options.requeue : true;
+    try {
+      this._channel.nack(msg, false, requeue);
+    } catch (err) {
+      this.emit('error', err);
+      throw err;
+    }
+  }
+}
+
+module.exports = RabbitMQClient;
+

package/src/transports/transportFactory.js

@@ -0,0 +1,34 @@
+'use strict';
+
+/**
+ * transportFactory: selects and instantiates the appropriate transport
+ * based on configuration. Currently supports RabbitMQ.
+ */
+
+const RabbitMQClient = require('./rabbitmqClient');
+
+/**
+ * Factory method: returns a transport instance based on config.type.
+ * @param {Object} config
+ * @param {'rabbitmq'} config.type - Transport type ('rabbitmq' for now)
+ * @returns {Object} Instance of transport (RabbitMQClient, etc.)
+ * @throws {Error} If the configured type is unsupported or missing
+ */
+function create(config) {
+  if (!config || !config.type) {
+    throw new Error('Transport type is required in configuration');
+  }
+
+  switch (config.type.toLowerCase()) {
+    case 'rabbitmq':
+      return new RabbitMQClient(config);
+
+    default:
+      throw new Error(`Unsupported transport type: ${config.type}`);
+  }
+}
+
+module.exports = {
+  create,
+};
+

package/src/utils/errorHandler.js

@@ -0,0 +1,121 @@
+'use strict';
+
+/**
+ * errorHandler.js
+ *
+ * Defines all custom error types used by MQ client core.
+ * Each extends the built-in Error class and carries additional contextual fields.
+ */
+
+/**
+ * ValidationError
+ * Thrown when user-supplied configuration does not match schema.
+ * - message: human-readable description
+ * - details: array of { path, message } describing each invalid field
+ */
+class ValidationError extends Error {
+  /**
+   * @param {string} message
+   * @param {Array<{path: string, message: string}>} details
+   */
+  constructor(message, details) {
+    super(message);
+    this.name = 'ValidationError';
+    this.details = Array.isArray(details) ? details : [];
+    Error.captureStackTrace(this, ValidationError);
+  }
+}
+
+/**
+ * ConnectionError
+ * Thrown when client cannot connect to broker.
+ * - message: description of what went wrong
+ * - cause: original error object
+ */
+class ConnectionError extends Error {
+  /**
+   * @param {string} message
+   * @param {Error} cause
+   */
+  constructor(message, cause) {
+    super(message);
+    this.name = 'ConnectionError';
+    this.cause = cause;
+    Error.captureStackTrace(this, ConnectionError);
+  }
+}
+
+/**
+ * PublishError
+ * Thrown when publishing a message fails.
+ * - message: description
+ * - queue: target queue name
+ * - cause: original error
+ */
+class PublishError extends Error {
+  /**
+   * @param {string} message
+   * @param {string} queue
+   * @param {Error} cause
+   */
+  constructor(message, queue, cause) {
+    super(message);
+    this.name = 'PublishError';
+    this.queue = queue;
+    this.cause = cause;
+    Error.captureStackTrace(this, PublishError);
+  }
+}
+
+/**
+ * ConsumeError
+ * Thrown when setting up a consumer fails.
+ * - message: description
+ * - queue: queue name associated with the consumer
+ * - cause: original error
+ */
+class ConsumeError extends Error {
+  /**
+   * @param {string} message
+   * @param {string} queue
+   * @param {Error} cause
+   */
+  constructor(message, queue, cause) {
+    super(message);
+    this.name = 'ConsumeError';
+    this.queue = queue;
+    this.cause = cause;
+    Error.captureStackTrace(this, ConsumeError);
+  }
+}
+
+/**
+ * SerializationError
+ * Thrown when JSON serialization or deserialization fails.
+ * - message: description
+ * - payload: original object or buffer that caused the error
+ * - cause: native exception (e.g., TypeError for circular references)
+ */
+class SerializationError extends Error {
+  /**
+   * @param {string} message
+   * @param {*} payload
+   * @param {Error} cause
+   */
+  constructor(message, payload, cause) {
+    super(message);
+    this.name = 'SerializationError';
+    this.payload = payload;
+    this.cause = cause;
+    Error.captureStackTrace(this, SerializationError);
+  }
+}
+
+module.exports = {
+  ValidationError,
+  ConnectionError,
+  PublishError,
+  ConsumeError,
+  SerializationError,
+};
+

package/src/utils/serializer.js

@@ -0,0 +1,45 @@
+'use strict';
+
+/**
+ * serializer.js
+ *
+ * Contains helper functions for serializing and deserializing payloads.
+ * On failure, throws a SerializationError (defined in errorHandler.js).
+ */
+
+const { SerializationError } = require('./errorHandler');
+
+/**
+ * Serializes a JavaScript object to JSON string.
+ * @param {Object} obj
+ * @returns {string}
+ * @throws {SerializationError} If JSON.stringify fails (e.g., circular reference).
+ */
+function serialize(obj) {
+  try {
+    return JSON.stringify(obj);
+  } catch (err) {
+    throw new SerializationError('Failed to serialize object', obj, err);
+  }
+}
+
+/**
+ * Deserializes a Buffer or string into a JavaScript object via JSON.parse.
+ * @param {Buffer|string} buffer
+ * @returns {Object}
+ * @throws {SerializationError} If JSON.parse fails or buffer cannot be converted.
+ */
+function deserialize(buffer) {
+  try {
+    const str = Buffer.isBuffer(buffer) ? buffer.toString('utf8') : buffer;
+    return JSON.parse(str);
+  } catch (err) {
+    throw new SerializationError('Failed to deserialize payload', buffer, err);
+  }
+}
+
+module.exports = {
+  serialize,
+  deserialize,
+};
+