README
@jsweb/worker
JavaScript module to parallel process data through dynamic multi-thread workers.
Installation
NPM or Yarn
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:
// 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.
CDN
If you prefer, you can get it directly from Unpkg CDN to use it in web frontend.
<script src="https://unpkg.com/@jsweb/worker"></script>
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:
<script type="module">
import worker from 'https://unpkg.com/@jsweb/worker/dist/browser.js'
// Your code goes here...
</script>
Usage example
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.
worker
The Instance
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:
- data or value to process (required)
- a number to setup concurrent threads to process data (optional)
worker(data, 4).exec(...)
The worker tries to detect how much "hardware concurrency threads" are available to use, or use the default: 2
.
Environment (scope)
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
.
.env(key, value)
Sets a Worker environment constant attached to 'self.env' object.
key
must to be a valid object keyvalue
can be any data to be available at Worker environment
Inside your tasks functions, you can refer to these constants through 'self.env' object.
worker(data)
.env('x', 5)
.env('y', 25)
.exec((value) => value * self.env.x * self.env.y)
.imports(...args)
Imports code to use at Worker enviroment like functions or scripts.
Accepts any number of named functions or scripts URLs.
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!
.unpkg(...args)
Import NPM modules from UNPKG CDN to use at Worker environment.
Accepts any number of string arguments to identify modules.
function createKeysForAllItems(item) {
item.key = self.randkey.uuid()
return item
}
worker(data).unpkg('randkey').map(createKeysForAllItems)
.exec(task)
Executes a task function in a single parallel thread.
worker(data)
.env('x', 5)
.env('y', 25)
.exec((value) => value * self.env.x * self.env.y)
.map(task)
Executes a multi-thread Array.map
method.
worker(data)
.env('two', 2)
.map((item) => item.value ** self.env.two)
.reduce(task, arg)
Executes a multi-thread Array.reduce
method.
worker(data).reduce((value, sum) => value + sum, 0)
.filter(task)
Executes a single parallel thread Array.filter
method.
worker(data).filter((value) => value.includes('OK'))
.sort(task)
Executes a single parallel thread Array.sort
method.
worker(data).sort((a, b) => a - b)
.flatMap(task)
Executes a multi-thread Array.flatMap
method.
const data = [
[1, 2, 3],
[4, 5, 6],
[7, 8, 9],
// ...
]
worker(data)
.env('two', 2)
.faltMap((item) => item.value ** self.env.two)
.then(task)
Promise-like async step.
Unlike the native Promise.then
, which returns a Promise
, this method returns the worker
instance to chain another methods.
worker(data)
.filter((value) => value.includes('OK'))
.then(doSomeThing)
.finally(task)
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.
worker(data)
.filter((value) => value.includes('OK'))
.then(doSomeThing)
.finally(doLastThing)
How this module works?
Coming soon...