|
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475 |
- # 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 { makeRemotelyCallable } from 'webextension-rpc'
- async function myFunc(arg) {
- return arg * 2
- }
- makeRemotelyCallable({ myFunc })
-
- In `content_script.js`:
-
- import { remoteFunction } from 'webextension-rpc'
- const myRemoteFunc = remoteFunction('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 { makeRemotelyCallable } from 'webextension-rpc'
-
- Or copy its `lib/index.js` and import from that if you prefer (this module has no dependencies).
-
-
- ## API
-
- ### `remoteFunction(functionName, { tabId })`
-
- Create a proxy function that invokes the specified remote function.
-
- - `functionName` (string, required): name of the function as registered on the remote side.
- - `options` (object, optional):
- - `tabId` (number): The id of the tab whose content script is the remote side. Leave undefined
- to call the background script (from a content script).
-
- ### `makeRemotelyCallable(functions, { insertExtraArg })`
-
- 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
|