Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/alesgenova/post-me
📩 Use web Workers and other Windows through a simple Promise API
https://github.com/alesgenova/post-me
communication concurrency iframe javascript parallel-computing postmate postmessage promise typescript web-worker webworker worker
Last synced: about 2 months ago
JSON representation
📩 Use web Workers and other Windows through a simple Promise API
- Host: GitHub
- URL: https://github.com/alesgenova/post-me
- Owner: alesgenova
- License: mit
- Created: 2020-11-29T00:54:17.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2021-02-19T02:26:52.000Z (over 3 years ago)
- Last Synced: 2024-07-23T08:43:07.721Z (2 months ago)
- Topics: communication, concurrency, iframe, javascript, parallel-computing, postmate, postmessage, promise, typescript, web-worker, webworker, worker
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/post-me
- Size: 801 KB
- Stars: 487
- Watchers: 11
- Forks: 13
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
[](https://github.com/alesgenova/post-me/actions?query=workflow%3Amain+branch%3Amain)
[](https://www.npmjs.com/package/post-me)
[](https://codecov.io/gh/alesgenova/post-me)
post-me
Communicate with web Workers and other Windows using a simple Promise based API
With __post-me__ it is easy for a parent (for example the main app) and a child (for example a worker or an iframe) to expose methods and custom events to each other.
## Features
- 🔁 Parent and child can both __expose__ __methods__ and/or __events__.
- 🔎 __Strong typing__ of method names, arguments, return values, as well as event names and payloads.
- 🤙 Seamlessly pass __callbacks__ to the other context to get progress or partial results.
- 📨 __Transfer__ arguments/return values/payloads when needed instead of cloning.
- 🔗 Establish __multiple__ concurrent __connections__.
- 🌱 __No dependencies__: 2kb gzip bundle.
- 🧪 Excellent __test coverage__.
- 👐 Open source (MIT)
## Demo
In this [live demo](https://alesgenova.github.io/post-me-demo) the main window communicates with a web worker and an iframe ([source](https://github.com/alesgenova/post-me-demo)).
## Content:
1. [Install](#install)
2. [Basic Usage](#usage)
3. [Typescript Support](#typescript)
4. [Other Uses](#other)
- [Windows](#windows)
- [MessageChannels](#channels)
5. [Callbacks as parameters](#callbacks)
6. [Transfer vs Clone](#transfer)
7. [Debugging](#debugging)
8. [Parallel Programming](#parallel)
9. [API Documentation](#api)
10. [References](#references)
## Install
Import __post-me__ as a module:
```bash
npm install post-me
```
```typescript
import { ParentHandshake } from 'post-me';
```
Import __post-me__ as a script:
```html
const ParentHandshake = PostMe.ParentHandshake;
```
## Usage
In the example below, the parent application calls methods exposed by the worker and listens to events emitted by it.
For the sake of simiplicity, only the worker is exposing methods and events, however the parent could do it as well.
Parent code:
```typescript
import { ParentHandshake, WorkerMessenger } from 'post-me';
const worker = new Worker('./worker.js');
const messenger = new WorkerMessenger({ worker });
ParentHandshake(messenger).then((connection) => {
const remoteHandle = connection.remoteHandle();
// Call methods on the worker and get the result as a promise
remoteHandle.call('sum', 3, 4).then((result) => {
console.log(result); // 7
});
// Listen for a specific custom event from the worker
remoteHandle.addEventListener('ping', (payload) => {
console.log(payload) // 'Oh, hi!'
});
});
```
Worker code:
```typescript
import { ChildHandshake, WorkerMessenger } from 'post-me';
// Methods exposed by the worker: each function can either return a value or a Promise.
const methods = {
sum: (x, y) => x + y,
mul: (x, y) => x * y
}
const messenger = WorkerMessenger({worker: self});
ChildHandshake(messenger, methods).then((connection) => {
const localHandle = connection.localHandle();
// Emit custom events to the app
localHandle.emit('ping', 'Oh, hi!');
});
```
## Typescript
Using typescript you can ensure that the parent and the child are using each other's methods and events correctly. Most coding mistakes will be caught during development by the typescript compiler.
Thanks to __post-me__ extensive typescript support, the correctness of the following items can be statically checked during development:
- Method names
- Argument number and types
- Return values type
- Event names
- Event payload type
Below a modified version of the previous example using typescript.
Types code:
```typescript
// types.ts
export type WorkerMethods = {
sum: (x: number, y: number) => number;
mul: (x: number, y: number) => number;
}
export type WorkerEvents = {
'ping': string;
}
```
Parent Code:
```typescript
import {
ParentHandshake, WorkerMessenger, RemoteHandle
} from 'post-me';
import { WorkerMethods, WorkerEvents } from './types';
const worker = new Worker('./worker.js');
const messenger = new WorkerMessenger({ worker });
ParentHandshake(messenger).then((connection) => {
const remoteHandle: RemoteHandle
= connection.remoteHandle();
// Call methods on the worker and get the result as a Promise
remoteHandle.call('sum', 3, 4).then((result) => {
console.log(result); // 7
});
// Listen for a specific custom event from the app
remoteHandle.addEventListener('ping', (payload) => {
console.log(payload) // 'Oh, hi!'
});
// The following lines have various mistakes that will be caught by the compiler
remoteHandle.call('mul', 3, 'four'); // Wrong argument type
remoteHandle.call('foo'); // 'foo' doesn't exist on WorkerMethods type
});
```
Worker code:
```typescript
import { ChildHandshake, WorkerMessenger, LocalHandle } from 'post-me';
import { WorkerMethods, WorkerEvents } from './types';
const methods: WorkerMethods = {
sum: (x: number, y: number) => x + y,
mul: (x: number, y: number) => x * y,
}
const messenger = WorkerMessenger({worker: self});
ChildHandshake(messenger, methods).then((connection) => {
const localHandle: LocalHandle
= connection.localHandle();
// Emit custom events to the worker
localHandle.emit('ping', 'Oh, hi!');
});
```
## Other Uses
post-me can establish the same level of bidirectional communications not only with workers but with other windows too (e.g. iframes) and message channels.
Internally, the low level differences between communicating with a `Worker`, a `Window`, or a `MessageChannel` have been abstracted, and the `Handshake` will accept any object that implements the `Messenger` interface defined by __post-me__.
This approach makes it easy for post-me to be extended by its users.
A `Messenger` implementation for communicating between `Windows` and `MessagePorts` is already provided in the library (`WindowMessenger` and `PortMessenger`).
### Windows
Here is an example of using post-me to communicate with an iframe.
Parent code:
```typescript
import { ParentHandshake, WindowMessenger } from 'post-me';
// Create the child window any way you like (iframe here, but could be popup or tab too)
const childFrame = document.createElement('iframe');
const childWindow = childFrame.contentWindow;
// For safety it is strongly adviced to pass the explicit child origin instead of '*'
const messenger = new WindowMessenger({
localWindow: window,
remoteWindow: childWindow,
remoteOrigin: '*'
});
ParentHandshake(messenger).then((connection) => {/* ... */});
```
Child code:
```typescript
import { ChildHandshake, WindowMessenger } from 'post-me';
// For safety it is strongly adviced to pass the explicit child origin instead of '*'
const messenger = new WindowMessenger({
localWindow: window,
remoteWindow: window.parent,
remoteOrigin: '*'
});
ChildHandshake(messenger).then((connection) => {/* ... */});
```
### MessageChannels
Here is an example of using post-me to communicate over a `MessageChannel`.
```typescript
import { ParentHandshake, ChildHandshake, PortMessenger } from 'post-me';
// Create a MessageChannel
const channel = new MessageChannel();
const port1 = channel.port1;
const port2 = channel.port2;
// In the real world port1 and port2 would be transferred to other workers/windows
{
const messenger = new PortMessenger({port: port1});
ParentHandshake(messenger).then(connection => {/* ... */});
}
{
const messenger = new PortMessenger({port: port2});
ChildHandshake(messenger).then(connection => {/* ... */});
}
```
## Callbacks as call parameters
Even though functions cannot actually be shared across contexts, with a little magic under the hood __post-me__ let's you pass callback functions as arguments when calling a method on the other worker/window.
Passing callbacks can be useful to obtain progress or partial results from a long running task.
Parent code:
```typescript
//...
ParentHandshake(messenger).then(connection => {
const remoteHandle = connection.remoteHandle();
const onProgress = (progress) => {
console.log(progress); // 0.25, 0.5, 0.75
}
remoteHandle.call("slowSum", 2, 3, onProgress).then(result => {
console.log(result); // 5
});
});
```
Worker code:
```typescript
const methods = {
slowSum: (x, y, onProgress) => {
onProgress(0.25);
onProgress(0.5);
onProgress(0.75);
return x + y;
}
// ...
ChildHandshake(messenger, methods).then(connection => {/* */})
```
## Transfer vs Clone
By default any call parameter, return value, and event payload is cloned when passed to the other context.
While in most cases this doesn't have a significant impact on performance, sometimes you might need to transfer an object instead of cloning it. NOTE: only `Transferable` objects can be transfered (`ArrayBuffer`, `MessagePort`, `ImageBitmap`, `OffscreenCanvas`).
__post-me__ provides a way to optionally transfer objects that are part of a method call, return value, or event payload.
In the example below, the parent passes a very large array to a worker, the worker modifies the array in place, and returns it to the parent. Transfering the array instead of cloning it twice can save significant amounts of time.
Parent code:
```typescript
// ...
ParentHandshake(messenger).then((connection) => {
const remoteHandle = connection.remoteHandle();
// Transfer the buffer of the array parameter of every call that will be made to 'fillArray'
remoteHandle.setCallTransfer('fillArray', (array, value) => [array.buffer]);
{
const array = new Float64Array(100000000);
remoteHandle.call('fillArray', array, 5);
}
// Transfer the buffer of the array parameter only for this one call made to 'scaleArray'
{
const array = new Float64Array(100000000);
const args = [array, 2];
const callOptions = { transfer: [array.buffer] };
remoteHandle.customCall('scaleArray', args, callOptions);
}
});
```
Worker code:
```typescript
// ...
const methods = {
fillArray: (array, value) => {
array.forEach((_, i) => {array[i] = value});
return array;
},
scaleArray: (buffer, type value) => {
array.forEach((a, i) => {array[i] = a * value});
return array;
}
}
ChildHandshake(messenger, model).then((connection) => {
const localHandle = connection.localHandle();
// For each method, declare which parts of the return value should be transferred instead of cloned.
localHandle.setReturnTransfer('fillArray', (result) => [result.buffer]);
localHandle.setReturnTransfer('scaleArray', (result) => [result.buffer]);
});
```
## Debugging
You can optionally output the internal low-level messages exchanged between the two ends.
To enable debugging, simply decorate any `Messenger` instance with the provided `DebugMessenger` decorator.
You can optionally pass to the decorator your own logging function (a glorified `console.log` by default), which can be useful to make the output more readable, or to inspect messages in automated tests.
```typescript
import { ParentHandshake, WindowMessenger, DebugMessenger } from 'post-me';
import debug from 'debug'; // Use the full feature logger from the debug library
// import { debug } from 'post-me'; // Or the lightweight implementation provided
let messenger = new WindowMessenger({
localWindow: window,
remoteWindow: childWindow,
remoteOrigin: '*'
});
// To enable debugging of each message exchange, decorate the messenger with DebugMessenger
const log = debug('post-me:parent'); // optional
messenger = DebugMessenger(messenger, log);
ParentHandshake(messenger).then((connection) => {
// ...
});
```
Output:
## Parallel Programming
[__@post-me/mpi__](https://github.com/alesgenova/post-me/tree/main/packages/mpi) is an experimental library to write parallel algorithms that run on a pool of workers using a MPI-like syntax. See the dedicated [README](https://github.com/alesgenova/post-me/tree/main/packages/mpi) for more information.
## API Documentation
The full [__API reference__](https://alesgenova.github.io/post-me/post-me.html) can be found [here](https://alesgenova.github.io/post-me/post-me.html).
## References
The __post-me__ API is loosely inspired by [postmate](https://github.com/dollarshaveclub/postmate), with several major improvements and fixes to outstanding issues:
- Native typescript support
- Method calls can have both arguments and a return value: ([#94](https://github.com/dollarshaveclub/postmate/issues/94))
- Parent and child can both expose methods and/or events (instead of child only): [#118](https://github.com/dollarshaveclub/postmate/issues/118)
- Exceptions that occur in a method call can be caught by the caller.
- Better control over handshake origin and attempts: ([#150](https://github.com/dollarshaveclub/postmate/issues/150), [#195](https://github.com/dollarshaveclub/postmate/issues/195))
- Multiple listeners for each event: ([#58](https://github.com/dollarshaveclub/postmate/issues/58))