JSPM – hermesjs@2.2.0

Package Exports

hermesjs
hermesjs/lib/adapter
hermesjs/lib/message
hermesjs/lib/router

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (hermesjs) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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)