README
messenger
This is a Req/Rep
Pub/Sub
library for the browser.
Features
Messaging between ...
- components in one window
- a main window and iframes
- iframes in one window
Caveats
The following messaging are not supported:
- cross-origin
- multiple main windows
Installation
via npm:
npm install knowledgecode@messenger --save
This library assumes Promise
is available. Running it on unsupported browsers, install a polyfill beforehand.
Usage
ES Modules:
import messenger from './esm/messenger.es.js';
messenger.send('topic', { msg: 'hello' });
Manually:
<script src="./messenger.js"></script>
<script>
messenger.send('topic', { msg: 'hello' });
</script>
API
send(topic, data[, timeout])
- {string} topic - topic name
- {Object} data - an object to send
- {number} [timeout] - reply timeout [ms]
Send a message (some object) to a topic. This method will return Promise
. The 3rd parameter, timeout
, is optional. If omit it or set to 0
, the Promise
will forever wait for reply from the other.
bind(topic, listener)
- {string} topic - topic name
- {Function} listener - a listener to receive messages, or null
Register a listener to wait for message on a topic. The topic name needs to be unique, listeners other than the first cannot bind on the same topic name. To unbind, call the function that this method will return.
publish(topic, data)
- {string} topic - topic name
- {Object} data - an object to publish
Publish a message (some object) to all the subscribers on a topic. This method won't wait for reply from the subscribers, and won't be failed even there is no subscriber there.
subscribe(topic, listener)
- {string} topic - topic name
- {Function} listener - a listener to receive delivered messages
Subscribe message on a topic. To unsubscribe, call the function that this method will return.
Req / Rep
In Req / Rep model, we use send()
and bind()
.
At first, using the bind()
, server-side
waits for messages from clients
, with a topic, "addition":
messenger.bind('addition', data => {
return new Promise(resolve => {
resolve(data.x + data.y);
});
});
The Promise
may be omitted:
messenger.bind('addition', data => {
return data.x + data.y;
});
Client-side
sends a message to the topic. If no one is waiting for messages with the topic, the send()
will be failed (Promise
will be rejected).
messenger.send('addition', {
x: 2, y: 3
}).then(rep => {
console.log(rep); // 5
});
Use a returned function to unbind the topic.
const unbind = messenger.bind('addition', data => {
return data.x + data.y;
});
// Unbind the "addition" topic.
unbind();
Pub / Sub
In Pub / Sub model, we use publish()
and subscribe()
.
Use subscribe()
to subscribe to a topic.
messenger.subscribe('input', data => {
console.log(`The ${data.key} is input!`); // The h key is input!
});
Use publish()
to publish a message to a topic (one or more subscribers). Even there is no subscriber, this method won't be failed. Also this method won't receive any replies from subscribers.
messenger.publish('input', {
key: 'h', shift: false, ctrl: true
});
Use a returned function to unsubscribe from the topic.
const unsubscribe = messenger.subscribe('input', data => {
console.log(`The ${data.key} is input!`); // The h key is input!
});
// Unsubscribe the "input" topic.
unsubscribe();
Browser support
Chrome, Firefox, Safari, Edge, IE9+
License
MIT