Two small helper methods that simplify communication between nodes in different subtrees of the browser DOM.
Starting with version 1.3, the library is written in TypeScript and thus the package includes TypeScript typings.
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.
Using a browser packager like Webpack or Rollup, you can cherry-pick only the functions you're interested in:
If using the UMD build added via
<script src>, call the methods on the exposed
Here is the complete API reference:
sendtype: string, data?: any: void
Dispatches an event of the specified
type with the specified
receivetype: string, callback:void, options?: : Subscription
Listens on dispatched events of the specified
type and, when it receives one, invokes
callback with the data passed when sending.
Use the returned
Subscription 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.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.
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
sar.receive'player:play', callback, ;
Here, after the event has been received once, it will be auto-cancelled. Furthermore, the subscription's
received property will have changed from
1, and the
remaining property from
receiveOncetype: string, callback:void: Subscription
A convenience method for the case when you want to receive the event only once.
This is semantically the same as the last example above.
A convenience method to create both a sender function and a receiver function for the specified
This is especially useful when coding in TypeScript, as it allows strict-typing the
// a.ts;;;// later on (button click, etc.)sendPlay;
Optionally, you can pass a function as the second argument which transforms the arguments passed to
send into the data structure supplied to the
sar.createtype: string, buildData:any:
;;// send...navigateTo"/foo", ;// receive...receiveNavigateTohistoryurl;
Here's a quick guide:
- Fork the repo and
make install(assumes yarn is installed).
- Run the tests. We only take pull requests with passing tests, and it's great to know that you have a clean slate:
- 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!
- Make the test pass.
- Push to your fork and submit a pull request.
Released under The MIT License.