postmsg-rpc

Tiny RPC over window.postMessage library

Install

npm install postmsg-rpc

Usage

In the window you want to call from (the "client"):

import { createClientFunc } from 'postmsg-rpc'

// Create a function that uses postMessage to call a function in a different window
const getFruits = createClientFunc('getFruits')

const fruits = await getFruits() // Wait for the fruits to ripen

In the other window (the "server"):

import { mapServerFunc } from 'postmsg-rpc'

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

// Map "calls" to this function (over postMessage) to a function on this object
mapServerFunc('getFruits', fruitService)

API

Async/await

createClientFunc(funcName, options)

Create a function that uses postMessage to call a 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 '*'

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
  • default window.addEventListener
• options.removeListener - function that removes a listener
  • default window.removeEventListener
• options.postMessage - function that posts a message
  • default window.postMessage
• options.getMessageData - a function that extracts data from the event object passed to a message event handler
  • default (e) => e.data

The function returned from createClientFunc will return a Promise when called 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 getFruits = createClientFunc('getFruits')
const fruitPromise = getFruits()

fruitPromise.cancel()

try {
  await fruitPromise
} catch (err) {
  if (err.isCanceled) {
    console.log('function call canceled')
  }
}

mapServerFunc(funcName, target, options)

Map "calls" to funcName (over postMessage) to a function on target. Assumes that the function being called on target returns a promise.

• funcName - the name of the function called on the client
• target - the object on which the function should be called i.e. target[funcName]()
• options.targetOrigin - passed to postMessage (see postMessage docs for more info)
  • default '*'
• options.targetFuncName - the function name on the target (if it differs from funcName)
• options.getTarget - a function that returns the target (useful if your target changes and you don't want to have to close/re-map each time)

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
  • default window.addEventListener
• options.removeListener - function that removes a listener
  • default window.removeEventListener
• options.postMessage - function that posts a message
  • default window.postMessage
• options.getMessageData - a function that extracts data from the event object 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.

Callbacks

createClientCallbackFunc(funcName, options)

Similar to createClientFunc except the function it creates expects to be passed a callback.

Returns an object with a cancel method which can be called to cancel an in flight request e.g.

const getFruits = createClientCallbackFunc('getFruits')
const handle = getFruits((err, fruits) => {
  if (err && err.isCanceled) {
    console.log('function call canceled')
  }
})

handle.cancel()

mapServerCallbackFunc(funcName, target, options)

Similar to mapServerFunc except it is assumed that the function being called on target requires a callback.

A (╯°□°）╯︵TABLEFLIP side project.