hermesjs

HermesJS

Build message-driven APIs with ease.

Install

npm install hermesjs

Example

Create a simple app to receive messages from a MQTT broker:

const Hermes = require('hermesjs');
const MqttAdapter = require('hermesjs-mqtt');

const app = new Hermes();

app.add(MqttAdapter, {
  host_url: 'mqtt://test.mosquitto.org',
  topics: 'hello/#'
});

app.use((message, next) => {
  console.log(message.payload);

  try {
    message.payload = JSON.parse(message.payload);
    next(null, message);
  } catch (e) {
    next('Message payload must be in JSON format');
  }
});

app.use((err, message, next) => {
  console.error(err);
  console.error('Received payload:');
  console.error(message.payload);
  next();
});

app.connect();

API

App

Constructor

const Hermes = require('hermesjs');
const app = new Hermes();

app.addAdapter(Adapter, options)

Adds a connection adapter. Adapters are built independently, as Node.js packages.

For instance, using a MQTT example:

const MqttAdapter = require('hermesjs-mqtt');

app.add(MqttAdapter, {
  host_url: 'mqtt://test.mosquitto.org',
  topics: 'hello/#'
});

app.use(...fn)

app.use(HermesRouter)

app.use(route, ...fn)

app.use(route, HermesRouter)

Use middlewares and routes. If you know how Connect/Express works, it's exactly the same, but instead of getting req and res, you get a message object.

Middlewares:

app.use((message, next) => {
  console.log(message.payload);
  // > '{"key": "value", "key2": 5}'
  message.payload = JSON.parse(message.payload);

  // Pass the modified message as the second
  // argument to forward it to the next middleware.
  next(null, message);
});

app.use((message, next) => {
  // Now `message.payload` is an object.
  console.log(message.payload);
  // > { key: 'value', key2: 5 }
  next();
});

Routes:

app.use('hello/:name', (message, next) => {
  console.log(`Hello ${message.params.name}!`);
  next();
});

HermesRouter

index.js

const hello = require('./routes/hello');

app.use('hello', hello);

routes/hello.js

const Router = require('hermesjs/lib/router');
const router = new Router();

router.use(':name', (message, next) => {
  console.log(`Hello ${message.params.name}!`);
  next();
});

router.use('world', (message, next) => {
  console.log(`Hello world!`);
  next();
});

module.exports = router;

Catch Errors

app.use((err, message, next) => {
  console.log('Handle error here...');
  next(err); // Optionally forward error to next middleware
});

app.useOutbound(...fn)

app.useOutbound(HermesRouter)

app.useOutbound(route, ...fn)

app.useOutbound(route, HermesRouter)

This is the same as app.use but for the outbound communication. The middlewares you specify here will be used before sending a message to the server or broker.

app.use((message, next) => {
  // Set `sentAt` attribute to every message before they are sent.
  message.payload.sentAt = Date.now();
  next(null, message);
});

app.send(payload, headers, topic)

app.send(HermesMessage)

It sends a message to the server. The message will go through all the outbound middlewares before it reaches the adapters.

app.send('Hello!', {}, 'hello/guest');

app.connect()

Starts the application and connects to the server using the adapters.

app.connect();

You can also use the app.listen() alias.

Message

message.reply(payload, headers, topic)

Replies back to the server.

app.use('hello/:name', (message, next) => {
  message.reply('Hello server!', undefined, `hello/${message.params.name}/response`);
});

message.params

Object containing all the params in the message topic, i.e.:

app.in.broker.use('hello/:name/:surname', (message, next) => {
  // Given the `hello/tim/burton` topic, the params will look like:
  // message.params == {
  //   name: 'tim',
  //   surname: 'burton'
  // }
}
});

Adapters

• MQTT adapter: https://github.com/hitchhq/hermes-mqtt
• AMQP adapter: https://github.com/hitchhq/hermes-amqp
• Socket.IO adapter: https://github.com/hitchhq/hermes-socketio

Author

Fran Méndez (fmvilas.com)