Skip to content
Two small helper methods that simplify communication between nodes in different subtrees of the browser DOM.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src
test
.editorconfig
.gitignore
.npmignore
.travis.yml
LICENSE.txt
Makefile
README.md
package.json
rollup.config.js
yarn.lock

README.md

send-and-receive

Travis build status no dependencies license

Two small helper methods that simplify communication between nodes in different subtrees of the browser DOM.

See it in action in this little JS Bin demo showing the basics (run with JS enabled). There's also a more advanced version available.

Under the hood, send() dispatches instances of CustomEvent, using window as the event target. receive() simply listens on window for dispatched events.

Note: IE 9/10/11 has only partial support for the CustomEvent interface. You can use a polyfill like krambuhl/custom-event-polyfill to fix it.

Installation

Install via npm:

% npm install send-and-receive

Or via yarn:

% yarn add send-and-receive

The UMD build is also available on unpkg, adding a sar object to the global scope.

<script src="https://unpkg.com/send-and-receive/dist/umd.min.js"></script>

Usage

Using a browser packager like Webpack or Rollup, you can cherry-pick only the functions you're interested in:

import { send, receive } from 'send-and-receive';

receive('my:event', (data) => {
  // do something with data
});

send('my:event', data);

If using the UMD build added via <script src>, call the methods on the exposed sar object:

<script>
  sar.send(/* ... */);
  sar.receive(/*... */);
</script>

Here is the complete API reference:

sar.send

send(string event[, any data])

Dispatches an event with optional data.

sar.send('player:play', {
  src: 'https://example.org/song.mp3',
  title: 'Example song'
});

sar.receive

object receive(string event, function callback[, object options])

Listens on dispatched events of the specified type and invokes callback(data) when it receives one.

const subscription = sar.receive('player:play', (data) => {
  console.log('Now playing ' + data.title);
  somePlayer.play(data.src);
});

Use the returned object to retrieve some metadata or to cancel receiving further events:

subscription.received  //=> How often has the event been received?
subscription.remaining //=> How many remaining events can it receive?

subscription.cancelled //=> Did we completely opt out of receiving further events?
subscription.cancel()  //=> Unlisten from the event and set cancelled status.

subscription.paused    //=> Did we temporarily stop receiving further events?
subscription.pause()   //=> Pause listening and set paused status.
subscription.resume()  //=> Resume listening and unset paused status.

Note that both subscription.pause() and subscription.resume() will throw an error if the subscription has been cancelled.

By default, the number of events it can receive is not limited, which means subscription.remaining will always return positive infinity.

Besides calling subscription.cancel() in order to stop listening to further events, you can also restrict the number of times the event will be received by supplying the limit option:

sar.receive('player:play', callback, { limit: 1 });

Here, after the event has been received once, it will be auto-cancelled. Furthermore, the subscription's received property will have changed from 0 to 1, and the remaining property from 1 to 0.

sar.receiveOnce (bonus method)

object receiveOnce(string event, function callback)

A convenience method for the case when you want to receive the event only once.

sar.receiveOnce('player:play', callback);

This is semantically the same as the last example above.

Contributing

Here's a quick guide:

  1. Fork the repo and make install (assumes yarn is installed).
  2. Run the tests. We only take pull requests with passing tests, and it's great to know that you have a clean slate: make test.
  3. Add a test for your change. Only refactoring and documentation changes require no new tests. If you are adding functionality or are fixing a bug, we need a test!
  4. Make the test pass.
  5. Push to your fork and submit a pull request.

Licence

Released under The MIT License.

You can’t perform that action at this time.