postmsg-rpc

Tiny RPC over window.postMessage library

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
postmsg-rpc
2722.4.05 years ago5 years agoMinified + gzip package size for postmsg-rpc in KB

Readme

postmsg-rpc
Build Status dependencies Status JavaScript Style Guide
Tiny RPC over window.postMessage library

Install

npm install postmsg-rpc

Usage

In the window you want to call to (the "server"):
import { expose } from 'postmsg-rpc'

const fruitService = {
  getFruits: (/* arg0, arg1, ... */) => new Promise(/* ... */)
}

// Expose this function for RPC from other windows
expose('getFruits', fruitService.getFruits)

In the other window (the "client"):
import { call } from 'postmsg-rpc'

// Call the exposed function
const 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).
import { caller } from 'postmsg-rpc'

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

// Wait for the fruits to ripen
const 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.
const fruitPromise = call('getFruits')

fruitPromise.cancel()

try {
  await fruitPromise
} catch (err) {
  if (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.