Class Network<MessageTypes>

Networks are required to have a name which represents a short name that describes the network. Transports can use this name to automatically find peers with the same network name.

Networks can be joined and left as needed. The same app is encouraged to only join the network once and then share an instance of Network as needed.

const net = new Network({
  name: 'name-of-network',

  transports: [
     new MachineLocalNetwork()
  ]
});

await net.join();

Nodes of the network

When a network is joined this instance will start emitting events about what nodes are available on the network. It is recommended to use onNodeAvailable and onNodeUnavailable to keep track of what nodes the instance can communicate with.

It's possible to iterate over a snapshot of nodes using nodes.

Sending and receiving messages

Messaging in Ataraxia does not guarantee delivery, messages may or may not reach their intended targets.

The onMessage event can be used to listen to events from any node, which is recommended to do when building something that deals with many nodes. If you're only interested in messages from a single node, Node.onMessage can be used instead.

To send a message to a single node use Node.send.

It is possible to broadcast a message to all the known nodes via broadcast, but as with regular messages no delivery is guaranteed and large broadcasts are discouraged.

Groups

Groups are a way to create named area of the network that nodes can join and leave as needed. Broadcasting a message on an group will only send it to known members of the groups.

const group = new NamedGroup(net, 'name-of-group');

// Groups need to be joined
await group.join();

// Broadcast to the known members
await group.broadcast('typeOfMessage', dataOfMessage);

Typing of messages

The network and groups can be typed when using TypeScript.

The types are defined as an interface with the keys representing the message types tied to the type of message:

interface EchoMessages {
  'namespace:echo': { message: string };
  'namespace:echo-reply': { reply: string };
}

An group can then be typed via:

const group: Group<EchoMessages> = new NamedGroup<EchoMessage>(net, 'echo');

This will help TypeScript validate messages that are sent:

// TypeScript will allow this
group.broadcast('namespace:echo', { message: 'Test' });

// TypeScript will not allow these
group.broadcast('namespace:echo', { msg: 'Test' });
group.broadcast('namespace:e', { message: 'Test' });

The same is true for listeners:

group.onMessage(msg => {
  if(msg.type === 'namespace:echo') {
     // In here msg.data will be of the type { message: string }
     const data = msg.data;
     msg.source.send('namespace:echo-reply', { reply: data.message })
       .catch(errorHandler);
  } else if(msg.type === 'namespace:echo-reply') {
    // msg.data will be { reply: string }
  } else {
     // No message of this type
  }
});