eq8-core

EQuateJS Core API Library - A loose interface for CQRS/ES

Overview

The core building blocks are:

• commands in the form of events for updating the application state; and,
• queries are used for returning the current state of the application.

The core API provides an ability to register handlers for events and queries, but more importantly, it also allows adding new registrars:

• registrars are layers of abstractions that map to sets of events or queries.

Contents

• Installation
• Events
  • Event: 'dispatch'
  • Event: 'subscribe'
  • Event: 'register:registry'
• Constructor
  • Parameters
• Methods
  • Core#dispatch(e, done)
    • Parameters
  • Core#subscribe(q, done)
    • Parameters
  • Core#chainListener(e, listener, done)
    • Parameters
  • Core#addRegistrar(registrars, done)
    • Parameters
  • Core#register(registries, done)
    • Parameters
• Appendices

Installation

npm install --save eq8-core

Events

Basically, eq8-core extends the EventEmitter class and has the following events:

Event: 'dispatch'

Emitted when Core#dispatch gets called

Event: 'subscribe'

Emitted when Core#subscribe gets called

Event: 'register:registry'

Emitted when Core#register gets called for a specific registry

Constructor

var Core = require('eq8-core');
var api = new Core(options);

Parameters

• options is an optional object
  • logger is a winston.Logger options object
  • on is an object with the following properties:
    • dispatch is an array of dispatch event listeners
    • subscribe is an array of subscribe event listeners

Methods

Core#dispatch(e, done)

Emits a dispatch event and passes the parameters e and done to the event handler

Parameters

• e is an arbitrary object to represent a command event

Core#subscribe(q, done)

Emits a subscribe event and passes the parameters q and done to the event handler

Parameters

• q is an arbitrary object to represent a query event
• done is an arbitrary callback function but conventionally takes an error-first argument: var done = function(err, ...){ ...}

Core#chainListener(e, listener, done)

Similar to EventEmitter.addListener except it removes the previously chained listener and adds it as a prior argument for the newly chained listener.

For example:

var Core = require('eq8-core');
var api = new Core();
var async = require('async');

function bottomOfStack(e, done) {
  console.log('bottomOfStack', e);
  done();
}

function topOfStack(e, done, prior) {
  console.log('topOfStack:', e);
  prior(e, done);
}

async.series([
  function(done) {
    api.chainListener('dispatch', bottomOfStack, done);
  },
  function(done) {
    api.chainListener('dispatch', topOfStack, done); 
  }
], function seriesDone() {
  api.dispatch('someEvent');
});

Result:

topOfStack: someEvent
bottomOfStack: someEvent

Parameters

• e is the event name - see list of events above
• listener is the handler for the event
• done is the callback function that gets called after the listener chaining lifecycle

Core#addRegistrar(registrars, done)

Chains a listener for register:<registryKey> events that occur during a Core#register method call

For example:

var Core = require('eq8-core');
var api = new Core();

var registrars = {
  'actions': function createAction(actions) {
    console.log('create actions:', actions);
  },
  'views': function createView(views) {
    console.log('create views:', views);
  }
};
api.addRegistrar(registrars);

var registries = {
  'actions': [
    {e: 'e1'},
    {e: 'e2'}
  ],
  'views': [
    {q: 'q1'},
    {q: 'q2'}
  ]
};
api.register(registries);

Result:

create actions: [ { e: 'e1' }, { e: 'e2' } ]
create views: [ { q: 'q1' }, { q: 'q2' } ]

Parameters

• registrars is an object that takes the form:

{
  'registryKey<n>': function handler(registryInitObj){},
  ...
}

• done is an optional error-first callback function that gets called after the registrar adding lifecycle

Core#register(registries, done)

Triggers a register:<registryKey> event for each registryKey<n> in registries

NOTE: See usage example in Core#addRegister

Parameters

• registries is an object that takes the form:

{
  registryKey1: registryInitObj1,
  ...
}

• done is an optional error-first callback function that gets called after the registration lifecycle

Appendices

• [Contributing] (./CONTRIBUTING.md)
• [License] (./LICENSE)