README.md

✨ Enhance your asynchronous web/node development by sprinkling parallel code execution! ✨

• installing
• API
  • task
  • cook
  • track
  • kill
• common mistakes

DEMO

installing

Install from npm:

npm i async-worker

Import:

import AsyncWorker from 'async-worker'

Alternatively use the embedded script tag (AsyncWorker will be available globally):

<script src="https://cdn.jsdelivr.net/npm/async-worker/dist/async-worker.web.js"></script>

API

task

To perform a long, expensive tasks outside of the main thread use asyncWorker.task

const { task } = new AsyncWorker()

const primes = await task(
	(from, to) => {
		let computedPrimes = []
		// im computing big data that would otherwise block the main thread
		return computedPrimes
	},
	10,
	1000000
)

function task<T, S extends any[]>(func: (...args: S) => T, ...args: S): Promise<T>

cook

To cook a function into an asynchronous one use asyncWorker.cook

const { cook } = new AsyncWorker()

const asyncFibo = cook(() => (n) => {
	if (n <= 0) return NaN

	let [first, second] = [0, 1]
	while (--n) [first, second] = [second, first + second]

	return first
})

const res = await asyncFibo(5)
console.log(`5th fibonacci number is ${res}`)

function cook<T, S extends any[], U extends any[]>(
	func: (...args: S) => (...args: U) => T,
	...args: S
): (...args: U) => Promise<T>

track

To track progress of a task use asyncWorker.track

const { track } = new AsyncWorker()

const tracker = track((tick, n) => {
	let fact = 1
	for (let i = 1; i <= n; i++) {
		fact *= i
		tick(i / n)
	}
	return fact
}, 15)

tracker.tick((progress) => console.log(`the factorial is ${progress * 100}% done!`))

console.log(`the result is ${await tracker.result}`)

function track<T, S extends any[]>(
	func: (tick: (progress: number) => void, ...args: S) => T,
	...args: S
): {
	result: Promise<T>
	tick: (ticker: (progress: number) => void) => void
}

kill

Once you're done using, you can kill it

const async = new AsyncWorker()

async.task(/* doing something */)

async.kill()

common mistakes

Because web workers/worker threads exist in a different thread the passed function does not have access to your current context variables. To pass in variables please add them as additional parameters and accept them in your functions. This will not work:

//...
const from = 10
const to = 1000000
const primes = await task(() => {
	console.log(from) // error during worker runtime: 'from' is not defined
	console.log(to) // error during worker runtime: 'to' is not defined
})
//...

Do instead:

//...
const from = 10
const to = 1000000
const primes = await task(
	(from, to) => {
		console.log(from) // :)
		console.log(to) // :)
	},
	from,
	to
)
//...

Some types are not transferable. Meaning you cannot send them to or receive from a web worker. Notably functions are not transferable. The following will not work:

//...
const answer = () => 42
const result = await task((answer) => {
	// DataCloneError: could not clone '() => 42'
}, answer)
//...

Nor will:

//...
const func = await task(() => {
	return () => 42
	// DataCloneError: could not clone '() => 42'
})
//...