@articulate/hermes

Event-sourced autonomous service toolkit for Node.js

Install

yarn add @articulate/hermes

Setup

Follow the setup instructions for Message DB to initialize the message store, or use this Docker image for local dev. Then provide connection options as below:

// server/lib/hermes.js

module.exports = require('@articulate/hermes')({
  connectionString: process.env.MESSAGE_STORE_URI
})

You'll need at least a connectionString, but see the following for the full list of available options:

• https://node-postgres.com/api/client
• https://node-postgres.com/api/pool

Note: You may alternatively specify the connection options using standard Postgres environment variables.

Documentation

See the full documentation here: https://articulate.github.io/hermes/

You can also host the docs locally by cloning the repo and running:

npm i docsify-cli -g
yarn docs

Local docs will then be available at: http://localhost:4000

Logging

Hermes uses the debug library to output raw logs. To turn on all of the logs, include the following environment variable:

DEBUG=hermes:*

When debugging locally, these additional variables may also help. See the debug docs for the full list of options.

DEBUG_COLORS=true
DEBUG_DEPTH=null
DEBUG_HIDE_DATE=true

Mocking

To help you test your autonomous services, Hermes ships with an in-memory substitute that passes the same test suite as the default Message DB implementation. Enable it with the { mock: true } flag. When enabled, Hermes will ignore any connection options specified, and will not connect to Postgres.

In addition, you may clear the in-memory store after each test using hermes.store.clear().

const hermes = require('@articulate/hermes')({
  mock: process.env.NODE_ENV === 'test'
})

afterEach(() => {
  hermes.store.clear()
})

Read more about testing with Hermes in the section on entity caching.

Not for production use. The in-memory substitute implementation is only intended for testing.

Tests

The Hermes tests run in Travis CI, but you can run the tests locally with docker-compose like so:

docker-compose build
docker-compose run --rm test