Microcom

Microcom is a lightweight TypeScript library for microservice communication over AMQP.
It provides a simple, unified interface for both Pub/Sub (event-driven) and RPC (request-response) messaging patterns — built for services that run independently but need to stay in sync.

It supports RabbitMQ, LavinMQ, and other AMQP-compliant brokers out of the box.

Features

• Shared AMQP connection reused across services.
• Built-in Pub/Sub for event-driven systems.
• Built-in RPC for request/response patterns.
• Offline-first Pub/Sub: messages persist when a service is offline and are consumed when it comes back online.
• Configurable queues per service (durable or transient).
• Written entirely in TypeScript, with type-safe interfaces.
• Supports distributed tracing (correlation IDs, trace IDs, etc.).

Installation

npm install microcom

Quick Start

RPC Example

import { MicrocomConnection, MicrocomRPC } from "microcom";

(async () => {
  // 1. Establish a shared AMQP connection
  const conn = await MicrocomConnection.create({
    amqpUrl: "amqp://localhost",
    queueName: "rpc_service_queue",
    queueProps: {
      exclusive: true,
      autoDelete: true,
    },
  });

  console.log("RPC connection established.");

  // 2. Create RPC instance
  const rpc = new MicrocomRPC(conn);

  // 3. Listen for incoming RPC requests
  rpc.respond(async (req) => {
    console.log("Received RPC request:", req);
    return { success: true, user: { id: req.userId, name: "John Doe" } };
  });

  // 4. Send an RPC request to another service
  const response = await rpc.request({
    method: "getUser",
    path: "users/getById",
    data: { userId: 101 },
  });

  console.log("RPC response:", response);
})();

Pub/Sub Example

import { MicrocomConnection, MicrocomPubSub } from "microcom";

(async () => {
  // 1. Establish a shared connection
  const conn = await MicrocomConnection.create({
    amqpUrl: "amqp://localhost",
    queueName: "user_service_queue",
    queueProps: {
      durable: true,        // ensures persistence
      exclusive: false,
      autoDelete: false,
    },
  });

  console.log("Pub/Sub connection established.");

  // 2. Initialize Pub/Sub with an exchange name
  const pubsub = await MicrocomPubSub.create(conn, "user_events", "topic");

  // 3. Subscribe to user-related events
  await pubsub.subscribe(
    (message) => {
      console.log("Received event:", message);
    },
    "user.created"
  );

  // 4. Publish a new event
  await pubsub.publish({
    event: "user.created",
    data: { id: 42, name: "John" },
  });

  console.log("Event published.");
})();

Behavior and Reliability

• Offline-first design:
  Durable queues ensure that messages are not lost if a service goes down. When it restarts, all pending messages will be delivered automatically.

• Exchange setup:
  Each Pub/Sub instance creates or connects to its own exchange (topic type by default).

• AMQP compatibility:
  Works seamlessly with RabbitMQ, LavinMQ, and other AMQP 0.9.1 compatible brokers.

Configuration

MicrocomConnection.create(options)

{
  amqpUrl: string;                 // AMQP broker URL
  queueName: string;               // Service-specific queue name
  queueProps?: AMQPQueueParams;    // Optional queue parameters (durable, autoDelete, etc.)
}

MicrocomPubSub.create(connection, exchangeName, type)

exchangeName: string;  // Exchange name (e.g., "user_events")
type?: "topic" | "direct" | "fanout";  // Default is "topic"

Error Handling

Microcom methods return Promises and should be used with try/catch:

try {
  const response = await rpc.request({ method: "findUser", data: { id: 5 } });
} catch (err) {
  console.error("RPC request failed:", err);
}

Issue Reporting

If you encounter issues, please open an issue on GitHub and include:

• Steps to reproduce
• Expected behavior
• Actual behavior
• Node.js version
• AMQP broker (RabbitMQ, LavinMQ, etc.)
• Logs (if available)

License

MIT License © 2025