api.md

API

The evejs library contains the following:

• eve.Agent
• eve.system a default, global instance of a service manager, loaded with a LocalTransport.
• eve.ServiceManager construct a service manager.
• eve.TransportManager construct a service manager.
• eve.module.BabbleModule
• eve.module.PatternModule
• eve.module.RequestModule
• eve.module.RPCModule
• eve.transport.Transport (abstract prototype)
• eve.transport.AMQPTransport using the AMPQ protocol, for example via RabbitMQ servers.
• eve.transport.DistribusTransport using distribus.
• eve.transport.HTTPTransport for messaging over http,
• eve.transport.LocalTransport using a local, in process transport.
• eve.transport.PubNubTransport using PubNub.
• eve.transport.WebSocketTransport using web sockets.
• eve.transport.connection.Connection (abstract prototype)
• eve.transport.connection.AMQPConnection
• eve.transport.connection.DistribusConnection
• eve.transport.connection.HTTPConnection
• eve.transport.connection.LocalConnection
• eve.transport.connection.PubNubConnection
• eve.transport.connection.WebSocketConnection
• eve.util containing some utility functions.

Agent

Constructor:

var agent = new eve.Agent([id: string]);

Properties:

• Agent.ready : Promise
  A promise which resolves when all connections of the agent are ready.

Methods:

• Agent.send(to: string, message: string) : Promise
  Send a message to an other agent. Returns a promise which resolves when the message has been send. Parameter to is either:

  • A string "agentId", the id of the recipient. Will be send via the default transport or when there is no default transport via the first connected transport.
  • A string "protocol://networkId/agentId". This is a sharable identifier for an agent.

• Agent.extend(module: string | Array.<string> [, options: Object]): Agent
  Extend an agent with modules (mixins). Available modules:

  • 'pattern'
    Add support for pattern listening to an object. The agent will be extended with functions listen and unlisten. Cannot be used in conjunction with module 'babble'.

  • 'request'
    Add support for sending requests and immediately retrieving a reply. The agent will be extended with a function request.

  • 'babble'
    Babblify an agent. The babblified agent will be extended with functions ask, tell, and listen. Cannot be used in conjunction with module 'pattern'.

  The function extend returns the agent itself, which allows chaining multiple extenstions.

• Agent.loadModule(module: string | Array.<string> [, options: Object]): Module
  Load a module for an agent. This is the same as Agent.extend, except that the functions offered by the module are not attached to the Agent itself, but returned as object. This allows storing the new functions in a separate namespace, preventing conflicts between modules or the agent itself.

• Agent.receive(from: string, message: string)
  Receive a message from an agent. The method should be overloaded with an implementation doing something with incoming messages.

• Agent.connect(transport: Transport | Transport[] | string | string[] [, id: string]) : Promise<Agent, Error>
  Connect the agent to a transport instance or the id of a transport loaded in eve.system. Parameter transport can be an Array to connect to multiple transports at once. Eve comes with multiple message transport implementations (see Transports. By default, the agent connects to the transport with it's own id. It is possible to provide an alternative id instead by specifying this as second argument.

• Agent.disconnect([transport: Transport | Transport[] | string | string[]])
  Disconnect the agent from a transport or multiple transports. When parameter transport is not provided, the agent will be disconnected from all transports.

Static methods:

• Agent.registerModule(constructor: Function) A static function to register a new type of module. This module can then be loaded via Agent.extend() and Agent.loadModule().

ServiceManager

A ServiceManager is an object to manage services for the agents. Currently, the only available service is transports. Typically, a service manager is provided to an agent on construction, allowing the agent to connect to relevant services.

A ServiceManager is created as:

var services = new eve.ServiceManager();
var services = new eve.ServiceManager(config: Object);

Where config is an optional JSON object structured as:

{
  "transports": [
    {
      "type": STRING,
      ... transport dependent params
    },
    ...
  ],
  "timer": {
    "rate": NUMBER | "discrete"
  },
  "random": {
    "deterministic": BOOLEAN
  }
}

Properties:

• transports: TransportManager see TransportManager
• timer: hypertimer see Timer
• random: function see Random

Methods:

• clear()
  Close all configured services and remove them from the manager.
• init(config: Object)
  Initialize the service manager with services loaded from a configuration object. All current services are unloaded and removed.

TransportManager

A TransportManager manages transports for reuse by multiple agents.

A TransportManager is created as:

var services = new eve.TransportManager();
var services = new eve.TransportManager(config: Array);

Where config is an optional JSON array structured as:

[
  {
    "type": STRING,
    ... transport dependent params
  },
  ...
]

Available types: "amqp", "distribus", "local", "pubnub" and "http". The configuration for all available transports is described in detail on the page Transports.

Methods:

• add(transport: Transport) : Transport
  Add a loaded transport to the manager. Returns the transport itself.
• clear()
  Close all configured transports and remove them from the manager.
• get(id: string) : Transport
  Get a single transport by it's id. Throws an error when no matching transport is found.
• getAll() : Transport[]
  Get all transports.
• getByType([type: string]) : Transport[]
  Get transports. When optional parameter type is provided, the transports are filtered by this type. When there are no transports found, an empty array is returned. Available types are: 'amqp', 'distribus', 'local', 'pubnub'.
• load(config: Object) : Transport
  Load a transport based on JSON configuration. Returns the loaded transport

Static methods:

• TransportManager.registerType(constructor: Function) A static function to register a new type of transport. This transport can then be loaded via configuration. When called, the constructor must generate a transport which is an instance of Transport.

Transport

The library provides multiple Transport implementations: LocalTransport, PubNubTransport, AMQPTransport, and DistribusTransport. It is quite easy to implement a support for other messaging services.

Transport has the following API:

Constructor:

var transport = new Transport([config: Object]);

Methods:

• Transport.connect(id: string, receive: Function) : Connection
  Connect an agent with given id. When a message for the agent comes in, the callback function receive is invoked as receive(from: string, message: string). The method returns a Connection, which can be used to send messages.

• Transport.close() : Connection
  Close a transport. For example in case of an HTTPTransport, the server will be closed.

Connection

When a connection is opened by a Transport, a Connection is returned.

Constructor:

var connection = new Connection(transport: Transport, id: string, receive: function);

Properties:

• Transport.ready: Promise
  The ready state of the transport. When ready, the properties Promise resolves.

Methods:

• Transport.close()
  Close the connection.
• Transport.send(to: string, message: string) : Promise
  Send a message via the transport.