burrata
v0.5.0
Published
Robust, developer-friendly postMessage.
Downloads
12
Readme
Burrata
Robust, developer-friendly postMessage
.
Synopsis
Burrata has two modes:
Client-server mode assumes that you've got one server document containing one or more client iframes that connect to it. This mode also makes it easy to broadcast a message to all clients.
Peer-to-peer mode sets up communication between exactly two iframes.
In both modes, bidirectional communication is fully supported. Servers, clients, and peers can all define and invoke commands. The distinction between both modes exists purely to accommodate common use cases.
Installation
Just use npm (or Yarn) to install Burrata:
npm install burrata
Under node_modules/burrata
, you'll then find:
dist/burrata.js
: the unminified UMD bundle;dist/burrata.min.js
: the minified UMD bundle;src/*.js
: the ECMAScript 2018 source files.
To get started, load dist/burrata.js
using a <script>
tag, which will make
burrata
available on the window
:
<script src="burrata.js"></script>
You can also load the bundles directly from unpkg or use your favorite bundler to build from source.
Usage
In both modes, it is recommended that you enter a meaningful value for ns
(namespace) and id
(node identifier) where applicable. In the examples below,
we'll use dummy values.
Client-Server Mode
In the top-level HTML document, create an instance of
Server
. Then, register some command handlers; in this case, we're creating a simpleecho
command. Finally, callinit()
to start listening for commands from clients.const ns = 'testing' // Pick a namespace. const server = new burrata.Server({ ns }) // Register the "echo" command, which sends back the value of the "msg" arg. server.setHandler('echo', async ({ msg }) => { return msg }) // Start listening for commands. server.init()
Add an
<iframe>
for each client. Inside the iframe, set up the client.const ns = 'testing' // The same namespace as for the server. const id = 'client_1' // A unique ID for this client. const client = new burrata.Client({ ns, id }) // Connect to server. await client.init()
Now that everything is wired up, make the client call its server's
echo
command.const response = await client.send('echo', { msg: 'Hello!' }) console.log('Response: ' + response)
Clients can define command handlers using the same setHandler()
function.
Please consult the demo for more examples.
Peer-to-Peer Mode
In peer-to-peer mode, you create two instances of burrata.Peer
and await their
init()
call. Like in client-server mode, you can use setHandler()
to define
commands on peers, and send()
to invoke them.
In most cases, you will also want to pass two additional options to the Peer
constructor, alongside ns
and id
:
source
: theWindow
on whichmessage
events for the peer will arive;target
: theWindow
on which the peer will callpostMessage()
.
Both options default to the current window
, which allows two peers to talk to
one another without creating iframes.
To find out more about peer-to-peer mode, please take a look at the demo.
Known Issues
- Coverage reporting is partly broken. Actual coverage is higher.
Author
License
MIT