Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/emitter-io/javascript
Nodejs MQTT client for emitter.io.
https://github.com/emitter-io/javascript
emitter mqtt-client sdk
Last synced: 5 days ago
JSON representation
Nodejs MQTT client for emitter.io.
- Host: GitHub
- URL: https://github.com/emitter-io/javascript
- Owner: emitter-io
- Created: 2016-04-01T09:59:37.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2020-08-01T02:39:04.000Z (over 4 years ago)
- Last Synced: 2024-11-02T13:05:31.638Z (11 days ago)
- Topics: emitter, mqtt-client, sdk
- Language: TypeScript
- Size: 761 KB
- Stars: 30
- Watchers: 6
- Forks: 17
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
Awesome Lists containing this project
README
[](https://nodei.co/npm/emitter-io/)
[](https://nodei.co/npm/emitter-io/)
This repository contains JavaScript client for both NodeJS and the Browser for [Emitter](https://emitter.io) (see also on [Emitter GitHub](https://github.com/emitter-io/emitter)). 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](#install)
* [Example](#example)
* [API](#api)
* [License](#license)
Emitter for NodeJS:
```
npm install emitter-io --save
```
Emitter for the Browser:
* [http://cdn.emitter.io/js/emitter.js](http://cdn.emitter.io/js/emitter.js)
* [http://cdn.emitter.io/js/emitter.min.js](http://cdn.emitter.io/js/emitter.min.js)
```
// 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: "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: "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](#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()`](http://nodejs.org/api/url.html#url_url_parse_urlstr_parsequerystring_slashesdenotehost), 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
#### Event `'connect'`
`function(connack) {}`
Emitted on successful (re)connection (i.e. connack rc=0).
* `connack` received connack packet. When `clean` connection option is `false` and server has a previous session
for `clientId` connection option, then `connack.sessionPresent` flag is `true`. When that is the case,
you may rely on stored session and prefer not to send subscribe commands for the client.
#### Event `'disconnect'`
`function() {}`
Emitted after a disconnection.
#### Event `'offline'`
`function() {}`
Emitted when the client goes offline.
#### Event `'error'`
`function(error) {}`
Emitted when the client cannot connect (i.e. connack rc != 0) or when a parsing error occurs.
#### Event `'keygen'`
`function(keyJson) {}`
Emitted when the client generate a key to a channel using Emitter#keygen() function.
### Event `'message'`
`function(message) {}`
Emitted when the client receives a message packet. The message object will be of [EmitterMessage](#message) 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)](https://youtu.be/_FgKiUlEb_s) and the [Emitter Pull Request (on GitHub)](https://github.com/emitter-io/emitter/pull/183).
* `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` or `String`
* `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 to `true`.
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` or `String`
* `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 to `true`.
-------------------------------------------------------
### 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` or `String`
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 include `r` for read-only, `w` for write-only, `p` for presence only and `rw` for read-write keys (In addition to `rw`, you can use any combination of `r`, `w` and `p` 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 not
* `changes` 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`.
The MIT License (MIT)
Copyright (c) 2016 Misakai Ltd.