Pass objects with async methods between WebWorkers and the main thread easily
npm install magic-portalPass objects with async methods between WebWorkers and the main thread easily
This is a Node.js module available through the
npm registry. It can be installed using the npm
or yarn
command line tools.
``sh`
npm install magic-portal --save
You load the library in both the main thread and the worker (same library, there's no client/server distinction)
and then create a new MagicPortal(channel) where channel is either the worker or the window..set
Then you call and .get on it like it's a Map, except you have to await the .get.
The functions on the object HAVE to be async functions that return Promises.
index.htmlhtml`
worker.jsjs
importScripts([
"https://unpkg.com/magic-portal/dist/index.umd.js"
])
;(async () => {
const portal = new MagicPortal(self)
portal.set('adder', {
add: async (a, b) => a + b
})
let main = await portal.get('main')
main.alert('hello from worker')
})();
`
The same examples, but using ES modules
index.htmlhtml`
worker.jsjs
import MagicPortal from "https://unpkg.com/magic-portal/dist/index.es6.js"
;(async () => {
const portal = new MagicPortal(self)
portal.set('adder', {
add: async (a, b) => a + b
})
let main = await portal.get('main')
main.alert('hello from worker')
})();
`
If you have some methods where you don't care about the return value, you can use the void option to tell MagicPortal you don't need to wait for the result.postMessage
This will cut the number of calls used in half, which could be useful if you have very high throughput (like an event emitter).
`js`
portal.set('main', {
add: async (a, b) => a + b,
alert: async (msg) => window.alert(msg)
}, {
void: ['alert']
})
Under the hood it uses a very simple postMessage remote procedure call (RPC) that looks like this:
`js`
// Announce "I am able to start receiving messages"
{
type: "MP_INIT"
}
// Announce "I have this object"
{
type: "MP_SET",
object: "adder",
methods: ["adder"]
}
// Method call (request)
{
type: "MP_CALL",
object: "adder",
method: "add",
args: [2, 2],
id: 36
}
// Return value (response)
{
type: "MP_RETURN",
id: 36,
result: 4
}
// or Error
{
type: "MP_RETURN",
id: 36,
error: "this is the error message"
}
Both sides of the MagicPortal queue their messages until they have received an MP_INIT message to account for the slight delay in starting up WebWorker threads..set
Calling sends (or queues) an MP_SET message, and when you call .get, it returns a promise that is resolved once a corresponding MP_SET message is received..set
(Therefore you should try to make all your calls before you start awaiting for .get calls to avoid a mutual deadlock where both threads are awaiting.).get
The object returned by has methods that correspond to the function properties of the original object passed to .set.MP_CALL
Calling these methods sends an message with the arguments, and the MagicPortal on the other side of the channel will receive the MP_CALL message and call the original method with those arguments.postMessage
Therefore the function arguments have to be serializable by the structured clone algorithm used by to send values.
`sh``
npm install
npm test
None
- babel-core: Babel compiler core.
- babel-preset-env: A Babel preset for each environment.
- jest: Delightful JavaScript Testing.
- microbundle: Zero-configuration bundler for tiny JS libs, powered by Rollup.
MIT