event-worker

Minimalistic event/promified driven web worker abstraction.

Install

npm

npm install event-worker --save

CDN

https://cdn.jsdelivr.net/npm/event-worker@1.3.0/index.min.js

Usage

Basic example

In your main thread (main.js):

const EventWorker = require('event-worker')
 
const worker = new EventWorker('path/to/my/worker.js')
 
async function test(){
  const user = await worker.emit('getUserById', { id: '30242' })
 
  /*
  {
    id: '30242',
    name: 'neil',
    lastname: 'tyson degrasse'
  }
  */
//...
 

And then in your web worker (worker.js) you can listen for that event and respond back with the requested data:

const EventWorker = require('event-worker')
 
const worker = new EventWorker()
 
worker.on('getUserById', async ({payload}) => {
 
  let user = await getUser(payload.id)
 
  return user // Respond back to the main thread with the data requested.
 
})
 
 
async function getUser(id){
 
  let user = await fetchUserFromLocalDatabase(id)
 
  if(user) return user
 
  user = await fetchUserFromServer(id)
 
  saveUserInLocaDatabase(user)
 
  return user
}

Workload splitting

If you want to keep your main thread running smoothly dividing the work load of expensive computational task between multiple web workers becomes easier.

From main thread (main.js):

const EventWorker = require('event-worker')
 
const workerPath = 'path/to/my/worker.js'
 
const workerPool = [
  new EventWorker(workerPath),
  new EventWorker(workerPath),
  new EventWorker(workerPath)
]
 
const sum = (a, b) => a + b
 
const multiplyBy2InOtherThread = (worker, index) => worker.emit('multiply_by_2', index)
 
(async ()=>
  (await Promise.all(
    workerPool.map(multiplyBy2InOtherThread)
  )).reduce(sum, 0)
)() // 6
 

From worker (worker.js):

 
importScripts('path/to/source/event-worker.js')
 
const worker = new EventWorker()
 
worker.on('multiply_by_2', ({payload}) => payload * 2 )
 

Bidirectional communication

You can listen for events triggered by your workers.

From main thread (main.js):

//...
 
worker.on('interestingData', ({payload})=>{
 
  doSomethingWithInterestingData(payload)
 
  return 'Good job worker!'
 
})
 
//..

From worker (worker.js):

 
//...
const res = await worker.emit('interestingData', 'interestingString')
 
res // => 'Good job worker!!'
 

Inlining code

Instead of having a separate file for your worker, you can wrap your code inside a function and pass it as an argument to the constructor of EventWorker. This is a good option when prototyping.

From main (main.js):

 
const worker = new EventWorker(async (mainThread) => {
 
  let res = await mainThread.emit('sayingHiFromWorker', 'Hi main thread!')
 
  console.log(res) // Hello worker!
 
})
 
worker.on('sayingHiFromWorker', ({payload}) => {
 
  console.log(payload) // Hi main thread!
 
  return "Hello worker!"
 
})

Caveat

When you inline functions it is easy to get confused by the execution context. If you try to access a variable that is outside the scope of the inline function it will fail.

 
const favoriteAnimal = 'chiguire'
 
const worker = new EventWorker(async (mainThread) => {
  // This will get executed in a worker.
  mainThread.on('onGetAnimals', ()=>{
 
    console.log(favoriteAnimal) // fails. favoriteAnimal variable is not in the same execution context.
 
    //...
  })
 
})
 

Error Handling

Error handling works the same as you would expect from a promise executed in the same thread:

From main thread (main.js):

const EventWorker = require('event-worker')
 
const worker = new EventWorker('path/to/my/worker.js')
 
worker.emit('rejectThisCall')
  .catch((reason) => {
    console.log(`Rejected because: "${reason}" `)
  })
 

From worker (worker.js):

 
importScripts('path/to/source/event-worker.js')
 
const worker = new EventWorker()
 
//throwing errors
worker.on('rejectThisCall', () => {
  throw new Error()
})
 
// throwing async errors
worker.on('rejectThisCallAsync', async ()=> {
  throw new Error()
})
 

Instead of embedding event-worker into your worker file with a module bundler, you can use the built in function importScripts:

 
importScripts('path/to/source/event-worker.js')
 
const worker = new EventWorker()
 
// ...

EventWorker reference is injected into the global scope once it's loaded.

API

new EventWorker(source) EventWorker

Creates a new instance

• source string | function | undefined

  • If a string is passed: It will assume it is the worker source file path.

  • If a function is passed it will get converted into a string an then transformed into a worker.

  • If nothing (undefined) is passed it will assume that the environment is the worker.

emit(eventName, data) Promise

Emits a event.

• eventName String

• data Any

on(eventName, callback) EventWorker

Registers for an event.

• eventName

• callback function(object) => Promise<any>

  Gets executed when eventName is emited.

  • object

    • object.payload any

      Data sent from the event emitter to the listener.

terminate() void

Immediately terminates the Worker. This does not offer the worker an opportunity to finish its operations; it is simply stopped at once.

Changelog

2017-11-04

• Removed "resolve" and "reject" function properties in the "on" callback.

Contributing

All contributions are welcome.

License

MIT © Alvaro Bernal