@alshdavid/rpc
v2.0.1
Published
### Workers and iFrames
Downloads
29
Readme
JavaScript RPC Library
Workers and iFrames
This library serves to be a tiny (3kb), low level RPC implementation for JavaScript that allows for the accessing of data and calling of functions/methods that live in an external context.
Such use cases are iframes and web workers. This can also be used with web sockets for cooperative server side execution.
import { Reference } from '@alshdavid/rpc'
// Worker Data = { foo: () => 'bar' }
const ref0 = new Reference(port1)
const ref1 = ref0.property('foo')
const ref2 = ref1.exec()
const value = await ref2.value()
console.log(value) // 'bar'
Usage
Summary
This is split into two halves, the half that holds the data you want to expose - known as the DataSource
and the half that wants to consume the data.
An example data source would be a web worker holding data that the host page wants to access. Alternatively, it could be that the web worker that wants access to the document and the host page is the data source exposing the window
object.
The consumer accesses the data using a Reference
which points to data in the DataSource
. The consumer can walk up an object to find data or trigger methods.
Data Source
From your Data Source (iframe, worker), expose your data
import { DataSource } from '@alshdavid/rpc'
const data = { foo: 'bar' }
const dataSource = new DataSource(port2, data)
Consumer
import { Reference } from '@alshdavid/rpc'
// Connect to the DataSource and get your root reference
const ref0 = new Reference(port1)
// Crawl the tree
const ref1 = ref0.property('foo')
// Grab the value at the reference point
const value = await ref1.value()
Functions, Methods, Callbacks
Functions, methods along with callback arguments. Yes, you can send function accepting function accepting functions over a serialized boundary.
// Data = () => 'Hello World'
const resultRef = await ref0.exec()
const value = await resultRef.value()
console.log(value) // 'Hello World'
// Data = (value) => value
const resultRef = await ref0.exec('Hello World')
const value = await resultRef.value()
console.log(value) // 'Hello World'
// Data = (callback) => void
await ref0.exec(() => {
console.log('callback')
})
// Data = (callback: (next: () => void) => void) => void
await ref0.exec(async nextRef => {
await nextRef.exec()
})
Exceptions
Errors thrown in the data source are propagated to the consumer through the reference. The errors are references to the error in the data source.
try {
await ref0.exec()
} catch (errorRef) {
console.log(await errorRef.reference.property('message').value())
}
Observed/Realized values vs Traversal
Values are not accessed until .exec()
or .value()
are run. Traversing an object using .property()
will not incur a communication cost.
// Data = { foo: { bar: { foobar: 'foobar' }}}
const ref1 = await ref0.property('foo') // Create reference with path
const ref2 = await ref1.property('bar', 'foobar') // Build it up
const foobar = await ref2.value() // Now get the value there
Memory Management
There might be some improvements I can make here with time, but for now certain calls will incur a memory cost as certain values are stored on either side.
Things like function return values, callback function values, callback parameters, are all cached and must be manually purged when no longer needed
// Data = () => 'Hello World'
const returnValueRef = await ref0.exec()
console.log(await returnValueRef.value()) // 'Hello World'
await returnValueRef.release() // Purge the cache for this return value
console.log(await returnValueRef.value()) // undefined
// Data = (callback: (foo, bar) => void) => void
const returnValueRef = await ref0.exec(async (fooRef, barRef) => {
console.log(await fooRef.value()) // 'foo'
console.log(await barRef.value()) // 'bar'
})
ref0.release() // This will purge the 'foo' and 'bar' variables
MessagePorts
The base API uses the browser MessagePort
as the communication interface, so transfer your ports between your entities and you're good to go.
import { Reference } from '@alshdavid/rpc'
const { port1, port2 } = new MessageChannel()
const iframe = document.createElement('iframe')
iframe.src = 'https://my-external-app'
iframe.contentWindow.postMessage('ports', '*', [port2])
const ref0 = new Reference(port1)
port1.start()