# webextension-rpc

This module provides a *Remote Procedure Call* abstraction around the message passing that is
available to WebExtension (browser extension) scripts. It makes it easier to call a function in the
background script from a tab’s content script, or vice versa.


## Example use

In `background.js`:

    import { RpcServer } from 'webextension-rpc'
    async function myFunc(arg) {
      return arg * 2
    }
    new RpcServer({ myFunc })

In `content_script.js`:

    import { RpcClient } from 'webextension-rpc'
    const myRemoteFunc = new RpcClient().func('myFunc')
    await myRemoteFunc(21) // 42!

Note that the remote function always returns a `Promise`, which resolves with the remote function’s
actual return value (if the return value is itself a Promise, its result is awaited too).


## Use in TypeScript

When used TypeScript, the type of a remote/proxy function is nearly equal to its original, and can
be derived from it automatically. For an example how to do this, see the `example` folder.


## Install

### Using NPM

This module is published [on npm](https://www.npmjs.com/package/webextension-rpc), as an ES module.

Run `npm install webextension-rpc` or equivalent, and in your code import what you need, e.g.:

    import { RpcClient, RpcServer } from 'webextension-rpc'


## API

### RpcClient

#### `new RpcClient(options?)` (constructor)

Instantiate the RpcClient.

Arguments:
- `options` (object, optional):
  - `options.tabId` (number): The id of the tab whose content script is the remote side. Leave undefined or
    null to invoke functions in the background script (from a content script).

#### `func(functionName, options?)`

Create a proxy function that invokes the specified remote function.

Arguments:
- `functionName` (string, required): name of the function as registered on the remote side.
- `options` (object, optional): override any options passed to the constructor.


### RpcServer

#### `new RpcServer(functions)` (constructor)

Register one or more functions to enable remote scripts to call them.

Arguments:

- `functions` (object, required): An object with a `{ functionName: function }` mapping. Each
  function will be remotely callable using the given name.

### `injectRpcInfo`

If the special symbol `injectRpcInfo` is passed as the first argument to a proxy function, this
argument will be replaced on the executing side by an `RpcInfo` object, which contains the following
attributes:

  - `tab`: the [`Tab`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/Tab),
    from which the call was made, if it was made by a content script.

[Tab]: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/Tab