node-mqlight (beta)

MQ Light is designed to allow applications to exchange discrete pieces of information in the form of messages. This might sound a lot like TCP/IP networking, and MQ Light does use TCP/IP under the covers, but MQ Light takes away much of the complexity and provides a higher level set of abstractions to build your applications with.

This Node.js module provides the high-level API by which you can interact with the MQ Light runtime.

Current Features:

• Send and receive arbitrary String and JSON objects between Node.js applications using an at-most-once quality of service.
• Includes samples to demonstrate API usage.

More functionality coming soon.

Getting Started

Install it in node.js:

npm install https://ibm.biz/node-mqlight

var mqlight = require('mqlight');

Then create some clients to send and receive messages:

var client = mqlight.createClient({
  clientId: 'client-id1'
});

var topic = "public";
client.on('connected', function() {
  client.send(topic, "Hello World!");
});

client.connect();

var client = mqlight.createClient({
  clientId: 'client-id2'
});

var address = "public";
client.on('connected', function() {
  client.subscribe(address);
  client.on('message', function(data, delivery) {
    console.log(data);
  });
});

client.connect();

API

mqlight.createClient([options])

Creates an MQ Light client instance.

• options, (Object) options for the client. Properties include:

  • service, (String) (required), the URL for the service to connect to.
  • id (String, default: AUTO_[0-9a-f]{7}), a unique identifier for this client.
  • user (String) (optional) user name for authentication
  • password (String) (optional) password for authentication

Returns Client object representing the client instance.

mqlight.Client.connect([callback])

Connects the MQ Light client instance to the service.

• callback - (Function) (optional) callback to be notified of errors & completion

mqlight.Client.send(topic, message [, options [, callback]])

Sends the given MQ Light message object to its address. String and Buffer messages will be sent and received as-is. Any other Object will be converted to JSON before sending and automatically parsed back into the same Object type when received.

• topic - (String) the topic to which the message will be sent.
• message - (String | Buffer | Object) the message body to be sent
• options - (Object) (optional) map of additional options for the send.
• callback - (Function) (optional) callback to be notified of errors & completion

mqlight.Client.subscribe(pattern [, share [,options [, callback]]])

Create a subscription and associates it with a pattern.

The pattern is matched against the address attribute of messages sent to the IBM MQ Light messaging service to determine whether a particular message will be delivered to a particular Destination.

• pattern - (String) used to match against the address attribute of messages to determine if a copy of the message should be received.
• share - (String) (optional) name for creating or joining a shared subscription for which messages are anycast between connected subscribers. If omitted defaults to unshared (e.g. private).
• options - (Object) (optional) map of additional options for the destination.
• callback - (Function) callback to be notified of errors & completion.

Returns the Client object that the subscribe was called on which will emit message events on arrival.

mqlight.Client.getId()

Returns the identifier associated with the client. This will either be what was passed in on the Client.createClient call or an autogenerated id.

mqlight.Client.getService()

Returns the URL of the service to which the client is currently connected to, or undefined if not connected.

mqlight.Client.getState()

Returns the current state of the client, which will be one of: 'connected', 'connecting', 'disconnected' or 'disconnecting'.

mqlight.Client.disconnect([callback])

Disconnects this Client from the messaging server and frees the system resources that it uses. Calling this method also implicitly closes any subscriptions that have been created using the client's Client.subscribe method.

Samples

To run the samples, install the module via npm and navigate to the mqlight/samples/ folder.

Usage:

Receiver Example:

Usage: recv.js [options] <address>
                          address: amqp://<domain>/<name>
                          (default amqp://localhost/public)

Options:
  -h, --help            show this help message and exit

Sender Example:

Usage: send.js [options] <msg_1> ... <msg_n>

Options:
  -h, --help            show this help message and exit
  -a ADDRESS, --address=ADDRESS
                        address: amqp://<domain>/<name>
                        (default amqp://localhost/public)
  -d NUM, --delay=NUM   add a NUM seconds time delay between each request

Release notes

0.1.0

• Initial beta release.
• Support for sending and receiving 'at-most-once' messages.
• Support for shared subscriptions.