transaction-manager

Simple transaction manager for json messages

Installation

`` bash
npm install --save transaction-manager
`

Usage example

` js
const TransactionManager = require("../index.js");

//Use websocket as transport
var tm = new TransactionManager(websocket);

//Add listeners for commands
tm
.on("cmd",(cmd)=> {
console.log("got cmd", cmd.name);
switch(cmd.name)
{
case "..." :
cmd.accept(...);
break;
case "..." :
cmd.reject(...);
break;
}
})
.on("event",(event)=> {
console.log("got event", event.name);
});

//Send new command
tm.cmd("cmd_name", cmd_data)
.then((data) => {
console.log("command accepted with data", data);
})
.reject((data) => {
console.log("command accepted with data", data);
});

tm.event("event_name");
`

$3

It is possible to provide a namespace attribute the command and events so you can route them easily between different listeners.

You can either provide a third parameter to the cmd(name,data,namespace) and event(name,data,namespace) or create a Namespace object that will handle internals for you on both sending and receiving:

` js
var ns1 = tm1.namespace("ns");
var ns2 = tm2.namespace("ns");

ns2.on("cmd",(cmd)=> {
console.log("ns2::got command", cmd.name);
cmd.accept("accepted");
});


ns1.cmd("test_namespace", { dummy: 1})
.then(() => {
console.log("ns1::command accepted");
})
.catch(console.error);

`

Note that if a namespace has been created for a received message, the event will not be emited to the main TransactionManager object but only to the registered Namespace

Wire protocol

The transaction manager uses a JSON based message format to exchange data between both ends (using WebSockets for example).

The base message will be a json object with a type property:

` json
{
"type" : "cmd"
}
`

There are three different message types allowed in this specification: cmd, response and event.

$3

The command message is a json object which type is “cmd”.It is used when the sending side expect a response from the other side as a result of this command.

Appart of the cmd attribute, it also contain the following attributes:

` json
{
"type" : "cmd",
"transId": 0,
"name" : "command_name",
"data" : ...
}
`

- type (String): “cmd”
- transId (Integer) : Unique id for this command transaction
- name (String): Command name
- data (String | Date | Array | Object) : custom command data

$3

The command message is a json object which type is “response”. It is used to accept a command sent by the other peer and pass some custom data associated to the response.

Apart of the cmd attribute, it also contain the following attributes:

` json
{
"type" : "response",
"transId" : 0,
"data" : ...
}
`

- type (String): “response”
- transId (Integer) : value from the command this response belongs to
- data (String | Date | Array | Object) : custom response data

$3

The command message is a json object which type is “error”. It is used to reject a command sent by the other peer and pass some custom data associated to the error.

Apart of the cmd attribute, it also contain the following attributes:

` json
{
"type" : "error",
"transId" : 0,
"data" : ...
}
`

- type (String): “error”
- transId (Integer) : value from the command this error belongs to
- data (String | Date | Array | Object) : custom error data


For each command, there must be a single response or error message matching the transaction id of the command.

$3

Event messages are used when the sending side does not expect any kind of response back and has a type of “event”. It has the following attributes:

` json
{
"type": "event",
"name": "event_name",
"data": ...
}
``

- type (String): “event”
- name (String): Event name
- data (String | Date | Array | Object) : custom event data

Note that the event message does not have any transaction id as it is not meant to be acknowledged by the receiving side.

License

MIT