This repository contains JavaScript client for both NodeJS and the Browser for Emitter (see also on Emitter GitHub). Emitter is an open-source real-time communication service for connecting online devices. At its core, emitter.io is a distributed, scalable and fault-tolerant publish-subscribe messaging platform based on MQTT protocol and featuring message storage.
Installation
Emitter for NodeJS:
npm install emitter-io --save
Emitter for the Browser:
Example
// connect to emitter.io and get the client
var client = emitter.connect(); // or: require('emitter-io') on NodeJS
// once we're connected, subscribe to the 'chat' channel
client.subscribe({
key: "<channel key>",
channel: "chat"
});
// on every message, print it out
client.on('message', function(msg){
console.log( msg.asString() );
});
// publish a message to the chat channel
client.publish({
key: "<channel key>",
channel: "chat/my_name",
message: "hello, emitter!"
});
API
connect()
Emitter()
Emitter#disconnect()
Emitter#publish()
Emitter#subscribe()
Emitter#unsubscribe()
Emitter#keygen()
Emitter#link()
Emitter#me()
Emitter#presence()
EmitterMessage()
EmitterMessage#asString()
EmitterMessage#asBinary()
EmitterMessage#asObject()
connect(host: string, port: number)
Connects to the emitter api broker specified by the given url and options and returns an Emitter instance. The URL can be on the following protocols: 'mqtt', 'mqtts', 'tcp', 'tls', 'ws', 'wss'. The URL can also be an object as returned by URL.parse()
, in that case the two objects are merged, i.e. you can pass a single object with both the URL and the connect options.
Emitter()
The Emitter
class wraps a client connection to an emitter.io MQTT broker over an arbitrary transport method (TCP, TLS, WebSocket, ecc). It automatically handles the following by with help of MQTT.js client:
- Regular server pings
- QoS flow
- Automatic reconnections
- Start publishing before being connected
'connect'
Event function(connack) {}
Emitted on successful (re)connection (i.e. connack rc=0).
connack
received connack packet. Whenclean
connection option isfalse
and server has a previous session forclientId
connection option, thenconnack.sessionPresent
flag istrue
. When that is the case, you may rely on stored session and prefer not to send subscribe commands for the client.
'disconnect'
Event function() {}
Emitted after a disconnection.
'offline'
Event function() {}
Emitted when the client goes offline.
'error'
Event function(error) {}
Emitted when the client cannot connect (i.e. connack rc != 0) or when a parsing error occurs.
'keygen'
Event function(keyJson) {}
Emitted when the client generate a key to a channel using Emitter#keygen()
function.
'message'
Event function(message) {}
Emitted when the client receives a message packet. The message object will be of EmitterMessage class, encapsulating the channel and the payload.
Emitter#disconnect()
Disconnects from the remote broker
Emitter#link({ key: string; channel: string; name: string; private: boolean; message: any; ttl?: number; me?: boolean; })
Creates a 2-character link to a channel. The channel may be private. For more information about this feature, see Emitter: Simplify Client/Server and IoT Apps with Links and Private Links (on YouTube) and the Emitter Pull Request (on GitHub).
key
is security key to use for the operation,String
channel
is the channel string to publish to,String
name
is the 2-character name of the link,String
private
requests the creation of a private channel,Boolean
message
is the message to publish,Buffer
orString
ttl
is the time to live of the messages that will be sent through the link,Number
.me
tells whether the messages sent through the link should be also sent to the publisher,Boolean
. By default it is set totrue
.
See also publishWithLink()
.
Emitter#publish({ key: string; channel: string; message: any; ttl?: number; me?: boolean; })
Publishes a message to a channel
key
is security key to use for the operation,String
channel
is the channel string to publish to,String
message
is the message to publish,Buffer
orString
ttl
is the time to live of the message,Number
me
tells whether the messages should be also sent to the publisher,Boolean
. By default it is set totrue
.
Emitter#publishWithLink({ link: string; message: any; })
Publishes a message to a link.
link
is the name of the link,String
message
is the message to publish,Buffer
orString
See also link()
.
Emitter#subscribe({ key: string; channel: string; })
Subscribes to a channel
key
is security key to use for the operation,String
channel
is the channel string to subscribe to,String
Emitter#unsubscribe({ key: string; channel: string; })
Unsubscribes from a channel
key
is security key to use for the operation,String
channel
is the channel string to unsubscribe from,String
Emitter#keygen({ key: string; channel: string; type: string; ttl: number; })
Sends a key generation request to the server.
key
is master/secret key to use for the operation,String
channel
is the channel string to generate a key for,String
type
the type of the key to generate. Possible options includer
for read-only,w
for write-only,p
for presence only andrw
for read-write keys (In addition torw
, you can use any combination ofr
,w
andp
for key generation),String
ttl
is the time-to-live of the key, in seconds.
Emitter#me()
Retrieves information about the underlying client connection. Information includes the client ID and the links created by the client.
Emitter#presence({ key: string; channel: string; status: boolean; changes: boolean; })
Requests the presence for a particular channel.
key
is master/secret key to use for the operation,String
channel
is the channel string to generate a key for,String
status
whether the current state should be retrieved or notchanges
whether the future changes should be received or not
EmitterMessage()
The EmitterMessage
class wraps a message received from the broker. It contains several properties:
channel
is channel the message was published to,String
binary
is the buffer associated with the payload,Buffer
EmitterMessage#asString()
Returns the payload as a utf-8 String
.
EmitterMessage#asBinary()
Returns the payload as the Buffer
.
EmitterMessage#asObject()
Returns the payload as JSON-deserialized Object
.
License
The MIT License (MIT) Copyright (c) 2016 Misakai Ltd.