Comlink’s goal is to make WebWorkers enjoyable. Comlink removes the mental barrier of thinking about postMessage
and hides the fact that you are working with workers.
Note: Comlink’s goal is to be a building-block for higher-level abstraction libraries. For example, take a look at Clooney.
// main.js
const MyClass = Comlink.proxy(new Worker('worker.js'));
// `instance` is an instance of `MyClass` that lives in the worker!
const instance = await new MyClass();
await instance.logSomething(); // logs “myValue = 42”
// worker.js
const myValue = 42;
class MyClass {
logSomething() {
console.log(`myValue = ${myValue}`);
}
}
Comlink.expose(MyClass, self);
Size: ~3.9k, ~1.6k gzip’d
WebWorkers are a web API that allow you to run code in a separate thread. To communicate with another thread, WebWorkers offer the postMessage
API. You can send messages in form of transferable JavaScript objects using myWorker.postMessage(someObject)
, triggering a message
event inside the worker.
Comlink turns this messaged-based API into a something more developer-friendly: Values from one thread can be used within the other thread (and vice versa) just like local values.
Comlink can be used with anything that offers postMessage
like windows, iframes and ServiceWorkers.
You can download Comlink from the dist folder. Alternatively, you can install it via npm
$ npm install --save comlinkjs
or use a CDN like delivrjs:
https://cdn.jsdelivr.net/npm/[email protected]/comlink.es6.min.js
There’s a collection of examples in the examples directory.
The Comlink module is provided in 3 different formats:
-
“es6”: This package uses the native ES6 module format. Import it as follows:
import {Comlink} from '../dist/comlink.es6.js'; // ...
-
“global”: This package adds
Comlink
to the global scope (i.e.self
). Useful for workers or projects without a module loader. -
“umd”: This package uses UMD so it is compatible with AMD, CommonJS and requireJS.
The Comlink module exports 3 functions:
Returns the value that is exposed on the other side of
endpoint
.
proxy
creates an ES6 proxy and sends all operations performed on that proxy through endpoint
. endpoint
can be a Window
, a Worker
or a MessagePort
.* The other endpoint of the channel should be passed to Comlink.expose
.
If you invoke function, all parameters will be structurally cloned or transferred if they are transferable. If you want to pass a function as a parameters (e.g. callbacks), make sure to use proxyValue
(see below). Same applies to the return value of a function.
*) Technically it can be any object with postMessage
, addEventListener
and
removeEventListener
.
Exposes
obj
toendpoint
. UseComlink.proxy
on the other end ofendpoint
.
expose
is the counter-part to proxy
. It listens for RPC messages on endpoint
and applies the operations to obj
. Return values of functions will be structurally cloned or transfered if they are transferable.
Makes sure a parameter or return value is proxied, not copied.
By default, all parameters to a function are copied (structural clone):
// main.js
const api = Comlink.proxy(new Worker('worker.js'));
const obj = {x: 0};
await api.setXto4(obj);
console.log(obj.x); // logs 0
The worker receives a copy of obj
, so any mutation of obj
done by the worker won’t affect the original object. If the value should not be copied but instead be proxied, use Comlink.proxyValue
:
- await api.setXto4(obj);
+ await api.setXto4(Comlink.proxyValue(obj));
console.log(obj.x)
will now log 4.
Keep in mind that functions cannot be copied. Unless they are used in combination with Comlink.proxyValue
, they will get discarded during copy.
License Apache-2.0