A modern, (almost) zero-dependency WebWorker abstraction.
npm install threads-es
!GitHub license

!Node.js tests
Supports Worker, SharedWorker.
It's made for the web, it doesn't support Node.js workers. Use with bundlers that support bundling workers with import.meta, i.e. Rollup or Webpack 5.
- Tiny, when minified.
- Promise based.
- Fully typed.
- Well tested.
Current documentation at: https://852kerfunkle.github.io/threads-es/v1.0.0
Latest documentation at: https://852kerfunkle.github.io/threads-es/main
More examples in the tests.
#### Threads
hello-world.worker.ts
``ts
import { exposeApi } from "threads-es/worker"
const helloWorldApi = {
helloWorld: () => {
return "Hello World!";
}
}
export type HelloWorldApiType = typeof helloWorldApi;
exposeApi(helloWorldApi);
`
controller.ts
`ts
import { EsThread } from "threads-es/controller"
import { HelloWorldApiType } from "./hello-world.worker.ts"
const thread = await EsThread.Spawn
new Worker(new URL("./hello-world.worker.ts", import.meta.url),
{type: "module"}));
// "Hello World!"
console.log(await thread.methods.helloWorld());
await thread.terminate();
`
#### Pools
pool.ts
`ts
import { EsThreadPool, EsThread } from "threads-es/controller"
import { HelloWorldApiType } from "./hello-world.worker.ts"
const pool = await EsThreadPool.Spawn(() => EsThread.Spawn
new Worker(new URL("./hello-world.worker.ts", import.meta.url),
{type: "module"}), {size: 4});
// "Hello World!"
console.log(await pool.queue(thread => thread.methods.helloWorld()));
await pool.terminate();
`
#### Transferables
transfer-array.worker.ts
`ts
import { Transfer, TransferDescriptor } from "threads-es/shared";
import { exposeApi } from "threads-es/worker"
const transferArrayApi = {
transferArray: (array: TransferDescriptor
const uint8 = new Uint8Array(array.send);
// Process the buffer.
return Transfer(uint8.buffer);
}
}
export type TransferArrayApiType = typeof transferArrayApi;
exposeApi(transferArrayApi);
`
controller.ts
`ts
import { EsThread } from "threads-es/controller"
import { Transfer } from "threads-es/shared";
import { TransferArrayApiType } from "./transfer-array.worker.ts"
const thread = await EsThread.Spawn
new Worker(new URL("./transfer-array.worker.ts", import.meta.url),
{type: "module"}));
const arrayIn = new Uint8Array(10);
arrayIn.forEach((value, index) => { arrayIn[index] = index });
const arrayOut = await thread.methods.transferArray(Transfer(arrayIn.buffer));
// Do something with the result.
await thread.terminate();
`
#### Reporting progress from a worker
If you need a worker to report progress you could use a stream. For other options see #4.
progress.worker.ts
`ts
import { TransferDescriptor } from 'threads-es/shared';
import { exposeApi } from 'threads-es/worker';
const progressApi = {
withProgress: async (ags..., progress: TransferDescriptor
// Imagine doing some work and updating the progress as it goes along.
await progress.write(10);
await progress.write(20);
await progress.write(100);
await progress.close();
}
}
export type ProgressApiType = typeof progressApi;
exposeApi(progressApi);
`
controller.ts
`ts
import { EsThread } from "threads-es/controller"
import { Transfer } from "threads-es/shared"
import { HelloWorldApiType } from "./progress.worker.ts"
const thread = await EsThread.Spawn
new Worker(new URL("./progress.worker.ts", import.meta.url),
{type: "module"}));
const progress = new WritableStream
write(p) {
// You could update the progress in the DOM, or write it to a log, or something like that.
}
});
await thread.methods.withProgress(args..., Transfer(progress));
await thread.terminate();
`
#### Webpack note
With Webpack or certain test frameworks, you might need the separate your thread api types from the thread code:
api-type.ts
`ts`
export type HelloWorldApiType = {
helloWorld: () => string;
};
worker.ts
`ts
import { exposeApi } from 'threads-es/worker';
import { type HelloWorldApiType } from './api-type';
const helloWorldApi: HelloWorldApiType = {
helloWorld: () => {
return 'Hello World!';
},
};
exposeApi(helloWorldApi);
`
controller.ts
`ts
import { EsThread } from "threads-es/controller"
import { HelloWorldApiType } from "./api-type"
const thread = await EsThread.Spawn
new Worker(new URL("./hello-world.worker.ts", import.meta.url),
{type: "module"}));
// "Hello World!"
console.log(await thread.methods.helloWorld());
await thread.terminate();
``
Inspired by threads.js.