Product
Introducing License Enforcement in Socket
Ensure open-source compliance with Socket’s License Enforcement Beta. Set up your License Policy and secure your software!
Comlink’s goal is to make [WebWorkers][webworker] enjoyable. Comlink removes the mental barrier of thinking about `postMessage` and hides the fact that you are working with workers.
Comlink is a utility that simplifies the process of working with Web Workers and other forms of remote communication in JavaScript. It allows you to expose and call functions across different execution contexts, such as between the main thread and a Web Worker, as if they were local functions.
Basic Usage
This example demonstrates the basic usage of Comlink to expose an object in a Web Worker and call its methods from the main thread.
const { wrap } = require('comlink');
// worker.js
const obj = {
counter: 0,
increment() {
this.counter++;
return this.counter;
}
};
Comlink.expose(obj);
// main.js
const worker = new Worker('worker.js');
const remoteObj = wrap(worker);
(async () => {
console.log(await remoteObj.increment()); // 1
console.log(await remoteObj.increment()); // 2
})();
Transferable Objects
This example shows how to use Comlink with transferable objects, such as ArrayBuffers, to efficiently transfer data between the main thread and a Web Worker.
const { wrap, transfer } = require('comlink');
// worker.js
const obj = {
processArray(buffer) {
// Process the buffer
return buffer;
}
};
Comlink.expose(obj);
// main.js
const worker = new Worker('worker.js');
const remoteObj = wrap(worker);
const buffer = new ArrayBuffer(8);
(async () => {
const result = await remoteObj.processArray(transfer(buffer, [buffer]));
console.log(result); // ArrayBuffer(8)
})();
Class Instances
This example demonstrates how to use Comlink to expose class instances in a Web Worker and interact with them from the main thread.
const { wrap } = require('comlink');
// worker.js
class Counter {
constructor() {
this.value = 0;
}
increment() {
this.value++;
return this.value;
}
}
Comlink.expose(Counter);
// main.js
const worker = new Worker('worker.js');
const RemoteCounter = wrap(worker);
(async () => {
const counter = await new RemoteCounter();
console.log(await counter.increment()); // 1
console.log(await counter.increment()); // 2
})();
Workerize is a library that automatically moves a module into a Web Worker and proxies calls to it. It is similar to Comlink in that it simplifies the use of Web Workers, but it is more focused on automatically converting entire modules into workers, whereas Comlink provides more granular control over exposing and calling individual functions or objects.
Threads is a library for creating and managing Web Workers with a focus on simplicity and type safety. It provides a higher-level API compared to Comlink, with built-in support for TypeScript and more structured worker management. While Comlink offers more flexibility in exposing and calling functions, Threads aims to provide a more streamlined and type-safe experience.
Greenlet is a micro-library that allows you to run a function in a Web Worker and return a promise for its result. It is similar to Comlink in that it simplifies the use of Web Workers, but it is more lightweight and focused on running individual functions rather than exposing entire objects or classes.
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);
Browsers without ES6 Proxy support can use the proxy-polyfill.
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/comlinkjs@3.1.1/umd/comlink.js
There’s a collection of examples in the examples directory.
The Comlink module exports 3 functions:
Comlink.proxy(endpoint)
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
.
Comlink.expose(obj, endpoint)
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.
Comlink.proxyValue(value)
Makes sure a parameter or return value is proxied, not copied.
By default, all parameters to a function that are not transferable 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
FAQs
Comlink makes WebWorkers enjoyable
The npm package comlink receives a total of 313,612 weekly downloads. As such, comlink popularity was classified as popular.
We found that comlink demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Ensure open-source compliance with Socket’s License Enforcement Beta. Set up your License Policy and secure your software!
Product
We're launching a new set of license analysis and compliance features for analyzing, managing, and complying with licenses across a range of supported languages and ecosystems.
Product
We're excited to introduce Socket Optimize, a powerful CLI command to secure open source dependencies with tested, optimized package overrides.