Grit MongoDB Event Machine

Create, Fetch, Acquire and Handle - events being saved as MongoDB documents.

What is MongoDB Event Machine

MongoDB Event Machine is a class to instantiate event producers and consumers. It can be used to develop all kinds of event-based systems, for example an engine to execute BPMN processes. When initialized with event handlers it functions as an event-consumer, otherwise as an event-producer. In both cases a connection to a MongoDB database is opened.

How does MongoDB Event Machine work under the hood

When created with handlers - once an instance of the class is listening - it creates a backoff function which checks for new events to handle (it is looking for events which were not yet acquired). Whenever a new (not acquired) event is found, the machine tries to acquire it. It could happen that another machine instance is also trying to acquire it but only one will win. Whoever acquires the event will handle it and when handled set it to status: handled. A producer can be used to create new events.

How to install

$ npm install @data-processing.solutions/grit-mongodb-eventmachine

or

$ yarn add @data-processing.solutions/grit-mongodb-eventmachine

Examples

Require

const EventMachine = require('@data-processing.solutions/grit-mongodb-eventmachine');

Producer

const eventMachine = new EventMachine({
  dbUrl: 'mongodb://localhost:27017',
  DEFAULT_PRIORITY: 50
});

eventMachine.listen().catch(err => console.error(err));

for (let i = 0; i <= 1; i++) {
  eventMachine.createNewEvent({
    intent: 'CREATE_SOMETHING',
    time: new Date().getTime() - 1
  });
}

When producing events, note that the intent is the name of the handler method you provide your consumer with. time is the desired time of executing this event, the (current timestamp - 1) should make it being picked up right away (if there are no other events, which are waiting for longer, or have higher priority)

Consumer

const eventMachine = new EventMachine(
  {
    dbUrl: 'mongodb://localhost:27017',
    DEFAULT_PRIORITY: 50,
    batchSize: 1, // Optional (default: 1), set how many events you want to fetch, acquire and handle at once
    intentScope: ['CREATE_SOMETHING'] // Optional, this worker/consumer only handles events with the intent CREATE_SOMETHING, [] means nothing will be handled, not defining it means all handlers will be handled
  },
  {
    CREATE_SOMETHING: event => {
      console.log('create something', event._id);
    }
  }
);

eventMachine.listen().catch(err => console.error(err));

When consuming events, note that you can define batchSize to acquire and handle multiple events at once, the default is 1. You can also define an intentScope so you might have an instance of the Event Machine only handling certain events, even though it is capable of more, handler-wise. This could be used to scale (TODO: elaborate).

Directly access the database schema

Whenever you have the need to read an existing event directly, you can invoke mongoose methods on the Event Model, like described following:

const Event = require('@grit/mongodb-eventmachine/lib/schemas/Event');

const specificEvent = await Event.findById('...');