@jsweb/worker

JavaScript module to parallel process data through dynamic multi-thread workers.

Installation

$3

The most common way used for the modern web applications development:

npm i -S @jsweb/worker

yarn add @jsweb/worker

And at your JS you can import the module that fits your environment:

``javascript
// ES6+ frontend web dev to use worker at the browser
import worker from '@jsweb/worker'

// ES6+ backend dev to use worker in Node.js
import worker from '@jsweb/worker/dist/node.mjs'

// CommonJS backend dev to use worker in Node.js
const worker = require('@jsweb/worker/dist/node.js')
`

Yes, it works in Node.js, but you must to import/require the correct module for your dev environment.

$3

If you prefer, you can get it directly from Unpkg CDN to use it in web frontend.

`html

`

By including the script in your page as traditional JS, the jsWebWorker function becomes available at the global scope.

This main exported module is in UMD format and targets browser.

But if you want to use a modern ES6+ module, you can do this:

`html

`

Usage example

`javascript
import worker from '@jsweb/worker'

let result

const data = [...aLotOfItemsHere]

worker(data)
.env('two', 2)
.map((item) => item.value ** self.env.two)
.reduce((value, sum) => value + sum, 0)
.finally((sum) => (result = sum))
`

Important:

Notice the self thing into the code!

Any function task running at the Worker must refer to the environment as self to access other context resources, except for globals.

The worker

$3

The worker function returns a high level object instance that works like Promise, with async methods.

In fact, it uses a Promise internaly to guide the entire process data flow when methods are called.

You can chain or async/await them to get the results.

The worker instance receive 2 arguments:

1. data or value to process (required)
2. a number to setup concurrent threads to process data (optional)

`javascript
worker(data, 4).exec(...)
`

The worker tries to detect how much "hardware concurrency threads" are available to use, or use the default: 2.

$3

At the browser, Workers run in parallel hardware threads, detached from main JS application thread.

It means you don't have access to all props and features available at the global JS scope.

If you need to know more about this, try to start here: Web Workers API : Functions and interfaces available in workers.

At the Node.js environment, workers use child_process. To know more about this, go to Node.js API: child_process

Methods

All methods are asyncronous and return the worker instance to chain other methods, except the .finally method, that ends the flow worker and returns just a native Promise.

$3

Sets a Worker environment constant attached to 'self.env' object.

- key must to be a valid object key
- value can be any data to be available at Worker environment

Inside your tasks functions, you can refer to these constants through 'self.env' object.

`javascript
worker(data)
.env('x', 5)
.env('y', 25)
.exec((value) => value self.env.x self.env.y)
`

$3

Imports code to use at Worker enviroment like functions or scripts.

Accepts any number of named functions or scripts URLs.

`javascript
const moment = 'https://momentjs.com/downloads/moment.min.js'

function howManyTimeAgo(dt) {
return self.moment(dt).fromNow()
}

function ageCalc({ birthDate }) {
return self.howManyTimeAgo(birthDate)
}

worker(data).imports(moment, howManyTimeAgo).exec(ageCalc)
`

It's just a "dumb" example... But it's important to remember about Worker scope!

$3

Import NPM modules from UNPKG CDN to use at Worker environment.

Accepts any number of string arguments to identify modules.

`javascript
function createKeysForAllItems(item) {
item.key = self.randkey.uuid()

return item
}

worker(data).unpkg('randkey').map(createKeysForAllItems)
`

$3

Executes a task function in a single parallel thread.

`javascript
worker(data)
.env('x', 5)
.env('y', 25)
.exec((value) => value self.env.x self.env.y)
`

$3

Executes a multi-thread Array.map method.

`javascript
worker(data)
.env('two', 2)
.map((item) => item.value ** self.env.two)
`

$3

Executes a multi-thread Array.reduce method.

`javascript
worker(data).reduce((value, sum) => value + sum, 0)
`

$3

Executes a single parallel thread Array.filter method.

`javascript
worker(data).filter((value) => value.includes('OK'))
`

$3

Executes a single parallel thread Array.sort method.

`javascript
worker(data).sort((a, b) => a - b)
`

$3

Executes a multi-thread Array.flatMap method.

`javascript
const data = [
[1, 2, 3],
[4, 5, 6],
[7, 8, 9],
// ...
]

worker(data)
.env('two', 2)
.faltMap((item) => item.value ** self.env.two)
`

$3

Promise-like async step.

Unlike the native Promise.then, which returns a Promise, this method returns the worker instance to chain another methods.

`javascript
worker(data)
.filter((value) => value.includes('OK'))
.then(doSomeThing)
`

$3

Promise-like async last step.

Like the native Promise.finally, this method returns a Promise and stops the worker instance flow.

You can't chain other worker methods after this.

`javascript
worker(data)
.filter((value) => value.includes('OK'))
.then(doSomeThing)
.finally(doLastThing)
``

How this module works?

Coming soon...