Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jurca/post-message-rpc
An RPC-like library for contexts connected via the postMessage API with TypeScript support.
https://github.com/jurca/post-message-rpc
Last synced: 6 days ago
JSON representation
An RPC-like library for contexts connected via the postMessage API with TypeScript support.
- Host: GitHub
- URL: https://github.com/jurca/post-message-rpc
- Owner: jurca
- License: isc
- Created: 2019-09-19T09:25:39.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2022-12-14T08:23:35.000Z (almost 2 years ago)
- Last Synced: 2024-10-07T20:49:08.535Z (about 1 month ago)
- Language: TypeScript
- Size: 486 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# post-message-rpc
[](https://travis-ci.org/jurca/post-message-rpc)
[](https://www.npmjs.com/package/@jurca/post-message-rpc)
[](LICENSE)
An RPC-like library for contexts connected via the postMessage API with
TypeScript support.
## Installation
`post-message-rpc` is available as npm package, you can use `npm` to install
it:
```
npm install --save @jurca/post-message-rpc
```
## Usage
There is separate API for the "server" (the RPC methods provider) and the
client.
### RPC Server
Use the `createServer` function to create an RPC server expecting procedure
calls from other contexts:
```javascript
import {createServer} from '@jurca/post-message-rpc'
createServer('channel ID', ['whitelist', 'of', 'origins'], {
foo(x, y) {
return x + y
},
bar(x) { // procedures may be asynchronous
return new Promise((resolve) => setTimeout(resolve, x)).then(() => x)
},
baz() {
// Errors thrown (synchronously or asynchronously) by procedures will be
// propagated to the client.
return Promise.reject(new Error('This is an error'))
},
})
```
Using an empty array will allow calls from any origin, but is is strongly
recommended for security reasons to always use an origin whitelist.
### RPC Client
Use the `createClient` function to create an RPC client. Use the same channel
ID as the one used to create the RPC server you want to communicate with (Each
context may contain multiple servers and/or clients).
```javascript
import {createClient} from '@jurca/post-message-rpc'
(async () => {
const client = await createClient(
iframeWindow,
{
// Connection options, consumed by the @jurca/post-message-p2p package.
// A string, number, symbol, boolean, null or undefined identifying the
// communication channel with the peer.
channel: 'channel ID',
// An optional timeout for receiving a confirmation that the peer has
// received the message, defaults to 10 seconds. Specified in
// milliseconds, must be a positive integer.
timeout: 100,
// The optional origin that is allowed to receive messages sent through
// this connection. Defaults to '*', but is recommended to be set for
// security reasons.
origin: 'https://some.origin.org',
// The optional number of retries when trying to perform a handshake
// with the provided peer. The connection will not be established if the
// peer will not be responding to the handshake messages. Defaults to 2.
handshakeRetries: 2,
// An optional delay between handshake attempts in milliseconds.
// Defaults to 500.
handshakeRetryDelay: 3000,
},
{
// This is a template listing the methods exposed by the server that the
// client intends to use. While it would be possible to create an
// implementation that uses the Proxy API rendering this argument not
// needed, it would break compatibility with Internet Explorer.
foo: null,
bar: null,
},
)
const firstResult = await client.foo(10, 12) // firstResult = 22
const otherResult = await client.bar(500) // otherResult = 500
try {
await client.baz()
} catch (error) {
// The error will have the name, message and stack correctly set. The
// stack will be the correct stack of the error thrown by the procedure at
// the server.
}
})()
```