tableflip/postmsg-rpc

Name: postmsg-rpc

Owner: TABLEFLIP

Description: Tiny RPC over window.postMessage library

Created: 2017-12-13 11:41:57.0

Updated: 2018-05-22 22:05:43.0

Pushed: 2018-03-21 15:06:25.0

Homepage: http://npm.im/postmsg-rpc

Size: 96

Language: JavaScript

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

postmsg-rpc

Tiny RPC over window.postMessage library

Install

install postmsg-rpc

Usage

In the window you want to call to (the “server”):

rt { expose } from 'postmsg-rpc'

t fruitService = {
tFruits: (/* arg0, arg1, ... */) => new Promise(/* ... */)


xpose this function for RPC from other windows
se('getFruits', fruitService.getFruits)

In the other window (the “client”):

rt { call } from 'postmsg-rpc'

all the exposed function
t fruits = await call('getFruits'/*, arg0, arg1, ... */)

Advanced usage

Use caller to create a function that uses postMessage to call an exposed function in a different window. It also allows you to pass options (see docs below).

rt { caller } from 'postmsg-rpc'

t getFruits = caller('getFruits'/*, options */)

ait for the fruits to ripen
t fruits = await getFruits(/*, arg0, arg1, ... */)

API

expose(funcName, func, options)

Expose func as funcName for RPC from other windows. Assumes that func returns a promise.

• funcName - the name of the function called on the client
• func - the function that should be called. Should be synchronous or return a promise. For callbacks, pass options.isCallback
• options.targetOrigin - passed to postMessage (see postMessage docs for more info)
  • default '*'
• options.isCallback - set to true if func takes a node style callback instead of returning a promise
  • default false
• options.postMessage - function that posts a message. It is passed two parameters, data and options.targetOrigin. e.g. document.querySelector('iframe').contentWindow.postMessage for exposing functions to an iframe or window.parent.postMessage for exposing functions from an iframe to a parent window
  • default window.postMessage

The following options are for use with other similar messaging systems, for example when using message passing in browser extensions or for testing:

• options.addListener - function that adds a listener. It is passed two parameters, the event name (always “message”) and a handler function
  • default window.addEventListener
• options.removeListener - function that removes a listener. It is passed two parameters, the event name (always “message”) and a handler function
  • default window.removeEventListener
• options.getMessageData - a function that extracts data from the arguments passed to a message event handler
  • default (e) => e.data

Returns an object with a close method to stop the server from listening to messages.

call(funcName, <arg0>, <arg1>, ...)

Call an exposed function in a different window.

• funcName - the name of the function to call

Returns a Promise, so can be awaited or used in the usual way (then/catch). The Promise returned has an additional property cancel which can be called to cancel an in flight request e.g.

t fruitPromise = call('getFruits')

tPromise.cancel()

{
ait fruitPromise
tch (err) {
 (err.isCanceled) {
console.log('function call canceled')

caller(funcName, options)

Create a function that uses postMessage to call an exposed function in a different window.

• funcName - the name of the function to call
• options.targetOrigin - passed to postMessage (see postMessage docs for more info)
  • default '*'
• options.postMessage - function that posts a message. It is passed two parameters, data and options.targetOrigin. e.g. document.querySelector('iframe').contentWindow.postMessage for calling functions in an iframe or window.parent.postMessage for calling functions in a parent window from an iframe
  • default window.postMessage

The following options are for use with other similar messaging systems, for example when using message passing in browser extensions or for testing:

• options.addListener - function that adds a listener. It is passed two parameters, the event name (always “message”) and a handler function
  • default window.addEventListener
• options.removeListener - function that removes a listener. It is passed two parameters, the event name (always “message”) and a handler function
  • default window.removeEventListener
• options.getMessageData - a function that extracts data from the arguments passed to a message event handler
  • default (e) => e.data

Contribute

Feel free to dive in! Open an issue or submit PRs.

License

MIT © Alan Shaw

---

A (?°?°???TABLEFLIP side project.