threads.js

To use threads.js with Parcel, you must import threads/register once at the very beginning of your application's master code. This registers the threads.js Worker implementation as the global Worker for your platform.

import { spawn } from "threads"
import "threads/register"

// ...

const work = await spawn(new Worker("./worker"))

To run the documentation site locally, use Bundler to install dependencies into a vendor directory and then start the Jekyll server.

Ensure you have Ruby and Bundler installed on your system before running these commands.

bundle install --path vendor/bundle
bundle exec jekyll serve --baseurl ''

To automatically bundle workers and resolve new Worker("./unbundled-path") expressions, use threads-plugin. This eliminates the need for worker-loader or manual entry point definitions.

Note for TypeScript users: Ensure your ts-loader configuration sets module: "esnext" so that import/export statements remain intact for the plugin to process.

npm install -D threads-plugin

const ThreadsPlugin = require('threads-plugin')

module.exports = {
  // ...
  plugins: [
    new ThreadsPlugin()
  ]
  // ...
}

TypeScript configuration requirement:

module: {
  rules: [
    {
      test: /\.ts$/,
      loader: "ts-loader",
      options: {
        compilerOptions: {
          module: "esnext"
        }
      }
    }
  ]
}

To use threads.js in your project, install the threads package using npm.

npm install threads

Because workers packaged inside an ASAR archive cannot be easily spawned, you must use the asarUnpack option in your Electron configuration (e.g., in package.json) to unpack the worker files. threads.js will automatically locate the workers in the unpacked directory.

"asarUnpack": {
  "dist/main/0.bundle.worker.js",
  "dist/main/0.bundle.worker.js.map"
}

Error handling is transparent. If an error is thrown inside a worker, the Promise returned by the master thread's call to the worker function will be rejected with that error, including the original stack trace.

// master.js
import { spawn, Thread, Worker } from "threads"

const counter = await spawn(new Worker("./workers/counter"))

try {
  await counter.increment()
  await counter.increment()
  await counter.decrement()

  console.log(`Counter is now at ${await counter.getCount()}`)
} catch (error) {
  console.error("Counter thread errored:", error)
} finally {
  await Thread.terminate(counter)
}

You can achieve type safety by declaring the type of the worker returned by spawn(). A best practice is to export the type from the worker module itself and use it in the master thread.

// counter.ts
import { expose } from "threads/worker"

let currentCount = 0

const counter = {
  getCount() {
    return currentCount
  },
  increment() {
    return ++currentCount
  },
  decrement() {
    return --currentCount
  }
}

export type Counter = typeof counter

expose(counter)

// master.ts
import { spawn, Thread, Worker } from "threads"
import { Counter } from "./workers/counter"

const counter = await spawn<Counter>(new Worker("./workers/counter"))
console.log(`Initial counter: ${await counter.getCount()}`)

await counter.increment()
console.log(`Updated counter: ${await counter.getCount()}`)

await Thread.terminate(counter)

To use threads.js in Node.js 12+, install the threads package. If you need to support Node.js versions 8 through 11, you must also install tiny-worker as an optional dependency to provide a fallback for worker_threads.

npm install threads tiny-worker

A Pool allows you to create a set of workers and queue worker calls. Instead of overwhelming workers with many tasks at once, the pool manages a queue and executes tasks in a controlled way with limited concurrency. Tasks are pulled from the queue as previous tasks finish.

Use a Pool when you have a large volume of work to offload to workers and want to maintain a specific concurrency level.

import { spawn, Pool, Worker } from "threads"

const pool = Pool(() => spawn(new Worker("./workers/multiplier")), 8 /* optional size */)

pool.queue(async multiplier => {
  const multiplied = await multiplier(2, 3)
  console.log(`2 * 3 = ${multiplied}`)
})

await pool.completed()
await pool.terminate()