Nail Polishing Minions

    postmsg-rpc

    2.4.0 • Public • Published

    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.

    Install

    npm i postmsg-rpc

    DownloadsWeekly Downloads

    12,180

    Version

    2.4.0

    License

    MIT

    Unpacked Size

    34.4 kB

    Total Files

    19

    Last publish

    Collaborators

    • alanshaw