JavaScript / TypeScript SDK

The official MessageX client is published on npm as messagex-client. It is a Node.js TCP client distributed as ECMAScript modules with TypeScript declarations.

1. Requirements and installationCopy Anchor Link

• Node.js 20 or newer
• A reachable MessageX broker TCP endpoint
• A broker username and password created during deployment

Install the client:

npm install messagex-client

References: npm package · SDK source

2. Configure credentialsCopy Anchor Link

Keep connection details outside source code. For Node.js 20.6+, create a local .env file:

MESSAGEX_HOST=127.0.0.1
MESSAGEX_PORT=5678
MESSAGEX_USER=admin
MESSAGEX_PASSWORD=replace-with-your-broker-password

Add .env to .gitignore. Never commit real credentials.

3. Connect and authenticateCopy Anchor Link

connect() opens a TCP socket and performs the protocol handshake in order:

1. CONNECT registers the client name on the connection.
2. AUTH verifies the username and password.
3. The promise resolves after both commands succeed.

import { MessageX } from 'messagex-client';

const client = new MessageX({
  host: process.env.MESSAGEX_HOST ?? '127.0.0.1',
  port: Number(process.env.MESSAGEX_PORT ?? 5678),
  username: process.env.MESSAGEX_USER,
  password: process.env.MESSAGEX_PASSWORD,
  clientName: 'orders-service',
});

client.on('disconnect', () => {
  console.error('MessageX connection closed');
});
client.on('warning', (error) => {
  console.warn('MessageX warning:', error.message);
});
client.on('error', (error) => {
  console.error('MessageX socket error:', error.message);
});

await client.connect();
console.log(client.isConnected, client.isAuthenticated);

The SDK requires host, username, and password. The default TCP port is 5678. Calling broker methods before connect() completes rejects with a connection error.

4. Understand the broker resourcesCopy Anchor Link

A producer does not publish directly to a queue. It publishes to an exchange. The exchange evaluates its bindings and routes a copy of the message to each matching queue.

• Exchange: routing entry point for published messages.
• Queue: persisted holding area from which consumers receive messages.
• Binding: relationship between an exchange and a queue, optionally with a routing key and arguments.
• Routing key: string supplied by the publisher and evaluated by the exchange's routing strategy.
• Consumer: active subscription that receives deliveries from a queue.
• Delivery tag: identifier for one in-flight delivery. The broker checks both the tag and owning connection when settling it.

5. Declare a queueCopy Anchor Link

const { queue } = await client.queue.declare({
  name: 'orders.created',
  durable: true,
  exclusive: false,
  autoDelete: false,
  maxDeliveryCount: 5,
  deadLetterQueue: 'orders.dead',
});

console.log(queue);

The broker associates an exclusive queue with its declaring connection. Other connections cannot consume from, bind to, or delete that exclusive queue.

6. Declare an exchangeCopy Anchor Link

const { exchange } = await client.exchange.declare({
  name: 'orders.events',
  type: 'topic',
  durable: true,
});
console.log(exchange);

MessageX supports four exchange types:

Exchange names are required and limited to 255 characters. The durable option defaults according to the broker's declaration defaults.

7. Bind a queue to an exchangeCopy Anchor Link

A binding tells the exchange which queue should receive matching messages.

Direct bindingCopy Anchor Link

await client.exchange.bind({
  exchangeName: 'orders.events',
  queueName: 'orders.created',
  routingKey: 'orders.created',
});

Topic bindingCopy Anchor Link

await client.exchange.bind({
  exchangeName: 'orders.events',
  queueName: 'all.order.events',
  routingKey: 'orders.*',
});

Fanout bindingCopy Anchor Link

await client.exchange.bind({
  exchangeName: 'broadcast.events',
  queueName: 'notifications.email',
});

Headers bindingCopy Anchor Link

await client.exchange.bind({
  exchangeName: 'events.by-header',
  queueName: 'apac.events',
  arguments: {
    'x-match': 'all',
    region: 'apac',
    priority: 'high',
  },
});

For headers exchanges, x-match: 'all' requires every supplied binding argument to match; x-match: 'any' accepts a match on any supplied argument. Binding arguments are limited to 32 entries.

Remove a binding with the same exchange, queue, routing key, and arguments:

await client.exchange.unbind({
  exchangeName: 'orders.events',
  queueName: 'orders.created',
  routingKey: 'orders.created',
});

8. Publish a messageCopy Anchor Link

const result = await client.publish({
  exchangeName: 'orders.events',
  routingKey: 'orders.created',
  message: {
    orderId: 'ORD-1001',
    amount: 2500,
    status: 'created',
  },
  headers: {
    source: 'checkout-service',
    region: 'apac',
  },
});

console.log('Queues matched:', result.routedQueues);

The message body must be JSON-serializable. The broker commits routed message records to PostgreSQL before it asks the consumer manager to dispatch available messages. routedQueues reports the number of matched destination queues, not the number of consumers.

If no binding matches, the publish can succeed with zero routed queues. Confirm exchange and binding configuration when messages are not arriving.

9. Consume messagesCopy Anchor Link

A consumer registers against an existing queue. The broker returns a consumerTag and begins delivering available messages through the callback.

const subscription = await client.consume({
  queueName: 'orders.created',
  onMessage: async (message) => {
    console.log('Body:', message.body);
    console.log('Headers:', message.headers);
    console.log('Delivery count:', message.deliveryCount);

    await processOrder(message.body);
    await message.ack();
  },
});

console.log('Consumer tag:', subscription.consumerTag);

The current broker uses prefetch count 1 per connection and queue. The consumer manager keeps active subscriptions in memory; the subscription itself is not a durable database resource.

10. ACK: acknowledge successful processingCopy Anchor Link

Call message.ack() after your application has completed the work it considers successful:

await processOrder(message.body);
await message.ack();

The broker verifies that the delivery tag belongs to the current connection. A valid ACK removes the message record and releases the consumer's prefetch slot so another message can be dispatched.

Do not ACK before completing important side effects. MessageX does not provide a distributed transaction between the broker and your application database.

11. NACK: reject a deliveryCopy Anchor Link

Use message.nack() when processing fails:

try {
  await processOrder(message.body);
  await message.ack();
} catch (error) {
  console.error(error);
  await message.nack({ requeue: true });
}

A failed message can be delivered more than once. Make consumer handlers idempotent when processing external side effects.

12. Cancel a consumerCopy Anchor Link

await subscription.cancel();

Cancellation stops that consumer subscription. An already delivered in-flight message can still be settled using its ACK/NACK methods.

13. Delete queues and exchangesCopy Anchor Link

These operations are destructive. Deleting a queue also removes its associated message and binding records according to the database relationships.

await client.queue.delete('orders.created');
await client.exchange.delete('orders.events');

Delete only after confirming that no producer or consumer still depends on the resource.

14. Close the connection cleanlyCopy Anchor Link

await subscription.cancel();
await client.close();

For a process that manages multiple subscriptions, cancel each subscription before closing the client. On connection loss, the broker releases unsettled deliveries owned by that connection; the SDK does not automatically reconnect or restore subscriptions.

15. Client optionsCopy Anchor Link

16. SDK events and errorsCopy Anchor Link

The SDK extends Node.js EventEmitter.

• connect, disconnect, close — connection lifecycle.
• message — each delivered message.
• event — non-message broker events.
• warning — recoverable SDK/protocol warning.
• error — socket or protocol error; attach a listener to handle it.
• consumerError — an application message callback threw or rejected.

Exported error classes:

• MessageXError
• MessageXConnectionError
• MessageXTimeoutError
• MessageXBrokerError

17. Current limitationsCopy Anchor Link

The current SDK does not implement automatic reconnect, subscription restoration, browser/WebSocket transport, TLS, transactions, batch publishing, or management HTTP API methods. The broker's TCP protocol is not encrypted; use a private network, VPN, SSH tunnel, or other protected transport for remote deployments.

18. Examples and sourceCopy Anchor Link

• MessageX examples
• JavaScript SDK source
• SDK README
• npm: messagex-client